適用於 JAVA 的 AWS Encryption SDK

本主題說明如何安裝及使用適用於 JAVA 的 AWS Encryption SDK。如需有關使用程式設計的詳細資訊適用於 JAVA 的 AWS Encryption SDK，請參閱上的aws-encryption-sdk-java存放庫 GitHub。如需 API 文件，請參閱. 適用於 JAVA 的 AWS Encryption SDK

主題

先決條件
安裝
AWS KMS Keyring
必要的加密內容 CMM
範例

先決條件

安裝適用於 JAVA 的 AWS Encryption SDK 之前，請確認您是否具備下列必要項目。

Java 開發環境

您會需要 Java 8 或更新版本。在 Oracle 網站上，移至 Java SE 下載，然後下載並安裝 Java SE 開發套件 (JDK)。

如果您使用 Oracle JDK，您還必須下載並安裝 Java Cryptography Extension (JCE) Unlimited Strength 管轄權政策檔案。

Bouncy Castle

適用於 JAVA 的 AWS Encryption SDK 需要 Bouncy Castle。

適用於 JAVA 的 AWS Encryption SDK 版本 1.6.1 和更新版本使用 Bouncy Castle 來序列化和還原序列化密碼編譯物件。您可以使用 Bouncy Castle 或 Bouncy Castle FIPS 來滿足此要求。如需安裝和設定 Bouncy Castle FIPS 的說明，請參閱 BC FIPS 文件，尤其是使用者指南和安全性原則 PDF。
適用於 JAVA 的 AWS Encryption SDK 的早期版本使用 Bouncy Castle 的 Java 適用的密碼編譯 API。只有非 FIPS Bouncy Castle 才能滿足此要求。

如果您沒有 Bouncy Castle，請移至 Bouncy Castle 最新版本下載與您 JDK 相對應的提供者檔案。您也可以使用阿帕奇 Maven 獲取標準充氣城堡提供商（bcprov-ext-jdk15 上）或充氣城堡 FIPS（b c-fips）的神器的神器。

AWS SDK for Java

版本 3. x 的適用於 JAVA 的 AWS Encryption SDK需要AWS SDK for Java 2.x，即使您不使用AWS KMS鑰匙圈。

版本 2. x 或更早版本的適用於 JAVA 的 AWS Encryption SDK不需要AWS SDK for Java. 不過，需AWS SDK for Java要使用 AWS Key Management Service(AWS KMS) 做為主要金鑰提供者。從適用於 JAVA 的 AWS Encryption SDK版本 2.4.0 開始，適用於 JAVA 的 AWS Encryption SDK支援的. AWS SDK for Java AWS Encryption SDKAWS SDK for Java1.x 和 2.x 的代碼是可互操作的。例如，您可以使用支援 AWS SDK for Java 1.x 的AWS Encryption SDK程式碼加密資料，並使用支援的程式碼解密資料 AWS SDK for Java 2.x (反之亦然)。適用於 JAVA 的 AWS Encryption SDK早於 2.4.0 的版本僅支援 AWS SDK for Java 1.x。如需更新您的版本的詳細資訊AWS Encryption SDK，請參閱遷移您的AWS Encryption SDK。

將適用於 JAVA 的 AWS Encryption SDK程式碼從 AWS SDK for Java 1.x 更新為時AWS SDK for Java 2.x，請使用中AWSKMS介面的參照來取代 AWS SDK for Java 1.x 中KmsClient介面的參照。AWS SDK for Java 2.x適用於 JAVA 的 AWS Encryption SDK不支援KmsAsyncClient介面。此外，請更新程式碼以使用命kmssdkv2名空間中的AWS KMS相關物件，而非kms命名空間。

若要安裝 AWS SDK for Java，請使用 Apache Maven。

若要匯入整個 AWS SDK for Java 作為相依性，請在 pom.xml 檔案中宣告它。
若要僅為 AWS SDK for Java 1.x 中的AWS KMS模組建立相依性，請遵循指定特定模組的指示，並將設定artifactId為aws-java-sdk-kms。
要僅為 AWS SDK for Java 2.x 中的AWS KMS模塊創建依賴關係，請按照指定特定模塊的說明進行操作。groupId將設定為software.amazon.awssdk和artifactId為kms。

如需更多變更，請參閱AWS SDK for Java 2.x開發人員指南中的 AWS SDK for Java 1.x 與 2.x 之間有何不同。

AWS Encryption SDK開發人員指南中的 Java 範例使用AWS SDK for Java 2.x.

安裝

安裝最新版本的適用於 JAVA 的 AWS Encryption SDK.

注意

適用於 JAVA 的 AWS Encryption SDK早於 2.0.0 的所有版本都處於此end-of-support階段。

您可以安全地從 2.0 版更新。 x 及更新版本的最新版本，適用於 JAVA 的 AWS Encryption SDK無需任何代碼或數據更改。但是，2.0 版中引入了新的安全功能。 x 不向後相容。若要從 1.7 之前的版本進行更新。 x 轉換為 2.0 版本。 x 和更新版本，您必須先更新到最新的 1。 x 版本的AWS Encryption SDK. 如需詳細資訊，請參閱遷移您的AWS Encryption SDK。

您可以使用下列方式來安裝適用於 JAVA 的 AWS Encryption SDK。

手動

若要安裝適用於 JAVA 的 AWS Encryption SDK，請複製或下載存aws-encryption-sdk-java GitHub放庫。

使用 Apache Maven

適用於 JAVA 的 AWS Encryption SDK 可透過具有下列依存性定義的 Apache Maven 取得。


<dependency>
  <groupId>com.amazonaws</groupId>
  <artifactId>aws-encryption-sdk-java</artifactId>
  <version>3.0.0</version>
</dependency>

安裝 SDK 之後，請參閱本指南中的範例 Java 程式碼以及 Javadoc 開始使用。 GitHub

AWS KMS鑰匙圈中適用於 JAVA 的 AWS Encryption SDK

版本 3. x 的適用於 JAVA 的 AWS Encryption SDK使用金鑰圈來執行信封加密。在適用於 JAVA 的 AWS Encryption SDK採取只有一個 KMS 密鑰的基本鑰AWS KMS匙圈。他們還需要一個AWS KMS客戶端，這使您有機會為 KMS 密鑰配置客戶端。AWS 區域

要使用一個或多個包裝鑰匙來創建鑰匙AWS KMS圈，請使用多鑰匙圈。適用於 JAVA 的 AWS Encryption SDK具有一個特殊的多鑰匙圈，可以接受一個或多個AWS KMS鑰匙，以及一個標準的多鑰匙圈，可以使用任何支持類型的一個或多個鑰匙圈。一些程序員更喜歡使用多鑰匙圈方法來創建他們的所有鑰匙圈，並適用於 JAVA 的 AWS Encryption SDK支持該策略。

為所有典型使用案例 (包括多區域金鑰) 適用於 JAVA 的 AWS Encryption SDK 提供基本的單一按鍵鑰匙圈和多重金鑰環。AWS KMS

例如，若要使用一個AWS KMS金鑰建立金鑰AWS KMS圈，您可以使用CreateAwsKmsKeyring()] 方法。


// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();

// Create the keyring
CreateAwsKmsKeyringInput kmsKeyringInput = CreateAwsKmsKeyringInput.builder()
        .kmsKeyId(keyArn)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

若要使用一個或多個金鑰建立AWS KMS金鑰圈，請使用方CreateAwsKmsMultiKeyring()法。此範例使用兩個 KMS 金鑰。若要指定一個 KMS 金鑰，請僅使用generator參數。指定其他 KMS 金鑰的msKeyIds參數是選擇性的。

此金鑰圈的輸入不會接受AWS KMS用戶端。而是針對金鑰圈中以 KMS 金鑰表示的每個區域AWS Encryption SDK使用預設用AWS KMS戶端。例如，如果Generator參數值所識別的 KMS 金鑰位於美國西部 (奧勒岡) 區域 (us-west-2)，則會為該區us-west-2域AWS Encryption SDK建立預設AWS KMS用戶端。如果您需要自定義AWS KMS客戶端，請使用該CreateAwsKmsKeyring()方法。


// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
            .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
            .build();

String generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<String> additionalKey = Collections.singletonList("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321");
// Create the keyring
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
        .generator(generatorKey)
        .kmsKeyIds(additionalKey)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);

適用於 JAVA 的 AWS Encryption SDK支援使用對稱加密 (SYMMETRIC_DEFAULT) 或非對稱 RSA KMS 金鑰的AWS KMS金鑰圈。 AWS KMS使用非對稱 RSA KMS 金鑰建立的金鑰圈只能包含一個 key pair。

若要使用非對稱 RSA 金AWS KMS鑰圈加密，您不需要 kms: GenerateDataKey 或 KMS: Encrypt，因為您必須在建立金鑰環時指定要用於加密的公開金鑰材料。使用此金鑰圈加密時，不會進行任何AWS KMS呼叫。若要使用非對稱 RSA AWS KMS 金鑰圈進行解密，您需要 K MS: 解密權限。

若要建立非對稱 RSA 金AWS KMS鑰圈，您必須從非對稱 RSA KMS 金鑰提供公開金鑰和私密金鑰 ARN。公開金鑰必須是 PEM 編碼。下列範例會建立具有非對稱 RSA key pair AWS KMS 圈。


// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder()
        // Specify algorithmSuite without asymmetric signing here
        //
        // ALG_AES_128_GCM_IV12_TAG16_NO_KDF("0x0014"),
        // ALG_AES_192_GCM_IV12_TAG16_NO_KDF("0x0046"),
        // ALG_AES_256_GCM_IV12_TAG16_NO_KDF("0x0078"),
        // ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256("0x0114"),
        // ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA256("0x0146"),
        // ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256("0x0178")
        .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256)
        .build();
                
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();

// Create a KMS RSA keyring.
//    This keyring takes in:
//     - kmsClient
//     - kmsKeyId: Must be an ARN representing an asymmetric RSA KMS key
//     - publicKey: A ByteBuffer of a UTF-8 encoded PEM file representing the public
//                  key for the key passed into kmsKeyId
//     - encryptionAlgorithm: Must be either RSAES_OAEP_SHA_256 or RSAES_OAEP_SHA_1
final CreateAwsKmsRsaKeyringInput createAwsKmsRsaKeyringInput =
        CreateAwsKmsRsaKeyringInput.builder()
                .kmsClient(KmsClient.create())
                .kmsKeyId(rsaKeyArn)
                .publicKey(publicKey)
                .encryptionAlgorithm(EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256)
                .build();
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);

3.x 版中必要的加密內容

使用版本 3。的 x適用於 JAVA 的 AWS Encryption SDK，您可以使用必要的加密內容 CMM 來在您的密碼編譯作業中要求加密內容。加密內容是一組非秘密金鑰值配對。加密內容會以密碼編譯方式繫結至加密的資料，因此必須使用相同的加密內容來解密欄位。使用必要的加密內容 CMM 時，您可以指定一或多個必要的加密內容金鑰 (必要金鑰)，這些金鑰必須包含在所有加密和解密呼叫中。

注意

必要的加密內容 CMM 只能與版本 4 互通。 AWS Encryption SDK用於 .NET 的 x。它不能與任何其他編程語言實現互操作。如果您使用必要的加密內容 CMM 加密資料，則只能使用版本 3 來解密資料。適用於 JAVA 的 AWS Encryption SDK或版本 4 的 x。 AWS Encryption SDK用於 .NET 的 x。

在加密時，AWS Encryption SDK會驗證所有必要的加密內容金鑰都包含在您指定的加密內容中。會AWS Encryption SDK簽署您指定的加密環境。只有非必要金鑰的索引鍵值配對才會以純文字形式儲存在加密作業傳回的加密訊息標頭中。

解密時，您必須提供一個加密內容，其中包含代表所需金鑰的所有金鑰-值配對。會AWS Encryption SDK使用此加密內容和儲存在加密郵件標頭中的金鑰值配對來重建您在加密作業中指定的原始加密內容。如果AWS Encryption SDK無法重建原始加密內容，則解密作業會失敗。如果您提供的金鑰-值組包含所需金鑰且值不正確，則無法解密加密的郵件。您必須提供與加密時指定的相同鍵值組。

重要

請仔細考慮您為加密內容中的必要金鑰選擇哪些值。您必須能夠在解密時再次提供相同的金鑰及其對應的值。如果您無法重現所需的金鑰，則無法解密加密的訊息。

下列範例會使用必要的加密內容 CMM 來初始化AWS KMS金鑰環。


// Instantiate the AWS Encryption SDK
final AwsCrypto crypto = AwsCrypto.builder()
        .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
        .build();
    
// Create your encryption context
final Map<String, String> encryptionContext = new HashMap<>();
encryptionContext.put("encryption", "context");
encryptionContext.put("is not", "secret");
encryptionContext.put("but adds", "useful metadata");
encryptionContext.put("that can help you", "be confident that");
encryptionContext.put("the data you are handling", "is what you think it is");    

// Create a list of required encryption contexts
final List<String> requiredEncryptionContextKeys = Arrays.asList("encryption", "context");
    
// Create the keyring
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsKeyringInput keyringInput = CreateAwsKmsKeyringInput.builder()
        .kmsKeyId(keyArn)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(keyringInput);
    
// Create the required encryption context CMM
ICryptographicMaterialsManager cmm = 
    materialProviders.CreateDefaultCryptographicMaterialsManager(
        CreateDefaultCryptographicMaterialsManagerInput.builder()
            .keyring(kmsKeyring)
            .build()
    );
ICryptographicMaterialsManager requiredCMM = 
    materialProviders.CreateRequiredEncryptionContextCMM(
        CreateRequiredEncryptionContextCMMInput.builder()
            .requiredEncryptionContextKeys(requiredEncryptionContextKeys)
            .underlyingCMM(cmm)
            .build()
        );

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

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

文件慣用形式

範例

適用於 JAVA 的 AWS Encryption SDK

主題

先決條件

安裝

注意

AWS KMS鑰匙圈中 適用於 JAVA 的 AWS Encryption SDK

3.x 版中必要的加密內容

注意

重要

AWS KMS鑰匙圈中適用於 JAVA 的 AWS Encryption SDK