Working with keys
The examples in this topic use the AWS KMS API to create, view, enable, and disable AWS KMS
AWS KMS keys, and to generate data keys.
Creating a KMS key
To create an AWS 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 AWS KMS client object that you created in Creating a client.
For help with creating KMS keys in the AWS KMS console, see Creating keys.
- Java
-
For details, see the createKey method in the
AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more
information, see the AWS 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 AWS Encryption SDK. You can also use the data key in HMAC operations.
In languages that require a client object, these examples use the AWS KMS client object that you created in Creating a client.
- Java
-
For details, see the generateDataKey method in the
AWS 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
AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more
information, see the AWS Tools for Windows PowerShell User Guide.
Viewing an AWS KMS key
To get detailed information about an AWS 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 AWS KMS client object that you created in Creating a client.
For help with viewing KMS keys in the AWS KMS console, see Viewing keys.
- Java
-
For details, see the describeKey method in the
AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more
information, see the AWS 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 AWS 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 AWS KMS operations, see Key identifiers (KeyId).
In languages that require a client object, these examples use the AWS KMS client object that you created in Creating a client.
For help with finding key IDs and key ARNs in the AWS KMS console, see Finding the key ID and key ARN.
- Java
-
For details, see the listKeys method in the
AWS 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 AWS 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 AWS 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 AWS SDK for Ruby.
# List KMS keys in this account
response = kmsClient.list_keys({
limit: 10
})
- PHP
-
For details, see the ListKeys method
in the AWS 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 AWS 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 AWS Tools for PowerShell, see Output Pagination with AWS Tools for PowerShell.
# List KMS keys in this account
$limit = 10
Get-KmsKeyList | Select-Object -First $limit
To use the AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more
information, see the AWS Tools for Windows PowerShell User Guide.
Enabling AWS KMS keys
To enable a disabled AWS KMS key, use the EnableKey operation.
In languages that require a client object, these examples use the AWS KMS client object that you created in Creating a client.
For help with enabling and disabling KMS keys in the AWS KMS console, see Enabling and disabling keys.
- Java
-
For details about the Java implementation, see the enableKey method in the
AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more
information, see the AWS Tools for Windows PowerShell User Guide.
Disabling AWS 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 AWS KMS client object that you created in Creating a client.
For help with enabling and disabling KMS keys in the AWS KMS console, see Enabling and disabling keys.
- Java
-
For details, see the disableKey method in the
AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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 AWS KMS PowerShell cmdlets, install the AWS.Tools.KeyManagementService module. For more
information, see the AWS Tools for Windows PowerShell User Guide.