本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS Encryption SDK 命令列界面
AWS Encryption SDK 命令列界面 (AWS 加密 CLI) 可讓您使用 AWS Encryption SDK 在命令列和指令碼中以互動方式加密和解密資料。您不需要具備密碼編譯或程式設計的專業知識。
**注意**
4.0.0 之前的 AWS 加密 CLI 版本處於[end-of-support階段](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)。
您可以安全地從 2.1.*x* 版和更新版本更新到最新版本的 AWS 加密 CLI，而不需要任何程式碼或資料變更。不過，2.1.*x* 版中引進[的新安全功能](about-versions.md#version-2)無法回溯相容。若要從 1.7.*x* 版或更早版本更新，您必須先更新至 AWS 加密 CLI 的最新 1.*x* 版本。如需詳細資訊，請參閱[遷移您的 AWS Encryption SDK](migration.md)。
新的安全功能最初在 AWS 加密 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](https://github.com/aws/aws-encryption-sdk-cli/) 儲存庫的相關[安全建議](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)。
如同 的所有實作 AWS Encryption SDK， AWS 加密 CLI 提供進階資料保護功能。其中包括[信封加密](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/how-it-works.html#envelope-encryption)、其他已驗證的資料 (AAD)，以及安全、已驗證的對稱金鑰[演算法套件](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/supported-algorithms.html)，例如具有金鑰衍生、[金鑰承諾](concepts.md#key-commitment)和簽署的 256 位元 AES-GCM。
AWS 加密 CLI 建置在 上[適用於 Python 的 AWS Encryption SDK](python.md)，並支援 Linux、macOS 和 Windows。您可以在 Linux 或 macOS 的偏好殼層中、在 Windows 的命令提示字元視窗 (cmd.exe) 中，以及在任何系統的 PowerShell 主控台中，執行命令和指令碼來加密和解密資料。
的所有特定語言實作 AWS Encryption SDK，包括 AWS 加密 CLI，皆可互通。例如，您可以使用 加密資料[適用於 JAVA 的 AWS Encryption SDK](java.md)，並使用 AWS Encryption CLI 解密資料。
本主題介紹 AWS 加密 CLI，說明如何安裝和使用它，並提供幾個範例來協助您開始使用。如需快速入門，請參閱 AWS 安全部落格中的[如何使用 AWS 加密 CLI 來加密和解密您的資料](https://aws.amazon.com/blogs/security/how-to-encrypt-and-decrypt-your-data-with-the-aws-encryption-cli/)。如需更多詳細資訊，請參閱[閱讀文件](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)，並加入我們在 GitHub 的 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 儲存庫中開發 AWS 加密 CLI。
**效能**
AWS 加密 CLI 建置在 上 適用於 Python 的 AWS Encryption SDK。每次執行 CLI 時，都會啟動 Python 執行時間的新執行個體。若要改善效能，請盡可能使用單一命令而非一系列的獨立命令。例如，執行會以遞迴方式處理目錄中檔案的一個命令，而不是對每個檔案執行個別命令。
**Topics**
+ [安裝 CLI](crypto-cli-install.md)
+ [如何使用 CLI](crypto-cli-how-to.md)
+ [範例](crypto-cli-examples.md)
+ [語法和參數參考](crypto-cli-reference.md)
+ [版本](crypto-cli-versions.md)
# 安裝 AWS Encryption SDK 命令列界面
本主題說明如何安裝 AWS 加密 CLI。如需詳細資訊，請參閱 GitHub 上的 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 儲存庫，並[閱讀相關文件](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)。
**Topics**
+ [安裝必要項目](#crypto-cli-prerequisites)
+ [安裝 CLI](#install-sdk-cli)
## 安裝必要項目
AWS 加密 CLI 建置在 上 適用於 Python 的 AWS Encryption SDK。若要安裝 AWS 加密 CLI，您需要 Python 和 `pip`，Python 套件管理工具。所有支援的平台皆有提供 Python 與 `pip`。
在安裝 AWS 加密 CLI 之前，請先安裝下列先決條件，
**Python**
AWS 加密 CLI 4.2.0 版及更新版本需要 Python 3.8 或更新版本。
舊版的 AWS Encryption CLI 支援 Python 2.7 和 3.4 及更新版本，但我們建議您使用最新版本的 AWS Encryption CLI。
Python 包含在大多數 Linux 和 macOS 安裝中，但您需要升級至 Python 3.6 或更新版本。我們建議您使用最新版本的 Python。在 Windows 上，您必須安裝 Python；預設不會安裝。若要下載並安裝 Python，請參閱 [Python 下載](https://www.python.org/downloads/)。
若要判斷 Python 是否已安裝完畢，請於命令列輸入下列內容。
```
python
```
若要查看 Python 版本，請使用 `-V` (大寫 V) 參數。
```
python -V
```
在 Windows 上，安裝 Python 之後，將`Python.exe`檔案的路徑新增至**路徑**環境變數的值。
在預設情況下，Python 會安裝在 `$home` 子目錄的所有使用者目錄或使用者描述檔目錄中 (`%userprofile%` 或 `AppData\Local\Programs\Python`)。若要找出系統中的 `Python.exe` 檔案，請查看下列登錄機碼。您可以使用 PowerShell 來搜尋登錄。
```
PS C:\> dir HKLM:\Software\Python\PythonCore\version\InstallPath
# -or-
PS C:\> dir HKCU:\Software\Python\PythonCore\version\InstallPath
```
**pip**
`pip` 為 Python 套件管理工具。若要安裝 AWS Encryption CLI 及其相依性，您需要 `pip` 8.1 或更新版本。如需安裝或升級 的說明`pip`，請參閱 `pip` 文件中的[安裝](https://pip.pypa.io/en/latest/installing/)。
在 Linux 安裝上， 8.1 `pip`之前的版本無法建置 AWS 加密 CLI 所需的**密碼編譯**程式庫。如果您選擇不更新`pip`版本，您可以分別安裝建置工具。如需詳細資訊，請參閱[在 Linux 上建置密碼編譯](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux)。
**AWS Command Line Interface**
只有在您在 AWS Command Line Interface (AWS CLI) AWS KMS keys 中 AWS Key Management Service 搭配 AWS 加密 CLI 使用 時，才需要 (AWS KMS)。如果您使用的是不同的[主金鑰提供者](concepts.md#master-key-provider)， AWS CLI 則不需要 。
若要 AWS KMS keys 搭配 AWS 加密 CLI 使用 ，您需要[安裝](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)和[設定 ](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-quick-configuration) AWS CLI。組態可讓您用來驗證 的登入資料可供 AWS 加密 CLI AWS KMS 使用。
## 安裝和更新 AWS 加密 CLI
安裝最新版本的 AWS Encryption CLI。當您使用 `pip` 安裝 AWS 加密 CLI 時，它會自動安裝 CLI 所需的程式庫，包括 [適用於 Python 的 AWS Encryption SDK](python.md)、Python [密碼編譯程式庫](https://cryptography.io/en/latest/)和 [適用於 Python (Boto3) 的 AWS SDK](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)。
**注意**
4.0.0 之前的 AWS 加密 CLI 版本處於終止[end-of-support階段](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)。
您可以安全地從 2.1.*x* 版和更新版本更新至最新版本的 AWS 加密 CLI，而不需要變更任何程式碼或資料。不過，2.1.*x* 版中引入[的新安全功能](about-versions.md#version-2)與回溯不相容。若要從 1.7.*x* 版或更早版本更新，您必須先更新至 AWS 加密 CLI 的最新 1.*x* 版本。如需詳細資訊，請參閱[遷移您的 AWS Encryption SDK](migration.md)。
新的安全功能最初在 AWS 加密 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](https://github.com/aws/aws-encryption-sdk-cli/) 儲存庫中的相關[安全建議](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)。
**安裝最新版本的 AWS 加密 CLI**
```
pip install aws-encryption-sdk-cli
```
**升級至最新版本的 AWS 加密 CLI**
```
pip install --upgrade aws-encryption-sdk-cli
```
**尋找 AWS 加密 CLI 和 的版本編號 AWS Encryption SDK**
```
aws-encryption-cli --version
```
輸出會列出兩個程式庫的版本編號。
```
aws-encryption-sdk-cli/2.1.0 aws-encryption-sdk/2.0.0
```
**升級至最新版本的 AWS 加密 CLI**
```
pip install --upgrade aws-encryption-sdk-cli
```
如果尚未安裝最新版本的 適用於 Python (Boto3) 的 AWS SDK，安裝 AWS Encryption CLI 也會安裝該版本。如果已安裝 Boto3，安裝程式會驗證 Boto3 版本並視需要更新。
**尋找已安裝的 Boto3 版本**
```
pip show boto3
```
**更新至最新版本的 Boto3**
```
pip install --upgrade boto3
```
若要安裝目前正在開發的 AWS 加密 CLI 版本，請參閱 GitHub 上的 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 儲存庫。
如需使用 `pip` 安裝與升級 Python 套件的詳細資訊，請參閱 [pip 文件](https://pip.pypa.io/en/stable/quickstart/)。
# 如何使用 AWS 加密 CLI
本主題說明如何使用 AWS 加密 CLI 中的參數。如需範例，請參閱 [AWS 加密 CLI 的範例](crypto-cli-examples.md)。如需完整的文件，請參閱[閱讀相關文件](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)。這些範例中顯示的語法適用於 AWS Encryption CLI 2.1.*x* 版及更新版本。
**注意**
4.0.0 之前的 AWS 加密 CLI 版本處於[end-of-support階段](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)。
您可以安全地從 2.1.*x* 版和更新版本更新至最新版的 AWS 加密 CLI，而不需要變更任何程式碼或資料。不過，2.1.*x* 版中引進[的新安全功能](about-versions.md#version-2)無法回溯相容。若要從 1.7.*x* 版或更早版本更新，您必須先更新至 AWS 加密 CLI 的最新 1.*x* 版本。如需詳細資訊，請參閱[遷移您的 AWS Encryption SDK](migration.md)。
新的安全功能最初在 AWS 加密 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](https://github.com/aws/aws-encryption-sdk-cli/) 儲存庫中的相關[安全建議](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)。
如需示範如何使用限制加密資料金鑰之安全功能的範例，請參閱 [限制加密的資料金鑰](configure.md#config-limit-keys)。
如需示範如何使用 AWS KMS 多區域金鑰的範例，請參閱 [使用多區域 AWS KMS keys](configure.md#config-mrks)。
**Topics**
+ [如何加密和解密資料](#crypto-cli-e-d-intro)
+ [如何指定包裝金鑰](#crypto-cli-master-key)
+ [如何提供輸入](#crypto-cli-input)
+ [如何指定輸出位置](#crypto-cli-output)
+ [如何使用加密內容](#crypto-cli-encryption-context)
+ [如何指定承諾政策](#crypto-cli-commitment-policy)
+ [如何在組態檔案中存放參數](#crypto-cli-config-file)
## 如何加密和解密資料
Encryption CLI AWS 使用 的功能 AWS Encryption SDK ，讓您輕鬆加密和解密資料。
**注意**
`--master-keys` 參數已在 AWS 加密 CLI 的 1.8.*x* 版中棄用，並在 2.1.*x* 版中移除。請改用 `--wrapping-keys` 參數。從 2.1.*x* 版開始，在加密和解密時需要 `--wrapping-keys` 參數。如需詳細資訊，請參閱[AWS Encryption SDK CLI 語法和參數參考](crypto-cli-reference.md)。
+ 當您在 AWS 加密 CLI 中加密資料時，您可以指定純文字資料和[包裝金鑰](concepts.md#master-key) （或*主金鑰*)，例如 AWS KMS key in AWS Key Management Service ()AWS KMS。如果您使用的是自訂主金鑰提供者，您也需要指定提供者。您也可以指定[已加密訊息](concepts.md#message)和加密操作相關中繼資料的輸出位置。[加密內容](concepts.md#encryption-context)是選用的，但建議使用。
在 1.8.*x* 版中，使用 `--commitment-policy` 參數時需要 `--wrapping-keys` 參數，否則無效。從 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 加密 CLI 會使用唯一的資料金鑰加密您的資料。然後，它會在您指定的包裝金鑰下加密資料金鑰。它會傳回[已加密訊息](concepts.md#message)和操作的相關中繼資料。已加密訊息包含加密的資料 (*加密文字*) 和資料金鑰的已加密副本。您不需要擔心存放和管理問題，或是遺失資料金鑰。
+ 解密資料時，傳入已加密訊息、選用的加密內容，以及純文字輸出和中繼資料的位置。您也可以指定 AWS 加密 CLI 可用來解密訊息的包裝金鑰，或告知 AWS 加密 CLI 可以使用任何加密訊息的包裝金鑰。
從 1.8.*x* 版開始， 參數在解密時`--wrapping-keys`為選用，但建議使用。從 2.1.*x* 版開始，在加密和解密時需要 `--wrapping-keys` 參數。
解密時，您可以使用 `--wrapping-keys` 參數的**金鑰**屬性來指定解密資料的包裝金鑰。在解密時指定 AWS KMS 包裝金鑰是選用的，但[最佳實務](best-practices.md)是防止您使用不打算使用的金鑰。如果您使用的是自訂主金鑰提供者，則必須指定提供者和包裝金鑰。
如果您不使用**金鑰**屬性，則必須將 `--wrapping-keys` 參數的[**探索**屬性](#discovery-cli-attribute)設定為 `true`，這可讓 AWS Encryption CLI 使用任何加密訊息的包裝金鑰來解密。
最佳實務是使用 `--max-encrypted-data-keys` 參數，以避免解密格式不正確的訊息，其中包含過多的加密資料金鑰。指定預期的加密資料金鑰數量 （用於加密的每個包裝金鑰各一個） 或合理的上限 （例如 5)。如需詳細資訊，請參閱[限制加密的資料金鑰](configure.md#config-limit-keys)。
`--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 加密 CLI 中加密資料時，您需要指定至少一個[包裝金鑰](concepts.md#master-key) （或*主金鑰*)。您可以使用 AWS KMS keys in AWS Key Management Service (AWS KMS)、來自自訂[主金鑰提供者的包裝金鑰](concepts.md#master-key-provider)，或兩者。自訂主金鑰提供者可以是任何相容的 Python 主金鑰提供者。
若要在 1.8.*x* 版和更新版本中指定包裝金鑰，請使用 `--wrapping-keys` 參數 (`-w`)。此參數的值是 `attribute=value` 格式的[屬性](#cli-master-key-attributes)集合。您使用的屬性取決於主金鑰提供者和命令。
+ **AWS KMS**。 在加密命令中，您必須指定具有**金鑰**屬性的`--wrapping-keys`參數。從 2.1.*x* 版開始，解密命令中也需要 `--wrapping-keys` 參數。解密時， `--wrapping-keys` 參數必須具有索引**鍵**屬性或值為 `true`（但不能同時具有兩者） 的**探索**屬性。其他屬性是選用的。
+ **自訂主金鑰提供者**。您必須在每個命令中指定`--wrapping-keys`參數。參數值必須擁有 **key** 和 **provider** 屬性。
您可以在相同的命令中包含[多個`--wrapping-keys`參數](#cli-many-cmks)和多個**金鑰**屬性。
### 包裝金鑰參數屬性
`--wrapping-keys` 參數的值包含下列屬性以及其值。所有加密命令都需要 `--wrapping-keys` 參數 （或 `--master-keys` 參數）。從 2.1.*x* 版開始，解密時也需要 `--wrapping-keys` 參數。
如果屬性名稱或值包含空格或特殊字元，請同時用引號括住名稱和值。例如 `--wrapping-keys key=12345 "provider=my cool provider"`。
**金鑰：指定包裝金鑰**
使用**金鑰**屬性來識別包裝金鑰。加密時，該值可以是主金鑰提供者辨識的任何金鑰識別符。
```
--wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab
```
在加密命令中，您必須包含至少一個**金鑰**屬性和值。若要在多個包裝金鑰下加密資料金鑰，請使用[多個**金鑰**屬性](#cli-many-cmks)。
```
aws-encryption-cli --encrypt --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab key=1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
```
在 使用的加密命令中 AWS KMS keys，**金鑰**的值可以是金鑰 ID、其金鑰 ARN、別名名稱或別名 ARN。例如，此加密命令在 **key** 屬性的值中使用別名 ARN。如需 金鑰識別符的詳細資訊 AWS KMS key，請參閱《 *AWS Key Management Service 開發人員指南*》中的[金鑰識別符](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)。
```
aws-encryption-cli --encrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
```
在使用自訂主金鑰提供者的解密命令中，**key** 和 **provider** 屬性是必要的。
```
\\ Custom master key provider
aws-encryption-cli --decrypt --wrapping-keys provider='myProvider' key='100101'
```
在 使用的解密命令中 AWS KMS，您可以使用**金鑰**屬性來指定 AWS KMS keys 要用於解密的 ，或使用值為 的[**探索**屬性](#discovery-cli-attribute)`true`，這可讓 AWS Encryption CLI 使用任何用來加密訊息 AWS KMS key 的 。如果您指定 AWS KMS key，它必須是用來加密訊息的其中一個包裝金鑰。
指定包裝金鑰是[AWS Encryption SDK 最佳實務](best-practices.md)。它可確保您使用 AWS KMS key 打算使用的 。
在解密命令中，**金鑰**屬性的值必須是[金鑰 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-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`。值 `true`可讓 AWS 加密 CLI 使用加密訊息的任何 AWS KMS key 進行解密。如果您未指定**探索**屬性，則 探索為 `false`（預設）。**探索**屬性僅在解密命令中有效，且僅在訊息加密時使用 AWS KMS keys。
值為 的**探索**屬性`true`是使用**金鑰**屬性來指定的替代方案 AWS KMS keys。解密使用 加密的訊息時 AWS KMS keys，每個`--wrapping-keys`參數都必須具有**金鑰**屬性或值為 的**探索**屬性`true`，但不能同時具有兩者。
當探索為 true 時，最佳實務是使用 **探索分割區**和**探索帳戶**屬性，將 AWS KMS keys 限制為您 AWS 帳戶 指定的 中所使用的 。在下列範例中，**探索**屬性允許 AWS 加密 CLI 在指定的 AWS KMS key 中使用任何 AWS 帳戶。
```
aws-encryption-cli --decrypt --wrapping-keys \
discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666
```
**提供者：指定主金鑰提供者**
**provider** 屬性識別[主金鑰提供者](concepts.md#master-key-provider)。預設值是 `aws-kms`，代表 AWS KMS。如果您使用不同的主金鑰提供者，則 **provider** 屬性為必要。
```
--wrapping-keys key=12345 provider=my_custom_provider
```
如需使用自訂 （非AWS KMS) 主金鑰提供者的詳細資訊，請參閱[AWS 加密 CLI ](https://github.com/aws/aws-encryption-sdk-cli/)儲存庫的 [README](https://github.com/aws/aws-encryption-sdk-cli/blob/master/README.rst) 檔案中的**進階組態**主題。
**區域：指定 AWS 區域**
使用**區域**屬性指定 AWS 區域 的 AWS KMS key。此屬性僅在加密命令中有效，且僅適用於主金鑰提供者是 AWS KMS時。
```
--encrypt --wrapping-keys key=alias/primary-key region=us-east-2
```
AWS 如果加密 CLI 命令包含區域，例如 ARN，則會使用**金鑰**屬性值中 AWS 區域 指定的 。如果**金鑰**值指定 a AWS 區域，則會忽略**區域**屬性。
**region** 屬性優先於其他區域規格。如果您不使用區域屬性， AWS Encryption CLI 命令會使用 AWS CLI [您命名設定檔](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles)中 AWS 區域 指定的 ，如果有的話，或是您的預設設定檔。
**Profile：指定命名設定檔**
使用 **profile** 屬性可指定 AWS CLI [命名描述檔](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles)。具名設定檔可以包含登入資料和 AWS 區域。此屬性僅適用於主金鑰提供者是 AWS KMS時。
```
--wrapping-keys key=alias/primary-key profile=admin-1
```
您可以使用 **profile** 屬性來指定加密和解密命令中的備用登入資料。在加密命令中，只有在**金鑰**值不包含區域且沒有**區域**屬性時， AWS 加密 CLI 才會在具名設定檔 AWS 區域 中使用 。在解密命令中，會忽略名稱設定檔 AWS 區域 中的 。
### 如何指定多個包裝金鑰
您可以在每個命令中指定多個包裝金鑰 （或*主金鑰*)。
如果您指定多個包裝金鑰，第一個包裝金鑰會產生並加密用於加密資料的資料金鑰。其他包裝金鑰會加密相同的資料金鑰。產生的[加密訊息](concepts.md#message)包含加密的資料 (「加密文字」) 和加密資料金鑰的集合，每個包裝金鑰各加密一個。任何包裝都可以解密一個加密的資料金鑰，然後解密資料。
有兩種方式可以指定多個包裝金鑰：
+ 在`--wrapping-keys`參數值中包含多個**金鑰**屬性。
```
$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`可讓 AWS 加密 CLI 使用任何加密訊息 AWS KMS key 的 。如果您在相同的命令中使用多個`--wrapping-keys`參數，在任何`--wrapping-keys`參數`discovery=true`中使用 會有效地覆寫其他`--wrapping-keys`參數中**金鑰**屬性的限制。
例如，在下列命令中，第一個`--wrapping-keys`參數中的**金鑰**屬性會將 AWS 加密 CLI 限制為指定的 AWS KMS key。不過，第二個`--wrapping-keys`參數中的 **探索**屬性可讓 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 加密 CLI 中的加密操作會將純文字資料做為輸入，並傳回[加密的訊息](concepts.md#message)。解密操作採用已加密訊息做為輸入，並傳回純文字資料。
所有 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 加密 CLI 會為 操作中的每個輸入檔案建立新的輸出檔案。
如果輸出檔案已存在，根據預設， AWS 加密 CLI 會列印警告，然後覆寫檔案。若要防止覆寫，請使用 `--interactive` 參數，這會在覆寫前提示您確認；或者 `--no-overwrite`，如果輸出會造成覆寫則略過輸入。若要隱藏覆寫警告，請使用 `--quiet`。若要從 AWS 加密 CLI 擷取錯誤和警告，請使用`2>&1`重新導向運算子將它們寫入輸出串流。
**注意**
覆寫輸出檔案的命令首先會刪除輸出檔案。如果命令失敗，輸出檔案可能已遭到刪除。
您可以透過幾種方法指定輸出位置。
+ 指定檔案名稱。如果指定檔案路徑，路徑中的所有目錄都必須存在，命令才能執行。
```
--output myEncryptedData.txt
```
+ 指定目錄。執行命令之前，輸出目錄必須存在。
如果輸入包含子目錄，命令會在指定的目錄之下重新產生子目錄。
```
--output Test
```
當輸出位置是目錄 （不含檔案名稱） 時， AWS 加密 CLI 會根據輸入檔案名稱加上尾碼來建立輸出檔案名稱。加密操作會附加 `.encrypted` 到輸入檔案名稱，而解密操作會附加 `.decrypted`。若要變更尾碼，請使用 `--suffix` 參數。
例如，如果您加密 `file.txt`，加密命令會建立 `file.txt.encrypted`。如果您解密 `file.txt.encrypted`，解密命令會建立 `file.txt.encrypted.decrypted`。
+ 寫入命令列 (stdout)。輸入 `-` 參數的 `--output` 值。您可以使用 `--output -`，將輸出輸送到另一個命令或程式。
```
--output -
```
## 如何使用加密內容
AWS 加密 CLI 可讓您在加密和解密命令中提供加密內容。這不是必要項目，但它是我們建議的密碼編譯最佳實務。
*加密內容*是一種任意、非私密*額外驗證資料*。在 AWS 加密 CLI 中，加密內容包含一組`name=value`配對。您可以使用此配對中的任何內容，包括檔案的相關資訊、可協助您在日誌中尋找加密操作的資料，或者您授予或政策要求的資料。
**在加密命令中**
您在加密命令中指定的加密內容，以及 [CMM](concepts.md#crypt-materials-manager) 新增的任何額外配對，將以密碼編譯的方式繫結至加密的資料。它也會納入命令傳回的[已加密訊息](concepts.md#encryption-context)中 (以純文字形式)。如果您使用的是 AWS KMS key，加密內容也可能以純文字顯示在稽核記錄和日誌中，例如 AWS CloudTrail。
以下範例顯示使用三個 `name=value` 配對的加密內容。
```
--encryption-context purpose=test dept=IT class=confidential
```
**在解密命令中**
在解密命令中，加密內容可協助您確認您正在解密正確的已加密訊息。
即使加密時有使用加密內容，您也不需要在解密命令中提供加密內容。不過，如果您這樣做， AWS 加密 CLI 會驗證解密命令加密內容中的每個元素是否與加密訊息加密內容中的 元素相符。如果沒有相符元素，解密命令會失敗。
例如，以下命令只有在加密內容包含 `dept=IT` 時，才會解密已加密訊息。
```
aws-encryption-cli --decrypt --encryption-context dept=IT ...
```
加密內容是安全策略的重要部分。不過，在選擇加密內容時，請記住它的值不是秘密。請勿在加密內容中包含任何機密資料。
**指定加密內容**
+ 在 **encrypt** 命令中，使用 `--encryption-context` 參數搭配一或多個 `name=value` 對組。使用空格來分隔每個對組。
```
--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"
```
例如，此加密命令包含使用兩個對組 (`purpose=test` 和 `dept=23`) 的加密內容。
```
aws-encryption-cli --encrypt --encryption-context purpose=test dept=23 ...
```
這些解密命令可以成功。每個命令中的加密內容是原始加密內容的子集。
```
\\ 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 ...
```
不過，這些解密命令會失敗。已加密訊息的加密內容不包含指定的元素。
```
aws-encryption-cli --decrypt --encryption-context dept=Finance ...
aws-encryption-cli --decrypt --encryption-context scope ...
```
## 如何指定承諾政策
若要設定命令[的承諾政策](concepts.md#commitment-policy)，請使用 [`--commitment-policy` 參數](crypto-cli-reference.md#syntax-commitment-policy)。此參數在 1.8.*x* 版中推出。它在加密和解密命令中有效。您設定的承諾政策僅適用於其出現的命令。如果您未設定命令的承諾政策， AWS 加密 CLI 會使用預設值。
例如，下列參數值會將承諾政策設定為 `require-encrypt-allow-decrypt`，該政策一律使用金鑰承諾加密，但會解密使用或不使用金鑰承諾加密的加密文字。
```
--commitment-policy require-encrypt-allow-decrypt
```
## 如何在組態檔案中存放參數
您可以在組態檔案中儲存常用的 AWS 加密 CLI 參數和值，以節省時間並避免輸入錯誤。
*組態檔案*是文字檔案，其中包含 AWS Encryption CLI 命令的參數和值。當您在 AWS Encryption CLI 命令中參考組態檔案時，參考會被組態檔案中的參數和值取代。其效果如同您在命令列中輸入檔案內容。組態檔案可使用任何名稱、位於目前使用者可存取的任何目錄中。
下列範例組態檔案 AWS KMS keys 會在不同的區域中`key.conf`指定兩個 。
```
--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
```
若要在命令中使用組態檔案，請在檔案名稱前加上 @ 符號 (`@`)。在 PowerShell 主控台中，請使用反引號字元來逸出 @ 符號 (``@`)。
此範例命令在加密命令中使用 `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 加密 CLI 範例](crypto-cli-examples.md)
# AWS 加密 CLI 的範例
使用以下範例，在您偏好的平台上嘗試 AWS 加密 CLI。如需主金鑰和其他參數的說明，請參閱[如何使用 AWS 加密 CLI](crypto-cli-how-to.md)。如需快速參考，請參閱 [AWS Encryption SDK CLI 語法和參數參考](crypto-cli-reference.md)。
**注意**
下列範例使用 AWS 加密 CLI 2.1.*x* 版的語法。
新的安全功能最初在 AWS 加密 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](https://github.com/aws/aws-encryption-sdk-cli/) 儲存庫的相關[安全建議](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)。
如需示範如何使用限制加密資料金鑰之安全功能的範例，請參閱 [限制加密的資料金鑰](configure.md#config-limit-keys)。
如需示範如何使用 AWS KMS 多區域金鑰的範例，請參閱 [使用多區域 AWS KMS keys](configure.md#config-mrks)。
**Topics**
+ [加密檔案](#cli-example-encrypt-file)
+ [解密檔案](#cli-example-decrypt-file)
+ [加密目錄中的所有檔案](#cli-example-encrypt-directory)
+ [解密目錄中的所有檔案](#cli-example-decrypt-directory)
+ [在命令列上加密和解密](#cli-example-stdin)
+ [使用多個主金鑰](#cli-example-multimaster)
+ [在指令碼中加密和解密](#cli-example-script)
+ [使用資料金鑰快取](#cli-example-caching)
## 加密檔案
此範例使用 AWS 加密 CLI 來加密 `hello.txt` 檔案的內容，其中包含「Hello World」字串。
當您在檔案上執行加密命令時， AWS 加密 CLI 會取得檔案的內容、產生唯一的[資料金鑰](concepts.md#DEK)、在資料金鑰下加密檔案內容，然後將[加密的訊息](concepts.md#message)寫入新檔案。
第一個命令會將 的金鑰 ARN 儲存在 `$keyArn`變數 AWS KMS key 中。使用 加密時 AWS KMS key，您可以使用金鑰 ID、金鑰 ARN、別名名稱或別名 ARN 來識別它。如需 金鑰識別符的詳細資訊 AWS KMS key，請參閱《 *AWS Key Management Service 開發人員指南*》中的[金鑰識別符](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)。
第二個命令會加密檔案內容。此命令會使用 `--encrypt` 參數來指定操作和 `--input` 參數，以指示需要加密的檔案。[`--wrapping-keys` 參數](crypto-cli-how-to.md#crypto-cli-master-key)及其所需的**金鑰**屬性，指示 命令使用由金鑰 ARN AWS KMS key 表示的 。
此命令會使用 `--metadata-output` 參數，指定用於加密操作相關中繼資料的文字檔案。根據最佳實務，此命令會使用 `--encryption-context` 參數來指定[加密細節](crypto-cli-how-to.md#crypto-cli-encryption-context)。
此命令也會使用 [`--commitment-policy` 參數](crypto-cli-reference.md#syntax-commitment-policy)來明確設定承諾政策。在 1.8.*x* 版中，當您使用 參數時，需要此`--wrapping-keys`參數。從 2.1.*x* 版開始， `--commitment-policy` 參數是選用的，但建議使用。
`--output` 參數的值，也就是點 (.)，則會通知此命令要將輸出檔寫入目前的目錄。
------
#### [ Bash ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt \
--output .
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid value.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --encrypt `
--input Hello.txt `
--wrapping-keys key=$keyArn `
--metadata-output $home\Metadata.txt `
--commitment-policy require-encrypt-require-decrypt `
--encryption-context purpose=test `
--output .
```
------
當執行成功時，加密命令並不會傳回任何輸出。若要判斷命令是否執行成功，請查看 `$?` 變數的布林值。當命令執行成功時，`$?` 的值會是 `0` (Bash) 或 `True` (PowerShell)。當命令執行失敗時，`$?` 的值會是非零 (Bash) 或 `False` (PowerShell)。
------
#### [ Bash ]
```
$ echo $?
0
```
------
#### [ PowerShell ]
```
PS C:\> $?
True
```
------
您也可以使用目錄列出命令，查看加密命令是否建立了新的檔案 `hello.txt.encrypted`。由於加密命令未指定輸出的檔案名稱，因此 AWS Encryption CLI 會將輸出寫入與輸入檔案同名的檔案，加上`.encrypted`尾碼。若要使用不同的尾碼或隱藏尾碼，請使用 `--suffix` 參數。
`hello.txt.encrypted` 檔案包含了[加密的訊息](concepts.md#message)，當中包含 `hello.txt` 檔案的加密文字、資料金鑰的加密副本，以及包括加密細節的額外中繼資料。
------
#### [ Bash ]
```
$ ls
hello.txt hello.txt.encrypted
```
------
#### [ PowerShell ]
```
PS C:\> dir
Directory: C:\TestCLI
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/15/2017 5:57 PM 11 Hello.txt
-a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted
```
------
## 解密檔案
此範例使用 AWS 加密 CLI 來解密先前範例中加密`Hello.txt.encrypted`的檔案內容。
此解密命令會使用 `--decrypt` 參數來指示操作和 `--input` 參數，以確認需要解密的檔案。`--output` 參數的值是一個點，即代表目前的目錄。
具有**金鑰**屬性的 `--wrapping-keys` 參數會指定用於解密加密訊息的包裝金鑰。在使用 解密命令中 AWS KMS keys，金鑰屬性的值必須是[金鑰 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)。解密命令中需要 `--wrapping-keys` 參數。如果您使用的是 AWS KMS keys，您可以使用**金鑰**屬性來指定 AWS KMS keys 進行解密，或使用值為 `true`（但不能同時指定兩者） 的**探索**屬性。如果您使用的是自訂主金鑰提供者，則需要**金鑰**和**提供者**屬性。
從 2.1.*x* 版開始， [`--commitment-policy` 參數](crypto-cli-reference.md#syntax-commitment-policy)是選用的，但建議使用。使用它可以明確地讓您的意圖清晰，即使您指定了預設值 `require-encrypt-require-decrypt`。
`--encryption-context` 參數在解密命令中屬於選用性，即使加密命令中已有提供[加密細節](crypto-cli-how-to.md#crypto-cli-encryption-context)。遇到這種情況時，解密命令會使用加密命令所提供的相同加密細節。在解密之前， AWS 加密 CLI 會驗證加密訊息中的加密內容是否包含`purpose=test`配對。如果沒有包含，解密命令執行就會失敗。
`--metadata-output` 參數會指定用於解密操作相關中繼資料的檔案。`--output` 參數的值，也就是點 (.)，則會將輸出檔寫入目前的目錄。
最佳實務是使用 `--max-encrypted-data-keys` 參數，以避免解密格式不正確的訊息，其中包含過多的加密資料金鑰。指定預期的加密資料金鑰數量 （用於加密的每個包裝金鑰各一個） 或合理的上限 （例如 5)。如需詳細資訊，請參閱[限制加密的資料金鑰](configure.md#config-limit-keys)。
只有在處理所有輸入之後， 才會`--buffer`傳回純文字，包括驗證存在的數位簽章。
------
#### [ Bash ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--commitment-policy require-encrypt-require-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output .
```
------
#### [ PowerShell ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --decrypt `
--input Hello.txt.encrypted `
--wrapping-keys key=$keyArn `
--commitment-policy require-encrypt-require-decrypt `
--encryption-context purpose=test `
--metadata-output $home\Metadata.txt `
--max-encrypted-data-keys 1 `
--buffer `
--output .
```
------
當執行成功時，解密命令並不會傳回任何輸出。若要判斷命令是否執行成功，請取得 `$?` 變數的值。您也可以使用目錄列出命令，查看此命令是否建立了另加尾碼 `.decrypted` 的新檔案。若要查看純文字內容，請使用命令以取得該檔案內容，例如 `cat` 或 [Get-Content](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-content)。
------
#### [ Bash ]
```
$ ls
hello.txt hello.txt.encrypted hello.txt.encrypted.decrypted
$ cat hello.txt.encrypted.decrypted
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> dir
Directory: C:\TestCLI
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 1:01 PM 11 Hello.txt
-a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted
-a---- 9/17/2017 1:08 PM 11 Hello.txt.encrypted.decrypted
PS C:\> Get-Content Hello.txt.encrypted.decrypted
Hello World
```
------
## 加密目錄中的所有檔案
此範例使用 AWS 加密 CLI 來加密目錄中所有檔案的內容。
當命令影響多個檔案時， AWS 加密 CLI 會個別處理每個檔案。它會取得檔案內容、從主金鑰取得該檔案的唯一[資料金鑰](concepts.md#DEK)、根據該資料金鑰來加密檔案內容，接著將結果寫入在輸出目錄中的新檔案。因此，您可以獨立解密處理輸出檔。
這份 `TestDir` 目錄清單顯示了我們要加密的純文字檔案。
------
#### [ Bash ]
```
$ ls testdir
cool-new-thing.py hello.txt employees.csv
```
------
#### [ PowerShell ]
```
PS C:\> dir C:\TestDir
Directory: C:\TestDir
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/12/2017 3:11 PM 2139 cool-new-thing.py
-a---- 9/15/2017 5:57 PM 11 Hello.txt
-a---- 9/17/2017 1:44 PM 46 Employees.csv
```
------
第一個命令會將 的 [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn) 儲存在 `$keyArn`變數 AWS KMS key 中。
第二個命令會加密在 `TestDir` 目錄中之檔案的內容，並將加密細節的檔案寫入 `TestEnc` 目錄。如果該 `TestEnc` 目錄不存在，命令執行就會失敗。由於輸入位置是一個目錄，所以必須使用 `--recursive` 參數。
[`--wrapping-keys` 參數](crypto-cli-how-to.md#crypto-cli-master-key)及其所需的**金鑰**屬性，指定要使用的包裝金鑰。此加密命令會包含[加密細節](crypto-cli-how-to.md#crypto-cli-encryption-context)、`dept=IT`。當您在執行加密多個檔案的加密命令中指定某加密細節時，所有檔案都會使用該相同加密細節。
命令也有 `--metadata-output` 參數，可告知 AWS 加密 CLI 在何處寫入有關加密操作的中繼資料。Encryption AWS CLI 會為每個加密的檔案寫入一個中繼資料記錄。
從 2.1.*x* 版開始， [`--commitment-policy parameter`](crypto-cli-how-to.md#crypto-cli-commitment-policy)是選用的，但建議使用。如果命令或指令碼因為無法解密加密文字而失敗，明確承諾政策設定可協助您快速偵測問題。
當命令完成時， AWS 加密 CLI 會將加密的檔案寫入`TestEnc`目錄，但不會傳回任何輸出。
最後的命令會列出 `TestEnc` 目錄中的檔案。每個純文字內容的輸入檔案，都會有一個加密細節的輸出檔案。由於此命令沒有指定替代尾碼，所以加密命令會在每個輸入檔名後面加上 `.encrypted`。
------
#### [ Bash ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input testdir --recursive\
--wrapping-keys key=$keyArn \
--encryption-context dept=IT \
--commitment-policy require-encrypt-require-decrypt \
--metadata-output ~/metadata \
--output testenc
$ ls testenc
cool-new-thing.py.encrypted employees.csv.encrypted hello.txt.encrypted
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
PS C:\> $keyArn = arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
PS C:\> aws-encryption-cli --encrypt `
--input .\TestDir --recursive `
--wrapping-keys key=$keyArn `
--encryption-context dept=IT `
--commitment-policy require-encrypt-require-decrypt `
--metadata-output .\Metadata\Metadata.txt `
--output .\TestEnc
PS C:\> dir .\TestEnc
Directory: C:\TestEnc
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted
-a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted
-a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted
```
------
## 解密目錄中的所有檔案
這個範例會解密目錄中的所有檔案。範例一開始是先處理位在 `TestEnc` 目錄中，先前範例所加密的檔案。
------
#### [ Bash ]
```
$ ls testenc
cool-new-thing.py.encrypted hello.txt.encrypted employees.csv.encrypted
```
------
#### [ PowerShell ]
```
PS C:\> dir C:\TestEnc
Directory: C:\TestEnc
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted
-a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted
-a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted
```
------
這個解密命令會解密在 TestEnc 目錄中的所有檔案，接著將純文字檔案寫入 TestDec 目錄。具有**金鑰**屬性和[金鑰 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) 值的 `--wrapping-keys` 參數會告知 AWS 加密 CLI AWS KMS keys 要使用哪個項目來解密檔案。命令使用 `--interactive` 參數來指示 AWS 加密 CLI 在覆寫具有相同名稱的檔案之前提示您。
此命令也會使用在先前加密檔案時所提供的加密細節。解密多個檔案時， AWS 加密 CLI 會檢查每個檔案的加密內容。如果任何檔案的加密內容檢查失敗， AWS 加密 CLI 會拒絕檔案、寫入警告、在中繼資料中記錄失敗，然後繼續檢查剩餘的檔案。如果 AWS 加密 CLI 因任何其他原因而無法解密檔案，整個解密命令會立即失敗。
在這個範例中，所有輸入檔中的已加密訊息都會包含 `dept=IT` 加密細節元素。不過，如果要解密的訊息採用不同的加密細節，這時您應該還是可以驗證部分的加密細節。例如，如果某些訊息包含 `dept=finance` 的加密細節，而其他訊息包含的是 `dept=IT`，這時您不用指定該值，就能驗證加密細節是否一直包含 `dept` 名稱。如果您想要設定更多限定，您可以使用個別命令來解密這些檔案。
解密命令不會傳回任何輸出，但您可以使用目錄列出命令，查看其是否建立了另加 `.decrypted` 尾碼的新檔案。若要查看純文字內容，請使用命令以取得該檔案內容。
------
#### [ Bash ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --decrypt \
--input testenc --recursive \
--wrapping-keys key=$keyArn \
--encryption-context dept=IT \
--commitment-policy require-encrypt-require-decrypt \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output testdec --interactive
$ ls testdec
cool-new-thing.py.encrypted.decrypted hello.txt.encrypted.decrypted employees.csv.encrypted.decrypted
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --decrypt `
--input C:\TestEnc --recursive `
--wrapping-keys key=$keyArn `
--encryption-context dept=IT `
--commitment-policy require-encrypt-require-decrypt `
--metadata-output $home\Metadata.txt `
--max-encrypted-data-keys 1 `
--buffer `
--output C:\TestDec --interactive
PS C:\> dir .\TestDec
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 10/8/2017 4:57 PM 2139 cool-new-thing.py.encrypted.decrypted
-a---- 10/8/2017 4:57 PM 46 Employees.csv.encrypted.decrypted
-a---- 10/8/2017 4:57 PM 11 Hello.txt.encrypted.decrypted
```
------
## 在命令列上加密和解密
這些範例會示範如何將輸入輸送到命令 (stdin)，以及將輸出寫入命令列 (stdout)。範例會說明如何在命令中表示 stdin、stdout，以及如何使用內建的 Base64 編碼工具防止 shell 錯誤解譯非 ASCII 字元。
這個範例會將純文字字串輸送到加密命令，並將加密的訊息儲存到變數中。然後，它會將變數中的已加密訊息輸送到解密命令，再由該命令將其輸出寫入到管道 (stdout)。
範例中包含了三種命令：
+ 第一個命令會將 的[金鑰 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) 儲存在 `$keyArn`變數 AWS KMS key 中。
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
------
#### [ PowerShell ]
```
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
```
------
+ 第二個命令會將 `Hello World` 字串輸送到加密命令，並將執行結果儲存到 `$encrypted` 變數中。
所有 AWS Encryption CLI 命令都需要 `--input`和 `--output` 參數。若要指示輸入要輸送到命令 (stdin)，`-` 參數的值應使用連字號 (`--input`)。若要將輸出傳送到命令列 (stdout)，`--output` 參數的值應使用連字號。
`--encode` 參數會先對輸出進行 Base64 編碼，再將其傳回。這樣可以防止 shell 錯誤解譯已加密訊息中的非 ASCII 字元。
由於這個命令只是為了概念驗證，所以我們會省略加密細節，並且隱藏中繼資料 (`-S`)。
------
#### [ Bash ]
```
$ encrypted=$(echo 'Hello World' | aws-encryption-cli --encrypt -S \
--input - --output - --encode \
--wrapping-keys key=$keyArn )
```
------
#### [ PowerShell ]
```
PS C:\> $encrypted = 'Hello World' | aws-encryption-cli --encrypt -S `
--input - --output - --encode `
--wrapping-keys key=$keyArn
```
------
+ 第三個命令會將 `$encrypted` 變數中的已加密訊息輸送到解密命令。
這個解密命令會使用 `--input -`，指示輸入會由該管道送入 (stdin)，而且使用 `--output -` 將輸出傳送到該管道 (stdout)。(輸入參數接收的是輸入的位置，而非實際的輸入位元組，因此您不能使用 `$encrypted` 變數做為 `--input` 參數值)。
此範例使用 `--wrapping-keys` 參數的 **探索**屬性，以允許 AWS 加密 CLI 使用任何 AWS KMS key 來解密資料。它不會指定[承諾政策](concepts.md#commitment-policy)，因此會使用 2.1.*x* 版和更新版本的預設值 `require-encrypt-require-decrypt`。
由於輸出是經過加密後再進行編碼，所以解密命令會先使用 `--decode` 參數來解碼經 Base64 編碼處理的輸入，接著再進行解密。您也可以先使用 `--decode` 參數，為經 Base64 編碼處理的解碼，接著再進行加密。
同樣地，這個命令會省略加密細節，並隱藏中繼資料 (-`S`)。
------
#### [ Bash ]
```
$ echo $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode --buffer -S
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode --buffer -S
Hello World
```
------
您也可以運用單一個命令來執行加密和解密操作，完全不用中斷變數。
在上述範例中，`--input` 和 `--output` 參數具有 `-` 值，而此命令會使用 `--encode` 參數來為輸出進行編碼，並使用 `--decode` 參數來為輸入進行解碼。
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ echo 'Hello World' |
aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S |
aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode -S
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> 'Hello World' |
aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S |
aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode -S
Hello World
```
------
## 使用多個主金鑰
此範例示範如何在加密 AWS CLI 中加密和解密資料時使用多個主金鑰。
如果您是使用多個主金鑰來加密資料，則其中任何一個主金鑰都可用來為資料進行解密。這個策略可確保您一定可以解密資料，即使其中一個主金鑰發生不可用的情況。如果您要將加密的資料儲存在多個 中 AWS 區域，此策略可讓您在相同區域中使用主金鑰來解密資料。
當您使用多個主金鑰來進行加密時，第一個主金鑰會扮演特殊的角色。它會產生將在資料加密時所用到的資料金鑰。其餘的主金鑰則加密處理純文字的資料金鑰。結果產生的[加密的訊息](concepts.md#message)，包含了該已加密資料和已加密資料金鑰的集合，每則訊息會對應到個別主金鑰。雖然第一個主金鑰會產生資料金鑰，但其中任何一個主金鑰都可以解密處理任何一個可用來解密處理資料的資料金鑰。
**使用三個主金鑰加密**
此範例命令使用三個包裝金鑰來加密`Finance.log`檔案，每個檔案各一個 AWS 區域。
它會將加密的訊息寫入到 `Archive` 目錄。此命令會使用 `--suffix` 參數，且不指定隱藏尾碼的參數值，因此輸入和輸出檔的名稱都是相同的。
此命令會使用 `--wrapping-keys` 參數，並指定三個 **key** 屬性。您也可以在相同的命令中使用多個 `--wrapping-keys` 參數。
若要加密日誌檔案， AWS Encryption CLI 會要求清單中的第一個包裝金鑰 `$key1`產生用來加密資料的資料金鑰。然後，它會使用其他每個包裝金鑰來加密相同資料金鑰的純文字副本。在輸出檔案中的已加密訊息，包含了全部三個的已加密資料金鑰。
------
#### [ Bash ]
```
$ key1=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ key2=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef
$ key3=arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
$ aws-encryption-cli --encrypt --input /logs/finance.log \
--output /archive --suffix \
--encryption-context class=log \
--metadata-output ~/metadata \
--wrapping-keys key=$key1 key=$key2 key=$key3
```
------
#### [ PowerShell ]
```
PS C:\> $key1 = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> $key2 = 'arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef'
PS C:\> $key3 = 'arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d'
PS C:\> aws-encryption-cli --encrypt --input D:\Logs\Finance.log `
--output D:\Archive --suffix `
--encryption-context class=log `
--metadata-output $home\Metadata.txt `
--wrapping-keys key=$key1 key=$key2 key=$key3
```
------
這個命令會解密處理已加密的 `Finance.log` 檔案副本，並將其寫入 `Finance.log.clear` 目錄中的 `Finance` 檔案。若要解密在三下加密的資料 AWS KMS keys，您可以指定相同的三個 AWS KMS keys 或任何子集。此範例僅指定其中一個 AWS KMS keys。
若要告知 AWS 加密 CLI AWS KMS keys 使用哪個 來解密您的資料，請使用 `--wrapping-keys` 參數的**金鑰**屬性。使用 解密時 AWS KMS keys，**金鑰**屬性的值必須是[金鑰 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)。
您必須擁有在您 AWS KMS keys 指定的 上呼叫 [Decrypt API](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) 的許可。如需詳細資訊，請參閱 [的身分驗證和存取控制 AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html)。
最佳實務是，此範例使用 `--max-encrypted-data-keys` 參數來避免解密格式不正確的訊息，其中包含過多的加密資料金鑰。即使此範例僅使用一個包裝金鑰進行解密，加密的訊息具有三 (3) 個加密的資料金鑰；加密時使用的三個包裝金鑰各一個。指定預期的加密資料金鑰數量或合理的最大值，例如 5。如果您指定小於 3 的最大值，則命令會失敗。如需詳細資訊，請參閱[限制加密的資料金鑰](configure.md#config-limit-keys)。
------
#### [ Bash ]
```
$ aws-encryption-cli --decrypt --input /archive/finance.log \
--wrapping-keys key=$key1 \
--output /finance --suffix '.clear' \
--metadata-output ~/metadata \
--max-encrypted-data-keys 3 \
--buffer \
--encryption-context class=log
```
------
#### [ PowerShell ]
```
PS C:\> aws-encryption-cli --decrypt `
--input D:\Archive\Finance.log `
--wrapping-keys key=$key1 `
--output D:\Finance --suffix '.clear' `
--metadata-output .\Metadata\Metadata.txt `
--max-encrypted-data-keys 3 `
--buffer `
--encryption-context class=log
```
------
## 在指令碼中加密和解密
此範例示範如何在指令碼中使用 AWS 加密 CLI。您可以編寫只要加密和解密資料的指令碼，或者在資料管理程序中負責加密或解密操作的指令碼。
在此範例中，指令碼會取得日誌檔案的集合、壓縮它們、加密它們，然後將加密的檔案複製到 Amazon S3 儲存貯體。這段指令碼會獨立處理個別檔案，所以這些檔案可以單獨地進行解密和展開。
在壓縮和加密檔案時，請務必先完成壓縮，再進行加密。正確完成加密的資料不能進行壓縮。
**警告**
壓縮資料可能包含由惡意人士所操控的秘密和資料，請務必小心。壓縮資料的最終大小，可能會不當透露出與其內容有關的敏感資訊。
------
#### [ Bash ]
```
# Continue running even if an operation fails.
set +e
dir=$1
encryptionContext=$2
s3bucket=$3
s3folder=$4
masterKeyProvider="aws-kms"
metadataOutput="/tmp/metadata-$(date +%s)"
compress(){
gzip -qf $1
}
encrypt(){
# -e encrypt
# -i input
# -o output
# --metadata-output unique file for metadata
# -m masterKey read from environment variable
# -c encryption context read from the second argument.
# -v be verbose
aws-encryption-cli -e -i ${1} -o $(dirname ${1}) --metadata-output ${metadataOutput} -m key="${masterKey}" provider="${masterKeyProvider}" -c "${encryptionContext}" -v
}
s3put (){
# copy file argument 1 to s3 location passed into the script.
aws s3 cp ${1} ${s3bucket}/${s3folder}
}
# Validate all required arguments are present.
if [ "${dir}" ] && [ "${encryptionContext}" ] && [ "${s3bucket}" ] && [ "${s3folder}" ] && [ "${masterKey}" ]; then
# Is $dir a valid directory?
test -d "${dir}"
if [ $? -ne 0 ]; then
echo "Input is not a directory; exiting"
exit 1
fi
# Iterate over all the files in the directory, except *gz and *encrypted (in case of a re-run).
for f in $(find ${dir} -type f \( -name "*" ! -name \*.gz ! -name \*encrypted \) ); do
echo "Working on $f"
compress ${f}
encrypt ${f}.gz
rm -f ${f}.gz
s3put ${f}.gz.encrypted
done;
else
echo "Arguments: "
echo " and ENV var \$masterKey must be set"
exit 255
fi
```
------
#### [ PowerShell ]
```
#Requires -Modules AWSPowerShell, Microsoft.PowerShell.Archive
Param
(
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String[]]
$FilePath,
[Parameter()]
[Switch]
$Recurse,
[Parameter(Mandatory=$true)]
[String]
$wrappingKeyID,
[Parameter()]
[String]
$masterKeyProvider = 'aws-kms',
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$ZipDirectory,
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$EncryptDirectory,
[Parameter()]
[String]
$EncryptionContext,
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$MetadataDirectory,
[Parameter(Mandatory)]
[ValidateScript({Test-S3Bucket -BucketName $_})]
[String]
$S3Bucket,
[Parameter()]
[String]
$S3BucketFolder
)
BEGIN {}
PROCESS {
if ($files = dir $FilePath -Recurse:$Recurse)
{
# Step 1: Compress
foreach ($file in $files)
{
$fileName = $file.Name
try
{
Microsoft.PowerShell.Archive\Compress-Archive -Path $file.FullName -DestinationPath $ZipDirectory\$filename.zip
}
catch
{
Write-Error "Zip failed on $file.FullName"
}
# Step 2: Encrypt
if (-not (Test-Path "$ZipDirectory\$filename.zip"))
{
Write-Error "Cannot find zipped file: $ZipDirectory\$filename.zip"
}
else
{
# 2>&1 captures command output
$err = (aws-encryption-cli -e -i "$ZipDirectory\$filename.zip" `
-o $EncryptDirectory `
-m key=$wrappingKeyID provider=$masterKeyProvider `
-c $EncryptionContext `
--metadata-output $MetadataDirectory `
-v) 2>&1
# Check error status
if ($? -eq $false)
{
# Write the error
$err
}
elseif (Test-Path "$EncryptDirectory\$fileName.zip.encrypted")
{
# Step 3: Write to S3 bucket
if ($S3BucketFolder)
{
Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted" -Key "$S3BucketFolder/$fileName.zip.encrypted"
}
else
{
Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted"
}
}
}
}
}
}
```
------
## 使用資料金鑰快取
這個範例會在加密處理大量檔案的命令中使用[資料金鑰快取](data-key-caching.md)。
根據預設， AWS 加密 CLI （和其他版本的 AWS Encryption SDK) 會為其加密的每個檔案產生唯一的資料金鑰。雖然最佳加密實務是為每筆操作使用唯一的資料金鑰，但在某些情況下，仍可接受特定的資料金鑰重複使用。如果您考慮使用資料金鑰快取，請向安全性工程師諮詢實際應用上的安全性需求，並且決定適合您的安全性閾值。
在這個範例中，資料金鑰快取因為減少了向主金鑰提供者提出請求的頻率，使得加密操作速度加快。
在這個範例中的命令會加密處理包含多個子目錄的大型目錄，其中包含總共大約 800 個小型日誌檔。第一個命令會將 AWS KMS key 的 ARN 儲存在 `keyARN` 變數中。第二個命令會加密處理輸入目錄中的所有檔案，並將其寫入封存目錄。這個命令會使用 `--suffix` 參數來指定 `.archive` 尾碼。
`--caching` 參數會啟用資料金鑰快取。負責限制快取中資料金鑰數量的 **capacity** 屬性則設為 1，因為序列式檔案處理時，一次一律使用一個資料金鑰。負責決定已快取金鑰可以使用多久的 **max\$1age** 屬性則設為 10 秒鐘。
選用的 **max\$1messages\$1encrypted** 屬性則設為 10 則訊息，所以在加密處理 10 個以上的檔案時，絕對不會使用單一個資料金鑰。限定每個資料金鑰能夠加密的檔案數目，能在資料金鑰遭洩的難得情況發生時減少受到影響的檔案數量。
若要為作業系統產生的日誌檔執行這個命令，您可能需要具備系統管理員權限 (Linux 的 `sudo`；Windows 的 **Run as Administrator (以系統管理員身分執行)**)。
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input /var/log/httpd --recursive \
--output ~/archive --suffix .archive \
--wrapping-keys key=$keyArn \
--encryption-context class=log \
--suppress-metadata \
--caching capacity=1 max_age=10 max_messages_encrypted=10
```
------
#### [ PowerShell ]
```
PS C:\> $keyARN = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10 max_messages_encrypted=10
```
------
為了測試資料金鑰快取的效果，這個範例會在 PowerShell 中使用 [Measure-Command](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/measure-command) cmdlet。若執行此範例時不執行資料金鑰快取功能，完成需時大約 25 秒鐘。這個程序會為目錄中的每個檔案產生新的資料金鑰。
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata }
Days : 0
Hours : 0
Minutes : 0
Seconds : 25
Milliseconds : 453
Ticks : 254531202
TotalDays : 0.000294596298611111
TotalHours : 0.00707031116666667
TotalMinutes : 0.42421867
TotalSeconds : 25.4531202
TotalMilliseconds : 25453.1202
```
資料金鑰快取能夠加快程序，即使限制每個資料金鑰最多只能處理 10 個檔案。這個命令現在只要不到 12 秒就能完成，因此向主金鑰提供者發出的呼叫次數減少成為原來次數的 1/10。
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10 max_messages_encrypted=10}
Days : 0
Hours : 0
Minutes : 0
Seconds : 11
Milliseconds : 813
Ticks : 118132640
TotalDays : 0.000136727592592593
TotalHours : 0.00328146222222222
TotalMinutes : 0.196887733333333
TotalSeconds : 11.813264
TotalMilliseconds : 11813.264
```
如果刪除 `max_messages_encrypted` 限制，則所有檔案都會依據相同的資料金鑰進行加密。這項變更會導致重複使用資料金鑰的風險提高，而且程序速度並不會加快。不過，它能將呼叫主金鑰提供者的次數縮減為 1 次。
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10}
Days : 0
Hours : 0
Minutes : 0
Seconds : 10
Milliseconds : 252
Ticks : 102523367
TotalDays : 0.000118661304398148
TotalHours : 0.00284787130555556
TotalMinutes : 0.170872278333333
TotalSeconds : 10.2523367
TotalMilliseconds : 10252.3367
```
# AWS Encryption SDK CLI 語法和參數參考
本主題提供語法圖表和概要參數描述，以協助您使用 AWS Encryption SDK 命令列界面 (CLI)。如需包裝金鑰和其他參數的說明，請參閱 [如何使用 AWS 加密 CLI](crypto-cli-how-to.md)。如需範例，請參閱 [AWS 加密 CLI 的範例](crypto-cli-examples.md)。如需完整的文件，請參閱[閱讀相關文件](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)。
**Topics**
+ [AWS 加密 CLI 語法](#crypto-cli-syntax)
+ [AWS 加密 CLI 命令列參數](#crypto-cli-parameters)
+ [進階參數](#cli-advanced-parameters)
## AWS 加密 CLI 語法
這些 AWS Encryption CLI 語法圖表顯示您使用 AWS Encryption CLI 執行的每個任務的語法。它們代表 AWS 加密 CLI 2.1.*x* 版和更新版本中建議的語法。
新的安全功能最初在 AWS 加密 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](https://github.com/aws/aws-encryption-sdk-cli/) 儲存庫中的相關[安全建議](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)。
**注意**
除非在參數描述中另有說明，否則每個參數或屬性在每個命令中只能使用一次。
如果您使用 參數不支援的屬性， AWS Encryption CLI 會忽略該不支援的屬性，而不會出現警告或錯誤。
**取得說明**
若要取得具有參數描述的完整 AWS 加密 CLI 語法，請使用 `--help`或 `-h`。
```
aws-encryption-cli (--help | -h)
```
**取得版本**
若要取得您 AWS Encryption CLI 安裝的版本編號，請使用 `--version`。當您提出問題、回報問題或分享有關使用 AWS 加密 CLI 的秘訣時，請務必包含 版本。
```
aws-encryption-cli --version
```
**加密資料**
下列語法圖表顯示 **encrypt** 命令使用的參數。
```
aws-encryption-cli --encrypt
--input [--recursive] [--decode]
--output