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

AWS Encryption SDK for Java

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

トピック

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

前提条件

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

Java 開発環境

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

Oracle JDK を使用する場合は、Java Cryptography Extension (JCE) 無制限強度の管轄ポリシーファイルをダウンロードして、インストールする必要があります。

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 のインストールおよび設定については、Bouncy Castle FIPS のドキュメントの特にユーザーガイドとセキュリティポリシーの PDF を参照してください。
AWS Encryption SDK for Java のそれより前のバージョンでは、Bouncy Castle の Java 用の暗号化 API を使用します。この要件は、FIPS 非対応の Bouncy Castle によってのみ満たされます。

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

AWS SDK for Java

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

バージョン 2。 x 以前のバージョンでは、AWS Encryption SDK for Javaは必要ありませんAWS SDK for Java。ただし、AWS SDK for Java は、マスターキープロバイダーとして AWS Key Management Service (AWS KMS) を使用する必要があります。AWS Encryption SDK for Java バージョン 2.4.0 以降、AWS Encryption SDK for Java は AWS SDK for Java のバージョン 1.x と 2.x の両方をサポートしています。AWS SDK for Java 1.x と 2.x の AWS Encryption SDK コードは相互運用可能です。たとえば、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 インターフェイスへの参照を、AWS SDK for Java 2.x の KmsClient インターフェイスへの参照に置き換えてください。AWS Encryption SDK for Java は KmsAsyncClient インターフェイスをサポートしていません。また、kms 名前空間の代わりに、kmssdkv2 名前空間の AWS 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の基本的なキーリングは KMS キーを 1 AWS Encryption SDK for Java つだけ使用します。また、AWS KMS クライアントも必要になり、KMS キーの AWS リージョン用にクライアントを設定する機会ができます。

1 つ以上の AWS KMS ラッピングキーを含むキーリングを作成するには、マルチキーリングを使用します。AWS Encryption SDK for Javaには、1 つ以上のキーを使用する特別なマルチキーリングと、サポートされているタイプの 1 AWS KMS つ以上のキーリングを使用する標準のマルチキーリングがあります。プログラマーの中には、すべてのキーリングの作成にマルチキーリング方式を使用することを好む人もいますが、はその方法をサポートしています。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() メソッドを使用します。この例では 2 つの KMS キーを使用しています。1 つの KMS キーを指定するには、generator パラメータのみを使用します。追加の KMS キーを指定する msKeyIds パラメータはオプションです。

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

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

非対称 RSA AWS KMS キーリングで暗号化するには、kms: GenerateDataKey または kms: Encrypt は必要ありません。キーリングを作成するときに、暗号化に使用する公開鍵の内容を指定する必要があるからです。AWS KMS このキーリングで暗号化する場合、呼び出しは行われません。非対称 RSA AWS KMS キーリングで復号化するには、kms: Decrypt 権限が必要です。

非対称 RSA AWS KMS キーリングを作成するには、非対称 RSA KMS キーのパブリックキーとプライベートキー ARN を提示する必要があります。パブリックキーは PEM でエンコードされている必要があります。次の例では、非対称 RSA キーペアを使用して 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 AWS Encryption SDK for Java では、必要な暗号化コンテキスト CMM を使用して、暗号化操作に暗号化コンテキストを要求できます。暗号化コンテキストは、一連の非シークレットのキーと値のペアです。暗号化コンテキストは、暗号化されたデータに暗号化されてバインドされます。これにより、フィールドを復号するために同じ暗号化コンテキストが必要になります。必要な暗号化コンテキスト CMM を使用する場合、すべての暗号化および復号化の呼び出しに含める必要のある 暗号化コンテキストキー (必須キー) を 1 つ以上指定できます。

注記

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

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

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

ドキュメントの表記規則

例