From 622c07e73a2e5784b89072bd06060e98a8df853f Mon Sep 17 00:00:00 2001 From: rculpepper Date: Tue, 3 May 2022 16:20:13 -0400 Subject: [PATCH 01/11] add api documentation --- website/content/api-docs/secret/transit.mdx | 143 +++++++++++++++++++- 1 file changed, 142 insertions(+), 1 deletion(-) diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx index 817674dedf01..ab79461d1e42 100644 --- a/website/content/api-docs/secret/transit.mdx +++ b/website/content/api-docs/secret/transit.mdx @@ -91,6 +91,146 @@ $ curl \ http://127.0.0.1:8200/v1/transit/keys/my-key ``` +## Import Key + +This endpoint imports existing key material into a new transit-managed encryption key. +To import key material into an existing key, see the `import_version/` endpoint. + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + create. This is specified as part of the URL. + +- `ciphertext` `(string: )` - A base64-encoded string that contains +two values: an ephemeral AES key wrapped using the wrapping key +returned by Vault and the encryption of the import key material under the +provided AES key. The wrapped AES key should be the first 512 bytes of the +ciphertext, and the encrypted key material should be the remaining bytes. + +- `type` `(string: )` – Specifies the type of key to create. The + currently-supported types are: + + - `aes128-gcm96` – AES-128 wrapped with GCM using a 96-bit nonce size AEAD + (symmetric, supports derivation and convergent encryption) + - `aes256-gcm96` – AES-256 wrapped with GCM using a 96-bit nonce size AEAD + (symmetric, supports derivation and convergent encryption, default) + - `chacha20-poly1305` – ChaCha20-Poly1305 AEAD (symmetric, supports + derivation and convergent encryption) + - `ed25519` – ED25519 (asymmetric, supports derivation). When using + derivation, a sign operation with the same context will derive the same + key and signature; this is a signing analogue to `convergent_encryption`. + - `ecdsa-p256` – ECDSA using the P-256 elliptic curve (asymmetric) + - `ecdsa-p384` – ECDSA using the P-384 elliptic curve (asymmetric) + - `ecdsa-p521` – ECDSA using the P-521 elliptic curve (asymmetric) + - `rsa-2048` - RSA with bit size of 2048 (asymmetric) + - `rsa-3072` - RSA with bit size of 3072 (asymmetric) + - `rsa-4096` - RSA with bit size of 4096 (asymmetric) + +- `allow_rotation` `(bool: false)` - If set, the imported key can be rotated +within Vault by using the `rotate` endpoint. + +- `convergent_encryption` `(bool: false)` – If enabled, the key will support + convergent encryption, where the same plaintext creates the same ciphertext. + This requires _derived_ to be set to `true`. When enabled, each + encryption(/decryption/rewrap/datakey) operation will derive a `nonce` value + rather than randomly generate it. + +- `derived` `(bool: false)` – Specifies if key derivation is to be used. If + enabled, all encrypt/decrypt requests to this named key must provide a context + which is used for key derivation. + +- `exportable` `(bool: false)` - Enables keys to be exportable. This + allows for all the valid keys in the key ring to be exported. Once set, this + cannot be disabled. + +- `allow_plaintext_backup` `(bool: false)` - If set, enables taking backup of + named key in the plaintext format. Once set, this cannot be disabled. + +- `auto_rotate_period` `(duration: "0", optional)` – The period at which + this key should be rotated automatically. Setting this to "0" (the default) + will disable automatic key rotation. This value cannot be shorter than one + hour. + +### Sample Payload + +```json +{ + "type": "ed25519", + "ciphertext": "..." +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/transit/keys/my-key/import +``` + +## Import Key Version + +This endpoint imports new key material into an existing imported key. + +**Note**: Vault-generated keys cannot be used for importing key material. +Only keys that were previously imported into Vault can import new key +material from an external source. + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + create. This is specified as part of the URL. + +- `ciphertext` `(string: )` - A base64-encoded string that contains +two values: an ephemeral AES key wrapped using the wrapping key +returned by Vault and the encryption of the import key material under the +provided AES key. The wrapped AES key should be the first 512 bytes of the +ciphertext, and the encrypted key material should be the remaining bytes. + +### Sample Payload + +```json +{ + "ciphertext": "..." +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/transit/keys/my-key/import_version +``` + +## Get Wrapping Key + +This endpoint is used to retrieve the wrapping key to use for importing keys. +The returned key will be a 4096-bit RSA public key. + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/transit/wrapping_key +``` + +### Sample Response + +```json +{ + "data": { + "public_key": "..." + }, +} +``` + ## Read Key This endpoint returns information about a named encryption key. The `keys` @@ -135,7 +275,8 @@ $ curl \ "supports_encryption": true, "supports_decryption": true, "supports_derivation": true, - "supports_signing": false + "supports_signing": false, + "imported": false } } ``` From 10f91417523691e8f1889bc544527ff658475e6f Mon Sep 17 00:00:00 2001 From: rculpepper Date: Thu, 5 May 2022 21:29:22 -0400 Subject: [PATCH 02/11] add guide for wrapping keys --- website/content/api-docs/secret/transit.mdx | 15 +++++-- website/content/docs/secrets/transit.mdx | 49 +++++++++++++++++++++ 2 files changed, 61 insertions(+), 3 deletions(-) diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx index ab79461d1e42..9b4a6c82576c 100644 --- a/website/content/api-docs/secret/transit.mdx +++ b/website/content/api-docs/secret/transit.mdx @@ -129,6 +129,9 @@ ciphertext, and the encrypted key material should be the remaining bytes. - `allow_rotation` `(bool: false)` - If set, the imported key can be rotated within Vault by using the `rotate` endpoint. +**NOTE**: Once an imported key is rotated within Vault, it will no longer +support importing key material with the `import_version` endpoint. + - `convergent_encryption` `(bool: false)` – If enabled, the key will support convergent encryption, where the same plaintext creates the same ciphertext. This requires _derived_ to be set to `true`. When enabled, each @@ -174,9 +177,9 @@ $ curl \ This endpoint imports new key material into an existing imported key. -**Note**: Vault-generated keys cannot be used for importing key material. -Only keys that were previously imported into Vault can import new key -material from an external source. +**Note**: Keys whose material was generated by Vault do not support +importing key material. Only keys that were previously imported into +Vault can import new key material from an external source. ### Parameters @@ -188,6 +191,8 @@ two values: an ephemeral AES key wrapped using the wrapping key returned by Vault and the encryption of the import key material under the provided AES key. The wrapped AES key should be the first 512 bytes of the ciphertext, and the encrypted key material should be the remaining bytes. +See the BYOK section of the [Transit secrets engine documentation](/docs/secret/transit) +for more information on constructing the ciphertext. ### Sample Payload @@ -407,6 +412,10 @@ ciphertext to be encrypted with the latest version of the key, use the `rewrap` endpoint. This is only supported with keys that support encryption and decryption operations. +**Note**: For imported keys, rotation is only supported if the +`allow_rotation` field was set to `true` on import. Once an imported key is +rotated within Vault, it will not support further import operations. + | Method | Path | | :----- | :--------------------------- | | `POST` | `/transit/keys/:name/rotate` | diff --git a/website/content/docs/secrets/transit.mdx b/website/content/docs/secrets/transit.mdx index 04e788441533..f6b67812e1fe 100644 --- a/website/content/docs/secrets/transit.mdx +++ b/website/content/docs/secrets/transit.mdx @@ -235,6 +235,55 @@ the proper permission, it can use this secrets engine. data, since the process would not be able to get access to the plaintext data. +## BYOK + +The transit secrets engine supports importing key material from external sources into +transit keys. + +First, the wrapping key needs to be read from transit: + +$ vault read transit/wrapping_key + +The wrapping key will be a 4096-bit RSA public key. + +Then the wrapping key is used to create the ciphertext input for the `import` endpoint. +For the explanations below, the key being imported into Vault is referred to as the target +key. + +### HSM + +If the key is being imported from an HSM that supports PKCS#11, there are +two scenarios: + +- If the HSM supports the CKM_RSA_AES_KEY_WRAP mechanism, that can be used to wrap the +target key using the wrapping key. + +- Otherwise, two mechanisms can be combined to wrap the target key. First, an AES key should +be generated and then used to wrap the target key using the CKM_AES_KEY_WRAP_PAD mechanism. +Then the AES key should be encrypted under the wrapping key using the CKM_RSA_PKCS_OAEP mechanism +using MGF1 and either SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512. + +To create the ciphertext for input to transit's import endpoint, append the wrapped target key +to the encrypted AES key and then encode the bytes in base64. + +### Manual Process + +If the target key is not stored in an HSM or KMS, the following steps can be used to construct +the ciphertext for the input of the `import` endpoint: + +- Generate an ephemeral AES key. + +- Wrap the target key using the ephemeral AES key with AES-KWP. + +- Wrap the AES key under the wrapping key returned by Vault using RSAES-OAEP with MGF1 and +either SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512. + +- Delete the ephemeral AES key. + +- Append the wrapped target key to the wrapped AES key. + +- Base64 encode the result. + ## Tutorial Refer to the [Encryption as a Service: Transit Secrets From 5bebe6489a0692547a3bf254d16c2c463bd5cd1a Mon Sep 17 00:00:00 2001 From: rculpepper Date: Fri, 6 May 2022 09:47:27 -0400 Subject: [PATCH 03/11] fix formatting and tweak wording --- website/content/docs/secrets/transit.mdx | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/website/content/docs/secrets/transit.mdx b/website/content/docs/secrets/transit.mdx index f6b67812e1fe..08e7a403e10e 100644 --- a/website/content/docs/secrets/transit.mdx +++ b/website/content/docs/secrets/transit.mdx @@ -242,29 +242,31 @@ transit keys. First, the wrapping key needs to be read from transit: +```text $ vault read transit/wrapping_key +``` The wrapping key will be a 4096-bit RSA public key. -Then the wrapping key is used to create the ciphertext input for the `import` endpoint. -For the explanations below, the key being imported into Vault is referred to as the target -key. +Then the wrapping key is used to create the ciphertext input for the `import` endpoint, +as described below. In the below, the target key refers to the key being imported. ### HSM If the key is being imported from an HSM that supports PKCS#11, there are -two scenarios: +two possible scenarios: - If the HSM supports the CKM_RSA_AES_KEY_WRAP mechanism, that can be used to wrap the target key using the wrapping key. - Otherwise, two mechanisms can be combined to wrap the target key. First, an AES key should be generated and then used to wrap the target key using the CKM_AES_KEY_WRAP_PAD mechanism. -Then the AES key should be encrypted under the wrapping key using the CKM_RSA_PKCS_OAEP mechanism +Then the AES key should be wrapped under the wrapping key using the CKM_RSA_PKCS_OAEP mechanism using MGF1 and either SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512. -To create the ciphertext for input to transit's import endpoint, append the wrapped target key -to the encrypted AES key and then encode the bytes in base64. +The ciphertext is constructed by appending the wrapped target key to the wrapped AES key. + +The ciphertext bytes should be base64-encoded. ### Manual Process @@ -275,7 +277,7 @@ the ciphertext for the input of the `import` endpoint: - Wrap the target key using the ephemeral AES key with AES-KWP. -- Wrap the AES key under the wrapping key returned by Vault using RSAES-OAEP with MGF1 and +- Wrap the AES key under the Vault wrapping key using RSAES-OAEP with MGF1 and either SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512. - Delete the ephemeral AES key. From b62cfc391f5b82b3ab3a7d319e119fb2dca6826e Mon Sep 17 00:00:00 2001 From: rculpepper Date: Tue, 10 May 2022 19:07:47 -0400 Subject: [PATCH 04/11] add hash function --- website/content/api-docs/secret/transit.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx index 9b4a6c82576c..01d8ca63221d 100644 --- a/website/content/api-docs/secret/transit.mdx +++ b/website/content/api-docs/secret/transit.mdx @@ -107,6 +107,10 @@ returned by Vault and the encryption of the import key material under the provided AES key. The wrapped AES key should be the first 512 bytes of the ciphertext, and the encrypted key material should be the remaining bytes. +- `hash_function` `(string: )` - The hash function used for the +RSA-OAEP step of creating the ciphertext. Supported hash functions are: +`SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, and `SHA-512`. + - `type` `(string: )` – Specifies the type of key to create. The currently-supported types are: @@ -194,6 +198,10 @@ ciphertext, and the encrypted key material should be the remaining bytes. See the BYOK section of the [Transit secrets engine documentation](/docs/secret/transit) for more information on constructing the ciphertext. +- `hash_function` `(string: )` - The hash function used for the +RSA-OAEP step of creating the ciphertext. Supported hash functions are: +`SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, and `SHA-512`. + ### Sample Payload ```json From 3feaca843af2848c9e011d0f63b4f887dbd40faa Mon Sep 17 00:00:00 2001 From: rculpepper Date: Tue, 10 May 2022 19:09:45 -0400 Subject: [PATCH 05/11] remove convergent param --- website/content/api-docs/secret/transit.mdx | 6 ------ 1 file changed, 6 deletions(-) diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx index 01d8ca63221d..369405102a80 100644 --- a/website/content/api-docs/secret/transit.mdx +++ b/website/content/api-docs/secret/transit.mdx @@ -136,12 +136,6 @@ within Vault by using the `rotate` endpoint. **NOTE**: Once an imported key is rotated within Vault, it will no longer support importing key material with the `import_version` endpoint. -- `convergent_encryption` `(bool: false)` – If enabled, the key will support - convergent encryption, where the same plaintext creates the same ciphertext. - This requires _derived_ to be set to `true`. When enabled, each - encryption(/decryption/rewrap/datakey) operation will derive a `nonce` value - rather than randomly generate it. - - `derived` `(bool: false)` – Specifies if key derivation is to be used. If enabled, all encrypt/decrypt requests to this named key must provide a context which is used for key derivation. From bef0cdd1a22364e8668db5a5892fd45b44df529a Mon Sep 17 00:00:00 2001 From: rculpepper Date: Tue, 24 May 2022 15:03:19 -0400 Subject: [PATCH 06/11] fix hash function description --- website/content/api-docs/secret/transit.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx index 369405102a80..0d2e22fae254 100644 --- a/website/content/api-docs/secret/transit.mdx +++ b/website/content/api-docs/secret/transit.mdx @@ -107,9 +107,10 @@ returned by Vault and the encryption of the import key material under the provided AES key. The wrapped AES key should be the first 512 bytes of the ciphertext, and the encrypted key material should be the remaining bytes. -- `hash_function` `(string: )` - The hash function used for the +- `hash_function` `(string: "SHA-256")` - The hash function used for the RSA-OAEP step of creating the ciphertext. Supported hash functions are: -`SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, and `SHA-512`. +`SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, and `SHA-512`. If not specified, +the hash function defaults to SHA-256. - `type` `(string: )` – Specifies the type of key to create. The currently-supported types are: @@ -192,9 +193,10 @@ ciphertext, and the encrypted key material should be the remaining bytes. See the BYOK section of the [Transit secrets engine documentation](/docs/secret/transit) for more information on constructing the ciphertext. -- `hash_function` `(string: )` - The hash function used for the +- `hash_function` `(string: "SHA-256")` - The hash function used for the RSA-OAEP step of creating the ciphertext. Supported hash functions are: -`SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, and `SHA-512`. +`SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, and `SHA-512`. If not specified, +the hash function defaults to SHA-256. ### Sample Payload From 0b5bfe4556fa036f349d95da8273e9d7a39c865a Mon Sep 17 00:00:00 2001 From: rculpepper Date: Thu, 26 May 2022 14:05:10 -0400 Subject: [PATCH 07/11] add security note --- website/content/docs/secrets/transit.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/website/content/docs/secrets/transit.mdx b/website/content/docs/secrets/transit.mdx index 08e7a403e10e..850e3c8c7f86 100644 --- a/website/content/docs/secrets/transit.mdx +++ b/website/content/docs/secrets/transit.mdx @@ -235,10 +235,11 @@ the proper permission, it can use this secrets engine. data, since the process would not be able to get access to the plaintext data. -## BYOK +## Bring Your Own Key (BYOK) -The transit secrets engine supports importing key material from external sources into -transit keys. +*Note:* Key import functionality supports cases in which there is a need to bring +in an existing key from an HSM or other outside system. It is more secure to +have Transit generate and manage a key within Vault. First, the wrapping key needs to be read from transit: From 6746f6655e180a086e7d278cb06121928b7fd80c Mon Sep 17 00:00:00 2001 From: rculpepper Date: Fri, 27 May 2022 13:51:20 -0400 Subject: [PATCH 08/11] fix mechanism --- website/content/docs/secrets/transit.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/secrets/transit.mdx b/website/content/docs/secrets/transit.mdx index 850e3c8c7f86..573156966f3a 100644 --- a/website/content/docs/secrets/transit.mdx +++ b/website/content/docs/secrets/transit.mdx @@ -257,7 +257,7 @@ as described below. In the below, the target key refers to the key being importe If the key is being imported from an HSM that supports PKCS#11, there are two possible scenarios: -- If the HSM supports the CKM_RSA_AES_KEY_WRAP mechanism, that can be used to wrap the +- If the HSM supports the CKM_AES_KEY_WRAP_KWP mechanism, that can be used to wrap the target key using the wrapping key. - Otherwise, two mechanisms can be combined to wrap the target key. First, an AES key should From b83f5b095ad6e735cf8e922015b3fb4b5934f327 Mon Sep 17 00:00:00 2001 From: rculpepper Date: Mon, 6 Jun 2022 14:15:33 -0400 Subject: [PATCH 09/11] fix notes --- website/content/api-docs/secret/transit.mdx | 10 +++++----- website/content/docs/secrets/transit.mdx | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx index 0d2e22fae254..1e2ff756e161 100644 --- a/website/content/api-docs/secret/transit.mdx +++ b/website/content/api-docs/secret/transit.mdx @@ -134,7 +134,7 @@ the hash function defaults to SHA-256. - `allow_rotation` `(bool: false)` - If set, the imported key can be rotated within Vault by using the `rotate` endpoint. -**NOTE**: Once an imported key is rotated within Vault, it will no longer +~>**NOTE**: Once an imported key is rotated within Vault, it will no longer support importing key material with the `import_version` endpoint. - `derived` `(bool: false)` – Specifies if key derivation is to be used. If @@ -176,7 +176,7 @@ $ curl \ This endpoint imports new key material into an existing imported key. -**Note**: Keys whose material was generated by Vault do not support +~>**Note**: Keys whose material was generated by Vault do not support importing key material. Only keys that were previously imported into Vault can import new key material from an external source. @@ -416,7 +416,7 @@ ciphertext to be encrypted with the latest version of the key, use the `rewrap` endpoint. This is only supported with keys that support encryption and decryption operations. -**Note**: For imported keys, rotation is only supported if the +~>**Note**: For imported keys, rotation is only supported if the `allow_rotation` field was set to `true` on import. Once an imported key is rotated within Vault, it will not support further import operations. @@ -552,7 +552,7 @@ will be returned. all nonces are unique for a given context. Failing to do so will severely impact the ciphertext's security. -**NOTE:** All plaintext data **must be base64-encoded**. The reason for this +~>**NOTE:** All plaintext data **must be base64-encoded**. The reason for this requirement is that Vault does not require that the plaintext is "text". It could be a binary file such as a PDF or image. The easiest safe transport mechanism for this data as part of a JSON payload is to base64-encode it. @@ -822,7 +822,7 @@ This endpoint returns high-quality random bytes of the specified length. are `hex` or `base64`. - `source` `(string: "platform")` - Specifies the source of the requested bytes. - `platform`, the default, sources bytes from the platform's entropy source. + `platform`, the default, sources bytes from the platform's entropy source. `seal` sources from entropy augmentation (enterprise only). `all` mixes bytes from all available sources. diff --git a/website/content/docs/secrets/transit.mdx b/website/content/docs/secrets/transit.mdx index 573156966f3a..aae705bd7c6d 100644 --- a/website/content/docs/secrets/transit.mdx +++ b/website/content/docs/secrets/transit.mdx @@ -237,7 +237,7 @@ the proper permission, it can use this secrets engine. ## Bring Your Own Key (BYOK) -*Note:* Key import functionality supports cases in which there is a need to bring +~>**Note:** Key import functionality supports cases in which there is a need to bring in an existing key from an HSM or other outside system. It is more secure to have Transit generate and manage a key within Vault. From 7219f612f1434f6c2c67f66460958420e328481e Mon Sep 17 00:00:00 2001 From: rculpepper Date: Mon, 6 Jun 2022 14:28:40 -0400 Subject: [PATCH 10/11] add spaces --- website/content/api-docs/secret/transit.mdx | 6 +++--- website/content/docs/secrets/transit.mdx | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx index 1e2ff756e161..e81b28813f53 100644 --- a/website/content/api-docs/secret/transit.mdx +++ b/website/content/api-docs/secret/transit.mdx @@ -134,7 +134,7 @@ the hash function defaults to SHA-256. - `allow_rotation` `(bool: false)` - If set, the imported key can be rotated within Vault by using the `rotate` endpoint. -~>**NOTE**: Once an imported key is rotated within Vault, it will no longer +~> **NOTE**: Once an imported key is rotated within Vault, it will no longer support importing key material with the `import_version` endpoint. - `derived` `(bool: false)` – Specifies if key derivation is to be used. If @@ -176,7 +176,7 @@ $ curl \ This endpoint imports new key material into an existing imported key. -~>**Note**: Keys whose material was generated by Vault do not support +~> **Note**: Keys whose material was generated by Vault do not support importing key material. Only keys that were previously imported into Vault can import new key material from an external source. @@ -416,7 +416,7 @@ ciphertext to be encrypted with the latest version of the key, use the `rewrap` endpoint. This is only supported with keys that support encryption and decryption operations. -~>**Note**: For imported keys, rotation is only supported if the +~> **Note**: For imported keys, rotation is only supported if the `allow_rotation` field was set to `true` on import. Once an imported key is rotated within Vault, it will not support further import operations. diff --git a/website/content/docs/secrets/transit.mdx b/website/content/docs/secrets/transit.mdx index aae705bd7c6d..ec19e6b9f568 100644 --- a/website/content/docs/secrets/transit.mdx +++ b/website/content/docs/secrets/transit.mdx @@ -237,7 +237,7 @@ the proper permission, it can use this secrets engine. ## Bring Your Own Key (BYOK) -~>**Note:** Key import functionality supports cases in which there is a need to bring +~> **Note:** Key import functionality supports cases in which there is a need to bring in an existing key from an HSM or other outside system. It is more secure to have Transit generate and manage a key within Vault. From 6c80e2443249188b1bb8d779358f9f8d7f9da02f Mon Sep 17 00:00:00 2001 From: rculpepper Date: Fri, 17 Jun 2022 15:38:00 -0400 Subject: [PATCH 11/11] fix hash function and add context --- website/content/api-docs/secret/transit.mdx | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx index e81b28813f53..f9c0a16c918b 100644 --- a/website/content/api-docs/secret/transit.mdx +++ b/website/content/api-docs/secret/transit.mdx @@ -107,10 +107,10 @@ returned by Vault and the encryption of the import key material under the provided AES key. The wrapped AES key should be the first 512 bytes of the ciphertext, and the encrypted key material should be the remaining bytes. -- `hash_function` `(string: "SHA-256")` - The hash function used for the +- `hash_function` `(string: "SHA256")` - The hash function used for the RSA-OAEP step of creating the ciphertext. Supported hash functions are: -`SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, and `SHA-512`. If not specified, -the hash function defaults to SHA-256. +`SHA1`, `SHA224`, `SHA256`, `SHA384`, and `SHA512`. If not specified, +the hash function defaults to SHA256. - `type` `(string: )` – Specifies the type of key to create. The currently-supported types are: @@ -141,6 +141,9 @@ support importing key material with the `import_version` endpoint. enabled, all encrypt/decrypt requests to this named key must provide a context which is used for key derivation. +- `context` `(string: "")` - A base64-encoded string providing a context for +key derivation. Required if `derived` is set to `true`. + - `exportable` `(bool: false)` - Enables keys to be exportable. This allows for all the valid keys in the key ring to be exported. Once set, this cannot be disabled. @@ -193,10 +196,10 @@ ciphertext, and the encrypted key material should be the remaining bytes. See the BYOK section of the [Transit secrets engine documentation](/docs/secret/transit) for more information on constructing the ciphertext. -- `hash_function` `(string: "SHA-256")` - The hash function used for the +- `hash_function` `(string: "SHA256")` - The hash function used for the RSA-OAEP step of creating the ciphertext. Supported hash functions are: -`SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, and `SHA-512`. If not specified, -the hash function defaults to SHA-256. +`SHA1`, `SHA224`, `SHA256`, `SHA384`, and `SHA512`. If not specified, +the hash function defaults to SHA256. ### Sample Payload