luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

Add more PKI usage best practices to documentation (#15562) 

* Add note about cross-cluster CRL URIs

As suggested by Ricardo Oliveira, thanks!

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Add note that short TTLs are relative to quantity

As suggested by Ricardo Oliveira, thanks!

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Add note to make sure default is configured

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Add note about automating certificate renewal

As suggested by Ricardo Oliveira, thanks!

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>
This commit is contained in:
Alexander Scheel 2022-05-23 12:00:24 -04:00 committed by GitHub
parent a90b29754e
commit 36c981bfe4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 50 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
website/content/docs/secrets/pki/considerations.mdx
View File

@ -72,6 +72,16 @@ by the HSM and one backed by Vault -- can satisfy both use cases. Operators
can make roles setting maximum TTLs for each issuer and consumers of the
mount can decide which to use.
### Always Configure a Default Issuer
For backwards compatibility, [the default issuer](/api-docs/secret/pki#read-issuers-configuration)
is used to service PKI endpoints without an explicit issuer (either via path
selection or role-based selection). When certificates are revoked and their
issuer is no longer part of this PKI mount, Vault places them on the default
issuer's CRL. This means maintaining a default issuer is important for both
backwards compatibility for issuing certificates and for ensuring revoked
certificates land on a CRL.
## Use a CA Hierarchy
It is generally recommended to use a hierarchical CA setup, with a root
@ -154,6 +164,30 @@ range of 30 to 90 days), and the [rotation strategies discussed in other
sections](/docs/secrets/pki/rotation-primitives), this should keep the
CRLs adequately small.
### Cluster Performance and Quantity of Leaf Certificates
As mentioned above, keeping TTLs short (or using `no_store=true`, preventing
revocation) and avoiding leases is important for a healthy cluster. However
it is important to note this is a scale problem: 10-1000 long-lived, stored
certificates are probably fine, but 50k-100k become a problem and 500k+
stored, unexpired certificates can negatively impact even large Vault
clusters--even with short TTLs!
However, once these certificates are expired, a [tidy operation](/api-docs/secret/pki#tidy)
will clean up CRLs and Vault cluster storage.
Note that organizational risk assessments for certificate compromise might
mean certain certificate types should always be issued with `no_store=false`;
even short-lived broad wildcard certificates (say, `*.example.com`) might be
important enough to have precise control over revocation. However, an internal
service with a well-scoped certificate (say, `service.example.com`) might be
of low enough risk to issue a 90-day TTL with `no_store=true`, preventing
the need for revocation in the unlikely case of compromise.
Having a shorter TTL decreases the likelihood of needing to revoke a cert
(but cannot prevent it entirely) and decrease the impact of any such
compromise.
## You must configure issuing/CRL/OCSP information _in advance_
This secrets engine serves CRLs from a predictable location, but it is not
@ -163,6 +197,22 @@ 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.
~> Note: when using Vault Enterprise's Performance Replication features with a
PKI Secrets Engine mount, each cluster will have its own CRL; this means
each cluster's unique CRL address should be included in the [AIA
information](https://datatracker.ietf.org/doc/html/rfc5280#section-5.2.7)
field separately, or the CRLs should be consolidated and served outside of
Vault.
## Automate Leaf Certificate Renewal
As much as possible, for managing certificates for services at scale, it is
best to automate renewal of certificates. Vault agent [has support for
automatically renewing requested certificates](/docs/agent/template#certificates)
based on the `validTo` field. Other solutions might involve using
[cert-manager](https://cert-manager.io/) in Kubernetes or OpenShift, backed
by the Vault CA.
## Safe Minimums
Since its inception, this secrets engine has enforced SHA256 for signature