certs

package
v0.17.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 8, 2024 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package certs provides common/shared utility code to support applications in this module which process certificates.

Index

Constants

View Source 
const CertValidityDateLayout string = "2006-01-02 15:04:05 -0700 MST"

CertValidityDateLayout is the chosen date layout for displaying certificate validity date/time values across our application.

View Source 
const ExpirationValidationOneLineSummaryExpiredTmpl string = "%s validation %s: %s cert %q expired %s (on %s)"

ExpirationValidationOneLineSummaryExpiredTmpl is a shared template string used for emitting one-line service check status output for certificate chains with expired certificates.

View Source 
const ExpirationValidationOneLineSummaryExpiresNextTmpl string = "%s validation %s: %s cert %q expires next with %s (until %s)"

ExpirationValidationOneLineSummaryExpiresNextTmpl is a shared template string used for emitting one-line service check status output for certificate chains whose certificates have not expired yet.

View Source 
const X509CertReliesOnCommonName string = "x509: certificate relies on legacy Common Name field, use SANs instead"

X509CertReliesOnCommonName mirrors the unexported error string emitted by the HostnameError.Error() method from the x509 package.

This error string is emitted when a certificate is missing Subject Alternate Names (SANs) AND a specified hostname matches the Common Name field.

Deprecated: See the ErrX509CertReliesOnCommonName value instead.

Variables

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

	// ErrNoCertsFound indicates that no certificates were found when
	// evaluating a certificate chain. This error is not really expected to
	// ever occur.
	ErrNoCertsFound = errors.New("no certificates found")

	// ErrExpiredCertsFound indicates that one or more certificates were found
	// to be expired when evaluating a certificate chain.
	ErrExpiredCertsFound = errors.New("expired certificates found")

	// ErrExpiringCertsFound indicates that one or more certificates were
	// found to be expiring soon when evaluating a certificate chain.
	ErrExpiringCertsFound = errors.New("expiring certificates found")

	// ErrHostnameVerificationFailed indicates a mismatch between a
	// certificate and a given hostname.
	ErrHostnameVerificationFailed = errors.New("hostname verification failed")

	// ErrCertMissingSANsEntries indicates that a certificate is missing one or
	// more Subject Alternate Names specified by the user.
	ErrCertMissingSANsEntries = errors.New("certificate is missing requested SANs entries")

	// ErrCertHasUnexpectedSANsEntries indicates that a certificate has one or
	// more Subject Alternate Names not specified by the user.
	ErrCertHasUnexpectedSANsEntries = errors.New("certificate has unexpected SANs entries")

	// ErrCertHasMissingAndUnexpectedSANsEntries indicates that a certificate is
	// missing one or more Subject Alternate Names specified by the user and also
	// contains one more more Subject Alternate Names not specified by the user.
	ErrCertHasMissingAndUnexpectedSANsEntries = errors.New("certificate is missing requested SANs entries, has unexpected SANs entries")

	// ErrX509CertReliesOnCommonName mirrors the unexported error string
	// emitted by the HostnameError.Error() method from the x509 package.
	//
	// https://cs.opensource.google/go/go/+/refs/tags/go1.20.1:src/crypto/x509/verify.go;l=104
	//
	// This error string is emitted when a certificate is missing Subject
	// Alternate Names (SANs) AND a specified hostname matches the Common Name
	// field.
	//
	// TODO: Open RFE in Go project asking that this be made an exportable
	// error value so that we can drop this hard-coded version (which is bound
	// to become a problem at some point).
	// https://github.com/atc0005/check-cert/issues/520
	//
	ErrX509CertReliesOnCommonName = errors.New("x509: certificate relies on legacy Common Name field, use SANs instead")

	// ErrNoCertValidationResults indicates that the cert chain validation
	// results collection is empty. This is an unusual condition as
	// configuration validation requires that at least one validation check is
	// performed.
	ErrNoCertValidationResults = errors.New("certificate validation results collection is empty")
)

Functions

func ChainPosition 

func ChainPosition(cert *x509.Certificate, certChain []*x509.Certificate) string

ChainPosition receives a cert and the cert chain that it belongs to and returns a string indicating what position or "role" it occupies in the certificate chain.

https://en.wikipedia.org/wiki/X.509 https://tools.ietf.org/html/rfc5280

func ExpirationStatus 

func ExpirationStatus(cert *x509.Certificate, ageCritical time.Time, ageWarning time.Time, ignoreExpired bool) string

ExpirationStatus receives a certificate and the expiration threshold values for CRITICAL and WARNING states and returns a human-readable string indicating the overall status at a glance. If requested, an expired certificate is marked as ignored.

func ExpiresInDays added in v0.10.0 

func ExpiresInDays(cert *x509.Certificate) (int, error)

ExpiresInDays evaluates the given certificate and returns the number of days until the certificate expires. If already expired, a negative number is returned indicating how many days the certificate is past expiration.

An error is returned if the pointer to the given certificate is nil.

func FormatCertSerialNumber 

func FormatCertSerialNumber(sn *big.Int) string

FormatCertSerialNumber receives a certificate serial number in its native type and formats it in the text format used by OpenSSL (and many other tools).

Example: DE:FD:50:2B:C5:7F:79:F4

func FormattedExpiration 

func FormattedExpiration(expireTime time.Time) string

FormattedExpiration receives a Time value and converts it to a string representing the largest useful whole units of time in days and hours. For example, if a certificate has 1 year, 2 days and 3 hours remaining until expiration, this function will return the string '367d 3h remaining', but if only 3 hours remain then '3h remaining' will be returned. If a certificate has expired, the 'ago' suffix will be used instead. For example, if a certificate has expired 3 hours ago, '3h ago' will be returned.

func GenerateCertChainReport added in v0.8.0 

func GenerateCertChainReport(
	certChain []*x509.Certificate,
	ageCriticalThreshold time.Time,
	ageWarningThreshold time.Time,
	verboseDetails bool,
	validationOptions CertChainValidationOptions,
) string

GenerateCertChainReport receives the current certificate chain status generates a formatted report suitable for display on the console or (potentially) via Microsoft Teams provided suitable conversion is performed on the output. If specified, additional details are provided such as certificate fingerprint and key IDs.

func GetCertsFromFile 

func GetCertsFromFile(filename string) ([]*x509.Certificate, []byte, error)

GetCertsFromFile is a helper function for retrieving a certificate chain from a specified PEM formatted certificate file. An error is returned if the file cannot be decoded and parsed (e.g., empty file, not PEM formatted). Any leading non-PEM formatted data is skipped while any trailing non-PEM formatted data is returned for potential further evaluation.

func HasExpiredCert 

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

HasExpiredCert receives a slice of x509 certificates and indicates whether any of the certificates in the chain have expired.

func HasExpiringCert 

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

HasExpiringCert receives a slice of x509 certificates, CRITICAL age threshold and WARNING age threshold values and ignoring any certificates already expired, uses the provided thresholds to determine if any certificates are about to expire. A boolean value is returned to indicate the results of this check.

func IntermediateCerts added in v0.10.0 

func IntermediateCerts(certChain []*x509.Certificate) []*x509.Certificate

IntermediateCerts receives a slice of x509 certificates and returns a (potentially empty) collection of intermediate certificates present in the chain.

func IsExpiredCert 

func IsExpiredCert(cert *x509.Certificate) bool

IsExpiredCert receives a x509 certificate and returns a boolean value indicating whether the cert has expired.

func IsExpiringCert 

func IsExpiringCert(cert *x509.Certificate, ageCritical time.Time, ageWarning time.Time) bool

IsExpiringCert receives a x509 certificate, CRITICAL age threshold and WARNING age threshold values and uses the provided thresholds to determine if the certificate is about to expire. A boolean value is returned to indicate the results of this check. An expired certificate fails this check.

func IsIntermediateCert added in v0.12.0 

func IsIntermediateCert(cert *x509.Certificate, certChain []*x509.Certificate) bool

IsIntermediateCert indicates whether a given certificate from a certificate chain is an intermediate certificate.

func IsLeafCert added in v0.12.0 

func IsLeafCert(cert *x509.Certificate, certChain []*x509.Certificate) bool

IsLeafCert indicates whether a given certificate from a certificate chain is a leaf or server certificate.

func IsRootCert added in v0.12.0 

func IsRootCert(cert *x509.Certificate, certChain []*x509.Certificate) bool

IsRootCert indicates whether a given certificate from a certificate chain is a root certificate.

func LeafCerts added in v0.10.0 

func LeafCerts(certChain []*x509.Certificate) []*x509.Certificate

LeafCerts receives a slice of x509 certificates and returns a (potentially empty) collection of leaf certificates present in the chain.

func LifeRemainingPercentage added in v0.17.0 

func LifeRemainingPercentage(cert *x509.Certificate) (float64, error)

LifeRemainingPercentage returns the percentage of remaining time before a certificate expires.

func LifeRemainingPercentageTruncated added in v0.17.0 

func LifeRemainingPercentageTruncated(cert *x509.Certificate) (int, error)

LifeRemainingPercentageTruncated returns the truncated percentage of remaining time before a certificate expires.

func MaxLifespan added in v0.17.0 

func MaxLifespan(cert *x509.Certificate) (time.Duration, error)

MaxLifespan returns the maximum lifespan for a given certificate from the date it was issued until the time it is scheduled to expire.

func MaxLifespanInDays added in v0.17.0 

func MaxLifespanInDays(cert *x509.Certificate) (int, error)

MaxLifespanInDays returns the maximum lifespan in days for a given certificate from the date it was issued until the time it is scheduled to expire.

func NextToExpire 

func NextToExpire(certChain []*x509.Certificate, excludeExpired bool) *x509.Certificate

NextToExpire receives a slice of x509 certificates and a boolean flag indicating whether already expired certificates should be excluded. If not excluded, the first expired certificate is returned, otherwise the first certificate out of the pool set to expire next is returned.

If *all* certs are expired, the cert which first expired will be returned regardless of the boolean flag provided. If the provided slice of x509 certificates is empty or nil then nil will be returned.

func NumExpiredCerts 

func NumExpiredCerts(certChain []*x509.Certificate) int

NumExpiredCerts receives a slice of x509 certificates and returns a count of how many certificates have expired.

func NumExpiringCerts 

func NumExpiringCerts(certChain []*x509.Certificate, ageCritical time.Time, ageWarning time.Time) int

NumExpiringCerts receives a slice of x509 certificates, CRITICAL age threshold and WARNING age threshold values and ignoring any certificates already expired, uses the provided thresholds to determine if any certificates are about to expire. A count of expiring certificates is returned.

func NumIntermediateCerts added in v0.10.0 

func NumIntermediateCerts(certChain []*x509.Certificate) int

NumIntermediateCerts receives a slice of x509 certificates and returns a count of intermediate certificates present in the chain.

func NumLeafCerts added in v0.10.0 

func NumLeafCerts(certChain []*x509.Certificate) int

NumLeafCerts receives a slice of x509 certificates and returns a count of leaf certificates present in the chain.

func NumRootCerts added in v0.10.0 

func NumRootCerts(certChain []*x509.Certificate) int

NumRootCerts receives a slice of x509 certificates and returns a count of root certificates present in the chain.

func NumUnknownCerts added in v0.10.0 

func NumUnknownCerts(certChain []*x509.Certificate) int

NumUnknownCerts receives a slice of x509 certificates and returns a count of unidentified certificates present in the chain.

func OldestIntermediateCert added in v0.10.0 

func OldestIntermediateCert(certChain []*x509.Certificate) *x509.Certificate

OldestIntermediateCert returns the oldest intermediate certificate in a given certificate chain. If a leaf certificate is not not present nil is returned.

func OldestLeafCert added in v0.10.0 

func OldestLeafCert(certChain []*x509.Certificate) *x509.Certificate

OldestLeafCert returns the oldest leaf certificate in a given certificate chain. If a leaf certificate is not not present nil is returned.

func OldestRootCert added in v0.10.0 

func OldestRootCert(certChain []*x509.Certificate) *x509.Certificate

OldestRootCert returns the oldest root certificate in a given certificate chain. If a root certificate is not not present nil is returned.

func RootCerts added in v0.10.0 

func RootCerts(certChain []*x509.Certificate) []*x509.Certificate

RootCerts receives a slice of x509 certificates and returns a (potentially empty) collection of root certificates present in the chain.

func ServiceState added in v0.4.3 

func ServiceState(val ServiceStater) nagios.ServiceState

ServiceState accepts a type capable of evaluating its status and uses those results to map to a compatible ServiceState value.

func ShouldCertExpirationBeIgnored added in v0.12.0 

func ShouldCertExpirationBeIgnored(
	cert *x509.Certificate,
	certChain []*x509.Certificate,
	validationOptions CertChainValidationOptions,
) bool

ShouldCertExpirationBeIgnored evaluates a given certificate, its certificate chain and the validation options specified and indicates whether the certificate should be ignored.

Types

type CertChainValidationOptions added in v0.12.0 

type CertChainValidationOptions struct {

	// IgnoreHostnameVerificationFailureIfEmptySANsList tracks whether a
	// request was made to ignore validation check results for the hostname
	// when the leaf certificate's Subject Alternate Names (SANs) list is
	// found to be empty.
	IgnoreHostnameVerificationFailureIfEmptySANsList bool

	// IgnoreValidationResultExpiration tracks whether a request was made to
	// ignore validation check results for certificate expiration. This is a
	// broad/blanket request that ignores expiration validation issues for ALL
	// certificates in a chain, not just the leaf/server certificate.
	IgnoreValidationResultExpiration bool

	// IgnoreValidationResultHostname tracks whether a request was made to
	// ignore validation check results from verifying a given hostname against
	// the leaf certificate in a certificate chain.
	IgnoreValidationResultHostname bool

	// IgnoreValidationResultSANs tracks whether a request was made to ignore
	// validation check results result from performing a Subject Alternate
	// Names (SANs) validation against a leaf certificate in a chain.
	IgnoreValidationResultSANs bool

	// IgnoreExpiredIntermediateCertificates tracks whether a request was made
	// to ignore validation check results for certificate expiration against
	// intermediate certificates in a certificate chain.
	IgnoreExpiredIntermediateCertificates bool

	// IgnoreExpiredRootCertificates tracks whether a request was made to
	// ignore validation check results for certificate expiration against root
	// certificates in a certificate chain.
	IgnoreExpiredRootCertificates bool
}

CertChainValidationOptions is a collection of validation options shared by all validation functions for types implementing the CertChainValidationResult interface.

Not all options are used by each validation function.

type CertChainValidationResult added in v0.8.0 

type CertChainValidationResult interface {

	// Err exposes the underlying error (if any) as-is. See the Status(),
	// Overview() and String() methods if additional context is desired for
	// display purposes.
	Err() error

	// CheckName emits the human-readable name of the validation check that
	// was performed.
	CheckName() string

	// Status is intended as a brief status of the validation result. This can
	// be used as initial lead-in text.
	//
	// Example:
	//
	// CRITICAL: Mismatched SANs entries for leaf certificate
	Status() string

	// Overview is a high-level overview of the validation result. This can be
	// used as lead-out text for a one-line summary/overview, or sandwiched
	// between lead-in text and a more detailed status report.
	//
	// Example:
	//
	// [EXPIRED: 0, EXPIRING: 1, OK: 2]
	Overview() string

	// StatusDetail is provides additional details intended to extend the
	// shorter status text with information suitable as explanation for the
	// overall state of the validation results. This text may span multiple
	// lines.
	//
	// Example:
	//
	// missing: [konrad-test.amazon.com, mp3recs.amazon.com, test-www.amazon.com, www.cdn.amazon.com, www.m.amazon.com, yellowpages.amazon.com], unexpected: [origin-www.amazon.com, buckeye-retail-website.amazon.com, huddles.amazon.com]
	StatusDetail() string

	// String provides the validation result in human-readable format.
	//
	// Most implementations will combine the contents of Status() and
	// Overview(), some implementations may also combine StatusDetail() if the
	// content is sufficiently brief.
	String() string

	// ServiceState maps the validation result to a compatible ServiceState
	// value.
	ServiceState() nagios.ServiceState

	// Report provides a summary of the validation results intended for use in
	// a final report for the user/sysadmin.
	//
	// Most implementations will likely combine String() and StatusDetail()
	// along with additional verbose details to provide this output.
	Report() string

	// IsWarningState indicates whether the results for a validation check
	// were found to be in a WARNING state. This is usually from crossing an
	// explicit or default WARNING threshold value. This returns false if the
	// validation check result is flagged as ignored.
	IsWarningState() bool

	// IsCriticalState indicates whether the results for a validation check
	// were found to be in a CRITICAL state. This is usually from crossing an
	// explicit or default CRITICAL threshold value. This returns false if the
	// validation check result is flagged as ignored.
	IsCriticalState() bool

	// IsUnknownState indicates whether the results for a validation check
	// were found to be in a UNKNOWN state. This returns false if the
	// validation check result is flagged as ignored.
	IsUnknownState() bool

	// IsOKState indicates whether the results for a validation check were
	// found to be in a passing state. For the purposes of validation check
	// evaluation, ignored validation check results are considered to be a
	// subset of OK status.
	//
	// See the IsIgnored() method for determining whether a validation check is
	// in that specific state, see the IsSuccessState() method for determining
	// whether a validation check was executed, evaluated and found to be
	// successful.
	IsOKState() bool

	// IsSucceeded indicates that the results for a validation check were
	// found to be in a non-problematic, non-ignored state; an ignored
	// validation check is considered to be OK, but not in a successful state.
	IsSucceeded() bool

	// IsIgnored indicates whether a specific validation check was performed,
	// but the results "ignored" when determining overall plugin state.
	IsIgnored() bool

	// IsFailed indicates whether a specific validation check resulted in a
	// non-successful state and is not flagged as ignored.
	IsFailed() bool

	// TotalCerts returns the number of certificates in the evaluated chain.
	TotalCerts() int

	// Priority indicates the level of importance for a specific validation
	// result.
	//
	// This value is calculated by applying a priority modifier for specific
	// failure conditions (recorded when the validation check result is
	// initially obtained) to a baseline value specific to the validation
	// check performed.
	//
	// If the validation check result is flagged as ignored the priority
	// modifier is also ignored.
	Priority() int

	// CertChain returns the associated certificate chain which was evaluated.
	CertChain() []*x509.Certificate
}

CertChainValidationResult represents the result for a validation check associated with a certificate chain. The result can indicate success, failure or if validation was ignored.

type CertChainValidationResults added in v0.8.0 

type CertChainValidationResults []CertChainValidationResult

CertChainValidationResults is a collection of validation results. This grouping allows for common/bulk operations such as determining overall state of the operations (e.g., via method calls such as IsWarningState(), IsCriticalState()).

func (*CertChainValidationResults) Add added in v0.8.0 

func (ccvr *CertChainValidationResults) Add(result CertChainValidationResult)

Add appends a validation result to the set for later evaluation.

func (CertChainValidationResults) CheckNames added in v0.8.0 

func (ccvr CertChainValidationResults) CheckNames() []string

CheckNames returns a (potentially empty) slice of validation result names.

func (CertChainValidationResults) Err added in v0.8.0 

func (ccvr CertChainValidationResults) Err() error

Err returns an error state evaluation of the validation results in the collection. This is a summary only and does not provide specifics regarding which validation errors occurred.

func (CertChainValidationResults) Errs added in v0.8.0 

func (ccvr CertChainValidationResults) Errs(includeIgnored bool) []error

Errs returns a slice of errors recorded for validation results in the collection that have *not* been flagged as ignored. A nil is returned if no errors are recorded for the collection. If specified, all errors recorded are returned, not just those which have not been flagged as ignored.

func (CertChainValidationResults) HasCriticalState added in v0.8.0 

func (ccvr CertChainValidationResults) HasCriticalState() bool

HasCriticalState indicates whether any validation results in the collection have a CRITICAL state.

func (CertChainValidationResults) HasFailed added in v0.8.0 

func (ccvr CertChainValidationResults) HasFailed() bool

HasFailed indicates whether any validation results in the collection have a failed state.

func (CertChainValidationResults) HasIgnored added in v0.8.0 

func (ccvr CertChainValidationResults) HasIgnored() bool

HasIgnored indicates whether any validation results in the collection have a ignored state.

func (CertChainValidationResults) HasSucceeded added in v0.8.0 

func (ccvr CertChainValidationResults) HasSucceeded() bool

HasSucceeded indicates whether any validation results in the collection have a succeeded state.

func (CertChainValidationResults) HasUnknownState added in v0.8.0 

func (ccvr CertChainValidationResults) HasUnknownState() bool

HasUnknownState indicates whether any validation results in the collection have a UNKNOWN state.

func (CertChainValidationResults) HasWarningState added in v0.8.0 

func (ccvr CertChainValidationResults) HasWarningState() bool

HasWarningState indicates whether any validation results in the collection have a WARNING state.

func (CertChainValidationResults) IgnoredCheckNames added in v0.8.0 

func (ccvr CertChainValidationResults) IgnoredCheckNames() []string

IgnoredCheckNames returns a (potentially empty) slice of names for ignored validation checks.

func (CertChainValidationResults) IsCriticalState added in v0.8.0 

func (ccvr CertChainValidationResults) IsCriticalState() bool

IsCriticalState is an alias for HasCriticalState.

func (CertChainValidationResults) IsOKState added in v0.8.0 

func (ccvr CertChainValidationResults) IsOKState() bool

IsOKState indicates whether all validation results in the collection have an OK state.

func (CertChainValidationResults) IsUnknownState added in v0.8.0 

func (ccvr CertChainValidationResults) IsUnknownState() bool

IsUnknownState is an alias for HasUnknownState.

func (CertChainValidationResults) IsWarningState added in v0.8.0 

func (ccvr CertChainValidationResults) IsWarningState() bool

IsWarningState is an alias for HasWarningState.

func (CertChainValidationResults) NotOKCheckNames added in v0.8.0 

func (ccvr CertChainValidationResults) NotOKCheckNames() []string

NotOKCheckNames returns a (potentially empty) slice of names for unsuccessful validation checks.

func (CertChainValidationResults) NotOKResults added in v0.8.0 

func (ccvr CertChainValidationResults) NotOKResults() CertChainValidationResults

NotOKResults returns a (potentially empty) subset of this collection containing only the non-OK validation check results. Ignored validation check results are considered a subset of OK results and are not included here.

func (CertChainValidationResults) NumCriticalState added in v0.8.0 

func (ccvr CertChainValidationResults) NumCriticalState() int

NumCriticalState indicates how many validation results in the collection have a CRITICAL state.

func (CertChainValidationResults) NumFailed added in v0.8.0 

func (ccvr CertChainValidationResults) NumFailed() int

NumFailed indicates how many validation results in the collection have a failed state.

func (CertChainValidationResults) NumIgnored added in v0.8.0 

func (ccvr CertChainValidationResults) NumIgnored() int

NumIgnored indicates how many validation results in the collection have a ignored status.

func (CertChainValidationResults) NumOKState added in v0.8.0 

func (ccvr CertChainValidationResults) NumOKState() int

NumOKState indicates how many validation results in the collection have an OK state.

func (CertChainValidationResults) NumSucceeded added in v0.8.0 

func (ccvr CertChainValidationResults) NumSucceeded() int

NumSucceeded indicates how many validation results in the collection have a succeeded state.

func (CertChainValidationResults) NumUnknownState added in v0.8.0 

func (ccvr CertChainValidationResults) NumUnknownState() int

NumUnknownState indicates how many validation results in the collection have an UNKNOWN state.

func (CertChainValidationResults) NumWarningState added in v0.8.0 

func (ccvr CertChainValidationResults) NumWarningState() int

NumWarningState indicates how many validation results in the collection have a WARNING state.

func (CertChainValidationResults) OKCheckNames added in v0.8.0 

func (ccvr CertChainValidationResults) OKCheckNames() []string

OKCheckNames returns a (potentially empty) slice of names for passing validation checks. Ignored validation checks are included.

func (CertChainValidationResults) OneLineSummary added in v0.8.0 

func (ccvr CertChainValidationResults) OneLineSummary() string

OneLineSummary returns a one-line summary of the certificate chain validation results suitable for display and notification purposes. Not all validation results may be mentioned directly in the one-line summary text.

func (CertChainValidationResults) Overview added in v0.8.0 

func (ccvr CertChainValidationResults) Overview() string

Overview is a high-level overview of the validation results collection. This can be used as lead-out text for a one-line summary/overview, or sandwiched between lead-in text and a more detailed status report.

func (CertChainValidationResults) Report added in v0.8.0 

func (ccvr CertChainValidationResults) Report() string

Report returns a formatted report suitable for display and notification purposes. The caller is responsible for calling the Sort method first in order to arrange the validation results by appropriate priority.

func (CertChainValidationResults) ServiceState added in v0.8.0 

func (ccvr CertChainValidationResults) ServiceState() nagios.ServiceState

ServiceState returns the appropriate Service Check Status label and exit code for the collection's validation results.

func (CertChainValidationResults) Sort added in v0.8.0 

func (ccvr CertChainValidationResults) Sort()

Sort orders the collection of validation results based on the priority value of each validation result. Validation results of equal value retain their order.

func (CertChainValidationResults) Status added in v0.8.0 

func (ccvr CertChainValidationResults) Status() string

Status is intended as a brief status of the validation results collection. This can be used as initial lead-in text.

func (CertChainValidationResults) SucceededResults added in v0.8.0 

func (ccvr CertChainValidationResults) SucceededResults() CertChainValidationResults

SucceededResults returns a (potentially empty) subset of this collection containing only the successful validation check results. Ignored validation check results are not included here.

func (CertChainValidationResults) SuccessCheckNames added in v0.8.0 

func (ccvr CertChainValidationResults) SuccessCheckNames() []string

SuccessCheckNames returns a (potentially empty) slice of names for successful validation checks. Ignored validation checks are NOT included.

func (CertChainValidationResults) Total added in v0.8.0 

func (ccvr CertChainValidationResults) Total() int

Total indicates how many validation results are in the collection.

type DiscoveredCertChain 

type DiscoveredCertChain struct {
	// Name is the hostname or FQDN of a system where a certificate chain was
	// retrieved. Depending on how scan targets were specified, this value may
	// not be populated.
	Name string

	// IPAddress is the IP Address where a certificate chain was discovered.
	// This value should always be populated.
	IPAddress string

	// Port is the TCP port where a certificate chain was retrieved.
	Port int

	// Certs is the certificate chain associated with a host.
	Certs []*x509.Certificate
}

DiscoveredCertChain represents the certificate chain found on a specific host along with that host's IP/Name and port.

type DiscoveredCertChains 

type DiscoveredCertChains []DiscoveredCertChain

DiscoveredCertChains is a collection of discovered certificate chains for specified hosts and ports.

func (DiscoveredCertChains) HasProblems 

func (dcc DiscoveredCertChains) HasProblems(
	certsExpireAgeCritical time.Time,
	certsExpireAgeWarning time.Time) bool

HasProblems asserts that no evaluated certificates are expired or expiring soon.

func (DiscoveredCertChains) NumProblems 

func (dcc DiscoveredCertChains) NumProblems(
	certsExpireAgeCritical time.Time,
	certsExpireAgeWarning time.Time) int

NumProblems indicates how many evaluated certificates are expired or expiring soon.

TODO: Need to either rename or expand the scope to also include hostname verification errors, chain validity, etc.

type ExpirationValidationResult added in v0.8.0 

type ExpirationValidationResult struct {
	// contains filtered or unexported fields
}

ExpirationValidationResult is the validation result from performing expiration validation against each certificate in a chain.

func ValidateExpiration added in v0.8.0 

func ValidateExpiration(
	certChain []*x509.Certificate,
	expireDaysCritical int,
	expireDaysWarning int,
	verboseOutput bool,
	validationOptions CertChainValidationOptions,
) ExpirationValidationResult

ValidateExpiration evaluates a given certificate chain using provided CRITICAL and WARNING thresholds (specified in number of days from this moment) for previously expired or "expiring soon" certificates. If specified, a flag is set to generate verbose validation output.

If requested, expired intermediate or root certificates are ignored.

NOTE: This validation type does not object to incorrect certificate entries (e.g., duplicate leaf certs) or incorrect chain order (e.g., intermediates before leaf cert).

func (ExpirationValidationResult) CertChain added in v0.8.0 

func (evr ExpirationValidationResult) CertChain() []*x509.Certificate

CertChain returns the evaluated certificate chain.

func (ExpirationValidationResult) CheckName added in v0.8.0 

func (evr ExpirationValidationResult) CheckName() string

CheckName emits the human-readable name of this validation check result.

func (ExpirationValidationResult) CriticalDateThreshold added in v0.8.0 

func (evr ExpirationValidationResult) CriticalDateThreshold() string

CriticalDateThreshold returns a formatted version of the CRITICAL date threshold used when calculating this validation check result.

func (ExpirationValidationResult) Err added in v0.8.0 

func (evr ExpirationValidationResult) Err() error

Err returns the underlying error (if any) regardless of whether this validation check result is flagged as ignored.

func (ExpirationValidationResult) FilteredCertificateChain added in v0.12.0 

func (evr ExpirationValidationResult) FilteredCertificateChain() []*x509.Certificate

FilteredCertificateChain returns the original certificate chain minus any certificates that the sysadmin has opted to ignore. The first leaf certificate encountered that is expired or expiring is returned by itself in order to give it the highest precedence.

If the sysadmin did not opt to ignore any certificates then the returned certificate chain is unchanged from the original.

func (ExpirationValidationResult) HasExpiredCerts added in v0.8.0 

func (evr ExpirationValidationResult) HasExpiredCerts() bool

HasExpiredCerts indicates whether any certificates in the chain have expired.

func (ExpirationValidationResult) HasExpiringCerts added in v0.8.0 

func (evr ExpirationValidationResult) HasExpiringCerts() bool

HasExpiringCerts indicates whether any certificates in the chain are expiring soon. Any already expired certificates are ignored.

func (ExpirationValidationResult) IsCriticalState added in v0.8.0 

func (evr ExpirationValidationResult) IsCriticalState() bool

IsCriticalState indicates whether this validation check result is in a CRITICAL state. This returns false if the validation check resulted in an OK or WARNING state, or is flagged as ignored. True is returned otherwise.

func (ExpirationValidationResult) IsFailed added in v0.8.0 

func (evr ExpirationValidationResult) IsFailed() bool

IsFailed indicates whether this validation check result is not flagged as ignored and problems were identified.

func (ExpirationValidationResult) IsIgnored added in v0.8.0 

func (evr ExpirationValidationResult) IsIgnored() bool

IsIgnored indicates whether this validation check result was flagged as ignored for the purposes of determining final validation state.

func (ExpirationValidationResult) IsOKState added in v0.8.0 

func (evr ExpirationValidationResult) IsOKState() bool

IsOKState indicates whether this validation check result is in an OK or passing state. For the purposes of validation check evaluation, ignored validation checks are considered to be a subset of OK status.

func (ExpirationValidationResult) IsSucceeded added in v0.8.0 

func (evr ExpirationValidationResult) IsSucceeded() bool

IsSucceeded indicates whether this validation check result is not flagged as ignored and no problems with the certificate chain were identified.

func (ExpirationValidationResult) IsUnknownState added in v0.8.0 

func (evr ExpirationValidationResult) IsUnknownState() bool

IsUnknownState indicates whether this validation check result is in an UNKNOWN state.

func (ExpirationValidationResult) IsWarningState added in v0.8.0 

func (evr ExpirationValidationResult) IsWarningState() bool

IsWarningState indicates whether this validation check result is in a WARNING state. This returns false if the validation check resulted in an OK or CRITICAL state, or is flagged as ignored. True is returned otherwise.

func (ExpirationValidationResult) NumExpiredCerts added in v0.8.0 

func (evr ExpirationValidationResult) NumExpiredCerts() int

NumExpiredCerts indicates how many certificates in the chain have expired.

func (ExpirationValidationResult) NumExpiringCerts added in v0.8.0 

func (evr ExpirationValidationResult) NumExpiringCerts() int

NumExpiringCerts indicates the number of certificates in the chain that are expiring soon. Any already expired certificates are ignored.

func (ExpirationValidationResult) NumValidCerts added in v0.8.0 

func (evr ExpirationValidationResult) NumValidCerts() int

NumValidCerts indicates the number of certificates in the chain that are not expired and not expiring soon.

func (ExpirationValidationResult) Overview added in v0.8.0 

func (evr ExpirationValidationResult) Overview() string

Overview provides a high-level summary of this validation check result.

func (ExpirationValidationResult) Priority added in v0.8.0 

func (evr ExpirationValidationResult) Priority() int

Priority indicates the level of importance for this validation check result.

This value is calculated by applying a priority modifier for specific failure conditions (recorded when the validation check result is initially obtained) to a baseline value specific to the validation check performed.

If the validation check result is flagged as ignored the priority modifier is also ignored.

func (ExpirationValidationResult) Report added in v0.8.0 

func (evr ExpirationValidationResult) Report() string

Report provides the validation check result in verbose human-readable format.

func (ExpirationValidationResult) ServiceState added in v0.8.0 

func (evr ExpirationValidationResult) ServiceState() nagios.ServiceState

ServiceState returns the appropriate Service Check Status label and exit code for this validation check result.

func (ExpirationValidationResult) Status added in v0.8.0 

func (evr ExpirationValidationResult) Status() string

Status is intended as a brief status of the validation check result. This can be used as initial lead-in text.

func (ExpirationValidationResult) StatusDetail added in v0.8.0 

func (evr ExpirationValidationResult) StatusDetail() string

StatusDetail provides additional details intended to extend the shorter status text with information suitable as explanation for the overall state of the validation check result. This text may span multiple lines.

func (ExpirationValidationResult) String added in v0.8.0 

func (evr ExpirationValidationResult) String() string

String provides the validation check result in human-readable format. Because the certificates chain report is so detailed we skip emitting those details.

func (ExpirationValidationResult) TotalCerts added in v0.8.0 

func (evr ExpirationValidationResult) TotalCerts() int

TotalCerts returns the number of certificates in the evaluated certificate chain.

func (ExpirationValidationResult) ValidationStatus added in v0.12.0 

func (evr ExpirationValidationResult) ValidationStatus(certChain []*x509.Certificate) string

ValidationStatus provides a one word status value for a given certificate chain based on previous expiration validation check results of the original certificate chain.

The intent is to allow providing a validation status value based on a subset of the original chain. If the given chain is empty, nil or a copy of the original certificate chain then the status value will reflect the original certificate chain.

func (ExpirationValidationResult) WarningDateThreshold added in v0.8.0 

func (evr ExpirationValidationResult) WarningDateThreshold() string

WarningDateThreshold returns a formatted version of the WARNING date threshold used when calculating this validation check result.

type HostnameValidationResult added in v0.8.0 

type HostnameValidationResult struct {
	// contains filtered or unexported fields
}

HostnameValidationResult is the validation result from verifying a given hostname against the leaf certificate in a certificate chain.

NOTE: If specified by the user, hostname verification is ignored if no SANs entries are present for the leaf certificate.

func ValidateHostname added in v0.8.0 

func ValidateHostname(
	certChain []*x509.Certificate,
	server string,
	dnsName string,
	ignoreIfSANsEmptyFlagName string,
	validationOptions CertChainValidationOptions,
) HostnameValidationResult

ValidateHostname asserts that a given server or DNS Name successfully matches the leaf certificate for a certificate chain. If the DNS Name value is specified it is used when verifying the hostname, otherwise an attempt is made to use the given server value.

Validation check results are ignored when the SANs list is found to be empty if the caller requests this. This option may be needed where the sysadmin wishes to perform expiration validation for certificates missing SANs entries (and does not wish to fail the overall plugin status due to the certificate lacking SANs entries).

Validation check results are *also* ignored if explicitly requested.

func (HostnameValidationResult) CertChain added in v0.8.0 

func (hnvr HostnameValidationResult) CertChain() []*x509.Certificate

CertChain returns the evaluated certificate chain.

func (HostnameValidationResult) CheckName added in v0.8.0 

func (hnvr HostnameValidationResult) CheckName() string

CheckName emits the human-readable name of this validation check result.

func (HostnameValidationResult) Err added in v0.8.0 

func (hnvr HostnameValidationResult) Err() error

Err returns the underlying error (if any) regardless of whether this validation check result is flagged as ignored.

func (HostnameValidationResult) IsCriticalState added in v0.8.0 

func (hnvr HostnameValidationResult) IsCriticalState() bool

IsCriticalState indicates whether this validation check result is in a CRITICAL state. This returns false if the validation check resulted in an OK or WARNING state, or is flagged as ignored. True is returned otherwise.

func (HostnameValidationResult) IsFailed added in v0.8.0 

func (hnvr HostnameValidationResult) IsFailed() bool

IsFailed indicates whether this validation check result is not flagged as ignored and problems were identified.

func (HostnameValidationResult) IsIgnored added in v0.8.0 

func (hnvr HostnameValidationResult) IsIgnored() bool

IsIgnored indicates whether this validation check result was flagged as ignored for the purposes of determining final validation state.

func (HostnameValidationResult) IsOKState added in v0.8.0 

func (hnvr HostnameValidationResult) IsOKState() bool

IsOKState indicates whether this validation check result is in an OK or passing state. For the purposes of validation check evaluation, ignored validation checks are considered to be a subset of OK status.

func (HostnameValidationResult) IsSucceeded added in v0.8.0 

func (hnvr HostnameValidationResult) IsSucceeded() bool

IsSucceeded indicates whether this validation check result is not flagged as ignored and no problems with the certificate chain were identified.

func (HostnameValidationResult) IsUnknownState added in v0.8.0 

func (hnvr HostnameValidationResult) IsUnknownState() bool

IsUnknownState indicates whether this validation check result is in an UNKNOWN state.

func (HostnameValidationResult) IsWarningState added in v0.8.0 

func (hnvr HostnameValidationResult) IsWarningState() bool

IsWarningState indicates whether this validation check result is in a WARNING state. This returns false if the validation check resulted in an OK or CRITICAL state, or is flagged as ignored. True is returned otherwise.

func (HostnameValidationResult) Overview added in v0.8.0 

func (hnvr HostnameValidationResult) Overview() string

Overview provides a high-level summary of this validation check result.

func (HostnameValidationResult) Priority added in v0.8.0 

func (hnvr HostnameValidationResult) Priority() int

Priority indicates the level of importance for this validation check result.

This value is calculated by applying a priority modifier for specific failure conditions (recorded when the validation check result is initially obtained) to a baseline value specific to the validation check performed.

If the validation check result is flagged as ignored the priority modifier is also ignored.

func (HostnameValidationResult) Report added in v0.8.0 

func (hnvr HostnameValidationResult) Report() string

Report provides the validation check result in verbose human-readable format.

func (HostnameValidationResult) ServiceState added in v0.8.0 

func (hnvr HostnameValidationResult) ServiceState() nagios.ServiceState

ServiceState returns the appropriate Service Check Status label and exit code for this validation check result.

func (HostnameValidationResult) Status added in v0.8.0 

func (hnvr HostnameValidationResult) Status() string

Status is intended as a brief status of the validation check result. This can be used as initial lead-in text.

func (HostnameValidationResult) StatusDetail added in v0.8.0 

func (hnvr HostnameValidationResult) StatusDetail() string

StatusDetail provides additional details intended to extend the shorter status text with information suitable as explanation for the overall state of the validation check result. This text may span multiple lines.

func (HostnameValidationResult) String added in v0.8.0 

func (hnvr HostnameValidationResult) String() string

String provides the validation check result in human-readable format.

func (HostnameValidationResult) TotalCerts added in v0.8.0 

func (hnvr HostnameValidationResult) TotalCerts() int

TotalCerts returns the number of certificates in the evaluated certificate chain.

type SANsListValidationResult added in v0.8.0 

type SANsListValidationResult struct {
	// contains filtered or unexported fields
}

SANsListValidationResult is the validation result from performing a Subject Alternate Names (SANs) validation against a leaf certificate in a chain.

func ValidateSANsList added in v0.8.0 

func ValidateSANsList(
	certChain []*x509.Certificate,
	requiredEntries []string,
	validationOptions CertChainValidationOptions,
) SANsListValidationResult

ValidateSANsList asserts that the leaf certificate for a given certificate chain contains exactly the Subject Alternate Names specified (no more, no less). If specified, this validation check result is ignored.

NOTE: The logic for evaluating the SKIPSANSCHECKS keyword is handled by the config package.

func (SANsListValidationResult) CertChain added in v0.8.0 

func (slvr SANsListValidationResult) CertChain() []*x509.Certificate

CertChain returns the evaluated certificate chain.

func (SANsListValidationResult) CheckName added in v0.8.0 

func (slvr SANsListValidationResult) CheckName() string

CheckName emits the human-readable name of this validation check result.

func (SANsListValidationResult) Err added in v0.8.0 

func (slvr SANsListValidationResult) Err() error

Err returns the underlying error (if any) regardless of whether this validation check result is flagged as ignored.

func (SANsListValidationResult) IsCriticalState added in v0.8.0 

func (slvr SANsListValidationResult) IsCriticalState() bool

IsCriticalState indicates whether this validation check result is in a CRITICAL state. This returns false if the validation check resulted in an OK or WARNING state, or is flagged as ignored. True is returned otherwise.

func (SANsListValidationResult) IsFailed added in v0.8.0 

func (slvr SANsListValidationResult) IsFailed() bool

IsFailed indicates whether this validation check result is not flagged as ignored and problems were identified.

func (SANsListValidationResult) IsIgnored added in v0.8.0 

func (slvr SANsListValidationResult) IsIgnored() bool

IsIgnored indicates whether this validation check result was flagged as ignored for the purposes of determining final validation state.

func (SANsListValidationResult) IsOKState added in v0.8.0 

func (slvr SANsListValidationResult) IsOKState() bool

IsOKState indicates whether this validation check result is in an OK or passing state. For the purposes of validation check evaluation, ignored validation checks are considered to be a subset of OK status.

func (SANsListValidationResult) IsSucceeded added in v0.8.0 

func (slvr SANsListValidationResult) IsSucceeded() bool

IsSucceeded indicates whether this validation check result is not flagged as ignored and no problems with the certificate chain were identified.

func (SANsListValidationResult) IsUnknownState added in v0.8.0 

func (slvr SANsListValidationResult) IsUnknownState() bool

IsUnknownState indicates whether this validation check result is in an UNKNOWN state.

func (SANsListValidationResult) IsWarningState added in v0.8.0 

func (slvr SANsListValidationResult) IsWarningState() bool

IsWarningState indicates whether this validation check result is in a WARNING state. This returns false if the validation check resulted in an OK or CRITICAL state, or is flagged as ignored. True is returned otherwise.

func (SANsListValidationResult) NumExpected added in v0.8.0 

func (slvr SANsListValidationResult) NumExpected() int

NumExpected returns the number of user-specified SANs list entries.

func (SANsListValidationResult) NumMatched added in v0.8.0 

func (slvr SANsListValidationResult) NumMatched() int

NumMatched returns the number of matched SANs list entries for the evaluated leaf certificate.

func (SANsListValidationResult) NumMismatched added in v0.8.0 

func (slvr SANsListValidationResult) NumMismatched() int

NumMismatched returns the number of failed SANs list entry matches for the evaluated leaf certificate.

func (SANsListValidationResult) NumPresent added in v0.8.0 

func (slvr SANsListValidationResult) NumPresent() int

NumPresent returns the number of SANs list entries for the evaluated leaf certificate.

func (SANsListValidationResult) Overview added in v0.8.0 

func (slvr SANsListValidationResult) Overview() string

Overview provides a high-level summary of this validation check result.

func (SANsListValidationResult) Priority added in v0.8.0 

func (slvr SANsListValidationResult) Priority() int

Priority indicates the level of importance for this validation check result.

This value is calculated by applying a priority modifier for specific failure conditions (recorded when the validation check result is initially obtained) to a baseline value specific to the validation check performed.

If the validation check result is flagged as ignored the priority modifier is also ignored.

func (SANsListValidationResult) Report added in v0.8.0 

func (slvr SANsListValidationResult) Report() string

Report provides the validation check result in verbose human-readable format.

func (SANsListValidationResult) ServiceState added in v0.8.0 

func (slvr SANsListValidationResult) ServiceState() nagios.ServiceState

ServiceState returns the appropriate Service Check Status label and exit code for this validation check result.

func (SANsListValidationResult) Status added in v0.8.0 

func (slvr SANsListValidationResult) Status() string

Status is intended as a brief status of the validation check result. This can be used as initial lead-in text.

func (SANsListValidationResult) StatusDetail added in v0.8.0 

func (slvr SANsListValidationResult) StatusDetail() string

StatusDetail provides additional details intended to extend the shorter status text with information suitable as explanation for the overall state of the validation check result. This text may span multiple lines.

func (SANsListValidationResult) String added in v0.8.0 

func (slvr SANsListValidationResult) String() string

String provides the validation check result in human-readable format.

func (SANsListValidationResult) TotalCerts added in v0.8.0 

func (slvr SANsListValidationResult) TotalCerts() int

TotalCerts returns the number of certificates in the evaluated certificate chain.

type ServiceStater added in v0.8.0 

type ServiceStater interface {
	IsCriticalState() bool
	IsWarningState() bool
	IsOKState() bool
}

ServiceStater represents a type that is capable of evaluating its overall state.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.