Backport of Docs improvements for Managed Keys into release/1.10.x (#…

…14906) * backport of commit 81b3f4f * backport of commit 952c9ba Co-authored-by: Scott G. Miller <[email protected]>
hashicorp · Apr 5, 2022 · 4e98cfc · 4e98cfc
1 parent ac3bd1e
commit 4e98cfc
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 4 deletions.
diff --git a/website/content/docs/enterprise/managed-keys.mdx b/website/content/docs/enterprise/managed-keys.mdx
@@ -7,13 +7,26 @@ description: >-
 
 # Managed Keys
 
+
 Within certain environments, customers want to leverage key management systems
 external to Vault, when handling, storing, and interacting with
 private key material, or are required to do so by standards requirements.
 
-To satisfy these requirements, Vault has a centralized configuration that
-different secrets engines can plug into, allowing them to delegate these
-operations to a trusted external KMS.
+To satisfy these requirements, Vault has a centralized abstraction called
+*Managed Keys* that different secrets engines can plug into, allowing them to 
+delegate these operations to a trusted external KMS.
+
+Minimally, a managed key consists of a named managed key entry managed by the
+[`sys/managed-key`](../../api-docs/system/managed-keys) API.  Besides a name,
+there are backend specific configurations to access the key in question.
+
+For PKCS#11 (HSM) backed managed keys, the managed key configuration must
+reference a [kms library stanza](../configuration/kms-library) which points
+to a PKCS#11 access library on the host machine.
+
+Note that a configured, named managed key corresponds to a single key within
+a backend.  More than one managed key can be configured targetting a single
+backend by creating multiple managed keys with the API.
 
 ## Namespace support
 
@@ -27,12 +40,14 @@ Managed Keys were developed to support different types of external backends.
 Currently, supported backends are PKCS#11 and AWS KMS.
 Support for additional integrations may be added in the future.
 
-## Plugin Support
+## Secret and Auth Engine Support
 
 The [PKI Secrets Engine](/api/secret/pki#managed-keys) has been integrated
 with Managed Keys to offer certificate generation, both root and intermediary
 PKI paths, leveraging private keys from an external trusted KMS.
 
+More engines may leverage managed keys in the future.
+
 ## API
 
 Managed Keys can be managed over the HTTP API. Please see

diff --git a/website/content/docs/secrets/pki.mdx b/website/content/docs/secrets/pki.mdx
@@ -144,6 +144,14 @@ 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