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.

Note

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 in the aws-encryption-sdk-cli repository on GitHub.

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 of true (but not both).

• Adds the --commitment-policy parameter. The only valid value is forbid-encrypt-allow-decrypt. The forbid-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 the forbid-encrypt-allow-decrypt value is required. Setting the value explicitly prevents your commitment policy from changing automatically to require-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 of true (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 is require-encrypt-require-decrypt.