AWS Encryption SDK CLI syntax and parameter reference

Get help

To get the full AWS Encryption CLI syntax with parameter descriptions, use --help or -h.

aws-encryption-cli (--help | -h)

Get the version

To get the version number of your AWS Encryption CLI installation, use --version. Be sure to include the version when you ask questions, report problems, or share tips about using the AWS Encryption CLI.

aws-encryption-cli --version

Encrypt data

The following syntax diagram shows the parameters that an encrypt command uses.

aws-encryption-cli --encrypt
                   --input <input> [--recursive] [--decode]
                   --output <output> [--interactive] [--no-overwrite] [--suffix [<suffix>]] [--encode]
                   --wrapping-keys  [--wrapping-keys] ...
                       key=<keyID> [key=<keyID>] ...
                       [provider=<provider-name>] [region=<aws-region>] [profile=<aws-profile>]
                   --metadata-output <location> [--overwrite-metadata] | --suppress-metadata]
                   [--commitment-policy <commitment-policy>]
                   [--encryption-context <encryption_context> [<encryption_context> ...]]
                   [--max-encrypted-data-keys <integer>]
                   [--algorithm <algorithm_suite>]
                   [--caching <attributes>] 
                   [--frame-length <length>]
                   [-v | -vv | -vvv | -vvvv]
                   [--quiet]

Decrypt data

The following syntax diagram shows the parameters that a decrypt command uses.

In version 1.8.x, the --wrapping-keys parameter is optional when decrypting, but recommended. Beginning in version 2.1.x, the --wrapping-keys parameter is required when encrypting and decrypting. For AWS KMS keys, you can use the key attribute to specify wrapping keys (best practice) or set the discovery attribute to true, which doesn't limit the wrapping keys that the AWS Encryption CLI can use.

aws-encryption-cli --decrypt (or [--decrypt-unsigned]) 
                   --input <input> [--recursive] [--decode]
                   --output <output> [--interactive] [--no-overwrite]  [--suffix [<suffix>]] [--encode]           
                   --wrapping-keys  [--wrapping-keys] ...
                       [key=<keyID>] [key=<keyID>] ...
                       [discovery={true|false}] [discovery-partition=<aws-partition-name> discovery-account=<aws-account-ID> [discovery-account=<aws-account-ID>] ...] 
                       [provider=<provider-name>] [region=<aws-region>] [profile=<aws-profile>]
                   --metadata-output <location> [--overwrite-metadata] | --suppress-metadata]
                   [--commitment-policy <commitment-policy>]
                   [--encryption-context <encryption_context> [<encryption_context> ...]]
                   [--buffer]
                   [--max-encrypted-data-keys <integer>]
                   [--caching <attributes>]
                   [--max-length <length>]
                   [-v | -vv | -vvv | -vvvv]
                   [--quiet]
                   

Use configuration files

You can refer to configuration files that contain parameters and their values. This is equivalent to typing the parameters and values in the command. For an example, see How to store parameters in a configuration file.

aws-encryption-cli @<configuration_file>

# In a PowerShell console, use a backtick to escape the @.
aws-encryption-cli `@<configuration_file>

This list provides a basic description of the AWS Encryption CLI command parameters. For a complete description, see the aws-encryption-sdk-cli documentation.

--encrypt (-e)

Encrypts the input data. Every command must have an --encrypt, or --decrypt, or --decrypt-unsigned parameter.

--decrypt (-d)

Decrypts the input data. Every command must have an --encrypt, --decrypt, or --decrypt-unsigned parameter.

--decrypt-unsigned [Introduced in versions 1.9.x and 2.2.x]

The --decrypt-unsigned parameter decrypts ciphertext and ensures that messages are unsigned before decryption. Use this parameter if you used the --algorithm parameter and selected an algorithm suite without digital signing to encrypt data. If the ciphertext is signed, decryption fails.

You can use --decrypt or --decrypt-unsigned for decryption but not both.

--wrapping-keys (-w) [Introduced in version 1.8.x]

Specifies the wrapping keys (or master keys) used in encryption and decryption operations. You can use multiple --wrapping-keys parameters in each command.

Beginning in version 2.1.x, the --wrapping-keys parameter is required in encrypt and decrypt commands. In version 1.8.x, encrypt commands require either a --wrapping-keys or --master-keys parameter. In version 1.8.x decrypt commands, a --wrapping-keys parameter is optional but recommended.

When using a custom master key provider, encrypt and decrypt commands require key and provider attributes. When using AWS KMS keys, encrypt commands require a key attribute. Decrypt commands require a key attribute or a discovery attribute with a value of true (but not both). Using the key attribute when decrypting is an AWS Encryption SDK best practice. It is particularly important if you're decrypting batches of unfamiliar messages, such as those in an Amazon S3 bucket or an Amazon SQS queue.

For an example showing how to use AWS KMS multi-Region keys as wrapping keys, see Using multi-Region AWS KMS keys.

Attributes: The value of the --wrapping-keys parameter consists of the following attributes. The format is attribute_name=value.

key

Identifies the wrapping key used in the operation. The format is a key=ID pair. You can specify multiple key attributes in each --wrapping-keys parameter value.

• Encrypt commands: All encrypt commands require the key attribute . When you use an AWS KMS key in an encrypt command, the value of the key attribute can be a key ID, key ARN, an alias name, or an alias ARN. For descriptions of the AWS KMS key identifiers, see Key identifiers in the AWS Key Management Service Developer Guide.

• Decrypt commands: When decrypting with AWS KMS keys, the --wrapping-keys parameter requires a key attribute with a key ARN value or a discovery attribute with a value of true (but not both). Using the key attribute is an AWS Encryption SDK best practice. When decrypting with a custom master key provider, the key attribute is required.

  Note

  To specify an AWS KMS wrapping key in a decrypt command, the value of the key attribute must be a key ARN. If you use a key ID, alias name, or alias ARN, the AWS Encryption CLI does not recognize the wrapping key.

You can specify multiple key attributes in each --wrapping-keys parameter value. However, any provider, region, and profile attributes in a --wrapping-keys parameter apply to all wrapping keys in that parameter value. To specify wrapping keys with different attribute values, use multiple --wrapping-keys parameters in the command.

discovery

Allows the AWS Encryption CLI to use any AWS KMS key to decrypt the message. The discovery value can be true or false. The default value is false. The discovery attribute is valid only in decrypt commands and only when the master key provider is AWS KMS.

When decrypting with AWS KMS keys, the --wrapping-keys parameter requires a key attribute or a discovery attribute with a value of true (but not both). If you use the key attribute, you can use a discovery attribute with a value of false to explicitly reject discovery.

• False (default) — When the discovery attribute isn't specified or its value is false, the AWS Encryption CLI decrypts the message using only the AWS KMS keys specified by the key attribute of the --wrapping-keys parameter. If you don't specify a key attribute when discovery is false, the decrypt command fails. This value supports an AWS Encryption CLI best practice.

• True — When the value of the discovery attribute is true, the AWS Encryption CLI gets the AWS KMS keys from metadata in the encrypted message, and uses those AWS KMS keys to decrypt the message. The discovery attribute with a value of true behaves like versions of the AWS Encryption CLI before version 1.8.x that didn't permit you to specify a wrapping key when decrypting. However, your intent to use any AWS KMS key is explicit. If you specify a key attribute when discovery is true, the decrypt command fails.

  The true value might cause the AWS Encryption CLI to use AWS KMS keys in different AWS accounts and Regions, or attempt to use AWS KMS keys that the user isn't authorized to use.

When discovery is true, it's a best practice to use the discovery-partition and discovery-account attributes to limit the AWS KMS keys used to those in the AWS accounts you specify.

discovery-account

Limits the AWS KMS keys used for decrypting to those in the specified AWS account. The only valid value for this attribute is an AWS account ID.

This attribute is optional and valid only in decrypt commands with AWS KMS keys where the discovery attribute is set to true and the discovery-partition attribute is specified.

Each discovery-account attribute takes just one AWS account ID, but you can specify multiple discovery-account attributes in the same --wrapping-keys parameter. All accounts specified in a given --wrapping-keys parameter must be in the specified AWS partition.

discovery-partition

Specifies the AWS partition for the accounts in the discovery-account attribute. Its value must be an AWS partition, such as aws, aws-cn, or aws-gov-cloud. For information, see Amazon Resource Names in the AWS General Reference.

This attribute is required when you use the discovery-account attribute. You can specify only one discovery-partition attribute in each --wrapping keys parameter. To specify AWS accounts in multiple partitions, use an additional --wrapping-keys parameter.

provider

Identifies the master key provider. The format is a provider=ID pair. The default value, aws-kms, represents AWS KMS. This attribute is required only when the master key provider is not AWS KMS.

region

Identifies the AWS Region of an AWS KMS key. This attribute is valid only for AWS KMS keys. It is used only when the key identifier does not specify a Region; otherwise, it is ignored. When it is used, it overrides the default Region in the AWS CLI named profile.

profile

Identifies an AWS CLI named profile. This attribute is valid only for AWS KMS keys. The Region in the profile is used only when the key identifier does not specify a Region and there is no region attribute in the command.

--input (-i)

Specifies the location of the data to encrypt or decrypt. This parameter is required. The value can be a path to a file or directory, or a file name pattern. If you are piping input to the command (stdin), use -.

If the input does not exist, the command completes successfully without error or warning.

--recursive (-r, -R)

Performs the operation on files in the input directory and its subdirectories. This parameter is required when the value of --input is a directory.

--decode

Decodes Base64-encoded input.

If you are decrypting a message that was encrypted and then encoded, you must decode the message before decrypting it. This parameter does that for you.

For example, if you used the --encode parameter in an encrypt command, use the --decode parameter in the corresponding decrypt command. You can also use this parameter to decode Base64-encoded input before you encrypt it.

--output (-o)

Specifies a destination for the output. This parameter is required. The value can be a file name, an existing directory, or -, which writes output to the command line (stdout).

If the specified output directory does not exist, the command fails. If the input contains subdirectories, the AWS Encryption CLI reproduces the subdirectories under the output directory that you specify.

By default, the AWS Encryption CLI overwrites files with the same name. To change that behavior, use the --interactive or --no-overwrite parameters. To suppress the overwrite warning, use the --quiet parameter.

Note

If a command that would overwrite an output file fails, the output file is deleted.

--interactive

Prompts before overwriting the file.

--no-overwrite

Does not overwrite files. Instead, if the output file exists, the AWS Encryption CLI skips the corresponding input.

--suffix

Specifies a custom file name suffix for files that the AWS Encryption CLI creates. To indicate no suffix, use the parameter with no value (--suffix).

By default, when the --output parameter does not specify a file name, the output file name has the same name as the input file name plus the suffix. The suffix for encrypt commands is .encrypted. The suffix for decrypt commands is .decrypted.

--encode

Applies Base64 (binary to text) encoding to the output. Encoding prevents the shell host program from misinterpreting non-ASCII characters in output text.

Use this parameter when writing encrypted output to stdout (--output -), especially in a PowerShell console, even when you are piping the output to another command or saving it in a variable.

--metadata-output