Documentation
¶
Overview ¶
Package certchain handles signed exchange certificates.
Index ¶
Constants ¶
const MaxCertDuration = 90 * (24 * time.Hour) // 90 days
MaxCertDuration represents the maximum duration allowed for the validity period of signed exchange certificates.
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 ¶
var ErrDummyOCSPResponse = errors.New("certchain: verifying dummy OCSPResponse")
ErrDummyOCSPResponse is returned if VerifyForRawChain/VerifySXGCriteria is called on DummyOCSPResponse.
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.
type OCSPResponse ¶
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 ¶
NewRawChainFromPEM creates a new RawChain from PEM bytes.
func (*RawChain) VerifyChain ¶
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 ¶
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.
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.
Source Files
¶
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. |