Working with keys - Amazon Key Management Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Working with keys

The examples in this topic use the Amazon KMS API to create, view, enable, and disable Amazon KMS Amazon KMS keys, and to generate data keys.

Creating a KMS key

To create an Amazon KMS key (KMS key), use the CreateKey operation. The examples in this section create a symmetric encryption KMS key. The Description parameter used in these examples is optional.

In languages that require a client object, these examples use the Amazon KMS client object that you created in Creating a client.

For help with creating KMS keys in the Amazon KMS console, see Creating keys.

Java

For details, see the createKey method in the Amazon SDK for Java API Reference.

// Create a KMS key // String desc = "Key for protecting critical data"; CreateKeyRequest req = new CreateKeyRequest().withDescription(desc); CreateKeyResult result = kmsClient.createKey(req);
C#

For details, see the CreateKey method in the Amazon SDK for .NET.

// Create a KMS key // String desc = "Key for protecting critical data"; CreateKeyRequest req = new CreateKeyRequest() { Description = desc }; CreateKeyResponse response = kmsClient.CreateKey(req);
Python

For details, see the create_key method in the Amazon SDK for Python (Boto3).

# Create a KMS key desc = 'Key for protecting critical data' response = kms_client.create_key( Description=desc )
Ruby

For details, see the create_key instance method in the Amazon SDK for Ruby.

# Create a KMS key desc = 'Key for protecting critical data' response = kmsClient.create_key({ description: desc })
PHP

For details, see the CreateKey method in the Amazon SDK for PHP.

// Create a KMS key // $desc = "Key for protecting critical data"; $result = $KmsClient->createKey([ 'Description' => $desc ]);
Node.js

For details, see the createKey property in the Amazon SDK for JavaScript in Node.js.

// Create a KMS key // const Description = 'Key for protecting critical data'; kmsClient.createKey({ Description }, (err, data) => { ... });
PowerShell

To create a KMS key in PowerShell, use the New-KmsKey cmdlet.

# Create a KMS key $desc = 'Key for protecting critical data' New-KmsKey -Description $desc

To use the Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.

Generating a data key

To generate a symmetric data key, use the GenerateDataKey operation. This operation returns a plaintext data key and a copy of that data key encrypted under a symmetric encryption KMS key that you specify. You must specify either a KeySpec or NumberOfBytes (but not both) in each command.

For help using the data key to encrypt data, see the Amazon Encryption SDK. You can also use the data key in HMAC operations.

In languages that require a client object, these examples use the Amazon KMS client object that you created in Creating a client.

Java

For details, see the generateDataKey method in the Amazon SDK for Java API Reference.

// Generate a data key // // Replace the following example key ARN with any valid key identfier String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; GenerateDataKeyRequest dataKeyRequest = new GenerateDataKeyRequest(); dataKeyRequest.setKeyId(keyId); dataKeyRequest.setKeySpec("AES_256"); GenerateDataKeyResult dataKeyResult = kmsClient.generateDataKey(dataKeyRequest); ByteBuffer plaintextKey = dataKeyResult.getPlaintext(); ByteBuffer encryptedKey = dataKeyResult.getCiphertextBlob();
C#

For details, see the GenerateDataKey method in the Amazon SDK for .NET.

// Generate a data key // // Replace the following example key ARN with any valid key identfier String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; GenerateDataKeyRequest dataKeyRequest = new GenerateDataKeyRequest() { KeyId = keyId, KeySpec = DataKeySpec.AES_256 }; GenerateDataKeyResponse dataKeyResponse = kmsClient.GenerateDataKey(dataKeyRequest); MemoryStream plaintextKey = dataKeyResponse.Plaintext; MemoryStream encryptedKey = dataKeyResponse.CiphertextBlob;
Python

For details, see the generate_data_key method in the Amazon SDK for Python (Boto3).

# Generate a data key # Replace the following example key ARN with any valid key identfier key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kms_client.generate_data_key( KeyId=key_id, KeySpec='AES_256' ) plaintext_key = response['Plaintext'] encrypted_key = response['CiphertextBlob']
Ruby

For details, see the generate_data_key instance method in the Amazon SDK for Ruby.

# Generate a data key # Replace the following example key ARN with any valid key identfier key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kmsClient.generate_data_key({ key_id: key_id, key_spec: 'AES_256' }) plaintext_key = response.plaintext encrypted_key = response.ciphertext_blob
PHP

For details, see the GenerateDataKey method in the Amazon SDK for PHP.

// Generate a data key // // Replace the following example key ARN with any valid key identfier $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $keySpec = 'AES_256'; $result = $KmsClient->generateDataKey([ 'KeyId' => $keyId, 'KeySpec' => $keySpec, ]); $plaintextKey = $result['Plaintext']; $encryptedKey = $result['CiphertextBlob'];
Node.js

For details, see the generateDataKey property in the Amazon SDK for JavaScript in Node.js.

// Generate a data key // // Replace the following example key ARN with any valid key identfier const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; const KeySpec = 'AES_256'; kmsClient.generateDataKey({ KeyId, KeySpec }, (err, data) => { if (err) console.log(err, err.stack); else { const { CiphertextBlob, Plaintext } = data; ... } });
PowerShell

To generate a symmetric data key, use the New-KMSDataKey cmdlet.

In the output, the plaintext key (in the Plaintext property) and the encrypted key (in the CiphertextBlob property) are MemoryStream objects. To convert them to strings, use the methods of the MemoryStream class, or a cmdlet or function that converts MemoryStream objects to strings, such as the ConvertFrom-MemoryStream and ConvertFrom-Base64 functions in the Convert module.

# Generate a data key # Replace the following example key ARN with any valid key identfier $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' $keySpec = 'AES_256' $response = New-KmsDataKey -KeyId $keyId -KeySpec $keySpec $plaintextKey = $response.Plaintext $encryptedKey = $response.CiphertextBlob

To use the Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.

Viewing an Amazon KMS key

To get detailed information about an Amazon KMS key, including the KMS key ARN and key state, use the DescribeKey operation.

DescribeKey does not get aliases. To get aliases, use the ListAliases operation. For examples, see Working with aliases.

In languages that require a client object, these examples use the Amazon KMS client object that you created in Creating a client.

For help with viewing KMS keys in the Amazon KMS console, see Viewing keys.

Java

For details, see the describeKey method in the Amazon SDK for Java API Reference.

// Describe a KMS key // // Replace the following example key ARN with any valid key identfier String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; DescribeKeyRequest req = new DescribeKeyRequest().withKeyId(keyId); DescribeKeyResult result = kmsClient.describeKey(req);
C#

For details, see the DescribeKey method in the Amazon SDK for .NET.

// Describe a KMS key // // Replace the following example key ARN with any valid key identfier String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; DescribeKeyRequest describeKeyRequest = new DescribeKeyRequest() { KeyId = keyId }; DescribeKeyResponse describeKeyResponse = kmsClient.DescribeKey(describeKeyRequest);
Python

For details, see the describe_key method in the Amazon SDK for Python (Boto3).

# Describe a KMS key # Replace the following example key ARN with any valid key identfier key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kms_client.describe_key( KeyId=key_id )
Ruby

For details, see the describe_key instance method in the Amazon SDK for Ruby.

# Describe a KMS key # Replace the following example key ARN with any valid key identfier key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kmsClient.describe_key({ key_id: key_id })
PHP

For details, see the DescribeKey method in the Amazon SDK for PHP.

// Describe a KMS key // // Replace the following example key ARN with any valid key identfier $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $result = $KmsClient->describeKey([ 'KeyId' => $keyId, ]);
Node.js

For details, see the describeKey property in the Amazon SDK for JavaScript in Node.js.

// Describe a KMS key // // Replace the following example key ARN with any valid key identfier const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; kmsClient.describeKey({ KeyId }, (err, data) => { ... });
PowerShell

To get detailed information about a KMS key, use the Get-KmsKey cmdlet.

# Describe a KMS key # Replace the following example key ARN with any valid key identfier $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' Get-KmsKey -KeyId $keyId

To use the Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.

Getting key IDs and key ARNs of KMS keys

To get the key IDs and key ARNs of the Amazon KMS keys, use the ListKeys operation. These examples use the optional Limit parameter, which sets the maximum number of KMS keys returned in each call. For help identifying a KMS key in an Amazon KMS operations, see Key identifiers (KeyId).

In languages that require a client object, these examples use the Amazon KMS client object that you created in Creating a client.

For help with finding key IDs and key ARNs in the Amazon KMS console, see Finding the key ID and key ARN.

Java

For details, see the listKeys method in the Amazon SDK for Java API Reference.

// List KMS keys in this account // Integer limit = 10; ListKeysRequest req = new ListKeysRequest().withLimit(limit); ListKeysResult result = kmsClient.listKeys(req);
C#

For details, see the ListKeys method in the Amazon SDK for .NET.

// List KMS keys in this account // int limit = 10; ListKeysRequest listKeysRequest = new ListKeysRequest() { Limit = limit }; ListKeysResponse listKeysResponse = kmsClient.ListKeys(listKeysRequest);
Python

For details, see the list_keys method in the Amazon SDK for Python (Boto3).

# List KMS keys in this account response = kms_client.list_keys( Limit=10 )
Ruby

For details, see the list_keys instance method in the Amazon SDK for Ruby.

# List KMS keys in this account response = kmsClient.list_keys({ limit: 10 })
PHP

For details, see the ListKeys method in the Amazon SDK for PHP.

// List KMS keys in this account // $limit = 10; $result = $KmsClient->listKeys([ 'Limit' => $limit, ]);
Node.js

For details, see the listKeys property in the Amazon SDK for JavaScript in Node.js.

// List KMS keys in this account // const Limit = 10; kmsClient.listKeys({ Limit }, (err, data) => { ... });
PowerShell

To get the key ID and key ARN of all KMS keys in the account and Region, use the Get-KmsKeyList cmdlet.

To limit the number of output objects, this example uses the Select-Object cmdlet, instead of the Limit parameter, which is being deprecated in list cmdlets. For help with paginating output in Amazon Tools for PowerShell, see Output Pagination with Amazon Tools for PowerShell.

# List KMS keys in this account $limit = 10 Get-KmsKeyList | Select-Object -First $limit

To use the Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.

Enabling Amazon KMS keys

To enable a disabled Amazon KMS key, use the EnableKey operation.

In languages that require a client object, these examples use the Amazon KMS client object that you created in Creating a client.

For help with enabling and disabling KMS keys in the Amazon KMS console, see Enabling and disabling keys.

Java

For details about the Java implementation, see the enableKey method in the Amazon SDK for Java API Reference.

// Enable a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; EnableKeyRequest req = new EnableKeyRequest().withKeyId(keyId); kmsClient.enableKey(req);
C#

For details, see the EnableKey method in the Amazon SDK for .NET.

// Enable a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; EnableKeyRequest enableKeyRequest = new EnableKeyRequest() { KeyId = keyId }; kmsClient.EnableKey(enableKeyRequest);
Python

For details, see the enable_key method in the Amazon SDK for Python (Boto3).

# Enable a KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kms_client.enable_key( KeyId=key_id )
Ruby

For details, see the enable_key instance method in the Amazon SDK for Ruby.

# Enable a KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kmsClient.enable_key({ key_id: key_id })
PHP

For details, see the EnableKey method in the Amazon SDK for PHP.

// Enable a KMS key // // Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $result = $KmsClient->enableKey([ 'KeyId' => $keyId, ]);
Node.js

For details, see the enableKey property in the Amazon SDK for JavaScript in Node.js.

// Enable a KMS key // // Replace the following example key ARN with a valid key ID or key ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; kmsClient.enableKey({ KeyId }, (err, data) => { ... });
PowerShell

To enable a KMS key, use the Enable-KmsKey cmdlet.

# Enable a KMS key # Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' Enable-KmsKey -KeyId $keyId

To use the Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.

Disabling Amazon KMS key

To disable a KMS key, use the DisableKey operation. Disabling a KMS key prevents it from being used in cryptographic operations.

In languages that require a client object, these examples use the Amazon KMS client object that you created in Creating a client.

For help with enabling and disabling KMS keys in the Amazon KMS console, see Enabling and disabling keys.

Java

For details, see the disableKey method in the Amazon SDK for Java API Reference.

// Disable a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; DisableKeyRequest req = new DisableKeyRequest().withKeyId(keyId); kmsClient.disableKey(req);
C#

For details, see the DisableKey method in the Amazon SDK for .NET.

// Disable a KMS key // // Replace the following example key ARN with a valid key ID or key ARN String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; DisableKeyRequest disableKeyRequest = new DisableKeyRequest() { KeyId = keyId }; kmsClient.DisableKey(disableKeyRequest);
Python

For details, see the disable_key method in the Amazon SDK for Python (Boto3).

# Disable a KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kms_client.disable_key( KeyId=key_id )
Ruby

For details, see the disable_key instance method in the Amazon SDK for Ruby.

# Disable a KMS key # Replace the following example key ARN with a valid key ID or key ARN key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' response = kmsClient.disable_key({ key_id: key_id })
PHP

For details, see the DisableKey method in the Amazon SDK for PHP.

// Disable a KMS key // // Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; $result = $KmsClient->disableKey([ 'KeyId' => $keyId, ]);
Node.js

For details, see the disableKey property in the Amazon SDK for JavaScript in Node.js.

// Disable a KMS key // // Replace the following example key ARN with a valid key ID or key ARN const KeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'; kmsClient.disableKey({ KeyId }, (err, data) => { ... });
PowerShell

To disable a KMS key, use the Disable-KmsKey cmdlet.

# Disable a KMS key # Replace the following example key ARN with a valid key ID or key ARN $keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' Disable-KmsKey -KeyId $keyId

To use the Amazon KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more information, see the Amazon Tools for Windows PowerShell User Guide.