genSymKey - AWS CloudHSM
SintaksContohParameterTopik terkait

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

genSymKey

Perintah genSymKey di alat key_mgmt_util menghasilkan kunci simetris di HSM Anda. Anda dapat menentukan jenis dan ukuran kunci, menetapkan ID dan label, dan berbagi kunci dengan pengguna HSM lainnya. Anda juga dapat membuat kunci yang tidak dapat diekstrak dan kunci yang kedaluwarsa ketika sesi berakhir. Ketika perintah berhasil, perintah mengembalikan handel kunci yang HSM tetapkan ke kunci. Anda dapat menggunakan handel kunci untuk mengidentifikasi kunci untuk perintah lain.

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

Sintaks

genSymKey -h

genSymKey -t <key-type>
          -s <key-size> 
          -l <label> 
          [-id <key-ID>] 
          [-min_srv <minimum-number-of-servers>] 
          [-m_value <0..8>]
          [-nex] 
          [-sess] 
          [-timeout <number-of-seconds> ]
          [-u <user-ids>] 
          [-attest]

Contoh

Contoh ini menunjukkan cara menggunakan genSymKey untuk membuat kunci simetris di HSM Anda.

Tip

Untuk menggunakan kunci yang Anda buat dengan contoh-contoh ini untuk operasi HMAC, Anda harus mengatur OBJ_ATTR_SIGN dan OBJ_ATTR_VERIFY menjadi TRUE setelah Anda menghasilkan kunci. Untuk menetapkan nilai-nilai ini, gunakan setAttribute di Utilitas Manajemen CloudHSM (CMU). Untuk informasi lebih lanjut, lihat setAttribute.

contoh : Hasilkan kunci AES

Perintah ini membuat kunci AES 256-bit dengan label aes256. Output menunjukkan bahwa handel kunci dari kunci baru adalah 6.

Command: genSymKey -t 31 -s 32 -l aes256

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 6

        Cluster Error Status
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
contoh : Buat kunci sesi

Perintah ini membuat kunci AES 192-bit yang tidak dapat diekstrak yang valid hanya dalam sesi saat ini. Anda mungkin perlu membuat kunci seperti ini untuk membungkus (dan kemudian segera membuka) kunci yang sedang diekspor. 

Command: genSymKey -t 31 -s 24 -l tmpAES -id wrap01 -nex -sess
contoh : Kembali dengan cepat

Perintah ini membuat kunci 512-byte generik dengan label IT_test_key. Perintah tidak menunggu kunci untuk disinkronkan ke semua HSM di klaster. Sebaliknya, perintah kembali segera setelah kunci dibuat pada salah satu HSM (-min_srv 1) atau dalam 1 detik (-timeout 1), mana yang lebih pendek. Jika kunci tidak disinkronkan ke jumlah minimum tertentu HSM sebelum batas waktu berakhir, kunci tidak dihasilkan. Anda mungkin ingin menggunakan perintah seperti ini dalam skrip yang membuat banyak kunci, seperti for pada contoh berikut. 

Command: genSymKey -t 16 -s 512 -l IT_test_key -min_srv 1 -timeout 1

$  for i in {1..30}; 
     do /opt/cloudhsm/bin/key_mgmt_util singlecmd loginHSM -u CU -s example_user -p example_pwd genSymKey -l aes -t 31 -s 32 -min_srv 1 -timeout 1; 
 done;
contoh : Buat kunci generik resmi kuorum

Perintah ini membuat kunci rahasia generik 2048-bit dengan label generic-mV2. Perintah menggunakan parameter -u untuk berbagi kunci dengan CU lain, pengguna 6. Perintah menggunakan parameter -m_value untuk mengharuskan kuorum setidaknya dua persetujuan untuk setiap operasi kriptografi yang menggunakan kunci. Perintah ini juga menggunakan parameter -attest untuk memverifikasi integritas firmware tempat kunci dihasilkan.

Output menunjukkan bahwa perintah menghasilkan kunci dengan handel kunci 9 dan bahwa pemeriksaan pengesahan pada firmware klaster telah dilewatkan.


                Command:  genSymKey -t 16 -s 2048 -l generic-mV2 -m_value 2 -u 6 -attest

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 9

        Attestation Check : [PASS]

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
contoh : Buat dan periksa kunci

Perintah ini membuat kunci Triple DES dengan label 3DES_shared dan ID dari IT-02. Kuncinya bisa digunakan oleh pengguna saat ini, dan pengguna 4 dan 5. Perintah gagal jika ID tidak unik dalam klaster atau jika pengguna saat ini adalah pengguna 4 atau 5.

Output menunjukkan bahwa kunci baru memiliki handel kunci 7.

Command: genSymKey -t 21 -s 24 -l 3DES_shared -id IT-02 -u 4,5

       Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 7

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

Untuk memverifikasi bahwa kunci 3DES baru dimiliki oleh pengguna saat ini dan dibagikan dengan pengguna 4 dan 5, gunakan getKeyInfo. Perintah menggunakan handel yang ditetapkan ke kunci baru (Key Handle: 7).

Output menunjukkan bahwa kunci tersebut dimiliki oleh pengguna 3 dan berbagi dengan pengguna 4 dan 5.

Command:  getKeyInfo -k 7

        Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS

        Owned by user 3

        also, shared to following 2 user(s):

                 4, 5

Untuk mengonfirmasi properti lain dari kunci, gunakan getAttribute. Perintah pertama menggunakan getAttribute untuk mendapatkan semua atribut (-a 512) dari handel kunci 7 (-o 7). Perintah menuliskannya ke file attr_7. Perintah kedua menggunakan cat untuk mendapatkan konten file attr_7.

Perintah ini mengonfirmasi bahwa kunci 7 adalah 192-bit (OBJ_ATTR_VALUE_LEN 0x00000018 atau 24-byte) 3DES (OBJ_ATTR_KEY_TYPE 0x15) kunci simetris (OBJ_ATTR_CLASS 0x04) dengan label3DES_shared (OBJ_ATTR_LABEL 3DES_shared) dan ID dari IT_02 (OBJ_ATTR_ID IT-02). Kunci persisten (OBJ_ATTR_TOKEN 0x01) dan dapat diekstrak (OBJ_ATTR_EXTRACTABLE 0x01) dan dapat digunakan untuk enkripsi, dekripsi, dan pembungkus.

Tip

Untuk menemukan atribut kunci yang telah Anda buat, seperti jenis, panjang, label, dan ID, gunakan getAttribute. Untuk menemukan kunci untuk pengguna tertentu, gunakan getKeyInfo. Untuk menemukan kunci berdasarkan nilai atribut mereka, gunakan findKey.

Untuk membantu menafsirkan atribut kunci, lihat Referensi Atribut Kunci.

Command:  getAttribute -o 7 -a 512 -out attr_7

got all attributes of size 444 attr cnt 17
Attributes dumped into attr_7 file

        Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS


$  cat attr_7

OBJ_ATTR_CLASS
0x04
OBJ_ATTR_KEY_TYPE
0x15
OBJ_ATTR_TOKEN
0x01
OBJ_ATTR_PRIVATE
0x01
OBJ_ATTR_ENCRYPT
0x01
OBJ_ATTR_DECRYPT
0x01
OBJ_ATTR_WRAP
0x00
OBJ_ATTR_UNWRAP
0x00
OBJ_ATTR_SIGN
0x00
OBJ_ATTR_VERIFY
0x00
OBJ_ATTR_LOCAL
0x01
OBJ_ATTR_SENSITIVE
0x01
OBJ_ATTR_EXTRACTABLE
0x01
OBJ_ATTR_LABEL
3DES_shared
OBJ_ATTR_ID
IT-02
OBJ_ATTR_VALUE_LEN
0x00000018
OBJ_ATTR_KCV
0x59a46e
Tip

Untuk menggunakan kunci yang Anda buat dengan contoh-contoh ini untuk operasi HMAC, Anda harus mengatur OBJ_ATTR_SIGN dan OBJ_ATTR_VERIFY menjadi TRUE setelah Anda menghasilkan kunci. Untuk menetapkan nilai-nilai ini, gunakan setAttribute di CMU. Untuk informasi lebih lanjut, lihat setAttribute.

Parameter

-h

Menampilkan bantuan untuk perintah.

Wajib: Ya

-t

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

Nilai yang valid:

  • 16: GENERIC_SECRET. Kunci rahasia generik adalah array byte yang tidak sesuai dengan standar tertentu, seperti persyaratan untuk kunci AES.

  • 18: RC4. Kunci RC4 tidak valid pada HSM mode FIPS

  • 21: Tiga DES (3DES). 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.

  • 31: AES

Wajib: Ya

-s

Menentukan ukuran kunci dalam byte. Misalnya, untuk membuat kunci 192-bit, ketik 24.

Nilai yang valid untuk setiap jenis kunci:

  • AES: 16 (128 bit), 24 (192 bit), 32 (256 bit)

  • 3DES: 24 (192 bit)

  • Rahasia Generik: <3584 (28672 bit)

Wajib: Ya

-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

-attest

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

Default: Tidak ada pemeriksaan pengesahan.

Wajib: Tidak

-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

-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

-m_value

Menentukan jumlah pengguna yang harus menyetujui operasi kriptografi yang menggunakan kunci. Ketik nilai dari 0 sampai 8.

Parameter ini menetapkan persyaratan autentikasi kuorum untuk kunci. Nilai default, 0, menonaktifkan fitur autentikasi kuorum untuk kunci. Ketika autentikasi kuorum diaktifkan, jumlah tertentu pengguna harus menandatangani token untuk menyetujui operasi kriptografi yang menggunakan kunci, dan operasi yang berbagi atau batal berbagi kunci.

Untuk menemukan kunci, gunakan getKeyInfo. m_value

Parameter ini hanya valid jika parameter -u dalam perintah membagikan kunci dengan cukup pengguna untuk memenuhi persyaratan m_value.

Default: 0

Wajib: Tidak

-nex

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

Default: Kunci dapat diekstrak.

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

-u

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

Ketik daftar ID pengguna HSM yang dipisahkan koma, seperti -u 5,6. Jangan sertakan ID pengguna HSM dari pengguna saat ini. Untuk menemukan ID pengguna HSM dari pengguna di HSM Anda, gunakan listUsers. Untuk berbagi atau batal berbagi kunci yang ada, gunakan shareKey di cloudhsm_mgmt_util.

Default: Hanya pengguna saat ini dapat menggunakan kunci privat.

Wajib: Tidak

Topik terkait