PKI secrets engine
Overview
The Public Key Infrastructure (PKI) secrets engine generates X.509 certificates. This secrets engine improves the enterprise’s PKI management by allowing services to obtain certificates without going through the usual manual processes of generating a private key and Certificate Signing Request (CSR), submitting them to a Certificate Authority (CA), and waiting for the verification and signing processes to be completed. Vault's built-in authentication and authorization mechanisms provide the necessary verification functionality.
The need for revocations is reduced by keeping time-to-live (TTL) values relatively short, which keeps the Certificate Revocation List (CRL) concise and helps the secrets engine scale to accommodate large workloads. This allows each instance of a running application to have a unique certificate, eliminating sharing and the associated challenges of revocation and rotation.
In addition, this secrets engine allows for ephemeral certificates by enabling automated rotation and allowing revocation to mostly be forgone. Certificates can be fetched and stored in memory upon application startup and discarded upon shutdown, without ever being written to disk.
Design considerations
Before deploying the PKI secrets engine, several important considerations must be taken into account, along with preparatory steps that should be undertaken. HashiCorp has published a set of design considerations, which can be found here. It is highly recommended to review all of these before using the secrets engine or generating the certificate authority (CA) associated with it.
Patterns: Offline Root CA vs Vault Root CA
Integrating with Offline Root CAs
Some use cases require that the root of trust be anchored within an existing company Root CA outside of Vault. For example, often the root CA has key protection controls that require the CA and its key pair to be offline, which is referred to as an offline root CA. Vault intermediate CAs can be integrated with existing company root or intermediate CAs.
- One benefit of this design pattern is that the organization root is likely to be present in application trust stores already. Both external intermediate CA and Vault intermediate CA need to be added to complete the chain of trust. Clients will benefit from rapid certificate issuance using Vault’s API and authentication framework.
- If integrating with external CAs, there may be additional security requirements placed on your overall Vault deployment.
Generally there are two patterns for integrating with existing CA's depending on where in the trust chain this integration happens: the root CA outside Vault or multiple CA's outside Vault. These are shown in the diagram below.
The workflow for external CA integration is as follows.
1. If creating a new CA in Vault: Use the generate intermediate endpoint to create the desired type of key pair (RSA, ed25519 or EC) and the CSR. In the snippet below, we have specified the key type to be internal; therefore, the private key is not returned.
Mount secrets engine, generate keys and CSR
vault secrets enable -path=inter_ca_v1 pki
vault write -format=json inter_ca_v1/intermediate/generate/internal \
common_name=dev.hashidemos.io | jq -r .data.csr > inter_ca_v1-csr.pem
2. Sign the CSR using the existing parent CA. These steps vary depending on the existing PKI in use and your organizational policies.
3. Use the set signed intermediate endpoint to associate the signed intermediate certificate with the secrets engine. Vault will recognize that the public key of the imported certificate matches the existing key material generated in step 1. We are assuming that the signed certificate was saved to the file: inter_ca_v1.cert.pem.
Use set signed intermediate to associate the CSR
vault write inter_ca_v1/intermediate/set-signed certificate=@./inter_ca_v1.cert.pem
4. Display the CA certificate to validate that all the fields are correct.
curl \-s "$VAULT\_ADDR/v1/inter\_ca\_v1/ca/pem" \\
| openssl x509 \-text \-noout
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
21:81:69:e1:5c:c2:f9:5a:04:2f:66:b1:89:ad:2f:d4:8b:0a:75:62
Signature Algorithm: sha256WithRSAEncryption
Issuer: CN=hashidemos.io
Validity
Not Before: Dec 14 03:16:12 2020 GMT
Not After : Dec 10 02:16:12 2021 GMT
Subject: CN=dev.hashidemos.io
...
Managing of Root CA within Vault
While it is recommended to use an offline root certificate authority (CA) when an organization has an existing external PKI infrastructure to handle offline root CA signing, this is not always feasible for all organizations. In such cases, it is possible to create and manage a root CA within Vault.
- One benefit of this design pattern is that the organization can leverage Vault's capabilities to manage the lifecycle of the Root CA. The private keys are also secured within Vault.
- However, the organization will still need to establish an appropriate process to disseminate the root CA to the application trust stores, ensuring that the Vault root CA is trusted within the organization.
Patterns: Managing intermediate CA
An intermediate CA is an authority that has its certificate signed by a parent CA. It follows the X.509 standards in defining the public key certificate formats and cryptographically signs other sub-CA certificates, and generates leaf certificates. When used for the latter, an intermediate CA is also an issuing CA. This section covers patterns for managing intermediate CAs with the Vault PKI secrets engine.
CA Hierarchy Design Considerations
How many levels of intermediates are necessary?
- Things to consider making this decision if not a prescriptive opinion on layer numbers.
- Topology and subordinate CA roles in Vault.
- Cross-signing for two intermediates, failover for the root of trust, and related topics.
- Root CA as the issuing CA.
A CA hierarchy entails having a root CA and one or more levels of intermediate CAs. We review some of these design patterns below, starting with all CAs being inside Vault and also integrating with existing CAs outside of Vault. As a general rule, it is recommended to have two or more CA levels for enhanced security.
Two CA levels: For simple use cases, having the root CA and one level of intermediate CA is sufficient. In this case, the intermediate CA also becomes an issuing CA since it can generate leaf certificates. Generally, there are multiple issuing CAs - each corresponding to a project, line of business (LOB), or other defined purpose.
Three CA levels: For large organizations, two CA levels can be challenging to scale, since each issuing CA must be configured correctly to enforce organizational security policies. Adding another layer of intermediate CA allows for better flexibility.
With this approach, one or more intermediate policy CAs can be introduced to allow per-organization central security teams to configure X.509 policies such as basic constraints, key usage, and extended key usage. Another important configuration is the path length which enforces the CA hierarchy depth of valid certificate paths. We recommend that security policies be established for CA path length and enforced via CA configuration.
These approaches are shown in the example below; each CA is a new instance of the PKI secrets engine mounted on a different path. As shown in the next section, often the root CA, and sometimes the intermediate policy CA, reside outside of Vault in an existing PKI system.
Issuing from a root CA: In this design, there is a single self-signed CA which is both the root and the issuing CA. While we do not recommend this pattern for production use, Vault does support it. Similar to intermediate CAs, one or more roles can be defined under the root CA for certificate issuance. This pattern may be used for simple use cases that are limited in scope, such as a development environment for a single project.
As a best practice, root and issuing CAs should have different security policies which cannot be implemented in this design. Unlike a tiered approach where issuing CAs are limited to administrative boundaries, the blast radius of a private key compromise event with this pattern is greater. Therefore when promoting to UAT, we recommend using one of the tiered approaches discussed earlier.
Other designs may include additional CA levels to allow for further separation of security controls and administrative tasks. Note that each additional level of CA will introduce more administrative complexity.
CA Hierarchy Design Recommendations
Root CA usage: We recommend limiting the root CA for only signing intermediate CSRs. Following this recommendation minimizes the chance of the root CA private key being exposed.
- If using Vault as the Root CA, when possible, the CA type should be kms or internal - this means that the private key is never revealed or exported. This setting also implies that during CA succession, the private key must be replaced with the new CA.
Security of the CA hierarchy: A compromise within the CA chain can risk compromising the entire chain of trust. Vault provides multiple ways to ensure the security of the CA hierarchy:
- Access to configure the root and intermediate CAs should be controlled via Vault ACL policies.
- The root CA and first levels of intermediate CAs may be placed in a Vault namespace separate from issuing CAs. This ensures a degree of isolation from the issuing or LOB CAs used by applications.
- Consider applying Vault Enterprise Control Groups for major lifecycle milestone operations such as Set Signed Intermediate, Generate Root, Generate Intermediate, and Sign Intermediate to mitigate potentially destructive operations.
Multiple issuing CAs: Issuing CAs should serve their own functional domain; there may therefore be many of them present within an organization based on administrative boundaries such as lines of business. This limits the blast radius of the affected chains of trust in case of compromise or misconfiguration. Vault has a range of CA configuration options to customize each CA with a precise security policy.