Prasyarat Instalasi AWS KMSgantungan kunci Konteks enkripsi yang diperlukan CMM

AWS Encryption SDK for Java

Topik ini menjelaskan cara menginstal dan menggunakanAWS Encryption SDK for Java. Untuk detail tentang pemrograman denganAWS Encryption SDK for Java, lihat aws-encryption-sdk-javarepositori di. GitHub Untuk dokumentasi API, lihat Javadoc untuk dokumen. AWS Encryption SDK for Java

Prasyarat

Sebelum Anda menginstalAWS Encryption SDK for Java, pastikan Anda memiliki prasyarat berikut.

Lingkungan pengembangan Java

Anda akan membutuhkan Java 8 atau yang lebih baru. Di situs web Oracle, buka Unduhan Java SE, kemudian unduh dan instal Java SE Development Kit (JDK).

Jika Anda menggunakan Oracle JDK, Anda juga harus mengunduh dan menginstal File Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy.

Kastil Bouncy

AWS Encryption SDK for JavaMembutuhkan Kastil Bouncy.

AWS Encryption SDK for Javaversi 1.6.1 dan yang lebih baru menggunakan Bouncy Castle untuk membuat serial dan deserialisasi objek kriptografi. Anda dapat menggunakan Bouncy Castle atau Bouncy Castle FIPS untuk memenuhi persyaratan ini. Untuk bantuan menginstal dan mengonfigurasi FIPS Bouncy Castle, lihat Dokumentasi BC FIPS, terutama Panduan Pengguna dan PDF Kebijakan Keamanan.
Versi sebelumnya AWS Encryption SDK for Java menggunakan API kriptografi Bouncy Castle untuk Java. Persyaratan ini hanya dipenuhi oleh Kastil Bouncy non-FIPS.

Jika Anda tidak memiliki Bouncy Castle, buka rilis terbaru Bouncy Castle untuk mengunduh file penyedia yang sesuai dengan JDK Anda. Anda juga dapat menggunakan Apache Maven untuk mendapatkan artefak untuk penyedia Bouncy Castle standar (bcprov-ext-jdk15on) atau artefak untuk Bouncy Castle FIPS (bc-fips).

AWS SDK for Java

Versi 3. x dari AWS Encryption SDK for Java membutuhkanAWS SDK for Java 2.x, bahkan jika Anda tidak menggunakan AWS KMS gantungan kunci.

Versi 2. x atau sebelumnya AWS Encryption SDK for Java tidak memerlukanAWS SDK for Java. Namun, AWS SDK for Java diperlukan untuk menggunakan AWS Key Management Service(AWS KMS) sebagai penyedia kunci utama. Dimulai pada AWS Encryption SDK for Java versi 2.4.0, AWS Encryption SDK for Java mendukung versi 1.x dan 2.x dari versi. AWS SDK for Java AWS Encryption SDKkode untuk AWS SDK for Java 1.x dan 2.x dapat dioperasikan. Misalnya, Anda dapat mengenkripsi data dengan AWS Encryption SDK kode yang mendukung AWS SDK for Java 1.x dan mendekripsi menggunakan kode yang mendukung AWS SDK for Java 2.x (atau sebaliknya). Versi yang AWS Encryption SDK for Java lebih awal dari 2.4.0 hanya mendukung AWS SDK for Java 1.x. Untuk informasi tentang memperbarui versi AndaAWS Encryption SDK, lihatMigrasiAWS Encryption SDK.

Saat memperbarui AWS Encryption SDK for Java kode Anda dari AWS SDK for Java 1.x keAWS SDK for Java 2.x, ganti referensi ke AWSKMSantarmuka di AWS SDK for Java 1.x dengan referensi ke KmsClientantarmuka di. AWS SDK for Java 2.x AWS Encryption SDK for JavaTidak mendukung KmsAsyncClientantarmuka. Juga, perbarui kode Anda untuk menggunakan objek AWS KMS -related di kmssdkv2 namespace, bukan namespace. kms

Untuk menginstalAWS SDK for Java, gunakan Apache Maven.

Untuk mengimpor keseluruhan AWS SDK for Java sebagai dependensi, deklarasikan dalam file Anda. pom.xml
Untuk membuat dependensi hanya untuk AWS KMS modul di AWS SDK for Java 1.x, ikuti instruksi untuk menentukan modul tertentu, dan atur ke. artifactId aws-java-sdk-kms
Untuk membuat dependensi hanya untuk AWS KMS modul di AWS SDK for Java 2.x, ikuti instruksi untuk menentukan modul tertentu. Atur groupId ke software.amazon.awssdk dan artifactId kekms.

Untuk perubahan lainnya, lihat Apa yang berbeda antara AWS SDK for Java 1.x dan 2.x di Panduan AWS SDK for Java 2.x Pengembang.

Contoh Java dalam Panduan AWS Encryption SDK Pengembang menggunakan fileAWS SDK for Java 2.x.

Instalasi

Instal versi terbaru dari fileAWS Encryption SDK for Java.

catatan

Semua versi yang AWS Encryption SDK for Java lebih awal dari 2.0.0 sedang dalam fase. end-of-support

Anda dapat memperbarui dengan aman dari versi 2.0. x dan yang lebih baru ke versi terbaru AWS Encryption SDK for Java tanpa kode atau perubahan data apa pun. Namun, fitur keamanan baru diperkenalkan di versi 2.0. x tidak kompatibel ke belakang. Untuk memperbarui dari versi lebih awal dari 1.7. x ke versi 2.0. x dan yang lebih baru, Anda harus terlebih dahulu memperbarui ke yang terbaru 1. x versiAWS Encryption SDK. Untuk detailnya, lihat MigrasiAWS Encryption SDK.

Anda dapat menginstal dengan cara berikut. AWS Encryption SDK for Java

Secara manual

Untuk menginstalAWS Encryption SDK for Java, kloning atau unduh aws-encryption-sdk-java GitHubrepositori.

Menggunakan Apache Maven

AWS Encryption SDK for JavaIni tersedia melalui Apache Maven dengan definisi ketergantungan berikut.


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

Setelah Anda menginstal SDK, mulailah dengan melihat contoh kode Java dalam panduan ini dan Javadoc aktif. GitHub

AWS KMSgantungan kunci di AWS Encryption SDK for Java

Versi 3. x dari AWS Encryption SDK for Java menggunakan keyrings untuk melakukan enkripsi amplop. AWS KMSGantungan kunci dasar hanya AWS Encryption SDK for Java mengambil satu tombol KMS. Mereka juga membutuhkan AWS KMS klien, yang memberi Anda kesempatan untuk mengkonfigurasi klien untuk kunci KMS. Wilayah AWS

Untuk membuat AWS KMS keyring dengan satu atau lebih tombol pembungkus, gunakan multi-keyring. Ini AWS Encryption SDK for Java memiliki multi-keyring khusus yang mengambil satu atau lebih AWS KMS tombol, dan multi-keyring standar yang mengambil satu atau lebih gantungan kunci dari jenis apa pun yang didukung. Beberapa programmer lebih suka menggunakan metode multi-keyring untuk membuat semua keyrings mereka, dan mendukung strategi ituAWS Encryption SDK for Java.

AWS Encryption SDK for JavaIni menyediakan keyring kunci tunggal dasar dan multi-keyrings untuk semua kasus penggunaan umum, termasuk kunci Multi-wilayah. AWS KMS

Misalnya, untuk membuat AWS KMS keyring dengan satu AWS KMS tombol, Anda dapat menggunakan metodeCreateAwsKmsKeyring()].


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

Untuk membuat keyring dengan satu atau lebih AWS KMS tombol, gunakan CreateAwsKmsMultiKeyring() metode ini. Contoh ini menggunakan dua kunci KMS. Untuk menentukan satu kunci KMS, gunakan hanya generator parameter. msKeyIdsParameter yang menentukan kunci KMS tambahan adalah opsional.

Input untuk keyring ini tidak membutuhkan AWS KMS klien. Sebaliknya, AWS Encryption SDK menggunakan AWS KMS klien default untuk setiap Wilayah diwakili oleh kunci KMS di keyring. Misalnya, jika kunci KMS yang diidentifikasi oleh nilai Generator parameter berada di Wilayah AS Barat (Oregon) (us-west-2), akan AWS Encryption SDK membuat AWS KMS klien default untuk Wilayah tersebutus-west-2. Jika Anda perlu menyesuaikan AWS KMS klien, gunakan CreateAwsKmsKeyring() metode ini.


// 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 Javamendukung AWS KMS keyrings yang menggunakan enkripsi simetris (SYMMETRIC_DEFAULT) atau kunci KMS RSA asimetris. AWS KMSkeyrings yang dibuat dengan kunci KMS RSA asimetris hanya dapat berisi satu key pair.

Untuk mengenkripsi dengan AWS KMS keyring RSA asimetris, Anda tidak perlu kms: GenerateDataKey atau KMS:Encrypt karena Anda harus menentukan materi kunci publik yang ingin Anda gunakan untuk enkripsi saat Anda membuat keyring. Tidak ada AWS KMS panggilan yang dilakukan saat mengenkripsi dengan keyring ini. Untuk mendekripsi dengan AWS KMS keyring RSA asimetris, Anda memerlukan izin KMS: Dekripsi.

Untuk membuat AWS KMS keyring RSA asimetris, Anda harus memberikan kunci publik dan kunci pribadi ARN dari kunci KMS RSA asimetris Anda. Kunci publik harus dikodekan PEM. Contoh berikut membuat AWS KMS keyring dengan asimetris RSA key pair.


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

Konteks enkripsi yang diperlukan dalam versi 3.x

Dengan versi 3. x dariAWS Encryption SDK for Java, Anda dapat menggunakan konteks enkripsi CMM yang diperlukan untuk memerlukan konteks enkripsi dalam operasi kriptografi Anda. Konteks enkripsi adalah sekumpulan pasangan kunci-nilai non-rahasia. Konteks enkripsi terikat secara kriptografis ke data terenkripsi sehingga konteks enkripsi yang sama diperlukan untuk mendekripsi bidang. Bila Anda menggunakan konteks enkripsi CMM yang diperlukan, Anda dapat menentukan satu atau beberapa kunci konteks enkripsi yang diperlukan (kunci wajib) yang harus disertakan dalam semua panggilan enkripsi dan dekripsi.

catatan

Konteks enkripsi yang diperlukan CMM hanya dapat dioperasikan dengan versi 4. x dari AWS Encryption SDK untuk .NET. Ini tidak dapat dioperasikan dengan implementasi bahasa pemrograman lainnya. Jika Anda mengenkripsi data menggunakan konteks enkripsi CMM yang diperlukan, Anda hanya dapat mendekripsi dengan versi 3. x dari AWS Encryption SDK for Java atau versi 4. x dari AWS Encryption SDK untuk .NET.

Pada enkripsi, AWS Encryption SDK memverifikasi bahwa semua kunci konteks enkripsi yang diperlukan disertakan dalam konteks enkripsi yang Anda tentukan. AWS Encryption SDKTanda konteks enkripsi yang Anda tentukan. Hanya pasangan kunci-nilai yang bukan kunci wajib yang diserialisasi dan disimpan dalam teks biasa di header pesan terenkripsi yang dikembalikan oleh operasi enkripsi.

Saat mendekripsi, Anda harus menyediakan konteks enkripsi yang berisi semua pasangan kunci-nilai yang mewakili kunci yang diperlukan. AWS Encryption SDKMenggunakan konteks enkripsi ini dan pasangan kunci-nilai yang disimpan dalam header pesan terenkripsi untuk merekonstruksi konteks enkripsi asli yang Anda tentukan dalam operasi enkripsi. Jika AWS Encryption SDK tidak dapat merekonstruksi konteks enkripsi asli, maka operasi dekripsi gagal. Jika Anda memberikan pasangan kunci-nilai yang berisi kunci yang diperlukan dengan nilai yang salah, pesan terenkripsi tidak dapat didekripsi. Anda harus memberikan pasangan nilai kunci yang sama yang ditentukan pada enkripsi.

penting

Pertimbangkan dengan cermat nilai mana yang Anda pilih untuk kunci yang diperlukan dalam konteks enkripsi Anda. Anda harus dapat memberikan kunci yang sama dan nilai yang sesuai lagi pada dekripsi. Jika Anda tidak dapat mereproduksi kunci yang diperlukan, pesan terenkripsi tidak dapat didekripsi.

Contoh berikut menginisialisasi AWS KMS keyring dengan konteks enkripsi CMM yang diperlukan.


// 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()
        );

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Contoh