Unwrap a key with AES-GCM using CloudHSM CLI - AWS CloudHSM
User typeRequirementsSyntaxExamplesArgumentsRelated topics

Unwrap a key with AES-GCM using CloudHSM CLI

Use the key unwrap aes-gcm command in CloudHSM CLI to unwrap a payload key into the cluster using the AES wrapping key and the AES-GCM unwrapping mechanism.

Unwrapped keys can be used in the same ways as the keys generated by AWS CloudHSM. To indicate that they were not generated locally, their local attribute is set to false.

To use the key unwrap aes-gcm command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its unwrap attribute must be set to true.

User type

The following types of users can run this command.

  • Crypto users (CUs)

Requirements

  • To run this command, you must be logged in as a CU.

Syntax

aws-cloudhsm > help key unwrap aes-gcm
Usage: key unwrap aes-gcm [OPTIONS] --filter [<FILTER>...] --tag-length-bits <TAG_LENGTH_BITS> --key-type-class <KEY_TYPE_CLASS> --label <LABEL> --iv <IV> <--data-path <DATA_PATH>|--data <DATA>>

Options:
      --cluster-id <CLUSTER_ID>
          Unique Id to choose which of the clusters in the config file to run the operation against. If not provided, will fall back to the value provided when interactive mode was started, or error
      --filter [<FILTER>...]
          Key reference (e.g. key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with
      --data-path <DATA_PATH>
          Path to the binary file containing the wrapped key data
      --data <DATA>
          Base64 encoded wrapped key data
      --attributes [<UNWRAPPED_KEY_ATTRIBUTES>...]
          Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the unwrapped key
      --share-crypto-users [<SHARE_CRYPTO_USERS;...]
          Space separated list of Crypto User usernames to share the unwrapped key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE;
          The quorum value for key management operations for the unwrapped key
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE;
          The quorum value for key usage operations for the unwrapped key
      --aad <AAD>
          Aes GCM Additional Authenticated Data (AAD) value, in hex
      --tag-length-bits <TAG_LENGTH_BITS>
          Aes GCM tag length in bits
      --key-type-class <KEY_TYPE_CLASS>
          Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private]
      --label <LABEL>
          Label for the unwrapped key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --iv <IV>
          Initial value used to wrap the key, in hex
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help

Examples

These examples show how to use the key unwrap aes-gcm command using an AES key with the unwrap attribute value set to true.

Example: Unwrap a payload key from Base64 encoded wrapped key data
aws-cloudhsm > key unwrap aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64  --aad 0x10 --iv 0xf90613bb8e337ec0339aad21 --data xvslgrtg8kHzrvekny97tLSIeokpPwV8
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001808e4",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}
Example: Unwrap a payload key provided through a data path
aws-cloudhsm > key unwrap aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64  --aad 0x10 --iv 0xf90613bb8e337ec0339aad21 --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001808e4",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [],
        "key-quorum-values": {
          "manage-key-quorum-value": 0,
          "use-key-quorum-value": 0
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "aes-unwrapped",
        "id": "0x",
        "check-value": "0x8d9099",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": false,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    }
  }
}

Arguments

<CLUSTER_ID>

The ID of the cluster to run this operation on.

Required: If multiple clusters have been configured.

<FILTER>

Key reference (for example, key-reference=0xabc) or space separated list of key attributes in the form of attr.KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE to select a key to unwrap with.

Required: Yes

<DATA_PATH>

Path to the binary file containing the wrapped key data.

Required: Yes (unless provided through Base64 encoded data)

<DATA>

Base64 encoded wrapped key data.

Required: Yes (unless provided through data path)

<ATTRIBUTES>

Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the wrapped key.

Required: No

<AAD>

Aes GCM Additional Authenticated Data (AAD) value, in hex.

Required: No

<TAG_LENGTH_BITS>

Aes GCM tag length in bits.

Required: Yes

<KEY_TYPE_CLASS>

Key type and class of wrapped key [possible values: aes, des3, ec-private, generic-secret, rsa-private].

Required: Yes

<LABEL>

Label for the unwrapped key.

Required: Yes

<SESSION>

Creates a session key that exists only in the current session. The key cannot be recovered after the session ends.

Required: No

<IV>

Initial value used to wrap the key, in hex.

Required: No

<APPROVAL>

Specifies the file path to a signed quorum token file to approve operation. Only required if the key management service quorum value of the unwrapping key is greater than 1.

Related topics