AWS code-library documentation change
Summary
Added explicit output examples for delete-imported-key-material command
Security assessment
Improves command output documentation without security implications
Diff
diff --git a/code-library/latest/ug/cli_2_kms_code_examples.md b/code-library/latest/ug/cli_2_kms_code_examples.md index 0c8905575..7c5ae3859 100644 --- a//code-library/latest/ug/cli_2_kms_code_examples.md +++ b//code-library/latest/ug/cli_2_kms_code_examples.md @@ -268,0 +269 @@ Output: + "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", @@ -291 +292 @@ For more information, see [Creating keys](https://docs.aws.amazon.com/kms/latest -The following `create-key` example creates a KMS key that contains an asymmetric RSA key pair 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.: @@ -328 +329 @@ For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.c -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. +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.: @@ -362 +363,36 @@ For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.c -**Example 4: To create an HMAC KMS key** +**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** @@ -398 +434 @@ For more information, see [HMAC keys in AWS KMS](https://docs.aws.amazon.com/kms -**Example 4: To create a multi-Region primary KMS key** +**Example 6: To create a multi-Region primary KMS key** @@ -414,0 +451 @@ Output: + "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", @@ -441 +478 @@ For more information, see [Asymmetric keys in AWS KMS](https://docs.aws.amazon.c -**Example 5: To create a KMS key for imported key material** +**Example 7: To create a KMS key for imported key material** @@ -514 +551 @@ For more information, see [AWS CloudHSM key stores](https://docs.aws.amazon.com/ -**Example 7: To create a KMS key in an external key store** +**Example 8: To create a KMS key in an external key store** @@ -707 +744,7 @@ The following `delete-imported-key-material` example deletes key material that h -This command produces no output. To verify that the key material is deleted, use the `describe-key` command to look for a key state of `PendingImport` or `PendingDeletion`. +Output: + + + { + "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", + "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6" + } @@ -709 +752 @@ This command produces no output. To verify that the key material is deleted, use -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 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_. @@ -888,0 +932 @@ Output: + "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", @@ -960,0 +1005 @@ Output: + "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", @@ -1063 +1108 @@ The following code example shows how to use `disable-key`. -The following example uses the `disable-key` command to disable a customer managed KMS key. To re-enable the KMS key, use the `enable-key` command. +The following `disable-key` command disables a customer managed KMS key. To re-enable the KMS key, use the `enable-key` command. @@ -1246,0 +1292 @@ Output: + "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", @@ -1287,0 +1334 @@ Output: + "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6" @@ -1324 +1371,2 @@ Output: - "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" + "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", + "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6" @@ -1360,0 +1409 @@ Output: + "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", @@ -1366,3 +1415 @@ The `Plaintext` (plaintext data key) and the `CiphertextBlob` (encrypted data ke -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_. - -**Example 2: To generate a 512-bit symmetric data key** +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** @@ -1390 +1437,2 @@ Output: - "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" + "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", + "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6" @@ -1395 +1443 @@ The `Plaintext` (plaintext data key) and `CiphertextBlob` (encrypted data key) a -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 more information, see [Data keys](https://docs.aws.amazon.com/kms/latest/developerguide/data-keys.html) in the _AWS Key Management Service Developer Guide_. @@ -1401,0 +1450,59 @@ For more information, see Data keys <https://docs.aws.amazon.com/kms/latest/deve +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": "<HMAC_TAG>", + "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_VERIFY_MAC. + + + 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_. + + + + @@ -1415 +1522 @@ You don't specify a KMS key when you run this command. The random byte string is -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. +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. @@ -1594,3 +1701 @@ Output: -For more information about using asymmetric KMS keys in AWS KMS, see [Using Symmetric and Asymmetric Keys](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the _AWS Key Management Service API Reference_. - -**Example 2: To convert a public key to DER format (Linux and macOS)** +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)** @@ -1613 +1718 @@ This command produces no output. -For more information about using asymmetric KMS keys in AWS KMS, see [Using Symmetric and Asymmetric Keys](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html) in the _AWS Key Management Service API Reference_. +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_. @@ -1644 +1749,7 @@ Before running this command, replace the example key ID with a valid key ID or k -This command produces no output. +Output: + + + { + "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", + "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6" + } @@ -2117 +2228 @@ The following `re-encrypt` command example demonstrates the recommended way to r -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 (|) the value of the `Plaintext` parameter to the Base64 utility, which decodes it. Then, it redirects (>) the decoded output to the `ExamplePlaintext` file. +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 (|) the value of the `Plaintext` parameter to the Base64 utility, which decodes it. Then, it redirects (>) the decoded output to the `ExamplePlaintext` file. @@ -2132 +2243 @@ This command produces no output. The output from the `re-encrypt` command is bas -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 more information, see [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) in the _AWS Key Management Service API Reference_. @@ -2161 +2272 @@ Output: -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 more information, see [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) in the _AWS Key Management Service API Reference_. @@ -2290 +2401 @@ You must specify a message to sign and a signing algorithm that your asymmetric -In AWS CLI 2.0, 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. +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. @@ -2556,0 +2668,40 @@ For more information, see [UpdateKeyDescription](https://docs.aws.amazon.com/cli +The following code example shows how to use `verify-mac`. + +**AWS CLI** + +