AWS Encryption SDK CLI 語法和參數參考 - AWS Encryption SDK
AWS加密 CLI 語法AWS加密 CLI 命令列參數進階參數

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

AWS Encryption SDK CLI 語法和參數參考

本主題提供語法圖表和概要參數描述，以協助您使用 AWS Encryption SDK 命令列界面 (CLI)。如需包裝鍵和其他參數的說明，請參閱如何使用加AWS密 CLI。如需範例，請參閱示例AWS加密 CLI。如需完整的文件，請參閱閱讀相關文件。

AWS加密 CLI 語法

這些AWS加密 CLI 語法圖表顯示您使用AWS加密 CLI 執行的每個工作的語法。它們代表AWS加密 CLI 2.1 版中的建議語法。 x 及更新版本。

新的安全功能最初在AWS加密 CLI 版本 1.7 中發布。 X 和 2.0。 x. 但是，AWS加密 CLI 版本 1.8。 x 會取代 1.7 版。 x 和AWS加密指令碼 2.1. x 取代了 2.0。 x. 如需詳細資訊，請參閱的aws-encryption-sdk-cli儲存庫中的相關安全性建議 GitHub。

注意

除非在參數描述中註明，否則每個參數或屬性只能在每個命令中使用一次。

如果您使用參數不支援的屬性，則AWS加密 CLI 會忽略該不支援的屬性，而不會出現警告或錯誤。

取得說明

若要取得具有參數說明的完整AWS加密 CLI 語法，請使用--help或-h。

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

若要取得AWS加密 CLI 安裝的版本號碼，請使用--version。當您提出問題、回報問題或分享有關使用AWS加密 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 屬性來指定包裝金鑰 (最佳作法) 或將探索屬性設定為true，這不會限制 EnAWS cryption 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加密 CLI 命令列參數

此清單提供AWS加密 CLI 命令參數的基本說明。如需完整說明，請參閱aws-encryption-sdk-cli文件。

--encrypt (-e)

加密輸入資料。每個命令都必須有一個--encrypt、或--decrypt、或--decrypt-unsigned參數。

--decrypt (-d)

解密輸入資料。每個命令都必須具有--encrypt--decrypt、或--decrypt-unsigned參數。

-解密-無簽名 [在版本 1.9 中引入。 X 和 2.2. x]

該--decrypt-unsigned參數解密文本，並確保消息在解密之前未簽名。如果您使用參數並選取沒有--algorithm數位簽章的演算法套件來加密資料，請使用此參數。如果密文已簽署，解密會失敗。

您可以使用--decrypt或--decrypt-unsigned進行解密，但不能同時使用兩者。

-包裝鍵（-w）[在版本 1.8 中引入。 x]

指定用於加密和解密作業的包裝金鑰 (或主金鑰)。您可以在每個指令中使用多個--wrapping-keys參數。

從 2.1 版開始。 x，--wrapping-keys參數在加密和解密命令中是必需的。在 1.8 版中。 x，加密命令需要一個--wrapping-keys或--master-keys參數。在 1.8 版中。 x 解密命令，--wrapping-keys參數是可選的，但建議使用。

使用自訂主要金鑰提供者時，加密和解密命令需要金鑰和提供者屬性。使用時AWS KMS keys，加密命令需要密鑰屬性。解密命令需要金鑰屬性或值為true (但不能兩者) 的探索屬性。解密時使用金鑰屬性是AWS Encryption SDK最佳作法。如果您要解密一批不熟悉的訊息 (例如 Amazon S3 儲存貯體或 Amazon SQS 佇列中的訊息)，這一點尤為重要。

如需展示如何使用AWS KMS多區域金鑰作為環繞金鑰的範例，請參閱使用多地區 AWS KMS keys。

屬性：--wrapping-keys 參數的值包含下列屬性。格式是 attribute_name=value。

key

識別作業中使用的包裝金鑰。格式是 key=ID 對組。您可以在每個--wrapping-keys參數值中指定多個關鍵屬性。

  • 加密命令：所有加密命令都需要密鑰屬性。當您AWS KMS key在加密命令中使用時，金鑰屬性的值可以是金鑰 ID、金鑰 ARN、別名 ARN、別名 ARN。如需AWS KMS金鑰識別碼的說明，請參閱AWS Key Management Service開發人員指南中的金鑰識別碼。

  • 解密命令：使用解密時AWS KMS keys，--wrapping-keys參數需要具有金鑰 ARN 值的金鑰屬性，或具有值true (但不能兩者) 的探索屬性。使用 key 屬性是AWS Encryption SDK最佳做法。使用自訂主要金鑰提供者進行解密時，需要金鑰屬性。

    注意

    若要在解密命令中指定AWS KMS包裝金鑰，金鑰屬性的值必須是金鑰 ARN。如果您使用金鑰 ID、別名名稱或別名 ARN，AWS加密 CLI 不會識別名稱或別名 ARN。

您可以在每個--wrapping-keys參數值中指定多個關鍵屬性。但是，參數中的任何提供者、區域和設定檔屬性都會套用至該--wrapping-keys參數值中的所有包裝鍵。若要使用不同的屬性值指定包裝鍵，請在指令中使用多個--wrapping-keys參數。

發現

允許加AWS密 CLI 使用任何AWS KMS key來解密訊息。探索值可以是true或false。預設值為 false。探索屬性僅在解密命令中有效，且只有在主要金鑰提供者為時才有效AWS KMS。

使用解密時AWS KMS keys，--wrapping-keys參數需要索引鍵屬性或值為true (但不能兩者) 的探索屬性。如果您使用 key 屬性，則可以使用值為的探索屬性false來明確拒絕探查。

  • False(預設值) — 未指定探查屬性或其值為時false，EnAWS cryption CLI 只會使用--wrapping-keys參數金鑰屬性所AWS KMS keys指定的解密訊息。如果您在探索時未指定金鑰屬性false，則解密命令會失敗。此值支援加AWS密 CLI 最佳做法。

  • True— 當探索屬性的值為時true，EnAWS cryption CLI 會從加密訊息中的AWS KMS keys中繼資料取得，並使用這些中繼資料AWS KMS keys來解密訊息。值為的探查屬性的true行為與 1.8 版之前的AWS加密 CLI 版本相似。 x 在解密時不允許您指定包裝密鑰。但是，您使用 any 的意圖AWS KMS key是明確的。如果您在探查時指定金鑰屬性true，則解密指令會失敗。

    該true值可能會導致AWS加密 CLIAWS KMS keys 在不同AWS 帳戶的區域中使用，或嘗試使用AWS KMS keys該使用者未獲授權使用。

如果是探索true，最佳做法是使用探索分割區和探索帳戶屬性，將使AWS KMS keys用的屬性限制在AWS 帳戶您指定的屬性。

探索帳戶

將AWS KMS keys用於解密的限制在指定的AWS 帳戶。此屬性的唯一有效值是 AWS 帳戶ID。

此屬性是選用的，只有在將探索屬性設AWS KMS keys定為true且已指定探索分割區屬性的解密命令中才有效。

每個探索帳戶屬性只需要一個AWS 帳戶 ID，但您可以在相同的--wrapping-keys參數中指定多個探索帳戶屬性。指定--wrapping-keys參數中指定的所有帳戶都必須位於指定的AWS分割區中。

探索分區

指定探索帳戶屬性中帳戶的AWS分割區。其值必須是AWS分割區，例如awsaws-cn、或aws-gov-cloud。如需相關資訊，請參閱 AWS 一般參考.

當您使用探索帳戶屬性時，此屬性是必要的。您只能在每個--wrapping keys參數中指定一個探索分割區屬性。若要AWS 帳戶在多個分割區中指定，請使用其他--wrapping-keys參數。

provider (提供者)

識別主金鑰提供者。格式是 provider=ID 對組。預設值 aws-kms 代表 AWS KMS。只有當主金鑰提供者不是 AWS KMS 時，此屬性才為必要。

region

識別AWS 區域的AWS KMS key。此屬性僅對AWS KMS keys。僅在 key 識別符未指定區域時才會用到，否則會忽略。使用此屬性時，它會覆寫 AWS CLI 命名設定檔中的預設區域。

profile

識別 AWS CLI 命名描述檔。此屬性僅對AWS KMS keys。只有在命令中的 key 識別符未指定區域，且沒有 region 屬性時，才會使用設定檔中的區域。

--input (-i)

指定加密或解密資料的位置。此為必要參數。這個值可以是檔案或目錄的路徑，或檔案名稱模式。如果您將輸入輸送到命令 (stdin)，請使用 -。

如果輸入不存在，命令會順利完成，且不出現錯誤或警告。

--recursive (-r, -R)

在輸入目錄及其子目錄中的檔案上執行操作。當 --input 的值是目錄時，此參數為必要。

--decode

解碼 Base64 編碼輸入。

如果您要解密先加密接著編碼的訊息，您必須先解碼訊息，然後才能解密。此參數會為您處理這些工作。

例如，如果您在加密命令中使用 --encode 參數，請在對應的解密命令中使用 --decode 參數。您也可以使用此參數來解碼 Base64 編碼輸入，接著再進行加密。

--output (-o)

指定輸出的目的地。此為必要參數。這個值可以是檔案名稱、現有目錄，或者 -，後者會將輸出寫入命令列 (stdout)。

如果指定的輸出目錄不存在，命令會失敗。如果輸入包含子目錄，則AWS加密 CLI 會在您指定的輸出目錄下重新產生子目錄。

根據預設，加AWS密 CLI 會覆寫具有相同名稱的檔案。若要變更此行為，請使用 --interactive 或 --no-overwrite 參數。若要隱藏覆寫警告，請使用 --quiet 參數。

注意

如果覆寫輸出檔案的命令失敗，則會刪除輸出檔案。

--interactive

在覆寫檔案之前出現提示。

--no-overwrite

不要覆寫檔案。相反地，如果輸出檔案存在，則AWS加密 CLI 會略過對應的輸入。

--suffix

為AWS加密 CLI 建立的檔案指定自訂檔案名稱尾碼。若要指示沒有尾碼，請使用參數而不加上值 (--suffix)。

在預設情況下，當 --output 參數未指定檔案名稱，輸出檔案名稱會具有輸入檔案名稱的相同名稱，再加上尾碼。加密命令的尾碼是 .encrypted。解密命令的尾碼是 .decrypted。

--encode

套用 Base64 (二進位至文字) 編碼到輸出。編碼可防止殼層主機程式錯誤解譯輸出文字中的非 ASCII 字元。

將加密輸出寫入 stdout (--output -) 時，尤其是在 PowerShell 控制台中，即使您要將輸出管道傳送到另一個命令或將其保存在變量中，也可以使用此參數。

--metadata-output

指定密碼編譯操作的相關中繼資料的位置。輸入路徑和檔案名稱。如果目錄不存在，命令會失敗。若要寫入中繼資料至命令列 (stdout)，請使用 -。

您不能在相同的命令中寫入命令輸出 (--output) 和中繼資料輸出 (--metadata-output) 至 stdout。此外，當 --input 或 --output 的值是目錄 (沒有檔案名稱)，您無法將中繼資料輸出寫入到相同目錄或該目錄的任何子目錄。

如果您指定現有檔案，依預設，AWS加密 CLI 會將新的中繼資料記錄附加至檔案中的任何內容。此功能可讓您建立單一檔案，其中包含所有密碼編譯操作的中繼資料。若要覆寫現有檔案中的內容，請使用 --overwrite-metadata 參數。

加AWS密 CLI 會針對命令執行的每個加密或解密作業，傳回 JSON 格式的中繼資料記錄。每個中繼資料記錄都包含輸入和輸出檔案的完整路徑、加密內容、演算法套件和其他有用資訊，供您用來檢視操作並驗證其符合您的安全標準。

--overwrite-metadata

覆寫中繼資料輸出檔案中的內容。在預設情況下，--metadata-output 參數會附加中繼資料到檔案中的任何現有內容。

--suppress-metadata (-S)

隱藏加密或解密操作的相關中繼資料。

-承諾政策

指定加密和解密命令的承諾原則。承諾產品原則會判斷您的郵件是否已使用金鑰承諾安全性功能加密和解密。

該--commitment-policy參數在 1.8 版中引入。 x. 它在加密和解密命令中是有效的。

在版本 1.8 中。 x，AWS加密 CLI 會針對所有加密和解密作業使用forbid-encrypt-allow-decrypt承諾原則。當您在加密或解密命令中使用--commitment-policy參數時，需要具有該forbid-encrypt-allow-decrypt值的參數。--wrapping-keys如果不使用--wrapping-keys參數，則--commitment-policy參數無效。明確設定承諾產品原則可防止承諾原則在升級至 2.1 版require-encrypt-require-decrypt時自動變更為。 x

從 2.1 版開始。 x，支援所有承諾產品原則值。--commitment-policy參數是選擇性的，預設值為require-encrypt-require-decrypt。

此參數具有以下值：

  • forbid-encrypt-allow-decrypt— 無法使用金鑰承諾加密。它可以解密有或沒有密鑰承諾加密的密文。

    在 1.8 版中。 x，這是唯一有效的值。加AWS密 CLI 會針對所有加密和解密作業使用forbid-encrypt-allow-decrypt承諾原則。

  • require-encrypt-allow-decrypt— 僅使用關鍵承諾進行加密。無論是否有關鍵承諾，都可以解密。2.1 版會引入此值。 x.

  • require-encrypt-require-decrypt(預設值) — 僅使用金鑰承諾進行加密和解密。2.1 版會引入此值。 x. 它是 2.1 版本中的默認值。 x 及更新版本。使用此值時，AWS加密 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"。

-緩衝區（-b）[在版本 1.9 中引入。 X 和 2.2. x]

僅在處理完所有輸入之後返回純文本，包括驗證數字簽名（如果存在）。

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

指定加密郵件中加密資料金鑰的數目上限。此為選用參數。

有效值為 1 至 65,535。如果忽略此參數，則AWS加密 CLI 不會強制執行任何最大值。加密訊息最多可容納 65,535 (2^16-1) 的加密資料金鑰。

您可以在加密命令中使用此參數，以防止格式錯誤的郵件。您可以在解密命令中使用它來檢測惡意消息，並避免使用無法解密的大量加密數據密鑰解密消息。如需詳細資訊和範例，請參閱限制加密的資料金鑰。

--help (-h)

在命令列印使用方法和語法。

--version

取得AWS加密 CLI 的版本。

-v | -vv | -vvv | -vvvv

顯示詳細資訊、警告和偵錯訊息。輸出中的詳細資訊會隨著參數中的 v 數量而增加。最詳細的設定 (-vvvv) 會從AWS加密 CLI 及其使用的所有元件傳回除錯層級資料。

--quiet (-q)

隱藏警告訊息，例如，當您覆寫輸出檔案時的訊息。

-主鍵 (-m) [已棄用]
注意

--主鍵參數在1.8 中已棄用。 x 並在 2.1 版中刪除。 x. 相反，請使用 -包裝鍵參數。

指定用於加密和解密操作的主金鑰。您可以在每個命令中使用多個主金鑰參數。

在加密命令中 --master-keys 參數為必要。只有當您使用自訂 (非AWS KMS) 主要金鑰提供者時，才需要在解密指令中使用此功能。

屬性：--master-keys 參數的值包含下列屬性。格式是 attribute_name=value。

key

識別作業中使用的包裝金鑰。格式是 key=ID 對組。在所有加密命令中 key 屬性為必要。

當您AWS KMS key在加密命令中使用時，金鑰屬性的值可以是金鑰 ID、金鑰 ARN、別名 ARN、別名 ARN。如需AWS KMS金鑰識別碼的詳細資訊，請參閱AWS Key Management Service開發人員指南中的金鑰識別碼

當主密鑰提供者不是解密命令時，密鑰屬性是必需的AWS KMS。在解密下加密之資料的命令中不允許使用金鑰屬性AWS KMS key。

您可以在每個--master-keys參數值中指定多個關鍵屬性。不過，任何 provider、region 和 profile 屬性都會套用至參數值中的所有主金鑰。若要使用不同的屬性值來指定主金鑰，請在命令中使用多個 --master-keys 參數。

provider (提供者)

識別主金鑰提供者。格式是 provider=ID 對組。預設值 aws-kms 代表 AWS KMS。只有當主金鑰提供者不是 AWS KMS 時，此屬性才為必要。

region

識別AWS 區域的AWS KMS key。此屬性僅對AWS KMS keys。僅在 key 識別符未指定區域時才會用到，否則會忽略。使用此屬性時，它會覆寫 AWS CLI 命名設定檔中的預設區域。

profile

識別 AWS CLI 命名描述檔。此屬性僅對AWS KMS keys。只有在命令中的 key 識別符未指定區域，且沒有 region 屬性時，才會使用設定檔中的區域。

進階參數

--algorithm

指定替代演算法套件。此參數是選用的，僅在加密命令中有效。

如果您省略此參數，則AWS加密 CLI 會使用 1.8 版中AWS Encryption SDK引入的其中一個預設演算法套件。 x. 這兩種預設演算法都使用 AES-GCM 搭配 HKDF、ECDSA 簽章和 256 位元加密金鑰。一個人使用關鍵承諾; 一個沒有。預設演算法套件的選擇取決於命令的承諾原則。

對於大多數加密操作，建議使用默認算法套件。如需有效值的清單，請參閱 ReName 文件中的algorithm參數值。

--frame-length

使用指定的框架長度建立輸出。此參數是選用的，僅在加密命令中有效。

以位元組為單位輸入值。有效值為 0 和 1 — 2 ^ 31-1。0 值表示非框數據。預設值為 4096 (位元組)。

注意

盡可能使用框架數據。僅AWS Encryption SDK支援舊版使用的非框架資料。的某些語言實作仍然AWS Encryption SDK可以產生非框架加密文字。所有支持的語言實現都可以解密框架和非框加密文本。

--max-length

代表從加密訊息讀取的最大框架大小 (或無框架訊息的最大內容長度)，以位元組為單位。此參數是選用的，僅在解密命令中有效。旨在避免您解密非常大型的惡意加密文字。

以位元組為單位輸入值。如果忽略此參數，解密時AWS Encryption SDK不會限制框架大小。

--caching

啟用資料金鑰快取功能，可重複使用資料金鑰，而非為每個輸入檔案產生新的資料金鑰。此參數支援進階案例。使用此功能前，請務必先閱讀資料金鑰快取文件。

--caching 參數具有下列屬性。

capacity (必要)

決定快取中的項目數上限。

最小值為 1。沒有最大數值。

max_age (必要)

決定使用快取項目的時間長度 (以秒為單位)，從這些項目新增至快取時間開始。

輸入大於 0 的數值。沒有最大數值。

最大消息 _ 加密（可選）

決定快取項目可以加密的最大訊息數。

有效值為 1 至 2 ^ 32。預設值為 2^32 (訊息)。

最大字節加密（可選）

決定快取項目可以加密的最大位元組數。

有效值為 0 和 1 — 2 ^ 63-1。預設值為 2^63-1 (訊息)。值為 0 只允許您在加密空的訊息字串時使用資料金鑰快取。