Versions of the AWS Encryption CLI
Beginning in version 2.1.x, the AWS Encryption CLI includes significant new security features to support AWS Encryption SDK best practices. These new features cause breaking changes that will require updates to your commands and scripts. To make migration to version 2.1.x easier, we provide a transition version, 1.8.x that lets you prepare your commands and scripts for 2.1.x. Features that are deprecated in version 1.8.x are removed in version 2.1.x.
New security features were originally released in AWS Encryption CLI versions 1.7.x and 2.0.x.
However, AWS Encryption CLI version 1.8.x replaces version 1.7.x and AWS Encryption CLI 2.1.x replaces 2.0.x. For details, see the relevant security advisory
Which version do I use?
If a command or script will be decrypting data encrypted by an earlier version of the AWS Encryption SDK, start with version 1.8.x. Make all recommended changes before updating to version 2.1.x or later. Otherwise, you can begin with the latest available version of the AWS Encryption CLI.
Learn more
-
For detailed information about the changes and guidance for migrating to these new versions, see Migrating to version 2.0.x.
-
For descriptions of the new AWS Encryption CLI parameters and attributes, see AWS Encryption SDK CLI syntax and parameter reference.
The following lists describe the change to the AWS Encryption CLI in versions 1.8.x and 2.1.x.
Version 1.8.x changes to the AWS Encryption CLI
-
Deprecates the
--master-keys
parameter. Instead, use the--wrapping-keys
parameter. -
Adds the
--wrapping-keys
(-w
) parameter. It supports all attributes of the--master-keys
parameter. It also adds the following optional attributes, which are valid only when decrypting with AWS KMS customer master keys (CMKs).-
discovery
-
discovery-partition
-
discovery-account
For custom master key providers,
--encrypt
and --decrypt
commands require either a--wrapping-keys
parameter or a--master-keys
parameter (but not both). Also, an--encrypt
command with AWS KMS CMKs requires either a--wrapping-keys
parameter or a--master-keys
parameter (but not both).In a
--decrypt
command with AWS KMS CMKs, the--wrapping-keys
parameter is optional, but recommended, because it is required in version 2.1.x. If you use it, you must specify either the key attribute or the discovery attribute with a value oftrue
(but not both). -
-
Adds the
--commitment-policy
parameter. The only valid value isforbid-encrypt-allow-decrypt
. Theforbid-encrypt-allow-decrypt
commitment policy is used in all encrypt and decrypt commands.In version 1.8.x, when you use the
--wrapping-keys
parameter, a--commitment-policy
parameter with theforbid-encrypt-allow-decrypt
value is required. Setting the value explicitly prevents your commitment policy from changing automatically torequire-encrypt-require-decrypt
when you upgrade to version 2.1.x.
Version 2.1.x changes to the AWS Encryption CLI
-
Removes the
--master-keys
parameter. Instead, use the--wrapping-keys
parameter. -
The
--wrapping-keys
parameter is required in all encrypt and decrypt commands. You must specify either a key attribute or a discovery attribute with a value oftrue
(but not both). -
The
--commitment-policy
parameter supports the following values. For details, see Setting your commitment policy.-
forbid-encrypt-allow-decrypt
-
require-encrypt-allow-decrypt
-
require-encrypt-require decrypt
(Default)
-
-
The
--commitment-policy
parameter is optional in version 2.1.x. The default value isrequire-encrypt-require-decrypt
.