Add documentation for Managed Keys (#13856)
* Add documentation for Managed Keys - Add concept, sys/api and pki updates related to managed keys * Review feedback - Reworked quite a bit of the existing documentation based on feedback and a re-reading - Moved the managed keys out of the concepts section and into the enterprise section * Address broken links and a few grammar tweaks
This commit is contained in:
Steven Clark
GitHub
parent
ba74accfcf
commit
73f4c075e5
@ -214,8 +214,7 @@ func (c *SecretsEnableCommand) Flags() *FlagSets {
|
||||
Name: flagNameAllowedManagedKeys,
|
||||
Target: &c.flagAllowedManagedKeys,
|
||||
Usage: "Managed key name(s) that the mount in question is allowed to access. " +
|
||||
"Note that multiple keys may be specified either by providing the key names " +
|
||||
"as a comma separated string or by providing this option multiple times, " +
|
||||
"Note that multiple keys may be specified by providing this option multiple times, " +
|
||||
"each time with 1 key.",
|
||||
})
|
||||
|
||||
|
||||
@ -142,8 +142,7 @@ func (c *SecretsTuneCommand) Flags() *FlagSets {
|
||||
Name: flagNameAllowedManagedKeys,
|
||||
Target: &c.flagAllowedManagedKeys,
|
||||
Usage: "Managed key name(s) that the mount in question is allowed to access. " +
|
||||
"Note that multiple keys may be specified either by providing the key names " +
|
||||
"as a comma separated string or by providing this option multiple times, " +
|
||||
"Note that multiple keys may be specified by providing this option multiple times, " +
|
||||
"each time with 1 key.",
|
||||
})
|
||||
|
||||
|
||||
@ -43,6 +43,7 @@ update your API calls accordingly.
|
||||
- [Sign Certificate](#sign-certificate)
|
||||
- [Sign Verbatim](#sign-verbatim)
|
||||
- [Tidy](#tidy)
|
||||
- [Managed Key](#managed-keys) (Enterprise Only)
|
||||
|
||||
## Read CA Certificate
|
||||
|
||||
@ -455,6 +456,9 @@ as a root, and for many other CAs, the various parameters on the final
|
||||
certificate are set at signing time and may or may not honor the parameters set
|
||||
here. _This will overwrite any previously existing CA private key._
|
||||
|
||||
Note that this API supports [Managed Keys](/docs/enterprise/managed-keys),
|
||||
additional details are available [below](#managed-keys) in a dedicated section.
|
||||
|
||||
This is mostly meant as a helper function, and not all possible parameters that
|
||||
can be set in a CSR are supported.
|
||||
|
||||
@ -467,7 +471,7 @@ can be set in a CSR are supported.
|
||||
- `type` `(string: <required>)` – Specifies the type of the intermediate to
|
||||
create. If `exported`, the private key will be returned in the response; if
|
||||
`internal` the private key will not be returned and _cannot be retrieved
|
||||
later_. This is part of the request URL.
|
||||
later_. `kms` is also supported [see below](#managed-keys). This is part of the request URL.
|
||||
|
||||
- `common_name` `(string: <required>)` – Specifies the requested CN for the
|
||||
certificate.
|
||||
@ -542,6 +546,14 @@ can be set in a CSR are supported.
|
||||
Otherwise Vault will generate a random serial for you. If you want more than
|
||||
one, specify alternative names in the alt_names map using OID 2.5.4.5.
|
||||
|
||||
### Managed Keys Parameters
|
||||
See [Managed Keys](#managed-keys) for additional details on this feature, if
|
||||
`type` was set to `kms`. One of the following parameters must be set
|
||||
|
||||
- `managed_key_name` `(string: "")` – The managed key's configured name.
|
||||
|
||||
- `managed_key_id` `(string: "")` – The managed key's UUID.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
@ -1073,6 +1085,9 @@ As with other issued certificates, Vault will automatically revoke the
|
||||
generated root at the end of its lease period; the CA certificate will sign its
|
||||
own CRL.
|
||||
|
||||
Note that this API supports [Managed Keys](/docs/enterprise/managed-keys),
|
||||
additional details are available [below](#managed-keys) in a dedicated section.
|
||||
|
||||
As of Vault 0.8.1, if a CA cert/key already exists, this function will not
|
||||
overwrite it; it must be deleted first. Previous versions of Vault would
|
||||
overwrite the existing cert/key with new values.
|
||||
@ -1086,7 +1101,8 @@ overwrite the existing cert/key with new values.
|
||||
- `type` `(string: <required>)` – Specifies the type of the root to
|
||||
create. If `exported`, the private key will be returned in the response; if
|
||||
`internal` the private key will not be returned and _cannot be retrieved
|
||||
later_. This is part of the request URL.
|
||||
later_. `kms` is also supported [see below](#managed-keys). This is part of the
|
||||
request URL.
|
||||
|
||||
- `common_name` `(string: <required>)` – Specifies the requested CN for the
|
||||
certificate.
|
||||
@ -1177,6 +1193,14 @@ overwrite the existing cert/key with new values.
|
||||
Otherwise Vault will generate a random serial for you. If you want more than
|
||||
one, specify alternative names in the alt_names map using OID 2.5.4.5.
|
||||
|
||||
### Managed Keys Parameters
|
||||
See [Managed Keys](#managed-keys) for additional details on this feature, if
|
||||
`type` was set to `kms`. One of the following parameters must be set
|
||||
|
||||
- `managed_key_name` `(string: "")` – The managed key's configured name.
|
||||
|
||||
- `managed_key_id` `(string: "")` – The managed key's UUID.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
@ -1211,6 +1235,8 @@ $ curl \
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Delete Root
|
||||
|
||||
This endpoint deletes the current CA key (the old CA certificate will still be
|
||||
@ -1720,3 +1746,25 @@ and thus scale horizontally.
|
||||
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.
|
||||
|
||||
# Managed Keys
|
||||
|
||||
~> Note: Managed keys are an Enterprise only feature.
|
||||
|
||||
The [Generate Root](#generate-root) and [Generate Intermediate](#generate-intermediate)
|
||||
API calls can leverage the Managed Keys feature, delegating operations that
|
||||
require private key material to an external system.
|
||||
|
||||
To leverage a Managed Key, assuming it has already been configured, set the type
|
||||
parameter to `kms` within either, [Generate Root](#generate-root) or
|
||||
[Generate Intermediate](#generate-intermediate) APIs, and one of either
|
||||
`managed_key_name` or `managed_key_id` parameters specifying a Managed Key to use.
|
||||
As with the `internal` type for those APIs, if the type parameter is set to `kms`,
|
||||
there is no way to read/fetch the private key.
|
||||
|
||||
The API call will fail if the specified Managed Key is not properly configured or
|
||||
arguments detailing private key attributes are specified such as `key_type` or
|
||||
`key_bits`.
|
||||
|
||||
Once either of the certificate APIs have successfully executed, all other PKI
|
||||
operations behave the same, with no other special configuration or parameters required.
|
||||
|
||||
201
website/content/api-docs/system/managed-keys.mdx
Normal file
201
website/content/api-docs/system/managed-keys.mdx
Normal file
@ -0,0 +1,201 @@
|
||||
---
|
||||
layout: api
|
||||
page_title: /sys/managed-keys - HTTP API
|
||||
description: The `/sys/managed-keys` endpoint is used manage the managed keys in Vault.
|
||||
---
|
||||
|
||||
# `/sys/managed-keys`
|
||||
|
||||
The `/sys/managed-keys` endpoint is used manage the Managed Key configuration within Vault.
|
||||
See the [Managed Keys](/docs/enterprise/managed-keys) section for further details on the Managed Keys system.
|
||||
|
||||
## List managed keys.
|
||||
|
||||
This endpoint lists all the Managed Keys of a certain type within the namespace.
|
||||
|
||||
| Method | Path |
|
||||
|:-------|:--------------------------|
|
||||
| `LIST` | `/sys/managed-keys/:type` |
|
||||
|
||||
### Parameters
|
||||
- `type` `(string: <required>)` – The backend type of keys to be listed.
|
||||
Supported options are `pkcs11`.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--request LIST \
|
||||
--header "X-Vault-Token: ..." \
|
||||
http://127.0.0.1:8200/v1/sys/managed-keys/pkcs11
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"keys": [
|
||||
"hsm-key1",
|
||||
"hsm-key2"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Create/Update managed key
|
||||
|
||||
An endpoint that will create or update a Managed Key within a given namespace. The :type refers to the backend type
|
||||
that the key is to use, such as `pkcs11`. The :name argument is unique name within all managed key types in
|
||||
the namespace.
|
||||
|
||||
| Method | Path |
|
||||
|:-------|:--------------------------------|
|
||||
| `POST` | `/sys/managed-keys/:type/:name` |
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--request POST \
|
||||
--header "X-Vault-Token: ..." \
|
||||
http://127.0.0.1:8200/v1/sys/managed-keys/pkcs11/hsm-key1
|
||||
```
|
||||
|
||||
### Generic Parameters
|
||||
- `name` `(string: <required>)` - A unique lowercase name that serves as identifying the key. Must be
|
||||
unique throughout all types in the namespace.
|
||||
|
||||
- `type` `(string: <required>)` – The backend type that will be leveraged for the managed key.
|
||||
Supported options are `pkcs11`.
|
||||
|
||||
- `allow_generate_key` `(string: "false")` - If no existing key can be found in the referenced backend, instructs
|
||||
Vault to generate a key within the backend.
|
||||
|
||||
- `allow_replace_key` `(string: "false")` - Controls the ability for Vault to replace through generation or importing
|
||||
a key into the configured backend even if a key is present, if set to false those operations are forbidden
|
||||
if a key exists.
|
||||
|
||||
- `allow_store_key` `(string: "false")` - Controls the ability for Vault to generate or import a key within the
|
||||
configured backend, if "false" those operations will be forbidden.
|
||||
|
||||
- `any_mount` `(string: "false")` - Allow usage from any mount point within the namespace if "true". If "false"
|
||||
specific mount points will need their `allowed_managed_keys` parameter to be updated with the key name to
|
||||
grant usage.
|
||||
|
||||
#### PKCS#11 backend Parameters
|
||||
|
||||
~> NOTE: The `pkcs11` backend is only available with Vault Enterprise Plus (HSMs) edition
|
||||
|
||||
- `type` `(string: "pkcs11")` - To select a PKCS#11 backend, the type parameter must be set to `pkcs11`
|
||||
|
||||
- `library` `(string: <required>)` - The name of the `kms_library` stanza to use from Vault's config to
|
||||
lookup the local library path. See [kms_library stanza](/docs/configuration/kms-library) for further details.
|
||||
|
||||
- `key_label` `(string: <required>)`: The label of the key to use. If the key
|
||||
does not exist and generation is enabled, this is the label that will be given
|
||||
to the generated key.
|
||||
|
||||
- `mechanism` `(string: <required>)` - The encryption/decryption mechanism to use,
|
||||
specified as a hexadecimal (prefixed by 0x) string. The following are supported mechanisms
|
||||
- `0x1041` `CKM_ECDSA`
|
||||
- `0x000D` `CKM_RSA_PKCS_PSS`
|
||||
- `0x0009` `CKM_RSA_PKCS_OAEP`
|
||||
- `0x0001` `CKM_RSA_PKCS`
|
||||
|
||||
- `pin` `(string: <required>)`: The PIN for login.
|
||||
|
||||
- `slot` `(string: <slot or token label required>)`: The slot number to use,
|
||||
specified as a string in a decimal format (e.g. `"2305843009213693953"`).
|
||||
|
||||
~> **Note**: Slots are typically listed as hex-decimal values in the OS setup
|
||||
utility but this configuration uses their decimal equivalent. For example, using the
|
||||
HSM command-line `pkcs11-tool`, a slot listed as `0x2000000000000001`in hex is equal
|
||||
to `2305843009213693953` in decimal; these values may be listed shorter or
|
||||
differently as determined by the HSM in use.
|
||||
|
||||
- `token_label` `(string: <slot or token label required>)`: The slot token label to
|
||||
use.
|
||||
|
||||
- `curve` `(string: "")` - supplies the curve value when using the `CKM_ECDSA mechanism`.
|
||||
The supported values are
|
||||
- `P384`
|
||||
- `P521`
|
||||
- `P256`
|
||||
|
||||
- `key_bits` `(int: 0)` - supplies the size in bits of the key when using `CKM_RSA_PKCS_PSS`,
|
||||
`CKM_RSA_PKCS_OAEP` or `CKM_RSA_PKCS` as a value for `mechanism`.
|
||||
The supported values are
|
||||
- 2048
|
||||
- 3072
|
||||
- 4096
|
||||
|
||||
- `force_rw_session` `(string: "false")`: Force all operations to open up
|
||||
a read-write session to the HSM. This is a boolean expressed as a string (e.g.
|
||||
`"true"`). This key is mainly to work around a limitation within AWS's CloudHSM v5
|
||||
pkcs11 implementation.
|
||||
|
||||
## Read managed key
|
||||
|
||||
This endpoint returns the managed key configuration at the given path.
|
||||
|
||||
| Method | Path |
|
||||
|:-------|:--------------------------------|
|
||||
| `GET` | `/sys/managed-keys/:type/:name` |
|
||||
|
||||
### Parameters
|
||||
- `name` `(string: <required>)` - The lowercase name identifying the key.
|
||||
|
||||
- `type` `(string: <required>)` – The backend type for the managed key.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
http://127.0.0.1:8200/v1/sys/managed-keys/pkcs11/hsm-key1
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"UUID": "af0a688e-d2c1-fc07-b365-40325674114d",
|
||||
"allow_generate_key": true,
|
||||
"allow_replace_key": false,
|
||||
"allow_store_key": false,
|
||||
"any_mount": false,
|
||||
"curve": "",
|
||||
"force_rw_session": false,
|
||||
"key_bits": 0,
|
||||
"key_label": "test-kms-root",
|
||||
"library": "softhsm",
|
||||
"mechanism": 1,
|
||||
"name": "hsm-key1",
|
||||
"pin": "redacted",
|
||||
"slot": 1,
|
||||
"token_label": "",
|
||||
"type": "pkcs11"
|
||||
}
|
||||
```
|
||||
|
||||
## Delete managed key
|
||||
|
||||
This endpoint deletes the managed key at the given path provided it is not
|
||||
listed within any mount point's `allowed_managed_keys`.
|
||||
|
||||
| Method | Path |
|
||||
|:---------|:--------------------------------|
|
||||
| `DELETE` | `/sys/managed-keys/:type/:name` |
|
||||
|
||||
### Parameters
|
||||
- `name` `(string: <required>)` - The lowercase name identifying the key.
|
||||
|
||||
- `type` `(string: <required>)` – The backend type for the managed key.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--request DELETE \
|
||||
--header "X-Vault-Token: ..." \
|
||||
http://127.0.0.1:8200/v1/sys/managed-keys/pkcs11/hsm-key1
|
||||
```
|
||||
42
website/content/docs/enterprise/managed-keys.mdx
Normal file
42
website/content/docs/enterprise/managed-keys.mdx
Normal file
@ -0,0 +1,42 @@
|
||||
---
|
||||
layout: docs
|
||||
page_title: Managed Keys
|
||||
description: >-
|
||||
Managed Keys is a system in Vault that defers all private key operations to a third party system.
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
## Namespace support
|
||||
|
||||
Every configured Managed Key is bound to a given namespace, defaulting to the
|
||||
root namespace. Any secrets engine's mount path must exist within the same namespace
|
||||
as the Managed Key for which it intends to use.
|
||||
|
||||
## Backend Support
|
||||
|
||||
Managed Keys were developed to support different types of external backends.
|
||||
At this time only a PKCS#11 backend is supported, with the possibility of
|
||||
future integrations being added.
|
||||
|
||||
## Plugin 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.
|
||||
|
||||
## API
|
||||
|
||||
Managed Keys can be managed over the HTTP API. Please see
|
||||
[Managed Keys API](/api-docs/system/managed-keys) for more details.
|
||||
|
||||
To configure PKI secrets engine with Managed Keys please see
|
||||
[PKI Secret API](/api/secret/pki#managed-keys)
|
||||
@ -449,6 +449,10 @@
|
||||
"title": "<code>/sys/license</code>",
|
||||
"path": "system/license"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/managed-keys <sup>ENT</sup></code>",
|
||||
"path": "system/managed-keys"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/metrics</code>",
|
||||
"path": "system/metrics"
|
||||
|
||||
@ -1828,6 +1828,10 @@
|
||||
"title": "Control Groups",
|
||||
"path": "enterprise/control-groups"
|
||||
},
|
||||
{
|
||||
"title": "Managed Keys",
|
||||
"path": "enterprise/managed-keys"
|
||||
},
|
||||
{
|
||||
"title": "MFA",
|
||||
"routes": [
|
||||
|
||||
Loading…
Reference in New Issue
Block a user