ca

Documentation

Overview

Package ca implements the KMS's built-in certificate authority. It mints the short-lived client certificates that machine clients present for mTLS authentication (plan-namespaces.md §7).

The package is deliberately self-contained: it depends only on the standard library and knows nothing about the KMS's domain types, storage, or wire protocol. Persistence, KEK-wrapping of the CA private key, bootstrap at unseal, and mapping a verified peer certificate to a stored identity are all the caller's responsibility. This package only holds the X.509 material and signs.

Keys are Ed25519. The CA certificate is long-lived and self-signed; issued client certificates are short-lived leaves carrying the identity name in both the CommonName and a URI SAN of the form "kms://identity/<name>". The URI SAN is authoritative for identity mapping; the CommonName is cosmetic.

Index

• Constants
• Variables
• func IdentityFromCert(cert *x509.Certificate) (string, error)
• type CA
  • func Generate() (ca *CA, certPEM, keyPEM []byte, err error)
  • func Load(certPEM, keyPEM []byte) (*CA, error)
  • func (c *CA) CertPEM() []byte
  • func (c *CA) CertPool() *x509.CertPool
  • func (c *CA) Certificate() *x509.Certificate
  • func (c *CA) IssueClientCert(identityName string, ttl time.Duration) (IssuedCert, error)
• type IssuedCert

Constants

const (

	// DefaultCertTTL is used by IssueClientCert when a non-positive ttl is
	// passed. It matches the plan's 90-day default.
	DefaultCertTTL = 90 * 24 * time.Hour
)

Variables

var ErrNoIdentitySAN = errors.New("certificate has no unique kms identity URI SAN")

ErrNoIdentitySAN is returned by IdentityFromCert when the certificate does not carry exactly one "kms://identity/<name>" URI SAN.

Functions

func IdentityFromCert

func IdentityFromCert(cert *x509.Certificate) (string, error)

IdentityFromCert extracts the identity name from a verified peer certificate. It requires exactly one URI SAN of the form "kms://identity/<name>" and returns its <name>. The CommonName is intentionally NOT used as a fallback: the URI SAN is the single authoritative identity claim, so a certificate lacking it (or carrying more than one) is rejected with ErrNoIdentitySAN.

Types

type CA

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

CA holds the built-in certificate authority: its certificate and the private key used to sign client certificates.

func Generate

func Generate() (ca *CA, certPEM, keyPEM []byte, err error)

Generate creates a fresh built-in CA: a new Ed25519 key pair and a self-signed, long-lived CA certificate. It returns the ready CA plus the PEM-encoded certificate and PKCS#8 private key so the caller can persist them (the private key must be stored KEK-wrapped, never in plaintext). The returned keyPEM is the only copy the caller will get; the CA retains the key in memory for signing.

func Load

func Load(certPEM, keyPEM []byte) (*CA, error)

Load reconstructs a CA from its persisted PEM material. The caller is responsible for having decrypted keyPEM (storage keeps it KEK-wrapped).

func (*CA) CertPEM

func (c *CA) CertPEM() []byte

CertPEM returns the PEM-encoded CA certificate (public; safe to serve).

func (*CA) CertPool

func (c *CA) CertPool() *x509.CertPool

CertPool returns a certificate pool containing only this CA, suitable for tls.Config.ClientCAs. Callers that also honor an operator-supplied client CA should AddCert this CA's Certificate() to their own pool instead.

func (*CA) Certificate

func (c *CA) Certificate() *x509.Certificate

Certificate returns the parsed CA certificate.

func (*CA) IssueClientCert

func (c *CA) IssueClientCert(identityName string, ttl time.Duration) (IssuedCert, error)

IssueClientCert mints a new client certificate for identityName, valid for ttl (DefaultCertTTL when ttl <= 0). The certificate carries identityName in its CommonName and a "kms://identity/<name>" URI SAN, and is marked for ExtKeyUsageClientAuth. A fresh Ed25519 key pair is generated per call; its private key is returned in the result and not retained.

type IssuedCert

type IssuedCert struct {
	CertPEM           []byte    // PEM-encoded leaf certificate
	KeyPEM            []byte    // PEM-encoded PKCS#8 Ed25519 private key
	Serial            string    // lowercase hex of the certificate serial number
	FingerprintSHA256 string    // lowercase hex of SHA-256 over the leaf DER
	NotAfter          time.Time // expiry (UTC, second precision)
}

IssuedCert is the result of minting one client certificate. The private key is generated per issuance and returned exactly once; it is never retained by the CA.