PKI secrets engine

Vault's pki secret engine is a full-fledged certificate authority. It can be a root CA, an intermediate CA, or a leaf-only issuer that delegates to one of those. It supports ACME (RFC 8555), CRL/OCSP, certificate counting, and templated subject distinguished names. Source: builtin/logical/pki/ and builtin/logical/pkiext/ (extensions split into a separate package to keep the main pkg small).

Purpose

Issue, revoke, and rotate X.509 certificates with policy-driven roles:

• Operators define a role (pki/roles/web-server) with allowed common names, key types, key bits, max TTLs, and SAN constraints.
• Apps with the right policy call pki/issue/web-server and get a fresh certificate.
• Vault tracks the issued cert for revocation; CRL and OCSP responders are auto-generated.

Roles, issuers, and keys

The schema separates issuers (CA cert + key references), keys (private keys, possibly multiple), and roles (issuance templates):

| Path | What | | ---------------------------------------- | ------------------------------------------------------- | ---- | ----------------------------------- | | pki/keys/<key-id> | A private key. May be local or managed_key-backed. | | pki/issuer/<issuer-id> | A CA cert + key reference; signs CRLs and certificates. | | pki/roles/<role> | Allowed CN, SANs, TTL, key type, extensions. | | pki/issue/<role> | Issue a fresh cert. | | pki/sign/<role> | Sign a CSR. | | pki/sign-verbatim | Sign without role-based restrictions (sudo). | | pki/revoke | Revoke by serial number. | | pki/cert/<serial> | Read cert by serial. | | pki/crl/rotate, pki/crl/rotate-delta | Force CRL regeneration. | | pki/issuer/<id>/json | der | pem | Export issuer in different formats. | | pki/config/cluster | Endpoints used for Issuer URL extension. |

Issuance flow

sequenceDiagram
    participant App
    participant Vault
    participant Role
    participant Issuer
    participant Key
    App->>Vault: POST pki/issue/<role> { common_name, ttl }
    Vault->>Role: validate against allowed_domains/cn/ttl/usages
    Vault->>Key: load private key for issuer
    Vault->>Issuer: sign cert with Key, set SerialNumber, AIA, CRL DPs
    Vault->>Vault: persist serial under pki/certs/<serial>
    Vault-->>App: PEM bundle (cert, ca, chain) and private key

CRL and OCSP

Vault generates a CRL on every revoke (builtin/logical/pki/crl_util.go) and serves it at pki/crl. It can also publish a delta CRL to keep the main CRL small. OCSP requests are handled at pki/ocsp using sdk/helper/ocsp/ and the responder logic in builtin/logical/pki/ocsp.go.

ACME

The pki engine implements RFC 8555 (ACME) so that ACME clients (Caddy, certbot, lego, …) can request certs from Vault as if from Let's Encrypt. Configuration is per-issuer with pki/issuer/<id>/acme/.... Implementation lives across many path_acme*.go files. The pkiext package exists to share types between pki and pkiext without import cycles.

acme_billing_system_view.go (in vault/) is how ACME issuance tallies into client/billing counts.

Certificate counting

vault/cert_count/ integrates with the activity log to count unique certificate subjects, which Vault Enterprise uses for billing. The cert-count subsystem is also surfaced in metrics.

CLI

A small set of helpers live in command/pki*.go:

• vault pki health-check — runs a battery of sanity checks against a pki mount.
• vault pki issue — wrapper for pki/issue/....
• vault pki list-intermediates — discover issuers in a chain.
• vault pki reissue — reissue with similar parameters.
• vault pki verify-sign — verify chain signatures.

These exist because pki is operational enough to deserve verb commands.

Templating in roles

Roles support identity templating — e.g. allowed_common_names="{{identity.entity.name}}" — so policies + roles together can grant a token only the ability to issue certs for itself. See helper/identity/identitytpl.go.

Integration points

• Stores certs in its own mount's storage view.
• Uses sdk/helper/certutil/ for parsing, generation, marshalling.
• Integrates with managed-key wrappers for HSM-backed CA keys.
• Activity log gathers cert-issuance counts via vault/cert_count/.

Entry points for modification

• New role parameter: extend roleEntry in builtin/logical/pki/path_roles.go.
• New issuer field: extend issuerEntry in builtin/logical/pki/issuing/.
• ACME flow tweaks: path_acme_*.go in builtin/logical/pki/.
• Managed-key support: see builtin/logical/pki/path_keys.go and the managed_key constants.