Working With Keys

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

// 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);

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

// 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();

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

// 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);

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

// 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);

Call the EnableKey function to mark a key as enabled.

// 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);

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

// 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);