更新AWS KMS主要金鑰提供者

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

注意

在 Python 中，打開棄用警告。這將幫助您識別需要更新的代碼部分。

如果您使用的是AWS KMS主要金鑰 (而非主要金鑰提供者)，您可以略過此步驟。 AWS KMS主金鑰不會被淘汰或移除。它們僅使用您指定的包裝密鑰進行加密和解密。

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

進一步了解遷移

對於所有AWS Encryption SDK使用者，請瞭解如何在中設定承諾產品原則設定承諾產品原則。

對於適用於 C 的 AWS Encryption SDK和適用於 JavaScript 的 AWS Encryption SDK使用者，請瞭解中金鑰圈的選擇性更新正在更新AWS KMS鑰匙圈。

遷移至嚴謹模

更新到最新的 1 後。 x 版本的AWS Encryption SDK，以嚴格模式中的主要金鑰提供者取代您的舊版主金鑰提供者。在嚴謹模式下，您必須指定加密和解密時要使用的包裝金鑰。僅AWS Encryption SDK使用您指定的環繞鍵。已取代的主金鑰提供者可以使用任何AWS KMS key加密資料金鑰 (包括AWS KMS keys在不同AWS 帳戶和區域) 的資料來解密資料。

1.7AWS Encryption SDK 版中引入了嚴格模式下的主密鑰提供程序。 x. 它們會取代舊式主金鑰提供者，而這些提供者在 1.7 中已淘汰。 x 並在 2.0 中刪除。 x. 在嚴謹模式中使用主要金鑰提供者是AWS Encryption SDK最佳作法。

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

Java

此範例代表使用的應用程式中的程式碼是 1.6.2 版或更早版本的適用於 JAVA 的 AWS Encryption SDK.

此程式碼會使用此KmsMasterKeyProvider.builder()方法來實體化使用 1AWS KMS key 做為包裝金鑰的AWS KMS主要金鑰提供者。

// 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

此範例顯示如何使用加AWS密 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 .  

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

1.7 版。--master-keys x 並在 2.0 版中刪除。 x. 它取代了 by--wrapping-keys 參數，這在加密和解密命令中是必需的。此參數支援嚴格模式和探索模式。嚴格模式是確保您使用想要的包裝鍵的AWS Encryption SDK最佳做法。

若要升級到嚴格模式，請在加密和解密時，使用--wrapping-keys參數的 key 屬性來指定包裝金鑰。

\\ 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 KMS主金鑰提供者使用嚴格模式是AWS Encryption SDK最佳做法，也就是說，在加密和解密時指定包裝金鑰。加密時，您必須一律指定包裝金鑰。但在某些情況下，指定AWS KMS keys用於解密的關鍵 ARN 是不切實際的。例如，如果您在加密AWS KMS keys時使用別名來識別，如果在解密時必須列出關鍵 ARN，就會失去別名的好處。此外，由於探索模式下的主要金鑰提供者的行為類似於原始主要金鑰提供者，因此您可以暫時使用它們做為移轉策略的一部分，然後在嚴謹模式中升級為主要金鑰提供者。

在這種情況下，您可以在探索模式下使用主要金鑰提供者。這些主要金鑰提供者不允許您指定包裝金鑰，因此您無法使用它們進行加密。解密時，他們可以使用任何加密資料金鑰的包裝金鑰。但與傳統主金鑰提供者 (其行為方式相同) 不同，您可以明確地在探索模式下建立這些提供者。在探索模式下使用主要金鑰提供者時，您可以限制可用於特定金鑰的包裝金鑰AWS 帳戶。此探索篩選器是選擇性的，但這是我們建議使用的最佳作法。如需有關AWS分割區和帳戶的資訊，請參閱 AWS 一般參考.

下列範例會以嚴格模式建立AWS KMS主金鑰提供者以供加密，並在探索模式下建立AWS KMS主金鑰提供者以進行解密。探索模式下的主要金鑰提供者使用探索篩選器，將用於解密的包裝金鑰限制為aws分割區和特定範例AWS 帳戶。儘管在這個非常簡單的示例中不需要帳戶過濾器，但是當一個應用程序加密數據並且不同的應用程序解密數據時，這是非常有益的最佳實踐。

Java

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

若要在嚴謹模式中實體化主金鑰提供者以進行加密，此範例會使用此Builder.buildStrict()方法。要在發現模式中實例化主密鑰提供程序以進行解密，它使用該Builder.buildDiscovery()方法。該Builder.buildDiscovery()方法採DiscoveryFilter用限制指定AWS分區和帳戶AWS KMS keys中的範圍。AWS Encryption SDK

// 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用限制在指定AWS分割區和帳戶AWS KMS keys中使用與限制為。DiscoveryFilterAWS Encryption SDK

# 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

此範例顯示如何使用加密 CLI 1.7 版進行AWS加密和解密。 x 或更新版本。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 .