AWS Encryption SDK CLI 语法和参数参考 - AWS Encryption SDK
AWS Encryption CLI 语法AWS Encryption CLI 命令行参数高级参数

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AWS Encryption SDK CLI 语法和参数参考

本主题提供了语法图表和简要参数描述以帮助您使用 AWS Encryption SDK命令行界面 (CLI)。有关包装密钥和其他参数的帮助，请参阅 如何使用 AWS Encryption CLI。有关示例，请参阅 AWS Encryption CLI 的示例。有关完整文档，请参阅阅读文档。

AWS Encryption CLI 语法

这些 AWS Encryption CLI 语法图表显示您使用 AWS Encryption CLI 执行的每个任务的语法。这些语法代表 AWS Encryption CLI 版本 2.1.x 及更高版本中的推荐语法。

新的安全功能最初是在 AWS Encryption CLI 版本 1.7.x 和 2.0.x 中发布的。但是，AWS Encryption CLI 版本 1.8.x 取代版本 1.7.x，AWS Encryption CLI 2.1.x 取代 2.0.x。有关详细信息，请参阅 GitHub 上的 aws-encryption-sdk-cli 存储库中的相关安全通告。

注意

除非在参数描述中注明，否则每个参数或属性只能在每个命令中使用一次。

如果您使用参数不支持的属性，AWS Encryption CLI 会忽略该不支持的属性，而不会出现警告或错误。

获取帮助

要获取完整 AWS Encryption CLI 语法和参数说明，请使用 --help 或 -h。

aws-encryption-cli (--help | -h)
获取版本

要获取您的 AWS Encryption CLI 安装的版本号，请使用 --version。在您提出问题、报告故障或分享有关使用 AWS Encryption CLI 的技巧时，请务必包含版本。

aws-encryption-cli --version
加密数据

以下语法图表显示 encrypt 命令使用的参数。

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 命令使用的参数。

在版本 1.8.x 中，--wrapping-keys 参数在解密时是可选的，但建议使用。从版本 2.1.x 开始，加密和解密时需要使用 --wrapping-keys 参数。对于 AWS KMS keys，您可以使用 key 属性来指定包装密钥（最佳实践），也可以将 discovery 属性设置为 true，这不会限制 AWS Encryption CLI 可以使用的包装密钥。

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]
使用配置文件

您可以引用包含参数及其值的配置文件。这相当于在命令中键入参数和值。有关示例，请参阅 如何在配置文件中存储参数。

aws-encryption-cli @<configuration_file>

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

AWS Encryption CLI 命令行参数

该列表提供 AWS Encryption CLI 命令参数的基本说明。有关完整说明，请参阅 aws-encryption-sdk-cli 文档。

--encrypt (-e)

加密输入数据。每个命令必须具有一个 --encrypt 或 --decrypt 或 --decrypt-unsigned 参数。

--decrypt (-d)

解密输入数据。每个命令必须具有一个 --encrypt、--decrypt 或 --decrypt-unsigned 参数。

--decrypt-unsigned [在版本 1.9.x 和 2.2.x 中引入。]

--decrypt-unsigned 参数对加密文字进行解密并确保消息在解密之前未签名。如果您使用 --algorithm 参数并选择了不带数字签名的算法套件来加密数据，请使用此参数。如果加密文字已签名，则解密失败。

您可以使用 --decrypt 或 --decrypt-unsigned 进行解密，但不能同时使用两者。

--wrapping-keys (-w) [在版本 1.8.x 中引入。]

指定在加密和解密操作中使用的包装密钥（或主密钥）。您可以在每个命令中使用多个 --wrapping-keys 参数。

从版本 2.1.x 开始，在加密和解密命令中需要使用 --wrapping-keys 参数。在版本 1.8.x 中，加密命令需要 --wrapping-keys 或 --master-keys 参数。在版本 1.8.x 解密命令中，--wrapping-keys 参数是可选的，但建议使用。

使用自定义主密钥提供程序时，加密和解密命令需要使用 key 和 provider 属性。使用 AWS KMS keys 时，加密命令需要使用 key 属性。解密命令需要使用 key 属性或值为 true 的 discovery 属性（但不能两者同时使用）。解密时使用 key 属性是 AWS Encryption SDK 最佳实践。如果您要解密多批陌生消息，例如 Amazon S3 存储桶或 Amazon SQS 队列中的消息，这一点尤其重要。

有关展示如何使用 AWS KMS 多区域密钥作为包装密钥的示例，请参阅 使用多区域 AWS KMS keys。

属性：--wrapping-keys 参数值包含以下属性。格式为 attribute_name=value。

key

标识操作中使用的包装密钥。格式为 key=ID 对。您可以在每个 --wrapping-keys 参数值中指定多个 key 属性。

  • 加密命令：所有加密命令都需要使用 key 属性。在加密命令中使用 AWS KMS key 时，key 属性的值可能是密钥 ID、密钥 ARN、别名名称或别名 ARN。有关 AWS KMS 密钥标识符的描述，请参阅《AWS Key Management Service 开发人员指南》中的密钥标识符。

  • 解密命令：使用 AWS KMS keys 解密时，--wrapping-keys 参数需要使用值为密钥 ARN 的 key 属性或值为 true 的 discovery 属性（但不能两者同时使用）。使用 key 属性是 AWS Encryption SDK 最佳实践。使用自定义主密钥提供程序解密时，需要使用 key 属性。

    注意

    要在解密命令中指定 AWS KMS 包装密钥，key 属性的值必须是密钥 ARN。如果使用密钥 ID、别名名称或别名 ARN，则 AWS Encryption CLI 无法识别包装密钥。

您可以在每个 --wrapping-keys 参数值中指定多个 key 属性。不过，--wrapping-keys 参数中的任何 provider、region 和 profile 属性适用于该参数值中的所有包装密钥。要指定具有不同属性值的包装密钥，请在命令中使用多个 --wrapping-keys 参数。

discovery

允许 AWS Encryption CLI 使用任何 AWS KMS key 来解密消息。discovery 值可以是 true 或 false。默认值为 false。discovery 属性仅在加密命令中有效，并且仅在主密钥提供程序为 AWS KMS 时有效。

使用 AWS KMS keys 解密时，--wrapping-keys 参数需要使用 key 属性或值为 true 的 discovery 属性（但不能两者同时使用）。如果您使用 key 属性，则可以使用值为 false 的 discovery 属性来明确拒绝发现。

  • False（默认）– 当未指定 discovery 属性或其值为 false 时，AWS Encryption CLI 仅使用 --wrapping-keys 参数的 key 属性指定的 AWS KMS keys 来解密消息。如果在 discovery 为 false 时没有指定 key 属性，则解密命令将失败。此值支持 AWS Encryption CLI 最佳实践。

  • True – 当 discovery 属性的值为 true 时，AWS Encryption CLI 会从加密消息中的元数据中获取 AWS KMS keys，并使用这些 AWS KMS keys 来解密消息。值为 true 的 discovery 属性的行为类似于版本 1.8.x 之前的 AWS Encryption CLI 版本，不允许您在解密时指定包装密钥。但是，您使用任何 AWS KMS key 的意图是明确的。如果在 discovery 为 true 时指定了 key 属性，则解密命令将失败。

    true 值可能会导致 AWS Encryption CLI 在不同的 AWS 账户 和区域中使用 AWS KMS keys，或者尝试使用用户无权使用的 AWS KMS keys。

当 discovery 为 true 时，最佳实践是使用 discovery-partition 和 discovery-account 属性将使用的 AWS KMS keys 限制为您指定的 AWS 账户 中的密钥。

discovery-account

将用于解密的 AWS KMS keys 限制为指定的 AWS 账户 中的密钥。此属性的唯一有效值是 AWS 账户 ID。

此属性是可选的，仅在 AWS KMS keys 的 discovery 属性设置为 true 且指定了 discovery-partition 属性的解密命令中有效。

每个 discovery-account 属性只需要一个 AWS 账户 ID，但您可以在同一个 --wrapping-keys 参数中指定多个 discovery-account 属性。在给定的 --wrapping-keys 参数中指定的所有账户都必须位于指定的 AWS 分区中。

discovery-partition

在 discovery-account 属性中为账户指定 AWS 分区。其值必须是 AWS 分区，例如 aws、aws-cn 或 aws-gov-cloud。有关更多信息，请参阅《AWS 一般参考》 中的 Amazon 资源名称。

当您使用 discovery-account 属性时，需要使用此属性。每个 --wrapping keys 参数中只能指定一个 discovery-partition 属性。要在多个分区中指定 AWS 账户，请使用其他 --wrapping-keys 参数。

provider

指定主密钥提供程序。格式为 provider=ID 对。默认值 aws-kms 表示 AWS KMS。只有在主密钥提供程序不是 AWS KMS 时，才需要使用该属性。

区域

标识 AWS KMS key 的 AWS 区域。该属性仅对 AWS KMS keys 有效。只有在密钥标识符未指定区域时，才会使用该属性，否则，将忽略该属性。在使用该属性时，它覆盖 AWS CLI 命名配置文件中的默认区域。

profile

标识 AWS CLI 命名配置文件。该属性仅对 AWS KMS keys 有效。只有在密钥标识符未指定区域并且在命令中不包含 region 属性时，才会使用配置文件中的区域。

--input (-i)

指定要加密或解密的数据的位置。此参数为必需参数。该值可以是文件或目录的路径，也可以是文件名模式。如果通过管道将输入发送到命令 (stdin)，请使用 -。

如果输入不存在，该命令将成功完成，而不会显示错误或警告。

--recursive (-r, -R)

对输入目录及其子目录中的文件执行操作。在 --input 值为目录时，需要使用该参数。

--decode

解码 Base64 编码的输入。

如果要解密已加密并随后编码的消息，您必须在解密该消息之前对其进行解码。该参数为您执行此操作。

例如，如果在 encrypt 命令中使用 --encode 参数，请在相应的 decrypt 命令中使用 --decode 参数。您也可以在加密 Base64 编码的输入之前使用该参数对其进行解码。

--output (-o)

指定输出的目标。此参数为必需参数。该值可以是文件名、现有目录或 -，后者将输出写入到命令行 (stdout)。

如果指定的输出目录不存在，该命令将失败。如果输入包含子目录，AWS Encryption CLI 将在指定的输出目录中重新生成这些子目录。

默认情况下，AWS Encryption CLI 覆盖具有相同名称的文件。要更改该行为，请使用 --interactive 或 --no-overwrite 参数。要禁止显示覆盖警告，请使用 --quiet 参数。

注意

如果覆盖输出文件的命令失败，则会删除输出文件。

--interactive

在覆盖文件之前提示。

--no-overwrite

不覆盖文件。如果输出文件存在，AWS Encryption CLI 将跳过相应的输入。

--suffix

为 AWS Encryption CLI 创建的文件指定自定义文件名后缀。要指示没有后缀，请使用没有值的参数 (--suffix)。

默认情况下，在 --output 参数未指定文件名时，输出文件名与输入文件名相同并加上后缀。encrypt 命令的后缀为 .encrypted。decrypt 命令的后缀为 .decrypted。

--encode

将 Base64（二进制到文本）编码应用于输出。编码可以防止 shell 主机程序错误地解释输出文本中的非 ASCII 字符。

在将加密的输出写入到 stdout (--output -) 时，请使用该参数（特别是在 PowerShell 控制台中），即使通过管道将输出发送到另一个命令或将其保存在变量中。

--metadata-output

指定有关加密操作的元数据的位置。请输入路径和文件名。如果目录不存在，该命令将失败。要将元数据写入到命令行 (stdout) 中，请使用 -。

您无法在同一命令中将命令输出 (--output) 和元数据输出 (--metadata-output) 写入到 stdout。此外，如果 --input 或 --output 值为目录（没有文件名），您无法将元数据输出写入到同一目录或该目录的任何子目录中。

如果指定一个现有文件，AWS Encryption CLI 默认将新的元数据记录附加到该文件中的任何内容后面。通过使用该功能，您可以创建一个包含所有加密操作的元数据的文件。要覆盖现有文件中的内容，请使用 --overwrite-metadata 参数。

对于命令执行的每个加密或解密操作，AWS Encryption CLI 返回一个 JSON 格式的元数据记录。每个元数据记录包含输入和输出文件的完整路径、加密上下文、算法套件以及其他有价值的信息，您可以使用这些信息查看操作并验证它是否符合您的安全标准。

--overwrite-metadata

覆盖元数据输出文件中的内容。默认情况下，--metadata-output 参数将元数据附加到文件中的任何现有内容后面。

--suppress-metadata (-S)

禁止显示有关加密或解密操作的元数据。

--commitment-policy

指定加密和解密命令的承诺策略。承诺策略决定您的消息是否使用密钥承诺安全功能进行加密和解密。

--commitment-policy 参数在版本 1.8.x 中引入。该参数在加密和解密命令中有效。

在版本 1.8.x 中，AWS Encryption CLI 对所有加密和解密操作使用 forbid-encrypt-allow-decrypt 承诺策略。当您在加密或解密命令中使用 --wrapping-keys 参数时，需要使用具有 forbid-encrypt-allow-decrypt 值的 --commitment-policy 参数。如果您不使用 --wrapping-keys 参数，则 --commitment-policy 参数无效。明确设置承诺策略可防止您的承诺策略在升级到版本 2.1.x 时自动更改为 require-encrypt-require-decrypt

从版本 2.1.x 开始，支持所有承诺策略值。--commitment-policy 参数是可选的，默认值为 require-encrypt-require-decrypt。

此参数具有以下值：

  • forbid-encrypt-allow-decrypt – 无法使用密钥承诺进行加密。可以解密使用或不使用密钥承诺加密的加密文字。

    在版本 1.8.x 中，这是唯一的有效值。AWS Encryption CLI 对所有加密和解密操作使用 forbid-encrypt-allow-decrypt 承诺策略。

  • require-encrypt-allow-decrypt – 仅使用密钥承诺进行加密。使用和不使用密钥承诺进行解密。此值在版本 2.1.x 中引入。

  • require-encrypt-require-decrypt（默认）– 仅使用密钥承诺进行加密和解密。此值在版本 2.1.x 中引入。在版本 2.1.x 和更高版本中，这是默认值。使用此值，AWS Encryption CLI 将不会解密使用 AWS Encryption SDK 早期版本加密的任何加密文字。

有关设置承诺策略的详细信息，请参阅 迁移 AWS Encryption SDK。

--encryption-context (-c)

为操作指定加密上下文。该参数不是必需的，但建议使用。

  • 在 --encrypt 命令中，输入一个或多个 name=value 对。请使用空格分隔这些对。

  • 在 --decrypt 命令中，输入 name=value 对和/或没有值的 name 元素。

如果 name 对中的 value 或 name=value 包含空格或特殊字符，请将整个对用引号引起来。例如，--encryption-context "department=software development"。

--buffer (-b) [在版本 1.9.x 和 2.2.x 中引入。]

仅在处理完所有输入之后返回明文，包括验证数字签名（如果存在）。

--max-encrypted-data-keys [在版本 1.9.x 和 2.2.x 中引入。]

指定加密消息中加密数据密钥的最大数量。此参数为可选项。

有效值为 1-65535。如果省略此参数，则 AWS Encryption CLI 不强制执行任何最大值。加密消息最多可以容纳 65535（2^16-1）个加密数据密钥。

您可以在加密命令中使用此参数来防止出现格式错误的消息。您可以在解密命令中使用该参数检测恶意消息，并避免使用大量无法解密的加密数据密钥解密消息。有关详细信息和示例，请参阅限制加密数据密钥。

--help (-h)

在命令行中输出用法和语法。

--version

获取 AWS Encryption CLI 的版本。

-v | -vv | -vvv | -vvvv

显示详细信息、警告和调试消息。输出中的详细信息随参数中的 v 数量而增加。最详细的设置（-vvvv）从 AWS Encryption CLI 及其使用的所有组件中返回调试级别数据。

--quiet (-q)

禁止显示警告消息，例如，在覆盖输出文件时显示的消息。

--master-keys (-m) [已弃用]
注意

--master-keys 参数在版本 1.8.x 中弃用并在版本 2.1.x 中删除。请改用 --wrapping-keys 参数。

指定在加密和解密操作中使用的主密钥。您可以在每个命令中使用多个主密钥参数。

需要在 encrypt 命令中使用 --master-keys 参数。只有在使用自定义（非 AWS KMS）主密钥提供程序时，才需要在解密命令中使用该参数。

属性：--master-keys 参数值包含以下属性。格式为 attribute_name=value。

key

标识操作中使用的包装密钥。格式为 key=ID 对。需要在所有 encrypt 命令中使用 key 属性。

在加密命令中使用 AWS KMS key 时，key 属性的值可能是密钥 ID、密钥 ARN、别名名称或别名 ARN。有关 AWS KMS 密钥标识符的详细信息，请参阅《AWS Key Management Service 开发者指南》中的密钥标识符。

在主密钥提供程序不是 AWS KMS 时，需要在解密命令中使用 key 属性。在解密根据 AWS KMS key 加密的数据的命令中，不允许使用 key 属性。

您可以在每个 --master-keys 参数值中指定多个 key 属性。不过，任何 provider、region 和 profile 属性适用于该参数值中的所有主密钥。要指定具有不同属性值的主密钥，请在命令中使用多个 --master-keys 参数。

provider

指定主密钥提供程序。格式为 provider=ID 对。默认值 aws-kms 表示 AWS KMS。只有在主密钥提供程序不是 AWS KMS 时，才需要使用该属性。

区域

标识 AWS KMS key 的 AWS 区域。该属性仅对 AWS KMS keys 有效。只有在密钥标识符未指定区域时，才会使用该属性，否则，将忽略该属性。在使用该属性时，它覆盖 AWS CLI 命名配置文件中的默认区域。

profile

标识 AWS CLI 命名配置文件。该属性仅对 AWS KMS keys 有效。只有在密钥标识符未指定区域并且在命令中不包含 region 属性时，才会使用配置文件中的区域。

高级参数

--algorithm

指定备用的算法套件。该参数是可选的，仅在 encrypt 命令中有效。

如果省略此参数，则 AWS Encryption CLI 将使用版本 1.8.x 中引入的 AWS Encryption SDK 的默认算法套件之一。两种默认算法都使用带有 HKDF、ECDSA 签名和 256 位加密密钥的 AES-GCM。一种算法使用密钥承诺；一种不使用。默认算法套件的选择由命令的承诺策略决定。

建议将默认算法套件用于大多数加密操作。有关有效值的列表，请参阅 Read the Docs 中 algorithm 参数的值。

--frame-length

创建具有指定帧长度的输出。该参数是可选的，仅在 encrypt 命令中有效。

请输入一个值（字节）。有效值为 0 和 1-2^31-1。值 0 表示非帧数据。默认值为 4096（字节）。

注意

尽可能使用帧数据。AWS Encryption SDK 仅支持传统用途的非帧数据。AWS Encryption SDK 的某些语言实现仍然可以生成非帧加密文字。所有支持的语言实现都可以解密成帧和非帧加密文字。

--max-length

指示要从加密的消息中读取的最大帧大小（或非帧消息的最大内容长度），以字节为单位。该参数是可选的，仅在 decrypt 命令中有效。它旨在防止您解密非常大的恶意密文。

请输入一个值（字节）。如果省略此参数，则解密时 AWS Encryption SDK 不限制帧大小。

--caching

启用数据密钥缓存功能，该功能重用数据密钥，而不是为每个输入文件生成新的数据密钥。该参数支持高级方案。在使用该功能之前，请务必阅读数据密钥缓存文档。

--caching 参数具有以下属性。

capacity（必需）

确定缓存中的最大条目数。

最小值为 1。没有最大值。

max_age（必需）

确定使用缓存条目的时间长度（秒），从将条目添加到缓存时算起。

请输入一个大于 0 的值。没有最大值。

max_messages_encrypted（可选）

确定缓存的条目可以加密的最大消息数。

有效值为 1-2^32。默认值为 2^32（消息）。

max_bytes_encrypted（可选）

确定缓存的条目可以加密的最大字节数。

有效值为 0 和 1-2^63-1。默认值为 2^63-1（消息）。在使用值 0 时，您只能在加密空消息字符串时使用数据密钥缓存。