Bersiaplah dengan mengatasi perubahan yang melanggar Migrasi ke SDK Klien 5 Topik terkait

Migrasikan penyedia JCE Anda dari AWS CloudHSM Client SDK 3 ke Client SDK 5

Gunakan topik ini untuk memigrasikan penyedia JCE Anda dari AWS CloudHSM Client SDK 3 ke Client SDK 5. Untuk manfaat migrasi, lihatManfaat SDK AWS CloudHSM Klien 5.

Pada tahun AWS CloudHSM, aplikasi pelanggan melakukan operasi kriptografi menggunakan AWS CloudHSM Client Software Development Kit (SDK). Client SDK 5 adalah SDK utama yang terus memiliki fitur baru dan dukungan platform yang ditambahkan ke dalamnya.

Penyedia Client SDK 3 JCE menggunakan kelas khusus dan APIs itu bukan bagian dari spesifikasi JCE standar. Client SDK 5 untuk penyedia JCE adalah keluhan dengan spesifikasi JCE dan tidak kompatibel dengan Client SDK 3 di area tertentu. Aplikasi pelanggan mungkin memerlukan perubahan sebagai bagian dari migrasi ke SDK Klien 5. Bagian ini menguraikan perubahan yang diperlukan untuk migrasi yang berhasil.

Untuk meninjau petunjuk migrasi untuk semua penyedia, lihatMigrasi dari SDK AWS CloudHSM Klien 3 ke SDK Klien 5.

Topik

Bersiaplah dengan mengatasi perubahan yang melanggar
Migrasi ke SDK Klien 5
Topik terkait

Bersiaplah dengan mengatasi perubahan yang melanggar

Tinjau perubahan yang melanggar ini dan perbarui aplikasi Anda di lingkungan pengembangan yang sesuai.

Kelas dan nama Provider telah berubah

Apa yang telah berubah	Apa itu di Client SDK 3	Apa itu di Client SDK 5	Contoh
Kelas dan nama penyedia	Kelas penyedia JCE di Client SDK 3 dipanggil `CaviumProvider` dan memiliki nama Provider. `Cavium`	Di Client SDK 5, kelas Provider dipanggil `CloudHsmProvider` dan memiliki nama `CloudHSM` Provider.	Contoh cara menginisialisasi `CloudHsmProvider` objek tersedia di repositori AWS CloudHSM GitHub sampel.

Login eksplisit telah berubah, implisit belum

Apa yang telah berubah	Apa itu di Client SDK 3	Apa itu di Client SDK 5	Contoh
Login eksplisit	Klien SDK 3 menggunakan `LoginManager` kelas untuk login eksplisit. ¹	Di Client SDK 5, `CloudHSM` penyedia mengimplementasikan `AuthProvider` untuk login eksplisit. `AuthProvider`adalah kelas Java standar dan mengikuti cara idiomatik Java untuk masuk ke Provider. Dengan manajemen status login yang ditingkatkan di Client SDK 5, aplikasi tidak perlu lagi memantau dan melakukan login selama ²rekoneksi.	Untuk contoh tentang cara menggunakan login eksplisit dengan Client SDK 5, lihat LoginRunner contoh di repositori sampel AWS GitHub CloudHSM.
Login implisit	Tidak ada perubahan yang diperlukan untuk login implisit. File properti yang sama dan semua variabel lingkungan akan terus berfungsi untuk login implisit saat bermigrasi dari Client SDK 3 ke Client SDK 5.		Untuk contoh tentang cara menggunakan login implisit dengan Client SDK 5, lihat LoginRunner sampel di repositori AWS CloudHSM GitHub sampel.

[1] Cuplikan kode SDK 3 klien:


LoginManager lm = LoginManager.getInstance();
                       
lm.login(partition, user, pass);

[2] Cuplikan kode SDK 5 klien:


// Construct or get the existing provider object 
AuthProvider provider = new CloudHsmProvider();
                       
// Call login method on the CloudHsmProvider object
// Here loginHandler is a CallbackHandler
provider.login(null, loginHandler);

Untuk contoh tentang cara menggunakan login eksplisit dengan Client SDK 5, lihat LoginRunner sampel di repositori AWS CloudHSM GitHub sampel.

Tampilkan lebih banyak

Tampilkan lebih sedikit

Generasi kunci telah berubah

Apa yang telah berubah	Apa itu di Client SDK 3	Apa itu di Client SDK 5	Contoh
Pembuatan kunci	Di Client SDK 3, `Cavium[Key-type]AlgorithmParameterSpec` digunakan untuk menentukan parameter pembuatan kunci. Untuk cuplikan kode, lihat catatan kaki. 1	Di Client SDK 5, `KeyAttributesMap` digunakan untuk menentukan atribut pembuatan kunci. Untuk cuplikan kode, lihat catatan kaki. 2	Untuk contoh tentang cara menggunakan `KeyAttributesMap` untuk menghasilkan kunci simetris, lihat SymmetricKeys sampel di repositori sampel AWS CloudHSM GitHub .
Generasi pasangan kunci	Di Client SDK 3, `Cavium[Key-type]AlgorithmparameterSpec` digunakan untuk menentukan parameter pembuatan key pair. Untuk cuplikan kode, lihat catatan kaki. 3	Di Client SDK 5, `KeyPairAttributesMap` digunakan untuk menentukan parameter ini. Untuk cuplikan kode, lihat catatan kaki. 4	Untuk contoh tentang cara menggunakan `KeyAttributesMap` untuk menghasilkan kunci asimetris, lihat AsymmetricKeys sampel di repositori AWS CloudHSM GitHub sampel.

[1] Cuplikan kode pembuatan kunci SDK 3 klien:


KeyGenerator keyGen = KeyGenerator.getInstance("AES", "Cavium");
CaviumAESKeyGenParameterSpec aesSpec = new CaviumAESKeyGenParameterSpec(
keySizeInBits,
keyLabel,
isExtractable,
isPersistent);
keyGen.init(aesSpec);
SecretKey aesKey = keyGen.generateKey();

[2] Cuplikan kode pembuatan kunci SDK 5 klien:


KeyGenerator keyGen = KeyGenerator.getInstance("AES",
CloudHsmProvider.PROVIDER_NAME);
                    
final KeyAttributesMap aesSpec = new KeyAttributesMap();
aesSpec.put(KeyAttribute.LABEL, keyLabel);
aesSpec.put(KeyAttribute.SIZE, keySizeInBits);
aesSpec.put(KeyAttribute.EXTRACTABLE, isExtractable);
aesSpec.put(KeyAttribute.TOKEN, isPersistent);
                    
keyGen.init(aesSpec);
SecretKey aesKey = keyGen.generateKey();

[3] Cuplikan kode pembuatan key pair SDK 3 klien::


KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("rsa", "Cavium");
CaviumRSAKeyGenParameterSpec spec = new CaviumRSAKeyGenParameterSpec(
keySizeInBits,
new BigInteger("65537"),
label + ":public",
label + ":private",
isExtractable,
isPersistent);
                    
keyPairGen.initialize(spec);
                    
keyPairGen.generateKeyPair();

[4] Cuplikan kode pembuatan key pair SDK 5 klien:


KeyPairGenerator keyPairGen =
KeyPairGenerator.getInstance("RSA", providerName);
                    
// Set attributes for RSA public key
final KeyAttributesMap publicKeyAttrsMap = new KeyAttributesMap();
publicKeyAttrsMap.putAll(additionalPublicKeyAttributes);
publicKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Public");
publicKeyAttrsMap.put(KeyAttribute.MODULUS_BITS, keySizeInBits);
publicKeyAttrsMap.put(KeyAttribute.PUBLIC_EXPONENT,
new BigInteger("65537").toByteArray());
                    
// Set attributes for RSA private key
final KeyAttributesMap privateKeyAttrsMap = new KeyAttributesMap();
privateKeyAttrsMap.putAll(additionalPrivateKeyAttributes);
privateKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Private");
                    
// Create KeyPairAttributesMap and use that to initialize the 
// keyPair generator
KeyPairAttributesMap keyPairSpec =
new KeyPairAttributesMapBuilder()
.withPublic(publicKeyAttrsMap)
.withPrivate(privateKeyAttrsMap)
.build();
                    
keyPairGen.initialize(keyPairSpec);
keyPairGen.generateKeyPair();

Tampilkan lebih banyak

Tampilkan lebih sedikit

Menemukan, menghapus, dan mereferensikan kunci telah berubah

Menemukan kunci yang sudah dihasilkan dengan AWS CloudHSM memerlukan penggunaan. KeyStore Klien SDK 3 memiliki dua KeyStore jenis: Cavium danCloudHSM. Klien SDK 5 hanya memiliki satu KeyStore jenis:CloudHSM.

Pindah dari Cavium KeyStore ke CloudHSM KeyStore membutuhkan perubahan KeyStore tipe. Selain itu, Client SDK 3 menggunakan pegangan kunci untuk referensi kunci, sedangkan Client SDK 5 menggunakan label kunci. Perubahan perilaku yang dihasilkan tercantum di bawah ini.

Apa yang telah berubah	Apa itu di Client SDK 3	Apa itu di Client SDK 5	Contoh
Referensi utama	Dengan Client SDK 3, aplikasi menggunakan label kunci atau pegangan kunci untuk referensi kunci di HSM. Mereka menggunakan label dengan KeyStore untuk menemukan kunci, atau mereka menggunakan pegangan dan membuat `CaviumKey` objek.	Di Client SDK 5, aplikasi dapat menggunakan tombol AWS CloudHSM KeyStore Kelas Java untuk Client SDK 5 untuk menemukan kunci berdasarkan label. Untuk menemukan kunci dengan pegangan, gunakan AWS CloudHSM `KeyStoreWithAttributes` dengan AWS CloudHSM `KeyReferenceSpec`.
Menemukan beberapa entri	Saat mencari kunci menggunakan`getEntry`,`getKey`, atau `getCertificate` dalam skenario di mana beberapa item dengan kriteria yang sama ada di `Cavium` KeyStore, hanya entri pertama yang ditemukan yang akan dikembalikan.	Dengan AWS CloudHSM `KeyStore` dan`KeyStoreWithAttributes`, skenario yang sama ini akan menghasilkan pengecualian yang dilemparkan. Untuk memperbaiki masalah ini, disarankan untuk mengatur label unik untuk kunci menggunakan Mengatur atribut kunci dengan CloudHSM CLI perintah di CloudHSM CLI. Atau gunakan `KeyStoreWithAttributes#getKeys` untuk mengembalikan semua kunci yang sesuai dengan kriteria.
Temukan semua kunci	Dimungkinkan di Client SDK 3 untuk menemukan semua kunci di HSM menggunakan. `Util.findAllKeys()`	Client SDK 5 membuat pencarian kunci lebih sederhana dan lebih efisien dengan menggunakan `KeyStoreWithAttributes` kelas. Jika memungkinkan, cache kunci Anda untuk meminimalkan latensi. Untuk informasi selengkapnya, lihat Mengelola kunci secara efektif dalam aplikasi Anda. Bila Anda perlu mengambil semua kunci dari HSM, gunakan `KeyStoreWithAttributes#getKeys` dengan kosong. `KeyAttributesMap`	Contoh yang menggunakan `KeyStoreWithAttributes` kelas untuk menemukan kunci tersedia di repositori AWS CloudHSM GitHub sampel dan cuplikan kode ditampilkan di. 1
Penghapusan kunci	Klien SDK 3 digunakan `Util.deleteKey()` untuk menghapus kunci.	`Key`Objek di Client SDK 5 mengimplementasikan `Destroyable` antarmuka yang memungkinkan kunci dihapus menggunakan `destroy()` metode antarmuka ini.	Kode contoh yang menunjukkan fungsionalitas tombol hapus dapat ditemukan di repositori sampel GitHub CloudHSM. Cuplikan sampel untuk setiap SDK ditampilkan di. 2

[1] cuplikan ditunjukkan di bawah ini:


KeyAttributesMap findSpec = new KeyAttributesMap();
findSpec.put(KeyAttribute.LABEL, label);
findSpec.put(KeyAttribute.KEY_TYPE, keyType);
KeyStoreWithAttributes keyStore = KeyStoreWithAttributes.getInstance("CloudHSM");
                    
keyStore.load(null, null);
keyStore.getKey(findSpec);

[2] Menghapus kunci di Client SDK 3:
```
Util.deleteKey(key);
```
Menghapus kunci di Client SDK 5:
```
((Destroyable) key).destroy();
```

Tampilkan lebih banyak

Tampilkan lebih sedikit

Operasi membuka cipher telah berubah, operasi cipher lainnya belum

catatan

Tidak ada perubahan yang diperlukan untuk operasi Cipher. encrypt/decrypt/wrap

Operasi buka bungkus memerlukan CaviumUnwrapParameterSpec kelas Client SDK 3 untuk diganti dengan salah satu kelas berikut khusus untuk operasi kriptografi yang terdaftar.

GCMUnwrapKeySpecuntuk AES/GCM/NoPadding membuka bungkusnya
IvUnwrapKeySpecuntuk AESWrap unwrap dan AES/CBC/NoPadding unwrap
OAEPUnwrapKeySpecuntuk RSA OAEP unwrap

Contoh cuplikan untuk: OAEPUnwrapkeySpec


OAEPParameterSpec oaepParameterSpec =
new OAEPParameterSpec(
        "SHA-256",
        "MGF1",
        MGF1ParameterSpec.SHA256,
        PSpecified.DEFAULT);

KeyAttributesMap keyAttributesMap =
        new KeyAttributesMap(KeyAttributePermissiveProfile.KEY_CREATION);
keyAttributesMap.put(KeyAttribute.TOKEN, true);
keyAttributesMap.put(KeyAttribute.EXTRACTABLE, false);

OAEPUnwrapKeySpec spec = new OAEPUnwrapKeySpec(oaepParameterSpec,
        keyAttributesMap);

Cipher hsmCipher =
        Cipher.getInstance(
                "RSA/ECB/OAEPPadding",
                CloudHsmProvider.PROVIDER_NAME);
hsmCipher.init(Cipher.UNWRAP_MODE, key, spec);

Tampilkan lebih banyak

Tampilkan lebih sedikit

Operasi tanda tangan tidak berubah

Tidak ada perubahan yang diperlukan untuk operasi Tanda Tangan.

Migrasi ke SDK Klien 5

Ikuti petunjuk di bagian ini untuk bermigrasi dari Client SDK 3 ke Client SDK 5.

catatan

Amazon Linux, Ubuntu 16.04, Ubuntu 18.04 CentOS 6, CentOS 8, dan RHEL 6 saat ini tidak didukung dengan Client SDK 5. Jika saat ini Anda menggunakan salah satu platform ini dengan Client SDK 3, Anda harus memilih platform yang berbeda saat bermigrasi ke Client SDK 5.

Copot pemasangan penyedia JCE untuk Client SDK 3.

Copot pemasangan Daemon Klien untuk SDK Klien 3.

catatan

Konfigurasi khusus perlu diaktifkan lagi.

Instal penyedia Client SDK JCE dengan mengikuti langkah-langkahnya. Instal penyedia JCE untuk AWS CloudHSM Client SDK 5
Client SDK 5 memperkenalkan format file konfigurasi baru dan alat bootstrap baris perintah. Untuk mem-bootstrap penyedia Client SDK 5 JCE Anda, ikuti petunjuk yang tercantum dalam panduan pengguna di bawah. Bootstrap Klien SDK
Di lingkungan pengembangan Anda, uji aplikasi Anda. Lakukan pembaruan pada kode yang ada untuk menyelesaikan perubahan yang melanggar sebelum migrasi terakhir Anda.

Topik terkait

Praktik terbaik untuk AWS CloudHSM

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

Migrasi Penyedia Penyimpanan Kunci (KSP)

SDK Klien 5