issuance

Documentation

Index

• func ContainsMustStaple(extensions []pkix.Extension) bool
• type CRLProfile
  • func NewCRLProfile(config CRLProfileConfig) (*CRLProfile, error)
• type CRLProfileConfig
• type CRLRequest
• type Certificate
  • func LoadCertificate(path string) (*Certificate, error)
  • func LoadChain(certFiles []string) ([]*Certificate, error)
  • func NewCertificate(ic *x509.Certificate) (*Certificate, error)
  • func (ic *Certificate) NameID() NameID
• type IssuanceRequest
  • func RequestFromPrecert(precert *x509.Certificate, scts []ct.SignedCertificateTimestamp) (*IssuanceRequest, error)
• type Issuer
  • func LoadIssuer(config IssuerConfig, clk clock.Clock) (*Issuer, error)
  • func (i *Issuer) IsActive() bool
  • func (i *Issuer) Issue(token *issuanceToken) ([]byte, error)
  • func (i *Issuer) IssueCRL(prof *CRLProfile, req *CRLRequest) ([]byte, error)
  • func (i *Issuer) KeyType() x509.PublicKeyAlgorithm
  • func (i *Issuer) Name() string
  • func (i *Issuer) NameID() NameID
  • func (i *Issuer) Prepare(prof *Profile, req *IssuanceRequest) ([]byte, *issuanceToken, error)
• type IssuerConfig
• type IssuerLoc
• type NameID
  • func IssuerNameID(ee *x509.Certificate) NameID
  • func ResponderNameID(resp *ocsp.Response) NameID
  • func SubjectNameID(ic *Certificate) NameID
• type PolicyConfig
• type Profile
  • func NewProfile(profileConfig ProfileConfig, skipLints []string) (*Profile, error)
• type ProfileConfig

Functions

func ContainsMustStaple

func ContainsMustStaple(extensions []pkix.Extension) bool

ContainsMustStaple returns true if the provided set of extensions includes an entry whose OID and value both match the expected values for the OCSP Must-Staple (a.k.a. id-pe-tlsFeature) extension.

Types

type CRLProfile

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

func NewCRLProfile

func NewCRLProfile(config CRLProfileConfig) (*CRLProfile, error)

type CRLProfileConfig

type CRLProfileConfig struct {
	ValidityInterval config.Duration
	MaxBackdate      config.Duration
}

type CRLRequest

type CRLRequest struct {
	Number *big.Int
	Shard  int64

	ThisUpdate time.Time

	Entries []x509.RevocationListEntry

	// TODO(#7296): Remove this and instead compute it from Issuer.CRLBaseURL
	DeprecatedIDPBaseURL string
}

type Certificate

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

Certificate embeds an *x509.Certificate and represents the added semantics that this certificate is a CA certificate.

func LoadCertificate

func LoadCertificate(path string) (*Certificate, error)

func LoadChain

func LoadChain(certFiles []string) ([]*Certificate, error)

LoadChain takes a list of filenames containing pem-formatted certificates, and returns a chain representing all of those certificates in order. It ensures that the resulting chain is valid. The final file is expected to be a root certificate, which the chain will be verified against, but which will not be included in the resulting chain.

func NewCertificate

func NewCertificate(ic *x509.Certificate) (*Certificate, error)

NewCertificate wraps an in-memory cert in an issuance.Certificate, marking it as an issuer cert. It may fail if the certificate does not contain the attributes expected of an issuer certificate.

func (*Certificate) NameID

func (ic *Certificate) NameID() NameID

NameID is equivalent to SubjectNameID(ic), but faster because it is precomputed.

type IssuanceRequest

type IssuanceRequest struct {
	PublicKey    crypto.PublicKey
	SubjectKeyId []byte

	Serial []byte

	NotBefore time.Time
	NotAfter  time.Time

	CommonName string
	DNSNames   []string

	IncludeMustStaple bool
	IncludeCTPoison   bool
	// contains filtered or unexported fields
}

IssuanceRequest describes a certificate issuance request

func RequestFromPrecert

func RequestFromPrecert(precert *x509.Certificate, scts []ct.SignedCertificateTimestamp) (*IssuanceRequest, error)

RequestFromPrecert constructs a final certificate IssuanceRequest matching the provided precertificate. It returns an error if the precertificate doesn't contain the CT poison extension.

type Issuer

type Issuer struct {
	// TODO(#7159): make Cert, Signer, and Linter private when all signing ops
	// are handled through this package (e.g. the CA doesn't need direct access
	// while signing CRLs anymore).
	Cert   *Certificate
	Signer crypto.Signer
	Linter *linter.Linter
	// contains filtered or unexported fields
}

Issuer is capable of issuing new certificates.

func LoadIssuer

func LoadIssuer(config IssuerConfig, clk clock.Clock) (*Issuer, error)

LoadIssuer constructs a new Issuer, loading its certificate from disk and its private key material from the indicated location. It also verifies that the issuer metadata (such as AIA URLs) is well-formed.

func (*Issuer) IsActive

func (i *Issuer) IsActive() bool

IsActive is true if the issuer is willing to issue precertificates, and false if the issuer is only willing to issue final certificates, OCSP, and CRLs.

func (*Issuer) Issue

func (i *Issuer) Issue(token *issuanceToken) ([]byte, error)

Issue performs a real issuance using an issuanceToken resulting from a previous call to Prepare(). Call this at most once per token. Calls after the first will receive an error.

func (*Issuer) IssueCRL

func (i *Issuer) IssueCRL(prof *CRLProfile, req *CRLRequest) ([]byte, error)

func (*Issuer) KeyType

func (i *Issuer) KeyType() x509.PublicKeyAlgorithm

KeyType returns either x509.RSA or x509.ECDSA, depending on whether the issuer has an RSA or ECDSA keypair. This is useful for determining which issuance requests should be routed to this issuer.

func (*Issuer) Name

func (i *Issuer) Name() string

Name provides the Common Name specified in the issuer's certificate.

func (*Issuer) NameID

func (i *Issuer) NameID() NameID

NameID provides the NameID of the issuer's certificate.

func (*Issuer) Prepare

func (i *Issuer) Prepare(prof *Profile, req *IssuanceRequest) ([]byte, *issuanceToken, error)

Prepare combines the given profile and request with the Issuer's information to create a template certificate. It then generates a linting certificate from that template and runs the linter over it. If successful, returns both the linting certificate (which can be stored) and an issuanceToken. The issuanceToken can be used to sign a matching certificate with this Issuer's private key.

type IssuerConfig

type IssuerConfig struct {
	// Active determines if the issuer can be used to sign precertificates. All
	// issuers, regardless of this field, can be used to sign final certificates
	// (for which an issuance token is presented), OCSP responses, and CRLs.
	// All Active issuers of a given key type (RSA or ECDSA) are part of a pool
	// and each precertificate will be issued randomly from a selected pool.
	// The selection of which pool depends on the precertificate's key algorithm,
	// the ECDSAForAll feature flag, and the ECDSAAllowListFilename config field.
	Active bool

	// UseForRSALeaves is a synonym for Active. Note that, despite the name,
	// setting this field to true cannot add an issuer to a pool different than
	// its key type. An active issuer will always be part of a pool based on its
	// key type.
	//
	// Deprecated: use Active instead.
	UseForRSALeaves bool
	// UseForECDSALeaves is a synonym for Active. Note that, despite the name,
	// setting this field to true cannot add an issuer to a pool different than
	// its key type. An active issuer will always be part of a pool based on its
	// key type.
	//
	// Deprecated: use Active instead.
	UseForECDSALeaves bool

	IssuerURL  string `validate:"required,url"`
	OCSPURL    string `validate:"required,url"`
	CRLURLBase string `validate:"omitempty,url,startswith=http://,endswith=/"`

	Location IssuerLoc
}

IssuerConfig describes the constraints on and URLs used by a single issuer.

type IssuerLoc

type IssuerLoc struct {
	// A file from which a private key will be read and parsed.
	File string `validate:"required_without_all=ConfigFile PKCS11"`
	// A file from which a pkcs11key.Config will be read and parsed, if File is not set.
	ConfigFile string `validate:"required_without_all=PKCS11 File"`
	// An in-memory pkcs11key.Config, which will be used if ConfigFile is not set.
	PKCS11 *pkcs11key.Config `validate:"required_without_all=ConfigFile File"`
	// A file from which a certificate will be read and parsed.
	CertFile string `validate:"required"`
	// Number of sessions to open with the HSM. For maximum performance,
	// this should be equal to the number of cores in the HSM. Defaults to 1.
	NumSessions int
}

IssuerLoc describes the on-disk location and parameters that an issuer should use to retrieve its certificate and private key. Only one of File, ConfigFile, or PKCS11 should be set.

type NameID

type NameID int64

NameID is a statistically-unique small ID which can be computed from both CA and end-entity certs to link them together into a validation chain. It is computed as a truncated hash over the issuer Subject Name bytes, or over the end-entity's Issuer Name bytes, which are required to be equal.

func IssuerNameID

func IssuerNameID(ee *x509.Certificate) NameID

IssuerNameID returns the IssuerNameID (a truncated hash over the raw bytes of the Issuer Distinguished Name) of the given end-entity certificate. Useful for performing lookups in contexts that don't expect hash collisions.

func ResponderNameID

func ResponderNameID(resp *ocsp.Response) NameID

ResponderNameID returns the NameID (a truncated hash over the raw bytes of the Responder Distinguished Name) of the given OCSP Response. As per the OCSP spec, it is technically possible for this field to not be populated: the OCSP Response can instead contain a SHA-1 hash of the Issuer Public Key as the Responder ID. However, all OCSP responses that we produce contain it, because the Go stdlib always includes it.

func SubjectNameID

func SubjectNameID(ic *Certificate) NameID

SubjectNameID returns the NameID (a truncated hash over the raw bytes of a Distinguished Name) of this issuer certificate's Subject. Useful for storing as a lookup key in contexts that don't expect hash collisions.

type PolicyConfig

type PolicyConfig struct {
	OID string `validate:"required"`
}

PolicyConfig describes a policy

type Profile

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

Profile is the validated structure created by reading in ProfileConfigs and IssuerConfigs

func NewProfile

func NewProfile(profileConfig ProfileConfig, skipLints []string) (*Profile, error)

NewProfile synthesizes the profile config and issuer config into a single object, and checks various aspects for correctness.

type ProfileConfig

type ProfileConfig struct {
	AllowMustStaple bool
	AllowCTPoison   bool
	AllowSCTList    bool
	AllowCommonName bool

	MaxValidityPeriod   config.Duration
	MaxValidityBackdate config.Duration

	// Deprecated: we do not respect this field.
	Policies []PolicyConfig `validate:"-"`
}

ProfileConfig describes the certificate issuance constraints for all issuers.