12b0e2a56b
* 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
202 lines
6.4 KiB
Plaintext
202 lines
6.4 KiB
Plaintext
---
|
||
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
|
||
```
|