# The key category in CloudHSM CLI
<a name="cloudhsm_cli-key"></a>

In the CloudHSM CLI, **key** is a parent category for a group of commands that, when combined with the parent category, create a command specific to keys. Currently, this category consists of the following commands:
+ [delete](cloudhsm_cli-key-delete.md)
+ [generate-file](cloudhsm_cli-key-generate-file.md)
+ [key generate-asymmetric-pair](cloudhsm_cli-key-generate-asymmetric-pair.md)
  + [key generate-asymmetric-pair rsa](cloudhsm_cli-key-generate-asymmetric-pair-rsa.md)
  + [key generate-asymmetric-pair ec](cloudhsm_cli-key-generate-asymmetric-pair-ec.md)
+ [key generate-symmetric](cloudhsm_cli-key-generate-symmetric.md)
  + [key generate-symmetric aes](cloudhsm_cli-key-generate-symmetric-aes.md)
  + [key generate-symmetric generic-secret](cloudhsm_cli-key-generate-symmetric-generic-secret.md)
+ [import pem](cloudhsm_cli-key-import-pem.md)
+ [list](cloudhsm_cli-key-list.md)
+ [replicate](cloudhsm_cli-key-replicate.md)
+ [set-attribute](cloudhsm_cli-key-set-attribute.md)
+ [share](cloudhsm_cli-key-share.md)
+ [unshare](cloudhsm_cli-key-unshare.md)
+ [unwrap](cloudhsm_cli-key-unwrap.md)
+ [wrap](cloudhsm_cli-key-wrap.md)

# Delete a key with CloudHSM CLI
<a name="cloudhsm_cli-key-delete"></a>

Use the **key delete** command in CloudHSM CLI to delete a key from an AWS CloudHSM cluster. You can only delete one key at a time. Deleting one key in a key pair has no effect on the other key in the pair. 

Only the CU who created the key and consequently owns it can delete the key. Users who share the key, but do not own it, can use the key in cryptographic operations, but can not delete it.

## User type
<a name="key-delete-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-delete-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="key-delete-syntax"></a>

```
aws-cloudhsm > help key delete
Delete a key in the HSM cluster

Usage: key delete [OPTIONS] --filter [<FILTER>...]

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 matching key for deletion
  -h, --help                     Print help
```

## Example
<a name="key-delete-examples"></a>

```
aws-cloudhsm > key delete --filter attr.label="ec-test-public-key"
{
  "error_code": 0,
  "data": {
    "message": "Key deleted successfully"
  }
}
```

## Arguments
<a name="key-delete-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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 matching key for deletion.  
For a list of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)  
Required: Yes

## Related topics
<a name="key-delete-seealso"></a>
+ [List keys for a user with CloudHSM CLI](cloudhsm_cli-key-list.md)
+ [Export an asymmetric key with CloudHSM CLI](cloudhsm_cli-key-generate-file.md)
+ [Unshare a key using CloudHSM CLI](cloudhsm_cli-key-unshare.md)
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# Export an asymmetric key with CloudHSM CLI
<a name="cloudhsm_cli-key-generate-file"></a>

Use the **key generate-file** command in CloudHSM CLI to export an asymmetric key from the hardware security module (HSM). If the target is a private key, then the reference to the private key will be exported in fake PEM format. If the target is a public key, then the public key bytes will be exported in PEM format.

The fake PEM file, which does not contain the actual private key material but instead references the private key in the HSM, can be used to establish SSL/TLS offloading from your web server to AWS CloudHSM. For more information, see [SSL/TLS offloading](ssl-offload.md).

## User type
<a name="key-generate-file-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-generate-file-requirements"></a>

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

## Syntax
<a name="key-generate-file-syntax"></a>

```
aws-cloudhsm > help key generate-file
Generate a key file from a key in the HSM cluster. This command does not export any private key data from the HSM

Usage: key generate-file --encoding <ENCODING> --path <PATH> --filter [<FILTER>...]

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
      --encoding <ENCODING>
          Encoding format for the key file

          Possible values:
          - reference-pem: PEM formatted key reference (supports private keys)
          - pem:           PEM format (supports public keys)

      --path <PATH>
          Filepath where the key file will be written

      --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 matching key for file generation

  -h, --help
          Print help (see a summary with '-h')
```

## Example
<a name="key-generate-file-examples"></a>

This example shows how to use **key generate-file** to generate a key file in your AWS CloudHSM cluster.

**Example**  

```
aws-cloudhsm > key generate-file --encoding reference-pem --path /tmp/ec-private-key.pem --filter attr.label="ec-test-private-key"
{
  "error_code": 0,
  "data": {
    "message": "Successfully generated key file"
  }
}
```

## Arguments
<a name="key-generate-file-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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 matching key for deletion.  
For a listing of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)  
Required: No

***<ENCODING>***  
Specifies the encoding format for the key file  
Required: Yes

***<PATH>***  
Specifies the file path where the key file will be written  
Required: Yes

## Generating KSP key references (Windows)
<a name="key-generate-ksp-key-reference"></a>

**Note**  
This feature is only in SDK version 5.16.0 and later.

### Prerequisites
<a name="key-generate-ksp-key-reference-requirements"></a>
+ You can generate KSP key references only on Windows platforms.
+ You must sign in as a crypto user (CU).

### File location
<a name="key-generate-ksp-key-reference-options"></a>

By default, AWS CloudHSM stores generated files in: `C:\Users\Default\AppData\Roaming\Microsoft\Crypto\CaviumKSP\GlobalPartition`

To specify a different location, use the `--path` parameter.

### Syntax
<a name="key-generate-ksp-key-reference-syntax"></a>

```
aws-cloudhsm > help key generate-file --encoding ksp-key-reference 
Generate a key file from a key in the HSM cluster. This command does not export any private key data from the HSM

Usage: key generate-file --encoding <ENCODING> --path <PATH> --filter [<FILTER>...]

Options:
      --encoding <ENCODING>
        Encoding format for the key file

        Possible values:
        - reference-pem:     PEM formatted key reference (supports private keys)
        - pem:               PEM format (supports public keys)
        - ksp-key-reference: KSP key reference format

      --cluster-id <CLUSTER_ID>
        Unique Id to choose which of the clusters in the config file to run the operation against. If not provided with multiple clusters configured, will error

      --path <PATH>
        Directory path where the key file will be written

      --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 matching key for file generation

      --all
        Generate ksp key reference for all available key pairs in HSM

  -h, --help
        Print help (see a summary with '-h')
```

### Example – Generate a KSP key reference using an attribute filter of a private key
<a name="key-generate-ksp-key-reference-example1"></a>

The following example generates a KSP key reference for a private key with a specific label.

**Example**  

```
aws-cloudhsm > key generate-file --encoding ksp-key-reference --path  --filter attr.label="ec-test-private-key"
{
  "error_code": 0,
  "data": {
    "message": "Successfully generated key file"
  }
}
```

### Example – Generate KSP key references for all key pairs
<a name="key-generate-ksp-key-reference-example2"></a>

The following example generates KSP key references for all key pairs in your cluster.

**Example**  

```
aws-cloudhsm > key generate-file --encoding ksp-key-reference --all
{
  "error_code": 0,
  "data": {
    "message": "Successfully generated key file"
  }
}
```

## Related topics
<a name="key-generate-file-seealso"></a>
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)
+ [The generate-asymmetric-pair category in CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair.md)
+ [The generate-symmetric category in CloudHSM CLI](cloudhsm_cli-key-generate-symmetric.md)

# The generate-asymmetric-pair category in CloudHSM CLI
<a name="cloudhsm_cli-key-generate-asymmetric-pair"></a>

In the CloudHSM CLI, **key generate-asymmetric-pair** is a parent category for a group of commands that, when combined with the parent category, create a command that generates asymmetric key pairs. Currently, this category consists of the following commands:
+ [key generate-asymmetric-pair ec](cloudhsm_cli-key-generate-asymmetric-pair-ec.md)
+ [key generate-asymmetric-pair rsa](cloudhsm_cli-key-generate-asymmetric-pair-rsa.md)

# Generate an asymmetric EC key pair with CloudHSM CLI
<a name="cloudhsm_cli-key-generate-asymmetric-pair-ec"></a>

Use the **key asymmetric-pair ec** command in CloudHSM CLI to generate an asymmetric Elliptic-curve (EC) key pair in your AWS CloudHSM cluster.

## User type
<a name="key-generate-asymmetric-pair-ec-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-generate-asymmetric-pair-ec-requirements"></a>

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

## Syntax
<a name="key-generate-asymmetric-pair-ec-syntax"></a>

```
aws-cloudhsm > help key generate-asymmetric-pair ec
Generate an Elliptic-Curve Cryptography (ECC) key pair

Usage: key generate-asymmetric-pair ec [OPTIONS] --public-label <PUBLIC_LABEL> --private-label <PRIVATE_LABEL> --curve <CURVE>

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
      --public-label <PUBLIC_LABEL>
          Label for the public key
      --private-label <PRIVATE_LABEL>
          Label for the private key
      --session
          Creates a session key pair that exists only in the current session. The key cannot be recovered after the session ends
      --curve <CURVE>
          Elliptic curve used to generate the key pair [possible values: prime256v1, secp256r1, secp224r1, secp384r1, secp256k1, secp521r1, ed25519]
      --public-attributes [<PUBLIC_KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated EC public key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --private-attributes [<PRIVATE_KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated EC private key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --share-crypto-users [<SHARE_CRYPTO_USERS>...]
          Space separated list of Crypto User usernames to share the EC private key with
      --manage-private-key-quorum-value <MANAGE_PRIVATE_KEY_QUORUM_VALUE>
          The quorum value for key management operations for the private key
      --use-private-key-quorum-value <USE_PRIVATE_KEY_QUORUM_VALUE>
          The quorum value for key usage operations for the private key
  -h, --help
          Print help
```

## Examples
<a name="key-generate-asymmetric-pair-ec-examples"></a>

These examples show how to use the **key generate-asymmetric-pair ec** command to create an EC key pair.

**Example: Create an EC key pair**  

```
aws-cloudhsm > key generate-asymmetric-pair ec \
    --curve secp224r1 \
    --public-label ec-public-key-example \
    --private-label ec-private-key-example
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x000000000012000b",
      "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": "ec",
        "label": "ec-public-key-example",
        "id": "",
        "check-value": "0xd7c1a7",
        "class": "public-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 57,
        "ec-point": "0x047096513df542250a6b228fd9cb67fd0c903abc93488467681974d6f371083fce1d79da8ad1e9ede745fb9f38ac8622a1b3ebe9270556000c",
        "curve": "secp224r1"
      }
    },
"private_key": {
      "key-reference": "0x000000000012000c",
      "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": "ec",
        "label": "ec-private-key-example",
        "id": "",
        "check-value": "0xd7c1a7",
        "class": "private-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 122,
        "ec-point": "0x047096513df542250a6b228fd9cb67fd0c903abc93488467681974d6f371083fce1d79da8ad1e9ede745fb9f38ac8622a1b3ebe9270556000c",
        "curve": "secp224r1"
      }
    }
  }
}
```

**Example: Create an EC key pair with optional attributes**  

```
aws-cloudhsm > key generate-asymmetric-pair ec \
    --curve secp224r1 \
    --public-label ec-public-key-example \
    --private-label ec-private-key-example \
    --public-attributes encrypt=true \
    --private-attributes decrypt=true
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x00000000002806eb",
      "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": "ec",
        "label": "ec-public-key-example",
        "id": "",
        "check-value": "0xedef86",
        "class": "public-key",
        "encrypt": true,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 57,
        "ec-point": "0x0487af31882189ec29eddf17a48e8b9cebb075b7b5afc5522fe9c83a029a450cc68592889a1ebf45f32240da5140d58729ffd7b2d44262ddb8",
        "curve": "secp224r1"
      }
    },
    "private_key": {
      "key-reference": "0x0000000000280c82",
      "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": "ec",
        "label": "ec-private-key-example",
        "id": "",
        "check-value": "0xedef86",
        "class": "private-key",
        "encrypt": false,
        "decrypt": true,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 122,
        "ec-point": "0x0487af31882189ec29eddf17a48e8b9cebb075b7b5afc5522fe9c83a029a450cc68592889a1ebf45f32240da5140d58729ffd7b2d44262ddb8",
        "curve": "secp224r1"
      }
    }
  }
}
```

**Example: Create an EC key pair with quorum values**  
When generating a key with quorum controls, the key must be associated with a minimum number of users equal to the largest key quorum value. Associated users include the key owner and Crypto Users with whom the key is shared with. To determine the number of minimum users to share the key with, get the largest quorum value between the key usage quorum value and the key management quorum value and subtract 1 to account for the key owner, who is by default associated with the key. To share the key with more users, use the **[Share a key using CloudHSM CLI](cloudhsm_cli-key-share.md)** command.  

```
aws-cloudhsm > key generate-asymmetric-pair ec \
    --curve secp224r1 \
    --public-label ec-public-key-example \
    --private-label ec-private-key-example \
    --public-attributes verify=true \
    --private-attributes sign=true
    --share-crypto-users cu2 cu3 cu4 \
    --manage-private-key-quorum-value 4 \
    --use-private-key-quorum-value 2
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x00000000002806eb",
      "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": "ec",
        "label": "ec-public-key-example",
        "id": "",
        "check-value": "0xedef86",
        "class": "public-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 57,
        "ec-point": "0x0487af31882189ec29eddf17a48e8b9cebb075b7b5afc5522fe9c83a029a450cc68592889a1ebf45f32240da5140d58729ffd7b2d44262ddb8",
        "curve": "secp224r1"
      }
    },
    "private_key": {
      "key-reference": "0x0000000000280c82",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [
          {
            "username": "cu2",
            "key-coverage": "full"
          },
          {
            "username": "cu3",
            "key-coverage": "full"
          },
          {
            "username": "cu4",
            "key-coverage": "full"
          },
        ],
        "key-quorum-values": {
          "manage-key-quorum-value": 4,
          "use-key-quorum-value": 2
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "ec",
        "label": "ec-private-key-example",
        "id": "",
        "check-value": "0xedef86",
        "class": "private-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 122,
        "ec-point": "0x0487af31882189ec29eddf17a48e8b9cebb075b7b5afc5522fe9c83a029a450cc68592889a1ebf45f32240da5140d58729ffd7b2d44262ddb8",
        "curve": "secp224r1"
      }
    }
  }
}
```

## Arguments
<a name="key-generate-asymmetric-pair-ec-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<CURVE>***  
Specifies the identifier for the elliptic curve.  
+ prime256v1
+ secp256r1
+ secp224r1
+ secp384r1
+ secp256k1
+ secp521r1
+ ed25519 (only supported on hsm2m.medium instances in non-FIPS mode)
Required: Yes

***<PUBLIC\$1KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated EC public key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `verify=true`)  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<PUBLIC\$1LABEL>***  
Specifies a user defined label for the public-key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<PRIVATE\$1KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated EC private key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `sign=true`)  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<PRIVATE\$1LABEL>***  
Specifies a user defined label for the private-key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<SESSION>***  
Creates a key that exists only in the current session. The key cannot be recovered after the session ends.  
Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.  
By default, keys that are generated are persistent (token) keys. Passing in <SESSION> changes this, ensuring a key generated with this argument is a session (ephemeral) key.  
Required: No

***<SHARE\$1CRYPTO\$1USERS>***  
Specifies a space separated list of Crypto User usernames to share the EC private key with  
Required: No

***<MANAGE\$1PRIVATE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for the private key's key management operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

***<USE\$1PRIVATE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for private key's key usage operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

## Related topics
<a name="key-generate-asymmetric-pair-ec-seealso"></a>
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# Generate an asymmetric RSA key pair with CloudHSM CLI
<a name="cloudhsm_cli-key-generate-asymmetric-pair-rsa"></a>

Use the **key generate-asymmetric-pair rsa** command in CloudHSM CLI to generate an asymmetric RSA key pair in your AWS CloudHSM cluster.

## User type
<a name="key-generate-asymmetric-pair-rsa-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-generate-asymmetric-pair-rsa-requirements"></a>

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

## Syntax
<a name="key-generate-asymmetric-pair-rsa-syntax"></a>

```
aws-cloudhsm > help key generate-asymmetric-pair rsa
Generate an RSA key pair

Usage: key generate-asymmetric-pair rsa [OPTIONS] --public-label <PUBLIC_LABEL> --private-label <PRIVATE_LABEL> --modulus-size-bits <MODULUS_SIZE_BITS> --public-exponent <PUBLIC_EXPONENT>

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
      --public-label <PUBLIC_LABEL>
          Label for the public key
      --private-label <PRIVATE_LABEL>
          Label for the private key
      --session
          Creates a session key pair that exists only in the current session. The key cannot be recovered after the session ends
      --modulus-size-bits <MODULUS_SIZE_BITS>
          Modulus size in bits used to generate the RSA key pair
      --public-exponent <PUBLIC_EXPONENT>
          Public exponent used to generate the RSA key pair
      --public-attributes [<PUBLIC_KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated RSA public key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --private-attributes [<PRIVATE_KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated RSA private key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --share-crypto-users [<SHARE_CRYPTO_USERS>...]
          Space separated list of Crypto User usernames to share the RSA key with
      --manage-private-key-quorum-value <MANAGE_PRIVATE_KEY_QUORUM_VALUE>
          The quorum value for key management operations for the private key
      --use-private-key-quorum-value <USE_PRIVATE_KEY_QUORUM_VALUE>
          The quorum value for key usage operations for the private key
  -h, --help
          Print help
```

## Examples
<a name="key-generate-asymmetric-pair-rsa-examples"></a>

These examples show how to use `key generate-asymmetric-pair rsa` to create a RSA key pair.

**Example: Create an RSA key pair**  

```
aws-cloudhsm > key generate-asymmetric-pair rsa \
--public-exponent 65537 \
--modulus-size-bits 2048 \
--public-label rsa-public-key-example \
--private-label rsa-private-key-example
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x0000000000160010",
      "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": "rsa",
        "label": "rsa-public-key-example",
        "id": "",
        "check-value": "0x498e1f",
        "class": "public-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 512,
        "public-exponent": "0x010001",
        "modulus": "0xdfca0669dc8288ed3bad99509bd21c7e6192661407021b3f4cdf4a593d939dd24f4d641af8e4e73b04c847731c6dbdff3385818e08dd6efcbedd6e5b130344968c
e89a065e7d1a46ced96b46b909db2ab6be871ee700fd0a448b6e975bb64cae77c49008749212463e37a577baa57ce3e574cb057e9db131e119badf50c938f26e8a5975c61a8ba7ffe7a1115a
bcebb7d20bd6df1948ae336ae23b52d73b7f3b6acc2543edb6358e08d326d280ce489571f4d34e316a2ea1904d513ca12fa04075fc09ad005c81b7345d7804ff24c45117f0a1020dca7794df037a10aadec8653473b2088711f7b7d8b58431654e14e31af0e00511da641058fb7475ffdbe60f",
        "modulus-size-bits": 2048
      }
    },
"private_key": {
      "key-reference": "0x0000000000160011",
      "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": "rsa",
        "label": "rsa-private-key-example",
        "id": "",
        "check-value": "0x498e1f",
        "class": "private-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 1217,
        "public-exponent": "0x010001",
        "modulus": "0xdfca0669dc8288ed3bad99509bd21c7e6192661407021b3f4cdf4a593d939dd24f4d641af8e4e73b04c847731c6dbdff3385818e08dd6efcbedd6e5b130344968ce89a065e7d1a46ced96b46b909db2ab6be871ee700fd0a448b6e975bb64cae77c49008749212463e37a577baa57ce3e574cb057e9db131e119badf50c938f26e8a5975c61a8ba7ffe7a1115abcebb7d20bd6df1948ae336ae23b52d73b7f3b6acc2543edb6358e08d326d280ce489571f4d34e316a2ea1904d513ca12fa04075fc09ad005c81b7345d7804ff24c45117f0a1020dca7794df037a10aadec8653473b2088711f7b7d8b58431654e14e31af0e00511da641058fb7475ffdbe60f",
        "modulus-size-bits": 2048
      }
    }
  }
}
```

**Example: Create an RSA key pair with optional attributes**  

```
aws-cloudhsm > key generate-asymmetric-pair rsa \
--public-exponent 65537 \
--modulus-size-bits 2048 \
--public-label rsa-public-key-example \
--private-label rsa-private-key-example \
--public-attributes encrypt=true \
--private-attributes decrypt=true
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x0000000000280cc8",
      "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": "rsa",
        "label": "rsa-public-key-example",
        "id": "",
        "check-value": "0x01fe6e",
        "class": "public-key",
        "encrypt": true,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 512,
        "public-exponent": "0x010001",
        "modulus": "0xb1d27e857a876f4e9fd5de748a763c539b359f937eb4b4260e30d1435485a732c878cdad9c72538e2215351b1d41358c9bf80b599c
73a80fdb457aa7b20cd61e486c326e2cfd5e124a7f6a996437437812b542e3caf85928aa866f0298580f7967ee6aa01440297d7308fdd9b76b70d1b67f12634d
f6e6296d6c116d5744c6d60d14d3bf3cb978fe6b75ac67b7089bafd50d8687213b31abc7dc1bad422780d29c851d5102b56f932551eaf52a9591fd8c43d81ecc
133022653225bd129f8491101725e9ea33e1ded83fb57af35f847e532eb30cd7e726f23910d2671c6364092e834697ec3cef72cc23615a1ba7c5e100156ae0ac
ac3160f0ca9725d38318b7",
        "modulus-size-bits": 2048
      }
    },
    "private_key": {
      "key-reference": "0x0000000000280cc7",
      "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": "rsa",
        "label": "rsa-private-key-example",
        "id": "",
        "check-value": "0x01fe6e",
        "class": "private-key",
        "encrypt": false,
        "decrypt": true,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 1217,
        "public-exponent": "0x010001",
        "modulus": "0xb1d27e857a876f4e9fd5de748a763c539b359f937eb4b4260e30d1435485a732c878cdad9c72538e2215351b1d41358c9bf80b599c73a80fdb457aa7b20cd61e486c326e2cfd5e124a7f6a996437437812b542e3caf85928aa866f0298580f7967ee6aa01440297d7308fdd9b76b70d1b67f12634df6e6296d6c116d5744c6d60d14d3bf3cb978fe6b75ac67b7089bafd50d8687213b31abc7dc1bad422780d29c851d5102b56f932551eaf52a9591fd8c43d81ecc133022653225bd129f8491101725e9ea33e1ded83fb57af35f847e532eb30cd7e726f23910d2671c6364092e834697ec3cef72cc23615a1ba7c5e100156ae0acac3160f0ca9725d38318b7",
        "modulus-size-bits": 2048
      }
    }
  }
}
```

**Example: Create an RSA key pair with quorum values**  
When generating a key with quorum controls, the key must be associated with a minimum number of users equal to the largest key quorum value. Associated users include the key owner and Crypto Users with whom the key is shared with. To determine the number of minimum users to share the key with, get the largest quorum value between the key usage quorum value and the key management quorum value and subtract 1 to account for the key owner, who is by default associated with the key. To share the key with more users, use the **[Share a key using CloudHSM CLI](cloudhsm_cli-key-share.md)** command.  

```
aws-cloudhsm > key generate-asymmetric-pair rsa \
--public-exponent 65537 \
--modulus-size-bits 2048 \
--public-label rsa-public-key-example \
--private-label rsa-private-key-example \
--public-attributes verify=true \
--private-attributes sign=true
--share-crypto-users cu2 cu3 cu4 \
--manage-private-key-quorum-value 4 \
--use-private-key-quorum-value 2
{
  "error_code": 0,
  "data": {
    "public_key": {
      "key-reference": "0x0000000000280cc8",
      "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": "rsa",
        "label": "rsa-public-key-example",
        "id": "",
        "check-value": "0x01fe6e",
        "class": "public-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": false,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": false,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 512,
        "public-exponent": "0x010001",
        "modulus": "0xb1d27e857a876f4e9fd5de748a763c539b359f937eb4b4260e30d1435485a732c878cdad9c72538e2215351b1d41358c9bf80b599c
73a80fdb457aa7b20cd61e486c326e2cfd5e124a7f6a996437437812b542e3caf85928aa866f0298580f7967ee6aa01440297d7308fdd9b76b70d1b67f12634d
f6e6296d6c116d5744c6d60d14d3bf3cb978fe6b75ac67b7089bafd50d8687213b31abc7dc1bad422780d29c851d5102b56f932551eaf52a9591fd8c43d81ecc
133022653225bd129f8491101725e9ea33e1ded83fb57af35f847e532eb30cd7e726f23910d2671c6364092e834697ec3cef72cc23615a1ba7c5e100156ae0ac
ac3160f0ca9725d38318b7",
        "modulus-size-bits": 2048
      }
    },
    "private_key": {
      "key-reference": "0x0000000000280cc7",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [
          {
            "username": "cu2",
            "key-coverage": "full"
          },
          {
            "username": "cu3",
            "key-coverage": "full"
          },
          {
            "username": "cu4",
            "key-coverage": "full"
          },
        ],
        "key-quorum-values": {
          "manage-key-quorum-value": 4,
          "use-key-quorum-value": 2
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "rsa",
        "label": "rsa-private-key-example",
        "id": "",
        "check-value": "0x01fe6e",
        "class": "private-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": false,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 1217,
        "public-exponent": "0x010001",
        "modulus": "0xb1d27e857a876f4e9fd5de748a763c539b359f937eb4b4260e30d1435485a732c878cdad9c72538e2215351b1d41358c9bf80b599c73a80fdb457aa7b20cd61e486c326e2cfd5e124a7f6a996437437812b542e3caf85928aa866f0298580f7967ee6aa01440297d7308fdd9b76b70d1b67f12634df6e6296d6c116d5744c6d60d14d3bf3cb978fe6b75ac67b7089bafd50d8687213b31abc7dc1bad422780d29c851d5102b56f932551eaf52a9591fd8c43d81ecc133022653225bd129f8491101725e9ea33e1ded83fb57af35f847e532eb30cd7e726f23910d2671c6364092e834697ec3cef72cc23615a1ba7c5e100156ae0acac3160f0ca9725d38318b7",
        "modulus-size-bits": 2048
      }
    }
  }
}
```

## Arguments
<a name="key-generate-asymmetric-pair-rsa-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<MODULUS\$1SIZE\$1BITS>***  
 Specifies the length of the modulus in bits. The minimum value is 2048.   
Required: Yes

***<PRIVATE\$1KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated RSA private key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `sign=true`)  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<PRIVATE\$1LABEL>***  
 Specifies a user defined label for the private-key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<PUBLIC\$1EXPONENT>***  
Specifies the public exponent. The value must be an odd number greater than or equal to 65537.  
Required: Yes

***<PUBLIC\$1KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated RSA public key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `verify=true`)  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<PUBLIC\$1LABEL>***  
 Specifies a user defined label for the public-key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<SESSION>***  
Creates a key that exists only in the current session. The key cannot be recovered after the session ends.  
Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.  
By default, keys that are generated are persistent (token) keys. Passing in <SESSION> changes this, ensuring a key generated with this argument is a session (ephemeral) key.  
Required: No

***<SHARE\$1CRYPTO\$1USERS>***  
Specifies a space separated list of Crypto User usernames to share the RSA private key with  
Required: No

***<MANAGE\$1PRIVATE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for the private key's key management operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

***<USE\$1PRIVATE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for private key's key usage operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

## Related topics
<a name="key-generate-asymmetric-pair-rsa-seealso"></a>
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# The generate-symmetric category in CloudHSM CLI
<a name="cloudhsm_cli-key-generate-symmetric"></a>

In the CloudHSM CLI, **key generate-symmetric** is a parent category for a group of commands that, when combined with the parent category, create a command that generates symmetric keys. Currently, this category consists of the following commands:
+ [key generate-symmetric aes](cloudhsm_cli-key-generate-symmetric-aes.md)
+ [key generate-symmetric generic-secret](cloudhsm_cli-key-generate-symmetric-generic-secret.md)

# Generate a symmetric AES key with CloudHSM CLI
<a name="cloudhsm_cli-key-generate-symmetric-aes"></a>

Use the **key generate-symmetric aes** command in CloudHSM CLI to generate a symmetric AES key in your AWS CloudHSM cluster.

## User type
<a name="key-generate-symmetric-aes-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-generate-symmetric-aes-requirements"></a>

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

## Syntax
<a name="key-generate-symmetric-aes-syntax"></a>

```
aws-cloudhsm > help key generate-symmetric aes
Generate an AES key

Usage: key generate-symmetric aes [OPTIONS] --label <LABEL> --key-length-bytes <KEY_LENGTH_BYTES>

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
      --label <LABEL>
          Label for the key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --key-length-bytes <KEY_LENGTH_BYTES>
          Key length in bytes
      --attributes [<KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated AES key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --share-crypto-users [<SHARE_CRYPTO_USERS>...]
          Space separated list of Crypto User usernames to share the AES key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE>
          The quorum value for key management operations
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE>
          The quorum value for key usage operations
  -h, --help
          Print help
```

## Examples
<a name="key-generate-symmetric-aes-examples"></a>

These examples show how to use the **key generate-symmetric aes** command to create an AES key.

**Example: Create an AES key**  

```
aws-cloudhsm > key generate-symmetric aes \
--label example-aes \
--key-length-bytes 24
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e06bf",
      "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": "example-aes",
        "id": "",
        "check-value": "0x9b94bd",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "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": 24
      }
    }
  }
}
```

**Example: Create an AES key with optional attributes**  

```
aws-cloudhsm > key generate-symmetric aes \
--label example-aes \
--key-length-bytes 24 \
--attributes decrypt=true encrypt=true
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e06bf",
      "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": "example-aes",
        "id": "",
        "check-value": "0x9b94bd",
        "class": "secret-key",
        "encrypt": true,
        "decrypt": true,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "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": 24
      }
    }
  }
}
```

**Example: Create an AES key with quorum values**  
When generating a key with quorum controls, the key must be associated with a minimum number of users equal to the largest key quorum value. Associated users include the key owner and Crypto Users with whom the key is shared with. To determine the number of minimum users to share the key with, get the largest quorum value between the key usage quorum value and the key management quorum value and subtract 1 to account for the key owner, who is by default associated with the key. To share the key with more users, use the **[Share a key using CloudHSM CLI](cloudhsm_cli-key-share.md)** command.  

```
aws-cloudhsm > key generate-symmetric aes \
--label example-aes \
--key-length-bytes 24 \
--attributes decrypt=true encrypt=true
--share-crypto-users cu2 cu3 cu4 \
--manage-key-quorum-value 4 \
--use-key-quorum-value 2
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e06bf",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [
          {
            "username": "cu2",
            "key-coverage": "full"
          },
          {
            "username": "cu3",
            "key-coverage": "full"
          },
          {
            "username": "cu4",
            "key-coverage": "full"
          },
        ],
        "key-quorum-values": {
          "manage-key-quorum-value": 4,
          "use-key-quorum-value": 2
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "aes",
        "label": "example-aes",
        "id": "",
        "check-value": "0x9b94bd",
        "class": "secret-key",
        "encrypt": true,
        "decrypt": true,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "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": 24
      }
    }
  }
}
```

## Arguments
<a name="key-generate-symmetric-aes-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated AES key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `sign=true`).  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<KEY-LENGTH-BYTES>***  
Specifies the key length in bytes.  

Valid values:
+ 16, 24, and 32
Required: Yes

***<LABEL>***  
Specifies a user defined label for the AES key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<SESSION>***  
Creates a key that exists only in the current session. The key cannot be recovered after the session ends.  
Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.  
By default, keys that are generated are persistent (token) keys. Passing in <SESSION> changes this, ensuring a key generated with this argument is a session (ephemeral) key.  
Required: No

***<SHARE\$1CRYPTO\$1USERS>***  
Specifies a space separated list of Crypto User usernames to share the AES key with  
Required: No

***<MANAGE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for key management operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

***<USE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for key usage operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

## Related topics
<a name="key-generate-symmetric-aes-seealso"></a>
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# Generate a symmetric Generic Secret key with CloudHSM CLI
<a name="cloudhsm_cli-key-generate-symmetric-generic-secret"></a>

Use the **key generate-symmetric generic-secret** command in CloudHSM CLI to generate a symmetric Generic Secret key in your AWS CloudHSM cluster.

## User type
<a name="key-generate-symmetric-generic-secret-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="key-generate-symmetric-generic-secret-requirements"></a>

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

## Syntax
<a name="key-generate-symmetric-generic-secret-syntax"></a>

```
aws-cloudhsm > key help generate-symmetric generic-secret
Generate a generic secret key

Usage: key generate-symmetric generic-secret [OPTIONS] --label <LABEL> --key-length-bytes <KEY_LENGTH_BYTES>

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
      --label <LABEL>
          Label for the key
      --session
          Creates a session key that exists only in the current session. The key cannot be recovered after the session ends
      --key-length-bytes <KEY_LENGTH_BYTES>
          Key length in bytes
      --attributes [<KEY_ATTRIBUTES>...]
          Space separated list of key attributes to set for the generated generic secret key in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE
      --share-crypto-users [<SHARE_CRYPTO_USERS>...]
          Space separated list of Crypto User usernames to share the generic secret key with
      --manage-key-quorum-value <MANAGE_KEY_QUORUM_VALUE>
          The quorum value for key management operations
      --use-key-quorum-value <USE_KEY_QUORUM_VALUE>
          The quorum value for key usage operations
  -h, --help
          Print help
```

## Examples
<a name="key-generate-symmetric-generic-secret-examples"></a>

These examples show how to use the **key generate-symmetric generic-secret** command to create a generic secret key.

**Example: Create a generic secret key**  

```
aws-cloudhsm > key generate-symmetric generic-secret \
--label example-generic-secret \
--key-length-bytes 256
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e08fd",
      "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": "generic-secret",
        "label": "example-generic-secret",
        "id": "",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "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": 256
      }
    }
  }
}
```

**Example: Create a generic secret key with optional attributes**  

```
aws-cloudhsm > key generate-symmetric generic-secret \
--label example-generic-secret \
--key-length-bytes 256 \
--attributes encrypt=true
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e08fd",
      "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": "generic-secret",
        "label": "example-generic-secret",
        "id": "",
        "class": "secret-key",
        "encrypt": true,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "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": 256
      }
    }
  }
}
```

**Example: Create a generic secret key with quorum values**  
When generating a key with quorum controls, the key must be associated with a minimum number of users equal to the largest key quorum value. Associated users include the key owner and Crypto Users with whom the key is shared with. To determine the number of minimum users to share the key with, get the largest quorum value between the key usage quorum value and the key management quorum value and subtract 1 to account for the key owner, who is by default associated with the key. To share the key with more users, use the **[Share a key using CloudHSM CLI](cloudhsm_cli-key-share.md)** command.  

```
aws-cloudhsm > key generate-symmetric generic-secret \
--label example-generic-secret \
--key-length-bytes 256 \
--attributes encrypt=true
--share-crypto-users cu2 cu3 cu4 \
--manage-key-quorum-value 4 \
--use-key-quorum-value 2
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000002e08fd",
      "key-info": {
        "key-owners": [
          {
            "username": "cu1",
            "key-coverage": "full"
          }
        ],
        "shared-users": [
          {
            "username": "cu2",
            "key-coverage": "full"
          },
          {
            "username": "cu3",
            "key-coverage": "full"
          },
          {
            "username": "cu4",
            "key-coverage": "full"
          },
        ],
        "key-quorum-values": {
          "manage-key-quorum-value": 4,
          "use-key-quorum-value": 2
        },
        "cluster-coverage": "full"
      },
      "attributes": {
        "key-type": "generic-secret",
        "label": "example-generic-secret",
        "id": "",
        "class": "secret-key",
        "encrypt": true,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "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": 256
      }
    }
  }
}
```

## Arguments
<a name="key-generate-symmetric-generic-secret-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the generated AES key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `sign=true`).  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

***<KEY-LENGTH-BYTES>***  
Specifies the key length in bytes.  

Valid values:
+ 1 to 800
Required: Yes

***<LABEL>***  
Specifies a user defined label for the generic secret key. The maximum size allowable for `label` is 127 characters for Client SDK 5.11 and after. Client SDK 5.10 and before has a limit of 126 characters.  
Required: Yes

***<SESSION>***  
Creates a key that exists only in the current session. The key cannot be recovered after the session ends.  
Use this parameter when you need a key only briefly, such as a wrapping key that encrypts, and then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to decrypt after the session ends.  
By default, keys that are generated are persistent (token) keys. Passing in <SESSION> changes this, ensuring a key generated with this argument is a session (ephemeral) key.  
Required: No

***<SHARE\$1CRYPTO\$1USERS>***  
Space separated list of Crypto User usernames to share the generic secret key with  
Required: No

***<MANAGE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for key management operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

***<USE\$1KEY\$1QUORUM\$1VALUE>***  
The quorum value for key usage operations. This value must be less than or equal to the number of users that the key is associated with. This includes users with whom the key is shared with and the key owner. Max value of 8.  
Required: No

## Related topics
<a name="key-generate-symmetric-generic-secret-seealso"></a>
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# Import a PEM format key with CloudHSM CLI
<a name="cloudhsm_cli-key-import-pem"></a>

Use the **key import pem** command in AWS CloudHSM to import a PEM format key into a hardware security module (HSM). You can use it to import public keys that were generated outside of the HSM.

**Note**  
Use the [Export an asymmetric key with CloudHSM CLI](cloudhsm_cli-key-generate-file.md) command to create a standard PEM file from a public key or to create a reference PEM file from a private key.

## User type
<a name="cloudhsm_cli-key-import-pem-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-import-pem-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-import-pem-syntax"></a>

```
aws-cloudhsm > help key import pem
Import key from a PEM file

Usage: key import pem [OPTIONS] --path <PATH> --label <LABEL> --key-type-class <KEY_TYPE_CLASS>
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
      --path <PATH>
          Path where the key is located in PEM format
      --label <LABEL>
          Label for the imported key
      --key-type-class <KEY_TYPE_CLASS>
          Key type and class of the imported key [possible values: ec-public, rsa-public]
      --attributes [<IMPORT_KEY_ATTRIBUTES>...]
          Space separated list of key attributes in the form of KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE for the imported key
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-import-pem-examples"></a>

These example shows how to use the **key import pem** command to import an RSA public key from a file in PEM format.

**Example: Import an RSA public key**  

```
aws-cloudhsm > key import pem --path /home/example --label example-imported-key --key-type-class rsa-public
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001e08e3",
      "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": "rsa",
        "label": "example-imported-key",
        "id": "0x",
        "check-value": "0x99fe93",
        "class": "public-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": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": false,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 512,
        "public-exponent": "0x010001",
        "modulus": "0x8e9c172c37aa22ed1ce25f7c3a7c936dadc532201400128b044ebb4b96│··3e4930ab910df5a2896eaeb8853cfea0e341227654a8337a7864cc8a87d136f006cfba9e68d0b329│··746c1ad60941668b18699fc8169ff1ec363d0d18292845b2454d6a0b8c5d111b79c047619d460cdf│··be59debbacb66b7abeaf3f3d35dd2b9cfa6b6b7b1258b6866cb4085ac749e9d8552b3a4509e1b86c│··828cc794e22767b4f6b5bc6ff5c96f4b7e60eab305d669cfa2197e85379cb35c659bb58fcd246d48│··d9f6a7f36063b42da025459275aa8e3abedad775387086bd6c198ded868403f4b87ffda5a2d455ac│··aa6cbd00003c31d8d2f51d10cd272b31cf0c4037791f48ad51fb35",
        "modulus-size-bits": 2048
      }
    },
    "message": "Successfully imported key"
  }
}
```

**Example: Import an RSA public key with optional attributes**  

```
aws-cloudhsm > key import pem --path /home/example --label example-imported-key-with-attributes --key-type-class rsa-public --attributes verify=true
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001e08e3",
      "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": "rsa",
        "label": "example-imported-key-with-attributes",
        "id": "0x",
        "check-value": "0x99fe93",
        "class": "public-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": false,
        "sign": false,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 512,
        "public-exponent": "0x010001",
        "modulus": "0x8e9c172c37aa22ed1ce25f7c3a7c936dadc532201400128b044ebb4b96│··3e4930ab910df5a2896eaeb8853cfea0e341227654a8337a7864cc8a87d136f006cfba9e68d0b329│··746c1ad60941668b18699fc8169ff1ec363d0d18292845b2454d6a0b8c5d111b79c047619d460cdf│··be59debbacb66b7abeaf3f3d35dd2b9cfa6b6b7b1258b6866cb4085ac749e9d8552b3a4509e1b86c│··828cc794e22767b4f6b5bc6ff5c96f4b7e60eab305d669cfa2197e85379cb35c659bb58fcd246d48│··d9f6a7f36063b42da025459275aa8e3abedad775387086bd6c198ded868403f4b87ffda5a2d455ac│··aa6cbd00003c31d8d2f51d10cd272b31cf0c4037791f48ad51fb35",
        "modulus-size-bits": 2048
      }
    },
    "message": "Successfully imported key"
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-import-pem-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PATH>***  
Specifies the file path where the key file is located.  
Required: Yes

***<LABEL>***  
Specifies a user defined label for the imported key. The maximum size allowable for `label` is 126 characters.  
Required: Yes

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key.  
Possible values:  
+ ec-public
+ rsa-public
Required: Yes

***<IMPORT\$1KEY\$1ATTRIBUTES>***  
Specifies a space separated list of key attributes to set for the imported key in the form of `KEY_ATTRIBUTE_NAME=KEY_ATTRIBUTE_VALUE` (for example, `sign=true`). For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: No

## Related topics
<a name="cloudhsm_cli-key-import-pem-seealso"></a>
+ [The crypto sign category in CloudHSM CLI](cloudhsm_cli-crypto-sign.md)
+ [The crypto verify category in CloudHSM CLI](cloudhsm_cli-crypto-verify.md)

# List keys for a user with CloudHSM CLI
<a name="cloudhsm_cli-key-list"></a>

Use the **key list** command in CloudHSM CLI to find all keys for the current user present in your AWS CloudHSM cluster. The output includes keys that the user owns and shares, as well as all public keys in the CloudHSM cluster.

## User type
<a name="chsm-cli-key-list-user-type"></a>

The following types of users can run this command.
+ Admins (COs)
+ Crypto users (CUs)

## Syntax
<a name="chsm-cli-key-list-syntax"></a>

```
aws-cloudhsm > help key list
List the keys the current user owns, shares, and all public keys in the HSM cluster

Usage: key list [OPTIONS]

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 matching key(s) to list
      --max-items <MAX_ITEMS>
          The total number of items to return in the command's output. If the total number of items available is more than the value specified, a next-token is provided in the command's output. To resume pagination, provide the next-token value in the starting-token argument of a subsequent command [default: 10]
      --starting-token <STARTING_TOKEN>
          A token to specify where to start paginating. This is the next-token from a previously truncated response
  -v, --verbose
          If included, prints all attributes and key information for each matched key. By default each matched key only displays its key-reference and label attribute. This flag when used by Admins has no effect
  -h, --help
          Print help
```

## Examples
<a name="chsm-cli-key-list-examples"></a>

The following examples show the different ways you run the **key list** command. The following examples show the outputs as a crypto user.

**Example: Find all keys – default**  
This command lists the keys of the logged in user present in the AWS CloudHSM cluster.  
By default, only 10 keys of the currently logged in user are displayed, and only the `key-reference` and `label` are displayed as output. Use the appropriate pagination options to display more or less keys as output.

```
aws-cloudhsm > key list
{
  "error_code": 0,
  "data": {
    "matched_keys": [
      {
        "key-reference": "0x00000000000003d5",
        "attributes": {
          "label": "test_label_1"
        }
      },
      {
        "key-reference": "0x0000000000000626",
        "attributes": {
          "label": "test_label_2"
        }
      },.
      ...8 keys later...
    ],
    "total_key_count": 56,
    "returned_key_count": 10,
    "next_token": "10"
  }
}
```

**Example: Find all keys – verbose**  
The output includes keys that the user owns and shares, as well as all public keys in the HSMs.  
Note: By default, only 10 keys of the currently logged in user are displayed. Use the appropriate pagination options to display more or less keys as output.

```
aws-cloudhsm > key list --verbose
{
  "error_code": 0,
  "data": {
    "matched_keys": [
      {
        "key-reference": "0x000000000012000c",
        "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": "ec",
          "label": "ec-test-private-key",
          "id": "",
          "check-value": "0x2a737d",
          "class": "private-key",
          "encrypt": false,
          "decrypt": false,
          "token": true,
          "always-sensitive": true,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "modifiable": true,
          "never-extractable": false,
          "private": true,
          "sensitive": true,
          "sign": false,
          "trusted": false,
          "unwrap": false,
          "verify": false,
          "wrap": false,
          "wrap-with-trusted": false,
          "key-length-bytes": 122,
          "ec-point": "0x0442d53274a6c0ec1a23c165dcb9ccdd72c64e98ae1a9594bb5284e752c746280667e11f1e983493c1c605e0a8071ede47ca280f94c6b2aa33",
          "curve": "secp224r1"
        }
      },
      {
        "key-reference": "0x000000000012000d",
        "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": "ec",
          "label": "ec-test-public-key",
          "id": "",
          "check-value": "0x2a737d",
          "class": "public-key",
          "encrypt": false,
          "decrypt": false,
          "token": true,
          "always-sensitive": false,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "modifiable": true,
          "never-extractable": false,
          "private": true,
          "sensitive": false,
          "sign": false,
          "trusted": false,
          "unwrap": false,
          "verify": false,
          "wrap": false,
          "wrap-with-trusted": false,
          "key-length-bytes": 57,
          "ec-point": "0x0442d53274a6c0ec1a23c165dcb9ccdd72c64e98ae1a9594bb5284e752c746280667e11f1e983493c1c605e0a8071ede47ca280f94c6b2aa33",
          "curve": "secp224r1"
        }
      }
    ],
      ...8 keys later...
    "total_key_count": 1580,
    "returned_key_count": 10
  }
}
```

**Example: Paginated return**  
The following example displays a paginated subset of the keys which shows only two keys. The example then provides a subsequent call to display the next two keys.  

```
aws-cloudhsm > key list --verbose --max-items 2
{
  "error_code": 0,
  "data": {
    "matched_keys": [
      {
        "key-reference": "0x0000000000000030",
        "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": "98a6688d1d964ed7b45b9cec5c4b1909",
          "id": "",
          "check-value": "0xb28a46",
          "class": "secret-key",
          "encrypt": false,
          "decrypt": false,
          "token": true,
          "always-sensitive": true,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "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": 32
        }
      },
      {
        "key-reference": "0x0000000000000042",
        "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": "4ad6cdcbc02044e09fa954143efde233",
          "id": "",
          "check-value": "0xc98104",
          "class": "secret-key",
          "encrypt": true,
          "decrypt": true,
          "token": true,
          "always-sensitive": true,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "modifiable": true,
          "never-extractable": false,
          "private": true,
          "sensitive": true,
          "sign": true,
          "trusted": false,
          "unwrap": true,
          "verify": true,
          "wrap": true,
          "wrap-with-trusted": false,
          "key-length-bytes": 16
        }
      }
    ],
    "total_key_count": 1580,
    "returned_key_count": 2,
    "next_token": "2"
  }
}
```
To display the next 2 keys, a subsequent call can be made:  

```
aws-cloudhsm > key list --verbose --max-items 2 --starting-token 2
{
  "error_code": 0,
  "data": {
    "matched_keys": [
      {
        "key-reference": "0x0000000000000081",
        "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": "6793b8439d044046982e5b895791e47f",
          "id": "",
          "check-value": "0x3f986f",
          "class": "secret-key",
          "encrypt": false,
          "decrypt": false,
          "token": true,
          "always-sensitive": true,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "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": 32
        }
      },
      {
        "key-reference": "0x0000000000000089",
        "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": "56b30fa05c6741faab8f606d3b7fe105",
          "id": "",
          "check-value": "0xe9201a",
          "class": "secret-key",
          "encrypt": false,
          "decrypt": false,
          "token": true,
          "always-sensitive": true,
          "derive": false,
          "destroyable": true,
          "extractable": true,
          "local": true,
          "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": 32
        }
      }
    ],
    "total_key_count": 1580,
    "returned_key_count": 2,
    "next_token": "4"
  }
}
```
For more examples that demonstrate how the key filtration mechanism works in the CloudHSM CLI, see [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md).

## Arguments
<a name="key-list-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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 matching key(s) to list.  
For a listing of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)  
Required: No

***<MAX\$1ITEMS>***  
The total number of items to return in the command's output. If the total number of items available is more than the value specified, a next-token is provided in the command's output. To resume pagination, provide the next-token value in the starting-token argument of a subsequent command.  
Required: No

***<STARTING\$1TOKEN>***  
A token to specify where to start paginating. This is the next-token from a previously truncated response.  
Required: No

***<VERBOSE>***  
If included, prints all attributes and key information for each matched key. By default each matched key only displays its key-reference and label attribute. This flag when used by Admins has no effect.  
Required: No

## Related topics
<a name="chsm-key-list-seealso"></a>
+ [Delete a key with CloudHSM CLI](cloudhsm_cli-key-delete.md)
+ [Export an asymmetric key with CloudHSM CLI](cloudhsm_cli-key-generate-file.md)
+ [Unshare a key using CloudHSM CLI](cloudhsm_cli-key-unshare.md)
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)

# Replicate a key with CloudHSM CLI
<a name="cloudhsm_cli-key-replicate"></a>

Use the **key replicate** command in CloudHSM CLI to replicate a key from a source AWS CloudHSM cluster to a destination AWS CloudHSM cluster.

## User type
<a name="chsm-cli-key-replicate-user-type"></a>

The following types of users can run this command.
+ Admins (COs)
+ Crypto users (CUs)
**Note**  
Crypto Users must own the key to use this command.

## Requirements
<a name="cloudhsm_cli-key-replicate-requirements"></a>
+ The source and destination clusters must be clones. This means one was created from a backup of the other, or they were both created from a common backup. See [Creating clusters from backups](create-cluster-from-backup.md) for more information.
+ The owner of the key must exist on the destination cluster. Additionally, if the key is shared with any users, those users must also exist on the destination cluster.
+ To run this command, you must be logged in as a crypto user or an admin on both the source and destination clusters.
  +  In single command mode, the command will use the CLOUDHSM\$1PIN and CLOUDHSM\$1ROLE environmental variables to authenticate on the source cluster. See [Single Command mode](cloudhsm_cli-modes.md#cloudhsm_cli-mode-single-command) for more information. To provide credentials for the destination cluster, you need to set two additional environmental variables: DESTINATION\$1CLOUDHSM\$1PIN and DESTINATION\$1CLOUDHSM\$1ROLE:

    ```
    $ export DESTINATION_CLOUDHSM_ROLE=<role>
    ```

    ```
    $ export DESTINATION_CLOUDHSM_PIN=<username:password>
    ```
  +  In interactive mode, users will need to explicitly log into both the source and destination clusters.

## Syntax
<a name="chsm-cli-key-replicate-syntax"></a>

```
aws-cloudhsm > help key replicate
Replicate a key from a source to a destination cluster

Usage: key replicate --filter [<FILTER>...] --source-cluster-id <SOURCE_CLUSTER_ID> --destination-cluster-id <DESTINATION_CLUSTER_ID>

Options:
      --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 matching key on the source cluster
      --source-cluster-id <SOURCE_CLUSTER_ID>
          Source cluster ID
      --destination-cluster-id <DESTINATION_CLUSTER_ID>
          Destination cluster ID
  -h, --help
          Print help
```

## Examples
<a name="chsm-cli-key-replicate-examples"></a>

**Example: Replicate key**  
This command replicates a key from a source cluster with to a cloned destination cluster. The example below demonstrates the output when logged in as a crypto user on both clusters.  

```
crypto-user-1@cluster-1234abcdefg > key replicate \
      --filter attr.label=example-key \
      --source-cluster-id cluster-1234abcdefg \
      --destination-cluster-id cluster-2345bcdefgh
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x0000000000300006",
      "key-info": {
        "key-owners": [
          {
            "username": "crypto-user-1",
            "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": "example-key",
        "id": "0x",
        "check-value": "0x5e118e",
        "class": "secret-key",
        "encrypt": false,
        "decrypt": false,
        "token": true,
        "always-sensitive": true,
        "derive": false,
        "destroyable": true,
        "extractable": true,
        "local": true,
        "modifiable": true,
        "never-extractable": true,
        "private": true,
        "sensitive": true,
        "sign": true,
        "trusted": false,
        "unwrap": false,
        "verify": true,
        "wrap": false,
        "wrap-with-trusted": false,
        "key-length-bytes": 16
      }
    },
    "message": "Successfully replicated key"
  }
}
```

## Arguments
<a name="key-replicate-arguments"></a>

***<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 matching key on the source cluster.  
For a listing of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)  
Required: Yes

***<SOURCE\$1CLUSTER\$1ID>***  
The source cluster ID.  
Required: Yes

***<DESTINATION\$1CLUSTER\$1ID>***  
The destination cluster ID.  
Required: Yes

## Related topics
<a name="chsm-key-replicate-seealso"></a>
+ [Connecting to multiple clusters with CloudHSM CLI](cloudhsm_cli-configs-multi-cluster.md)

# Set the attributes of keys with CloudHSM CLI
<a name="cloudhsm_cli-key-set-attribute"></a>

Use the **key set-attribute** command in CloudHSM CLI to set the attributes of keys in your AWS CloudHSM cluster. Only the CU who created the key and consequently owns it can change the key's attributes.

For a list of key attributes that can be used in CloudHSM CLI, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).

## User type
<a name="chsm-cli-key-set-attribute-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs) can run this command.
+ Admins can set the trusted attribute.

## Requirements
<a name="chsm-cli-key-set-attribute-requirements"></a>

To run this command, you must be logged in as a CU. To set the trusted attribute, you must be logged in as an admin user.

## Syntax
<a name="chsm-cli-key-set-attribute-syntax"></a>

```
aws-cloudhsm > help key set-attribute
Set an attribute for a key in the HSM cluster

Usage: cloudhsm-cli key set-attribute [OPTIONS] --filter [<FILTER>...] --name <KEY_ATTRIBUTE> --value <KEY_ATTRIBUTE_VALUE>

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 matching key to modify
      --name <KEY_ATTRIBUTE>            Name of attribute to be set
      --value <KEY_ATTRIBUTE_VALUE>...  Attribute value to be set
      --approval <APPROVAL>            Filepath of signed quorum token file to approve operation
  -h, --help                            Print help
```

## Example: Setting a key attribute
<a name="chsm-cli-key-set-attribute-examples"></a>

The following example shows how to use the **key set-attribute** command to set the label.

**Example**  

1. Use the key with the label `my_key`, as shown here:

   ```
   aws-cloudhsm > key set-attribute --filter attr.label=my_key --name encrypt --value false
   {
     "error_code": 0,
     "data": {
       "message": "Attribute set successfully"
     }
   }
   ```

1. Use the **key list** command to confirm the `encrypt` attribute has changed:

   ```
   aws-cloudhsm > key list --filter attr.label=my_key --verbose
   {
     "error_code": 0,
     "data": {
       "matched_keys": [
         {
           "key-reference": "0x00000000006400ec",
           "key-info": {
             "key-owners": [
               {
                 "username": "bob",
                 "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": "my_key",
             "id": "",
             "check-value": "0x6bd9f7",
             "class": "secret-key",
             "encrypt": false,
             "decrypt": true,
             "token": true,
             "always-sensitive": true,
             "derive": true,
             "destroyable": true,
             "extractable": true,
             "local": true,
             "modifiable": true,
             "never-extractable": false,
             "private": true,
             "sensitive": true,
             "sign": true,
             "trusted": true,
             "unwrap": true,
             "verify": true,
             "wrap": true,
             "wrap-with-trusted": false,
             "key-length-bytes": 32
           }
         }
       ],
       "total_key_count": 1,
       "returned_key_count": 1
     }
   }
   ```

## Arguments
<a name="chsm-cli-key-set-attribute-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<KEY\$1ATTRIBUTE>***  
Specifies the name of the key's attribute.  
Required: Yes

***<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 matching key for deletion.  
For a listing of supported CloudHSM CLI key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)  
Required: No

***<KEY\$1ATTRIBUTE\$1VALUE>***  
Specifies the value of the key's attribute.  
Required: Yes

***<KEY\$1REFERENCE>***  
A hexadecimal or decimal representation of the key. (such as a key handle).  
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 key is greater than 1.

## Related topics
<a name="chsm-cli-key-set-attribute-see-also"></a>
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)

# Share a key using CloudHSM CLI
<a name="cloudhsm_cli-key-share"></a>

Use the **key share** command in CloudHSM CLI to share a key with other CUs in your AWS CloudHSM cluster.

Only the CU who created the key and consequently owns it can share the key. Users with whom a key is shared can use the key in cryptographic operations, but they cannot delete, export, share, unshare, derive, or wrap the key. Additionally, these users cannot change [key attributes](cloudhsm_cli-key-attributes.md).

## User type
<a name="chsm-cli-key-share-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="chsm-cli-key-share-requirements"></a>

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

## Syntax
<a name="chsm-cli-key-share-syntax"></a>

```
aws-cloudhsm > help key share
Share a key in the HSM cluster with another user

Usage: key share --filter [<FILTER>...] --username <USERNAME> --role <ROLE>

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 matching key for sharing

      --username <USERNAME>
          A username with which the key will be shared

      --role <ROLE>
          Role the user has in the cluster

          Possible values:
          - crypto-user: A CryptoUser has the ability to manage and use keys
          - admin:       An Admin has the ability to manage user accounts

      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation

  -h, --help
          Print help (see a summary with '-h')
```

## Example: Share a key with another CU
<a name="chsm-cli-key-share-examples"></a>

The following example shows how to use the **key share** command to share a key with the CU `alice`.

**Example**  

1. Run the **key share** command to share the key with `alice`.

   ```
   aws-cloudhsm > key share --filter attr.label="rsa_key_to_share" attr.class=private-key --username alice --role crypto-user
   {
     "error_code": 0,
     "data": {
       "message": "Key shared successfully"
     }
   }
   ```

1. Run the **key list** command.

   ```
   aws-cloudhsm > key list --filter attr.label="rsa_key_to_share" attr.class=private-key --verbose
   {
     "error_code": 0,
     "data": {
       "matched_keys": [
         {
           "key-reference": "0x00000000001c0686",
           "key-info": {
             "key-owners": [
               {
                 "username": "cu3",
                 "key-coverage": "full"
               }
             ],
             "shared-users": [
               {
                 "username": "cu2",
                 "key-coverage": "full"
               },
               {
                 "username": "cu1",
                 "key-coverage": "full"
               },
               {
                 "username": "cu4",
                 "key-coverage": "full"
               },
               {
                 "username": "cu5",
                 "key-coverage": "full"
               },
               {
                 "username": "cu6",
                 "key-coverage": "full"
               },
               {
                 "username": "cu7",
                 "key-coverage": "full"
               },
               {
                 "username": "alice",
                 "key-coverage": "full"
               }
             ],
             "key-quorum-values": {
               "manage-key-quorum-value": 0,
               "use-key-quorum-value": 0
             },
             "cluster-coverage": "full"
           },
           "attributes": {
             "key-type": "rsa",
             "label": "rsa_key_to_share",
             "id": "",
             "check-value": "0xae8ff0",
             "class": "private-key",
             "encrypt": false,
             "decrypt": true,
             "token": true,
             "always-sensitive": true,
             "derive": false,
             "destroyable": true,
             "extractable": true,
             "local": true,
             "modifiable": true,
             "never-extractable": false,
             "private": true,
             "sensitive": true,
             "sign": true,
             "trusted": false,
             "unwrap": true,
             "verify": false,
             "wrap": false,
             "wrap-with-trusted": false,
             "key-length-bytes": 1219,
             "public-exponent": "0x010001",
             "modulus": "0xa8855cba933cec0c21a4df0450ec31675c024f3e65b2b215a53d2bda6dcd191f75729150b59b4d86df58254c8f518f7d000cc04d8e958e7502c7c33098e28da4d94378ef34fb57d1cc7e042d9119bd79be0df728421a980a397095157da24cf3cc2b6dab12225d33fdca11f0c6ed1a5127f12488cda9a556814b39b06cd8373ff5d371db2212887853621b8510faa7b0779fbdec447e1f1d19f343acb02b22526487a31f6c704f8f003cb4f7013136f90cc17c2c20e414dc1fc7bcfb392d59c767900319679fc3307388633485657ce2e1a3deab0f985b0747ef4ed339de78147d1985d14fdd8634219321e49e3f5715e79c298f18658504bab04086bfbdcd3b",
             "modulus-size-bits": 2048
           }
         }
       ],
       "total_key_count": 1,
       "returned_key_count": 1
     }
   }
   ```

1. In the above list, verify `alice` is in the list of `shared-users`

## Arguments
<a name="chsm-cli-key-share-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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 matching key for deletion.  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: Yes

***<USERNAME>***  
Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ). The username is not case sensitive in this command, username is always displayed in lowercase.  
Required: Yes

***<ROLE>***  
Specifies the role assigned to this user. This parameter is required. To get the user’s role, use the user list command. For detailed information about the user types on an HSM, see [HSM user types for CloudHSM CLI](understanding-users.md).  
Required: Yes

***<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 key is greater than 1.

## Related topics
<a name="chsm-cli-key-share-see-also"></a>
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)

# Unshare a key using CloudHSM CLI
<a name="cloudhsm_cli-key-unshare"></a>

Use the **key unshare** command in CloudHSM CLI to unshare a key with other CUs in your AWS CloudHSM cluster.

Only the CU who created the key and consequently owns it can unshare the key. Users with whom a key is shared can use the key in cryptographic operations, but they cannot delete, export, share, or unshare the key. Additionally, these users cannot change [key attributes](cloudhsm_cli-key-attributes.md).

## User type
<a name="chsm-cli-key-unshare-user-type"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="chsm-cli-key-unshare-requirements"></a>

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

## Syntax
<a name="chsm-cli-key-unshare-syntax"></a>

```
aws-cloudhsm > help key unshare
Unshare a key in the HSM cluster with another user

Usage: key unshare --filter [<FILTER>...] --username <USERNAME> --role <ROLE>

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 matching key for unsharing

      --username <USERNAME>
          A username with which the key will be unshared

      --role <ROLE>
          Role the user has in the cluster

          Possible values:
          - crypto-user: A CryptoUser has the ability to manage and use keys
          - admin:       An Admin has the ability to manage user accounts

      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation

  -h, --help
          Print help (see a summary with '-h')
```

## Example: Unshare a key with another CU
<a name="chsm-cli-key-share-examples"></a>

The following example shows how to use the **key unshare** command to unshare a key with the CU `alice`.

**Example**  

1. Run the **key list** command and filter by the specific key you want to unshare with `alice`.

   ```
   aws-cloudhsm > key list --filter attr.label="rsa_key_to_share" attr.class=private-key --verbose
   {
     "error_code": 0,
     "data": {
       "matched_keys": [
         {
           "key-reference": "0x00000000001c0686",
           "key-info": {
             "key-owners": [
               {
                 "username": "cu3",
                 "key-coverage": "full"
               }
             ],
             "shared-users": [
               {
                 "username": "cu2",
                 "key-coverage": "full"
               },
               {
                 "username": "cu1",
                 "key-coverage": "full"
               },
               {
                 "username": "cu4",
                 "key-coverage": "full"
               },
               {
                 "username": "cu5",
                 "key-coverage": "full"
               },
               {
                 "username": "cu6",
                 "key-coverage": "full"
               },
               {
                 "username": "cu7",
                 "key-coverage": "full"
               },
               {
                 "username": "alice",
                 "key-coverage": "full"
               }
             ],
             "key-quorum-values": {
               "manage-key-quorum-value": 0,
               "use-key-quorum-value": 0
             },
             "cluster-coverage": "full"
           },
           "attributes": {
             "key-type": "rsa",
             "label": "rsa_key_to_share",
             "id": "",
             "check-value": "0xae8ff0",
             "class": "private-key",
             "encrypt": false,
             "decrypt": true,
             "token": true,
             "always-sensitive": true,
             "derive": false,
             "destroyable": true,
             "extractable": true,
             "local": true,
             "modifiable": true,
             "never-extractable": false,
             "private": true,
             "sensitive": true,
             "sign": true,
             "trusted": false,
             "unwrap": true,
             "verify": false,
             "wrap": false,
             "wrap-with-trusted": false,
             "key-length-bytes": 1219,
             "public-exponent": "0x010001",
             "modulus": "0xa8855cba933cec0c21a4df0450ec31675c024f3e65b2b215a53d2bda6dcd191f75729150b59b4d86df58254c8f518f7d000cc04d8e958e7502c7c33098e28da4d94378ef34fb57d1cc7e042d9119bd79be0df728421a980a397095157da24cf3cc2b6dab12225d33fdca11f0c6ed1a5127f12488cda9a556814b39b06cd8373ff5d371db2212887853621b8510faa7b0779fbdec447e1f1d19f343acb02b22526487a31f6c704f8f003cb4f7013136f90cc17c2c20e414dc1fc7bcfb392d59c767900319679fc3307388633485657ce2e1a3deab0f985b0747ef4ed339de78147d1985d14fdd8634219321e49e3f5715e79c298f18658504bab04086bfbdcd3b",
             "modulus-size-bits": 2048
           }
         }
       ],
       "total_key_count": 1,
       "returned_key_count": 1
     }
   }
   ```

1. Confirm `alice` is in the `shared-users` output, and run the following **key unshare** command to unshare the key with `alice`.

   ```
   aws-cloudhsm > key unshare --filter attr.label="rsa_key_to_share" attr.class=private-key --username alice --role crypto-user
   {
     "error_code": 0,
     "data": {
       "message": "Key unshared successfully"
     }
   }
   ```

1. Run the `key list` command again to confirm that the key has been unshared with `alice`.

   ```
   aws-cloudhsm > key list --filter attr.label="rsa_key_to_share" attr.class=private-key --verbose
   {
     "error_code": 0,
     "data": {
       "matched_keys": [
         {
           "key-reference": "0x00000000001c0686",
           "key-info": {
             "key-owners": [
               {
                 "username": "cu3",
                 "key-coverage": "full"
               }
             ],
             "shared-users": [
               {
                 "username": "cu2",
                 "key-coverage": "full"
               },
               {
                 "username": "cu1",
                 "key-coverage": "full"
               },
               {
                 "username": "cu4",
                 "key-coverage": "full"
               },
               {
                 "username": "cu5",
                 "key-coverage": "full"
               },
               {
                 "username": "cu6",
                 "key-coverage": "full"
               },
               {
                 "username": "cu7",
                 "key-coverage": "full"
               },
             ],
             "key-quorum-values": {
               "manage-key-quorum-value": 0,
               "use-key-quorum-value": 0
             },
             "cluster-coverage": "full"
           },
           "attributes": {
             "key-type": "rsa",
             "label": "rsa_key_to_share",
             "id": "",
             "check-value": "0xae8ff0",
             "class": "private-key",
             "encrypt": false,
             "decrypt": true,
             "token": true,
             "always-sensitive": true,
             "derive": false,
             "destroyable": true,
             "extractable": true,
             "local": true,
             "modifiable": true,
             "never-extractable": false,
             "private": true,
             "sensitive": true,
             "sign": true,
             "trusted": false,
             "unwrap": true,
             "verify": false,
             "wrap": false,
             "wrap-with-trusted": false,
             "key-length-bytes": 1219,
             "public-exponent": "0x010001",
             "modulus": "0xa8855cba933cec0c21a4df0450ec31675c024f3e65b2b215a53d2bda6dcd191f75729150b59b4d86df58254c8f518f7d000cc04d8e958e7502c7c33098e28da4d94378ef34fb57d1cc7e042d9119bd79be0df728421a980a397095157da24cf3cc2b6dab12225d33fdca11f0c6ed1a5127f12488cda9a556814b39b06cd8373ff5d371db2212887853621b8510faa7b0779fbdec447e1f1d19f343acb02b22526487a31f6c704f8f003cb4f7013136f90cc17c2c20e414dc1fc7bcfb392d59c767900319679fc3307388633485657ce2e1a3deab0f985b0747ef4ed339de78147d1985d14fdd8634219321e49e3f5715e79c298f18658504bab04086bfbdcd3b",
             "modulus-size-bits": 2048
           }
         }
       ],
       "total_key_count": 1,
       "returned_key_count": 1
     }
   }
   ```

## Arguments
<a name="chsm-cli-key-unshare-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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 matching key for deletion.  
For a list of supported key attributes, see [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md).  
Required: Yes

***<USERNAME>***  
Specifies a friendly name for the user. The maximum length is 31 characters. The only special character permitted is an underscore ( \$1 ). The username is not case sensitive in this command, username is always displayed in lowercase.  
Required: Yes

***<ROLE>***  
Specifies the role assigned to this user. This parameter is required. To get the user’s role, use the user list command. For detailed information about the user types on an HSM, see [HSM user types for CloudHSM CLI](understanding-users.md).  
Required: Yes

***<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 key is greater than 1.

## Related topics
<a name="chsm-cli-key-unshare-see-also"></a>
+ [Filter keys using CloudHSM CLI](manage-keys-cloudhsm-cli-filtering.md)
+ [Key attributes for CloudHSM CLI](cloudhsm_cli-key-attributes.md)

# The key unwrap command in CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap"></a>

The **key unwrap** parent command in CloudHSM CLI imports an encrypted (wrapped) symmetric or asymmetric private key from a file and into the HSM. This command is designed to import encrypted keys that were wrapped by the [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md) command, but it can also be used to unwrap keys that were wrapped with other tools. However, in those situations, we recommend using the PKCS\$111 or JCE software libraries to unwrap the key.
+ [aes-gcm](cloudhsm_cli-key-unwrap-aes-gcm.md)
+ [aes-no-pad](cloudhsm_cli-key-unwrap-aes-no-pad.md)
+ [aes-pkcs5-pad](cloudhsm_cli-key-unwrap-aes-pkcs5-pad.md)
+ [aes-zero-pad](cloudhsm_cli-key-unwrap-aes-zero-pad.md)
+ [cloudhsm-aes-gcm](cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm.md)
+ [rsa-aes](cloudhsm_cli-key-unwrap-rsa-aes.md)
+ [rsa-oaep](cloudhsm_cli-key-unwrap-rsa-oaep.md)
+ [rsa-pkcs](cloudhsm_cli-key-unwrap-rsa-pkcs.md)

# Unwrap a key with AES-GCM using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-aes-gcm"></a>

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
<a name="cloudhsm_cli-key-unwrap-aes-gcm-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-aes-gcm-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-aes-gcm-syntax"></a>

```
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
<a name="cloudhsm_cli-key-unwrap-aes-gcm-examples"></a>

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
<a name="cloudhsm_cli-key-unwrap-aes-gcm-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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\$1PATH>***  
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\$1LENGTH\$1BITS>***  
Aes GCM tag length in bits.  
Required: Yes

***<KEY\$1TYPE\$1CLASS>***  
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
<a name="cloudhsm_cli-key-unwrap-aes-gcm-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with AES-NO-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-aes-no-pad"></a>

Use the **key unwrap aes-no-pad** command in CloudHSM CLI to unwrap a payload key into the AWS CloudHSM cluster using the AES wrapping key and the `AES-NO-PAD` 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-no-pad** command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-syntax"></a>

```
aws-cloudhsm > help key unwrap aes-no-pad
Usage: key unwrap aes-no-pad [OPTIONS] --filter [<FILTER>...] --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--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
      --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
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-examples"></a>

These examples show how to use the **key unwrap aes-no-pad** 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-no-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data eXK3PMAOnKM9y3YX6brbhtMoC060EOH9
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08ec",
      "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-no-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08ec",
      "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
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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\$1PATH>***  
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

***<KEY\$1TYPE\$1CLASS>***  
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

***<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
<a name="cloudhsm_cli-key-unwrap-aes-no-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with AES-PKCS5-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad"></a>

Use the **key unwrap aes-pkcs5-pad** command in CloudHSM CLI to unwrap a payload key using the AES wrapping key and the `AES-PKCS5-PAD` 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-pkcs5-pad** command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-syntax"></a>

```
aws-cloudhsm > help key unwrap aes-pkcs5-pad
Usage: key unwrap aes-pkcs5-pad [OPTIONS] --filter [<FILTER>...] --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--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
      --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
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-examples"></a>

These examples show how to use the **key unwrap aes-pkcs5-pad** 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-pkcs5-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data MbuYNresfOKyGNnxKWen88nSfX+uUE/0qmGofSisicY=
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08e3",
      "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-pkcs5-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08e3",
      "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
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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\$1PATH>***  
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

***<KEY\$1TYPE\$1CLASS>***  
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

***<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
<a name="cloudhsm_cli-key-unwrap-aes-pkcs5-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with AES-ZERO-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad"></a>

Use the **key unwrap aes-zero-pad** command in CloudHSM CLI to unwrap a payload key into the AWS CloudHSM cluster using the AES wrapping key and the `AES-ZERO-PAD` 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-no-pad** command, you must have the AES wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-syntax"></a>

```
aws-cloudhsm > help key unwrap aes-zero-pad
Usage: key unwrap aes-zero-pad [OPTIONS] --filter [<FILTER>...] --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--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
      --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
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-examples"></a>

These examples show how to use the **key unwrap aes-zero-pad** 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-zero-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data L1wVlL/YeBNVAw6Mpk3owFJZXBzDLONt
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08e7",
      "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-zero-pad --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08e7",
      "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
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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\$1PATH>***  
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

***<KEY\$1TYPE\$1CLASS>***  
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

***<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
<a name="cloudhsm_cli-key-unwrap-aes-zero-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with CLOUDHSM-AES-GCM using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm"></a>

Use the **key unwrap cloudhsm-aes-gcm** command in CloudHSM CLI to unwrap a payload key into the AWS CloudHSM cluster using the AES wrapping key and the `CLOUDHSM-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 cloudhsm-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
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-syntax"></a>

```
aws-cloudhsm > help key unwrap cloudhsm-aes-gcm
Usage: key unwrap cloudhsm-aes-gcm [OPTIONS] --filter [<FILTER>...] --tag-length-bits <TAG_LENGTH_BITS> --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--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
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-examples"></a>

These examples show how to use the **key unwrap cloudhsm-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 cloudhsm-aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64  --aad 0x10 --data 6Rn8nkjEriDYlnP3P8nPkYQ8hplOEJ899zsrF+aTB0i/fIlZ
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001408e8",
      "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 cloudhsm-aes-gcm --key-type-class aes --label aes-unwrapped --filter attr.label=aes-example --tag-length-bits 64  --aad 0x10 --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001408e8",
      "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
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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\$1PATH>***  
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\$1LENGTH\$1BITS>***  
Aes GCM tag length in bits.  
Required: Yes

***<KEY\$1TYPE\$1CLASS>***  
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

***<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
<a name="cloudhsm_cli-key-unwrap-cloudhsm-aes-gcm-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with RSA-AES using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-rsa-aes"></a>

Use the **key unwrap rsa-aes** command in CloudHSM CLI to unwrap a payload key using an RSA private key and the `RSA-AES` 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 rsa-aes**, you must have the RSA private key of the RSA public wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`. 

**Note**  
This command is only available with CloudHSM CLI 5.11\$1.

## User type
<a name="cloudhsm_cli-key-unwrap-rsa-aes-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-rsa-aes-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-rsa-aes-syntax"></a>

```
aws-cloudhsm > help key unwrap rsa-aes
Usage: key unwrap rsa-aes [OPTIONS] --filter [<FILTER>...] --hash-function <HASH_FUNCTION> --mgf <MGF> --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--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
      --hash-function <HASH_FUNCTION>
          Hash algorithm [possible values: sha1, sha224, sha256, sha384, sha512]
      --mgf <MGF>
          Mask Generation Function algorithm [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512]
      --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
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-unwrap-rsa-aes-examples"></a>

These examples show how to use the **key unwrap rsa-aes** command using the RSA private key with the `unwrap` attribute value set to `true`.

**Example: Unwrap a payload key from Base64 encoded wrapped key data**  

```
aws-cloudhsm > key unwrap rsa-aes --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --hash-function sha256 --mgf mgf1-sha256 --data HrSE1DEyLjIeyGdPa9R+ebiqB5TIJGyamPker31ZebPwRA+NcerbAJO8DJ1lXPygZcI21vIFSZJuWMEiWpe1R9D/5WSYgxLVKex30xCFqebtEzxbKuv4DOmU4meSofqREYvtb3EoIKwjyxCMRQFgoyUCuP4y0f0eSv0k6rSJh4NuCsHptXZbtgNeRcR4botN7LlzkEIUcq4fVHaatCwd0J1QGKHKyRhkol+RL5WGXKe4nAboAkC5GO7veI5yHL1SaKlssSJtTL/CFpbSLsAFuYbv/NUCWwMY5mwyVTCSlw+HlgKK+5TH1MzBaSi8fpfyepLT8sHy2Q/VRl6ifb49p6m0KQFbRVvz/OWUd6l4d97BdgtaEz6ueg==
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001808e2",
      "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 rsa-aes --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --hash-function sha256 --mgf mgf1-sha256 --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001808e2",
      "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
<a name="cloudhsm_cli-key-unwrap-rsa-aes-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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\$1PATH>***  
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

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`].  
Required: Yes

***<HASH\$1FUNCTION>***  
Specifies the hash function.  
Valid values:  
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Required: Yes

***<MGF>***  
Specifies the mask generation function.   
The mask generation function hash function must match the signing mechanism hash function.
Valid values:  
+ mgf1-sha1
+ mgf1-sha224
+ mgf1-sha256
+ mgf1-sha384
+ mgf1-sha512
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

***<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
<a name="cloudhsm_cli-key-unwrap-rsa-aes-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with RSA-OAEP using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-rsa-oaep"></a>

Use the **key unwrap rsa-oaep** command in CloudHSM CLI to unwrap a payload key using the RSA private key and the `RSA-OAEP` 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 rsa-oaep** command, you must have the RSA private key of the RSA public wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-syntax"></a>

```
aws-cloudhsm > help key unwrap rsa-oaep
Usage: key unwrap rsa-oaep [OPTIONS] --filter [<FILTER>...] --hash-function <HASH_FUNCTION> --mgf <MGF> --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--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
      --hash-function <HASH_FUNCTION>
          Hash algorithm [possible values: sha1, sha224, sha256, sha384, sha512]
      --mgf <MGF>
          Mask Generation Function algorithm [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512]
      --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
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-examples"></a>

These examples show how to use the **key unwrap rsa-oaep** command using the RSA private key with the `unwrap` attribute value set to `true`.

**Example: Unwrap a payload key from Base64 encoded wrapped key data**  

```
aws-cloudhsm > key unwrap rsa-oaep --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-example-key --hash-function sha256 --mgf mgf1-sha256 --data OjJe4msobPLz9TuSAdULEu17T5rMDWtSlLyBSkLbaZnYzzpdrhsbGLbwZJCtB/jGkDNdB4qyTAOQwEpggGf6v+Yx6JcesNeKKNU8XZal/YBoHC8noTGUSDI2qr+u2tDc84NPv6d+F2KOONXsSxMhmxzzNG/gzTVIJhOuy/B1yHjGP4mOXoDZf5+7f5M1CjxBmz4Vva/wrWHGCSG0yOaWblEvOiHAIt3UBdyKmU+/My4xjfJv7WGGu3DFUUIZ06TihRtKQhUYU1M9u6NPf9riJJfHsk6QCuSZ9yWThDT9as6i7e3htnyDhIhGWaoK8JU855cN/YNKAUqkNpC4FPL3iw==
{
  "data": {
    "key": {
      "key-reference": "0x00000000001808e9",
      "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 rsa-oaep --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-example-key --hash-function sha256 --mgf mgf1-sha256 --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001808e9",
      "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
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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\$1PATH>***  
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

***<KEY\$1TYPE\$1CLASS>***  
Key type and class of wrapped key [possible values: `aes`, `des3`, `ec-private`, `generic-secret`, `rsa-private`].  
Required: Yes

***<HASH\$1FUNCTION>***  
Specifies the hash function.  
Valid values:  
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Required: Yes

***<MGF>***  
Specifies the mask generation function.   
The mask generation function hash function must match the signing mechanism hash function.
Valid values:  
+ mgf1-sha1
+ mgf1-sha224
+ mgf1-sha256
+ mgf1-sha384
+ mgf1-sha512
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

***<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
<a name="cloudhsm_cli-key-unwrap-rsa-oaep-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Unwrap a key with RSA-PKCS using CloudHSM CLI
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs"></a>

Use the **key unwrap rsa-pkcs** command in CloudHSM CLI to unwrap a payload key using the RSA private key and the `RSA-PKCS` 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 rsa-pkcs** command, you must have the RSA private key of the RSA public wrapping key in your AWS CloudHSM cluster, and its `unwrap` attribute must be set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-syntax"></a>

```
aws-cloudhsm > help key unwrap rsa-pkcs
Usage: key unwrap rsa-pkcs [OPTIONS] --filter [<FILTER>...] --key-type-class <KEY_TYPE_CLASS> --label <LABEL> <--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
      --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
      --approval <APPROVAL>
          Filepath of signed quorum token file to approve operation
  -h, --help
          Print help
```

## Examples
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-examples"></a>

These examples show how to use the **key unwrap rsa-oaep** 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 rsa-pkcs --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --data am0Nc7+YE8FWs+5HvU7sIBcXVb24QA0l65nbNAD+1bK+e18BpSfnaI3P+r8Dp+pLu1ofoUy/vtzRjZoCiDofcz4EqCFnGl4GdcJ1/3W/5WRvMatCa2d7cx02swaeZcjKsermPXYRO1lGlfq6NskwMeeTkV8R7Rx9artFrs1y0DdIgIKVaiFHwnBIUMnlQrR2zRmMkfwU1jxMYmOYyD031F5VbnjSrhfMwkww2la7uf/c3XdFJ2+0Bo94c6og/yfPcpOOobJlITCoXhtMRepSdO4OggYq/6nUDuHCtJ86pPGnNahyr7+sAaSI3a5ECQLUjwaIARUCyoRh7EFK3qPXcg==
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08ef",
      "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 rsa-pkcs --key-type-class aes --label aes-unwrapped --filter attr.label=rsa-private-key-example --data-path payload-key.pem
{
  "error_code": 0,
  "data": {
    "key": {
      "key-reference": "0x00000000001c08ef",
      "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
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<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\$1PATH>***  
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

***<KEY\$1TYPE\$1CLASS>***  
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

***<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
<a name="cloudhsm_cli-key-unwrap-rsa-pkcs-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# The key wrap command in CloudHSM CLI
<a name="cloudhsm_cli-key-wrap"></a>

The **key wrap** command in CloudHSM CLI exports an encrypted copy of a symmetric or asymmetric private key from the hardware security module (HSM) to a file. When you run **key wrap**, you specify two things: The key to export and the output file. The key to export is a key on the HSM that will encrypt (wrap) the key that you want to export.

The **key wrap** command does not remove the key from the HSM or prevent you from using it in cryptographic operations. You can export the same key multiple times. To import the encrypted key back into the HSM, use [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md). Only the owner of a key, that is the crypto user (CU) who created the key, can wrap the key. Users with whom the key is shared can only use the key in cryptographic operations.

The **key wrap** command consists of the following subcommands:
+ [aes-gcm](cloudhsm_cli-key-wrap-aes-gcm.md)
+ [aes-no-pad](cloudhsm_cli-key-wrap-aes-no-pad.md)
+ [aes-pkcs5-pad](cloudhsm_cli-key-wrap-aes-pkcs5-pad.md)
+ [aes-zero-pad](cloudhsm_cli-key-wrap-aes-zero-pad.md)
+ [cloudhsm-aes-gcm](cloudhsm_cli-key-wrap-cloudhsm-aes-gcm.md)
+ [rsa-aes](cloudhsm_cli-key-wrap-rsa-aes.md)
+ [rsa-oaep](cloudhsm_cli-key-wrap-rsa-oaep.md)
+ [rsa-pkcs](cloudhsm_cli-key-wrap-rsa-pkcs.md)

# Wrap a key with AES-GCM using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-aes-gcm"></a>

Use the **key wrap aes-gcm** command in CloudHSM CLI to wrap a payload key using an AES key on the hardware security module (HSM) and the `AES-GCM` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

Only the owner of a key, that is the crypto user (CU) who created the key, can wrap the key. Users who share the key can use the key in cryptographic operations.

To use the **key wrap aes-gcm** command, you must first have an AES key in your AWS CloudHSM cluster. You can generate an AES key for wrapping with the [Generate a symmetric AES key with CloudHSM CLI](cloudhsm_cli-key-generate-symmetric-aes.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-aes-gcm-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-aes-gcm-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-aes-gcm-syntax"></a>

```
aws-cloudhsm > help key wrap aes-gcm
Usage: key wrap aes-gcm [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...] --tag-length-bits <TAG_LENGTH_BITS>

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
      --payload-filter [<PAYLOAD_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 payload key
      --wrapping-filter [<WRAPPING_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 wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
      --aad <AAD>
          Aes GCM Additional Authenticated Data (AAD) value, in hex
      --tag-length-bits <TAG_LENGTH_BITS>
          Aes GCM tag length in bits
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-aes-gcm-examples"></a>

This example shows how to use the **key wrap aes-gcm** command using an AES key.

**Example**  

```
aws-cloudhsm > key wrap aes-gcm --payload-filter attr.label=payload-key --wrapping-filter attr.label=aes-example --tag-length-bits 64  --aad 0x10
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000001c08ea",
    "iv": "0xf90613bb8e337ec0339aad21",
    "wrapped_key_data": "xvslgrtg8kHzrvekny97tLSIeokpPwV8"
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-aes-gcm-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
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 payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
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 wrapping key.   
Required: Yes

***<AAD>***  
AES GCM Additional Authenticated Data (AAD) value, in hex.   
Required: No

***<TAG\$1LENGTH\$1BITS>***  
AES GCM tag length in bits.  
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-aes-gcm-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with AES-NO-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-aes-no-pad"></a>

Use the **key wrap aes-no-pad** command in CloudHSM CLI to wrap a payload key using an AES key on the hardware security module (HSM) and the `AES-NO-PAD` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

Only the owner of a key, that is the crypto user (CU) who created the key, can wrap the key. Users who share the key can use the key in cryptographic operations.

To use the **key wrap aes-no-pad** command, you must first have an AES key in your AWS CloudHSM cluster. You can generate an AES key for wrapping using the [Generate a symmetric AES key with CloudHSM CLI](cloudhsm_cli-key-generate-symmetric-aes.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-aes-no-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-aes-no-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-aes-no-pad-syntax"></a>

```
aws-cloudhsm > help key wrap aes-no-pad
Usage: key wrap aes-no-pad [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...]

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
      --payload-filter [<PAYLOAD_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 payload key
      --wrapping-filter [<WRAPPING_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 wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-aes-no-pad-examples"></a>

This example shows how to use the **key wrap aes-no-pad** command using an AES key with the `wrap` attribute value set to `true`.

**Example**  

```
aws-cloudhsm > key wrap aes-no-pad --payload-filter attr.label=payload-key --wrapping-filter attr.label=aes-example
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000001c08ea",
    "wrapped_key_data": "eXK3PMAOnKM9y3YX6brbhtMoC060EOH9"
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-aes-no-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
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 payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
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 wrapping key.   
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-aes-no-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with AES-PKCS5-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad"></a>

Use the **key wrap aes-pkcs5-pad** command in CloudHSM CLI to wrap a payload key using an AES key on the hardware security module (HSM) and the `AES-PKCS5-PAD` wrapping mechanism. The payload key's `extractable` attribute must be set to `true`.

Only the owner of a key, that is the crypto user (CU) who created the key, can wrap the key. Users who share the key can use the key in cryptographic operations.

To use the **key wrap aes-pkcs5-pad** command, you must first have an AES key in your AWS CloudHSM cluster. You can generate an AES key for wrapping using the [Generate a symmetric AES key with CloudHSM CLI](cloudhsm_cli-key-generate-symmetric-aes.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-syntax"></a>

```
aws-cloudhsm > help key wrap aes-pkcs5-pad
Usage: key wrap aes-pkcs5-pad [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...]

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
      --payload-filter [<PAYLOAD_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 payload key
      --wrapping-filter [<WRAPPING_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 wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-examples"></a>

This example shows how to use the **key wrap aes-pkcs5-pad** command using an AES key with the `wrap` attribute value set to `true`.

**Example**  

```
aws-cloudhsm > key wrap aes-pkcs5-pad --payload-filter attr.label=payload-key --wrapping-filter attr.label=aes-example
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000001c08ea",
    "wrapped_key_data": "MbuYNresfOKyGNnxKWen88nSfX+uUE/0qmGofSisicY="
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
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 payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
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 wrapping key.   
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-aes-pkcs5-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with AES-ZERO-PAD using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-aes-zero-pad"></a>

Use the **key wrap aes-zero-pad** command in CloudHSM CLI to wrap a payload key using an AES key on the hardware security module HSM) and the `AES-ZERO-PAD` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

Only the owner of a key, that is the crypto user (CU) who created the key, can wrap the key. Users who share the key can use the key in cryptographic operations.

To use the **key wrap aes-zero-pad** command, you must first have an AES key in your AWS CloudHSM cluster. You can generate an AES key for wrapping using the [Generate a symmetric AES key with CloudHSM CLI](cloudhsm_cli-key-generate-symmetric-aes.md) command with the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-syntax"></a>

```
aws-cloudhsm > help key wrap aes-zero-pad
Usage: key wrap aes-zero-pad [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...]

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
      --payload-filter [<PAYLOAD_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 payload key
      --wrapping-filter [<WRAPPING_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 wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-examples"></a>

This example shows how to use the **key wrap aes-zero-pad ** command using an AES key with the `wrap` attribute value set to `true`.

**Example**  

```
aws-cloudhsm > key wrap aes-zero-pad --payload-filter attr.label=payload-key --wrapping-filter attr.label=aes-example
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000001c08ea",
    "wrapped_key_data": "L1wVlL/YeBNVAw6Mpk3owFJZXBzDLONt"
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
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 payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
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 wrapping key.   
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-aes-zero-pad-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with CLOUDHSM-AES-GCM using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm"></a>

Use the **key wrap cloudhsm-aes-gcm** command in CloudHSM CLI to wrap a payload key using an AES key on the hardware security module (HSM) and the `CLOUDHSM-AES-GCM` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

Only the owner of a key, that is the crypto user (CU) who created the key, can wrap the key. Users who share the key can use the key in cryptographic operations.

To use the **key wrap cloudhsm-aes-gcm** command, you must first have an AES key in your AWS CloudHSM cluster. You can generate an AES key for wrapping with the [Generate a symmetric AES key with CloudHSM CLI](cloudhsm_cli-key-generate-symmetric-aes.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-syntax"></a>

```
aws-cloudhsm > help key wrap cloudhsm-aes-gcm
Usage: key wrap cloudhsm-aes-gcm [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...] --tag-length-bits <TAG_LENGTH_BITS>

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
      --payload-filter [<PAYLOAD_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 payload key
      --wrapping-filter [<WRAPPING_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 wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
      --aad <AAD>
          Aes GCM Additional Authenticated Data (AAD) value, in hex
      --tag-length-bits <TAG_LENGTH_BITS>
          Aes GCM tag length in bits
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-examples"></a>

This example shows how to use the **key wrap cloudhsm-aes-gcm** command using an AES key.

**Example**  

```
aws-cloudhsm > key wrap cloudhsm-aes-gcm --payload-filter attr.label=payload-key --wrapping-filter attr.label=aes-example --tag-length-bits 64 --aad 0x10
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000001c08ea",
    "wrapped_key_data": "6Rn8nkjEriDYlnP3P8nPkYQ8hplOEJ899zsrF+aTB0i/fIlZ"
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
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 payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
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 wrapping key.   
Required: Yes

***<AAD>***  
AES GCM Additional Authenticated Data (AAD) value, in hex.   
Required: No

***<TAG\$1LENGTH\$1BITS>***  
AES GCM tag length in bits.  
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-cloudhsm-aes-gcm-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with RSA-AES using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-rsa-aes"></a>

Use the **key wrap rsa-aes** command in CloudHSM CLI to wrap a payload key using an RSA public key on the hardware security module (HSM) and the RSA-AES wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

Only the owner of a key, that is the crypto user (CU) who created the key, can wrap the key. Users who share the key can use the key in cryptographic operations.

To use the **key wrap rsa-aes** command, you must first have an RSA key in your AWS CloudHSM cluster. You can generate an RSA key pair using the [The generate-asymmetric-pair category in CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-rsa-aes-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-rsa-aes-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-rsa-aes-syntax"></a>

```
aws-cloudhsm > help key wrap rsa-aes
Usage: key wrap rsa-aes [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...] --hash-function <HASH_FUNCTION> --mgf <MGF>

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
      --payload-filter [<PAYLOAD_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 payload key
      --wrapping-filter [<WRAPPING_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 wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
      --hash-function <HASH_FUNCTION>
          Hash algorithm [possible values: sha1, sha224, sha256, sha384, sha512]
      --mgf <MGF>
          Mask Generation Function algorithm [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512]
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-rsa-aes-examples"></a>

This example shows how to use the **key wrap rsa-ae** command using an RSA public key with the `wrap` attribute value set to `true`.

**Example**  

```
aws-cloudhsm > key wrap rsa-aes --payload-filter attr.label=payload-key --wrapping-filter attr.label=rsa-public-key-example --hash-function sha256 --mgf mgf1-sha256
{
  "error_code": 0,
  "data": {
    "payload-key-reference": "0x00000000001c08f1",
    "wrapping-key-reference": "0x00000000007008da",
    "wrapped-key-data": "HrSE1DEyLjIeyGdPa9R+ebiqB5TIJGyamPker31ZebPwRA+NcerbAJO8DJ1lXPygZcI21vIFSZJuWMEiWpe1R9D/5WSYgxLVKex30xCFqebtEzxbKuv4DOmU4meSofqREYvtb3EoIKwjyxCMRQFgoyUCuP4y0f0eSv0k6rSJh4NuCsHptXZbtgNeRcR4botN7LlzkEIUcq4fVHaatCwd0J1QGKHKyRhkol+RL5WGXKe4nAboAkC5GO7veI5yHL1SaKlssSJtTL/CFpbSLsAFuYbv/NUCWwMY5mwyVTCSlw+HlgKK+5TH1MzBaSi8fpfyepLT8sHy2Q/VRl6ifb49p6m0KQFbRVvz/OWUd6l4d97BdgtaEz6ueg=="
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-wrap-rsa-aes-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
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 payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
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 wrapping key.   
Required: Yes

***<MGF>***  
Specifies the mask generation function.  
The mask generation function hash function must match the signing mechanism hash function.
Valid values  
+ mgf1-sha1
+ mgf1-sha224
+ mgf1-sha256
+ mgf1-sha384
+ mgf1-sha512
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-rsa-aes-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with RSA-OAEP using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-rsa-oaep"></a>

Use the **key wrap rsa-oaep** command in CloudHSM CLI to wrap a payload key using an RSA public key on the hardware security module (HSM) and the `RSA-OAEP` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

Only the owner of a key, that is the crypto user (CU) who created the key, can wrap the key. Users who share the key can use the key in cryptographic operations.

To use the **key wrap rsa-oaep** command, you must first have an RSA key in your AWS CloudHSM cluster. You can generate an RSA key pair using the [The generate-asymmetric-pair category in CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-unwrap-rsa-aes-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-unwrap-rsa-aes-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-unwrap-rsa-aes-syntax"></a>

```
aws-cloudhsm > help key wrap rsa-oaep
Usage: key wrap rsa-oaep [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...] --hash-function <HASH_FUNCTION> --mgf <MGF>

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
      --payload-filter [<PAYLOAD_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 payload key
      --wrapping-filter [<WRAPPING_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 wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
      --hash-function <HASH_FUNCTION>
          Hash algorithm [possible values: sha1, sha224, sha256, sha384, sha512]
      --mgf <MGF>
          Mask Generation Function algorithm [possible values: mgf1-sha1, mgf1-sha224, mgf1-sha256, mgf1-sha384, mgf1-sha512]
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-unwrap-rsa-aes-examples"></a>

This example shows how to use the **key wrap rsa-oaep** command using an RSA public key with the `wrap` attribute value set to `true`.

**Example**  

```
aws-cloudhsm > key wrap rsa-oaep --payload-filter attr.label=payload-key --wrapping-filter attr.label=rsa-public-key-example --hash-function sha256 --mgf mgf1-sha256
{
  "error_code": 0,
  "data": {
    "payload-key-reference": "0x00000000001c08f1",
    "wrapping-key-reference": "0x00000000007008da",
    "wrapped-key-data": "OjJe4msobPLz9TuSAdULEu17T5rMDWtSlLyBSkLbaZnYzzpdrhsbGLbwZJCtB/jGkDNdB4qyTAOQwEpggGf6v+Yx6JcesNeKKNU8XZal/YBoHC8noTGUSDI2qr+u2tDc84NPv6d+F2KOONXsSxMhmxzzNG/gzTVIJhOuy/B1yHjGP4mOXoDZf5+7f5M1CjxBmz4Vva/wrWHGCSG0yOaWblEvOiHAIt3UBdyKmU+/My4xjfJv7WGGu3DFUUIZ06TihRtKQhUYU1M9u6NPf9riJJfHsk6QCuSZ9yWThDT9as6i7e3htnyDhIhGWaoK8JU855cN/YNKAUqkNpC4FPL3iw=="
  }
}
```

## Arguments
<a name="cloudhsm_cli-key-unwrap-rsa-aes-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
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 payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
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 wrapping key.   
Required: Yes

***<MGF>***  
Specifies the mask generation function.  
The mask generation function hash function must match the signing mechanism hash function.
Valid values  
+ mgf1-sha1
+ mgf1-sha224
+ mgf1-sha256
+ mgf1-sha384
+ mgf1-sha512
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-unwrap-rsa-aes-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)

# Wrap a key with RSA-PKCS using CloudHSM CLI
<a name="cloudhsm_cli-key-wrap-rsa-pkcs"></a>

Use the **key wrap rsa-pkcs** command in CloudHSM CLI to wrap a payload key using an RSA public key on the hardware security module (HSM) and the `RSA-PKCS` wrapping mechanism. The payload key’s `extractable` attribute must be set to `true`.

Only the owner of a key, that is the crypto user (CU) who created the key, can wrap the key. Users who share the key can use the key in cryptographic operations.

To use the **key wrap rsa-pkcs** command, you must first have an RSA key in your AWS CloudHSM cluster. You can generate an RSA key pair using the [The generate-asymmetric-pair category in CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair.md) command and the `wrap` attribute set to `true`.

## User type
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-userType"></a>

The following types of users can run this command.
+ Crypto users (CUs)

## Requirements
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-requirements"></a>
+ To run this command, you must be logged in as a CU.

## Syntax
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-syntax"></a>

```
aws-cloudhsm > help key wrap rsa-pkcs
Usage: key wrap rsa-pkcs [OPTIONS] --payload-filter [<PAYLOAD_FILTER>...] --wrapping-filter [<WRAPPING_FILTER>...]

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
      --payload-filter [<PAYLOAD_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 payload key
      --wrapping-filter [<WRAPPING_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 wrapping key
      --path <PATH>
          Path to the binary file where the wrapped key data will be saved
      --wrapping-approval <WRAPPING_APPROVALR>
          File path of signed quorum token file to approve operation for wrapping key
      --payload-approval <PAYLOAD_APPROVALR>
          File path of signed quorum token file to approve operation for payload key
  -h, --help
          Print help
```

## Example
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-examples"></a>

This example shows how to use the **key wrap rsa-pkcs** command using an RSA public key.

**Example**  

```
aws-cloudhsm > key wrap rsa-pkcs --payload-filter attr.label=payload-key --wrapping-filter attr.label=rsa-public-key-example
{
  "error_code": 0,
  "data": {
    "payload_key_reference": "0x00000000001c08f1",
    "wrapping_key_reference": "0x00000000007008da",
    "wrapped_key_data": "am0Nc7+YE8FWs+5HvU7sIBcXVb24QA0l65nbNAD+1bK+e18BpSfnaI3P+r8Dp+pLu1ofoUy/vtzRjZoCiDofcz4EqCFnGl4GdcJ1/3W/5WRvMatCa2d7cx02swaeZcjKsermPXYRO1lGlfq6NskwMeeTkV8R7Rx9artFrs1y0DdIgIKVaiFHwnBIUMnlQrR2zRmMkfwU1jxMYmOYyD031F5VbnjSrhfMwkww2la7uf/c3XdFJ2+0Bo94c6og/yfPcpOOobJlITCoXhtMRepSdO4OggYq/6nUDuHCtJ86pPGnNahyr7+sAaSI3a5ECQLUjwaIARUCyoRh7EFK3qPXcg=="
  }
```

## Arguments
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-arguments"></a>

***<CLUSTER\$1ID>***  
The ID of the cluster to run this operation on.  
Required: If multiple clusters have been [configured.](cloudhsm_cli-configs-multi-cluster.md)

***<PAYLOAD\$1FILTER>***  
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 payload key.  
Required: Yes

***<PATH>***  
Path to the binary file where the wrapped key data will be saved.  
Required: No

***<WRAPPING\$1FILTER>***  
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 wrapping key.   
Required: Yes

***<WRAPPING\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for wrapping key. Only required if wrapping key's key management service quorum value is greater than 1.

***<PAYLOAD\$1APPROVALR>***  
Specifies the file path to a signed quorum token file to approve operation for payload key. Only required if payload key's key management service quorum value is greater than 1.

## Related topics
<a name="cloudhsm_cli-key-wrap-rsa-pkcs-seealso"></a>
+ [The key wrap command in CloudHSM CLI](cloudhsm_cli-key-wrap.md)
+ [The key unwrap command in CloudHSM CLI](cloudhsm_cli-key-unwrap.md)