After deploying version 1.7.x successfully to all hosts, you can upgrade to version 2.0.x. Version 2.0.x includes breaking changes for all earlier versions of the AWS Encryption SDK. However, if you make the code changes recommended in Stage 1, you can avoid errors when you migrate to version 2.0.x.
When you update to versions 2.0.x and later from 1.7.x, verify that your commitment policy is
consistently set to ForbidEncryptAllowDecrypt. Then, depending on your data configuration, you can migrate at your own pace to RequireEncryptAllowDecrypt and then to the default setting, RequireEncryptRequireDecrypt. We recommend a series of transition steps like the following pattern.
1. Begin with your commitment policy (p. 193) set to ForbidEncryptAllowDecrypt. The AWS Encryption SDK can decrypt messages with key commitment, but it doesn't yet encrypt with key commitment.
2. When you are ready, you can update your commitment policy to RequireEncryptAllowDecrypt.
The AWS Encryption SDK begins to encrypt your data with key commitment (p. 10). It can decrypt ciphertext with and without key commitment.
Before updating your commitment policy to RequireEncryptAllowDecrypt, verify that version 1.7.x is deployed to all hosts, including hosts of any applications that decrypt the ciphertext you produce. Versions of the AWS Encryption SDK prior to version 1.7.x cannot decrypt messages encrypted with key commitment.
This is also a good time to add metrics to your application to measure whether you are still processing ciphertext without key commitment. This will help you determine when it's safe to update your commitment policy setting to RequireEncryptRequireDecrypt. For some applications, such as those that encrypt messages in an Amazon SQS queue, this might mean waiting long enough that all ciphertext encrypted under old versions have been re-encrypted or deleted. For other applications, such as encrypted S3 objects, you might need to download, re-encrypt, and re-upload all objects.
3. When you are certain that you don't have any messages encrypted without key commitment, you can update your commitment policy to RequireEncryptRequireDecrypt. This value assures that your data is always encrypted and decrypted with key commitment. This setting is the default, so you aren't required to set it explicitly, but we recommend it. An explicit setting will aid debugging (p. 198) and any potential rollbacks that might be required if your application encounters ciphertext encrypted without key commitment.
Updating AWS KMS master key providers
To migrate to versions 1.7.x and then to version 2.0.x or later, you must replace legacy AWS KMS master key providers with master key providers created explicitly in strict mode or discovery mode (p. 177).
Legacy master key providers are deprecated in version 1.7.x and removed in version 2.0.x. This change is required for applications and scripts that use the AWS Encryption SDK for Java (p. 68), AWS Encryption SDK for Python (p. 86), and the AWS Encryption CLI (p. 94). The examples in this section will show you how to update your code.
NoteIn Python, turn on deprecation warnings. This will help you identify the parts of your code that you need to update.
If you are using an AWS KMS master key (not a master key provider), you can skip this step. AWS KMS master keys are not deprecated or removed. They encrypt and decrypt only with the wrapping keys that you specify.
The examples in this section focus on the elements of your code that you need to change. For a complete example of the updated code, see the Examples section of the GitHub repository for your programming
language (p. 59). Also, these examples typically use key ARNs to represent AWS KMS keys. When you create a master key provider for encrypting, you can use any valid AWS KMS key identifier to represent an AWS KMS key . When you create a master key provider for decrypting, you must use a key ARN.
Learn more about migration
For all AWS Encryption SDK users, learn about setting your commitment policy in the section called
“Setting your commitment policy” (p. 193).
For AWS Encryption SDK for C and AWS Encryption SDK for JavaScript users, learn about an optional update to keyrings in Updating AWS KMS keyrings (p. 191).
Topics
• Migrating to strict mode (p. 187)
• Migrating to discovery mode (p. 189)
Migrating to strict mode
After updating to version 1.7.x, you can replace your legacy master key providers with master key providers in strict mode. In strict mode, you must specify the wrapping keys to use when encrypting and decrypting. The AWS Encryption SDK uses only the wrapping keys you specify. Deprecated master key providers can decrypt data using any AWS KMS key that encrypted a data key, including AWS KMS keys in different AWS accounts and Regions.
Master key providers in strict mode are introduced in the AWS Encryption SDK version 1.7.x. They replace legacy master key providers, which are deprecated in 1.7.x and removed in 2.0.x. Using master key providers in strict mode is an AWS Encryption SDK best practice (p. 17).
The following code creates a master key provider in strict mode that you can use for encrypting and decrypting.
Java
This example represents code in an application that uses the version 1.6.2 or earlier of the AWS Encryption SDK for Java.
This code uses the KmsMasterKeyProvider.builder() method to instantiate an AWS KMS master key provider that uses one AWS KMS key as a wrapping key.
// Create a master key provider
// Replace the example key ARN with a valid one String awsKmsKey =
"arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder() .withKeysForEncryption(awsKmsKey)
.build();
This example represents code in an application that uses version 1.7.x or later of the AWS Encryption SDK for Java . For a complete example, see BasicEncryptionExample.java.
The Builder.build() and Builder.withKeysForEncryption() methods used in the previous example are deprecated in version 1.7.x and are removed from version 2.0.x.
To update to a strict mode master key provider, this code replaces calls to deprecated methods with a call to the new Builder.buildStrict() method. This example specifies one AWS KMS key as the wrapping key, but the Builder.buildStrict() method can take a list of multiple AWS KMS keys.
// Create a master key provider in strict mode
// Replace the example key ARN with a valid one from your AWS account.
String awsKmsKey =
"arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder() .buildStrict(awsKmsKey);
Python
This example represents code in an application that uses version 1.4.1 of the AWS Encryption SDK for Python. This code uses KMSMasterKeyProvider, which is deprecated in version 1.7.x and removed from version 2.0.x. When decrypting, it uses any AWS KMS key that encrypted a data key without regard to the AWS KMS keys you specify.
Note that KMSMasterKey is not deprecated or removed. When encrypting and decrypting, it uses only the AWS KMS key you specify.
# Create a master key provider
# Replace the example key ARN with a valid one
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = KMSMasterKeyProvider(
key_ids=[key_1, key_2]
)
This example represents code in an application that uses version 1.7.x of the AWS Encryption SDK for Python. For a complete example, see basic_encryption.py.
To update to a strict mode master key provider, this code replaces the call to
KMSMasterKeyProvider() with a call to StrictAwsKmsMasterKeyProvider().
# Create a master key provider in strict mode
# Replace the example key ARNs with valid values from your AWS account
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
AWS Encryption CLI
This example shows how to encrypt and decrypt using the AWS Encryption CLI version 1.1.7 or earlier.
In version 1.1.7 and earlier, when encrypting, you specify one or more master keys (or wrapping keys), such as an AWS KMS key. When decrypting, you can't specify any wrapping keys unless you are using a custom master key provider. The AWS Encryption CLI can use any wrapping key that encrypted a data key.
\\ Replace the example key ARN with a valid one
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--master-keys key=$keyArn \
--metadata-output ~/metadata \ --encryption-context purpose=test \ --output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --output .
This example shows how to encrypt and decrypt using the AWS Encryption CLI version 1.7.x or later.
For complete examples, see Examples of the AWS Encryption CLI (p. 107).
The --master-keys parameter is deprecated in version 1.7.x and removed in version 2.0.x. It's replaced the by --wrapping-keys parameter, which is required in encrypt and decrypt commands.
This parameter supports strict mode and discovery mode. Strict mode is an AWS Encryption SDK best practice that assures that you use the wrapping key that you intend.
To upgrade to strict mode, use the key attribute of the --wrapping-keys parameter to specify a wrapping key when encrypting and decrypting.
\\ Replace the example key ARN with a valid value
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \ --metadata-output ~/metadata \ --encryption-context purpose=test \ --output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \ --wrapping-keys key=$keyArn \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --output .
Migrating to discovery mode
Beginning in version 1.7.x, it's an AWS Encryption SDK best practice (p. 17) to use strict mode for AWS KMS master key providers, that is, to specify wrapping keys when encrypting and decrypting. You must always specify wrapping keys when encrypting. But there are situations in which specifying the key ARNs of AWS KMS keys for decrypting is impractical. For example, if you're using aliases to identify AWS KMS keys when encrypting, you lose the benefit of aliases if you have to list key ARNs when decrypting. Also, because master key providers in discovery mode behave like the original master key providers, you might use them temporarily as part of your migration strategy, and then upgrade to master key providers in strict mode later.
In cases like this, you can use master key providers in discovery mode. These master key providers don't let you specify wrapping keys, so you cannot use them for encrypting. When decrypting, they can use any wrapping key that encrypted a data key. But unlike legacy master key providers, which behave the same way, you create them in discovery mode explicitly. When using master key providers in discovery mode, you can limit the wrapping keys that can be used to those in particular AWS accounts. This filter is optional, but it's a best practice that we recommend. For information about AWS partitions and accounts, see Amazon Resource Names in the AWS General Reference.
The following examples create an AWS KMS master key provider in strict mode for encrypting and an AWS KMS master key provider in discovery mode for decrypting. The master key provider in discovery mode uses a discovery filter to limit the wrapping keys used for decrypting to the aws partition and to particular example AWS accounts. Although the account filter is not necessary in this very simple example, it's a best practice that is very beneficial when one application encrypts data and a different application decrypts the data.
Java
This example represents code in an application that uses version 1.7.x or later of the AWS Encryption SDK for Java. For a complete example, see DiscoveryDecryptionExample.java.
To instantiate a master key provider in strict mode for encrypting, this example uses the Builder.buildStrict() method. To instantiate a master key provider in discovery mode for decrypting, it uses the the Builder.buildDiscovery() method. The
Builder.buildDiscovery() method takes a DiscoveryFilter that limits the AWS Encryption SDK to AWS KMS keys in the specified AWS partition and accounts.
// Create a master key provider in strict mode for encrypting
// Replace the example alias ARN with a valid one from your AWS account.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias";
KmsMasterKeyProvider encryptingKeyProvider = KmsMasterKeyProvider.builder() .buildStrict(awsKmsKey);
// Create a master key provider in discovery mode for decrypting // Replace the example account IDs with valid values.
DiscoveryFilter accounts = new DiscoveryFilter("aws", Arrays.asList("111122223333", "444455556666"));
KmsMasterKeyProvider decryptingKeyProvider = KmsMasterKeyProvider.builder() .buildDiscovery(accounts);
Python
This example represents code in an application that uses version 1.7.x or later of the AWS Encryption SDK for Python . For a complete example, see discovery_kms_provider.py.
To create a master key provider in strict mode for encrypting, this example uses
StrictAwsKmsMasterKeyProvider. To create a master key provider in discovery mode for decrypting, it uses DiscoveryAwsKmsMasterKeyProvider with a DiscoveryFilter that limits the AWS Encryption SDK to AWS KMS keys in the specified AWS partition and accounts.
# Create a master key provider in strict mode
# Replace the example key ARN and alias ARNs with valid values from your AWS account.
key_1 = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias"
key_2 = "arn:aws:kms:us-west-2:444455556666:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
# Create a master key provider in discovery mode for decrypting
# Replace the example account IDs with valid values accounts = DiscoveryFilter(
partition="aws",
account_ids=["111122223333", "444455556666"]
)
aws_kms_master_key_provider = DiscoveryAwsKmsMasterKeyProvider(
discovery_filter=accounts )
AWS Encryption CLI
This example shows how to encrypt and decrypt using the AWS Encryption CLI version 1.7.x or later. Beginning in version 1.7.x, the --wrapping-keys parameter is required when encrypting and decrypting. The --wrapping-keys parameter supports strict mode and discovery mode. For complete examples, see the section called “Examples” (p. 107).
When encrypting, this example specifies a wrapping key, which is required. When decrypting, it explicitly chooses discovery mode by using the discovery attribute of the --wrapping-keys parameter with a value of true.
To limit the wrapping keys that the AWS Encryption SDK can use in discovery mode to those in particular AWS accounts, this example uses the discovery-partition and discovery-account attributes of the --wrapping-keys parameter. These optional attributes are valid only when the discovery attribute is set to true. You must use the partition and discovery-account attributes together; neither is valid alone.
\\ Replace the example key ARN with a valid value
$ keyAlias=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyAlias \ --metadata-output ~/metadata \ --encryption-context purpose=test \ --output .
\\ Decrypt your ciphertext
\\ Replace the example account IDs with valid values
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \ --wrapping-keys discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \ discovery-account=444455556666 \ --encryption-context purpose=test \
--metadata-output ~/metadata \ --output .
Updating AWS KMS keyrings
The AWS KMS keyrings in the AWS Encryption SDK for C (p. 59) and the AWS Encryption SDK for JavaScript (p. 77) support best practices (p. 17) by allowing you to specify wrapping keys when encrypting and decrypting. If you create a standard AWS KMS decryption keyring (p. 49), you specify wrapping keys explicitly.
When you update to versions 1.7.x and later, you can use a discovery filter to limit the wrapping keys that any AWS KMS discovery keyring (p. 49) or AWS KMS regional discovery keyring (p. 50) uses when decrypting to the wrapping keys in particular AWS accounts. Filtering a discovery keyring is an AWS Encryption SDK best practice (p. 17).
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 the section called
“Setting your commitment policy” (p. 193).
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 the section called “Updating AWS KMS master key providers” (p. 186).
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' } })
Setting your commitment policy
Key commitment (p. 10) assures that your encrypted data always decrypts to the same plaintext. To provide this security property, beginning in version 1.7.x, AWS Encryption SDK uses new algorithm suites (p. 13) with key commitment. To determine whether your data is encrypted and decrypted with key commitment, use the commitment policy (p. 11) configuration setting. Encrypting and decrypting data with key commitment is an AWS Encryption SDK best practice (p. 17).
Setting a commitment policy is an important step in migrating from version 1.7.x of the AWS Encryption SDK to versions 2.0.x and later. After setting and changing your commitment policy, be sure to test your application thoroughly before deploying it in production. For migration guidance, see How to migrate and deploy the AWS Encryption SDK (p. 185).
The commitment policy setting has three valid values in versions 2.0.x and later. In version 1.7.x, only ForbidEncryptAllowDecrypt is valid.
• ForbidEncryptAllowDecrypt — The AWS Encryption SDK cannot encrypt with key commitment. It can decrypt ciphertexts encrypted with or without key commitment.
In version 1.7.x, this is the only valid value. It ensures that you don't encrypt with key commitment until you are fully prepared to decrypt with key commitment. Setting the value explicitly prevents your commitment policy from changing automatically to require-encrypt-require-decrypt when you upgrade to version 2.0.x or later. Instead, you can migrate your commitment policy (p. 193) in stages.
• RequireEncryptAllowDecrypt — The AWS Encryption SDK must encrypt with key commitment.
It can decrypt ciphertexts encrypted with or without key commitment. This value is added in version 2.0.x.
• RequireEncryptRequireDecrypt — The AWS Encryption SDK must encrypt with key commitment.
It only decrypts ciphertexts with key commitment. This value is added in version 2.0.x. It is the default value in version 2.0.x.
In version 1.7.x, the only valid commitment policy value is ForbidEncryptAllowDecrypt. After you
In version 1.7.x, the only valid commitment policy value is ForbidEncryptAllowDecrypt. After you