unWrapKey

Perintah unWrapKey di alat key_mgmt_util mengimpor kunci simetris atau privat dibungkus (dienkripsi) dari file ke HSM. Hal ini dirancang untuk mengimpor kunci terenkripsi yang dibungkus oleh wrapKey di key_mgmt_util, tetapi juga dapat digunakan untuk membuka kunci yang dibungkus dengan alat-alat lain. Namun, dalam situasi tersebut, sebaiknya gunakan PKCS #11 atau pustaka perangkat lunak JCE untuk membuka kunci.

Kunci yang diimpor berfungsi seperti kunci yang dihasilkan oleh AWS CloudHSM. Walau bagaimanapun, nilai atribut OBJ_ATTR_ adalah nol, yang menunjukkan bahwa kunci itu tidak dihasilkan secara lokal.

Setelah Anda mengimpor kunci, pastikan bahwa Anda menandai atau menghapus file kunci. Perintah ini tidak mencegah Anda dari mengimpor materi kunci yang sama beberapa kali. Hasilnya—beberapa kunci dengan handel kunci yang berbeda dan materi kunci yang sama—menyulitkan untuk melacak penggunaan materi utama dan mencegahnya melebihi batas kriptografinya.

Sebelum Anda menjalankan perintah key_mgmt_util, Anda harus memulai key_mgmt_util dan masuk ke HSM sebagai pengguna kripto (CU).

Sintaksis

unWrapKey -h

unWrapKey -f <key-file-name> 
          -w <wrapping-key-handle> 
          [-sess]
          [-min_srv <minimum-number-of-HSMs>]          
          [-timeout <number-of-seconds>]
          [-aad <additional authenticated data filename>]
          [-tag_size <tag size>]
          [-iv_file <IV file>]
          [-attest]
          [-m <wrapping-mechanism>]
          [-t <hash-type>]
          [-nex]
          [-u <user id list>]
          [-m_value <number of users needed for approval>]
          [-noheader]
          [-l <key-label>]
          [-id <key-id>]
          [-kt <key-type>]
          [-kc <key-class]
          [-i <unwrapping-IV>]
    

Contoh

Contoh ini menunjukkan cara menggunakan unWrapKey untuk mengimpor kunci yang dibungkus dari file ke HSM. Pada contoh pertama, kita membuka kunci yang dibungkus dengan perintah key_mgmt_util wrapKey, dan dengan demikian memiliki header. Pada contoh kedua, kita membuka kunci yang dibungkus di luar key_mgmt_util, dan dengan demikian tidak memiliki header.

contoh : Buka kunci (dengan header)

Perintah ini mengimpor salinan kunci simetris 3DES yang dibungkus ke dalam HSM. Kuncinya dibuka dengan kunci AES dengan label 6, yang secara kriptografi identik dengan yang digunakan untuk membungkus kunci 3DES. Output menunjukkan bahwa kunci dalam file itu dibuka dan diimpor, dan bahwa handel kunci yang diimpor adalah 29.

        Command:  unWrapKey -f 3DES.key -w 6 -m 4

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Key Unwrapped.  Key Handle: 29

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

contoh : Buka kunci (tidak ada header)

Perintah ini mengimpor salinan kunci simetris 3DES yang dibungkus ke dalam HSM. Kuncinya dibuka dengan kunci AES dengan label 6, yang secara kriptografi identik dengan yang digunakan untuk membungkus kunci 3DES. Karena kunci 3DES ini tidak dibungkus dengan key_mgmt_util, parameter noheader ditentukan, bersama dengan parameter yang menyertainya yan diperlukan: label kunci (unwrapped3DES), kelas kunci (4), dan jenis kunci (21). Output menunjukkan bahwa kunci dalam file itu dibuka dan diimpor, dan bahwa handel kunci yang diimpor adalah 8.

Command: unWrapKey -f 3DES.key -w 6 -noheader -l unwrapped3DES -kc 4 -kt 21 -m 4
      
      Cfm3CreateUnwrapTemplate2 returned: 0x00 : HSM Return: SUCCESS
       Cfm2UnWrapWithTemplate3 returned: 0x00 : HSM Return: SUCCESS

       Key Unwrapped. Key Handle: 8

       Cluster Error Status
       Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
       Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

Parameter

-h

Menampilkan bantuan untuk perintah.

Wajib: Ya

-f

Jalur dan nama file yang berisi kunci yang dibungkus.

Wajib: Ya

-w

Menentukan kunci pembungkus. Masukkan handel kunci dari kunci AES atau kunci RSA pada HSM. Parameter ini diperlukan. Untuk menemukan handel kunci, gunakan perintah findKey.

Untuk membuat kunci pembungkus, gunakan genSymKeyuntuk menghasilkan kunci AES (tipe 31) atau GenRSA KeyPair untuk menghasilkan key pair RSA (tipe 0). Jika Anda menggunakan pasangan kunci RSA, pastikan untuk membungkus kunci dengan salah satu kunci, dan buka dengan yang lain. Untuk memverifikasi bahwa kunci dapat digunakan sebagai kunci pembungkus, gunakan getAttribute untuk mendapatkan nilai atribut OBJ_ATTR_WRAP, yang diwakili oleh konstanta 262.

Wajib: Ya

-sess

Membuat kunci yang hanya ada di sesi saat ini. Kunci tidak dapat dipulihkan setelah sesi berakhir.

Gunakan parameter ini ketika Anda memerlukan kunci hanya sebentar, seperti kunci pembungkus yang mengenkripsi, dan kemudian dengan cepat mendekripsi, kunci lain. Jangan gunakan kunci sesi untuk mengenkripsi data yang mungkin perlu Anda dekripsi setelah sesi berakhir.

Untuk mengubah kunci sesi menjadi kunci (token) persisten, gunakan setAttribute.

Default: Kunci persisten.

Wajib: Tidak

-min_srv

Menentukan jumlah minimum HSM tempat kunci disinkronkan sebelum nilai parameter -timeout kedaluwarsa. Jika kunci tidak disinkronkan ke jumlah tertentu server dalam waktu yang ditentukan, kunci tidak dibuat.

AWS CloudHSM secara otomatis menyinkronkan setiap kunci ke setiap HSM di cluster. Untuk mempercepat proses Anda, tetapkan nilai min_srv menjadi kurang dari jumlah HSM di klaster dan menetapkan nilai waktu habis rendah. Namun, perhatikan bahwa beberapa permintaan mungkin tidak menghasilkan kunci.

Default: 1

Wajib: Tidak

-timeout

Menentukan berapa lama (dalam detik) perintah menunggu kunci yang akan disinkronkan dengan jumlah HSM yang ditentukan oleh parameter min_srv.

Parameter ini hanya valid jika parameter min_srv juga digunakan dalam perintah.

Default: Tidak ada waktu habis. Perintah menunggu tanpa batas waktu dan kembali hanya ketika kunci disinkronkan ke jumlah minimum server.

Wajib: Tidak

-attest

Menjalankan pemeriksaan integritas yang memverifikasi bahwa firmware tempat klaster berjalan belum dirusak.

Default: Tidak ada pemeriksaan pengesahan.

Wajib: Tidak

-nex

Membuat kunci tidak dapat diekstrak. Kunci yang dihasilkan tidak dapat diekspor dari HSM.

Default: Kunci dapat diekstrak.

Wajib: Tidak

-m

Nilai yang mewakili mekanisme pembungkus. CloudHSM mendukung mekanisme berikut:

Mekanisme	Nilai
AES_KEY_WRAP_PAD_PKCS5	4
NIST_AES_WRAP_NO_PAD	5
NIST_AES_WRAP_PAD	6
RSA_AES	7
RSA_OAEP (untuk ukuran data maksimum, lihat catatan di bagian ini nanti)	8
AES_GCM	10
CLOUDHSM_AES_GCM	11
RSA_PKCS(untuk ukuran data maksimum, lihat catatan nanti di bagian ini). Lihat catatan 1 di bawah untuk perubahan yang akan datang.	12

Wajib: Ya

catatan

Saat menggunakan mekanisme RSA_OAEP pembungkus, ukuran kunci maksimum yang dapat Anda bungkus ditentukan oleh modulus kunci RSA dan panjang hash yang ditentukan sebagai berikut: Ukuran kunci maksimum = modulusLengthIn Bytes- (2* Bytes) -2. hashLengthIn

Saat menggunakan mekanisme pembungkus RSA_PKCS, ukuran kunci maksimum yang dapat Anda bungkus ditentukan oleh modulus kunci RSA sebagai berikut: Ukuran kunci maksimum = (Bytes -11). modulusLengthIn

-t

Algoritma hash	Nilai
SHA1	2
SHA256	3
SHA384	4
SHA512	5
SHA224 (berlaku untuk mekanisme RSA_AES dan RSA_OAEP)	6

Wajib: Tidak

-noheader

Jika Anda membuka kunci yang dibungkus di luar key_mgmt_util, Anda harus menentukan parameter ini dan semua parameter terkait lainnya.

Wajib: Tidak

catatan

Jika Anda menentukan parameter ini, Anda juga harus menentukan parameter berikut -noheader:

• -l

  Menentukan label yang akan ditambahkan ke kunci terbuka.

  Wajib: Ya

• -kc

  Menentukan label yang akan ditambahkan ke kunci terbuka. Berikut ini adalah nilai yang dapat diterima:

  3 = kunci privat dari pasangan kunci publik-privat

  4 = kunci rahasia (simetris)

  Wajib: Ya

• -kt

  Menentukan jenis kunci yang akan dibuka. Berikut ini adalah nilai yang dapat diterima:

  0 = RSA

  1 = DSA

  3 = ECC

  16 = GENERIC_SECRET

  21 = DES3

  31 = AES

  Wajib: Ya

Anda juga dapat secara opsional menentukan parameter berikut -noheader:

• -id

  ID yang akan ditambahkan ke kunci terbuka.

  Wajib: Tidak

• -i

  Vektor inisialisasi (IV) pembuka bungkus yang akan digunakan.

  Wajib: Tidak

[1] Sesuai dengan panduan NIST, ini tidak diizinkan untuk cluster dalam mode FIPS setelah 2023. Untuk cluster dalam mode non-FIPS, masih diperbolehkan setelah 2023. Lihat Kepatuhan FIPS 140: Penutupan Mekanisme 2024 untuk detail.

Topik terkait

• WrapKey

• exSymKey

• imSymKey