imSymKey

Perintah imSymKey dalam alat key_mgmt_util mengimpor salinan teks terang kunci simetris dari file ke HSM. Anda dapat menggunakannya untuk mengimpor kunci yang Anda hasilkan dengan metode apa pun di luar HSM dan kunci yang diekspor dari HSM, seperti kunci yang ditulis oleh perintah exSymKey, ke file.

Selama proses impor, imSymKey menggunakan kunci AES yang Anda pilih (kunci pembungkus) untuk membungkus (mengenkripsi) dan kemudian membuka(dekripsi) kunci yang akan diimpor. Namun, imSymKey bekerja hanya pada file yang berisi kunci teks terang. Untuk mengekspor dan mengimpor kunci terenkripsi, gunakan WrapKey dan perintah. unWrapKey

Selain itu, perintah imSymKey mengimpor hanya kunci simetris. Untuk mengimpor kunci publik, gunakan importPubKey. Untuk mengimpor kunci pribadi, gunakan importPrivateKeyatau WrapKey.

catatan

Anda tidak dapat mengimpor kunci PEM yang dilindungi kata sandi menggunakan kunci simetris atau pribadi.

Kunci impor bekerja sangat mirip dengan kunci yang dihasilkan di HSM. Namun, nilai atribut OBJ_ATTR_LOCAL adalah nol, yang menunjukkan bahwa itu tidak dihasilkan secara lokal. Anda dapat menggunakan perintah berikut untuk berbagi kunci simetris saat Anda mengimpornya. Anda dapat menggunakan perintah shareKey di cloudhsm_mgmt_util untuk berbagi kunci setelah diimpor.


imSymKey -l aesShared -t 31 -f kms.key -w 3296 -u 5

Setelah Anda mengimpor kunci, pastikan untuk 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 kunci 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).

Sintaks


imSymKey -h

imSymKey -f <key-file>
         -w <wrapping-key-handle>  
         -t <key-type>
         -l <label>
         [-id <key-ID>]
         [-sess]
         [-wk <wrapping-key-file> ]
         [-attest]
         [-min_srv <minimum-number-of-servers>]
         [-timeout <number-of-seconds> ]
         [-u <user-ids>]

Contoh

Contoh ini menunjukkan cara menggunakan imSymKey untuk mengimpor kunci simetris ke dalam HSM Anda.

contoh : Impor kunci simetris AES

Contoh ini menggunakan imSymKey untuk mengimpor kunci simetris AES ke dalam HSM.

Perintah pertama menggunakan OpenSSL untuk menghasilkan kunci simetris AES 256-bit acak. Menyimpan kunci dalam file aes256.key.


$  openssl rand -out aes256-forImport.key 32

Perintah kedua menggunakan imSymKey untuk mengimpor kunci AES dari file aes256.key ke dalam HSM. Perintah menggunakan kunci 20, kunci AES di HSM, sebagai kunci pembungkus dan menentukan label imported. Berbeda dengan ID, label tidak perlu unik di klaster. Nilai dari parameter -t (tipe) adalah 31, yang mewakili AES.

Output menunjukkan bahwa kunci dalam file dibungkus dan dibuka, kemudian diimpor ke HSM, di mana handel kunci 262180 ditugaskan.


Command:  imSymKey -f aes256.key -w 20 -t 31 -l imported

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 262180

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

Perintah berikutnya menggunakan getAttribute untuk mendapatkan atribut OBJ_ATTR_LOCAL (Atribut 355) dari kunci yang baru diimpor dan menuliskannya ke file attr_262180.


Command:  getAttribute -o 262180 -a 355 -out attributes/attr_262180
Attributes dumped into attributes/attr_262180_imported file

        Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS

Ketika Anda memeriksa atribut file, Anda dapat melihat bahwa nilai atribut OBJ_ATTR_LOCAL adalah nol, yang menunjukkan bahwa materi kunci tidak dihasilkan dalam HSM.


$  cat attributes/attr_262180_local
OBJ_ATTR_LOCAL
0x00000000

contoh : Pindahkan kunci simetris antar cluster

Contoh ini menunjukkan cara menggunakan exSymKeydan imSymKey memindahkan kunci AES plaintext antar cluster. Anda mungkin menggunakan proses seperti ini untuk membuat pembungkus AES yang ada di HSM kedua klaster. Setelah kunci pembungkus bersama berada di tempat, Anda dapat menggunakan WrapKey unWrapKeydan untuk memindahkan kunci terenkripsi antara cluster.

Pengguna CU yang melakukan operasi ini harus memiliki izin untuk masuk ke HSM di kedua klaster.

Perintah pertama digunakan exSymKeyuntuk mengekspor kunci 14, kunci AES 32-bit, dari cluster 1 ke dalam file. aes.key Perintah menggunakan kunci 6, kunci AES pada HSM di klaster 1, sebagai kunci pembungkus.


Command: exSymKey -k 14 -w 6 -out aes.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "aes.key"

Pengguna kemudian masuk ke key_mgmt_util di klaster 2 dan menjalankan perintah imSymKey untuk mengimpor kunci dalam file aes.key ke dalam HSM di klaster 2. Perintah ini menggunakan kunci 252152, kunci AES pada HSM di klaster 2, sebagai kunci pembungkus.

Karena tombol pembungkus itu exSymKeydan imSymKey gunakan bungkus dan segera buka kunci target, tombol pembungkus pada cluster yang berbeda tidak perlu sama.

Output menunjukkan bahwa kunci berhasil diimpor ke dalam klaster 2 dan handel kunci 21 ditugaskan.


Command:  imSymKey -f aes.key -w 262152 -t 31 -l xcluster

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 21

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

Untuk membuktikan bahwa kunci 14 klaster 1 dan kunci 21 di klaster 2 memiliki materi kunci yang sama, dapatkan nilai pemeriksaan kunci (KCV) dari setiap kunci. Jika nilai KCV adalah sama, bahan utama adalah sama.

Perintah berikut menggunakan getAttribute di klaster 1 untuk menuliskan nilai atribut KCV (atribut 371) dari kunci 14 ke file attr_14_kcv. Kemudian, ini menggunakan perintah cat untuk mendapatkan isi dari file attr_14_kcv.


Command:  getAttribute -o 14 -a 371 -out attr_14_kcv
Attributes dumped into attr_14_kcv file

$  cat attr_14_kcv
OBJ_ATTR_KCV
0xc33cbd

Perintah serupa ini menggunakan getAttribute di klaster 2 untuk menulis nilai atribut KCV (atribut 371) kunci 21 ke file attr_21_kcv. Kemudian, ini menggunakan perintah cat untuk mendapatkan isi dari file attr_21_kcv.


Command:  getAttribute -o 21 -a 371 -out attr_21_kcv
Attributes dumped into attr_21_kcv file

$  cat attr_21_kcv
OBJ_ATTR_KCV
0xc33cbd

Output menunjukkan bahwa nilai KCV dari dua kunci adalah sama, yang membuktikan bahwa materi kunci adalah sama.

Karena materi kunci yang sama ada di HSM klaster kedua, Anda sekarang dapat berbagi kunci yang dienkripsi antara klaster tanpa pernah mengekspos kunci teks terang. Misalnya, Anda dapat menggunakan perintah wrapKey dengan kunci pembungkus 14 untuk mengekspor kunci terenkripsi dari klaster 1, dan kemudian gunakan unWrapKey dengan pembungkus kunci 21 untuk mengimpor kunci dienkripsi ke dalam klaster 2.

contoh : Impor kunci sesi

Perintah ini menggunakan parameter -sess dari imSymKey untuk mengimpor kunci 192-bit Triple DES yang hanya berlaku dalam sesi saat ini.

Perintah menggunakan parameter -f untuk menentukan file yang berisi kunci untuk diimpor, parameter -t untuk menentukan jenis kunci, dan parameter -w untuk menentukan kunci pembungkus. Perintah menggunakan parameter -l untuk menentukan label yang mengelompokkan kunci dan parameter -id untuk membuat pengenal yang mudah diingat, tapi unik, untuk kunci. Perintah ini juga menggunakan parameter -attest untuk memverifikasi firmware yang mengimpor kunci.

Output menunjukkan bahwa kunci berhasil dibungkus dan dibuka, diimpor ke HSM, dan handel kunci 37 ditugaskan. Selain itu, pemeriksaan pengesahan dilewatkan, yang menunjukkan bahwa firmware belum dirusak.


Command:  imSymKey -f 3des192.key -w 6 -t 21 -l temp -id test01 -sess -attest

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 37

        Attestation Check : [PASS]

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

Selanjutnya, Anda dapat menggunakan perintah getAttribute atau findKey untuk memverifikasi atribut kunci yang baru diimpor. Perintah berikut menggunakan findKey untuk memverifikasi bahwa kunci 37 memiliki jenis, label, dan ID yang ditentukan oleh perintah, dan bahwa itu adalah kunci sesi. Ditampilkan pada baris 5 output, findKey melaporkan bahwa satu-satunya kunci yang cocok dengan semua atribut adalah kunci 37.


Command:  findKey -t 21 -l temp -id test01 -sess 1
Total number of keys present 1

 number of keys matched from start index 0::0
37

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

        Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

Parameter

-attest

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

Default: Tidak ada pemeriksaan pengesahan.

Wajib: Tidak

-f

Menentukan file yang berisi kunci untuk diimpor.

File harus berisi salinan teks terang dari kunci AES atau Triple DES dengan panjang yang ditentukan. Kunci RC4 dan DES tidak valid pada HSM mode FIPS.

AES: 16, 24 atau 32 byte
Triple DES (3DES): 24 byte

Wajib: Ya

-h

Menampilkan bantuan untuk perintah.

Wajib: Ya

-id

Menentukan pengenal yang ditetapkan pengguna untuk kunci. Ketik string yang unik dalam klaster. Default-nya adalah string kosong.

Default: Tidak ada nilai ID.

Wajib: Tidak

-l

Menentukan label yang ditetapkan pengguna untuk kunci. Ketik string.

Anda dapat menggunakan frasa apa pun yang membantu Anda mengidentifikasi kunci. Karena label tidak harus unik, Anda dapat menggunakannya pada grup dan mengelompokkan kunci.

Wajib: Ya

-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

-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

-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

-t

Menentukan jenis kunci simetris. Masukkan konstanta yang mewakili jenis kunci. Misalnya, untuk membuat kunci AES, masukkan -t 31.

Nilai yang valid:

21: Tiga DES (3DES).
31: AES

Wajib: Ya

-u

Berbagi kunci yang Anda impor dengan pengguna tertentu. Parameter ini memberikan izin kepada pengguna kripto HSM (CU) lainnya untuk menggunakan kunci ini dalam operasi kriptografi.

Ketik satu ID atau daftar ID pengguna HSM yang dipisahkan koma, seperti -u 5,6. Jangan sertakan ID pengguna HSM dari pengguna saat ini. Untuk menemukan ID, Anda dapat menggunakan perintah listUsers di alat baris perintah cloudhsm_mgmt_util atau perintah listUsers pada alat baris perintah key_mgmt_util.

Wajib: Tidak

-w

Menentukan handel kunci dari kunci pembungkus. Parameter ini diperlukan. Untuk menemukan handel kunci, gunakan perintah findKey.

Kunci pembungkus adalah kunci dalam HSM yang digunakan untuk mengenkripsi (“membungkus”) dan kemudian mendekripsi (“membuka bungkus”) kunci selama proses impor. Hanya kunci AES yang dapat digunakan sebagai kunci pembungkus.

Anda dapat menggunakan kunci AES (dari berbagai ukuran) sebagai kunci pembungkus. Karena kunci pembungkus membungkus, dan kemudian segera membuka, kunci target, Anda dapat menggunakan sebagai kunci AES hanya sesi sebagai kunci pembungkus. Untuk menentukan apakah kunci dapat digunakan sebagai kunci pembungkus, gunakangetAttribute untuk mendapatkan nilai dari atribut OBJ_ATTR_WRAP (262). Untuk membuat kunci pembungkus, gunakan genSymKeyuntuk membuat kunci AES (tipe 31).

Jika Anda menggunakan parameter -wk untuk menentukan kunci pembungkus eksternal, kunci pembungkus -w digunakan untuk membuka, tetapi tidak untuk membungkus, kunci yang sedang diimpor.

catatan

Kunci 4 adalah kunci internal yang tidak didukung. Kami merekomendasikan bahwa Anda menggunakan kunci AES yang Anda buat dan kelola sebagai kunci pembungkus.

Wajib: Ya

-wk

Gunakan kunci AES dalam file tertentu untuk membungkus kunci yang sedang diimpor. Masukkan jalur dan nama file yang berisi kunci AES plaintext.

Bila Anda menyertakan parameter ini. imSymKey menggunakan kunci dalam file -wk untuk membungkus kunci yang diimpor dan menggunakan kunci dalam HSM yang ditentukan oleh parameter -w untuk membukanya. Nilai parameter -w dan -wk harus menyelesaikan ke kunci plaintext yang sama.

Default: Gunakan kunci pembungkus pada HSM untuk membuka.

Wajib: Tidak

Topik terkait

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

importPubKey

insertMaskedObject