前提条件インストール AWS KMS キーリング必要な暗号化コンテキスト CMM

AWS Encryption SDK for Java

このトピックでは、 AWS Encryption SDK for Javaをインストールして使用する方法について説明します。を使用したプログラミングの詳細については AWS Encryption SDK for Java、「」の「 aws-encryption-sdk-javaリポジトリ」を参照してください GitHub。API ドキュメントについては、の Javadoc を参照してください AWS Encryption SDK for Java。

トピック

前提条件
インストール
AWS KMS キーリング
必要な暗号化コンテキスト CMM
例

前提条件

をインストールする前に AWS Encryption SDK for Java、次の前提条件があることを確認してください。

Java 開発環境

Java 8 以降が必要になります。Oracle ウェブサイトで、Java SE ダウンロードに移動し、Java SE 開発キット () をダウンロードしてインストールしますJDK。

Oracle を使用する場合はJDK、Java 暗号化拡張機能 (JCE) Unlimited 強度管轄ポリシーファイルもダウンロードしてインストールする必要があります。

Bouncy Castle

AWS Encryption SDK for Java には Bouncy Castle が必要です。

AWS Encryption SDK for Java バージョン 1.6.1 以降では、Bouncy Castle を使用して暗号化オブジェクトをシリアル化および逆シリアル化します。この要件を満たすには、Bouncy Castle または Bouncy Castle FIPS を使用できます。Bouncy Castle のインストールと設定についてはFIPS、「BC FIPSドキュメント」、特に ユーザーガイドとセキュリティポリシー「」を参照してくださいPDFs。
の以前のバージョンでは、Java API用の Bouncy Castle の暗号化 AWS Encryption SDK for Java を使用しています。この要件は、バFIPSウンシー以外のキャッテルでのみ満たされます。

Bouncy Castle をお持ちでない場合は、Bouncy Castle の最新リリースにアクセスして、に対応するプロバイダーファイルをダウンロードしてくださいJDK。Apache Maven を使用して、標準の Bouncy Castle プロバイダーのアーティファクト (bcprov-ext-jdk15on ) または Bouncy Castle のアーティファクト FIPS (bc-fips ) を取得することもできます。

AWS SDK for Java

のバージョン 3.x では AWS SDK for Java 2.x、 AWS KMS キーリングを使用していない場合でも、 AWS Encryption SDK for Java が必要です。

のバージョン 2.x 以前の AWS Encryption SDK for Java では、は必要ありません AWS SDK for Java。ただし、マスターキープロバイダーとして AWS Key Management Service (AWS KMS) を使用するには、 AWS SDK for Java が必要です。 AWS Encryption SDK for Java バージョン 2.4.0 以降、 AWS Encryption SDK for Java は 1.x と 2.x の AWS SDK for Java. AWS Encryption SDK code のバージョン AWS SDK for Java 1.x と 2.x の両方を相互運用できます。例えば、 AWS SDK for Java 1.x をサポートする AWS Encryption SDK コードでデータを暗号化し、をサポートするコードを使用して復号化できます AWS SDK for Java 2.x （またはその逆）。2.4.0 より AWS Encryption SDK for Java 前のバージョンのでは、 AWS SDK for Java 1.x のみがサポートされています。のバージョンの更新については、 AWS Encryption SDK「」を参照してくださいAWS Encryption SDK の移行。

AWS Encryption SDK for Java コードを AWS SDK for Java 1.x からに更新する場合は AWS SDK for Java 2.x、 AWS SDK for Java 1.x のAWSKMSインターフェイスへの参照をのKmsClientインターフェイスへの参照に置き換えます AWS SDK for Java 2.x。 AWS Encryption SDK for Java は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。

インストール

AWS Encryption SDK for Javaの最新バージョンをインストールします。

注記

2.0.0 より AWS Encryption SDK for Java 前ののすべてのバージョンはend-of-support、フェーズにあります。

バージョン 2.0.x 以降から AWS Encryption SDK for Java の最新バージョンにコードやデータを変更せずに安全に更新できます。ただし、バージョン 2.0.x で導入された新しいセキュリティ機能には下位互換性がありません。1.7.x より前のバージョンから 2.0.x 以降のバージョンに更新するには、まず AWS Encryption SDKの最新の 1.x バージョンに更新する必要があります。詳細については、「AWS Encryption SDK の移行」を参照してください。

は、次の AWS Encryption SDK for Java 方法でインストールできます。

手動

をインストールするには AWS Encryption SDK for Java、aws-encryption-sdk-java GitHubリポジトリのクローンを作成するか、ダウンロードします。

Apache Maven の使用

AWS Encryption SDK for Java は、次の依存関係定義を使用して 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 のキーリング AWS Encryption SDK for Java

のバージョン 3.x AWS Encryption SDK for Java では、キーリングを使用してエンベロープ暗号化を実行します。の基本的な AWS KMS キーリングは 1 つのKMSキーのみ AWS Encryption SDK for Java を取ります。また、 AWS KMS クライアントも必要です。これにより、KMSキー AWS リージョンの用にクライアントを設定できます。

1 つ以上のラッピング AWS KMS キーを持つキーリングを作成するには、マルチキーリングを使用します。 AWS Encryption SDK for Java には、1 つ以上のキーを受け取る特別なマルチ AWS KMS キーリングと、サポートされている任意のタイプの 1 つ以上のキーリングを受け取る標準のマルチキーリングがあります。一部のプログラマーは、マルチキーリング方式を使用してすべてのキーリングを作成することを好み、はその戦略 AWS Encryption SDK for Java をサポートしています。

AWS Encryption SDK for Java は、マルチ AWS KMS リージョンキーを含むすべての一般的なユースケースに、基本的なシングルキーキーキーリングとマルチキーリングを提供します。

例えば、1 つの 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);

1 つ以上のキーを持つ AWS KMS キーリングを作成するには、 CreateAwsKmsMultiKeyring()メソッドを使用します。この例では KMS キーを 2 つ使用しています。1 つのKMSキーを指定するには、 generatorパラメータのみを使用します。追加のKMSキーを指定する msKeyIdsパラメータはオプションです。

このキーリングの入力は AWS KMS クライアントを取りません。代わりに、はキーリングのKMSキーで表される各リージョンのデフォルト AWS KMS クライアント AWS Encryption SDK を使用します。例えば、 Generatorパラメータの値で識別されるKMSキーが米国西部 (オレゴン) リージョン () にある場合us-west-2、はus-west-2リージョンのデフォルト AWS KMS クライアント AWS Encryption SDK を作成します。 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 = materialProviders.CreateAwsKmsMultiKeyring(keyringInput);

AWS Encryption SDK for Java は、対称暗号化 (SYMMETRIC_DEFAULT) または非対称RSAKMSキーを使用する AWS KMS キーリングをサポートします。非対称RSAKMSキーで作成された AWS KMS キーリングには、1 つのキーペアのみを含めることができます。

非対称RSA AWS KMS キーリングで暗号化するには、kms:GenerateDataKey または kms:Encrypt は必要ありません。キーリングの作成時に暗号化に使用するパブリックキーマテリアルを指定する必要があるためです。このキーリングで暗号化する場合、 AWS KMS 呼び出しは行われません。非対称RSA AWS KMS キーリングで復号するには、kms:Decrypt アクセス許可が必要です。

非対称RSA AWS KMS キーリングを作成するには、非対称キーARNからパブリックキーとプライベートRSAKMSキーを指定する必要があります。パブリックキーはPEMエンコードする必要があります。次の例では、非対称 AWS KMS キーペアを使用して RSAキーリングを作成します。


// 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 では AWS Encryption SDK for Java、必要な暗号化コンテキストを使用してCMM、暗号化オペレーションで暗号化コンテキストを要求できます。暗号化コンテキストは、一連の非シークレットのキーと値のペアです。暗号化コンテキストは、暗号化されたデータに暗号化されてバインドされます。これにより、フィールドを復号するために同じ暗号化コンテキストが必要になります。必要な暗号化コンテキストを使用する場合CMM、すべての暗号化および復号呼び出しに含める必要がある 1 つ以上の必要な暗号化コンテキストキー (必須キー) を指定できます。

注記

必要な暗号化コンテキストCMMは、用ののバージョン 4.x とのみ相互運用 AWS Encryption SDK 可能ですNET。その他のプログラミング言語実装とは相互運用できません。必要な暗号化コンテキストを使用してデータを暗号化する場合はCMM、のバージョン 3.x AWS Encryption SDK for Java またはのバージョン 4.x でのみ復号 AWS Encryption SDK できます。NET

暗号化時に、は、必要な暗号化コンテキストキーがすべて、指定した暗号化コンテキストに含まれている AWS Encryption SDK ことを確認します。は、指定した暗号化コンテキスト AWS Encryption SDK に署名します。必須キーではないキーと値のペアのみがシリアル化され、暗号化操作によって返される暗号化メッセージのヘッダーにプレーンテキストで保存されます。

復号化時には、必要なキーを表すすべてのキーと値のペアを含む暗号化コンテキストを提供する必要があります。 AWS Encryption SDK は、この暗号化コンテキストと、暗号化されたメッセージのヘッダーに保存されているキーと値のペアを使用して、暗号化オペレーションで指定した元の暗号化コンテキストを再構築します。が元の暗号化コンテキストを再構築 AWS Encryption SDK できない場合、復号オペレーションは失敗します。誤った値を持つ必要なキーを含むキーと値のペアを供給すると、暗号化されたメッセージは復号化できません。暗号化時に指定したのと同じキーと値のペアを供給する必要があります。

重要

暗号化のコンテキストで必要なキーにどの値を選択するかを慎重に検討してください。復号化時には、同じキーとそれに対応する値を再度提供できる必要があります。必要なキーを再現できない場合、暗号化されたメッセージは復号化できません。

次の例では、必要な暗号化コンテキストを使用して AWS KMS キーリングを初期化しますCMM。


// 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 が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

例