mirror of
https://github.com/hashicorp/vault.git
synced 2026-04-26 00:30:11 -04:00
Update docs to include specifics and caveats around Transit Managed Keys support. (#20099)
This commit is contained in:
Matt Schultz
GitHub
parent
05feed51bc
commit
fc783b00ab
3 changed files with 44 additions and 14 deletions
|
|
@ -648,7 +648,7 @@ will be returned.
|
|||
|
||||
- `batch_input` `(array<object>: nil)` – Specifies a list of items to be
|
||||
encrypted in a single batch. When this parameter is set, if the parameters
|
||||
'plaintext', 'context' and 'nonce' are also set, they will be ignored.
|
||||
'plaintext', 'context' and 'nonce' are also set, they will be ignored.
|
||||
Any batch output will preserve the order of the batch input. The
|
||||
format for the input is:
|
||||
|
||||
|
|
@ -679,10 +679,10 @@ will be returned.
|
|||
all nonces are unique for a given context. Failing to do so will severely
|
||||
impact the ciphertext's security.
|
||||
|
||||
- `partial_failure_response_code` `(int: 400)` Ordinarily, if a batch item fails
|
||||
to encrypt due to a bad input, but other batch items succeed, the HTTP response
|
||||
- `partial_failure_response_code` `(int: 400)` Ordinarily, if a batch item fails
|
||||
to encrypt due to a bad input, but other batch items succeed, the HTTP response
|
||||
code is 400 (Bad Request). Some applications may want to treat partial failures
|
||||
differently. Providing the parameter returns the given response code integer
|
||||
differently. Providing the parameter returns the given response code integer
|
||||
instead of a failed status code in this case. If all values fail an error
|
||||
code is still returned. Be warned that some failures (such as failure to
|
||||
decrypt) could be indicative of a security breach and should not be
|
||||
|
|
@ -767,7 +767,7 @@ This endpoint decrypts the provided ciphertext using the named key.
|
|||
|
||||
- `batch_input` `(array<object>: nil)` – Specifies a list of items to be
|
||||
decrypted in a single batch. When this parameter is set, if the parameters
|
||||
'ciphertext', 'context' and 'nonce' are also set, they will be ignored.
|
||||
'ciphertext', 'context' and 'nonce' are also set, they will be ignored.
|
||||
Any batch output will preserve the order of the batch input. Format
|
||||
for the input goes like this:
|
||||
|
||||
|
|
@ -783,10 +783,10 @@ This endpoint decrypts the provided ciphertext using the named key.
|
|||
}
|
||||
]
|
||||
```
|
||||
- `partial_failure_response_code` `(int: 400)` Ordinarily, if a batch item fails
|
||||
to encrypt due to a bad input, but other batch items succeed, the HTTP response
|
||||
- `partial_failure_response_code` `(int: 400)` Ordinarily, if a batch item fails
|
||||
to encrypt due to a bad input, but other batch items succeed, the HTTP response
|
||||
code is 400 (Bad Request). Some applications may want to treat partial failures
|
||||
differently. Providing the parameter returns the given response code integer
|
||||
differently. Providing the parameter returns the given response code integer
|
||||
instead of a failed status code in this case. If all values fail an error
|
||||
code is still returned. Be warned that some failures (such as failure to
|
||||
decrypt) could be indicative of a security breach and should not be
|
||||
|
|
@ -1079,7 +1079,7 @@ $ curl \
|
|||
## Generate HMAC
|
||||
|
||||
This endpoint returns the digest of given data using the specified hash
|
||||
algorithm and the named key. The key can be of any type supported by `transit`,
|
||||
algorithm and the named key. The key can be of any type supported by `transit`,
|
||||
as each `transit` key version has an independent, random 256-bit HMAC secret key. If
|
||||
the key is of a type that supports rotation, the latest (current) version will
|
||||
be used.
|
||||
|
|
@ -1125,7 +1125,7 @@ be used.
|
|||
- `batch_input` `(array<object>: nil)` – Specifies a list of items for processing.
|
||||
When this parameter is set, if the parameter 'input' is also set, it will be
|
||||
ignored. Responses are returned in the 'batch_results' array component of the
|
||||
'data' element of the response. Any batch output will preserve the order of
|
||||
'data' element of the response. Any batch output will preserve the order of
|
||||
the batch input. If the input data value of an item is invalid, the
|
||||
corresponding item in the 'batch_results' will have the key 'error' with a value
|
||||
describing the error. The format for batch_input is:
|
||||
|
|
@ -1279,7 +1279,7 @@ supports signing.
|
|||
- `batch_input` `(array<object>: nil)` – Specifies a list of items for processing.
|
||||
When this parameter is set, any supplied 'input' or 'context' parameters will be
|
||||
ignored. Responses are returned in the 'batch_results' array component of the
|
||||
'data' element of the response. Any batch output will preserve the order of the
|
||||
'data' element of the response. Any batch output will preserve the order of the
|
||||
batch input. If the input data value of an item is invalid, the
|
||||
corresponding item in the 'batch_results' will have the key 'error' with a value
|
||||
describing the error. The format for batch_input is:
|
||||
|
|
@ -1472,9 +1472,9 @@ data.
|
|||
either an 'hmac' or 'signature' parameter. All items in the batch must consistently
|
||||
supply either 'hmac' or 'signature' parameters. It is an error for some items to
|
||||
supply 'hmac' while others supply 'signature'. Responses are returned in the
|
||||
'batch_results' array component of the 'data' element of the response. Any batch
|
||||
output will preserve the order of the batch input. If the input data value of an
|
||||
item is invalid, the corresponding item in the 'batch_results' will have the key
|
||||
'batch_results' array component of the 'data' element of the response. Any batch
|
||||
output will preserve the order of the batch input. If the input data value of an
|
||||
item is invalid, the corresponding item in the 'batch_results' will have the key
|
||||
'error' with a value describing the error. The format for batch_input is:
|
||||
|
||||
```json
|
||||
|
|
@ -1765,4 +1765,25 @@ $ curl \
|
|||
},
|
||||
```
|
||||
|
||||
## Managed Keys
|
||||
|
||||
~> **Note**: Managed keys are an Enterprise only feature.
|
||||
|
||||
Managed Keys can be used with the Transit Secrets Engine to perform cryptographic operations. Currently
|
||||
[Sign Data](#sign-data) and [Verify Signed Data](#verify-signed-data) are well supported, and in certain
|
||||
configurations, [Encrypt Data](#encrypt-data) and [Decrypt Data](#decrypt-data) are supported.
|
||||
|
||||
When a Transit key is created of type `managed_key`, Transit will lookup the key by name or ID, and will
|
||||
attempt to generate the key when key generation is allowed (as specified when the [Create/Update Managed Key](/vault/api-docs/system/managed-keys#create-update-managed-key)
|
||||
endpoint is called). Key generation is currently supported for cloud KMSes and for certain PKCS#11 mechanisms
|
||||
on HSMs. This is a best effort operation, so certain KMS/HSM/key configurations will require the key to exist
|
||||
externally prior to use with Transit.
|
||||
|
||||
For key types and mechanisms that require an IV, this value can be provided via the `nonce` parameter of
|
||||
the [Encrypt Data](#encrypt-data) and [Decrypt Data](#decrypt-data) endpoints.
|
||||
|
||||
Signing and verifying data with a Managed Key through Transit may require pre-hashing of the data. Transit
|
||||
can be informed that data is pre-hashed with the `prehashed` parameter of the [Sign Data](#sign-data) and
|
||||
[Verify Signed Data](#verify-signed-data) endpoints.
|
||||
|
||||
[sys-plugin-reload-backend]: /vault/api-docs/system/plugins-reload-backend#reload-plugins
|
||||
|
|
|
|||
|
|
@ -121,6 +121,10 @@ $ curl \
|
|||
- `0x0009` `CKM_RSA_PKCS_OAEP`
|
||||
- `0x0001` `CKM_RSA_PKCS`
|
||||
|
||||
~> **Note**: It is possible to use unsupported mechanisms with a managed key, however automatic key generation is only
|
||||
possible with the above supported mechanisms. Automatic key generation is also currently a best effort operation and may
|
||||
not function correctly on all HSMs.
|
||||
|
||||
- `pin` `(string: <required>)`: The PIN for login.
|
||||
|
||||
- `slot` `(string: <slot or token label required>)`: The slot number to use,
|
||||
|
|
|
|||
|
|
@ -46,6 +46,11 @@ The [PKI Secrets Engine](/vault/api-docs/secret/pki#managed-keys) has been integ
|
|||
with Managed Keys to offer certificate generation, both root and intermediary
|
||||
PKI paths, leveraging private keys from an external trusted KMS.
|
||||
|
||||
The [Transit Secrets Engine](/vault/api-docs/secret/transit#managed-keys) allows users
|
||||
to generate and verify cryptographic signatures with Managed Keys, and in some cases encrypt
|
||||
and decrypt data, or generate MACs and HMACs. These operations are performed on the KMS or HSM
|
||||
that hosts the Managed Key material.
|
||||
|
||||
More engines may leverage managed keys in the future.
|
||||
|
||||
## API
|
||||
|
|
|
|||
Loading…
Reference in a new issue