如何使用 AWS Encryption CLI - AWS Encryption SDK
如何加密和解密数据如何指定包装密钥如何提供输入如何指定输出位置如何使用加密上下文如何指定承诺策略如何在配置文件中存储参数

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

如何使用 AWS Encryption CLI

本主题介绍了如何在 AWS Encryption CLI 中使用参数。有关示例，请参阅 AWS Encryption CLI 的示例。有关完整文档，请参阅阅读文档。这些示例中显示的语法适用于 AWS Encryption CLI 版本 2.1.x 及更高版本。

注意

AWS Encryption CLI 4.0.0 之前的版本处于终止支持阶段。

您无需更改任何代码或数据即可安全地从 AWS Encryption CLI 版本 2.1.x 及更高版本更新为最新版本。但是，版本 2.1.x 中引入了新的安全功能，不向后兼容。要从版本 1.7.x 或更早版本更新，必须先更新为 AWS Encryption CLI 最新的 1.x 版本。有关详细信息，请参阅 迁移 AWS Encryption SDK。

新的安全功能最初是在 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 KMS 多区域密钥的示例，请参阅 使用多区域 AWS KMS keys。

如何加密和解密数据

AWS Encryption CLI 使用 AWS Encryption SDK 的功能轻松且安全地加密和解密数据。

注意

--master-keys 参数在 AWS Encryption CLI 版本 1.8.x 中弃用并在版本 2.1.x 中删除。请改用 --wrapping-keys 参数。从版本 2.1.x 开始，加密和解密时需要使用 --wrapping-keys 参数。有关详细信息，请参阅 AWS Encryption SDK CLI 语法和参数参考。

  • 在 AWS Encryption CLI 中加密数据时，需要指定您的明文数据和包装密钥（或主密钥），例如 AWS Key Management Service（AWS KMS）中的 AWS KMS key。如果使用自定义主密钥提供程序，您还需要指定该提供程序。您还需要指定加密的消息以及有关加密操作的元数据的输出位置。加密上下文是可选的，但建议使用。

    在版本 1.8.x 中，使用 --wrapping-keys 参数时需要使用 --commitment-policy 参数；否则该参数无效。从版本 2.1.x 开始，--commitment-policy 参数是可选的，但建议使用。

    aws-encryption-cli --encrypt --input myPlaintextData \
                   --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \
                   --output myEncryptedMessage \
                   --metadata-output ~/metadata \
                   --encryption-context purpose=test \
                   --commitment-policy require-encrypt-require-decrypt

    AWS Encryption CLI 使用唯一的数据密钥对您的数据进行加密。然后，对您指定的包装密钥下的数据密钥进行加密。它返回加密的消息以及有关该操作的元数据。加密的消息包含加密的数据（密文）以及数据密钥的加密副本。您不必担心数据密钥存储、管理或丢失问题。

     

  • 在解密数据时，您将传入加密的消息、可选的加密上下文以及明文输出和元数据位置。您还可以指定 AWS Encryption CLI 可以用来解密消息的包装密钥，或者指示 AWS Encryption CLI 可以使用任何对消息进行加密的包装密钥。

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

    解密时，您可以使用 --wrapping-keys 参数的 key 属性来指定用于解密数据的包装密钥。在解密时指定 AWS KMS 包装密钥是可选的，但这是一种最佳实践，可以防止您使用本来不打算使用的密钥。如果使用自定义主密钥提供程序，您必须指定该提供程序和包装密钥。

    如果您不使用 key 属性，则必须将 --wrapping-keys 参数的 discovery 属性设置为 true，这样，AWS Encryption CLI 就可以使用加密消息的任何包装密钥进行解密。

    最佳实践是使用 --max-encrypted-data-keys 参数来避免使用过多的加密数据密钥解密格式错误的消息。指定预期的加密数据密钥数量（加密中使用的每个包装密钥各一个）或合理的最大值（例如 5）。有关详细信息，请参阅 限制加密数据密钥。

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

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

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

    aws-encryption-cli --decrypt --input myEncryptedMessage \
                   --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \
                   --output myPlaintextData \
                   --metadata-output ~/metadata \
                   --max-encrypted-data-keys 1 \
                   --buffer \
                   --encryption-context purpose=test \ 
                   --commitment-policy require-encrypt-require-decrypt

    AWS Encryption CLI 使用包装密钥解密加密的消息中的数据密钥。然后，它使用数据密钥解密数据。它返回明文数据以及有关该操作的元数据。

如何指定包装密钥

在 AWS Encryption CLI 中加密数据时，需要至少指定一个包装密钥（或主密钥）。您可以在 AWS Key Management Service（AWS KMS）中使用 AWS KMS keys、来自自定义主密钥提供程序的包装密钥，或者同时使用两者。自定义主密钥提供程序可以是任何兼容的 Python 主密钥提供程序。

要在版本 1.8.x 及以后的版本中指定包装密钥，请使用 --wrapping-keys 参数 (-w)。该参数的值是具有 attribute=value 格式的属性集合。您使用的属性取决于主密钥提供程序和命令。

  • AWS KMS。在加密命令中，您必须指定具有 key 属性的 --wrapping-keys 参数。从版本 2.1.x 开始，解密命令中也需要使用 --wrapping-keys 参数。解密时，--wrapping-keys 参数必须具有值为 true 的 key 属性或 discovery 属性（但不能两者同时使用）。其他属性是可选的。

  • 自定义主密钥提供程序。您必须在每个命令中指定 --wrapping-keys 参数。该参数值必须具有 key 和 provider 属性。

您可以在同一命令中包含多个 --wrapping-keys 参数和多个 key 属性。

包装密钥参数属性

--wrapping-keys 参数值包含以下属性及其值。所有加密命令都需要一个 --wrapping-keys 参数（或 --master-keys 参数）。从版本 2.1.x 开始，解密时也需要 --wrapping-keys 参数。

如果属性名称或值包含空格或特殊字符，请将名称和值用引号引起来。例如，--wrapping-keys key=12345 "provider=my cool provider"。

密钥：指定包装密钥

使用 key 属性识别包装密钥。加密时，该值可以是主密钥提供程序识别的任何密钥标识符。

--wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab

在加密命令中，您必须至少包含一个 key 属性和值。要在多个包装密钥下加密您的数据密钥，请使用多个 key 属性。

aws-encryption-cli --encrypt --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab key=1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d

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

aws-encryption-cli --encrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias

在使用自定义主密钥提供程序的 decrypt 命令中，需要使用 key 和 provider 属性。

\\ Custom master key provider
aws-encryption-cli --decrypt --wrapping-keys provider='myProvider' key='100101'

在使用 AWS KMS 的解密命令中，您可以使用 key 属性指定用于解密的 AWS KMS keys，或者使用值为 true 的 discovery 属性，该属性指示 AWS Encryption CLI 使用任何用于加密消息的 AWS KMS key。如果指定 AWS KMS key，则该密钥必须是用于加密消息的包装密钥之一。

指定包装密钥是 AWS Encryption SDK 最佳实践。这可以确保您使用打算使用的 AWS KMS key。

在解密命令中，key 属性的值必须是密钥 ARN。

\\ AWS KMS key
aws-encryption-cli --decrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
发现：解密时使用任何 AWS KMS key

如果您在解密时不需要限制要使用的 AWS KMS keys，则可以使用值为 true 的 discovery 属性。true 值允许 AWS Encryption CLI 使用任何加密消息的 AWS KMS key 进行解密。如果不指定 discovery 属性，则发现为 false（默认值）。discovery 属性仅在解密命令中有效，并且仅当消息使用 AWS KMS keys 加密时才有效。

值为 true 的 discovery 属性可以替代使用 key 属性指定 AWS KMS keys。解密使用 AWS KMS keys 加密的消息时，每个 --wrapping-keys 参数都必须有一个 key 属性或一个值为 true 的 discovery 属性，但不能两者同时使用。

当 discovery 为 true 时，最佳实践是使用 discovery-partition 和 discovery-account 属性将使用的 AWS KMS keys 限制在您指定的 AWS 账户 内。在以下示例中，discovery 属性允许 AWS Encryption CLI 使用指定的 AWS KMS key 中的任何 AWS 账户。

aws-encryption-cli --decrypt --wrapping-keys \
    discovery=true \
    discovery-partition=aws \
    discovery-account=111122223333 \
    discovery-account=444455556666
提供程序：指定主密钥提供程序

provider 属性指定主密钥提供程序。默认值为 aws-kms，它表示 AWS KMS。如果使用不同的主密钥提供程序，则需要使用 provider 属性。

--wrapping-keys key=12345 provider=my_custom_provider

有关使用自定义（非 AWS KMS）主密钥提供程序的更多信息，请参阅 AWS Encryption CLI 存储库的 README 文件中的高级配置主题。

区域：指定 AWS 区域

使用 region 属性指定 AWS KMS key 的 AWS 区域。该属性仅在 encrypt 命令中有效，并且仅在主密钥提供程序为 AWS KMS 时有效。

--encrypt --wrapping-keys key=alias/primary-key region=us-east-2

如果 AWS Encryption CLI 命令包含区域（例如 ARN），则使用 key 属性值中指定的 AWS 区域。如果 key 值指定了 AWS 区域，则 region 属性将被忽略。

region 属性优先于指定的其他区域。如果未使用区域属性，则 AWS Encryption CLI 命令使用在 AWS CLI 命名配置文件（如果有）或默认配置文件中指定的 AWS 区域。

profile：指定命名配置文件

可以使用 profile 属性指定 AWS CLI 命名配置文件。命名配置文件可以包含凭证和 AWS 区域。只有在主密钥提供程序为 AWS KMS 时，该属性才有效。

--wrapping-keys key=alias/primary-key profile=admin-1

您可以使用 profile 属性在 encrypt 和 decrypt 命令中指定备用凭证。在加密命令中，只有在 key 值不包含区域并且没有 region 属性时，AWS Encryption CLI 才会使用命名配置文件中的 AWS 区域。在解密命令中，将忽略命名配置文件中的 AWS 区域。

如何指定多个包装密钥

您可以在每个命令中指定多个包装密钥（或主密钥）。

如果指定多个包装密钥，第一个包装密钥将生成并加密用于加密数据的数据密钥。其他包装密钥对相同的数据密钥进行加密。生成的加密消息包含加密的数据（“加密文字”）以及一组加密的数据密钥，每个包装密钥加密一个数据密钥。任何包装密钥可以解密一个加密的数据密钥，然后解密数据。

可以通过两种方法指定多个包装密钥：

  • 在 --wrapping-keys 参数值中包含多个 key 属性。

    $key_oregon=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$key_ohio=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef

--wrapping-keys key=$key_oregon key=$key_ohio

  • 在同一命令中包含多个 --wrapping-keys 参数。如果您指定的属性值不适用于命令中的所有包装密钥，请使用该语法。

    --wrapping-keys region=us-east-2 key=alias/test_key \
--wrapping-keys region=us-west-1 key=alias/test_key

值为 true 的 discovery 属性允许 AWS Encryption CLI 使用任何加密消息的 AWS KMS key。如果您在同一个命令中使用多个 --wrapping-keys 参数，则在任何 --wrapping-keys 参数中使用 discovery=true 都会有效地覆盖其他 --wrapping-keys 参数中 key 属性的限制。

例如，在以下命令中，第一个 --wrapping-keys 参数中的 key 属性将 AWS Encryption CLI 限制为指定的 AWS KMS key。但是，第二个 --wrapping-keys 参数中的 discovery 属性允许 AWS Encryption CLI 使用指定账户中的任何 AWS KMS key 来解密消息。

aws-encryption-cli --decrypt \
    --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --wrapping-keys discovery=true \
                    discovery-partition=aws \
                    discovery-account=111122223333 \
                    discovery-account=444455556666

如何提供输入

AWS Encryption CLI 中的加密操作将明文数据作为输入，并返回加密的消息。解密操作将加密的消息作为输入，并返回明文数据。

需要在所有 AWS Encryption CLI 命令中使用 --input 参数 (-i)，该参数指示 AWS Encryption CLI 在何处查找输入。

您可以通过任何以下方法提供输入：

  • 使用文件。

    --input myData.txt

  • 使用文件名模式。

    --input testdir/*.xml

  • 使用目录或目录名称模式。在输入为目录时，需要使用 --recursive 参数 (-r, -R)。

    --input testdir --recursive

  • 通过管道将输入发送到命令 (stdin)。请使用 - 参数的值 --input。（--input 参数始终是必需的。）

    echo 'Hello World' | aws-encryption-cli --encrypt --input -

如何指定输出位置

--output 参数指示 AWS Encryption CLI 在何处写入加密或解密操作的结果。需要在每个 AWS Encryption CLI 命令中使用该参数。AWS Encryption CLI 为操作中的每个输入文件创建新的输出文件。

如果输出文件已存在，AWS Encryption CLI 默认输出一条警告，然后覆盖该文件。要禁止覆盖，请使用 --interactive 参数（在覆盖之前提示您确认）或 --no-overwrite（在输出导致覆盖时跳过输入）。要禁止显示覆盖警告，请使用 --quiet。要从 AWS Encryption CLI 中捕获错误和警告，请使用 2>&1 重定向运算符将其写入到输出流中。

注意

覆盖输出文件的命令先删除输出文件。如果该命令失败，则可能已删除输出文件。

您可以通过多种方法指定输出位置。

  • 指定文件名。如果指定文件的路径，在运行该命令之前，路径中的所有目录必须存在。

    --output myEncryptedData.txt

  • 指定目录。在运行该命令之前，输出目录必须存在。

    如果输入包含子目录，该命令将在指定的目录中重新生成这些子目录。

    --output Test

    在输出位置为目录（没有文件名）时，AWS Encryption CLI 根据输入文件名加上后缀创建输出文件名。加密操作将 .encrypted 附加到输入文件名后面，而解密操作附加 .decrypted。要更改后缀，请使用 --suffix 参数。

    例如，如果加密 file.txt，encrypt 命令将创建 file.txt.encrypted。如果解密 file.txt.encrypted，decrypt 命令将创建 file.txt.encrypted.decrypted。

     

  • 写入到命令行 (stdout)。为 - 参数输入值 --output。您可以使用 --output - 通过管道将输出发送到另一个命令或程序。

    --output -

如何使用加密上下文

AWS Encryption CLI 允许在加密和解密命令中提供加密上下文。这不是必需的，但这是我们建议的加密最佳实践。

加密上下文 是一种任意的非机密其他经过身份验证的数据。在 AWS Encryption CLI 中，加密上下文包含一组 name=value 对。您可以在对中使用任意内容，包括有关文件的信息、帮助您在日志中查找加密操作的数据或您的授权或策略所需的数据。

在 encrypt 命令中

在 encrypt 命令中指定的加密上下文以及 CMM 添加的任何其他对以加密方式绑定到加密的数据。它还包含（以明文形式）在该命令返回的加密的消息中。如果使用 AWS KMS key，加密上下文也可能以明文形式显示在审核记录和日志中，如 AWS CloudTrail。

以下示例显示具有三个 name=value 对的加密上下文。

--encryption-context purpose=test dept=IT class=confidential

在 decrypt 命令中

在 decrypt 命令中，加密上下文帮助您确认解密的是正确的加密消息。

不需要在 decrypt 命令中提供加密上下文，即使在加密时使用了加密上下文。不过，如果这样做，AWS Encryption CLI 将检查解密命令的加密上下文中的每个元素与加密消息的加密上下文中的元素是否匹配。如果任何元素不匹配，decrypt 命令将失败。

例如，只有在加密上下文包含 dept=IT 时，以下命令才会解密加密的消息。

aws-encryption-cli --decrypt --encryption-context dept=IT ...

加密上下文是安全策略的重要组成部分。不过，在选择加密上下文时，请记住它的值不是机密的。请不要在加密上下文中包含任何机密数据。

指定加密上下文

  • 在 encrypt 命令中，使用具有一个或多个 name=value 对的 --encryption-context 参数。请使用空格分隔每个对。

    --encryption-context name=value [name=value] ...

  • 在 decrypt 命令中，--encryption-context 参数值可以包含 name=value 对、name 元素（没有值）或两者的组合。

    --encryption-context name[=value] [name] [name=value] ...

如果 name 对中的 value 或 name=value 包含空格或特殊字符，请将整个对用引号引起来。

--encryption-context "department=software engineering" "AWS 区域=us-west-2"

例如，该 encrypt 命令包含具有两个对（purpose=test 和 dept=23）的加密上下文。

aws-encryption-cli --encrypt --encryption-context purpose=test dept=23 ...

这些 decrypt 命令将会成功。每个命令中的加密上下文是原始加密上下文的一部分。

\\ Any one or both of the encryption context pairs
aws-encryption-cli --decrypt --encryption-context dept=23 ...

\\ Any one or both of the encryption context names
aws-encryption-cli --decrypt --encryption-context purpose ...

\\ Any combination of names and pairs
aws-encryption-cli --decrypt --encryption-context dept purpose=test ...

不过，这些 decrypt 命令将会失败。加密的消息中的加密上下文不包含指定的元素。

aws-encryption-cli --decrypt --encryption-context dept=Finance ...
aws-encryption-cli --decrypt --encryption-context scope ...

如何指定承诺策略

要为命令设置承诺策略，请使用 --commitment-policy 参数。此参数在版本 1.8.x 中引入。该参数在加密和解密命令中有效。您设置的承诺策略仅对出现在其中的命令有效。如果不为命令设置承诺策略，AWS Encryption CLI 将使用默认值。

例如，以下参数值将承诺策略设置为 require-encrypt-allow-decrypt，该策略始终使用密钥承诺进行加密，但会解密使用或不使用密钥承诺加密的加密文字。

--commitment-policy require-encrypt-allow-decrypt

如何在配置文件中存储参数

您可以将经常使用的 AWS Encryption CLI 参数和值保存在配置文件中，以节省时间和避免键入错误。

配置文件是一个文本文件，其中包含 AWS Encryption CLI 命令的参数和值。在 AWS Encryption CLI 命令中引用配置文件时，引用将替换为配置文件中的参数和值。如果在命令行中键入文件内容，效果是相同的。配置文件可以具有任何名称，并且可以位于当前用户可访问的任何目录中。

以下示例配置文件 (key.conf) 指定不同区域中的两个 AWS KMS keys。

--wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
--wrapping-keys key=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef

要在命令中使用配置文件，请在文件名前面添加 at 符号 (@)。在 PowerShell 控制台中，请使用反引号字符转义 at 符号 (`@)。

以下示例命令在 encrypt 命令中使用 key.conf 文件。

Bash
$ aws-encryption-cli -e @key.conf -i hello.txt -o testdir
PowerShell
PS C:\> aws-encryption-cli -e `@key.conf -i .\Hello.txt -o .\TestDir

配置文件规则

使用配置文件的规则如下所示：

  • 您可以在每个配置文件中包含多个参数，并按任意顺序列出这些参数。请在单独一行中列出每个参数及其值（如果有）。

  • 使用 # 为一行的全部或部分内容添加注释。

  • 您可以包含对其他配置文件的引用。不要使用反引号转义 @ 符号，即使在 PowerShell 中。

  • 如果在配置文件中使用引号，引起来的文本不能跨多个行。

例如，以下是示例 encrypt.conf 文件的内容。

# Archive Files
--encrypt
--output /archive/logs
--recursive
--interactive
--encryption-context class=unclassified dept=IT
--suffix  # No suffix
--metadata-output ~/metadata
@caching.conf  # Use limited caching

也可以在命令中包含多个配置文件。以下示例命令使用 encrypt.conf 和 master-keys.conf 配置文件。

Bash
$  aws-encryption-cli -i /usr/logs @encrypt.conf @master-keys.conf
PowerShell
PS C:\> aws-encryption-cli -i $home\Test\*.log `@encrypt.conf `@master-keys.conf

下一步：试用 AWS Encryption CLI 示例