d2bc5b5e3d
* Rename pki.mdx -> pki/index.mdx Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Split off quick-start document Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Split off considerations document Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Split off intermediate CA setup document Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Split off setup and usage document Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Consistent quick-start doc naming Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com> * Add table of contents to index Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>
135 lines
6.4 KiB
Plaintext
135 lines
6.4 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: PKI - Secrets Engines
|
|
description: The PKI secrets engine for Vault generates TLS certificates.
|
|
---
|
|
|
|
# PKI Secrets Engine - Considerations
|
|
|
|
To successfully deploy this secrets engine, there are a number of important
|
|
considerations to be aware of, as well as some preparatory steps that should be
|
|
undertaken. You should read all of these _before_ using this secrets engine or
|
|
generating the CA to use with this secrets engine.
|
|
|
|
## Be Careful with Root CAs
|
|
|
|
Vault storage is secure, but not as secure as a piece of paper in a bank vault.
|
|
It is, after all, networked software. If your root CA is hosted outside of
|
|
Vault, don't put it in Vault as well; instead, issue a shorter-lived
|
|
intermediate CA certificate and put this into Vault. This aligns with industry
|
|
best practices.
|
|
|
|
Since 0.4, the secrets engine supports generating self-signed root CAs and
|
|
creating and signing CSRs for intermediate CAs. In each instance, for security
|
|
reasons, the private key can _only_ be exported at generation time, and the
|
|
ability to do so is part of the command path (so it can be put into ACL
|
|
policies).
|
|
|
|
If you plan on using intermediate CAs with Vault, it is suggested that you let
|
|
Vault create CSRs and do not export the private key, then sign those with your
|
|
root CA (which may be a second mount of the `pki` secrets engine).
|
|
|
|
### Managed Keys
|
|
|
|
Since 1.10, Vault Enterprise can access private key material in a
|
|
[_managed key_](../enterprise/managed-keys). In this case Vault never sees the
|
|
private key, and the external KMS or HSM performs certificate signing operations.
|
|
Managed keys are configured by selecting the `kms` type when generating a root
|
|
or intermediate.
|
|
|
|
## One CA Certificate, One Secrets Engine
|
|
|
|
In order to vastly simplify both the configuration and codebase of the PKI
|
|
secrets engine, only one CA certificate is allowed per secrets engine. If you
|
|
want to issue certificates from multiple CAs, mount the PKI secrets engine at
|
|
multiple mount points with separate CA certificates in each.
|
|
|
|
This also provides a convenient method of switching to a new CA certificate
|
|
while keeping CRLs valid from the old CA certificate; simply mount a new secrets
|
|
engine and issue from there.
|
|
|
|
A common pattern is to have one mount act as your root CA and to use this CA
|
|
only to sign intermediate CA CSRs from other PKI secrets engines.
|
|
|
|
## Keep certificate lifetimes short, for CRL's sake
|
|
|
|
This secrets engine aligns with Vault's philosophy of short-lived secrets. As
|
|
such it is not expected that CRLs will grow large; the only place a private key
|
|
is ever returned is to the requesting client (this secrets engine does _not_
|
|
store generated private keys, except for CA certificates). In most cases, if the
|
|
key is lost, the certificate can simply be ignored, as it will expire shortly.
|
|
|
|
If a certificate must truly be revoked, the normal Vault revocation function can
|
|
be used; alternately a root token can be used to revoke the certificate using
|
|
the certificate's serial number. Any revocation action will cause the CRL to be
|
|
regenerated. When the CRL is regenerated, any expired certificates are removed
|
|
from the CRL (and any revoked, expired certificate are removed from secrets
|
|
engine storage).
|
|
|
|
This secrets engine does not support multiple CRL endpoints with sliding date
|
|
windows; often such mechanisms will have the transition point a few days apart,
|
|
but this gets into the expected realm of the actual certificate validity periods
|
|
issued from this secrets engine. A good rule of thumb for this secrets engine
|
|
would be to simply not issue certificates with a validity period greater than
|
|
your maximum comfortable CRL lifetime. Alternately, you can control CRL caching
|
|
behavior on the client to ensure that checks happen more often.
|
|
|
|
Often multiple endpoints are used in case a single CRL endpoint is down so that
|
|
clients don't have to figure out what to do with a lack of response. Run Vault in HA mode, and the CRL endpoint should be available even if a particular node
|
|
is down.
|
|
|
|
## You must configure issuing/CRL/OCSP information _in advance_
|
|
|
|
This secrets engine serves CRLs from a predictable location, but it is not
|
|
possible for the secrets engine to know where it is running. Therefore, you must
|
|
configure desired URLs for the issuing certificate, CRL distribution points, and
|
|
OCSP servers manually using the `config/urls` endpoint. It is supported to have
|
|
more than one of each of these by passing in the multiple URLs as a
|
|
comma-separated string parameter.
|
|
|
|
## Safe Minimums
|
|
|
|
Since its inception, this secrets engine has enforced SHA256 for signature
|
|
hashes rather than SHA1. As of 0.5.1, a minimum of 2048 bits for RSA keys is
|
|
also enforced. Software that can handle SHA256 signatures should also be able to
|
|
handle 2048-bit keys, and 1024-bit keys are considered unsafe and are disallowed
|
|
in the Internet PKI.
|
|
|
|
## Token Lifetimes and Revocation
|
|
|
|
When a token expires, it revokes all leases associated with it. This means that
|
|
long-lived CA certs need correspondingly long-lived tokens, something that is
|
|
easy to forget. Starting with 0.6, root and intermediate CA certs no longer have
|
|
associated leases, to prevent unintended revocation when not using a token with
|
|
a long enough lifetime. To revoke these certificates, use the `pki/revoke`
|
|
endpoint.
|
|
|
|
## Certificate Storage
|
|
|
|
Unlike many secrets engines which replicate their state to all clusters
|
|
in multi-cluster architectures, the PKI secrets engine stores leaf certificates
|
|
issued without `no_store` set to true local to the cluster that issued them.
|
|
This allows for both primary and secondary clusters' nodes to issue
|
|
certificates for greater scalability. As a result, these certificates
|
|
and any revocations are visible only on the issuing cluster.
|
|
|
|
## Telemetry
|
|
|
|
Beyond Vault's default telemetry around request processing, PKI exposes count and
|
|
duration metrics for the issue, sign, sign-verbatim, and revoke calls. The
|
|
metrics keys take the form `mount-path,operation,[failure]` with labels for namespace and role name.
|
|
|
|
## Learn
|
|
|
|
Refer to the [Build Your Own Certificate Authority (CA)](https://learn.hashicorp.com/vault/secrets-management/sm-pki-engine)
|
|
guide for a step-by-step tutorial.
|
|
|
|
Have a look at the [PKI Secrets Engine with Managed Keys](https://learn.hashicorp.com/tutorials/vault/managed-key-pki?in=vault/enterprise)
|
|
for more about how to use externally managed keys with PKI.
|
|
|
|
## API
|
|
|
|
The PKI secrets engine has a full HTTP API. Please see the
|
|
[PKI secrets engine API](/api-docs/secret/pki) for more
|
|
details.
|