Menu
AWS Key Management Service
Developer Guide

Working With Keys

This topic discusses how to create, describe, list, enable, and disable keys.

Creating a Customer Master Key

Call the CreateKey function to create a customer master key. The function takes three optional parameters, as shown in the following example.

Copy
// Creating a key. // // Input Parameters: // The function takes three optional parameters. // Description - Contains a string description for the key // KeyUsage - Use the default value (ENCRYPT_DECRYPT) // Policy - Use the default policy, which grants rights to all key actions // // Return Values: // The function returns a CreateKeyResult structure that contains the following: // AWSAccountId - Account ID of the account the key is associated with // ARN - Amazon Resource Name for the key // CreationDate - Date the key was created in UTC format // Description - Key description // Enabled - A Boolean value that specifies whether the key is enabled // KeyID - A unique value that can be used to identify the key in other operations // KeyUsage - A value that shows what the key can be used for // String desc = "Key for protecting critical data"; CreateKeyRequest req = new CreateKeyRequest().withDescription(desc); CreateKeyResult result = kms.createKey(req);

Generating a Data Key

Call the GenerateDataKey function to create a data key. The function takes up to five parameters, as shown in the following example.

Copy
// Generate a data key // // Input Parameters: // The function takes five parameters. // KeyId - Unique identifier for the key to be used for encryption // EncryptionContext - Authenticated data // NumberOfBytes - The number of bytes of data key being requested // KeySpec - The key specification being requested ("AES_128" or "AES_256") // GrantTokens - List of grant tokens // // Return Values: // The function returns a byte buffer that contains the encrypted key, a byte buffer // of the plaintext key, and the KeyID of the master key under which the key is encrypted. // // Replace the following string with a real key ID. 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_128"); GenerateDataKeyResult dataKeyResult = kmsClient.generateDataKey(dataKeyRequest); ByteBuffer plaintextKey = dataKeyResult.getPlaintext(); ByteBuffer encryptedKey = dataKeyResult.getCiphertextBlob();

Describing a Key

Call the DescribeKey function to retrieve detailed information about a customer master key.

Copy
// Describing a key. // // Input Parameters: // The function takes one required parameter. // KeyId - Unique identifier of the key. This can be an ARN, an alias, or a globally unique // identifier. // // Return Values: // The function returns a DescribeKeyResult object that contains metadata about // the key. // AWSAccountId - ID of the account the key is associated with // ARN - Amazon Resource Name for the key // CreationDate - Date the key was created in UTC format // Description - Key description // Enabled - A Boolean value that specifies whether the key is enabled // KeyId - A unique value that can be used to identify the key in other operations // KeyUsage - A value that shows what the key can be used for // // Replace the following string with a real key ID. String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; DescribeKeyRequest req = new DescribeKeyRequest().withKeyId(keyId); DescribeKeyResult result = kms.describeKey(req);

Listing Keys

Call the ListKeys function to retrieve a list of the customer master keys.

Copy
// Listing keys. // // Input Parameters: // The function takes two required parameters. // Limit - Specify this parameter only when paginating results to indicate the // maximum number of keys you want listed in the response. If there are // additional keys beyond the maximum you specify, the Truncated // response element will be set to true. // Marker - Use this parameter only when paginating results, and only in a subsequent // request after you've received a response where the results are truncated. // Set it to the value of the NextMarker in the response you // just received. // // Return Values: // The function returns a ListKeysResult object that contains the following // values: // Keys - A list of keys // NextMarker - If Truncated is true, this value is present and contains the value // to use for the Marker request parameter in a subsequent pagination // request. // Truncated - A flag that indicates whether there are more items in the list. If your results // were truncated, you can make a subsequent pagination request using the // Marker request parameter to retrieve more keys in the list. // Integer limit = 10; String marker = null; ListKeysRequest req = new ListKeysRequest().withMarker(marker).withLimit(limit); ListKeysResult result = kms.listKeys(req);

Enabling Keys

Call the EnableKey function to mark a key as enabled.

Copy
// Enabling a key. // // Input Parameters: // The function takes one required parameter. // KeyId - Unique identifier of the customer master key to be enabled. This can be an // ARN, an alias, or a globally unique identifier. // // Return Values: // The function does not return a value. // Replace the following string with a real key ID. String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; EnableKeyRequest req = new EnableKeyRequest().withKeyId(keyId); kms.enableKey(req);

Disabling Keys

Call the DisableKey function to prevent a key from being used.

Copy
// Disabling a key. // // Input Parameters: // The function takes one required parameter. // KeyId - Unique identifier of the customer master key to be disabled. This can be an // ARN, an alias, or a globally unique identifier. // // Return Values: // The function does not return a value. // // Replace the following string with a real key ID. String keyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; DisableKeyRequest req = new DisableKeyRequest().withKeyId(keyId); kms.disableKey(req);