Learn PKI - Vault PKI Engine (HashiCorp Vault)

#Introduction

In episode 11 you saw CFSSL, a toolkit that serves PKI through simple utilities and APIs. This episode brings a far more complete approach: HashiCorp Vault, a secret management tool that contains a PKI engine inside it. Rather than a PKI-specific tool, Vault stores many kinds of secrets — tokens, database credentials, and certificates — with one centralized access policy.

The strength of the Vault PKI engine lies in its usage pattern: you define roles, then request certificates via commands or APIs. Vault manages the CA keys, issues certificates, records every issuance, and provides CRL and OCSP. All transactions are recorded in the audit log.

This episode's roadmap: we mount the PKI engine, arrange the root and intermediate architecture, create roles, issue certificates, configure validity periods, manage CRL and OCSP, then integrate with step-ca and applications through consul-template and Vault Agent.

#PKI Engine Concepts in Vault

Vault treats a CA as a secrets engine at a specific path, usually pki for the root and pki_int for the intermediate. Each engine has its own private key, validity policy, and separate CRL. By separating paths, a single Vault instance can host several CAs at once.

Each engine has a series of endpoints for different tasks: creating CA keys, signing intermediates, issuing certificates, revoking certificates, and reading the CRL. Access to these endpoints is governed by ordinary Vault policies, so only certain parties may issue.

#Root and Intermediate Architecture

The same best practice from episode 2 still applies: the root CA is taken offline or held very strictly, while the intermediate serves day-to-day requests. In Vault, the root and intermediate live as two different engines on the same or separate instances.

#Creating the Root CA

The root is created with internal generation. Vault creates the root key and certificate while storing them.

vault secrets enable pki
vault secrets tune -max-lease-ttl=87600h pki

vault write -format=json pki/root/generate/internal \
  common_name="DevNull Root CA" \
  ttl=87600h

The root validity period is made very long, for example ten years, because the root is rarely rotated. The root key in the pki engine must be protected with strict access policy.

#Creating the Intermediate

The intermediate lives in a separate engine named pki_int. Its key is generated in that engine, then its CSR is signed by the root.

vault secrets enable -path=pki_int pki
vault secrets tune -max-lease-ttl=43800h pki_int

vault write -format=json pki_int/intermediate/generate/internal \
  common_name="DevNull Intermediate CA" \
  ttl=43800h > int.json

vault write -format=json pki/root/sign-intermediate \
  csr=@int.json > signed.json

vault write pki_int/intermediate/set-signed certificate=@signed.json

After this step, pki_int is ready to issue certificates as a legitimate CA, under the root's umbrella. This pattern keeps the root key minimally used.

#Role-Based Issuance

Vault does not accept arbitrary certificate requests. All issuance goes through roles that define allowed domains, key types, and maximum validity. This is the security key of the PKI engine.

#Creating a Role

vault write pki_int/roles/web-service \
  allowed_domains=internal.example.com \
  allow_subdomains=true \
  max_ttl=2160h \
  key_type=ec \
  key_bits=256

The web-service role only allows names under internal.example.com. Other names are rejected by Vault. max_ttl caps the longest validity period that can be requested.

#Requesting a Certificate

Issuance is done by writing to the issue endpoint followed by the role name.

vault write pki_int/issue/web-service \
  common_name=api.internal.example.com \
  ttl=2160h

vault write pki_int/issue/web-service returns the certificate, private key, and CA chain in a single response. Note that the private key is generated by Vault itself, so the application must store it carefully before use.

Besides issue, there is sign for signing CSRs that come from outside, and generate for creating the key and certificate together. Choose according to need: issue is most convenient for new applications, sign is more suitable when the key was already created elsewhere.

#Certificate Lifetime and Rotation

Certificate validity is determined by three layers: the engine limit, the role limit, and the requested value. Vault always takes the smallest value. With max_ttl on the role and ttl on the request, you can enforce policies such as a maximum certificate validity of 90 days.

Vault does not renew certificates automatically. Renewal happens when the application requests again via issue or when a client such as Vault Agent performs renewal. This is why integration with automation tools is so important.

#OCSP and CRL

Vault records every issued certificate and revokes certificates when asked. The CRL is available via a dedicated endpoint and is updated automatically according to the configured interval.

vault read pki_int/crl/pem

vault write pki_int/revoke serial_number=12:34:56:78

vault write pki_int/revoke revokes the certificate and lists it in the CRL. Vault also provides an OCSP responder so applications can check certificate status in real time. A revoked certificate cannot be reactivated.

#Integration with step-ca

step-ca and Vault are not rivals; they can be combined. A common scenario: Vault becomes the primary CA, while step-ca serves ACME requests in environments that need them. Through the step-kms plugin from HashiCorp, step-ca can store its CA keys in Vault Transit so the private key never leaves Vault.

The choice between the two depends on context. If your team already uses Vault for other secrets, its PKI engine is a natural step. If the main needs are ACME and SSH, step-ca is more direct. Both are equally capable, and understanding both makes you flexible.

#Integration with Applications

Issued certificates must reach the application securely. The two most common ways: consul-template and Vault Agent.

#consul-template

consul-template renders templates from values fetched from Vault, then writes the result to files. The certificate is renewed when its validity nears the end.

{{ with secret "pki_int/issue/web-service" "common_name=api.internal.example.com" }}
{{ .Data.certificate }}
{{ .Data.private_key }}
{{ end }}

This template requests a certificate via the web-service role, then writes the certificate and private key to the location you specify. When Vault indicates a renewal, consul-template rewrites the files and notifies the service.

#Vault Agent

Vault Agent works similarly without needing an external template. It fetches the certificate, writes to a sink, then renews automatically before expiry.

vault {
  address = "https://vault.internal:8200"
}
 
template {
  source      = "/etc/agent/cert.tpl"
  destination = "/etc/tls/server.crt"
}
 
template {
  source      = "/etc/agent/key.tpl"
  destination = "/etc/tls/server.key"
}

With this pattern, the application does not need to understand the Vault API at all. It only reads files in a certain directory, and those files are always fresh thanks to Vault Agent.

#Closing

Episode 12 introduced the Vault PKI engine as a centralized approach to certificate management. You mounted the engine, built the root and intermediate architecture, created roles for controlled issuance, configured validity periods, managed OCSP and CRL, combined it with step-ca, and connected applications via consul-template and Vault Agent.

Key takeaways:

• The Vault PKI engine treats a CA as a secrets path with centralized access policy.
• The root and intermediate architecture is implemented by separating the pki and pki_int engines.
• Roles restrict the domains, key types, and validity periods that can be requested.
• vault write pki_int/issue acts as the role-based issuance gateway.
• CRL and OCSP are managed automatically by Vault, complete with an audit log.
• consul-template and Vault Agent automate distribution and renewal to applications.

In episode 13 we discuss the most sensitive part: private keys. You will learn file-based security, passphrase-protected keys, HSM and PKCS#11 with YubiKey PIV and TPM, the step-ca HSM image, KMS such as AWS KMS and Azure Key Vault, and split knowledge. See you there!