Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS customer master
* key (CMK), see 'Viewing Keys' at
* http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
*
*/
public class BasicEncryptionKeyringExample {
private static final byte[] EXAMPLE_DATA = "Hello World".getBytes(StandardCharsets.UTF_8);
public static void main(final String[] args) {
final String keyArn = args[0];
encryptAndDecryptWithKeyring(keyArn);
}
public static void encryptAndDecryptWithKeyring(final String keyArn) {
// 1. Instantiate the SDK
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto =
AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput =
CreateAwsKmsMultiKeyringInput.builder().generator(keyArn).build();
final IKeyring kmsKeyring = materialProviders.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create an encryption context
// We recommend using an encryption context whenever possible
// to protect integrity. This sample uses placeholder values.
// For more information see:
// blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management
final Map encryptionContext =
Collections.singletonMap("ExampleContextKey", "ExampleContextValue");
// 4. Encrypt the data
final CryptoResult encryptResult =
crypto.encryptData(kmsKeyring, EXAMPLE_DATA, encryptionContext);
final byte[] ciphertext = encryptResult.getResult();
// 5. Decrypt the data
final CryptoResult decryptResult =
crypto.decryptData(
kmsKeyring,
ciphertext,
// Verify that the encryption context in the result contains the
// encryption context supplied to the encryptData method
encryptionContext);
// 6. Verify that the decrypted plaintext matches the original plaintext
assert Arrays.equals(decryptResult.getResult(), EXAMPLE_DATA);
}
}
```
## 加密和解密位元組串流
下列範例示範如何使用 AWS Encryption SDK 來加密和解密位元組串流。
此範例使用[原始 AES keyring](use-raw-aes-keyring.md)。
加密時，此範例會使用 `AwsCrypto.builder() .withEncryptionAlgorithm()`方法來指定沒有[數位簽章的](concepts.md#digital-sigs)演算法套件。解密時，為了確保加密文字未簽署，此範例會使用 `createUnsignedMessageDecryptingStream()`方法。如果遇到具有數位簽章的加密文字，則 `createUnsignedMessageDecryptingStream()`方法會失敗。
如果您使用包含數位簽章的預設演算法套件進行加密，請改用 `createDecryptingStream()`方法，如下一個範例所示。
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.keyrings;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoAlgorithm;
import com.amazonaws.encryptionsdk.CryptoInputStream;
import com.amazonaws.encryptionsdk.jce.JceMasterKey;
import com.amazonaws.util.IOUtils;
import software.amazon.cryptography.materialproviders.IKeyring;
import software.amazon.cryptography.materialproviders.MaterialProviders;
import software.amazon.cryptography.materialproviders.model.AesWrappingAlg;
import software.amazon.cryptography.materialproviders.model.CreateRawAesKeyringInput;
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.security.SecureRandom;
import java.util.Collections;
import java.util.Map;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
/**
*
* Encrypts and then decrypts a file under a random key.
*
*
* Arguments:
*
*
Name of file containing plaintext data to encrypt
*
*
*
* This program demonstrates using a standard Java {@link SecretKey} object as a {@link IKeyring} to
* encrypt and decrypt streaming data.
*/
public class FileStreamingKeyringExample {
private static String srcFile;
public static void main(String[] args) throws IOException {
srcFile = args[0];
// In this example, we generate a random key. In practice,
// you would get a key from an existing store
SecretKey cryptoKey = retrieveEncryptionKey();
// Create a Raw Aes Keyring using the random key and an AES-GCM encryption algorithm
final MaterialProviders materialProviders = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawAesKeyringInput keyringInput = CreateRawAesKeyringInput.builder()
.wrappingKey(ByteBuffer.wrap(cryptoKey.getEncoded()))
.keyNamespace("Example")
.keyName("RandomKey")
.wrappingAlg(AesWrappingAlg.ALG_AES128_GCM_IV12_TAG16)
.build();
IKeyring keyring = materialProviders.CreateRawAesKeyring(keyringInput);
// Instantiate the SDK.
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
// This example encrypts with an algorithm suite that doesn't include signing for faster decryption,
// since this use case assumes that the contexts that encrypt and decrypt are equally trusted.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY)
.build();
// Create an encryption context to identify the ciphertext
Map context = Collections.singletonMap("Example", "FileStreaming");
// Because the file might be too large to load into memory, we stream the data, instead of
//loading it all at once.
FileInputStream in = new FileInputStream(srcFile);
CryptoInputStream encryptingStream = crypto.createEncryptingStream(keyring, in, context);
FileOutputStream out = new FileOutputStream(srcFile + ".encrypted");
IOUtils.copy(encryptingStream, out);
encryptingStream.close();
out.close();
// Decrypt the file. Verify the encryption context before returning the plaintext.
// Since the data was encrypted using an unsigned algorithm suite, use the recommended
// createUnsignedMessageDecryptingStream method, which only accepts unsigned messages.
in = new FileInputStream(srcFile + ".encrypted");
CryptoInputStream decryptingStream = crypto.createUnsignedMessageDecryptingStream(keyring, in);
// Does it contain the expected encryption context?
if (!"FileStreaming".equals(decryptingStream.getCryptoResult().getEncryptionContext().get("Example"))) {
throw new IllegalStateException("Bad encryption context");
}
// Write the plaintext data to disk.
out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();
out.close();
}
/**
* In practice, this key would be saved in a secure location.
* For this demo, we generate a new random key for each operation.
*/
private static SecretKey retrieveEncryptionKey() {
SecureRandom rnd = new SecureRandom();
byte[] rawKey = new byte[16]; // 128 bits
rnd.nextBytes(rawKey);
return new SecretKeySpec(rawKey, "AES");
}
}
```
## 使用多重 keyring 加密和解密位元組串流
下列範例示範如何 AWS Encryption SDK 搭配[多 keyring](use-multi-keyring.md) 使用 。使用多重 keyring 來加密資料時，其任何 keyring 中的任何包裝金鑰均可以解密該資料。此範例使用 [AWS KMS keyring](use-kms-keyring.md) 和[原始 RSA keyring](use-raw-rsa-keyring.md) 作為子 keyring。
此範例使用[預設演算法套件](supported-algorithms.md)加密，其中包含[數位簽章](concepts.md#digital-sigs)。串流時， 會在完整性檢查之後，但在驗證數位簽章之前 AWS Encryption SDK 發行純文字。為了避免在驗證簽章之前使用純文字，此範例會緩衝純文字，並只在解密和驗證完成時寫入磁碟。
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.keyrings;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoOutputStream;
import com.amazonaws.util.IOUtils;
import software.amazon.cryptography.materialproviders.IKeyring;
import software.amazon.cryptography.materialproviders.MaterialProviders;
import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput;
import software.amazon.cryptography.materialproviders.model.CreateMultiKeyringInput;
import software.amazon.cryptography.materialproviders.model.CreateRawRsaKeyringInput;
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
import software.amazon.cryptography.materialproviders.model.PaddingScheme;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.nio.ByteBuffer;
import java.security.GeneralSecurityException;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.util.Collections;
/**
*
* Encrypts a file using both AWS KMS Key and an asymmetric key pair.
*
*
* Arguments:
*
*
Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS key,
* see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
*
*
Name of file containing plaintext data to encrypt
*
*
* You might use AWS Key Management Service (AWS KMS) for most encryption and decryption operations, but
* still want the option of decrypting your data offline independently of AWS KMS. This sample
* demonstrates one way to do this.
*
* The sample encrypts data under both an AWS KMS key and an "escrowed" RSA key pair
* so that either key alone can decrypt it. You might commonly use the AWS KMS key for decryption. However,
* at any time, you can use the private RSA key to decrypt the ciphertext independent of AWS KMS.
*
* This sample uses the RawRsaKeyring to generate a RSA public-private key pair
* and saves the key pair in memory. In practice, you would store the private key in a secure offline
* location, such as an offline HSM, and distribute the public key to your development team.
*/
public class EscrowedEncryptKeyringExample {
private static ByteBuffer publicEscrowKey;
private static ByteBuffer privateEscrowKey;
public static void main(final String[] args) throws Exception {
// This sample generates a new random key for each operation.
// In practice, you would distribute the public key and save the private key in secure
// storage.
generateEscrowKeyPair();
final String kmsArn = args[0];
final String fileName = args[1];
standardEncrypt(kmsArn, fileName);
standardDecrypt(kmsArn, fileName);
escrowDecrypt(fileName);
}
private static void standardEncrypt(final String kmsArn, final String fileName) throws Exception {
// Encrypt with the KMS key and the escrowed public key
// 1. Instantiate the SDK
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
.generator(kmsArn)
.build();
IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create the Raw Rsa Keyring with Public Key.
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.build();
IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 4. Create the multi-keyring.
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(kmsKeyring)
.childKeyrings(Collections.singletonList(rsaPublicKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
// 5. Encrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName);
final FileOutputStream out = new FileOutputStream(fileName + ".encrypted");
final CryptoOutputStream encryptingStream = crypto.createEncryptingStream(multiKeyring, out);
IOUtils.copy(in, encryptingStream);
in.close();
encryptingStream.close();
}
private static void standardDecrypt(final String kmsArn, final String fileName) throws Exception {
// Decrypt with the AWS KMS key and the escrow public key.
// 1. Instantiate the SDK.
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
.generator(kmsArn)
.build();
IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create the Raw Rsa Keyring with Public Key.
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.build();
IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 4. Create the multi-keyring.
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(kmsKeyring)
.childKeyrings(Collections.singletonList(rsaPublicKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
// 5. Decrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName + ".encrypted");
final FileOutputStream out = new FileOutputStream(fileName + ".decrypted");
// Since we are using a signing algorithm suite, we avoid streaming decryption directly to the output file,
// to ensure that the trailing signature is verified before writing any untrusted plaintext to disk.
final ByteArrayOutputStream plaintextBuffer = new ByteArrayOutputStream();
final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(multiKeyring, plaintextBuffer);
IOUtils.copy(in, decryptingStream);
in.close();
decryptingStream.close();
final ByteArrayInputStream plaintextReader = new ByteArrayInputStream(plaintextBuffer.toByteArray());
IOUtils.copy(plaintextReader, out);
out.close();
}
private static void escrowDecrypt(final String fileName) throws Exception {
// You can decrypt the stream using only the private key.
// This method does not call AWS KMS.
// 1. Instantiate the SDK
final AwsCrypto crypto = AwsCrypto.standard();
// 2. Create the Raw Rsa Keyring with Private Key.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.privateKey(privateEscrowKey)
.build();
IKeyring escrowPrivateKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 3. Decrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName + ".encrypted");
final FileOutputStream out = new FileOutputStream(fileName + ".deescrowed");
final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(escrowPrivateKeyring, out);
IOUtils.copy(in, decryptingStream);
in.close();
decryptingStream.close();
}
private static void generateEscrowKeyPair() throws GeneralSecurityException {
final KeyPairGenerator kg = KeyPairGenerator.getInstance("RSA");
kg.initialize(4096); // Escrow keys should be very strong
final KeyPair keyPair = kg.generateKeyPair();
publicEscrowKey = RawRsaKeyringExample.getPEMPublicKey(keyPair.getPublic());
privateEscrowKey = RawRsaKeyringExample.getPEMPrivateKey(keyPair.getPrivate());
}
}
```
# 適用於 JavaScript 的 AWS Encryption SDK
適用於 JavaScript 的 AWS Encryption SDK 旨在為在 JavaScript 中撰寫 Web 瀏覽器應用程式的開發人員或在 Node.js 中撰寫 Web 伺服器應用程式的開發人員提供用戶端加密程式庫。
與 的所有實作一樣 AWS Encryption SDK， 適用於 JavaScript 的 AWS Encryption SDK 提供進階資料保護功能。這些功能包括[信封加密](concepts.md#envelope-encryption)、額外的驗證資料 (AAD) 以及安全、已認證的對稱金鑰[演算法套件](concepts.md#crypto-algorithm)，例如 256 位元 AES-GCM 搭配金鑰衍生和簽署。
根據語言的限制， 的所有特定語言實作 AWS Encryption SDK 都設計為可互通。如需 JavaScript 語言限制的詳細資訊，請參閱 [的相容性 適用於 JavaScript 的 AWS Encryption SDK](javascript-compatibility.md)。
**進一步了解**
+ 如需使用 進行程式設計的詳細資訊 適用於 JavaScript 的 AWS Encryption SDK，請參閱 GitHub 上的 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 儲存庫。
+ 如需程式設計範例，請參閱 [適用於 JavaScript 的 AWS Encryption SDK 範例](js-examples.md)和 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 儲存庫中的 [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) 和 [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) 模組。
+ 如需使用 適用於 JavaScript 的 AWS Encryption SDK 在 Web 應用程式中加密資料的真實範例，請參閱 AWS 安全部落格中的[如何使用 適用於 JavaScript 的 AWS Encryption SDK 和 Node.js 在瀏覽器中啟用加密](https://aws.amazon.com/blogs/security/how-to-enable-encryption-browser-aws-encryption-sdk-javascript-node-js/)。
**Topics**
+ [相容性](javascript-compatibility.md)
+ [安裝](javascript-installation.md)
+ [模組](javascript-modules.md)
+ [範例](js-examples.md)
# 的相容性 適用於 JavaScript 的 AWS Encryption SDK
適用於 JavaScript 的 AWS Encryption SDK 旨在與 的其他語言實作互通 AWS Encryption SDK。在大多數情況下，您可以使用 加密資料 適用於 JavaScript 的 AWS Encryption SDK ，並使用任何其他語言實作解密資料，包括 [AWS Encryption SDK 命令列界面](crypto-cli.md)。您也可以使用 適用於 JavaScript 的 AWS Encryption SDK 來解密 其他語言實作所產生的[加密訊息](concepts.md#message) AWS Encryption SDK。
不過，當您使用 時 適用於 JavaScript 的 AWS Encryption SDK，您需要注意 JavaScript 語言實作和 Web 瀏覽器中的一些相容性問題。
此外，使用不同的語言實作時，請務必設定相容的主金鑰提供者、主金鑰和 keyring。如需詳細資訊，請參閱[Keyring 相容性](choose-keyring.md#keyring-compatibility)。
## 適用於 JavaScript 的 AWS Encryption SDK 相容性
的 JavaScript 實作與其他語言實作 AWS Encryption SDK 不同，方式如下：
+ 的加密操作 適用於 JavaScript 的 AWS Encryption SDK 不會傳回非影格加密文字。不過， 適用於 JavaScript 的 AWS Encryption SDK 會解密 其他語言實作傳回的框架和非框架加密文字 AWS Encryption SDK。
+ 從 Node.js 版本 12.9.0 開始，Node.js 支援以下 RSA 金鑰包裝選項：
+ 具有 SHA1、SHA256、SHA384 或 SHA512 的 OAEP
+ 具有 SHA1 的 OAEP 和具有 SHA1 的 MGF1
+ PKCS1v15
+ 在版本 12.9.0 之前，Node.js 僅支援以下 RSA 金鑰包裝選項：
+ 具有 SHA1 的 OAEP 和具有 SHA1 的 MGF1
+ PKCS1v15
## 瀏覽器相容性
某些 Web 瀏覽器不支援 適用於 JavaScript 的 AWS Encryption SDK 所需的基本密碼編譯操作。您可以透過瀏覽器實作的 WebCrypto API 設定備用來彌補部分遺漏的操作。
**Web 瀏覽器限制**
下列限制為所有 Web 瀏覽器通用：
+ WebCrypto API 不支援 PKCS1v15 金鑰包裝。
+ 瀏覽器不支援 192 位元金鑰。
**必要的密碼編譯操作**
在 Web 瀏覽器中， 適用於 JavaScript 的 AWS Encryption SDK 需要下列操作。如果瀏覽器不支援這些操作，則它與 適用於 JavaScript 的 AWS Encryption SDK相容。
+ 瀏覽器必須包含 `crypto.getRandomValues()`，這是一種以密碼編譯方式產生隨機值的方法。如需支援 `crypto.getRandomValues()` 之 Web 瀏覽器版本的相關資訊，請參閱[我可以使用 crypto.getRandomValues() 嗎？](https://caniuse.com/#feat=getrandomvalues)。
**必要的備用**
適用於 JavaScript 的 AWS Encryption SDK 需要在 Web 瀏覽器中執行下列程式庫和操作。如果您支援不符合這些需求的 Web 瀏覽器，則必須設定備用。否則，嘗試 適用於 JavaScript 的 AWS Encryption SDK 搭配瀏覽器使用 將會失敗。
+ 會在 Web 應用程式中執行基本密碼編譯操作的 WebCrypto API，並非可在所有瀏覽器上使用。如需支援 Web 密碼編譯的 Web 瀏覽器版本的相關資訊，請參閱[我可以使用 Web 密碼編譯嗎？](https://caniuse.com/#feat=cryptography)。
+ Safari Web 瀏覽器的現代版本不支援 AWS Encryption SDK 所需的零位元組 AES-GCM 加密。如果瀏覽器實作 WebCrypto API，但無法使用 AES-GCM 加密零位元組，則 只會 適用於 JavaScript 的 AWS Encryption SDK 使用備用程式庫進行零位元組加密。它會使用 WebCrypto API 進行所有其他操作。
若要設定任一限制的備用，請將下列陳述式新增至您的程式碼。在 [configureFallback](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/web-crypto-backend/src/backend-factory.ts#L78) 函數中，指定支援遺漏功能的程式庫。下列範例會使用 Microsoft Research JavaScript Cryptography Library (`msrcrypto`)，但是您可以以相容的程式庫取代它。如需完整範例，請參閱 [fallback.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/fallback.ts)。
```
import { configureFallback } from '@aws-crypto/client-browser'
configureFallback(msrCrypto)
```
# 安裝 適用於 JavaScript 的 AWS Encryption SDK
適用於 JavaScript 的 AWS Encryption SDK 包含相互依存模組的集合。模組中的數個只是設計要一起運作的模組集合。部分模組是專為獨立運作而設計。一些模組為所有實作所需；一些模組則僅用於特殊情況。如需有關 AWS Encryption SDK 適用於 JavaScript 的 中模組的資訊，請參閱 [中的模組 適用於 JavaScript 的 AWS Encryption SDK](javascript-modules.md)和 GitHub 上 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules) 儲存庫中每個模組中的 `README.md` 檔案。
**注意**
所有 適用於 JavaScript 的 AWS Encryption SDK 早於 2.0.0 的 版本都處於[end-of-support階段](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)。
您可以從 2.0.*x* 版和更新版本安全地更新至最新版本的 ， 適用於 JavaScript 的 AWS Encryption SDK 而不需要變更任何程式碼或資料。不過，2.0.*x* 版中引進[的新安全功能](about-versions.md#version-2)無法回溯相容。若要從 1.7.*x* 之前的版本更新至 2.0.*x* 及更新版本，您必須先更新至最新的 1 適用於 JavaScript 的 AWS Encryption SDK.*x* 版本。如需詳細資訊，請參閱[遷移您的 AWS Encryption SDK](migration.md)。
若要安裝模組，請使用 [npm 套件管理工具](https://www.npmjs.com/get-npm)。
例如，若要安裝`client-node`模組，其中包含使用 Node.js 適用於 JavaScript 的 AWS Encryption SDK 中的 進行程式設計所需的所有模組，請使用下列命令。
```
npm install @aws-crypto/client-node
```
若要安裝`client-browser`模組，其中包含在瀏覽器 適用於 JavaScript 的 AWS Encryption SDK 中使用 進行程式設計所需的所有模組，請使用下列命令。
```
npm install @aws-crypto/client-browser
```
如需如何使用 的工作範例 適用於 JavaScript 的 AWS Encryption SDK，請參閱 GitHub 上 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 儲存庫中 `example-node`和 `example-browser`模組中的範例。
# 中的模組 適用於 JavaScript 的 AWS Encryption SDK
中的模組 適用於 JavaScript 的 AWS Encryption SDK 可讓您輕鬆地安裝專案所需的程式碼。
## JavaScript Node.js 的模組
[client-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-node)
包含使用 Node.js 適用於 JavaScript 的 AWS Encryption SDK 中的 進行程式設計所需的所有模組。
[caching-materials-manager-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-node)
匯出支援 Node 適用於 JavaScript 的 AWS Encryption SDK .js 中 [資料金鑰快取](data-key-caching.md)功能的函數。
[decrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-node)
匯出會解密並驗證代表資料和資料流的加密訊息的函數。包含在 `client-node` 模組中。
[encrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-node)
匯出加密和簽署不同類型資料的函數。包含在 `client-node` 模組中。
[example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node)
在 Node.js 適用於 JavaScript 的 AWS Encryption SDK 中使用 匯出程式設計的工作範例。包括不同類型的 keyring 和不同類型資料的範例。
[hkdf-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/hkdf-node)
匯出 Node.js 適用於 JavaScript 的 AWS Encryption SDK 中 在特定演算法套件中使用的 [HMAC 型金鑰衍生函數](https://en.wikipedia.org/wiki/HKDF) (HKDF)。瀏覽器 適用於 JavaScript 的 AWS Encryption SDK 中的 使用 WebCrypto API 中的原生 HKDF 函數。
[integration-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-node)
定義測試，以驗證 Node.js 適用於 JavaScript 的 AWS Encryption SDK 中的 是否與 的其他語言實作相容 AWS Encryption SDK。
[kms-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-node)
匯出支援 Node.js 中 AWS KMS keyring 的函數。
[raw-aes-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-node)
匯出在 Node.js 中支援[原始 AES keyring](use-raw-aes-keyring.md) 的函數。
[raw-rsa-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-node)
匯出在 Node.js 中支援[原始 RSA keyring](use-raw-rsa-keyring.md) 的函數。
## JavaScript 瀏覽器的模組
[client-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-browser)
包括您在瀏覽器 適用於 JavaScript 的 AWS Encryption SDK 中使用 進行程式設計所需的所有模組。
[caching-materials-manager-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-browser)
匯出支援瀏覽器中 JavaScript [資料金鑰快取](data-key-caching.md)功能的函數。
[decrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-browser)
匯出會解密並驗證代表資料和資料流的加密訊息的函數。
[encrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-browser)
匯出加密和簽署不同類型資料的函數。
[example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser)
在瀏覽器 適用於 JavaScript 的 AWS Encryption SDK 中使用 進行程式設計的工作範例。包括不同類型的 keyring 和不同類型資料的範例。
[integration-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-browser)
定義測試，以驗證瀏覽器中的 適用於 JAVA 的 AWS Encryption SDK指令碼是否與 的其他語言實作相容 AWS Encryption SDK。
[kms-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-browser)
匯出在瀏覽器中支援 [AWS KMS keyring ](use-kms-keyring.md)的函數。
[raw-aes-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-browser)
匯出在瀏覽器中支援[原始 AES keyring](use-raw-aes-keyring.md) 的函數。
[raw-rsa-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-browser)
匯出在瀏覽器中支援[原始 RSA keyring](use-raw-rsa-keyring.md) 的函數。
## 適用於所有實作的模組
[cache-material](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/cache-material)
支援[資料金鑰快取](data-key-caching.md)功能。提供用於組合隨每個資料金鑰快取的密碼編譯資料的程式碼。
[kms-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring)
匯出支援 [KMS keyring](use-kms-keyring.md) 的函數。
[material-management](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/material-management)
實作[密碼編譯資料管理員](concepts.md#crypt-materials-manager) (CMM)。
[raw-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-keyring)
匯出原始 AES 和 RSA keyring 所需的函數。
[serialize](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/serialize)
匯出 SDK 用來序列化其輸出的函數。
[web-crypto-backend](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/web-crypto-backend)
匯出在瀏覽器的 中使用 WebCrypto API 適用於 JavaScript 的 AWS Encryption SDK 的函數。
# 適用於 JavaScript 的 AWS Encryption SDK 範例
以下範例說明如何使用 適用於 JavaScript 的 AWS Encryption SDK 來加密和解密資料。
您可以在 GitHub 適用於 JavaScript 的 AWS Encryption SDK 的 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 儲存庫的 [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) 和 [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) 模組中找到更多使用 的範例。當您安裝 `client-browser` 或 `client-node` 模組時，不會安裝這些範例模組。
**請參閱完整的程式碼範例**：節點：[kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_simple.ts)，瀏覽器：[kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/kms_simple.ts)
**Topics**
+ [使用 AWS KMS keyring 加密資料](#javascript-example-encrypt)
+ [使用 AWS KMS keyring 解密資料](#javascript-example-decrypt)
## 使用 AWS KMS keyring 加密資料
下列範例示範如何使用 適用於 JavaScript 的 AWS Encryption SDK 來加密和解密短字串或位元組陣列。
此範例具有 [AWS KMS keyring](use-kms-keyring.md)，這是一種 keyring，使用 AWS KMS key 來產生和加密資料金鑰。如需建立 的說明 AWS KMS key，請參閱《 *AWS Key Management Service 開發人員指南*》中的[建立金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)。如需在 AWS KMS keyring AWS KMS keys 中識別 的說明，請參閱 [在 AWS KMS keyring AWS KMS keys 中識別](use-kms-keyring.md#kms-keyring-id)
步驟 1：設定承諾政策。
從 1.7.*x* 版開始 適用於 JavaScript 的 AWS Encryption SDK，您可以在呼叫執行個體化 AWS Encryption SDK 用戶端的新 `buildClient`函數時設定承諾政策。`buildClient` 函數會採用列舉值來代表您的承諾政策。它會傳回更新 `encrypt`和 `decrypt`函數，在您加密和解密時強制執行您的承諾政策。
下列範例使用 `buildClient`函數來指定[預設承諾政策](migrate-commitment-policy.md) `REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。您也可以使用 `buildClient`來限制加密訊息中的加密資料金鑰數量。如需詳細資訊，請參閱[限制加密的資料金鑰](configure.md#config-limit-keys)。
```
import {
KmsKeyringBrowser,
KMS,
getClient,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
步驟 2：建構 keyring。
建立用於加密的 AWS KMS keyring。
使用 AWS KMS keyring 加密時，您必須指定*產生器金鑰*，也就是 AWS KMS key 用來產生純文字資料金鑰並將其加密的 。您也可以指定零個或多個*額外的金鑰*來加密相同的純文字資料金鑰。keyring 會針對 keyring AWS KMS key 中的每個 傳回純文字資料金鑰和該資料金鑰的加密複本，包括產生器金鑰。若要解密資料，您需要解密任何一個加密的資料金鑰。
若要在 中指定加密 keyring AWS KMS keys 的 適用於 JavaScript 的 AWS Encryption SDK，您可以使用[任何支援的 AWS KMS 金鑰識別符](use-kms-keyring.md#kms-keyring-id)。此範例會使用產生器金鑰 (依[別名 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN) 識別)，以及一個額外的金鑰 (依[金鑰 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) 識別)。
如果您計劃重複使用 AWS KMS keyring 進行解密，則必須使用金鑰 ARNs 來識別 keyring AWS KMS keys 中的 。
執行此程式碼之前，請將範例 AWS KMS key 識別符取代為有效的識別符。您必須具有在 keyring 中[使用 AWS KMS keys所需的許可](use-kms-keyring.md#kms-keyring-permissions)。
首先提供您的登入資料給瀏覽器。 適用於 JavaScript 的 AWS Encryption SDK 範例會使用 [webpack.DefinePlugin](https://webpack.js.org/plugins/define-plugin/)，它會以您的實際登入資料取代登入資料常數。但是您可以使用任何方法來提供您的登入資料。然後，使用登入資料來建立 AWS KMS 用戶端。
```
declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken
}
})
```
接著，指定產生器金鑰和其他金鑰 AWS KMS keys 的 。然後，使用 AWS KMS 用戶端和 建立 AWS KMS keyring AWS KMS keys。
```
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds })
```
```
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
```
步驟 3：設定加密內容。
[加密內容](concepts.md#encryption-context)是一種任意、非私密額外驗證資料。當您在加密時提供加密內容時， AWS Encryption SDK 密碼編譯會將加密內容繫結至加密文字，因此需要相同的加密內容才能解密資料。使用加密內容是選用的，但我們建議使用它作為最佳實務。
建立包含加密內容對的簡單物件。每個對組中的索引鍵和值必須是字串。
```
const context = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2'
}
```
```
const context = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2'
}
```
步驟 4：加密資料。
若要加密純文字資料，請呼叫 `encrypt` 函數。傳入 AWS KMS keyring、純文字資料和加密內容。
`encrypt` 函數會傳回[加密訊息](concepts.md#message) (`result`)，其中包含加密的資料、加密的資料金鑰和重要的中繼資料，包括加密內容和簽章。
您可以使用任何支援的程式設計語言 AWS Encryption SDK 的 [來解密此加密訊息](#javascript-example-decrypt)。
```
const plaintext = new Uint8Array([1, 2, 3, 4, 5])
const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
```
```
const plaintext = 'asdf'
const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
```
## 使用 AWS KMS keyring 解密資料
您可以使用 適用於 JavaScript 的 AWS Encryption SDK 解密加密的訊息並復原原始資料。
在此範例中，我們會解密我們在 [使用 AWS KMS keyring 加密資料](#javascript-example-encrypt) 範例中加密的資料。
步驟 1：設定承諾政策。
從 1.7.*x* 版開始 適用於 JavaScript 的 AWS Encryption SDK，您可以在呼叫執行個體化 AWS Encryption SDK 用戶端的新 `buildClient`函數時設定承諾政策。`buildClient` 函數會採用列舉值來代表您的承諾政策。它會傳回更新 `encrypt`和 `decrypt`函數，在您加密和解密時強制執行您的承諾政策。
下列範例使用 `buildClient`函數來指定[預設承諾政策](migrate-commitment-policy.md) `REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。您也可以使用 `buildClient`來限制加密訊息中的加密資料金鑰數量。如需詳細資訊，請參閱[限制加密的資料金鑰](configure.md#config-limit-keys)。
```
import {
KmsKeyringBrowser,
KMS,
getClient,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
步驟 2：建構 keyring。
若要解密資料，請傳入`encrypt`函數傳回的[加密訊息](concepts.md#message) (`result`)。加密的訊息包括加密的資料、加密的資料金鑰和重要的中繼資料，包括加密內容和簽章。
解密時，您還必須指定 [AWS KMS keyring](use-kms-keyring.md)。您可以使用用來加密資料或不同 keyring 的相同 keyring。若要成功，解密 keyring AWS KMS key 中至少有一個必須能夠解密加密訊息中的其中一個加密資料金鑰。由於不會產生任何資料金鑰，您不需要在解密 keyring 中指定產生器金鑰。如果您這麼做，則會以相同方式處理產生器金鑰和額外金鑰。
若要在 中指定解密 keyring AWS KMS key 的 適用於 JavaScript 的 AWS Encryption SDK，您必須使用[金鑰 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)。否則， AWS KMS key 就無法辨識 。如需在 AWS KMS keyring AWS KMS keys 中識別 的說明，請參閱 [在 AWS KMS keyring AWS KMS keys 中識別](use-kms-keyring.md#kms-keyring-id)
如果您使用相同的 keyring 來加密和解密，請使用金鑰 ARNs 來識別 keyring AWS KMS keys 中的 。
在此範例中，我們建立的 keyring 只包含加密 keyring AWS KMS keys 中的其中一個 。執行此程式碼之前，請將範例金鑰 ARN 換成有效的金鑰 ARN。您必須具有 AWS KMS key上的 `kms:Decrypt` 許可。
首先提供您的登入資料給瀏覽器。 適用於 JavaScript 的 AWS Encryption SDK 範例會使用 [webpack.DefinePlugin](https://webpack.js.org/plugins/define-plugin/)，它會以您的實際登入資料取代登入資料常數。但是您可以使用任何方法來提供您的登入資料。然後，使用登入資料來建立 AWS KMS 用戶端。
```
declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken
}
})
```
接著，使用 AWS KMS 用戶端建立 AWS KMS keyring。此範例僅使用 AWS KMS keys 來自加密 keyring 的其中一個 。
```
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringBrowser({ clientProvider, keyIds })
```
```
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ keyIds })
```
步驟 3：解密資料。
接下來，呼叫 `decrypt` 函數。傳入您剛建立的解密 keyring (`keyring`) 和`encrypt`函數傳回的[加密訊息](concepts.md#message) (`result`)。 AWS Encryption SDK 使用 keyring 來解密其中一個加密的資料金鑰。然後它會使用純文字資料金鑰來解密資料。
如果呼叫成功，`plaintext` 欄位會包含純文字 (已解密) 資料。`messageHeader` 欄位包含有關解密程序的中繼資料，包括用來解密資料的加密內容。
```
const { plaintext, messageHeader } = await decrypt(keyring, result)
```
```
const { plaintext, messageHeader } = await decrypt(keyring, result)
```
步驟 4：驗證加密內容。
用來解密資料的[加密內容](concepts.md#encryption-context)包含在 `decrypt` 函數傳回的訊息標頭 (`messageHeader`) 中。在您的應用程式傳回純文字資料之前，請確認您在加密時所提供的加密內容包含在解密時所使用的加密內容中。不相符可能表示資料遭到篡改，或您沒有解密正確的加密文字。
驗證加密內容時，請勿要求完全相符。使用加密演算法搭配簽署時，[密碼編譯資料管理員](concepts.md#crypt-materials-manager) (CMM) 會在加密訊息之前，將公有簽署金鑰新增至加密內容。但是，您提交的所有加密內容對都應該包含在傳回的加密內容中。
首先，從訊息標頭取得加密內容。然後，確認原始加密內容 (`context`) 中的每個索引鍵值對符合傳回的加密內容 (`encryptionContext`) 中的索引鍵值對。
```
const { encryptionContext } = messageHeader
Object
.entries(context)
.forEach(([key, value]) => {
if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
```
```
const { encryptionContext } = messageHeader
Object
.entries(context)
.forEach(([key, value]) => {
if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
```
如果加密內容檢查成功，您可以傳回純文字資料。
# 適用於 Python 的 AWS Encryption SDK
本主題說明如何安裝及使用 適用於 Python 的 AWS Encryption SDK。如需使用 進行程式設計的詳細資訊 適用於 Python 的 AWS Encryption SDK，請參閱 GitHub 上的 [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/) 儲存庫。如需 API 文件，請參閱[閱讀相關文件](https://aws-encryption-sdk-python.readthedocs.io/en/latest/)。
**Topics**
+ [先決條件](#python-prerequisites)
+ [安裝](#python-installation)
+ [範例](python-example-code.md)
## 先決條件
安裝 之前 適用於 Python 的 AWS Encryption SDK，請確定您有下列先決條件。
**支援的 Python 版本**
3.2.0 版和更新 適用於 Python 的 AWS Encryption SDK 版本需要 Python 3.8 或更新版本。
[AWS 密碼編譯材料提供者程式庫](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL) 是 4.*x* 版中 適用於 Python 的 AWS Encryption SDK 引入之 的選用相依性。如果您想要安裝 MPL，則必須使用 Python 3.11 或更新版本。
舊版 AWS Encryption SDK 支援 Python 2.7 和 Python 3.4 及更新版本，但建議您使用最新版本的 AWS Encryption SDK。
若要下載 Python，請參閱 [Python 下載](https://www.python.org/downloads/)。
**適用於 Python 的 pip 安裝工具**
`pip` 包含在 Python 3.6 和更新版本中，但您可能想要升級。如需升級或安裝 的詳細資訊`pip`，請參閱 `pip` 文件中的[安裝](https://pip.pypa.io/en/latest/installation/)。
## 安裝
安裝最新版本的 適用於 Python 的 AWS Encryption SDK。
**注意**
所有 適用於 Python 的 AWS Encryption SDK 早於 3.0.0 的 版本都處於[end-of-support階段](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)。
您可以從 2.0.*x* 版和更新版本安全地更新至最新版本的 ， AWS Encryption SDK 而不需要變更任何程式碼或資料。不過，2.0.*x* 版中引進[的新安全功能](about-versions.md#version-2)無法回溯相容。若要從 1.7.*x* 之前的版本更新至 2.0.*x* 及更新版本，您必須先更新至最新的 1 AWS Encryption SDK.*x* 版本。如需詳細資訊，請參閱[遷移您的 AWS Encryption SDK](migration.md)。
使用 `pip` 安裝 適用於 Python 的 AWS Encryption SDK，如下列範例所示。
**若要安裝最新版本**
```
pip install "aws-encryption-sdk[MPL]"
```
`[MPL]` 尾碼會安裝[AWS 密碼編譯物料提供者程式庫 ](https://github.com/aws/aws-cryptographic-material-providers-library)(MPL)。MPL 包含用於加密和解密資料的建構。MPL 是 4.*x* 版中 適用於 Python 的 AWS Encryption SDK 引入之 的選用相依性。我們強烈建議您安裝 MPL。不過，如果您不打算使用 MPL，您可以省略`[MPL]`尾碼。
如需使用 pip 來安裝及升級套件的詳細資訊，請參閱[安裝套件](https://packaging.python.org/tutorials/installing-packages/)。
在所有平台上 適用於 Python 的 AWS Encryption SDK 都需要[密碼編譯程式庫](https://cryptography.io/en/latest/) (pyca/cryptography)。所有版本的 `pip`會自動在 Windows 上安裝和建置程式`cryptography`庫。 `pip` 8.1 和更新版本會自動在 Linux `cryptography`上安裝和建置 。如果您使用的是舊版 ，`pip`而且 Linux 環境沒有建置程式`cryptography`庫所需的工具，則需要安裝它們。如需詳細資訊，請參閱[在 Linux 上建置密碼編譯](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux)。
密碼[編譯](https://cryptography.io/en/latest/)相依性介於 2.5.0 和 3.3.2 之間的 適用於 Python 的 AWS Encryption SDK PIN 版本 1.10.0 和 2.5.0。其他版本的 適用於 Python 的 AWS Encryption SDK 安裝最新版本的密碼編譯。如果您需要 3.3.2 之後的加密版本，建議您使用最新的 主要版本。 適用於 Python 的 AWS Encryption SDK
如需 的最新開發版本 適用於 Python 的 AWS Encryption SDK，請前往 GitHub 中的 [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/) 儲存庫。
安裝 之後 適用於 Python 的 AWS Encryption SDK，請先查看本指南中的 [Python 範例程式碼](python-example-code.md)。
# 適用於 Python 的 AWS Encryption SDK 範例程式碼
下列範例示範如何使用 適用於 Python 的 AWS Encryption SDK 來加密和解密資料。
本節中的範例示範如何使用 4.*x* 版 適用於 Python 的 AWS Encryption SDK 搭配選用[的密碼編譯材料提供者程式庫](https://github.com/aws/aws-cryptographic-material-providers-library)相依性 (`aws-cryptographic-material-providers`)。若要檢視使用舊版或沒有材料提供者程式庫 (MPL) 的安裝範例，請在 GitHub 上 [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/) 儲存庫[的版本](https://github.com/aws/aws-encryption-sdk-python/releases)清單中尋找您的版本。
當您 適用於 Python 的 AWS Encryption SDK 搭配 MPL 使用 4.*x* 版時，它會使用 [keyring ](choose-keyring.md)來執行[信封加密](concepts.md#envelope-encryption)。 AWS Encryption SDK 提供與您在先前版本中使用的主金鑰提供者相容的 keyring。如需詳細資訊，請參閱[Keyring 相容性](choose-keyring.md#keyring-compatibility)。如需從主金鑰提供者遷移至 keyring 的範例，請參閱 GitHub 上儲存`aws-encryption-sdk-python`庫中的[遷移範例](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/migration)；
**Topics**
+ [Strings](#python-example-strings)
+ [位元組串流](#python-example-streams)
## 加密和解密字串
下列範例示範如何使用 AWS Encryption SDK 來加密和解密字串。此範例使用具有對稱加密 KMS 金鑰的 [AWS KMS keyring](use-kms-keyring.md)。
此範例會使用[預設承諾政策](migrate-commitment-policy.md) 來執行個體化 AWS Encryption SDK 用戶端`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。如需詳細資訊，請參閱[設定您的承諾政策](migrate-commitment-policy.md)。
```
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
This example sets up the KMS Keyring
The AWS KMS keyring uses symmetric encryption KMS keys to generate, encrypt and
decrypt data keys. This example creates a KMS Keyring and then encrypts a custom input EXAMPLE_DATA
with an encryption context. This example also includes some sanity checks for demonstration:
1. Ciphertext and plaintext data are not the same
2. Encryption context is correct in the decrypted message header
3. Decrypted plaintext value matches EXAMPLE_DATA
These sanity checks are for demonstration in the example only. You do not need these in your code.
AWS KMS keyrings can be used independently or in a multi-keyring with other keyrings
of the same or a different type.
"""
import boto3
from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders
from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig
from aws_cryptographic_material_providers.mpl.models import CreateAwsKmsKeyringInput
from aws_cryptographic_material_providers.mpl.references import IKeyring
from typing import Dict # noqa pylint: disable=wrong-import-order
import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy
EXAMPLE_DATA: bytes = b"Hello World"
def encrypt_and_decrypt_with_keyring(
kms_key_id: str
):
"""Demonstrate an encrypt/decrypt cycle using an AWS KMS keyring.
Usage: encrypt_and_decrypt_with_keyring(kms_key_id)
:param kms_key_id: KMS Key identifier for the KMS key you want to use for encryption and
decryption of your data keys.
:type kms_key_id: string
"""
# 1. Instantiate the encryption SDK client.
# This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
# which enforces that this client only encrypts using committing algorithm suites and enforces
# that this client will only decrypt encrypted messages that were created with a committing
# algorithm suite.
# This is the default commitment policy if you were to build the client as
# `client = aws_encryption_sdk.EncryptionSDKClient()`.
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# 2. Create a boto3 client for KMS.
kms_client = boto3.client('kms', region_name="us-west-2")
# 3. Optional: create encryption context.
# Remember that your encryption context is NOT SECRET.
encryption_context: Dict[str, str] = {
"encryption": "context",
"is not": "secret",
"but adds": "useful metadata",
"that can help you": "be confident that",
"the data you are handling": "is what you think it is",
}
# 4. Create your keyring
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
kms_key_id=kms_key_id,
kms_client=kms_client
)
kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring(
input=keyring_input
)
# 5. Encrypt the data with the encryptionContext.
ciphertext, _ = client.encrypt(
source=EXAMPLE_DATA,
keyring=kms_keyring,
encryption_context=encryption_context
)
# 6. Demonstrate that the ciphertext and plaintext are different.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert ciphertext != EXAMPLE_DATA, \
"Ciphertext and plaintext data are the same. Invalid encryption"
# 7. Decrypt your encrypted data using the same keyring you used on encrypt.
plaintext_bytes, _ = client.decrypt(
source=ciphertext,
keyring=kms_keyring,
# Provide the encryption context that was supplied to the encrypt method
encryption_context=encryption_context,
)
# 8. Demonstrate that the decrypted plaintext is identical to the original plaintext.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert plaintext_bytes == EXAMPLE_DATA, \
"Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
```
## 加密和解密位元組串流
下列範例示範如何使用 AWS Encryption SDK 來加密和解密位元組串流。此範例使用[原始 AES keyring](use-raw-aes-keyring.md)。
此範例會使用[預設承諾政策](migrate-commitment-policy.md) 來執行個體化 AWS Encryption SDK 用戶端`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。如需詳細資訊，請參閱[設定您的承諾政策](migrate-commitment-policy.md)。
```
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
This example demonstrates file streaming for encryption and decryption.
File streaming is useful when the plaintext or ciphertext file/data is too large to load into
memory. Therefore, the AWS Encryption SDK allows users to stream the data, instead of loading it
all at once in memory. In this example, we demonstrate file streaming for encryption and decryption
using a Raw AES keyring. However, you can use any keyring with streaming.
This example creates a Raw AES Keyring and then encrypts an input stream from the file
`plaintext_filename` with an encryption context to an output (encrypted) file `ciphertext_filename`.
It then decrypts the ciphertext from `ciphertext_filename` to a new file `decrypted_filename`.
This example also includes some sanity checks for demonstration:
1. Ciphertext and plaintext data are not the same
2. Encryption context is correct in the decrypted message header
3. Decrypted plaintext value matches EXAMPLE_DATA
These sanity checks are for demonstration in the example only. You do not need these in your code.
See raw_aes_keyring_example.py in the same directory for another raw AES keyring example
in the AWS Encryption SDK for Python.
"""
import filecmp
import secrets
from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders
from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig
from aws_cryptographic_material_providers.mpl.models import AesWrappingAlg, CreateRawAesKeyringInput
from aws_cryptographic_material_providers.mpl.references import IKeyring
from typing import Dict # noqa pylint: disable=wrong-import-order
import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy
def encrypt_and_decrypt_with_keyring(
plaintext_filename: str,
ciphertext_filename: str,
decrypted_filename: str
):
"""Demonstrate a streaming encrypt/decrypt cycle.
Usage: encrypt_and_decrypt_with_keyring(plaintext_filename
ciphertext_filename
decrypted_filename)
:param plaintext_filename: filename of the plaintext data
:type plaintext_filename: string
:param ciphertext_filename: filename of the ciphertext data
:type ciphertext_filename: string
:param decrypted_filename: filename of the decrypted data
:type decrypted_filename: string
"""
# 1. Instantiate the encryption SDK client.
# This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
# which enforces that this client only encrypts using committing algorithm suites and enforces
# that this client will only decrypt encrypted messages that were created with a committing
# algorithm suite.
# This is the default commitment policy if you were to build the client as
# `client = aws_encryption_sdk.EncryptionSDKClient()`.
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# 2. The key namespace and key name are defined by you.
# and are used by the Raw AES keyring to determine
# whether it should attempt to decrypt an encrypted data key.
key_name_space = "Some managed raw keys"
key_name = "My 256-bit AES wrapping key"
# 3. Optional: create encryption context.
# Remember that your encryption context is NOT SECRET.
encryption_context: Dict[str, str] = {
"encryption": "context",
"is not": "secret",
"but adds": "useful metadata",
"that can help you": "be confident that",
"the data you are handling": "is what you think it is",
}
# 4. Generate a 256-bit AES key to use with your keyring.
# In practice, you should get this key from a secure key management system such as an HSM.
# Here, the input to secrets.token_bytes() = 32 bytes = 256 bits
static_key = secrets.token_bytes(32)
# 5. Create a Raw AES keyring
# We choose to use a raw AES keyring, but any keyring can be used with streaming.
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput(
key_namespace=key_name_space,
key_name=key_name,
wrapping_key=static_key,
wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
)
raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring(
input=keyring_input
)
# 6. Encrypt the data stream with the encryptionContext
with open(plaintext_filename, 'rb') as pt_file, open(ciphertext_filename, 'wb') as ct_file:
with client.stream(
mode='e',
source=pt_file,
keyring=raw_aes_keyring,
encryption_context=encryption_context
) as encryptor:
for chunk in encryptor:
ct_file.write(chunk)
# 7. Demonstrate that the ciphertext and plaintext are different.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert not filecmp.cmp(plaintext_filename, ciphertext_filename), \
"Ciphertext and plaintext data are the same. Invalid encryption"
# 8. Decrypt your encrypted data stream using the same keyring you used on encrypt.
with open(ciphertext_filename, 'rb') as ct_file, open(decrypted_filename, 'wb') as pt_file:
with client.stream(
mode='d',
source=ct_file,
keyring=raw_aes_keyring,
encryption_context=encryption_context
) as decryptor:
for chunk in decryptor:
pt_file.write(chunk)
# 10. Demonstrate that the decrypted plaintext is identical to the original plaintext.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert filecmp.cmp(plaintext_filename, decrypted_filename), \
"Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
```
# AWS Encryption SDK for Rust
本主題說明如何安裝和使用 AWS Encryption SDK for Rust。如需使用 AWS Encryption SDK for Rust 進行程式設計的詳細資訊，請參閱 GitHub 上 aws-encryption-sdk 儲存庫的 [Rust](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/) 目錄。
AWS Encryption SDK for Rust 與 的一些其他程式設計語言實作有以下 AWS Encryption SDK 不同：
+ 不支援[資料金鑰快取](data-key-caching.md)。不過， AWS Encryption SDK for Rust 支援[AWS KMS 階層式 keyring](use-hierarchical-keyring.md)，這是替代的密碼編譯資料快取解決方案。
+ 不支援串流資料
AWS Encryption SDK for Rust 包含 2.0.*x* 版和更新版本中引入的所有安全功能 AWS Encryption SDK，以及 的其他語言實作。不過，如果您使用 AWS Encryption SDK for Rust 來解密由 2.0.*x* 前版本另一個語言實作所加密的資料 AWS Encryption SDK，您可能需要調整您的[承諾政策](concepts.md#commitment-policy)。如需詳細資訊，請參閱[如何設定您的承諾政策](migrate-commitment-policy.md#migrate-commitment-step1)。
AWS Encryption SDK for Rust 是 [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md) AWS Encryption SDK 中 的產品，這是一種正式的驗證語言，您可以在其中撰寫規格、實作它們的程式碼，以及測試它們的證明。結果是一個程式庫，可在架構中實作 的功能 AWS Encryption SDK ，以確保功能正確性。
**進一步了解**
+ 如需示範如何在 中設定選項的範例 AWS Encryption SDK，例如指定替代演算法套件、限制加密的資料金鑰，以及使用 AWS KMS 多區域金鑰，請參閱 [設定 AWS Encryption SDK](configure.md)。
+ 如需示範如何設定和使用 AWS Encryption SDK for Rust 的範例，請參閱 GitHub 上 aws-encryption-sdk 儲存庫中的 [Rust 範例](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples)。
**Topics**
+ [先決條件](#prerequisites-rust)
+ [安裝](#rust-installation)
+ [範例](rust-examples.md)
## 先決條件
在安裝 AWS Encryption SDK for Rust 之前，請確定您有下列先決條件。
**安裝 Rust 和 Cargo**
使用 [rustup](https://rustup.rs/) 安裝目前穩定的 [Rust](https://www.rust-lang.org/) 版本。
如需下載和安裝中斷的詳細資訊，請參閱 Cargo Book 中的[安裝程序](https://doc.rust-lang.org/cargo/getting-started/installation.html)。
## 安裝
AWS Encryption SDK for Rust 可在 Crates.io：// 上做為[https://crates.io/crates/aws-esdk](https://crates.io/crates/aws-esdk)木箱使用。如需安裝和建置 AWS Encryption SDK for Rust 的詳細資訊，請參閱 GitHub 上 aws-encryption-sdk 儲存庫中的 [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline)：//。
您可以使用下列方式安裝 AWS Encryption SDK for Rust。
**手動**
若要安裝 AWS Encryption SDK for Rust，請複製或下載 [aws-encryption-sdk](https://github.com/aws/aws-encryption-sdk/tree/mainline) GitHub 儲存庫。
**使用 Crates.io**
在專案目錄中執行下列 Cargo 命令：
```
cargo add aws-esdk
```
或將以下行新增至 Cargo.toml：
```
aws-esdk = ""
```
# AWS Encryption SDK for Rust 範例程式碼
下列範例顯示使用 AWS Encryption SDK for Rust 進行程式設計時所使用的基本編碼模式。具體而言，您會執行個體化 AWS Encryption SDK 和材料提供者程式庫。然後，在呼叫每個方法之前，您可以執行個體化定義方法輸入的物件。
如需示範如何在 中設定選項的範例 AWS Encryption SDK，例如指定替代演算法套件和限制加密的資料金鑰，請參閱 GitHub 上 aws-encryption-sdk 儲存庫中的 [Rust 範例](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples/)。
## 在 AWS Encryption SDK for Rust 的 中加密和解密資料
此範例顯示加密和解密資料的基本模式。它會使用受一個 AWS KMS 包裝金鑰保護的資料金鑰來加密小型檔案。
**步驟 1：執行個體化 AWS Encryption SDK。**
您將使用 中的方法來 AWS Encryption SDK 加密和解密資料。
```
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
```
**步驟 2：建立 AWS KMS 用戶端。**
```
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
```
**選用：建立您的加密內容。**
```
let encryption_context = HashMap::from([
("encryption".to_string(), "context".to_string()),
("is not".to_string(), "secret".to_string()),
("but adds".to_string(), "useful metadata".to_string()),
("that can help you".to_string(), "be confident that".to_string()),
("the data you are handling".to_string(), "is what you think it is".to_string()),
]);
```
**步驟 3：執行個體化材料提供者程式庫。**
您將使用材料提供者程式庫中的方法來建立 keyring，以指定哪些金鑰保護您的資料。
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
```
**步驟 4：建立 AWS KMS keyring。**
若要建立 keyring，請使用 keyring 輸入物件呼叫 keyring 方法。此範例使用 `create_aws_kms_keyring()`方法並指定一個 KMS 金鑰。
```
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
```
**步驟 5：加密純文字。**
```
let plaintext = example_data.as_bytes();
let encryption_response = esdk_client.encrypt()
.plaintext(plaintext)
.keyring(kms_keyring.clone())
.encryption_context(encryption_context.clone())
.send()
.await?;
let ciphertext = encryption_response
.ciphertext
.expect("Unable to unwrap ciphertext from encryption response");
```
**步驟 6：使用您在加密時所使用的相同 keyring 來解密加密的資料。**
```
let decryption_response = esdk_client.decrypt()
.ciphertext(ciphertext)
.keyring(kms_keyring)
// Provide the encryption context that was supplied to the encrypt method
.encryption_context(encryption_context)
.send()
.await?;
let decrypted_plaintext = decryption_response
.plaintext
.expect("Unable to unwrap plaintext from decryption response");
```
# 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