@aws-sdk/client-kms 3.288.0 → 3.289.0

package/dist-types/commands/DescribeKeyCommand.d.ts

@@ -111,6 +111,234 @@ export interface DescribeKeyCommandOutput extends DescribeKeyResponse, __Metadat
  * @see {@link DescribeKeyCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To get details about a KMS key
+ * ```javascript
+ * // The following example gets metadata for a symmetric encryption KMS key.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new DescribeKeyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyMetadata": {
+ *     "AWSAccountId": "111122223333",
+ *     "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *     "CreationDate": "2017-07-05T14:04:55-07:00",
+ *     "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
+ *     "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_KMS"
+ *   }
+ * }
+ * *\/
+ * // example id: get-key-details-1
+ * ```
+ *
+ * @example To get details about an RSA asymmetric KMS key
+ * ```javascript
+ * // The following example gets metadata for an asymmetric RSA KMS key used for signing and verification.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new DescribeKeyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyMetadata": {
+ *     "AWSAccountId": "111122223333",
+ *     "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *     "CreationDate": 1571767572.317,
+ *     "CustomerMasterKeySpec": "RSA_2048",
+ *     "Description": "",
+ *     "Enabled": false,
+ *     "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
+ *     "KeyManager": "CUSTOMER",
+ *     "KeySpec": "RSA_2048",
+ *     "KeyState": "Disabled",
+ *     "KeyUsage": "SIGN_VERIFY",
+ *     "MultiRegion": false,
+ *     "Origin": "AWS_KMS",
+ *     "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 id: to-get-details-about-an-rsa-asymmetric-kms-key-2
+ * ```
+ *
+ * @example To get details about a multi-Region key
+ * ```javascript
+ * // The following example gets metadata for a multi-Region replica key. This multi-Region key is a symmetric encryption key. DescribeKey returns information about the primary key and all of its replicas.
+ * const input = {
+ *   "KeyId": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"
+ * };
+ * const command = new DescribeKeyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyMetadata": {
+ *     "AWSAccountId": "111122223333",
+ *     "Arn": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
+ *     "CreationDate": 1586329200.918,
+ *     "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
+ *     "Description": "",
+ *     "Enabled": true,
+ *     "EncryptionAlgorithms": [
+ *       "SYMMETRIC_DEFAULT"
+ *     ],
+ *     "KeyId": "mrk-1234abcd12ab34cd56ef1234567890ab",
+ *     "KeyManager": "CUSTOMER",
+ *     "KeyState": "Enabled",
+ *     "KeyUsage": "ENCRYPT_DECRYPT",
+ *     "MultiRegion": true,
+ *     "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"
+ *         }
+ *       ]
+ *     },
+ *     "Origin": "AWS_KMS"
+ *   }
+ * }
+ * *\/
+ * // example id: to-get-details-about-a-multi-region-key-3
+ * ```
+ *
+ * @example To get details about an HMAC KMS key
+ * ```javascript
+ * // The following example gets the metadata of an HMAC KMS key.
+ * const input = {
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new DescribeKeyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyMetadata": {
+ *     "AWSAccountId": "123456789012",
+ *     "Arn": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *     "CreationDate": 1566160362.664,
+ *     "CustomerMasterKeySpec": "HMAC_256",
+ *     "Description": "Development test key",
+ *     "Enabled": true,
+ *     "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
+ *     "KeyManager": "CUSTOMER",
+ *     "KeyState": "Enabled",
+ *     "KeyUsage": "GENERATE_VERIFY_MAC",
+ *     "MacAlgorithms": [
+ *       "HMAC_SHA_256"
+ *     ],
+ *     "MultiRegion": false,
+ *     "Origin": "AWS_KMS"
+ *   }
+ * }
+ * *\/
+ * // example id: to-get-details-about-an-hmac-kms-key-4
+ * ```
+ *
+ * @example To get details about a KMS key in an AWS CloudHSM key store
+ * ```javascript
+ * // The following example gets the metadata of a KMS key in an AWS CloudHSM key store.
+ * const input = {
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new DescribeKeyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyMetadata": {
+ *     "AWSAccountId": "123456789012",
+ *     "Arn": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *     "CloudHsmClusterId": "cluster-1a23b4cdefg",
+ *     "CreationDate": 1646160362.664,
+ *     "CustomKeyStoreId": "cks-1234567890abcdef0",
+ *     "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
+ *     "Description": "CloudHSM key store test key",
+ *     "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"
+ *   }
+ * }
+ * *\/
+ * // example id: to-get-details-about-a-kms-key-in-an-AWS-CloudHSM-key-store-5
+ * ```
+ *
+ * @example To get details about a KMS key in an external key store
+ * ```javascript
+ * // The following example gets the metadata of a KMS key in an external key store.
+ * const input = {
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new DescribeKeyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyMetadata": {
+ *     "AWSAccountId": "123456789012",
+ *     "Arn": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *     "CreationDate": 1646160362.664,
+ *     "CustomKeyStoreId": "cks-1234567890abcdef0",
+ *     "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
+ *     "Description": "External key store test key",
+ *     "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"
+ *     }
+ *   }
+ * }
+ * *\/
+ * // example id: to-get-details-about-a-kms-key-in-an-external-key-store-6
+ * ```
+ *
  */
 export declare class DescribeKeyCommand extends $Command<DescribeKeyCommandInput, DescribeKeyCommandOutput, KMSClientResolvedConfig> {
     readonly input: DescribeKeyCommandInput;

package/dist-types/commands/DisableKeyCommand.d.ts

@@ -43,6 +43,17 @@ export interface DisableKeyCommandOutput extends __MetadataBearer {
  * @see {@link DisableKeyCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To disable a KMS key
+ * ```javascript
+ * // The following example disables the specified KMS key.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new DisableKeyCommand(input);
+ * await client.send(command);
+ * // example id: to-disable-a-cmk-1478566583659
+ * ```
+ *
  */
 export declare class DisableKeyCommand extends $Command<DisableKeyCommandInput, DisableKeyCommandOutput, KMSClientResolvedConfig> {
     readonly input: DisableKeyCommandInput;

package/dist-types/commands/DisableKeyRotationCommand.d.ts

@@ -61,6 +61,17 @@ export interface DisableKeyRotationCommandOutput extends __MetadataBearer {
  * @see {@link DisableKeyRotationCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To disable automatic rotation of key material
+ * ```javascript
+ * // The following example disables automatic annual rotation of the key material for the specified KMS key.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new DisableKeyRotationCommand(input);
+ * await client.send(command);
+ * // example id: to-disable-automatic-rotation-of-key-material-1478624396092
+ * ```
+ *
  */
 export declare class DisableKeyRotationCommand extends $Command<DisableKeyRotationCommandInput, DisableKeyRotationCommandOutput, KMSClientResolvedConfig> {
     readonly input: DisableKeyRotationCommandInput;

package/dist-types/commands/DisconnectCustomKeyStoreCommand.d.ts

@@ -80,6 +80,17 @@ export interface DisconnectCustomKeyStoreCommandOutput extends DisconnectCustomK
  * @see {@link DisconnectCustomKeyStoreCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To disconnect a custom key store from its CloudHSM cluster
+ * ```javascript
+ * // This example disconnects an AWS KMS custom key store from its backing key store. For an AWS CloudHSM key store, it disconnects the key store from its AWS CloudHSM cluster. For an external key store, it disconnects the key store from the external key store proxy that communicates with your external key manager. This operation doesn't return any data. To verify that the custom key store is disconnected, use the <code>DescribeCustomKeyStores</code> operation.
+ * const input = {
+ *   "CustomKeyStoreId": "cks-1234567890abcdef0"
+ * };
+ * const command = new DisconnectCustomKeyStoreCommand(input);
+ * await client.send(command);
+ * // example id: to-disconnect-a-custom-key-store-from-its-cloudhsm-cluster-1628627955156
+ * ```
+ *
  */
 export declare class DisconnectCustomKeyStoreCommand extends $Command<DisconnectCustomKeyStoreCommandInput, DisconnectCustomKeyStoreCommandOutput, KMSClientResolvedConfig> {
     readonly input: DisconnectCustomKeyStoreCommandInput;

package/dist-types/commands/EnableKeyCommand.d.ts

@@ -39,6 +39,17 @@ export interface EnableKeyCommandOutput extends __MetadataBearer {
  * @see {@link EnableKeyCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To enable a KMS key
+ * ```javascript
+ * // The following example enables the specified KMS key.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new EnableKeyCommand(input);
+ * await client.send(command);
+ * // example id: to-enable-a-cmk-1478627501129
+ * ```
+ *
  */
 export declare class EnableKeyCommand extends $Command<EnableKeyCommandInput, EnableKeyCommandOutput, KMSClientResolvedConfig> {
     readonly input: EnableKeyCommandInput;

package/dist-types/commands/EnableKeyRotationCommand.d.ts

@@ -69,6 +69,17 @@ export interface EnableKeyRotationCommandOutput extends __MetadataBearer {
  * @see {@link EnableKeyRotationCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To enable automatic rotation of key material
+ * ```javascript
+ * // The following example enables automatic annual rotation of the key material for the specified KMS key.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new EnableKeyRotationCommand(input);
+ * await client.send(command);
+ * // example id: to-enable-automatic-rotation-of-key-material-1478629109677
+ * ```
+ *
  */
 export declare class EnableKeyRotationCommand extends $Command<EnableKeyRotationCommandInput, EnableKeyRotationCommandOutput, KMSClientResolvedConfig> {
     readonly input: EnableKeyRotationCommandInput;

package/dist-types/commands/EncryptCommand.d.ts

@@ -138,6 +138,24 @@ export interface EncryptCommandOutput extends EncryptResponse, __MetadataBearer
  * @see {@link EncryptCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To encrypt data
+ * ```javascript
+ * // The following example encrypts data with the specified KMS key.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "Plaintext": "<binary data>"
+ * };
+ * const command = new EncryptCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "CiphertextBlob": "<binary data>",
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
+ * }
+ * *\/
+ * // example id: to-encrypt-data-1478906026012
+ * ```
+ *
  */
 export declare class EncryptCommand extends $Command<EncryptCommandInput, EncryptCommandOutput, KMSClientResolvedConfig> {
     readonly input: EncryptCommandInput;

package/dist-types/commands/GenerateDataKeyCommand.d.ts

@@ -122,6 +122,25 @@ export interface GenerateDataKeyCommandOutput extends GenerateDataKeyResponse, _
  * @see {@link GenerateDataKeyCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To generate a data key
+ * ```javascript
+ * // The following example generates a 256-bit symmetric data encryption key (data key) in two formats. One is the unencrypted (plainext) data key, and the other is the data key encrypted with the specified KMS key.
+ * const input = {
+ *   "KeyId": "alias/ExampleAlias",
+ *   "KeySpec": "AES_256"
+ * };
+ * const command = new GenerateDataKeyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "CiphertextBlob": "<binary data>",
+ *   "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "Plaintext": "<binary data>"
+ * }
+ * *\/
+ * // example id: to-generate-a-data-key-1478912956062
+ * ```
+ *
  */
 export declare class GenerateDataKeyCommand extends $Command<GenerateDataKeyCommandInput, GenerateDataKeyCommandOutput, KMSClientResolvedConfig> {
     readonly input: GenerateDataKeyCommandInput;

package/dist-types/commands/GenerateDataKeyPairCommand.d.ts

@@ -99,6 +99,27 @@ export interface GenerateDataKeyPairCommandOutput extends GenerateDataKeyPairRes
  * @see {@link GenerateDataKeyPairCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To generate an RSA key pair for encryption and decryption
+ * ```javascript
+ * // This example generates an RSA data key pair for encryption and decryption. The operation returns a plaintext public key and private key, and a copy of the private key that is encrypted under a symmetric encryption KMS key that you specify.
+ * const input = {
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "KeyPairSpec": "RSA_3072"
+ * };
+ * const command = new GenerateDataKeyPairCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "KeyPairSpec": "RSA_3072",
+ *   "PrivateKeyCiphertextBlob": "<binary data>",
+ *   "PrivateKeyPlaintext": "<binary data>",
+ *   "PublicKey": "<binary data>"
+ * }
+ * *\/
+ * // example id: to-generate-an-rsa-key-pair-for-encryption-and-decryption-1628619376878
+ * ```
+ *
  */
 export declare class GenerateDataKeyPairCommand extends $Command<GenerateDataKeyPairCommandInput, GenerateDataKeyPairCommandOutput, KMSClientResolvedConfig> {
     readonly input: GenerateDataKeyPairCommandInput;

package/dist-types/commands/GenerateDataKeyPairWithoutPlaintextCommand.d.ts

@@ -91,6 +91,26 @@ export interface GenerateDataKeyPairWithoutPlaintextCommandOutput extends Genera
  * @see {@link GenerateDataKeyPairWithoutPlaintextCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To generate an asymmetric data key pair without a plaintext key
+ * ```javascript
+ * // This example returns an asymmetric elliptic curve (ECC) data key pair. The private key is encrypted under the symmetric encryption KMS key that you specify. This operation doesn't return a plaintext (unencrypted) private key.
+ * const input = {
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "KeyPairSpec": "ECC_NIST_P521"
+ * };
+ * const command = new GenerateDataKeyPairWithoutPlaintextCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "KeyPairSpec": "ECC_NIST_P521",
+ *   "PrivateKeyCiphertextBlob": "<binary data>",
+ *   "PublicKey": "<binary data>"
+ * }
+ * *\/
+ * // example id: to-generate-an-asymmetric-data-key-pair-without-a-plaintext-key-1628620971564
+ * ```
+ *
  */
 export declare class GenerateDataKeyPairWithoutPlaintextCommand extends $Command<GenerateDataKeyPairWithoutPlaintextCommandInput, GenerateDataKeyPairWithoutPlaintextCommandOutput, KMSClientResolvedConfig> {
     readonly input: GenerateDataKeyPairWithoutPlaintextCommandInput;

package/dist-types/commands/GenerateDataKeyWithoutPlaintextCommand.d.ts

@@ -100,6 +100,24 @@ export interface GenerateDataKeyWithoutPlaintextCommandOutput extends GenerateDa
  * @see {@link GenerateDataKeyWithoutPlaintextCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To generate an encrypted data key
+ * ```javascript
+ * // The following example generates an encrypted copy of a 256-bit symmetric data encryption key (data key). The data key is encrypted with the specified KMS key.
+ * const input = {
+ *   "KeyId": "alias/ExampleAlias",
+ *   "KeySpec": "AES_256"
+ * };
+ * const command = new GenerateDataKeyWithoutPlaintextCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "CiphertextBlob": "<binary data>",
+ *   "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
+ * }
+ * *\/
+ * // example id: to-generate-an-encrypted-data-key-1478914121134
+ * ```
+ *
  */
 export declare class GenerateDataKeyWithoutPlaintextCommand extends $Command<GenerateDataKeyWithoutPlaintextCommandInput, GenerateDataKeyWithoutPlaintextCommandOutput, KMSClientResolvedConfig> {
     readonly input: GenerateDataKeyWithoutPlaintextCommandInput;

package/dist-types/commands/GenerateMacCommand.d.ts

@@ -56,6 +56,26 @@ export interface GenerateMacCommandOutput extends GenerateMacResponse, __Metadat
  * @see {@link GenerateMacCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To generate an HMAC for a message
+ * ```javascript
+ * // This example 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.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "MacAlgorithm": "HMAC_SHA_384",
+ *   "Message": "Hello World"
+ * };
+ * const command = new GenerateMacCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "Mac": "<HMAC_TAG>",
+ *   "MacAlgorithm": "HMAC_SHA_384"
+ * }
+ * *\/
+ * // example id: to-generate-an-hmac-for-a-message-1631570135665
+ * ```
+ *
  */
 export declare class GenerateMacCommand extends $Command<GenerateMacCommandInput, GenerateMacCommandOutput, KMSClientResolvedConfig> {
     readonly input: GenerateMacCommandInput;

package/dist-types/commands/GenerateRandomCommand.d.ts

@@ -43,6 +43,22 @@ export interface GenerateRandomCommandOutput extends GenerateRandomResponse, __M
  * @see {@link GenerateRandomCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To generate random data
+ * ```javascript
+ * // The following example generates 32 bytes of random data.
+ * const input = {
+ *   "NumberOfBytes": 32
+ * };
+ * const command = new GenerateRandomCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "Plaintext": "<binary data>"
+ * }
+ * *\/
+ * // example id: to-generate-random-data-1479163645600
+ * ```
+ *
  */
 export declare class GenerateRandomCommand extends $Command<GenerateRandomCommandInput, GenerateRandomCommandOutput, KMSClientResolvedConfig> {
     readonly input: GenerateRandomCommandInput;

package/dist-types/commands/GetKeyPolicyCommand.d.ts

@@ -36,6 +36,23 @@ export interface GetKeyPolicyCommandOutput extends GetKeyPolicyResponse, __Metad
  * @see {@link GetKeyPolicyCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To retrieve a key policy
+ * ```javascript
+ * // The following example retrieves the key policy for the specified KMS key.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "PolicyName": "default"
+ * };
+ * const command = new GetKeyPolicyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "Policy": "{\n  \"Version\" : \"2012-10-17\",\n  \"Id\" : \"key-default-1\",\n  \"Statement\" : [ {\n    \"Sid\" : \"Enable IAM User Permissions\",\n    \"Effect\" : \"Allow\",\n    \"Principal\" : {\n      \"AWS\" : \"arn:aws:iam::111122223333:root\"\n    },\n    \"Action\" : \"kms:*\",\n    \"Resource\" : \"*\"\n  } ]\n}"
+ * }
+ * *\/
+ * // example id: to-retrieve-a-key-policy-1479170128325
+ * ```
+ *
  */
 export declare class GetKeyPolicyCommand extends $Command<GetKeyPolicyCommandInput, GetKeyPolicyCommandOutput, KMSClientResolvedConfig> {
     readonly input: GetKeyPolicyCommandInput;

package/dist-types/commands/GetKeyRotationStatusCommand.d.ts

@@ -81,6 +81,22 @@ export interface GetKeyRotationStatusCommandOutput extends GetKeyRotationStatusR
  * @see {@link GetKeyRotationStatusCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To retrieve the rotation status for a KMS key
+ * ```javascript
+ * // The following example retrieves the status of automatic annual rotation of the key material for the specified KMS key.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new GetKeyRotationStatusCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyRotationEnabled": true
+ * }
+ * *\/
+ * // example id: to-retrieve-the-rotation-status-for-a-cmk-1479172287408
+ * ```
+ *
  */
 export declare class GetKeyRotationStatusCommand extends $Command<GetKeyRotationStatusCommandInput, GetKeyRotationStatusCommandOutput, KMSClientResolvedConfig> {
     readonly input: GetKeyRotationStatusCommandInput;

package/dist-types/commands/GetParametersForImportCommand.d.ts

@@ -62,6 +62,27 @@ export interface GetParametersForImportCommandOutput extends GetParametersForImp
  * @see {@link GetParametersForImportCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To retrieve the public key and import token for a KMS key
+ * ```javascript
+ * // The following example retrieves the public key and import token for the specified KMS key.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "WrappingAlgorithm": "RSAES_OAEP_SHA_1",
+ *   "WrappingKeySpec": "RSA_2048"
+ * };
+ * const command = new GetParametersForImportCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "ImportToken": "<binary data>",
+ *   "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "ParametersValidTo": "2016-12-01T14:52:17-08:00",
+ *   "PublicKey": "<binary data>"
+ * }
+ * *\/
+ * // example id: to-retrieve-the-public-key-and-import-token-for-a-cmk-1480626483211
+ * ```
+ *
  */
 export declare class GetParametersForImportCommand extends $Command<GetParametersForImportCommandInput, GetParametersForImportCommandOutput, KMSClientResolvedConfig> {
     readonly input: GetParametersForImportCommandInput;

package/dist-types/commands/GetPublicKeyCommand.d.ts

@@ -77,6 +77,29 @@ export interface GetPublicKeyCommandOutput extends GetPublicKeyResponse, __Metad
  * @see {@link GetPublicKeyCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To download the public key of an asymmetric KMS key
+ * ```javascript
+ * // This example gets the public key of an asymmetric RSA KMS key used for encryption and decryption. The operation returns the key spec, key usage, and encryption or signing algorithms to help you use the public key correctly outside of AWS KMS.
+ * const input = {
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
+ * };
+ * const command = new GetPublicKeyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "CustomerMasterKeySpec": "RSA_4096",
+ *   "EncryptionAlgorithms": [
+ *     "RSAES_OAEP_SHA_1",
+ *     "RSAES_OAEP_SHA_256"
+ *   ],
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
+ *   "KeyUsage": "ENCRYPT_DECRYPT",
+ *   "PublicKey": "<binary data>"
+ * }
+ * *\/
+ * // example id: to-download-the-public-key-of-an-asymmetric-kms-key-1628621691873
+ * ```
+ *
  */
 export declare class GetPublicKeyCommand extends $Command<GetPublicKeyCommandInput, GetPublicKeyCommandOutput, KMSClientResolvedConfig> {
     readonly input: GetPublicKeyCommandInput;

package/dist-types/commands/ImportKeyMaterialCommand.d.ts

@@ -92,6 +92,20 @@ export interface ImportKeyMaterialCommandOutput extends ImportKeyMaterialRespons
  * @see {@link ImportKeyMaterialCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To import key material into a KMS key
+ * ```javascript
+ * // The following example imports key material into the specified KMS key.
+ * const input = {
+ *   "EncryptedKeyMaterial": "<binary data>",
+ *   "ExpirationModel": "KEY_MATERIAL_DOES_NOT_EXPIRE",
+ *   "ImportToken": "<binary data>",
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new ImportKeyMaterialCommand(input);
+ * await client.send(command);
+ * // example id: to-import-key-material-into-a-cmk-1480630551969
+ * ```
+ *
  */
 export declare class ImportKeyMaterialCommand extends $Command<ImportKeyMaterialCommandInput, ImportKeyMaterialCommandOutput, KMSClientResolvedConfig> {
     readonly input: ImportKeyMaterialCommandInput;