本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 更新 AWS KMS 主金鑰提供者
若要遷移至最新的 1.*x* 版本 AWS Encryption SDK，然後遷移至 2.0.*x* 版或更新版本，您必須將舊版 AWS KMS 主金鑰提供者取代為以[*嚴格模式*或*探索模式*](about-versions.md#changes-to-mkps)明確建立的主金鑰提供者。舊版主金鑰提供者已在 1.7.*x* 版中棄用，並在 2.0.*x* 版中移除。使用 [適用於 JAVA 的 AWS Encryption SDK](java.md)、 和 [AWS Encryption CLI](crypto-cli.md) 的應用程式[適用於 Python 的 AWS Encryption SDK](python.md)和指令碼需要此變更。本節中的範例將示範如何更新程式碼。
**注意**
在 Python 中，[開啟棄用警告](https://docs.python.org/3/library/warnings.html)。這將協助您識別您需要更新的程式碼部分。
如果您使用的是 AWS KMS 主金鑰 （不是主金鑰提供者），您可以略過此步驟。 AWS KMS 主金鑰不會棄用或移除。它們只會使用您指定的包裝金鑰來加密和解密。
本節中的範例著重於您需要變更的程式碼元素。如需更新程式碼的完整範例，請參閱[程式設計語言](programming-languages.md)的 GitHub 儲存庫範例一節。此外，這些範例通常會使用金鑰 ARNs 來表示 AWS KMS keys。當您建立用於加密的主金鑰提供者時，您可以使用任何有效的 AWS KMS [金鑰識別符](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)來代表 AWS KMS key 。當您建立用於解密的主金鑰提供者時，您必須使用金鑰 ARN。
**進一步了解遷移**
對於 AWS Encryption SDK 所有使用者，了解如何在 中設定您的承諾政策[設定您的承諾政策](migrate-commitment-policy.md)。
對於 適用於 C 的 AWS Encryption SDK 和 適用於 JavaScript 的 AWS Encryption SDK 使用者，了解 中 keyring 的選用更新[更新 AWS KMS keyring](migrate-keyrings-v2.md)。
**Topics**
+ [遷移至嚴格模式](#migrate-mkp-strict-mode)
+ [遷移至探索模式](#migrate-mkp-discovery-mode)
## 遷移至嚴格模式
更新至最新的 1.*x* 版本後 AWS Encryption SDK，以嚴格模式將舊版主金鑰提供者取代為主金鑰提供者。在嚴格模式下，您必須指定加密和解密時要使用的包裝金鑰。只會 AWS Encryption SDK 使用您指定的包裝金鑰。已棄用的主金鑰提供者可以使用加密資料金鑰的任何 AWS KMS key 來解密資料，包括在不同的 AWS KMS keys AWS 帳戶 和 區域中。
嚴格模式的主金鑰提供者會在 1.7.*x* AWS Encryption SDK 版中推出。它們取代了舊版主金鑰提供者，這些提供者已在 1.7.*x* 中棄用，並在 2.0.*x* 中移除。在嚴格模式下使用主金鑰提供者是 AWS Encryption SDK [最佳實務](best-practices.md)。
下列程式碼會以嚴格模式建立主金鑰提供者，您可以用來加密和解密。
------
#### [ Java ]
此範例代表使用 1.6.2 版或更早版本的應用程式中的程式碼。 適用於 JAVA 的 AWS Encryption SDK
此程式碼使用 `KmsMasterKeyProvider.builder()`方法來執行個體化使用 AWS KMS 主金鑰提供者 AWS KMS key 做為包裝金鑰。
```
// Create a master key provider
// Replace the example key ARN with a valid one
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.withKeysForEncryption(awsKmsKey)
.build();
```
此範例代表應用程式中使用 1.7.*x* 版或更新版本的程式碼。 適用於 JAVA 的 AWS Encryption SDK 如需完整範例，請參閱 [BasicEncryptionExample.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/BasicEncryptionExample.java)。
上一個範例中使用的 `Builder.build()`和 `Builder.withKeysForEncryption()`方法已在 1.7.*x* 版中棄用，並從 2.0.*x* 版中移除。
若要更新至嚴格的模式主金鑰提供者，此程式碼會將對已棄用方法的呼叫取代為對新`Builder.buildStrict()`方法的呼叫。此範例指定一個 AWS KMS key 做為包裝金鑰，但 `Builder.buildStrict()`方法可以取得多個 的清單 AWS KMS keys。
```
// Create a master key provider in strict mode
// Replace the example key ARN with a valid one from your AWS 帳戶.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
```
------
#### [ Python ]
此範例代表應用程式中使用 1.4.1 版的程式碼。 適用於 Python 的 AWS Encryption SDK此程式碼使用 `KMSMasterKeyProvider`，已在 1.7.*x* 版中棄用，並從 2.0.*x* 版中移除。解密時，它會使用加密資料金鑰的任何 AWS KMS key ，而不考慮 AWS KMS keys 您指定的 。
請注意， `KMSMasterKey` 不會棄用或移除。加密和解密時，只會使用 AWS KMS key 您指定的 。
```
# Create a master key provider
# Replace the example key ARN with a valid one
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = KMSMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
此範例代表應用程式中使用 1.7.*x* 版的程式碼。 適用於 Python 的 AWS Encryption SDK如需完整範例，請參閱 [basic\$1encryption.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/basic_encryption.py)。
若要更新為嚴格模式主金鑰提供者，此程式碼會將對 的呼叫取代`KMSMasterKeyProvider()`為對 的呼叫`StrictAwsKmsMasterKeyProvider()`。
```
# Create a master key provider in strict mode
# Replace the example key ARNs with valid values from your AWS 帳戶
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
------
#### [ AWS Encryption CLI ]
此範例說明如何使用 AWS Encryption CLI 1.1.7 版或更早版本來加密和解密。
在 1.1.7 版和更早版本中，加密時，您會指定一或多個主金鑰 （或*包裝金鑰*)，例如 AWS KMS key。解密時，除非您使用自訂主金鑰提供者，否則無法指定任何包裝金鑰。 AWS 加密 CLI 可以使用加密資料金鑰的任何包裝金鑰。
```
\\ Replace the example key ARN with a valid one
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--master-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
此範例示範如何使用 AWS Encryption CLI 1.7.*x* 版或更新版本來加密和解密。如需完整範例，請參閱 [AWS 加密 CLI 的範例](crypto-cli-examples.md)。
參數`--master-keys`已在 1.7.*x* 版中棄用，並在 2.0.*x* 版中移除。它會以 `--wrapping-keys` 參數取代 ，這是加密和解密命令中的必要項目。此參數支援嚴格模式和探索模式。嚴格模式是 AWS Encryption SDK 最佳實務，可確保您使用您想要的包裝金鑰。
若要升級至*嚴格模式*，請在加密和解密時使用 `--wrapping-keys` 參數的**金鑰**屬性來指定包裝金鑰。
```
\\ Replace the example key ARN with a valid value
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
## 遷移至探索模式
從 1.7.*x* 版開始， AWS Encryption SDK [最佳實務](best-practices.md)是對 AWS KMS 主金鑰提供者使用*嚴格模式*，也就是在加密和解密時指定包裝金鑰。加密時，您必須一律指定包裝金鑰。但在某些情況下，指定用於 AWS KMS keys 解密的 金鑰 ARNs 並不切實際。例如，如果您使用別名來識別加密 AWS KMS keys 時，如果您在解密時必須列出金鑰 ARNs，則會失去別名的好處。此外，由於探索模式中的主金鑰提供者的行為與原始主金鑰提供者類似，因此您可以在遷移策略中暫時使用這些提供者，稍後再以嚴格模式升級至主金鑰提供者。
在這種情況下，您可以在*探索模式中*使用主金鑰提供者。這些主金鑰提供者不會讓您指定包裝金鑰，因此您無法使用它們進行加密。解密時，他們可以使用任何加密資料金鑰的包裝金鑰。但與行為相同的舊版主金鑰提供者不同，您可以在探索模式中明確建立它們。在探索模式下使用主金鑰提供者時，您可以限制可用於這些提供者的包裝金鑰 AWS 帳戶。此探索篩選條件是選用的，但我們建議採用最佳實務。如需有關 AWS 分割區和帳戶的資訊，請參閱 中的 [Amazon Resource Names](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax)*AWS 一般參考*。
下列範例會在嚴格模式下建立用於加密 AWS KMS 的主金鑰提供者，並在探索模式下建立用於解密 AWS KMS 的主金鑰提供者。探索模式中的主金鑰提供者會使用探索篩選條件，將用於解密的包裝金鑰限制為`aws`分割區和特定範例 AWS 帳戶。雖然在此非常簡單的範例中不需要帳戶篩選條件，但當一個應用程式加密資料，而另一個應用程式解密資料時，這是非常有益的最佳實務。
------
#### [ Java ]
此範例代表應用程式中使用 1.7.*x* 版或更新版本的程式碼。 適用於 JAVA 的 AWS Encryption SDK如需完整範例，請參閱 [DiscoveryDecryptionExample.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/)。
若要以嚴格模式執行個體化主金鑰提供者以進行加密，此範例會使用 `Builder.buildStrict()`方法。若要在探索模式中執行個體化主金鑰提供者以進行解密，它會使用 `Builder.buildDiscovery()`方法。`Builder.buildDiscovery()` 方法採用的 `DiscoveryFilter`會將指定 AWS 分割區和帳戶中的 限制 AWS Encryption SDK AWS KMS keys 為 。
```
// Create a master key provider in strict mode for encrypting
// Replace the example alias ARN with a valid one from your AWS 帳戶.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias";
KmsMasterKeyProvider encryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Create a master key provider in discovery mode for decrypting
// Replace the example account IDs with valid values.
DiscoveryFilter accounts = new DiscoveryFilter("aws", Arrays.asList("111122223333", "444455556666"));
KmsMasterKeyProvider decryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildDiscovery(accounts);
```
------
#### [ Python ]
此範例代表應用程式中使用 1.7.*x* 版或更新版本的程式碼。 適用於 Python 的 AWS Encryption SDK 如需完整範例，請參閱 [探索\$1kms\$1provider.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/discovery_kms_provider.py)。
若要在嚴格模式下建立用於加密的主金鑰提供者，此範例使用 `StrictAwsKmsMasterKeyProvider`。若要在探索模式中建立主要金鑰提供者以進行解密，它會使用 `DiscoveryAwsKmsMasterKeyProvider`搭配 `DiscoveryFilter`，在指定的 AWS 分割區和帳戶中將 限制 AWS Encryption SDK AWS KMS keys 為 。
```
# Create a master key provider in strict mode
# Replace the example key ARN and alias ARNs with valid values from your AWS 帳戶.
key_1 = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias"
key_2 = "arn:aws:kms:us-west-2:444455556666:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
# Create a master key provider in discovery mode for decrypting
# Replace the example account IDs with valid values
accounts = DiscoveryFilter(
partition="aws",
account_ids=["111122223333", "444455556666"]
)
aws_kms_master_key_provider = DiscoveryAwsKmsMasterKeyProvider(
discovery_filter=accounts
)
```
------
#### [ AWS Encryption CLI ]
此範例示範如何使用 AWS Encryption CLI 1.7.*x* 版或更新版本來加密和解密。從 1.7.*x* 版開始，在加密和解密時需要 `--wrapping-keys` 參數。`--wrapping-keys` 參數支援嚴格模式和探索模式。如需完整範例，請參閱 [AWS 加密 CLI 的範例](crypto-cli-examples.md)。
加密時，此範例會指定需要的包裝金鑰。解密時，它會使用值為 的 `--wrapping-keys` 參數`discovery`屬性來明確選擇*探索模式*`true`。
若要將 AWS Encryption SDK 可在探索模式中使用的包裝金鑰限制為特別是那些金鑰 AWS 帳戶，此範例會使用 `--wrapping-keys` 參數的 `discovery-partition`和 `discovery-account` 屬性。這些選用屬性只有在`discovery`屬性設定為 時才有效`true`。您必須同時使用 `discovery-partition`和 `discovery-account` 屬性；兩者都無效。
```
\\ Replace the example key ARN with a valid value
$ keyAlias=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyAlias \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
\\ Replace the example account IDs with valid values
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666 \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------