Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Migrasikan penyedia JCE Anda dari AWS CloudHSM Client SDK 3 ke Client SDK 5
Gunakan topik ini untuk memigrasikan [penyedia JCE](java-library.md) Anda dari AWS CloudHSM Client SDK 3 ke Client SDK 5. Untuk manfaat migrasi, lihat[Manfaat SDK AWS CloudHSM Klien 5](client-sdk-5-benefits.md).
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, lihat[Migrasi dari SDK AWS CloudHSM Klien 3 ke SDK Klien 5](client-sdk-migration.md).
**Topics**
+ [Bersiaplah dengan mengatasi perubahan yang melanggar](#jce-migration-preparation-sdk5)
+ [Migrasi ke SDK Klien 5](#w2aac25c19c21c15)
+ [Topik terkait](#java-lib-migrate_to_sdk5-seealso)
## 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java#L43-L50). |
### 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. [1](#explicit_login_sdk3_note) | 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 [2](#explicit_login_sdk5_note)rekoneksi. | Untuk contoh tentang cara menggunakan login eksplisit dengan Client SDK 5, lihat LoginRunner contoh di repositori sampel [AWS GitHub CloudHSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141). |
| 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L143-L202) 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141) AWS CloudHSM GitHub sampel.
### 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](#key_generation_sdk3_note) | Di Client SDK 5, `KeyAttributesMap` digunakan untuk menentukan atribut pembuatan kunci. Untuk cuplikan kode, lihat catatan kaki. [2](#key_generation_sdk5_note) | Untuk contoh tentang cara menggunakan `KeyAttributesMap` untuk menghasilkan kunci simetris, lihat [SymmetricKeys sampel di repositori sampel](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java) 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](#key_pair_generation_sdk3_note) | Di Client SDK 5, `KeyPairAttributesMap` digunakan untuk menentukan parameter ini. Untuk cuplikan kode, lihat catatan kaki. [4](#key_pair_generation_sdk5_note) | Untuk contoh tentang cara menggunakan `KeyAttributesMap` untuk menghasilkan kunci asimetris, lihat [AsymmetricKeys sampel](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java) 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();
```
### 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` dan`CloudHSM`. 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](alternative-keystore_5.md) 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](cloudhsm_cli-key-set-attribute.md) 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](bp-application-integration.md#bp-manage-application). 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L205-L223) dan cuplikan kode ditampilkan di. [1](#using_keystore_att_note) |
| 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L229-L234). Cuplikan sampel untuk setiap SDK ditampilkan di. [2](#delete_key_note) |
+ [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();
```
### 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.
+ `GCMUnwrapKeySpec`untuk `AES/GCM/NoPadding` membuka bungkusnya
+ `IvUnwrapKeySpec`untuk `AESWrap unwrap` dan `AES/CBC/NoPadding unwrap`
+ `OAEPUnwrapKeySpec`untuk `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);
```
### 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.
1. Copot pemasangan penyedia JCE untuk Client SDK 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client-jce
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client-jce
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client-jce
```
------
1. Hentikan Daemon Klien untuk SDK Klien 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ CentOS 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 8 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo systemctl stop cloudhsm-client
```
------
1. Copot pemasangan Daemon Klien untuk SDK Klien 3.
------
#### [ Amazon Linux 2 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ CentOS 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 7 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ RHEL 8 ]
```
$ sudo yum remove cloudhsm-client
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo apt remove cloudhsm-client
```
------
**catatan**
Konfigurasi khusus perlu diaktifkan lagi.
1. Instal penyedia Client SDK JCE dengan mengikuti langkah-langkahnya. [Instal penyedia JCE untuk AWS CloudHSM Client SDK 5](java-library-install_5.md)
1. 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](cluster-connect.md#connect-how-to)
1. 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](best-practices.md)