Versions of the AWS Encryption CLI

We recommend that you use the latest version of the AWS Encryption CLI. If you're using a version of the AWS Encryption CLI older than 2.1.x, we recommend that you upgrade to version 1.8.x and then to version 2.1.x as soon as possible.

In version 2.1.x, the AWS Encryption CLI introduces support for significant new security features that meet 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.

For information about significant versions of the AWS Encryption SDK, see Versions of the AWS Encryption SDK.

Which version do I use?

If you're new to the AWS Encryption CLI, use the latest version.

To decrypt data encrypted by a version of the AWS Encryption SDK earlier than version 1.7.x, 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.

Version 1.9.x and 2.2.x changes to the AWS Encryption CLI

• Adds the --decrypt-unsigned parameter. For details, see Version 2.2.x.

• Adds the --buffer parameter. For details, see Version 2.2.x.

• Adds the --max-encrypted-data-keys parameter. For details, see Limit encrypted data keys.

Version 3.0.x changes to the AWS Encryption CLI

• Adds support for AWS KMS multi-Region keys. For details, see Use multi-Region KMS keys.