certchain

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Sep 9, 2022 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package certchain handles signed exchange certificates.

Index

Constants

View Source
const MaxCertDuration = 90 * (24 * time.Hour) // 90 days

MaxCertDuration represents the maximum duration allowed for the validity period of signed exchange certificates.

View Source
const MaxOCSPResponseDuration = 7 * (24 * time.Hour) // 7 days

MaxOCSPResponseDuration represents the maximum duration allowed for the validity period of OCSP responses. used with signed exchanges.

Variables

View Source
var ErrDummyOCSPResponse = errors.New("certchain: verifying dummy OCSPResponse")

ErrDummyOCSPResponse is returned if VerifyForRawChain/VerifySXGCriteria is called on DummyOCSPResponse.

View Source
var ErrInvalidOCSPValue = errors.New("certchain: invalid ocsp value")

ErrInvalidOCSPValue is returned by ReadCBOR if the provided CBOR stream contained invalid OCSP response.

Functions

This section is empty.

Types

type AugmentedChain

type AugmentedChain struct {
	*RawChain

	// OCSPResp contains an OCSP response for the end-entity certificate.
	OCSPResp *OCSPResponse

	// SCTList contains unembedded SCTs for the end-entity certificate.
	//
	// Note SCTs can also be embedded in certificates and OCSP responses.
	// SCTList is required only when neither the end-entity certificate nor
	// its OCSP response contains embedded SCTs.
	SCTList []byte
}

AugmentedChain is a certificate chain augmented with an OCSP response and unembedded SCTs (Signed Certificate Timestamps) for the end-entity certificate. It is designed to support application/cert-chain+cbor certificate chains, but augments the certificate chain instead of each certificate. In particular, AugmentedChain stores unembedded SCTs only for the end-entity certificate while the application/cert-chain+cbor format can contain SCTs for every certificate. This difference should not matter in practice: the signed exchange validation process only uses SCTs of the end-entity certificate.

AugmentedChain handles SCT lists as an opaque byte sequence. It does not know about the validity of SCTs against the certificate, for example.

func NewAugmentedChain

func NewAugmentedChain(c *RawChain, ocsp *OCSPResponse, sct []byte) *AugmentedChain

NewAugmentedChain creates a new AugmentedChain.

func NewAugmentedChainFromCBOR

func NewAugmentedChainFromCBOR(cborBytes []byte) (*AugmentedChain, error)

NewAugmentedChainFromCBOR creates a new AugmentedChain from a serialized certificate chain in the application/cert-chain+cbor format.

If you are reading the certificate chain from a file or over the network, consider using ReadAugmentedChain. It stops reading immediately when it has detected an error in the middle.

See ReadAugmentedChain for how the ocsp and sct values are handled.

func ReadAugmentedChain

func ReadAugmentedChain(r io.Reader) (*AugmentedChain, error)

ReadAugmentedChain reads an application/cert-chain+cbor stream from r to create an AugmentedChain.

The ocsp value is parsed into an OCSPResponse. In case of a parse error, ReadAugmentedChain creates an AugmentedChain with DummyOCSPResponse and returns it with ErrInvalidOCSPValue; the invalid ocsp value is discarded. The caller may expect or ignore ErrInvalidOCSPValue, e.g. when using a test certificate.

ReadAugmentedChain keeps the sct value only for the end-entity certificate. The sct values for other certificates, if any, are silently discarded. Note AugmentedChain stores unembedded SCTs only for the end-entity certifiacte.

func (*AugmentedChain) HasSCTList

func (ac *AugmentedChain) HasSCTList() bool

HasSCTList reports whether the AugmentedChain ac contains SCTs. It looks for an SCT extension in the end-entity certificate and the OCSP response for embedded SCTs, as well as the SCTList field for unembedded SCTs.

HasSCTList only checks the existence, not the content. The SCTList field is assumed to contain SCTs unless it is nil or empty.

func (*AugmentedChain) VerifyAll

func (ac *AugmentedChain) VerifyAll(t time.Time, inProduction bool) error

VerifyAll does comprehensive checks with ac. More specifically it checks:

  • ac.RawChain.VerifyChain succeeds.
  • ac.RawChain.VerifySXGCriteria succeeds.
  • ac.OCSPResp.VerifyForRawChain succeeds.
  • ac.OCSPResp.VerifySXGCriteria succeeds.
  • ac.HasSCTList returns true.

If inProduction is true, allow test certs and OCSP to have dummy value.

VerifyAll returns a multierror.Error (hashicorp/go-multierror) to report as many problems as possible.

func (*AugmentedChain) WriteCBOR

func (ac *AugmentedChain) WriteCBOR(w io.Writer) error

WriteCBOR writes an AugmentedChain to w in the application/cert-chain+cbor format.

type OCSPResponse

type OCSPResponse struct {
	*ocsp.Response
	Raw []byte
}

OCSPResponse wraps an ocsp.Response with the DER bytes.

var DummyOCSPResponse *OCSPResponse = &OCSPResponse{
	new(ocsp.Response),
	[]byte("dummy-ocsp"),
}

DummyOCSPResponse is a dummy OCSPResponse to use with test certificates lacking OCSP responders, such as self-signed certificates.

Note DummyOCSPResponse does not comprise a valid OCSP response. It just provides dummy bytes to fill in the application/cert-chain+cbor stream.

func ParseOCSPResponse

func ParseOCSPResponse(bytes []byte) (*OCSPResponse, error)

ParseOCSPResponse parses an OCSP response in DER form. It only supports responses for a single certificate. If the response contains a certificate then the signature over the response is checked.

func ParseOCSPResponseForRawChain

func ParseOCSPResponseForRawChain(derBytes []byte, c *RawChain) (*OCSPResponse, error)

ParseOCSPResponseForRawChain parses an OCSP response in DER form and searches for an OCSPResponse relating to c. If such an OCSPResponse is found and the OCSP response contains a certificate then the signature over the response is checked. c.Issuer will be used to validate the signature or embedded certificate.

func (*OCSPResponse) VerifyForRawChain

func (resp *OCSPResponse) VerifyForRawChain(t time.Time, c *RawChain) error

VerifyForRawChain verifies that resp is valid at the provided time t for the RawChain c. More specifically it checks resp has:

  • a serial number matching c.Leaf.
  • a valid signature or embedded certificate from c.Issuer.
  • an update period that includes t.

VerifyForRawChain returns ErrDummyOCSPResponse if resp is DummyOCSPResponse. In other error cases, VerifyForRawChain returns a multierror.Error (hashicorp/go-multierror) to report as many problems as possible.

BUG(yuizumi): VerifyForRawChain should verify the OCSPResponse has both a matching serial number and a matching issuer, but it verifies the issuer only indirectly, through the signature or embedded certificate.

func (*OCSPResponse) VerifySXGCriteria

func (resp *OCSPResponse) VerifySXGCriteria() error

VerifySXGCriteria verifies that resp satisfies the criteria for use with signed exchanges. More specifically it checks resp has:

  • ocsp.Good as its Status value.
  • an update interval not longer than MaxOCSPResponseDuration.

VerifySXGCriteria returns ErrDummyOCSPResponse if resp is DummyOCSPResponse. In other error cases, VerifySXGCriteria returns a multierror.Error (hashicorp/go-multierror) to report as many problems as possible.

type RawChain

type RawChain struct {
	// Certs is the array of certificates which form this certificate chain,
	// starting with the end-entity certificate.
	Certs []*x509.Certificate

	// Digest gives a unique identifier of this certificate chain, produced
	// using a hash function.
	Digest string

	// Leaf represents the end-entity certificate of this certificate chain.
	// It is always equal to Certs[0].
	Leaf *x509.Certificate

	// Issuer represents the certificate of the Leaf's direct issuer. It is
	// equal to Certs[1] for CA-issued certificates and Certs[0] (Leaf) for
	// self-signed certificates.
	Issuer *x509.Certificate

	// OCSPServer is the URI of the Leaf's OCSP responder. If Leaf does not
	// have an OCSP responder, OCSPServer is an empty string.
	OCSPServer string
}

RawChain represents an X509 certificate chain, populated with information extracted from it for convenience.

func NewRawChain

func NewRawChain(certs []*x509.Certificate) (*RawChain, error)

NewRawChain creates a new RawChain with certs.

certs must form a certificate chain, where the first element is the end-entity certificate and the last element is the root certificate or the certificate issued by a trusted root. Each certificate in the chain must be followed by the certificate of its direct issuer, except for the last certificate.

func NewRawChainFromPEM

func NewRawChainFromPEM(bytes []byte) (*RawChain, error)

NewRawChainFromPEM creates a new RawChain from PEM bytes.

func (*RawChain) VerifyChain

func (c *RawChain) VerifyChain(t time.Time) error

VerifyChain attempts to verify that c is valid as of the provided time t, calling c.Leaf.Verify internally.

WARNING: VerifyChain does not verify that the root certificate is trusted by operating systems or user agents.

func (*RawChain) VerifySXGCriteria

func (c *RawChain) VerifySXGCriteria() error

VerifySXGCriteria verifies that the RawChain c satisifes the criteria for use with signed exchanges. More specifically it checks c.Leaf has:

  • a public key of supported cryptographic algorithm.
  • canHttpSignExchange extension.
  • a validity period not longer than MaxCertDuration.

VerifySXGCriteria returns multierror.Error (hashicorp/go-multierror) to report as many problems as possible.

BUG(yuizumi): VerifySXGCriteria accepts only ECDSA-P256 and ECDSA-P384 public keys; the signedexchange package (WICG/webpackage) supports only those keys at the moment.

func (*RawChain) WritePEM

func (c *RawChain) WritePEM(w io.Writer) error

WritePEM writes the RawChain to w in the PEM format.

Notes

Bugs

  • VerifyForRawChain should verify the OCSPResponse has both a matching serial number and a matching issuer, but it verifies the issuer only indirectly, through the signature or embedded certificate.

  • We are using bytes.Equal to match the issuer and the subject, like the crypto/x509 package. It is not the way we are supposed to compare distinguished names, although it is a good approximate.

  • VerifySXGCriteria accepts only ECDSA-P256 and ECDSA-P384 public keys; the signedexchange package (WICG/webpackage) supports only those keys at the moment.

Directories

Path Synopsis
Package certchainutil complements the certchain package.
Package certchainutil complements the certchain package.
Package certmanager manages signed exchange certificates.
Package certmanager manages signed exchange certificates.
acmeclient
Package acmeclient provides a RawChainSource to acquire a signed exchange certificate using the ACME protocol.
Package acmeclient provides a RawChainSource to acquire a signed exchange certificate using the ACME protocol.
futureevent
Package futureevent defines interface to handle future events.
Package futureevent defines interface to handle future events.

Jump to

Keyboard shortcuts

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