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

Add a little more information about PKI and replicated data sets to the PKI docs. (#15683) 

* Add a little more information about PKI and replicated data sets.

 - Add a TOC to the PKI considerations page
 - Merge in the existing certificate storage into a new Replicated DataSets
   section
 - Move the existing Cluster Scalability section from the api-docs into the
   considerations page.
This commit is contained in:
Steven Clark 2022-05-31 10:04:51 -04:00 committed by GitHub
parent 1331c2aa12
commit 69296e9edf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 81 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
website/content/api-docs/secret/pki.mdx
View File

@ -2791,30 +2791,7 @@ $ curl \
## Cluster Scalability
Most non-introspection operations in the PKI secrets engine require a write to
storage, and so are forwarded to the cluster's active node for execution.
This table outlines which operations can be executed on performance standbys
and thus scale horizontally.
| Path | Operations |
| --------------------------- | -------------------- |
| ca[/pem] | Read |
| cert/<em>serial-number</em> | Read |
| cert/ca_chain | Read |
| config/crl | Read |
| certs | List |
| ca_chain | Read |
| crl[/pem] | Read |
| crl/pem | Read |
| issue | Update <sup>\*</sup> |
| revoked/\* | Read, List |
| sign | Update <sup>\*</sup> |
| sign-verbatim | Update <sup>\*</sup> |
\* Only if the corresponding role has `no_store` set to true and `generate_lease`
set to false. If `generate_lease` is true the lease creation will be forwarded to
the active node; if `no_store` is false the entire request will be forwarded to
the active node.
See [PKI Cluster Scalability](/docs/secrets/pki/considerations#cluster-scalability) in the considerations page.
## Managed Keys

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

@ -11,6 +11,28 @@ 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.
## Table of Contents
- [Be Careful with Root CAs](#be-careful-with-root-cas)
- [Managed Keys](#managed-keys)
- [One CA Certificate, One Secrets Engine](#one-ca-certificate-one-secrets-engine)
- [Always Configure a Default Issuer](#always-configure-a-default-issuer)
- [Key Types Matter](#key-types-matter)
- [Use a CA Hierarchy](#use-a-ca-hierarchy)
- [Keep certificate lifetimes short, for CRL's sake](#keep-certificate-lifetimes-short-for-crls-sake)
- [NotAfter Behavior on Leaf Certificates](#notafter-behavior-on-leaf-certificates)
- [Cluster Performance and Quantity of Leaf Certificates](#cluster-performance-and-quantity-of-leaf-certificates)
- [You must configure issuing/CRL/OCSP information _in advance_](#you-must-configure-issuingcrlocsp-information-_in-advance_)
- [Automate Leaf Certificate Renewal](#automate-leaf-certificate-renewal)
- [Safe Minimums](#safe-minimums)
- [Token Lifetimes and Revocation](#token-lifetimes-and-revocation)
- [Safe Usage of Roles](#safe-usage-of-roles)
- [Telemetry](#telemetry)
- [Auditing](#auditing)
- [Role-Based Access](#role-based-access)
- [Replicated DataSets](#replicated-datasets)
- [Cluster Scalability](#cluster-scalability)
## Be Careful with Root CAs
Vault storage is secure, but not as secure as a piece of paper in a bank vault.
@ -271,7 +293,7 @@ be used sparingly, if at all).
generally recommend to set `no_store` to `true` (defaults to `false`).
This prevents revocation but allows higher throughput as Vault no longer
needs to store every issued certificate. This is discussed more in the
[Certificate Storage](#certificate-storage) section below.
[Replicated Datasets](#replicated-datasets) section below.
- Do not use roles with root certificates (`issuer_ref`). Root certificates
should generally only issue intermediates (see the section on [CA hierarchy
above](#use-a-ca-hierarchy)), which doesn't rely on roles.
@ -279,18 +301,6 @@ be used sparingly, if at all).
for all purposes. Generally the default values are useful for client and
server TLS authentication.
## 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 with `no_store` set to `false` 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. This additionally
means each cluster has its own set of CRLs, distinct from other clusters. These
CRLs should either be unified into a single CRL for distribution from a single
URI, or server operators should know to fetch all CRLs from all clusters.
## Telemetry
Beyond Vault's default telemetry around request processing, PKI exposes count and
@ -434,6 +444,63 @@ For these personas, we suggest the following ACLs, in condensed, tabular form:
| `/root/rotate/+` | Write | Yes | | | | |
| `/root/replace` | Write | Yes | | | | |
## Replicated DataSets
When operating with [Performance Secondary](/docs/enterprise/replication#architecture)
clusters, certain data-sets are maintained across all clusters, while others for performance
and scalability reasons are kept within a given cluster.
The following table breaks down by data type what data sets will cross the cluster boundaries.
For data-types that do not cross a cluster boundary, read requests for that data will need to be
sent to the appropriate cluster that the data was generated on.
| Data Set | Replicated Across Clusters |
|--------------------------|----------------------------|
| Issuers & Keys | Yes |
| Roles | Yes |
| CRL Config | Yes |
| URL Config | Yes |
| Issuer Config | Yes |
| Key Config | Yes |
| CRL | No |
| Revoked Certificates | No |
| Leaf/Issued Certificates | No |
The main effect is that within the PKI secrets engine leaf certificates
issued with `no_store` set to `false` are stored local to the cluster that issued them.
This allows for both primary and [Performance Secondary](/docs/enterprise/replication#architecture)
clusters' active node to issue certificates for greater scalability. As a
result, these certificates and any revocations are visible only on the issuing
cluster. This additionally means each cluster has its own set of CRLs, distinct
from other clusters. These CRLs should either be unified into a single CRL for
distribution from a single URI, or server operators should know to fetch all
CRLs from all clusters.
## Cluster Scalability
Most non-introspection operations in the PKI secrets engine require a write to
storage, and so are forwarded to the cluster's active node for execution.
This table outlines which operations can be executed on performance standby nodes
and thus scale horizontally across all nodes within a cluster.
| Path | Operations |
|-------------------------------|----------------------|
| ca[/pem] | Read |
| cert/<em>serial-number</em> | Read |
| cert/ca_chain | Read |
| config/crl | Read |
| certs | List |
| ca_chain | Read |
| crl[/pem] | Read |
| issue | Update <sup>\*</sup> |
| revoke/<em>serial-number</em> | Read |
| sign | Update <sup>\*</sup> |
| sign-verbatim | Update <sup>\*</sup> |
\* Only if the corresponding role has `no_store` set to true and `generate_lease`
set to false. If `generate_lease` is true the lease creation will be forwarded to
the active node; if `no_store` is false the entire request will be forwarded to
the active node.
## Tutorial