Versions of the AWS Encryption CLI - AWS Encryption SDK
Version 1.8.x changes to the AWS Encryption CLIVersion 2.1.x changes to the AWS Encryption CLIVersion 1.9.x and 2.2.x changes to the AWS Encryption CLIVersion 3.0.x changes to the AWS Encryption CLI

Versions of the AWS Encryption CLI

We recommend that you use the latest version of the AWS Encryption CLI.

Note

Versions of the AWS Encryption CLI earlier than 4.0.0 are in the end-of-support phase.

You can safely update from version 2.1.x and later to the latest version of the AWS Encryption CLI without any code or data changes. However, new security features introduced in version 2.1.x are not backward-compatible. To update from version 1.7.x or earlier, you must first update to the latest 1.x version of the AWS Encryption CLI. For details, see Migrating your AWS Encryption SDK.

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, migrate first to the latest version of the AWS Encryption CLI. Make all recommended changes before updating to version 2.1.x or later. For details, see Migrating your AWS Encryption SDK.

Learn more

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 keys.

    • 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 keys requires either a --wrapping-keys parameter or a --master-keys parameter (but not both).

    In a --decrypt command with AWS KMS keys, 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

Version 3.0.x changes to the AWS Encryption CLI