From 850872e910f5c11b890887a4308129d7b5a15877 Mon Sep 17 00:00:00 2001 From: hc-github-team-secure-vault-core <82990506+hc-github-team-secure-vault-core@users.noreply.github.com> Date: Wed, 12 Apr 2023 14:56:43 -0400 Subject: [PATCH] backport of commit fc783b00ab6556748344af08fbd9eb016c1ee9a3 (#20120) Co-authored-by: Matt Schultz <975680+schultz-is@users.noreply.github.com> --- website/content/api-docs/secret/transit.mdx | 49 +++++++++++++------ .../content/api-docs/system/managed-keys.mdx | 4 ++ .../content/docs/enterprise/managed-keys.mdx | 5 ++ 3 files changed, 44 insertions(+), 14 deletions(-) diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx index 0a986fe8d6cb..dcd1526e2d8a 100644 --- a/website/content/api-docs/secret/transit.mdx +++ b/website/content/api-docs/secret/transit.mdx @@ -648,7 +648,7 @@ will be returned. - `batch_input` `(array: 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: 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: 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: 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 @@ -1763,4 +1763,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 diff --git a/website/content/api-docs/system/managed-keys.mdx b/website/content/api-docs/system/managed-keys.mdx index abafe20c0a9e..762b2a181114 100644 --- a/website/content/api-docs/system/managed-keys.mdx +++ b/website/content/api-docs/system/managed-keys.mdx @@ -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: )`: The PIN for login. - `slot` `(string: )`: The slot number to use, diff --git a/website/content/docs/enterprise/managed-keys.mdx b/website/content/docs/enterprise/managed-keys.mdx index 9a9e3c9a5b5e..fe71a3adc67e 100644 --- a/website/content/docs/enterprise/managed-keys.mdx +++ b/website/content/docs/enterprise/managed-keys.mdx @@ -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