更新 AWS KMS 主金鑰提供者

若要遷移至最新的 1.x 版本 AWS Encryption SDK，然後遷移至 2.0.x 或更新版本，您必須將舊版 AWS KMS 主金鑰提供者取代為以嚴格模式或探索模式明確建立的主金鑰提供者。舊版主金鑰提供者在 1.7.x 版中已棄用，並在 2.0.x 版中移除。使用適用於 JAVA 的 AWS Encryption SDK、和 AWS Encryption CLI 的應用程式適用於 Python 的 AWS Encryption SDK和指令碼需要此變更。本節中的範例將示範如何更新程式碼。

注意

在 Python 中，開啟棄用警告。這將協助您識別您需要更新的程式碼部分。

如果您使用的是 AWS KMS 主金鑰（不是主金鑰提供者），您可以略過此步驟。 AWS KMS 主金鑰不會棄用或移除。它們只會使用您指定的包裝金鑰來加密和解密。

本節中的範例著重於您需要變更的程式碼元素。如需更新程式碼的完整範例，請參閱程式設計語言 GitHub 儲存庫的範例一節。此外，這些範例通常會使用金鑰 ARNs 來表示 AWS KMS keys。當您建立用於加密的主金鑰提供者時，您可以使用任何有效的 AWS KMS 金鑰識別符來代表 AWS KMS key 。當您建立用於解密的主金鑰提供者時，您必須使用金鑰 ARN。

進一步了解遷移

對於 AWS Encryption SDK 所有使用者，了解如何在中設定您的承諾政策設定您的承諾政策。

對於適用於 C 的 AWS Encryption SDK 和適用於 JavaScript 的 AWS Encryption SDK 使用者，了解中 keyrings 的選用更新更新 AWS KMS keyring。

遷移至嚴格模式

更新至最新的 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 最佳實務。

下列程式碼會以嚴格模式建立主金鑰提供者，您可以用來加密和解密。

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。

上一個範例中使用的 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_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

此範例示範如何使用 Encryption CLI 1.1.7 版或更早版本 AWS 來加密和解密。

在 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 .

此範例示範如何使用 Encryption CLI 1.7.x 版或更新版本 AWS 來加密和解密。如需完整範例，請參閱 AWS 加密 CLI 的範例。

--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 最佳實務是對 AWS KMS 主金鑰提供者使用嚴格模式，也就是在加密和解密時指定包裝金鑰。加密時，您必須一律指定包裝金鑰。但在某些情況下，指定的金鑰 ARNs AWS KMS keys 進行解密並不切實際。例如，如果您使用別名來識別加密 AWS KMS keys 時，如果您在解密時必須列出金鑰 ARNs，則會失去別名的優點。此外，由於探索模式中的主金鑰提供者的行為與原始主金鑰提供者類似，因此您可以在遷移策略中暫時使用這些提供者，然後稍後在嚴格模式下升級至主金鑰提供者。

在這種情況下，您可以在探索模式中使用主金鑰提供者。這些主金鑰提供者不會讓您指定包裝金鑰，因此您無法使用這些金鑰進行加密。解密時，他們可以使用任何加密資料金鑰的包裝金鑰。但是，與以相同方式運作的傳統主金鑰提供者不同，您會在探索模式中明確建立它們。在探索模式中使用主金鑰提供者時，您可以限制包裝金鑰，特別是那些金鑰 AWS 帳戶。此探索篩選條件是選用的，但我們建議最佳實務。如需有關 AWS 分割區和帳戶的資訊，請參閱中的 Amazon Resource NamesAWS 一般參考。

下列範例會在嚴格模式下建立用於加密 AWS KMS 的主金鑰提供者，並在探索模式下建立用於解密 AWS KMS 的主金鑰提供者。探索模式中的主金鑰提供者會使用探索篩選條件，將用於解密的包裝金鑰限制為aws分割區和特定範例 AWS 帳戶。雖然在此非常簡單的範例中不需要帳戶篩選條件，但當一個應用程式加密資料，而另一個應用程式解密資料時，這是非常有益的最佳實務。

Java

此範例代表應用程式中使用 1.7.x 版或更新版本的程式碼。適用於 JAVA 的 AWS Encryption SDK如需完整範例，請參閱 DiscoveryDecryptionExample.java。

若要以嚴格模式執行個體化主金鑰提供者以進行加密，此範例會使用 Builder.buildStrict()方法。若要在探索模式中執行個體化主金鑰提供者以進行解密，會使用 Builder.buildDiscovery()方法。Builder.buildDiscovery() 方法採用 DiscoveryFilter，將限制 AWS Encryption SDK AWS KMS keys 在指定 AWS 分割區和帳戶中的。


// 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 如需完整範例，請參閱 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

此範例示範如何使用 Encryption CLI 1.7.x 版或更新版本 AWS 來加密和解密。從 1.7.x 版開始，在加密和解密時需要 --wrapping-keys 參數。--wrapping-keys 參數支援嚴格模式和探索模式。如需完整範例，請參閱 AWS 加密 CLI 的範例。

加密時，此範例會指定必要的包裝金鑰。解密時，它會使用值為的 --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 .

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

如何遷移和部署

更新 AWS KMS keyring