shared

Documentation

Overview

Package shared provides common/shared utility code for all payload format versions.

Index

• Constants
• Variables
• func CertChainToJSON(certChain []*x509.Certificate) ([]byte, error)
• func CertChainToPEM(certChain []*x509.Certificate) ([]string, error)
• func ErrorsToStrings(errs []error) []string
• func HasDuplicateCertsInChain(certChain []*x509.Certificate) bool
• func HasExpiredCerts(certChain []*x509.Certificate) bool
• func HasExpiringCerts(certChain []*x509.Certificate, ageCritical time.Time, ageWarning time.Time) bool
• func HasHostnameMismatch(hostnameValue string, certChain []*x509.Certificate) bool
• func HasMisorderedCerts(certChain []*x509.Certificate) bool
• func HasMissingIntermediateCerts(certChain []*x509.Certificate) bool
• func HasMissingSANsEntries(certChain []*x509.Certificate) bool
• func HasSelfSignedLeaf(certChain []*x509.Certificate) bool
• func HasWeakSignatureAlgorithm(certChain []*x509.Certificate) bool
• func LookupValidityPeriodDescription(cert *x509.Certificate) string
• type CertExpirationMetadata
  • func LookupCertExpMetadata(cert *x509.Certificate, certNumber int, certChain []*x509.Certificate) (CertExpirationMetadata, error)

Constants

const (
	ValidityPeriod1Year   string = "1 year"
	ValidityPeriod90Days  string = "90 days"
	ValidityPeriod45Days  string = "45 days"
	ValidityPeriodUNKNOWN string = "UNKNOWN"
)

Validity period keywords intended as human readable output.

Common historical certificate lifetimes:

• 5 year (1825 days, 60 months)
• 3 year (1185 days, 39 months)
• 2 year (825 days, 27 months)
• 1 year (398 days, 13 months)

See also:

• https://www.sectigo.com/knowledge-base/detail/TLS-SSL-Certificate-Lifespan-History-2-3-and-5-year-validity/kA01N000000zFKp
• https://support.sectigo.com/Com_KnowledgeDetailPage?Id=kA03l000000o6cv
• https://www.digicert.com/faq/public-trust-and-certificates/how-long-are-tls-ssl-certificate-validity-periods
• https://docs.digicert.com/en/whats-new/change-log/older-changes/change-log--2023.html#certcentral--changes-to-multi-year-plan-coverage
• https://knowledge.digicert.com/quovadis/ssl-certificates/ssl-general-topics/maximum-validity-changes-for-tls-ssl-to-drop-to-825-days-in-q1-2018
• https://chromium.googlesource.com/chromium/src/+/666712ff6c7ba7aa5da380bc0a617b637c9232b3/net/docs/certificate_lifetimes.md
• https://www.entrust.com/blog/2017/03/maximum-certificate-lifetime-drops-to-825-days-in-2018

Variables

var (
	// ErrMissingValue indicates that an expected value was missing.
	ErrMissingValue = errors.New("missing expected value")
)

Functions

func CertChainToJSON

func CertChainToJSON(certChain []*x509.Certificate) ([]byte, error)

CertChainToJSON encodes the certificate chain in PEM format and then marshals the PEM-encoded certificates to JSON. An error is returned if an invalid cert chain is provided or if the marshaling process fails.

func CertChainToPEM

func CertChainToPEM(certChain []*x509.Certificate) ([]string, error)

CertChainToPEM encodes the certificate chain in PEM format as a slice of string values. An error is returned if an invalid cert chain is provided.

func ErrorsToStrings

func ErrorsToStrings(errs []error) []string

ErrorsToStrings converts a collection of error interfaces to string values.

func HasDuplicateCertsInChain

func HasDuplicateCertsInChain(certChain []*x509.Certificate) bool

HasDuplicateCertsInChain asserts that there are duplicate certificates within a given certificate chain.

func HasExpiredCerts

func HasExpiredCerts(certChain []*x509.Certificate) bool

HasExpiredCerts asserts that the given certificate chain has one or more expired certificates.

func HasExpiringCerts

func HasExpiringCerts(certChain []*x509.Certificate, ageCritical time.Time, ageWarning time.Time) bool

HasExpiringCerts asserts that the given certificate chain has one or more expiring certificates.

func HasHostnameMismatch

func HasHostnameMismatch(hostnameValue string, certChain []*x509.Certificate) bool

HasHostnameMismatch asserts that the given hostname value is valid for the first certificate in the chain. If an empty hostname value or empty certificate chain is provided a mismatch cannot be determined and false is returned.

func HasMisorderedCerts

func HasMisorderedCerts(certChain []*x509.Certificate) bool

HasMisorderedCerts asserts that a given certificate chain contains certificates out of the expected order.

func HasMissingIntermediateCerts

func HasMissingIntermediateCerts(certChain []*x509.Certificate) bool

HasMissingIntermediateCerts asserts that a given certificate chain is missing intermediate certificates.

func HasMissingSANsEntries

func HasMissingSANsEntries(certChain []*x509.Certificate) bool

HasMissingSANsEntries asserts that the first leaf certificate for a given certificate chain is missing Subject Alternate Names (SANs) entries.

func HasSelfSignedLeaf

func HasSelfSignedLeaf(certChain []*x509.Certificate) bool

HasSelfSignedLeaf asserts that a given certificate chain has a self-signed leaf certificate.

func HasWeakSignatureAlgorithm

func HasWeakSignatureAlgorithm(certChain []*x509.Certificate) bool

HasWeakSignatureAlgorithm indicates that the certificate chain has been signed using a cryptographically weak hashing algorithm (e.g. MD2, MD4, MD5, or SHA1). These signature algorithms are known to be vulnerable to collision attacks. An attacker can exploit this to generate another certificate with the same digital signature, allowing an attacker to masquerade as the affected service.

NOTE: This does not apply to trusted root certificates; TLS clients trust them by their identity instead of the signature of their hash; client code setting this field would need to exclude root certificates from the determination whether the chain is vulnerable to weak signature algorithms.

• https://security.googleblog.com/2014/09/gradually-sunsetting-sha-1.html
• https://security.googleblog.com/2015/12/an-update-on-sha-1-certificates-in.html
• https://superuser.com/questions/1122069/why-are-root-cas-with-sha1-signatures-not-a-risk
• https://developer.mozilla.org/en-US/docs/Web/Security/Weak_Signature_Algorithm
• https://www.tenable.com/plugins/nessus/35291
• https://docs.ostorlab.co/kb/WEAK_HASHING_ALGO/index.html

TODO: Replace with slog debug calls

func LookupValidityPeriodDescription

func LookupValidityPeriodDescription(cert *x509.Certificate) string

LookupValidityPeriodDescription is a helper function to lookup human readable validity period description for a certificate's maximum lifetime value.

Types

type CertExpirationMetadata

type CertExpirationMetadata struct {
	ValidityPeriodDays     int
	DaysRemainingTruncated int
	DaysRemainingPrecise   float64
	CertLifetimePercent    int
}

CertExpirationMetadata is a bundle of certificate expiration related metadata used when preparing a certificate payload for inclusion in plugin output.

func LookupCertExpMetadata

func LookupCertExpMetadata(cert *x509.Certificate, certNumber int, certChain []*x509.Certificate) (CertExpirationMetadata, error)

LookupCertExpMetadata is a helper function used to lookup specific certificate expiration metadata values used when preparing a certificate payload for inclusion in plugin output.