Updating AWS KMS keyrings

The AWS KMS keyrings in the AWS Encryption SDK for C, the AWS Encryption SDK for .NET, and the AWS Encryption SDK for JavaScript support best practices by allowing you to specify wrapping keys when encrypting and decrypting. If you create an AWS KMS discovery keyring, you do so explicitly.

Note

The earliest version of the AWS Encryption SDK for .NET is version 3.0.x. All versions of the AWS Encryption SDK for .NET support the security best practices introduced in 2.0.x of the AWS Encryption SDK. You can safely upgrade to the latest version without any code or data changes.

When you update to the latest 1.x version of the AWS Encryption SDK, you can use a discovery filter to limit the wrapping keys that an AWS KMS discovery keyring or AWS KMS regional discovery keyring uses when decrypting to those in particular AWS accounts. Filtering a discovery keyring is an AWS Encryption SDK best practice.

The examples in this section will show you how to add the discovery filter to an AWS KMS regional discovery keyring.

Learn more about migration

For all AWS Encryption SDK users, learn about setting your commitment policy in Setting your commitment policy.

For AWS Encryption SDK for Java, AWS Encryption SDK for Python, and AWS Encryption CLI users, learn about a required update to master key providers in Updating AWS KMS master key providers.

 

You might have code like the following in your application. This example creates an AWS KMS regional discovery keyring that can only use wrapping keys in the US West (Oregon) (us-west-2) Region. This example represents code in AWS Encryption SDK versions earlier than 1.7.x. However, it is still valid in versions 1.7.x and later.

C

struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
       .WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery());

JavaScript Browser

const clientProvider = getClient(KMS, { credentials })

const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser({ clientProvider, discovery })

JavaScript Node.js

const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({ clientProvider, discovery })

Beginning in version 1.7.x, you can add a discovery filter to any AWS KMS discovery keyring. This discovery filter limits the AWS KMS keys that the AWS Encryption SDK can use for decryption to those in the specified partition and accounts. Before using this code, change the partition, if necessary, and replace the example account IDs with valid ones.

C

For a complete example, see kms_discovery.cpp.

std::shared_ptr<KmsKeyring::DiscoveryFilter> discovery_filter(
    KmsKeyring::DiscoveryFilter::Builder("aws")
        .AddAccount("111122223333")
        .AddAccount("444455556666")
        .Build());

struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
       .WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery(discovery_filter));

JavaScript Browser

const clientProvider = getClient(KMS, { credentials })

const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser(clientProvider, {
    discovery,
    discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})

JavaScript Node.js

For a complete example, see kms_filtered_discovery.ts.

const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({
    clientProvider,
    discovery,
    discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})