verifier

package
v0.0.0-...-b578434 Latest Latest
Warning

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

Go to latest
Published: Jun 8, 2021 License: Apache-2.0, ISC, MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetCRL

func GetCRL(ctx context.Context, distributionPoint string) (*pkix.CertificateList, error)

GetCRL - fetch and parse the CRL from the provided distrution point

Types

type Graph

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

Graph represents signing relationships between SubjectAndKey tuples. A node in the graph is a SubjectAndKey. An edge in the graph is a certificate issued by the direct predecessor (tail) to the direct successor (head).

func NewGraph

func NewGraph() (g *Graph)

NewGraph initializes an empty Graph.

func (*Graph) AddCert

func (g *Graph) AddCert(c *x509.Certificate)

AddCert inserts an edge for c into the graph, and creates nodes as needed.

func (*Graph) AddRoot

func (g *Graph) AddRoot(c *x509.Certificate)

AddRoot adges an edge for certificate c, and marks it as a root.

func (*Graph) AppendFromPEM

func (g *Graph) AppendFromPEM(r io.Reader, root bool) int

AppendFromPEM adds any certificates encoded as PEM from r to the graph. If root is true, it marks them as roots. It returns the number of certificates parsed.

func (*Graph) Edges

func (g *Graph) Edges() []*GraphEdge

Edges returns all edges in the graph as a slice.

func (*Graph) FindEdge

func (g *Graph) FindEdge(fp x509.CertificateFingerprint) *GraphEdge

FindEdge returns an edge with a certificate matching the given SHA256 fingerprint, if it exists. If it does not exist, FindEdge returns nil.

func (*Graph) FindNode

func (g *Graph) FindNode(fp x509.CertificateFingerprint) *GraphNode

FindNode returns a node with a matching spki_subject_fingerprint to fp, if it exists. If it does not exist, FindNode returns nil.

func (*Graph) IsRoot

func (g *Graph) IsRoot(c *x509.Certificate) bool

IsRoot returns true if c is a root in the graph.

func (*Graph) Nodes

func (g *Graph) Nodes() (out []*GraphNode)

Nodes returns a slice of all nodes in the graph.

func (*Graph) WalkChains

func (g *Graph) WalkChains(c *x509.Certificate) (out []x509.CertificateChain)

WalkChains is the same as WalkChainsAsync, except synchronous.

func (*Graph) WalkChainsAsync

func (g *Graph) WalkChainsAsync(c *x509.Certificate, opt WalkOptions) chan x509.CertificateChain

WalkChainsAsync performs a depth-first walk of g, starting at c, to any root edges. It returns all non-looping paths from c to a root. WalkChainsAsync immediately returns a channel. It sends any chains it finds through the channel, and closes it once all paths have been found. If the channel does not get consumed, this function may block indefinitely.

type GraphEdge

type GraphEdge struct {
	Certificate *x509.Certificate
	// contains filtered or unexported fields
}

A GraphEdge is a certificate that joins two SubjectAndKeys.

type GraphEdgeSet

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

A GraphEdgeSet represents a set of edges. Edges are deduplicated by certificate fingerprint.

func NewGraphEdgeSet

func NewGraphEdgeSet() (es *GraphEdgeSet)

NewGraphEdgeSet initializes an empty GraphEdgeSet.

func (*GraphEdgeSet) ContainsCertificate

func (es *GraphEdgeSet) ContainsCertificate(c *x509.Certificate) bool

ContainsCertificate returns true if c is contained in the GraphEdgeSet.

func (*GraphEdgeSet) ContainsEdge

func (es *GraphEdgeSet) ContainsEdge(edge *GraphEdge) bool

ContainsEdge returns true if the edge is contained in the GraphEdgeSet.

func (*GraphEdgeSet) Edges

func (es *GraphEdgeSet) Edges() (out []*GraphEdge)

Edges returns all edges in the set as a slice.

func (*GraphEdgeSet) FindEdge

FindEdge returns an edge matching the certificate fingerprint, if it exists. If it does not exist, FindEdge returns nil.

func (*GraphEdgeSet) Size

func (es *GraphEdgeSet) Size() int

Size returns the number of edges in the GraphEdgeSet.

type GraphNode

type GraphNode struct {
	SubjectAndKey *x509.SubjectAndKey
	// contains filtered or unexported fields
}

A GraphNode is a SubjectAndKey

type RevocationInfo

type RevocationInfo struct {
	RevocationTime time.Time
	NextUpdate     time.Time
	Reason         crl.RevocationReasonCode
}

RevocationInfo provides basic revocation information

func CheckCRL

func CheckCRL(ctx context.Context, c *x509.Certificate, certList *pkix.CertificateList) (isRevoked bool, info *RevocationInfo, err error)

CheckCRL - check whether the provided certificate has been revoked through a CRL. If no certList is provided, function will attempt to fetch it through the GetCRL function. If performing repeated calls to this function, independently calling GetCRL and caching the list between calls to CheckCRL is highly recommended (otherwise the CRL will be fetched on every single call to CheckCRL!).

func CheckOCSP

func CheckOCSP(ctx context.Context, c *x509.Certificate, issuer *x509.Certificate) (isRevoked bool, info *RevocationInfo, e error)

CheckOCSP - check the ocsp status of a provided certificate if issuer is not provided, function will attempt to fetch it through the AIA issuing field (which will then fail if this field is empty)

type RevocationProvider

type RevocationProvider interface {
	// CheckOCSP - check the ocsp status of a provided certificate
	CheckOCSP(ctx context.Context, c *x509.Certificate, issuer *x509.Certificate) (isRevoked bool, info *RevocationInfo, e error)
	// CheckCRL - check whether the provided certificate has been revoked through
	// a CRL. If no certList is provided, function will attempt to fetch it.
	CheckCRL(ctx context.Context, c *x509.Certificate, certList *pkix.CertificateList) (isRevoked bool, info *RevocationInfo, err error)
}

RevocationProvider is an interface to implement revocation status provider

type VerificationOptions

type VerificationOptions struct {
	VerifyTime         time.Time
	Name               string
	PresentedChain     *Graph // XXX: Unused
	ShouldCheckOCSP    bool
	ShouldCheckCRL     bool
	RevocationProvider RevocationProvider
	CRLSet             *google.CRLSet
	OneCRL             *mozilla.OneCRL
}

VerificationOptions contains settings for Verifier.Verify(). VerificationOptions should be safely copyable.

type VerificationResult

type VerificationResult struct {

	// The name being checked, e.g. "www.censys.io".
	Name string

	// Whitelisted is true if the certificate is whitelisted by a given verifier
	// as trusted, e.g. when Apple whitelisted subset of StartCom certs by SPKI
	// hash in the wake of the WoSign incidents surrounding misissuance.
	Whitelisted bool

	// Blacklisted is true if the certificate is blacklisted by a given verifier
	// as untrusted, e.g. Cloudflare certificates valid at the time of Heartbleed
	// disclosure in Chrome.
	Blacklisted bool

	// InRevocationSet is true if the certificate has been revoked and is listed
	// in the revocation set that is part of the Verifier (e.g. in OneCRL).
	InRevocationSet bool

	// OCSPRevoked is true if the certificate has been revoked through OCSP,
	// which is only checked if VerificationOptions.ShouldCheckOCSP flag is set
	OCSPRevoked bool

	// OCSPRevocationInfo provides revocation info when OCSPRevoked is true
	OCSPRevocationInfo *RevocationInfo

	// CRLRevoked is true if the certificate has been revoked through CRL,
	// which is only checked if VerificationOptions.ShouldCheckCRL flag is set
	CRLRevoked bool

	// CRLRevocationInfo provides revocation info when CRLRevoked is true
	CRLRevocationInfo *RevocationInfo

	// ValiditionError will be non-nil when there was some sort of error during
	// validation not involving a name mismatch, e.g. if a chain could not be
	// built.
	ValidationError error

	// NameError will be non-nil when there was a mismatch between the name on the
	// certificate and the name being verified against.
	NameError error

	// Parents is a set of currently valid certificates that are immediate parents
	// of the certificate being verified, and are part of a chain that is valid at
	// the time the certificate being verified expires.
	Parents []*x509.Certificate

	// CurrentChains is a list of validated certificate chains that are valid at
	// ValidationTime, starting at the certificate being verified, and ending at a
	// certificate in the root store.
	CurrentChains []x509.CertificateChain

	// ExpiredChains is a list of certificate chains that were valid at some
	// point, but not at ValidationTime.
	ExpiredChains []x509.CertificateChain

	// NeverValidChains is a list of certificate chains that could never be valid
	// due to date-related issues, but are otherwise valid.
	NeverValidChains []x509.CertificateChain

	// ValidAtExpirationChains is a list of certificate chains that were valid at
	// the time of expiration of the certificate being validated.
	ValidAtExpirationChains []x509.CertificateChain

	// CertificateType is one of Leaf, Intermediate, or Root.
	CertificateType x509.CertificateType

	// VerifyTime is time used in verification, set in the VerificationOptions.
	VerifyTime time.Time

	// Expired is false if NotBefore < VerifyTime < NotAfter
	Expired bool

	// ParentSPKISubjectFingerprint is the SHA256 of the (SPKI, Subject) for
	// parents of this certificate.
	ParentSPKISubjectFingerprint x509.CertificateFingerprint

	// ParentSPKI is the raw bytes of the subject public key info of the parent. It
	// is the SPKI used as part of the ParentSPKISubjectFingerprint.
	ParentSPKI []byte
}

VerificationResult contains the result of a verification of a certificate against a store and its associated policies. It discerns between NameError, meaning the name on the certificate does not match, and a ValidationError, meaning some sort of issue with the cryptography, or other issues with the chain.

func (*VerificationResult) HadTrustedChain

func (res *VerificationResult) HadTrustedChain() bool

HadTrustedChain returns true if at some point in time, the certificate had a chain to a trusted root in this store.

This is equivalent to checking if len(Current) > 0 || len(ValidAtExpired) > 0

func (*VerificationResult) HasTrustedChain

func (res *VerificationResult) HasTrustedChain() bool

HasTrustedChain returns true if len(current) > 0

func (*VerificationResult) MatchesDomain

func (res *VerificationResult) MatchesDomain() bool

MatchesDomain returns true if NameError == nil and Name != "".

type Verifier

type Verifier struct {
	PKI             *Graph
	VerifyProcedure VerifyProcedure
}

A Verifier represents a context for verifying certificates.

func NewApple

func NewApple(pki *Graph) (apple *Verifier)

NewApple returns a new verifier mimicking Apple SecureTransport.

func NewGoogleCTPrimary

func NewGoogleCTPrimary(pki *Graph) (gct *Verifier)

NewGoogleCTPrimary returns a new verifier mimicking the behavior of the primary Google CT logs (e.g. Pilot).

func NewJava

func NewJava(pki *Graph) (java *Verifier)

NewJava returns a new verifier mimicking javax.net.ssl.

func NewMicrosoft

func NewMicrosoft(pki *Graph) (microsoft *Verifier)

NewMicrosoft returns a new verifier mimicking Microsoft SChannel.

func NewNSS

func NewNSS(pki *Graph) (nss *Verifier)

NewNSS returns a new verifier mimicking NSS.

func NewVerifier

func NewVerifier(pki *Graph, verifyProc VerifyProcedure) *Verifier

NewVerifier returns and initializes a new Verifier given a PKI graph and set of verification procedures.

func (*Verifier) Verify

func (v *Verifier) Verify(c *x509.Certificate, opts VerificationOptions) (res *VerificationResult)

Verify checks if c chains back to a certificate in Roots, possibly via a certificate in Intermediates, and returns all such chains. It additional checks if the Name in the VerificationOptions matches the name on the certificate.

func (*Verifier) VerifyWithContext

func (v *Verifier) VerifyWithContext(ctx context.Context, c *x509.Certificate, opts VerificationOptions) (res *VerificationResult)

VerifyWithContext checks if c chains back to a certificate in Roots, possibly via a certificate in Intermediates, and returns all such chains. It additional checks if the Name in the VerificationOptions matches the name on the certificate.

type VerifyProcedure

type VerifyProcedure interface {
}

VerifyProcedure is an interface to implement additional browser specific logic at the start and end of verification.

type VerifyProcedureApple

type VerifyProcedureApple struct{}

VerifyProcedureApple implements the VerifyProcedure interface for Apple.

type VerifyProcedureGoogleCTPrimary

type VerifyProcedureGoogleCTPrimary struct{}

VerifyProcedureGoogleCTPrimary implements the VerifyProcedure interface for the primary Google CT servers.

type VerifyProcedureJava

type VerifyProcedureJava struct{}

VerifyProcedureJava implements the VerifyProcedure interface for Java.

type VerifyProcedureMicrosoft

type VerifyProcedureMicrosoft struct{}

VerifyProcedureMicrosoft implements the VerifyProcedure interface for Microsoft.

type VerifyProcedureNSS

type VerifyProcedureNSS struct{}

VerifyProcedureNSS implements the VerifyProcedure interface for NSS.

type WalkOptions

type WalkOptions struct {
	ChannelSize int
}

WalkOptions contains options for the Graph.Walk* functions. It's a structure since anything related to verification inevitably results in a large number of arguments.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL