There are more AWS SDK examples available in the [AWS Doc SDK Examples](https://github.com/awsdocs/aws-doc-sdk-examples) GitHub repo.
# AWS KMS examples using AWS CLI
The following code examples show you how to perform actions and implement common scenarios by using the AWS Command Line Interface with AWS KMS.
*Actions* are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.
Each example includes a link to the complete source code, where you can find instructions on how to set up and run the code in context.
**Topics**
+ [Actions](#actions)
## Actions
### `cancel-key-deletion`
The following code example shows how to use `cancel-key-deletion`.
**AWS CLI**
**To cancel the scheduled deletion of a customer managed KMS key**
The following `cancel-key-deletion` example cancels the scheduled deletion of a customer managed KMS key.
```
aws kms cancel-key-deletion \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Output:
```
{
"KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
When the `cancel-key-deletion` command succeeds, the scheduled deletion is canceled. However, the key state of the KMS key is `Disabled`, so you can't use the KMS key in cryptographic operations. To restore its functionality, use the `enable-key` command .
For more information, see [Scheduling and canceling key deletion](https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html#deleting-keys-scheduling-key-deletion) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [CancelKeyDeletion](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/cancel-key-deletion.html) in *AWS CLI Command Reference*.
### `connect-custom-key-store`
The following code example shows how to use `connect-custom-key-store`.
**AWS CLI**
**To connect a custom key store**
The following `connect-custom-key-store` example reconnects the specified custom key store. You can use a command like this one to connect a custom key store for the first time or to reconnect a key store that was disconnected.
You can use this command to connect an AWS CloudHSM key store or an external key store.
```
aws kms connect-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0
```
This command does not return any output. To verify that the command was effective, use the `describe-custom-key-stores` command.
For information about connecting an AWS CloudHSM key store, see [Connecting and disconnecting an AWS CloudHSM key store](https://docs.aws.amazon.com/kms/latest/developerguide/disconnect-keystore.html) in the *AWS Key Management Service Developer Guide*.
For information about connecting an external key store, see [Connecting and disconnecting an external key store](https://docs.aws.amazon.com/kms/latest/developerguide/xks-connect-disconnect.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [ConnectCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/connect-custom-key-store.html) in *AWS CLI Command Reference*.
### `create-alias`
The following code example shows how to use `create-alias`.
**AWS CLI**
**To create an alias for a KMS key**
The following `create-alias` command creates an alias named `example-alias` for the KMS key identified by key ID `1234abcd-12ab-34cd-56ef-1234567890ab`.
Alias names must begin with `alias/`. Do not use alias names that begin with `alias/aws`; these are reserved for use by AWS.
```
aws kms create-alias \
--alias-name alias/example-alias \
--target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
This command doesn't return any output. To see the new alias, use the `list-aliases` command.
For more information, see [Using aliases](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [CreateAlias](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-alias.html) in *AWS CLI Command Reference*.
### `create-custom-key-store`
The following code example shows how to use `create-custom-key-store`.
**AWS CLI**
**Example 1: To create an AWS CloudHSM key store**
The following `create-custom-key-store` example creates an AWS CloudHSM key store backed by an AWS CloudHSM cluster using the required parameters. You can also add the `custom-key-store-type``parameter with the default value: ``AWS_CLOUDHSM`.
To specify the file input for the `trust-anchor-certificate` command in the AWS CLI, the `file://` prefix is required.
```
aws kms create-custom-key-store \
--custom-key-store-name ExampleCloudHSMKeyStore \
--cloud-hsm-cluster-id cluster-1a23b4cdefg \
--key-store-password kmsPswd \
--trust-anchor-certificate file://customerCA.crt
```
Output:
```
{
"CustomKeyStoreId": cks-1234567890abcdef0
}
```
For more information, see [Creating an AWS CloudHSM key store](https://docs.aws.amazon.com/kms/latest/developerguide/create-keystore.html) in the *AWS Key Management Service Developer Guide*.
**Example 2: To create an external key store with public endpoint connectivity**
The following `create-custom-key-store` example creates an external key store (XKS) that communicates with AWS KMS over the internet.
In this example, the `XksProxyUriPath` uses an optional prefix of `example-prefix`.
NOTE: If you use AWS CLI version 1.0, run the following command before specifying a parameter with an HTTP or HTTPS value, such as the XksProxyUriEndpoint parameter.
```
aws configure set cli_follow_urlparam false
```
Otherwise, AWS CLI version 1.0 replaces the parameter value with the content found at that URI address.
```
aws kms create-custom-key-store \
--custom-key-store-name ExamplePublicEndpointXKS \
--custom-key-store-type EXTERNAL_KEY_STORE \
--xks-proxy-connectivity PUBLIC_ENDPOINT \
--xks-proxy-uri-endpoint "https://myproxy.xks.example.com" \
--xks-proxy-uri-path "/example-prefix/kms/xks/v1" \
--xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="
```
Output:
```
{
"CustomKeyStoreId": cks-2234567890abcdef0
}
```
For more information, see [Creating an external key store](https://docs.aws.amazon.com/kms/latest/developerguide/create-keystorecreate-xks-keystore.html) in the *AWS Key Management Service Developer Guide*.
**Example 3: To create an external key store with VPC endpoint service connectivity**
The following `create-custom-key-store` example creates an external key store (XKS) that uses an Amazon VPC endpoint service to communicate with AWS KMS.
NOTE: If you use AWS CLI version 1.0, run the following command before specifying a parameter with an HTTP or HTTPS value, such as the XksProxyUriEndpoint parameter.
```
aws configure set cli_follow_urlparam false
```
Otherwise, AWS CLI version 1.0 replaces the parameter value with the content found at that URI address.
```
aws kms create-custom-key-store \
--custom-key-store-name ExampleVPCEndpointXKS \
--custom-key-store-type EXTERNAL_KEY_STORE \
--xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
--xks-proxy-uri-endpoint "https://myproxy-private.xks.example.com" \
--xks-proxy-uri-path "/kms/xks/v1" \
--xks-proxy-vpc-endpoint-service-name "com.amazonaws.vpce.us-east-1.vpce-svc-example1" \
--xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="
```
Output:
```
{
"CustomKeyStoreId": cks-3234567890abcdef0
}
```
For more information, see [Creating an external key store](https://docs.aws.amazon.com/kms/latest/developerguide/create-keystorecreate-xks-keystore.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [CreateCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-custom-key-store.html) in *AWS CLI Command Reference*.
### `create-grant`
The following code example shows how to use `create-grant`.
**AWS CLI**
**To create a grant**
The following `create-grant` example creates a grant that allows the `exampleUser` user to use the `decrypt` command on the `1234abcd-12ab-34cd-56ef-1234567890ab` example KMS key. The retiring principal is the `adminRole` role. The grant uses the `EncryptionContextSubset` grant constraint to allow this permission only when the encryption context in the `decrypt` request includes the `"Department": "IT"` key-value pair.
```
aws kms create-grant \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--grantee-principal arn:aws:iam::123456789012:user/exampleUser \
--operations Decrypt \
--constraints EncryptionContextSubset={Department=IT} \
--retiring-principal arn:aws:iam::123456789012:role/adminRole
```
Output:
```
{
"GrantId": "1a2b3c4d2f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
"GrantToken": ""
}
```
To view detailed information about the grant, use the `list-grants` command.
For more information, see [Grants in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [CreateGrant](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-grant.html) in *AWS CLI Command Reference*.
### `create-key`
The following code example shows how to use `create-key`.
**AWS CLI**
**Example 1: To create a customer managed KMS key in AWS KMS**
The following `create-key` example creates a symmetric encryption KMS key.
To create the basic KMS key, a symmetric encryption key, you do not need to specify any parameters. The default values for those parameters create a symmetric encryption key.
Because this command doesn't specify a key policy, the KMS key gets the [default key policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default) for programmatically created KMS keys. To view the key policy, use the `get-key-policy` command. To change the key policy, use the `put-key-policy` command.
```
aws kms create-key
```
The `create-key` command returns the key metadata, including the key ID and ARN of the new KMS key. You can use these values to identify the KMS key in other AWS KMS operations. The output does not include the tags. To view the tags for a KMS key, use the `list-resource-tags command`.
Output:
```
{
"KeyMetadata": {
"AWSAccountId": "111122223333",
"Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": "2017-07-05T14:04:55-07:00",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "AWS_KMS"
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
]
}
}
```
Note: The `create-key` command does not let you specify an alias, To create an alias for the new KMS key, use the `create-alias` command.
For more information, see [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service Developer Guide*.
**Example 2: To create an asymmetric RSA KMS key for encryption and decryption**
The following `create-key` example creates a KMS key that contains an asymmetric RSA key pair for encryption and decryption. The key spec and key usage can't be changed after the key is created.:
```
aws kms create-key \
--key-spec RSA_4096 \
--key-usage ENCRYPT_DECRYPT
```
Output:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2021-04-05T14:04:55-07:00",
"CustomerMasterKeySpec": "RSA_4096",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"RSAES_OAEP_SHA_1",
"RSAES_OAEP_SHA_256"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "RSA_4096",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "AWS_KMS"
}
}
```
For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the *AWS Key Management Service Developer Guide*.
**Example 3: To create an asymmetric elliptic curve KMS key for signing and verification**
To create an asymmetric KMS key that contains an asymmetric elliptic curve (ECC) key pair for signing and verification. The `--key-usage` parameter is required even though `SIGN_VERIFY` is the only valid value for ECC KMS keys. The key spec and key usage can't be changed after the key is created.:
```
aws kms create-key \
--key-spec ECC_NIST_P521 \
--key-usage SIGN_VERIFY
```
Output:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2019-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "ECC_NIST_P521",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "ECC_NIST_P521",
"KeyState": "Enabled",
"KeyUsage": "SIGN_VERIFY",
"MultiRegion": false,
"Origin": "AWS_KMS",
"SigningAlgorithms": [
"ECDSA_SHA_512"
]
}
}
```
For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the *AWS Key Management Service Developer Guide*.
**Example 4: To create an asymmetric ML-DSA KMS key for signing and verification**
This example creates a module-lattice digital signature algorithm (ML-DSA) key for signing and verification. The key-usage parameter is required even though `SIGN_VERIFY` is the only valid value for ML-DSA keys.
```
aws kms create-key \
--key-spec ML_DSA_65 \
--key-usage SIGN_VERIFY
```
Output:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2019-12-02T07:48:55-07:00",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "ML_DSA_65",
"KeyState": "Enabled",
"KeyUsage": "SIGN_VERIFY",
"MultiRegion": false,
"Origin": "AWS_KMS",
"SigningAlgorithms": [
"ML_DSA_SHAKE_256"
]
}
}
```
For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the *AWS Key Management Service Developer Guide*.
**Example 5: To create an HMAC KMS key**
The following `create-key` example creates a 384-bit HMAC KMS key. The `GENERATE_VERIFY_MAC` value for the `--key-usage` parameter is required even though it's the only valid value for HMAC KMS keys.
```
aws kms create-key \
--key-spec HMAC_384 \
--key-usage GENERATE_VERIFY_MAC
```
Output:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2022-04-05T14:04:55-07:00",
"CustomerMasterKeySpec": "HMAC_384",
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "HMAC_384",
"KeyState": "Enabled",
"KeyUsage": "GENERATE_VERIFY_MAC",
"MacAlgorithms": [
"HMAC_SHA_384"
],
"MultiRegion": false,
"Origin": "AWS_KMS"
}
}
```
For more information, see [HMAC keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) in the *AWS Key Management Service Developer Guide*.
**Example 6: To create a multi-Region primary KMS key**
The following `create-key` example creates a multi-Region primary symmetric encryption key. Because the default values for all parameters create a symmetric encryption key, only the `--multi-region` parameter is required for this KMS key. In the AWS CLI, to indicate that a Boolean parameter is true, just specify the parameter name.
```
aws kms create-key \
--multi-region
```
Output:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab",
"AWSAccountId": "111122223333",
"CreationDate": "2021-09-02T016:15:21-09:00",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "mrk-1234abcd12ab34cd56ef12345678990ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": true,
"MultiRegionConfiguration": {
"MultiRegionKeyType": "PRIMARY",
"PrimaryKey": {
"Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab",
"Region": "us-west-2"
},
"ReplicaKeys": []
},
"Origin": "AWS_KMS"
}
}
```
For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the *AWS Key Management Service Developer Guide*.
**Example 7: To create a KMS key for imported key material**
The following `create-key` example creates a creates a KMS key with no key material. When the operation is complete, you can import your own key material into the KMS key. To create this KMS key, set the `--origin` parameter to `EXTERNAL`.
```
aws kms create-key \
--origin EXTERNAL
```
Output:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2019-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Description": "",
"Enabled": false,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "PendingImport",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "EXTERNAL"
}
}
```
For more information, see [Importing key material in AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html) in the *AWS Key Management Service Developer Guide*.
**Example 6: To create a KMS key in an AWS CloudHSM key store**
The following `create-key` example creates a creates a KMS key in the specified AWS CloudHSM key store. The operation creates the KMS key and its metadata in AWS KMS and creates the key material in the AWS CloudHSM cluster associated with the custom key store. The `--custom-key-store-id` and `--origin` parameters are required.
```
aws kms create-key \
--origin AWS_CLOUDHSM \
--custom-key-store-id cks-1234567890abcdef0
```
Output:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"CreationDate": "2019-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "AWS_CLOUDHSM"
}
}
```
For more information, see [AWS CloudHSM key stores](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html) in the *AWS Key Management Service Developer Guide*.
**Example 8: To create a KMS key in an external key store**
The following `create-key` example creates a creates a KMS key in the specified external key store. The `--custom-key-store-id`, `--origin`, and `--xks-key-id` parameters are required in this command.
The `--xks-key-id` parameter specifies the ID of an existing symmetric encryption key in your external key manager. This key serves as the external key material for the KMS key.The value of the `--origin` parameter must be `EXTERNAL_KEY_STORE`.The `custom-key-store-id` parameter must identify an external key store that is connected to its external key store proxy.
```
aws kms create-key \
--origin EXTERNAL_KEY_STORE \
--custom-key-store-id cks-9876543210fedcba9 \
--xks-key-id bb8562717f809024
```
Output:
```
{
"KeyMetadata": {
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"CreationDate": "2022-12-02T07:48:55-07:00",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"CustomKeyStoreId": "cks-9876543210fedcba9",
"Description": "",
"Enabled": true,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"MultiRegion": false,
"Origin": "EXTERNAL_KEY_STORE",
"XksKeyConfiguration": {
"Id": "bb8562717f809024"
}
}
}
```
For more information, see [External key stores](https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [CreateKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/create-key.html) in *AWS CLI Command Reference*.
### `decrypt`
The following code example shows how to use `decrypt`.
**AWS CLI**
**Example 1: To decrypt an encrypted message with a symmetric KMS key (Linux and macOS)**
The following `decrypt` command example demonstrates the recommended way to decrypt data with the AWS CLI. This version shows how to decrypt data under a symmetric KMS key.
Provide the ciphertext in a file.In the value of the `--ciphertext-blob` parameter, use the `fileb://` prefix, which tells the CLI to read the data from a binary file. If the file is not in the current directory, type the full path to file. For more information about reading AWS CLI parameter values from a file, see Loading AWS CLI parameters from a file in the *AWS Command Line Interface User Guide* and Best Practices for Local File Parameters in the *AWS Command Line Tool Blog*.Specify the KMS key to decrypt the ciphertext.The `--key-id` parameter is not required when decrypting with a symmetric KMS key. AWS KMS can get the key ID of the KMS key that was used to encrypt the data from the metadata in the ciphertext. But it's always a best practice to specify the KMS key you are using. This practice ensures that you use the KMS key that you intend, and prevents you from inadvertently decrypting a ciphertext using a KMS key you do not trust.Request the plaintext output as a text value.The `--query` parameter tells the CLI to get only the value of the `Plaintext` field from the output. The `--output` parameter returns the output as text.Base64-decode the plaintext and save it in a file.The following example pipes (\$1) the value of the `Plaintext` parameter to the Base64 utility, which decodes it. Then, it redirects (>) the decoded output to the `ExamplePlaintext` file.
Before running this command, replace the example key ID with a valid key ID from your AWS account.
```
aws kms decrypt \
--ciphertext-blob fileb://ExampleEncryptedFile \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--output text \
--query Plaintext | base64 \
--decode > ExamplePlaintextFile
```
This command produces no output. The output from the `decrypt` command is base64-decoded and saved in a file.
For more information, see [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) in the *AWS Key Management Service API Reference*.
**Example 2: To decrypt an encrypted message with a symmetric KMS key (Windows command prompt)**
The following example is the same as the previous one except that it uses the `certutil` utility to Base64-decode the plaintext data. This procedure requires two commands, as shown in the following examples.
Before running this command, replace the example key ID with a valid key ID from your AWS account.
```
aws kms decrypt ^
--ciphertext-blob fileb://ExampleEncryptedFile ^
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab ^
--output text ^
--query Plaintext > ExamplePlaintextFile.base64
```
Run the `certutil` command.
```
certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile
```
Output:
```
Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.
```
For more information, see [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) in the *AWS Key Management Service API Reference*.
**Example 3: To decrypt an encrypted message with an asymmetric KMS key (Linux and macOS)**
The following `decrypt` command example shows how to decrypt data encrypted under an RSA asymmetric KMS key.
When using an asymmetric KMS key, the `encryption-algorithm` parameter, which specifies the algorithm used to encrypt the plaintext, is required.
Before running this command, replace the example key ID with a valid key ID from your AWS account.
```
aws kms decrypt \
--ciphertext-blob fileb://ExampleEncryptedFile \
--key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--encryption-algorithm RSAES_OAEP_SHA_256 \
--output text \
--query Plaintext | base64 \
--decode > ExamplePlaintextFile
```
This command produces no output. The output from the `decrypt` command is base64-decoded and saved in a file.
For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [Decrypt](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/decrypt.html) in *AWS CLI Command Reference*.
### `delete-alias`
The following code example shows how to use `delete-alias`.
**AWS CLI**
**To delete an AWS KMS alias**
The following `delete-alias` example deletes the alias `alias/example-alias`. The alias name must begin with alias/.
```
aws kms delete-alias \
--alias-name alias/example-alias
```
This command produces no output. To find the alias, use the `list-aliases` command.
For more information, see [Deleting an alias](https://docs.aws.amazon.com/kms/latest/developerguide/alias-manage.html#alias-delete) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [DeleteAlias](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/delete-alias.html) in *AWS CLI Command Reference*.
### `delete-custom-key-store`
The following code example shows how to use `delete-custom-key-store`.
**AWS CLI**
**To delete a custom key store**
The following `delete-custom-key-store` example deletes the specified custom key store.
Deleting an AWS CloudHSM key store has no effect on the associated CloudHSM cluster. Deleting an external key store has no effect on the associated external key store proxy, external key manager, or external keys.
**NOTE:** Before you can delete a custom key store, you must schedule the deletion of all KMS keys in the custom key store and then wait for those KMS keys to be deleted. Then, you must disconnect the custom key store. For help finding the KMS keys in your custom key store, see [Delete an AWS CloudHSM key store (API)](https://docs.aws.amazon.com/kms/latest/developerguide/delete-keystore.html#delete-keystore-api) in the *AWS Key Management Service Developer Guide*.
```
delete-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0
```
This command does not return any output. To verify that the custom key store is deleted, use the `describe-custom-key-stores` command.
For information about deleting an AWS CloudHSM key stores, see [Deleting an AWS CloudHSM key store](https://docs.aws.amazon.com/kms/latest/developerguide/delete-keystore.html) in the *AWS Key Management Service Developer Guide*.
For information about deleting external key stores, see [Deleting an external key store](https://docs.aws.amazon.com/kms/latest/developerguide/delete-xks.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [DeleteCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/delete-custom-key-store.html) in *AWS CLI Command Reference*.
### `delete-imported-key-material`
The following code example shows how to use `delete-imported-key-material`.
**AWS CLI**
**To delete imported key material from a KMS key**
The following `delete-imported-key-material` example deletes key material that had been imported into a KMS key.
```
aws kms delete-imported-key-material \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Output:
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
For more information, see [Deleting imported key material](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-delete-key-material.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [DeleteImportedKeyMaterial](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/delete-imported-key-material.html) in *AWS CLI Command Reference*.
### `derive-shared-secret`
The following code example shows how to use `derive-shared-secret`.
**AWS CLI**
**To derive a shared secret**
The following `derive-shared-secret` example derives a shared secret using a key agreement algorithm.
You must use an asymmetric NIST-recommended elliptic curve (ECC) or SM2 (China Regions only) KMS key pair with a `KeyUsage` value of `KEY_AGREEMENT` to call DeriveSharedSecret.
```
aws kms derive-shared-secret \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-agreement-algorithm ECDH \
--public-key "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvH3Yj0wbkLEpUl95Cv1cJVjsVNSjwGq3tCLnzXfhVwVvmzGN8pYj3U8nKwgouaHbBWNJYjP5VutbbkKS4Kv4GojwZBJyHN17kmxo8yTjRmjR15SKIQ8cqRA2uaERMLnpztIXdZp232PQPbWGxDyXYJ0aJ5EFSag"
```
Output:
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"SharedSecret": "MEYCIQCKZLWyTk5runarx6XiAkU9gv3lbwPO/pHa+DXFehzdDwIhANwpsIV2g/9SPWLLsF6p/hiSskuIXMTRwqrMdVKWTMHG",
"KeyAgreementAlgorithm": "ECDH",
"KeyOrigin": "AWS_KMS"
}
```
For more information, see [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) in the *AWS Key Management Service API Reference*.
+ For API details, see [DeriveSharedSecret](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/derive-shared-secret.html) in *AWS CLI Command Reference*.
### `describe-custom-key-stores`
The following code example shows how to use `describe-custom-key-stores`.
**AWS CLI**
**Example 1: To get details about an AWS CloudHSM key store**
The following `describe-custom-key-store` example displays details about the specified AWS CloudHSM key store. The command is the same for all types of custom key stores, but the output differs with the key store type and, for an external key store, its connectivity option.
By default, this command displays information about all custom key stores in the account and Region. To display information about a particular custom key store, use the `custom-key-store-name` or `custom-key-store-id` parameter.
```
aws kms describe-custom-key-stores \
--custom-key-store-name ExampleCloudHSMKeyStore
```
The output of this command includes useful details about the AWS CloudHSM key store including its connection state (`ConnectionState`). If the connection state is `FAILED`, the output includes a `ConnectionErrorCode` field that describes the problem.
Output:
```
{
"CustomKeyStores": [
{
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-04-05T14:04:55-07:00",
"CustomKeyStoreId": "cks-1234567890abcdef0",
"CustomKeyStoreName": "ExampleExternalKeyStore",
"TrustAnchorCertificate": ""
}
]
}
```
For more information, see [Viewing an AWS CloudHSM key store](https://docs.aws.amazon.com/kms/latest/developerguide/view-keystore.html) in the *AWS Key Management Service Developer Guide*.
**Example 2: To get details about an external key store with public endpoint connectivity**
The following `describe-custom-key-store` example displays details about the specified external key store. The command is the same for all types of custom key stores, but the output differs with the key store type and, for an external key store, its connectivity option.
By default, this command displays information about all custom key stores in the account and Region. To display information about a particular custom key store, use the `custom-key-store-name` or `custom-key-store-id` parameter.
```
aws kms describe-custom-key-stores \
--custom-key-store-id cks-9876543210fedcba9
```
The output of this command includes useful details about the external key store including its connection state (`ConnectionState`). If the connection state is `FAILED`, the output includes a `ConnectionErrorCode` field that describes the problem.
Output:
```
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-9876543210fedcba9",
"CustomKeyStoreName": "ExampleXKS",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-12-02T07:48:55-07:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE12345670EXAMPLE",
"Connectivity": "PUBLIC_ENDPOINT",
"UriEndpoint": "https://myproxy.xks.example.com",
"UriPath": "/example-prefix/kms/xks/v1"
}
}
]
}
```
For more information, see [Viewing an external key store](https://docs.aws.amazon.com/kms/latest/developerguide/view-xks-keystore.html) in the *AWS Key Management Service Developer Guide*.
**Example 3: To get details about an external key store with VPC endpoint service connectivity**
The following `describe-custom-key-store` example displays details about the specified external key store. The command is the same for all types of custom key stores, but the output differs with the key store type and, for an external key store, its connectivity option.
By default, this command displays information about all custom key stores in the account and Region. To display information about a particular custom key store, use the `custom-key-store-name` or `custom-key-store-id` parameter.
```
aws kms describe-custom-key-stores \
--custom-key-store-id cks-2234567890abcdef0
```
The output of this command includes useful details about the external key store including its connection state (`ConnectionState`). If the connection state is `FAILED`, the output includes a `ConnectionErrorCode` field that describes the problem.
Output:
```
{
"CustomKeyStores": [
{
"CustomKeyStoreId": "cks-3234567890abcdef0",
"CustomKeyStoreName": "ExampleVPCExternalKeyStore",
"ConnectionState": "CONNECTED",
"CreationDate": "2022-12-22T07:48:55-07:00",
"CustomKeyStoreType": "EXTERNAL_KEY_STORE",
"XksProxyConfiguration": {
"AccessKeyId": "ABCDE12345670EXAMPLE",
"Connectivity": "VPC_ENDPOINT_SERVICE",
"UriEndpoint": "https://myproxy-private.xks.example.com",
"UriPath": "/kms/xks/v1",
"VpcEndpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-example1"
}
}
]
}
```
For more information, see [Viewing an external key store](https://docs.aws.amazon.com/kms/latest/developerguide/view-xks-keystore.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [DescribeCustomKeyStores](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/describe-custom-key-stores.html) in *AWS CLI Command Reference*.
### `describe-key`
The following code example shows how to use `describe-key`.
**AWS CLI**
**Example 1: To find detailed information about a KMS key**
The following `describe-key` example gets detailed information about the AWS managed key for Amazon S3 in the example account and Region. You can use this command to find details about AWS managed keys and customer managed keys.
To specify the KMS key, use the `key-id` parameter. This example uses an alias name value, but you can use a key ID, key ARN, alias name, or alias ARN in this command.
```
aws kms describe-key \
--key-id alias/aws/s3
```
Output:
```
{
"KeyMetadata": {
"AWSAccountId": "846764612917",
"KeyId": "b8a9477d-836c-491f-857e-07937918959b",
"Arn": "arn:aws:kms:us-west-2:846764612917:key/b8a9477d-836c-491f-857e-07937918959b",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CreationDate": 2017-06-30T21:44:32.140000+00:00,
"Enabled": true,
"Description": "Default KMS key that protects my S3 objects when no other key is defined",
"KeyUsage": "ENCRYPT_DECRYPT",
"KeyState": "Enabled",
"Origin": "AWS_KMS",
"KeyManager": "AWS",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
]
}
}
```
For more information, see [Viewing keys](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html) in the *AWS Key Management Service Developer Guide*.
**Example 2: To get details about an RSA asymmetric KMS key**
The following `describe-key` example gets detailed information about an asymmetric RSA KMS key used for signing and verification.
```
aws kms describe-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Output:
```
{
"KeyMetadata": {
"AWSAccountId": "111122223333",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": "2019-12-02T19:47:14.861000+00:00",
"CustomerMasterKeySpec": "RSA_2048",
"Enabled": false,
"Description": "",
"KeyState": "Disabled",
"Origin": "AWS_KMS",
"MultiRegion": false,
"KeyManager": "CUSTOMER",
"KeySpec": "RSA_2048",
"KeyUsage": "SIGN_VERIFY",
"SigningAlgorithms": [
"RSASSA_PKCS1_V1_5_SHA_256",
"RSASSA_PKCS1_V1_5_SHA_384",
"RSASSA_PKCS1_V1_5_SHA_512",
"RSASSA_PSS_SHA_256",
"RSASSA_PSS_SHA_384",
"RSASSA_PSS_SHA_512"
]
}
}
```
**Example 3: To get details about a multi-Region replica key**
The following `describe-key` example gets metadata for a multi-Region replica key. This multi-Region key is a symmetric encryption key. The output of a `describe-key` command for any multi-Region key returns information about the primary key and all of its replicas.
```
aws kms describe-key \
--key-id arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab
```
Output:
```
{
"KeyMetadata": {
"MultiRegion": true,
"AWSAccountId": "111122223333",
"Arn": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"CreationDate": "2021-06-28T21:09:16.114000+00:00",
"CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"Description": "",
"Enabled": true,
"KeyId": "mrk-1234abcd12ab34cd56ef1234567890ab",
"KeyManager": "CUSTOMER",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"Origin": "AWS_KMS",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"MultiRegionConfiguration": {
"MultiRegionKeyType": "PRIMARY",
"PrimaryKey": {
"Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "us-west-2"
},
"ReplicaKeys": [
{
"Arn": "arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "eu-west-1"
},
{
"Arn": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "ap-northeast-1"
},
{
"Arn": "arn:aws:kms:sa-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "sa-east-1"
}
]
}
}
}
```
**Example 4: To get details about an HMAC KMS key**
The following `describe-key` example gets detailed information about an HMAC KMS key.
```
aws kms describe-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Output:
```
{
"KeyMetadata": {
"AWSAccountId": "123456789012",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Arn": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": "2022-04-03T22:23:10.194000+00:00",
"Enabled": true,
"Description": "Test key",
"KeyUsage": "GENERATE_VERIFY_MAC",
"KeyState": "Enabled",
"Origin": "AWS_KMS",
"KeyManager": "CUSTOMER",
"CustomerMasterKeySpec": "HMAC_256",
"MacAlgorithms": [
"HMAC_SHA_256"
],
"MultiRegion": false
}
}
```
+ For API details, see [DescribeKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/describe-key.html) in *AWS CLI Command Reference*.
### `disable-key-rotation`
The following code example shows how to use `disable-key-rotation`.
**AWS CLI**
**To disable automatic rotation of a KMS key**
The following `disable-key-rotation` example disables automatic rotation of a customer managed KMS key. To reenable automatic rotation, use the `enable-key-rotation` command.
```
aws kms disable-key-rotation \
--key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
This command produces no output. To verify that automatic rotation is disable for the KMS key, use the `get-key-rotation-status` command.
For more information, see [Rotating keys](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [DisableKeyRotation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/disable-key-rotation.html) in *AWS CLI Command Reference*.
### `disable-key`
The following code example shows how to use `disable-key`.
**AWS CLI**
**To temporarily disable a KMS key**
The following `disable-key` command disables a customer managed KMS key. To re-enable the KMS key, use the `enable-key` command.
```
aws kms disable-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
This command produces no output.
For more information, see [Enabling and Disabling Keys](https://docs.aws.amazon.com/kms/latest/developerguide/enabling-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [DisableKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/disable-key.html) in *AWS CLI Command Reference*.
### `disconnect-custom-key-store`
The following code example shows how to use `disconnect-custom-key-store`.
**AWS CLI**
**To disconnect a custom key store**
The following `disconnect-custom-key-store` example disconnects a custom key store from its AWS CloudHSM cluster. You might disconnect a key store to troubleshoot a problem, to update its settings, or to prevent KMS keys in the keystore from being used in cryptographic operations.
This command is the same for all custom key stores, including AWS CloudHSM key stores and external key stores.
Before running this command, replace the example custom key store ID with a valid one.
```
$ aws kms disconnect-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0
```
This command produces no output. verify that the command was effective, use the `describe-custom-key-stores` command.
For more information about disconnecting an AWS CloudHSM key store, see [Connecting and disconnecting an AWS CloudHSM key store](https://docs.aws.amazon.com/kms/latest/developerguide/disconnect-keystore.html) in the *AWS Key Management Service Developer Guide*.
For more information about disconnecting an external key store, see [Connecting and disconnecting an external key store](https://docs.aws.amazon.com/kms/latest/developerguide/xks-connect-disconnect.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [DisconnectCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/disconnect-custom-key-store.html) in *AWS CLI Command Reference*.
### `enable-key-rotation`
The following code example shows how to use `enable-key-rotation`.
**AWS CLI**
**To enable automatic rotation of a KMS key**
The following `enable-key-rotation` example enables automatic rotation of a customer managed KMS key with a rotation period of 180 days. The KMS key will be rotated one year (approximate 365 days) from the date that this command completes and every year thereafter.
The `--key-id` parameter identifies the KMS key. This example uses a key ARN value, but you can use either the key ID or the ARN of the KMS key.The `--rotation-period-in-days` parameter specifies the number of days between each rotation date. Specify a value between 90 and 2560 days. If no value is specified, the default value is 365 days.
```
aws kms enable-key-rotation \
--key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--rotation-period-in-days 180
```
This command produces no output. To verify that the KMS key is enabled, use the `get-key-rotation-status` command.
For more information, see [Rotating keys](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [EnableKeyRotation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/enable-key-rotation.html) in *AWS CLI Command Reference*.
### `enable-key`
The following code example shows how to use `enable-key`.
**AWS CLI**
**To enable a KMS key**
The following `enable-key` example enables a customer managed key. You can use a command like this one to enable a KMS key that you temporarily disabled by using the `disable-key` command. You can also use it to enable a KMS key that is disabled because it was scheduled for deletion and the deletion was canceled.
To specify the KMS key, use the `key-id` parameter. This example uses an key ID value, but you can use a key ID or key ARN value in this command.
Before running this command, replace the example key ID with a valid one.
```
aws kms enable-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
This command produces no output. To verify that the KMS key is enabled, use the `describe-key` command. See the values of the `KeyState` and `Enabled` fields in the `describe-key` output.
For more information, see [Enabling and Disabling Keys](https://docs.aws.amazon.com/kms/latest/developerguide/enabling-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [EnableKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/enable-key.html) in *AWS CLI Command Reference*.
### `encrypt`
The following code example shows how to use `encrypt`.
**AWS CLI**
**Example 1: To encrypt the contents of a file on Linux or MacOS**
The following `encrypt` command demonstrates the recommended way to encrypt data with the AWS CLI.
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
The command does several things:
Uses the `--plaintext` parameter to indicate the data to encrypt. This parameter value must be base64-encoded.The value of the `plaintext` parameter must be base64-encoded, or you must use the `fileb://` prefix, which tells the AWS CLI to read binary data from the file.If the file is not in the current directory, type the full path to file. For example: `fileb:///var/tmp/ExamplePlaintextFile` or `fileb://C:\Temp\ExamplePlaintextFile`. For more information about reading AWS CLI parameter values from a file, see [Loading Parameters from a File](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#cli-using-param-file) in the *AWS Command Line Interface User Guide* and [Best Practices for Local File Parameters](https://blogs.aws.amazon.com/cli/post/TxLWWN1O25V1HE/Best-Practices-for-Local-File-Parameters) on the AWS Command Line Tool Blog.Uses the `--output` and `--query` parameters to control the command's output.These parameters extract the encrypted data, called the *ciphertext*, from the command's output.For more information about controlling output, see [Controlling Command Output](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html) in the *AWS Command Line Interface User Guide*.Uses the `base64` utility to decode the extracted output into binary data.The ciphertext that is returned by a successful `encrypt` command is base64-encoded text. You must decode this text before you can use the AWS CLI to decrypt it.Saves the binary ciphertext to a file.The final part of the command (`> ExampleEncryptedFile`) saves the binary ciphertext to a file to make decryption easier. For an example command that uses the AWS CLI to decrypt data, see the decrypt examples.
**Example 2: Using the AWS CLI to encrypt data on Windows**
This example is the same as the previous one, except that it uses the `certutil` tool instead of `base64`. This procedure requires two commands, as shown in the following example.
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob > C:\Temp\ExampleEncryptedFile.base64
certutil -decode C:\Temp\ExampleEncryptedFile.base64 C:\Temp\ExampleEncryptedFile
```
**Example 3: Encrypting with an asymmetric KMS key**
The following `encrypt` command shows how to encrypt plaintext with an asymmetric KMS key. The `--encryption-algorithm` parameter is required. As in all `encrypt` CLI commands, the `plaintext` parameter must be base64-encoded, or you must use the `fileb://` prefix, which tells the AWS CLI to read binary data from the file.
```
aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--encryption-algorithm RSAES_OAEP_SHA_256 \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
This command produces no output.
+ For API details, see [Encrypt](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/encrypt.html) in *AWS CLI Command Reference*.
### `generate-data-key-pair-without-plaintext`
The following code example shows how to use `generate-data-key-pair-without-plaintext`.
**AWS CLI**
**To generate an ECC NIST P384 asymmetric data key pair**
The following `generate-data-key-pair-without-plaintext` example requests an ECC NIST P384 key pair for use outside of AWS.
The command returns a plaintext public key and a copy of the private key encrypted under the specified KMS key. It does not return a plaintext private key. You can safely store the encrypted private key with the encrypted data, and call AWS KMS to decrypt the private key when you need to use it.
To request an ECC NIST P384 asymmetric data key pair, use the `key-pair-spec` parameter with a value of `ECC_NIST_P384`.
The KMS key you specify must be a symmetric encryption KMS key, that is, a KMS key with a `KeySpec` value of `SYMMETRIC_DEFAULT`.
NOTE: The values in the output of this example are truncated for display.
```
aws kms generate-data-key-pair-without-plaintext \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-pair-spec ECC_NIST_P384
```
Output:
```
{
"PrivateKeyCiphertextBlob": "AQIDAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAFFxmiD134doUDzMGmfCEtcAAAHaTCCB2UGCSqGSIb3DQEHBqCCB1...",
"PublicKey": "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA3A3eGMyPrvSn7+LdlJE1oUoQV5HpEuHAVbdOyND+NmYDH/mL1OSIEuLrcdZ5hrMH4pk83r40l...",
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"KeyPairSpec": "ECC_NIST_P384"
}
```
The `PublicKey` and `PrivateKeyCiphertextBlob` are returned in base64-encoded format.
For more information, see [Data key pairs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-key-pairs) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [GenerateDataKeyPairWithoutPlaintext](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key-pair-without-plaintext.html) in *AWS CLI Command Reference*.
### `generate-data-key-pair`
The following code example shows how to use `generate-data-key-pair`.
**AWS CLI**
**To generate an 2048-bit RSA asymmetric data key pair**
The following `generate-data-key-pair` example requests a 2048-bit RSA asymmetric data key pair for use outside of AWS. The command returns a plaintext public key and a plaintext private key for immediate use and deletion, and a copy of the private key encrypted under the specified KMS key. You can safely store the encrypted private key with the encrypted data.
To request a 2048-bit RSA asymmetric data key pair, use the `key-pair-spec` parameter with a value of `RSA_2048`.
The KMS key you specify must be a symmetric encryption KMS key, that is, a KMS key with a `KeySpec` value of `SYMMETRIC_DEFAULT`.
NOTE: The values in the output of this example are truncated for display.
```
aws kms generate-data-key-pair \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-pair-spec RSA_2048
```
Output:
```
{
"PrivateKeyCiphertextBlob": "AQIDAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAFFxmiD134doUDzMGmfCEtcAAAHaTCCB2UGCSqGSIb3DQEHBqCCB1...",
"PrivateKeyPlaintext": "MIIG/QIBADANBgkqhkiG9w0BAQEFAASCBucwggbjAgEAAoIBgQDcDd4YzI+u9Kfv4t2UkTWhShBXkekS4cBVt07I0P42ZgMf+YvU5IgS4ut...",
"PublicKey": "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA3A3eGMyPrvSn7+LdlJE1oUoQV5HpEuHAVbdOyND+NmYDH/mL1OSIEuLrcdZ5hrMH4pk83r40l...",
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
"KeyPairSpec": "RSA_2048"
}
```
The `PublicKey`, `PrivateKeyPlaintext`, and `PrivateKeyCiphertextBlob` are returned in base64-encoded format.
For more information, see [Data key pairs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-key-pairs) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [GenerateDataKeyPair](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key-pair.html) in *AWS CLI Command Reference*.
### `generate-data-key-without-plaintext`
The following code example shows how to use `generate-data-key-without-plaintext`.
**AWS CLI**
**To generate a 256-bit symmetric data key without a plaintext key**
The following `generate-data-key-without-plaintext` example requests an encrypted copy of a 256-bit symmetric data key for use outside of AWS. You can call AWS KMS to decrypt the data key when you are ready to use it.
To request a 256-bit data key, use the `key-spec` parameter with a value of `AES_256`. To request a 128-bit data key, use the `key-spec` parameter with a value of `AES_128`. For all other data key lengths, use the `number-of-bytes` parameter.
The KMS key you specify must be a symmetric encryption KMS key, that is, a KMS key with a key spec value of SYMMETRIC\$1DEFAULT.
```
aws kms generate-data-key-without-plaintext \
--key-id "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
--key-spec AES_256
```
Output:
```
{
"CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogL",
"KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
The `CiphertextBlob` (encrypted data key) is returned in base64-encoded format.
For more information, see [Data keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [GenerateDataKeyWithoutPlaintext](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key-without-plaintext.html) in *AWS CLI Command Reference*.
### `generate-data-key`
The following code example shows how to use `generate-data-key`.
**AWS CLI**
**Example 1: To generate a 256-bit symmetric data key**
The following `generate-data-key` example requests a 256-bit symmetric data key for use outside of AWS. The command returns a plaintext data key for immediate use and deletion, and a copy of that data key encrypted under the specified KMS key. You can safely store the encrypted data key with the encrypted data.
To request a 256-bit data key, use the `key-spec` parameter with a value of `AES_256`. To request a 128-bit data key, use the `key-spec` parameter with a value of `AES_128`. For all other data key lengths, use the `number-of-bytes` parameter.
The KMS key you specify must be a symmetric encryption KMS key, that is, a KMS key with a key spec value of SYMMETRIC\$1DEFAULT.
```
aws kms generate-data-key \
--key-id alias/ExampleAlias \
--key-spec AES_256
```
Output:
```
{
"Plaintext": "VdzKNHGzUAzJeRBVY+uUmofUGGiDzyB3+i9fVkh3piw=",
"KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
"CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogLqPWZconQhwHAIBEIA7d9AC7GeJJM34njQvg4Wf1d5sw0NIo1MrBqZa+YdhV8MrkBQPeac0ReRVNDt9qleAt+SHgIRF8P0H+7U="
}
```
The `Plaintext` (plaintext data key) and the `CiphertextBlob` (encrypted data key) are returned in base64-encoded format.
For more information, see [Data keys](https://docs.aws.amazon.com/kms/latest/developerguide/data-keys.html) in the *AWS Key Management Service Developer Guide*. **Example 2: To generate a 512-bit symmetric data key**
The following `generate-data-key` example requests a 512-bit symmetric data key for encryption and decryption. The command returns a plaintext data key for immediate use and deletion, and a copy of that data key encrypted under the specified KMS key. You can safely store the encrypted data key with the encrypted data.
To request a key length other than 128 or 256 bits, use the `number-of-bytes` parameter. To request a 512-bit data key, the following example uses the `number-of-bytes` parameter with a value of 64 (bytes).
The KMS key you specify must be a symmetric encryption KMS key, that is, a KMS key with a key spec value of SYMMETRIC\$1DEFAULT.
NOTE: The values in the output of this example are truncated for display.
```
aws kms generate-data-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--number-of-bytes 64
```
Output:
```
{
"CiphertextBlob": "AQIBAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAEnX/QQNmMwDfg2korNMEc8AAACaDCCAmQGCSqGSIb3DQEHBqCCAlUwggJRAgEAMIICSgYJKoZ...",
"Plaintext": "ty8Lr0Bk6OF07M2BWt6qbFdNB+G00ZLtf5MSEb4al3R2UKWGOp06njAwy2n72VRm2m7z/Pm9Wpbvttz6a4lSo9hgPvKhZ5y6RTm4OovEXiVfBveyX3DQxDzRSwbKDPk/...",
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
The `Plaintext` (plaintext data key) and `CiphertextBlob` (encrypted data key) are returned in base64-encoded format.
For more information, see [Data keys](https://docs.aws.amazon.com/kms/latest/developerguide/data-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [GenerateDataKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-data-key.html) in *AWS CLI Command Reference*.
### `generate-mac`
The following code example shows how to use `generate-mac`.
**AWS CLI**
**Example 1: To generate an HMAC for a message**
The following `generate-mac` command generates an HMAC for a message, an HMAC KMS key, and a MAC algorithm. The algorithm must be supported by the specified HMAC KMS key.
In AWS CLI v2, the value of the `message` parameter must be Base64-encoded. Or, you can save the message in a file and use the `fileb://` prefix, which tells the AWS CLI to read binary data from the file.
Before running this command, replace the example key ID with a valid key ID from your AWS account. The key ID must represent a HMAC KMS key with a key usage of `GENERATE_VERIFY_MAC`.
```
msg=(echo 'Hello World' | base64)
aws kms generate-mac \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://Message \
--mac-algorithm HMAC_SHA_384
```
Output:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"Mac": "",
"MacAlgorithm": "HMAC_SHA_384"
}
```
For more information about using HMAC KMS keys in AWS KMS, see [HMAC keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) in the *AWS Key Management Service Developer Guide*.
**Example 2: To save an HMAC in a file (Linux and macOs)**
The following `generate-mac` example generates an HMAC for a short message stored in a local file. The command also gets the `Mac` property from the response, Base64-decodes it and saves it in the ExampleMac file. You can use the MAC file in a `verify-mac` command that verifies the MAC.
The `generate-mac` command requires a Base64-encoded message and a MAC algorithm that your HMAC KMS key supports. To get the MAC algorithms that your KMS key supports, use the `describe-key` command.
Before running this command, replace the example key ID with a valid key ID from your AWS account. The key ID must represent an asymmetric KMS key with a key usage of GENERATE\$1VERIFY\$1MAC.
```
echo 'hello world' | base64 > EncodedMessage
aws kms generate-mac \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://EncodedMessage \
--mac-algorithm HMAC_SHA_384 \
--output text \
--query Mac | base64 --decode > ExampleMac
```
This command produces no output. This example extracts the `Mac` property of the output and saves it in a file.
For more information about using HMAC KMS keys in AWS KMS, see [HMAC keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [GenerateMac](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-mac.html) in *AWS CLI Command Reference*.
### `generate-random`
The following code example shows how to use `generate-random`.
**AWS CLI**
**Example 1: To generate a 256-bit random byte string (Linux or macOs)**
The following `generate-random` example generates a 256-bit (32-byte), base64-encoded random byte string. The example decodes the byte string and saves it in the random file.
When you run this command, you must use the `number-of-bytes` parameter to specify the length of the random value in bytes.
You don't specify a KMS key when you run this command. The random byte string is unrelated to any KMS key.
By default, AWS KMS generates the random number. However, if you specify a [custom key store](https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html), the random byte string is generated in the AWS CloudHSM cluster associated with the custom key store.
This example uses the following parameters and values:
It uses the required `--number-of-bytes` parameter with a value of `32` to request a 32-byte (256-bit) string.It uses the `--output` parameter with a value of `text` to direct the AWS CLI to return the output as text, instead of JSON.It uses the `--query parameter` to extract the value of the `Plaintext` property from the response.It pipes ( \$1 ) the output of the command to the `base64` utility, which decodes the extracted output.It uses the redirection operator ( > ) to save decoded byte string to the `ExampleRandom` file.It uses the redirection operator ( > ) to save the binary ciphertext to a file.
```
aws kms generate-random \
--number-of-bytes 32 \
--output text \
--query Plaintext | base64 --decode > ExampleRandom
```
This command produces no output.
For more information, see [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html) in the *AWS Key Management Service API Reference*.
**Example 2: To generate a 256-bit random number (Windows Command Prompt)**
The following example uses the `generate-random` command to generate a 256-bit (32-byte), base64-encoded random byte string. The example decodes the byte string and saves it in the random file. This example is the same as the previous example, except that it uses the `certutil` utility in Windows to base64-decode the random byte string before saving it in a file.
First, generate a base64-encoded random byte string and saves it in a temporary file, `ExampleRandom.base64`.
```
aws kms generate-random \
--number-of-bytes 32 \
--output text \
--query Plaintext > ExampleRandom.base64
```
Because the output of the `generate-random` command is saved in a file, this example produces no output.
Now use the `certutil -decode` command to decode the base64-encoded byte string in the `ExampleRandom.base64` file. Then, it saves the decoded byte string in the `ExampleRandom` file.
```
certutil -decode ExampleRandom.base64 ExampleRandom
```
Output:
```
Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.
```
For more information, see [GenerateRandom](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateRandom.html) in the *AWS Key Management Service API Reference*.
+ For API details, see [GenerateRandom](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/generate-random.html) in *AWS CLI Command Reference*.
### `get-key-policy`
The following code example shows how to use `get-key-policy`.
**AWS CLI**
**To copy a key policy from one KMS key to another KMS key**
The following `get-key-policy` example gets the key policy from one KMS key and saves it in a text file. Then, it replaces the policy of a different KMS key using the text file as the policy input.
Because the `--policy` parameter of `put-key-policy` requires a string, you must use the `--output text` option to return the output as a text string instead of JSON.
```
aws kms get-key-policy \
--policy-name default \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--query Policy \
--output text > policy.txt
aws kms put-key-policy \
--policy-name default \
--key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--policy file://policy.txt
```
This command produces no output.
For more information, see [PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) in the *AWS KMS API Reference*.
+ For API details, see [GetKeyPolicy](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-key-policy.html) in *AWS CLI Command Reference*.
### `get-key-rotation-status`
The following code example shows how to use `get-key-rotation-status`.
**AWS CLI**
**To retrieve the rotation status for a KMS key.**
The following `get-key-rotation-status` example returns information about the rotation status of the specified KMS key, including whether automatic rotation is enabled, the rotation period, and the next scheduled rotation date. You can use this command on customer managed KMS keys and AWS managed KMS keys. However, all AWS managed KMS keys are automatically rotated every year.
```
aws kms get-key-rotation-status \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Output:
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyRotationEnabled": true,
"NextRotationDate": "2024-02-14T18:14:33.587000+00:00",
"RotationPeriodInDays": 365
}
```
For more information, see [Rotating keys](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [GetKeyRotationStatus](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-key-rotation-status.html) in *AWS CLI Command Reference*.
### `get-parameters-for-import`
The following code example shows how to use `get-parameters-for-import`.
**AWS CLI**
**To get the items required to import key material into a KMS key**
The following `get-parameters-for-import` example gets the public key and import token that you need to import key material into a KMS key. When you use the `import-key-material` command, be sure to use the import token and key material encrypted by the public key that were returned in the same `get-parameters-for-import` command. Also, the wrapping algorithm that you specify in this command must be one that you use to encrypt the key material with the public key.
To specify the KMS key, use the `key-id` parameter. This example uses an key ID, but you can use a key ID or key ARN in this command.
```
aws kms get-parameters-for-import \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--wrapping-algorithm RSAES_OAEP_SHA_256 \
--wrapping-key-spec RSA_2048
```
Output:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"PublicKey": "",
"ImportToken": "",
"ParametersValidTo": 1593893322.32
}
```
For more information, see [Download the public key and import token](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [GetParametersForImport](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-parameters-for-import.html) in *AWS CLI Command Reference*.
### `get-public-key`
The following code example shows how to use `get-public-key`.
**AWS CLI**
**Example 1: To download the public key of an asymmetric KMS key**
The following `get-public-key` example downloads the public key of an asymmetric KMS key.
In addition to returning the public key, the output includes information that you need to use the public key safely outside of AWS KMS, including the key usage and supported encryption algorithms.
```
aws kms get-public-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Output:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"PublicKey": "jANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAl5epvg1/QtJhxSi2g9SDEVg8QV/...",
"CustomerMasterKeySpec": "RSA_4096",
"KeyUsage": "ENCRYPT_DECRYPT",
"EncryptionAlgorithms": [
"RSAES_OAEP_SHA_1",
"RSAES_OAEP_SHA_256"
]
}
```
For more information about using asymmetric KMS keys in AWS KMS, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the *AWS Key Management Service Developer Guide*. **Example 2: To convert a public key to DER format (Linux and macOS)**
The following `get-public-key` example downloads the public key of an asymmetric KMS key and saves it in a DER file.
When you use the `get-public-key` command in the AWS CLI, it returns a DER-encoded X.509 public key that is Base64-encoded. This example gets the value of the `PublicKey` property as text. It Base64-decodes the `PublicKey` and saves it in the `public_key.der` file. The `output` parameter returns the output as text, instead of JSON. The `--query` parameter gets only the `PublicKey` property, not the properties that you need to use the public key safely outside of AWS KMS.
Before running this command, replace the example key ID with a valid key ID from your AWS account.
```
aws kms get-public-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--output text \
--query PublicKey | base64 --decode > public_key.der
```
This command produces no output.
For more information about using asymmetric KMS keys in AWS KMS, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [GetPublicKey](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/get-public-key.html) in *AWS CLI Command Reference*.
### `import-key-material`
The following code example shows how to use `import-key-material`.
**AWS CLI**
**To import key material into a KMS key**
The following `import-key-material` example uploads key material into a KMS key that was created with no key material. The key state of the KMS key must be `PendingImport`.
This command uses key material that you encrypted with the public key that the `get-parameters-for-import` command returned. It also uses the import token from the same `get-parameters-for-import` command.
The `expiration-model` parameter indicates that the key material automatically expires on the date and time specified by the `valid-to` parameter. When the key material expires, AWS KMS deletes the key material, the key state of the KMS key changes to `Pending import` and the KMS key becomes unusable. To restore the KMS key, you must reimport the same key material. To use different key material, you must create a new KMS key.
Before running this command, replace the example key ID with a valid key ID or key ARN from your AWS account.
```
aws kms import-key-material \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--encrypted-key-material fileb://EncryptedKeyMaterial.bin \
--import-token fileb://ImportToken.bin \
--expiration-model KEY_MATERIAL_EXPIRES \
--valid-to 2021-09-21T19:00:00Z
```
Output:
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}
```
For more information about importing key material, see [Importing Key Material](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [ImportKeyMaterial](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/import-key-material.html) in *AWS CLI Command Reference*.
### `list-aliases`
The following code example shows how to use `list-aliases`.
**AWS CLI**
**Example 1: To list all aliases in an AWS account and Region**
The following example uses the `list-aliases` command to list all aliases in the default Region of the AWS account. The output includes aliases associated with AWS managed KMS keys and customer managed KMS keys.
```
aws kms list-aliases
```
Output:
```
{
"Aliases": [
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/testKey",
"AliasName": "alias/testKey",
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
},
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/FinanceDept",
"AliasName": "alias/FinanceDept",
"TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321"
},
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/dynamodb",
"AliasName": "alias/aws/dynamodb",
"TargetKeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
},
{
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/ebs",
"AliasName": "alias/aws/ebs",
"TargetKeyId": "0987ab65-43cd-21ef-09ab-87654321cdef"
},
...
]
}
```
**Example 2: To list all aliases for a particular KMS key**
The following example uses the `list-aliases` command and its `key-id` parameter to list all aliases that are associated with a particular KMS key.
Each alias is associated with only one KMS key, but a KMS key can have multiple aliases. This command is very useful because the AWS KMS console lists only one alias for each KMS key. To find all aliases for a KMS key, you must use the `list-aliases` command.
This example uses the key ID of the KMS key for the `--key-id` parameter, but you can use a key ID, key ARN, alias name, or alias ARN in this command.
```
aws kms list-aliases --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Output:
```
{
"Aliases": [
{
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/oregon-test-key",
"AliasName": "alias/oregon-test-key"
},
{
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/project121-test",
"AliasName": "alias/project121-test"
}
]
}
```
For more information, see [Working with Aliases](https://docs.aws.amazon.com/kms/latest/developerguide/programming-aliases.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [ListAliases](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-aliases.html) in *AWS CLI Command Reference*.
### `list-grants`
The following code example shows how to use `list-grants`.
**AWS CLI**
**To view the grants on an AWS KMS key**
The following `list-grants` example displays all of the grants on the specified AWS managed KMS key for Amazon DynamoDB in your account. This grant allows DynamoDB to use the KMS key on your behalf to encrypt a DynamoDB table before writing it to disk. You can use a command like this one to view the grants on the AWS managed KMS keys and customer managed KMS keys in the AWS account and Region.
This command uses the `key-id` parameter with a key ID to identify the KMS key. You can use a key ID or key ARN to identify the KMS key. To get the key ID or key ARN of an AWS managed KMS key, use the `list-keys` or `list-aliases` command.
```
aws kms list-grants \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
The output shows that the grant gives Amazon DynamoDB permission to use the KMS key for cryptographic operations, and gives it permission to view details about the KMS key (`DescribeKey`) and to retire grants (`RetireGrant`). The `EncryptionContextSubset` constraint limits these permission to requests that include the specified encryption context pairs. As a result, the permissions in the grant are effective only on specified account and DynamoDB table.
```
{
"Grants": [
{
"Constraints": {
"EncryptionContextSubset": {
"aws:dynamodb:subscriberId": "123456789012",
"aws:dynamodb:tableName": "Services"
}
},
"IssuingAccount": "arn:aws:iam::123456789012:root",
"Name": "8276b9a6-6cf0-46f1-b2f0-7993a7f8c89a",
"Operations": [
"Decrypt",
"Encrypt",
"GenerateDataKey",
"ReEncryptFrom",
"ReEncryptTo",
"RetireGrant",
"DescribeKey"
],
"GrantId": "1667b97d27cf748cf05b487217dd4179526c949d14fb3903858e25193253fe59",
"KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"RetiringPrincipal": "dynamodb.us-west-2.amazonaws.com",
"GranteePrincipal": "dynamodb.us-west-2.amazonaws.com",
"CreationDate": "2021-05-13T18:32:45.144000+00:00"
}
]
}
```
For more information, see [Grants in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [ListGrants](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-grants.html) in *AWS CLI Command Reference*.
### `list-key-policies`
The following code example shows how to use `list-key-policies`.
**AWS CLI**
**To get the names of key policies for a KMS key**
The following `list-key-policies` example gets the names of the key policies for a customer managed key in the example account and Region. You can use this command to find the names of key policies for AWS managed keys and customer managed keys.
Because the only valid key policy name is `default`, this command is not useful.
To specify the KMS key, use the `key-id` parameter. This example uses a key ID value, but you can use a key ID or key ARN in this command.
```
aws kms list-key-policies \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Output:
```
{
"PolicyNames": [
"default"
]
}
```
For more information about AWS KMS key policies, see [Using Key Policies in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [ListKeyPolicies](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-key-policies.html) in *AWS CLI Command Reference*.
### `list-key-rotations`
The following code example shows how to use `list-key-rotations`.
**AWS CLI**
**To retrieve information about all completed key material rotations**
The following `list-key-rotations` example lists information about all completed key material rotations for the specified KMS key.
```
aws kms list-key-rotations \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Output:
```
{
"Rotations": [
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"RotationDate": "2024-03-02T10:11:36.564000+00:00",
"RotationType": "AUTOMATIC"
},
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"RotationDate": "2024-04-05T15:14:47.757000+00:00",
"RotationType": "ON_DEMAND"
}
],
"Truncated": false
}
```
For more information, see [Rotating keys](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [ListKeyRotations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-key-rotations.html) in *AWS CLI Command Reference*.
### `list-keys`
The following code example shows how to use `list-keys`.
**AWS CLI**
**To get the KMS keys in an account and Region**
The following `list-keys` example gets the KMS keys in an account and Region. This command returns both AWS managed keys and customer managed keys.
```
aws kms list-keys
```
Output:
```
{
"Keys": [
{
"KeyArn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
},
{
"KeyArn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
"KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321"
},
{
"KeyArn": "arn:aws:kms:us-east-2:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d",
"KeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
}
]
}
```
For more information, see [Viewing Keys](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [ListKeys](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-keys.html) in *AWS CLI Command Reference*.
### `list-resource-tags`
The following code example shows how to use `list-resource-tags`.
**AWS CLI**
**To get the tags on a KMS key**
The following `list-resource-tags` example gets the tags for a KMS key. To add or replace resource tags on KMS keys, use the `tag-resource` command. The output shows that this KMS key has two resource tags, each of which has a key and value.
To specify the KMS key, use the `key-id` parameter. This example uses a key ID value, but you can use a key ID or key ARN in this command.
```
aws kms list-resource-tags \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Output:
```
{
"Tags": [
{
"TagKey": "Dept",
"TagValue": "IT"
},
{
"TagKey": "Purpose",
"TagValue": "Test"
}
],
"Truncated": false
}
```
For more information about using tags in AWS KMS, see [Tagging keys](https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [ListResourceTags](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-resource-tags.html) in *AWS CLI Command Reference*.
### `list-retirable-grants`
The following code example shows how to use `list-retirable-grants`.
**AWS CLI**
**To view the grants that a principal can retire**
The following `list-retirable-grants` example displays all of the grants that the `ExampleAdmin` user can retire on the KMS keys in an AWS account and Region. You can use a command like this one to view the grants that any account principal can retire on KMS keys in the AWS account and Region.
The value of the required `retiring-principal` parameter must be the Amazon Resource Name (ARN) of an account, user, or role.
You cannot specify a service for the value of `retiring-principal` in this command, even though a service can be the retiring principal. To find the grants in which a particular service is the retiring principal, use the `list-grants` command.
The output shows that `ExampleAdmin` user has permission to retire grants on two different KMS keys in the account and region. In addition to the retiring principal, the account has permission to retire any grant in the account.
```
aws kms list-retirable-grants \
--retiring-principal arn:aws:iam::111122223333:user/ExampleAdmin
```
Output:
```
{
"Grants": [
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"GrantId": "156b69c63cb154aa21f59929ff19760717be8d9d82b99df53e18b94a15a5e88e",
"Name": "",
"CreationDate": 2021-01-14T20:17:36.419000+00:00,
"GranteePrincipal": "arn:aws:iam::111122223333:user/ExampleUser",
"RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
"IssuingAccount": "arn:aws:iam::111122223333:root",
"Operations": [
"Encrypt"
],
"Constraints": {
"EncryptionContextSubset": {
"Department": "IT"
}
}
},
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
"GrantId": "8c94d1f12f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
"Name": "",
"CreationDate": "2021-02-02T19:49:49.638000+00:00",
"GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",
"RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
"IssuingAccount": "arn:aws:iam::111122223333:root",
"Operations": [
"Decrypt"
],
"Constraints": {
"EncryptionContextSubset": {
"Department": "IT"
}
}
}
],
"Truncated": false
}
```
For more information, see [Grants in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [ListRetirableGrants](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/list-retirable-grants.html) in *AWS CLI Command Reference*.
### `put-key-policy`
The following code example shows how to use `put-key-policy`.
**AWS CLI**
**To change the key policy for a KMS key**
The following `put-key-policy` example changes the key policy for a customer managed key.
To begin, create a key policy and save it in a local JSON file. In this example, the file is `key_policy.json`. You can also specify the key policy as a string value of the `policy` parameter.
The first statement in this key policy gives the AWS account permission to use IAM policies to control access to the KMS key. The second statement gives the `test-user` user permission to run the `describe-key` and `list-keys` commands on the KMS key.
Contents of `key_policy.json`:
```
{
"Version":"2012-10-17",
"Id" : "key-default-1",
"Statement" : [
{
"Sid" : "Enable IAM User Permissions",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:root"
},
"Action" : "kms:*",
"Resource" : "*"
},
{
"Sid" : "Allow Use of Key",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:user/test-user"
},
"Action" : [
"kms:DescribeKey",
"kms:ListKeys"
],
"Resource" : "*"
}
]
}
```
To identify the KMS key, this example uses the key ID, but you can also use a key ARN. To specify the key policy, the command uses the `policy` parameter. To indicate that the policy is in a file, it uses the required `file://` prefix. This prefix is required to identify files on all supported operating systems. Finally, the command uses the `policy-name` parameter with a value of `default`. If no policy name is specified, the default value is `default`. The only valid value is `default`.
```
aws kms put-key-policy \
--policy-name default \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--policy file://key_policy.json
```
This command does not produce any output. To verify that the command was effective, use the `get-key-policy` command. The following example command gets the key policy for the same KMS key. The `output` parameter with a value of `text` returns a text format that is easy to read.
```
aws kms get-key-policy \
--policy-name default \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--output text
```
Output:
```
{
"Version":"2012-10-17",
"Id" : "key-default-1",
"Statement" : [
{
"Sid" : "Enable IAM User Permissions",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:root"
},
"Action" : "kms:*",
"Resource" : "*"
},
{
"Sid" : "Allow Use of Key",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:user/test-user"
},
"Action" : [ "kms:Describe", "kms:List" ],
"Resource" : "*"
}
]
}
```
For more information, see [Changing a Key Policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [PutKeyPolicy](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/put-key-policy.html) in *AWS CLI Command Reference*.
### `re-encrypt`
The following code example shows how to use `re-encrypt`.
**AWS CLI**
**Example 1: To re-encrypt an encrypted message under a different symmetric KMS key (Linux and macOS).**
The following `re-encrypt` command example demonstrates the recommended way to re-encrypt data with the AWS CLI.
Provide the ciphertext in a file.In the value of the `--ciphertext-blob` parameter, use the `fileb://` prefix, which tells the CLI to read the data from a binary file. If the file is not in the current directory, type the full path to file. For more information about reading AWS CLI parameter values from a file, see [Loading AWS CLI parameters from a file](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html) in the *AWS Command Line Interface User Guide* and [Best Practices for Local File Parameters](https://aws.amazon.com/blogs/developer/best-practices-for-local-file-parameters/) in the *AWS Command Line Tool Blog*.Specify the source KMS key, which decrypts the ciphertext.The `--source-key-id` parameter is not required when decrypting with symmetric encryption KMS keys. AWS KMS can get the KMS key that was used to encrypt the data from the metadata in the ciphertext blob. But it's always a best practice to specify the KMS key you are using. This practice ensures that you use the KMS key that you intend, and prevents you from inadvertently decrypting a ciphertext using a KMS key you do not trust.Specify the destination KMS key, which re-encrypts the data.The `--destination-key-id` parameter is always required. This example uses a key ARN, but you can use any valid key identifier.Request the plaintext output as a text value.The `--query` parameter tells the CLI to get only the value of the `Plaintext` field from the output. The `--output` parameter returns the output as text.Base64-decode the plaintext and save it in a file.The following example pipes (\$1) the value of the `Plaintext` parameter to the Base64 utility, which decodes it. Then, it redirects (>) the decoded output to the `ExamplePlaintext` file.
Before running this command, replace the example key IDs with valid key identifiers from your AWS account.
```
aws kms re-encrypt \
--ciphertext-blob fileb://ExampleEncryptedFile \
--source-key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--destination-key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--query CiphertextBlob \
--output text | base64 --decode > ExampleReEncryptedFile
```
This command produces no output. The output from the `re-encrypt` command is base64-decoded and saved in a file.
For more information, see [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) in the *AWS Key Management Service API Reference*.
**Example 2: To re-encrypt an encrypted message under a different symmetric KMS key (Windows command prompt).**
The following `re-encrypt` command example is the same as the previous one except that it uses the `certutil` utility to Base64-decode the plaintext data. This procedure requires two commands, as shown in the following examples.
Before running this command, replace the example key ID with a valid key ID from your AWS account.
```
aws kms re-encrypt ^
--ciphertext-blob fileb://ExampleEncryptedFile ^
--source-key-id 1234abcd-12ab-34cd-56ef-1234567890ab ^
--destination-key-id 0987dcba-09fe-87dc-65ba-ab0987654321 ^
--query CiphertextBlob ^
--output text > ExampleReEncryptedFile.base64
```
Then use the `certutil` utility
```
certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile
```
Output:
```
Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.
```
For more information, see [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) in the *AWS Key Management Service API Reference*.
+ For API details, see [ReEncrypt](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/re-encrypt.html) in *AWS CLI Command Reference*.
### `retire-grant`
The following code example shows how to use `retire-grant`.
**AWS CLI**
**To retire a grant on a customer master key**
The following `retire-grant` example deletes a grant from a KMS key.
The following example command specifies the `grant-id` and the `key-id` parameters. The value of the `key-id` parameter must be the key ARN of the KMS key.
```
aws kms retire-grant \
--grant-id 1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3 \
--key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
This command produces no output. To confirm that the grant was retired, use the `list-grants` command.
For more information, see [Retiring and revoking grants](https://docs.aws.amazon.com/kms/latest/developerguide/grant-manage.html#grant-delete) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [RetireGrant](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/retire-grant.html) in *AWS CLI Command Reference*.
### `revoke-grant`
The following code example shows how to use `revoke-grant`.
**AWS CLI**
**To revoke a grant on a customer master key**
The following `revoke-grant` example deletes a grant from a KMS key. The following example command specifies the `grant-id` and the `key-id` parameters. The value of the `key-id` parameter can be the key ID or key ARN of the KMS key.
```
aws kms revoke-grant \
--grant-id 1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3 \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
This command produces no output. To confirm that the grant was revoked, use the `list-grants` command.
For more information, see [Retiring and revoking grants](https://docs.aws.amazon.com/kms/latest/developerguide/grant-manage.html#grant-delete) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [RevokeGrant](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/revoke-grant.html) in *AWS CLI Command Reference*.
### `rotate-key-on-demand`
The following code example shows how to use `rotate-key-on-demand`.
**AWS CLI**
**To perform on-demand rotation of a KMS key**
The following `rotate-key-on-demand` example immediately initiates rotation of the key material for the specified KMS key.
```
aws kms rotate-key-on-demand \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
Output:
```
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
For more information, see [How to perform on-demand key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotating-keys-on-demand) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [RotateKeyOnDemand](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/rotate-key-on-demand.html) in *AWS CLI Command Reference*.
### `schedule-key-deletion`
The following code example shows how to use `schedule-key-deletion`.
**AWS CLI**
**To schedule the deletion of a customer managed KMS key.**
The following `schedule-key-deletion` example schedules the specified customer managed KMS key to be deleted in 15 days.
The `--key-id` parameter identifies the KMS key. This example uses a key ARN value, but you can use either the key ID or the ARN of the KMS key.The `--pending-window-in-days` parameter specifies the length of the 7-30 day waiting period. By default, the waiting period is 30 days. This example specifies a value of 15, which tells AWS to permanently delete the KMS key 15 days after the command completes.
```
aws kms schedule-key-deletion \
--key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--pending-window-in-days 15
```
The response includes the key ARN, key state, waiting period (`PendingWindowInDays`), and the deletion date in Unix time. To view the deletion date in local time, use the AWS KMS console. KMS keys in the `PendingDeletion` key state cannot be used in cryptographic operations.
```
{
"KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"DeletionDate": "2022-06-18T23:43:51.272000+00:00",
"KeyState": "PendingDeletion",
"PendingWindowInDays": 15
}
```
For more information, see [Deleting keys](https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [ScheduleKeyDeletion](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/schedule-key-deletion.html) in *AWS CLI Command Reference*.
### `sign`
The following code example shows how to use `sign`.
**AWS CLI**
**Example 1: To generate a digital signature for a message**
The following `sign` example generates a cryptographic signature for a short message. The output of the command includes a base-64 encoded `Signature` field that you can verify by using the `verify` command.
You must specify a message to sign and a signing algorithm that your asymmetric KMS key supports. To get the signing algorithms for your KMS key, use the `describe-key` command.
In AWS CLI v2, the value of the `message` parameter must be Base64-encoded. Or, you can save the message in a file and use the `fileb://` prefix, which tells the AWS CLI to read binary data from the file.
Before running this command, replace the example key ID with a valid key ID from your AWS account. The key ID must represent an asymmetric KMS key with a key usage of SIGN\$1VERIFY.
```
msg=(echo 'Hello World' | base64)
aws kms sign \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://UnsignedMessage \
--message-type RAW \
--signing-algorithm RSASSA_PKCS1_V1_5_SHA_256
```
Output:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"Signature": "ABCDEFhpyVYyTxbafE74ccSvEJLJr3zuoV1Hfymz4qv+/fxmxNLA7SE1SiF8lHw80fKZZ3bJ...",
"SigningAlgorithm": "RSASSA_PKCS1_V1_5_SHA_256"
}
```
For more information about using asymmetric KMS keys in AWS KMS, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the *AWS Key Management Service Developer Guide*.
**Example 2: To save a digital signature in a file (Linux and macOs)**
The following `sign` example generates a cryptographic signature for a short message stored in a local file. The command also gets the `Signature` property from the response, Base64-decodes it and saves it in the ExampleSignature file. You can use the signature file in a `verify` command that verifies the signature.
The `sign` command requires a Base64-encoded message and a signing algorithm that your asymmetric KMS key supports. To get the signing algorithms that your KMS key supports, use the `describe-key` command.
Before running this command, replace the example key ID with a valid key ID from your AWS account. The key ID must represent an asymmetric KMS key with a key usage of SIGN\$1VERIFY.
```
echo 'hello world' | base64 > EncodedMessage
aws kms sign \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://EncodedMessage \
--message-type RAW \
--signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
--output text \
--query Signature | base64 --decode > ExampleSignature
```
This command produces no output. This example extracts the `Signature` property of the output and saves it in a file.
For more information about using asymmetric KMS keys in AWS KMS, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [Sign](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/sign.html) in *AWS CLI Command Reference*.
### `tag-resource`
The following code example shows how to use `tag-resource`.
**AWS CLI**
**To add a tag to a KMS key**
The following `tag-resource` example adds `"Purpose":"Test"` and `"Dept":"IT"` tags to a customer managed KMS key. You can use tags like these to label KMS keys and create categories of KMS keys for permissions and auditing.
To specify the KMS key, use the `key-id` parameter. This example uses a key ID value, but you can use a key ID or key ARN in this command.
```
aws kms tag-resource \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--tags TagKey='Purpose',TagValue='Test' TagKey='Dept',TagValue='IT'
```
This command produces no output. To view the tags on an AWS KMS KMS key, use the `list-resource-tags` command.
For more information about using tags in AWS KMS, see [Tagging keys](https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [TagResource](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/tag-resource.html) in *AWS CLI Command Reference*.
### `untag-resource`
The following code example shows how to use `untag-resource`.
**AWS CLI**
**To delete a tag from a KMS key**
The following `untag-resource` example deletes the tag with the `"Purpose"` key from a customer managed KMS key.
To specify the KMS key, use the `key-id` parameter. This example uses a key ID value, but you can use a key ID or key ARN in this command. Before running this command, replace the example key ID with a valid key ID from your AWS account.
```
aws kms untag-resource \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--tag-key 'Purpose'
```
This command produces no output. To view the tags on an AWS KMS KMS key, use the `list-resource-tags` command.
For more information about using tags in AWS KMS, see [Tagging keys](https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [UntagResource](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/untag-resource.html) in *AWS CLI Command Reference*.
### `update-alias`
The following code example shows how to use `update-alias`.
**AWS CLI**
**To associate an alias with a different KMS key**
The following `update-alias` example associates the alias `alias/test-key` with a different KMS key.
The `--alias-name` parameter specifies the alias. The alias name value must begin with `alias/`.The `--target-key-id` parameter specifies the KMS key to associate with the alias. You don't need to specify the current KMS key for the alias.
```
aws kms update-alias \
--alias-name alias/test-key \
--target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
This command produces no output. To find the alias, use the `list-aliases` command.
For more information, see [Updating aliases](https://docs.aws.amazon.com/kms/latest/developerguide/alias-manage.html#alias-update) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [UpdateAlias](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/update-alias.html) in *AWS CLI Command Reference*.
### `update-custom-key-store`
The following code example shows how to use `update-custom-key-store`.
**AWS CLI**
**Example 1: To edit the friendly name of a custom key store**
The following `update-custom-key-store` example changes the name of the custom key store. This example works for an AWS CloudHSM key store or an external key store.
Use the `custom-key-store-id` to identify the key store. Use the `new-custom-key-store-name` parameter to specify the new friendly name.
To update the friendly name of an AWS CloudHSM key store, you must first disconnect the key store, such as by using the `disconnect-custom-key-store` command. You can update the friendly name of an external key store while it is connected or disconnected. To find the connection state of your custom key store, use the `describe-custom-key-store` command.
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--new-custom-key-store-name ExampleKeyStore
```
This command does not return any data. To verify that the command worked, use a `describe-custom-key-stores` command.
For more information about updating an AWS CloudHSM key store, see [Editing AWS CloudHSM key store settings](https://docs.aws.amazon.com/kms/latest/developerguide/update-keystore.html) in the *AWS Key Management Service Developer Guide*.
For more information about updating an external key store, see [Editing external key store properties](https://docs.aws.amazon.com/kms/latest/developerguide/update-xks-keystore.html) in the *AWS Key Management Service Developer Guide*.
**Example 2: To edit the kmsuser password of an AWS CloudHSM key store**
The following `update-custom-key-store` example updates the value of the `kmsuser` password to the current password for the `kmsuser` in the CloudHSM cluster associated with the specified key store. This command doesn't change the `kmsuser` password it the cluster. It just tells AWS KMS the current password. If KMS doesn't have the current `kmsuser` password, it cannot connect to the AWS CloudHSM key store.
**NOTE:** Before updating an AWS CloudHSM key store, you must disconnect it. Use the `disconnect-custom-key-store` command. After the command completes, you can reconnect the AWS CloudHSM key store. Use the `connect-custom-key-store` command.
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--key-store-password ExamplePassword
```
This command does not return any output. To verify that the change was effective, use a `describe-custom-key-stores` command.
For more information about updating an AWS CloudHSM key store, see [Editing AWS CloudHSM key store settings](https://docs.aws.amazon.com/kms/latest/developerguide/update-keystore.html) in the *AWS Key Management Service Developer Guide*.
**Example 3: To edit the AWS CloudHSM cluster of an AWS CloudHSM key store**
The following example changes the AWS CloudHSM cluster that is associated with an AWS CloudHSM key store to a related cluster, such as a different backup of the same cluster.
**NOTE:** Before updating an AWS CloudHSM key store, you must disconnect it. Use the `disconnect-custom-key-store` command. After the command completes, you can reconnect the AWS CloudHSM key store. Use the `connect-custom-key-store` command.
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--cloud-hsm-cluster-id cluster-1a23b4cdefg
```
This command does not return any output. To verify that the change was effective, use a `describe-custom-key-stores` command.
For more information about updating an AWS CloudHSM key store, see [Editing AWS CloudHSM key store settings](https://docs.aws.amazon.com/kms/latest/developerguide/update-keystore.html) in the *AWS Key Management Service Developer Guide*.
**Example 4: To edit the proxy authentication credential of an external key store**
The following example updates the proxy authentication credential for your external key store. You must specify both the `raw-secret-access-key` and the `access-key-id`, even if you are changing only one of the values. You can use this feature to fix an invalid credential or to change the credential when the external key store proxy rotates it.
Establish the proxy authentication credential for AWS KMS on your external key store. Then use this command to provide the credential to AWS KMS. AWS KMS uses this credential to sign its requests to your external key store proxy.
You can update the proxy authentication credential while the external key store is connected or disconnected. To find the connection state of your custom key store, use the `describe-custom-key-store` command.
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="
```
This command does not return any output. To verify that the change was effective, use a `describe-custom-key-stores` command.
For more information about updating an external key store, see [Editing external key store properties](https://docs.aws.amazon.com/kms/latest/developerguide/update-xks-keystore.html) in the *AWS Key Management Service Developer Guide*.
**Example 5: To edit the proxy connectivity of an external key store**
The following example changes the external key store proxy connectivity option from public endpoint connectivity to VPC endpoint service connectivity. In addition to changing the `xks-proxy-connectivity` value, you must change the `xks-proxy-uri-endpoint` value to reflect the private DNS name associated with the VPC endpoint service. You must also add an `xks-proxy-vpc-endpoint-service-name` value.
**NOTE:** Before updating the proxy connectivity of an external store, you must disconnect it. Use the `disconnect-custom-key-store` command. After the command completes, you can reconnect the external key store by using the `connect-custom-key-store` command.
```
aws kms update-custom-key-store \
--custom-key-store-id cks-1234567890abcdef0 \
--xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
--xks-proxy-uri-endpoint "https://myproxy-private.xks.example.com" \
--xks-proxy-vpc-endpoint-service-name "com.amazonaws.vpce.us-east-1.vpce-svc-example"
```
This command does not return any output. To verify that the change was effective, use a `describe-custom-key-stores` command.
For more information about updating an external key store, see [Editing external key store properties](https://docs.aws.amazon.com/kms/latest/developerguide/update-xks-keystore.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [UpdateCustomKeyStore](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/update-custom-key-store.html) in *AWS CLI Command Reference*.
### `update-key-description`
The following code example shows how to use `update-key-description`.
**AWS CLI**
**Example 1: To add or change a description to a customer managed KMS key**
The following `update-key-description` example adds a description to a customer managed KMS key. You can use the same command to change an existing description.
The `--key-id` parameter identifies the KMS key in the command. This example uses a key ARN value, but you can use either the key ID or the key ARN of the KMS key.The `--description` parameter specifies the new description. The value of this parameter replaces the current description of the KMS key, if any.
```
aws kms update-key-description \
--key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--description "IT Department test key"
```
This command produces no output. To view the description of a KMS key, use the `describe-key` command.
For more information, see [UpdateKeyDescription](https://docs.aws.amazon.com/cli/latest/reference/kms/update-key-description.html) in the *AWS Key Management Service API Reference*.
**Example 2: To delete the description of a customer managed KMS key**
The following `update-key-description` example deletes the description to a customer managed KMS key.
The `--key-id` parameter identifies the KMS key in the command. This example uses a key ID value, but you can use either the key ID or the key ARN of the KMS key.The `--description` parameter with an empty string value ('') deletes the existing description.
```
aws kms update-key-description \
--key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
--description ''
```
This command produces no output. To view the description of a KMS key, use the the describe-key command.
For more information, see [UpdateKeyDescription](https://docs.aws.amazon.com/cli/latest/reference/kms/update-key-description.html) in the *AWS Key Management Service API Reference*.
+ For API details, see [UpdateKeyDescription](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/update-key-description.html) in *AWS CLI Command Reference*.
### `verify-mac`
The following code example shows how to use `verify-mac`.
**AWS CLI**
**Example 1: To verify an HMAC**
The following `verify-mac` command verifies an HMAC for a particular message, HMAC KMS keys, and MAC algorithm. A value of 'true' in the MacValid value in the response indicates that the HMAC is valid.
In AWS CLI v2, the value of the `message` parameter must be Base64-encoded. Or, you can save the message in a file and use the `fileb://` prefix, which tells the AWS CLI to read binary data from the file.
The MAC that you specify cannot be base64-encoded. For help decoding the MAC that the `generate-mac` command returns, see the `generate-mac` command examples.
Before running this command, replace the example key ID with a valid key ID from your AWS account. The key ID must represent a HMAC KMS key with a key usage of `GENERATE_VERIFY_MAC`.
```
msg=(echo 'Hello World' | base64)
aws kms verify-mac \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://Message \
--mac-algorithm HMAC_SHA_384 \
--mac fileb://ExampleMac
```
Output:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"MacValid": true,
"MacAlgorithm": "HMAC_SHA_384"
}
```
For more information about using HMAC KMS keys in AWS KMS, see [HMAC keys in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [VerifyMac](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/verify-mac.html) in *AWS CLI Command Reference*.
### `verify`
The following code example shows how to use `verify`.
**AWS CLI**
**To verify a digital signature**
The following `verify` command verifies a cryptographic signature for a short, Base64-encoded message. The key ID, message, message type, and signing algorithm must be same ones that were used to sign the message.
In AWS CLI v2, the value of the `message` parameter must be Base64-encoded. Or, you can save the message in a file and use the `fileb://` prefix, which tells the AWS CLI to read binary data from the file.
The signature that you specify cannot be base64-encoded. For help decoding the signature that the `sign` command returns, see the `sign` command examples.
The output of the command includes a Boolean `SignatureValid` field that indicates that the signature was verified. If the signature validation fails, the `verify` command fails, too.
Before running this command, replace the example key ID with a valid key ID from your AWS account.
```
aws kms verify \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--message fileb://EncodedMessage \
--message-type RAW \
--signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
--signature fileb://ExampleSignature
```
Output:
```
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"SignatureValid": true,
"SigningAlgorithm": "RSASSA_PKCS1_V1_5_SHA_256"
}
```
For more information about using asymmetric KMS keys in AWS KMS, see [Using asymmetric keys](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the *AWS Key Management Service Developer Guide*.
+ For API details, see [Verify](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/kms/verify.html) in *AWS CLI Command Reference*.