From b49622076fb7f80ade21d17ed598b581705738e8 Mon Sep 17 00:00:00 2001 From: Rachel Culpepper <84159930+rculpepper@users.noreply.github.com> Date: Thu, 25 Apr 2024 17:05:11 -0500 Subject: [PATCH] Add docs for cmac (#26654) * add docs for cmac * move cmac --- website/content/api-docs/secret/transit.mdx | 118 +++++++++++++++++- .../content/docs/secrets/transit/index.mdx | 2 + 2 files changed, 119 insertions(+), 1 deletion(-) diff --git a/website/content/api-docs/secret/transit.mdx b/website/content/api-docs/secret/transit.mdx index 485a42e5779e..d669821774b7 100644 --- a/website/content/api-docs/secret/transit.mdx +++ b/website/content/api-docs/secret/transit.mdx @@ -65,6 +65,8 @@ values set here cannot be changed after key creation. - `rsa-4096` - RSA with bit size of 4096 (asymmetric) - `hmac` - HMAC (HMAC generation, verification) - `managed_key` - External key configured via the [Managed Keys](/vault/docs/enterprise/managed-keys) feature (enterprise only) + - `aes128-cmac` - AES-128 CMAC (CMAC generation, verification) + - `aes256-cmac` - AES-256 CMAC (CMAC generation, verification) ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `chacha20-poly1305` and `ed25519`. @@ -162,6 +164,8 @@ the hash function defaults to SHA256. - `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) + - `aes128-cmac` - AES-128 CMAC (CMAC generation, verification) + - `aes256-cmac` - AES-256 CMAC (CMAC generation, verification) - `public_key` `(string: "", optional)` - A plaintext PEM public key to be imported. This limits the operations available under this key to verification @@ -573,7 +577,7 @@ the chain as it will overwrite any previously set certificate chain. chain against. If the version is set to `latest` or is not set, the current key will be returned. - - `certificate_chain` `(string: )` - A PEM encoded certificate chain. It should be composed + - `certificate_chain` `(string: )` - A PEM encoded certificate chain. It should be composed by one or more concatenated PEM blocks and ordered starting from the end-entity certificate. ### Sample request @@ -662,6 +666,7 @@ be valid. asymmetric keys (EC with NIST P-curves or Ed25519 and RSA). - `certificate-chain`, to return the imported certificate chain (via `set-certificate`) corresponding to this key and version. + - `cmac-key` - `name` `(string: )` – Specifies the name of the key to read information about. This is specified as part of the URL. @@ -1759,6 +1764,117 @@ $ curl \ } ``` +## Generate CMAC + +This endpoint returns the CMAC of given data using the specified key. + +| Method | Path | +| :----- | :-------------------------------------- | +| `POST` | `/transit/cmac/:name(/:url_mac_length)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the key to use for the + CMAC function. This is specified as part of the URL. + +- `key_version` `(int: 0)` – Specifies the version of the key to use for the + operation. If not set, uses the latest version. Must be greater than or equal + to the key's `min_encryption_version`, if set. + +- `input` `(string: "")` – Specifies the **base64 encoded** input data. One of + `input` or `batch_input` must be supplied. + +- `mac_length` (int: 0) - Specifies the MAC length to use (POST body parameter). + The `mac_length` cannot be larger than the cipher's block size. + +- `url_mac_length` (int: 0): Specifies the MAC length to use (URL parameter). + If provided, this value overrides `mac_length`. The `url_mac_length` cannot + be larger than the cipher's block size. + +- `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 + 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 + { + "batch_input": [ + { + "input": "adba32==" + }, + { + "input": "aGVsbG8gd29ybGQuCg==" + } + ] + } + ``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/transit/cmac/my-key +``` + +### Sample payload + +```json +{ + "input": "adba32==" +} +``` + +### Sample response + +```json +{ + "data": { + "cmac": "vault:v1:adba343QQ6XPDzm3V5XG9aOdQS0=" + } +} +``` + +### Sample payload with batch_input + +```json +{ + "batch_input": [ + { + "input": "adba32==" + }, + { + "input": "adba32==", + "mac_length": 8 + } + ] +} +``` + +### Sample response for batch_input + +```json +{ + "data": { + "batch_results": [ + { + "reference": "", + "cmac": "vault:v1:adba343QQ6XPDzm3V5XG9aOdQS0=" + }, + { + "reference": "", + "cmac": "vault:v1:adba343QQ6XPDzm3" + } + ] + } +} +``` + ## Backup key This endpoint returns a plaintext backup of a named key. The backup contains all diff --git a/website/content/docs/secrets/transit/index.mdx b/website/content/docs/secrets/transit/index.mdx index 3dfdd46402e4..162b2356bc6d 100644 --- a/website/content/docs/secrets/transit/index.mdx +++ b/website/content/docs/secrets/transit/index.mdx @@ -89,6 +89,8 @@ types also generate separate HMAC keys): - `managed_key`: Managed key; supports a variety of operations depending on the backing key management solution. See [Managed Keys](/vault/docs/enterprise/managed-keys) for more information. +- `aes128-cmac`: CMAC with a 128-bit AES key; supporting CMAC generation and verification. +- `aes256-cmac`: CMAC with a 256-bit AES key; supporting CMAC generation and verification. ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: `chacha20-poly1305` and `ed25519`.