PKI Secrets Engine

The PKI Secrets Engine in HashiCorp Vault dynamically issues and manages X.509 certificates for TLS and mutual TLS (mTLS) use cases. It automates private key generation, CSR submission, CA signing, and certificate retrieval—enforcing Vault’s authentication methods and ACL policies to authorize issuance.

Key Benefits of Vault PKI

Workloads can request certificates at runtime and discard them on shutdown, avoiding long-lived revocation lists.

Vault as an Intermediate CA

Vault typically functions as an intermediate CA, integrating seamlessly with your offline root CA. The flow is:

1. Vault generates an intermediate CSR.
2. You sign it with the offline root CA.
3. You import the signed intermediate certificate into Vault.
4. Vault issues end-entity certificates on behalf of your root.

Certificate Management Architecture

A typical deployment architecture:

1. Root CA (offline, long-lived)
2. Vault running the PKI Secrets Engine (intermediate CA)
3. Clients (VMs, containers, applications) that authenticate to Vault and request certificates

Clients receive their unique certificates and private keys securely at runtime.

Enabling the PKI Secrets Engine

Enable Vault’s PKI engine at the default or a custom path:

# Enable at default path "pki/"
vault secrets enable pki

# Or enable at custom path "hcvop_int/"
vault secrets enable -path=hcvop_int pki

Tuning the Maximum TTL

Set the maximum lease TTL to enforce certificate lifetimes:

# Default PKI: max TTL = 30 days
vault secrets tune -max-lease-ttl=720h pki

# Custom PKI at "hcvop_int/": max TTL = 1 year
vault secrets tune -max-lease-ttl=8760h hcvop_int

Generating and Signing an Intermediate CSR

1. Generate CSR in Vault (outputs JSON, extract CSR):

   vault write -format=json \
     hcvop_int/intermediate/generate/internal \
     common_name="hcvop.com Intermediate" \
     | jq -r '.data.csr' > pki_intermediate.csr
   

2. Sign CSR with your offline root CA and save as intermediate.cert.pem.

3. Import the signed certificate back into Vault:

   vault write hcvop_int/intermediate/set-signed \
     [email protected]
   

Configuring CA and CRL URLs

Clients fetch the issuer certificate and CRL via these URLs embedded in issued certs:

vault write pki/config/urls \
  issuing_certificates="https://vault.example.com:8200/v1/pki/ca" \
  crl_distribution_points="https://vault.example.com:8200/v1/pki/crl"

Defining PKI Roles

A role in Vault maps policies to certificate settings (allowed domains, TTLs, SANs).

Example Role Configurations

Creating a PKI Role

vault write pki/roles/web_dmz_role \
  allowed_domains=dmz.hcvop.com \
  allow_subdomains=true \
  allow_bare_domains=false \
  allow_glob_domains=false \
  max_ttl=720h \
  allow_localhost=true \
  organization=hcvop \
  country=US

Applications authenticate to Vault and request certificates based on their assigned role.

Issuing Certificates

Issue a certificate for a given role:

vault write pki/issue/web_dmz_role \
  common_name=dmzhcp01.dmz.hcvop.com \
  alt_names=portal.dmz.hcvop.com \
  max_ttl=720h

Response fields:

• certificate: TLS certificate (PEM)
• issuing_ca: CA certificate chain (Vault intermediate)
• private_key: Private key (returned only once)
• private_key_type: Key algorithm (e.g., rsa)
• serial_number: Unique cert serial number

Revoking Certificates

Revoke by serial number:

vault write pki/revoke \
  serial_number="4d:00:01:30:20:2c:5e:31:ba:a9:7b"

The response includes revocation time in Unix and RFC 3339 formats.

Cleaning Up the Certificate Store

Periodically tidy expired and revoked certificates:

vault write pki/tidy \
  tidy_cert_store=true \
  tidy_revoked_certs=true

Vault logs the tidy operation—monitor server logs for completion status.

References

• Vault PKI Secrets Engine
• Vault Authentication Methods
• X.509 Certificate Profile
• Managing Certificate Revocation List (CRL)