genSymKey - AWS CloudHSM
SintassiEsempiParameters (Parametri)Argomenti correlati

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

genSymKey

Il comando genSymKey nello strumento key_mgmt_util consente di generare una chiave simmetrica nei moduli HSM. È possibile specificare il tipo e le dimensioni della chiave, assegnare un ID e un'etichetta e condividere la chiave con altri utenti HSM. È anche possibile creare chiavi non estraibili e chiavi che scadono al termine della sessione. Quando il comando viene completato con successo, restituisce un handle che l'HSM assegna alla chiave. È possibile utilizzare l'handle per identificare la chiave per altri comandi.

Prima di eseguire un comando key_mgmt_util, devi avviare key_mgmt_util e accedere all'HSM come crypto user (CU).

Sintassi

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]

Esempi

Questi esempi mostrano come utilizzare genSymKey per creare chiavi simmetriche nei moduli HSM.

Suggerimento

Per utilizzare le chiavi create con questi esempi per le operazioni HMAC, è necessario impostare OBJ_ATTR_SIGN e OBJ_ATTR_VERIFY a TRUE dopo aver generato la chiave. Per impostare questi valori, utilizza setAttribute in CloudHSM Management Utility (CMU). Per ulteriori informazioni, vedi setAttribute.

Esempio Generazione di una chiave AES

Questo comando crea una chiave AES a 256 bit con un'etichetta aes256. L'output indica che l'handle della nuova chiave è 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
Esempio : Creazione di una chiave di sessione

Questo comando crea una chiave AES non estraibile a 192 bit valida solo per la durata della sessione corrente. È possibile creare una chiave come questa per eseguire il wrapping (e subito dopo annullare il wrapping) di una chiave in fase di esportazione. 

Command: genSymKey -t 31 -s 24 -l tmpAES -id wrap01 -nex -sess
Esempio : Risultato rapido

Questo comando crea una chiave generica a 512 byte con un'etichetta di IT_test_key. Il comando non attende la sincronizzazione della chiave con tutti i moduli HSM nel cluster. Restituisce invece un risultato non appena la chiave viene creata in qualsiasi HSM (-min_srv 1) o in 1 secondo (-timeout 1), qualunque sia la soluzione più rapida. Se la chiave non viene sincronizzata con il numero minimo di moduli HSM specificato prima della scadenza del timeout, non viene generata. È possibile utilizzare un comando come questo in uno script che crea numerose chiavi, come il loop for nell'esempio seguente. 

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;
Esempio : Creazione di una chiave generica con autorizzazione del quorum

Questo comando crea una chiave segreta generica a 2048 bit con l'etichetta generic-mV2. Il comando utilizza il parametro -u per condividere la chiave con un altro utente di crittografia, l'utente 6. Usa il parametro -m_value per richiedere un quorum di almeno due approvazioni per le operazioni di crittografia che utilizzano la chiave. Il comando utilizza inoltre il parametro -attest per verificare l'integrità del firmware in cui la chiave viene generata.

L'output indica che il comando ha generato una chiave con handle 9 e che il controllo di attestazione sul firmware del cluster ha avuto esito positivo.


                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
Esempio : Creazione e analisi di una chiave

Questo comando crea una chiave Triple DES con un'etichetta 3DES_shared e un ID IT-02. La chiave può essere utilizzata dall'utente corrente e dagli utenti 4 e 5. Il comando ha esito negativo se l'ID non è univoco nel cluster o se l'utente corrente è l'utente 4 o 5.

L'output indica che la nuova chiave ha un handle 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

Per verificare che la nuova chiave 3DES sia di proprietà dell'utente corrente e sia condivisa con gli utenti 4 e 5, utilizza getKeyInfo. Il comando usa l'handle assegnato alla nuova chiave (Key Handle: 7).

L'output conferma che la chiave è di proprietà dell'utente 3 ed è condivisa con gli utenti 4 e 5.

Command:  getKeyInfo -k 7

        Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS

        Owned by user 3

        also, shared to following 2 user(s):

                 4, 5

Per verificare le altre proprietà della chiave, utilizza getAttribute. Il primo comando usa getAttribute per ottenere tutti gli attributi (-a 512) dell'handle di chiave 7 (-o 7) e li scrive nel file attr_7. Il secondo comando usa cat per ottenere il contenuto del file attr_7.

Questo comando conferma che la chiave 7 è una chiave simmetrica (OBJ_ATTR_CLASS 0x04) 3DES (OBJ_ATTR_KEY_TYPE 0x15) a 192 bit (OBJ_ATTR_VALUE_LEN 0x00000018 o 24 byte) con un'etichetta 3DES_shared (OBJ_ATTR_LABEL 3DES_shared) e un ID IT_02 (OBJ_ATTR_ID IT-02). La chiave è persistente (OBJ_ATTR_TOKEN 0x01) ed estraibile (OBJ_ATTR_EXTRACTABLE 0x01) e può essere utilizzata per la crittografia, la decodifica e il wrapping.

Suggerimento

Per trovare gli attributi di una chiave che hai creato, ad esempio tipo, lunghezza, etichetta e ID, usa getAttribute. Per trovare le chiavi di un utente specifico, utilizza getKeyInfo. Per trovare le chiavi in base ai valori degli attributi, usa findKey.

Per informazioni sull'interpretazione degli attributi chiave, vedi Riferimento per l'attributo della chiave.

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
Suggerimento

Per utilizzare le chiavi create con questi esempi per le operazioni HMAC, è necessario impostare OBJ_ATTR_SIGN e OBJ_ATTR_VERIFY a TRUE dopo aver generato la chiave. Per impostare questi valori, usa setAttribute in CMU. Per ulteriori informazioni, vedi setAttribute.

Parameters (Parametri)

-h

Visualizza l'aiuto per il comando.

Campo obbligatorio: sì

-t

Specifica il tipo di chiave simmetrica. Inserisci la costante che rappresenta il tipo di chiave. Ad esempio, per creare una chiave AES, digita -t 31.

Valori validi:

Campo obbligatorio: sì

-s

Specifica le dimensioni della chiave in byte. Ad esempio, per creare una chiave a 192 bit, digita 24.

Valori validi per ogni tipo di chiave:

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

  • 3DES: 24 (192 bit)

  • Segreta generica: <3584 (28672 bit)

Campo obbligatorio: sì

-l

Specifica un'etichetta definita dall'utente per la chiave privata. Digita una stringa

Puoi usare qualsiasi frase che ti aiuti a identificare la chiave. Poiché l'etichetta non deve essere necessariamente univoca, è possibile utilizzarla per raggruppare e classificare le chiavi.

Campo obbligatorio: sì

-attestare

Esegue un controllo di integrità per verificare che il firmware su cui viene eseguito il cluster non sia stato manomesso.

Impostazione predefinita: nessun controllo di attestazione.

Campo obbligatorio: no

-id

Specifica un identificatore definito dall'utente per la chiave. Digita una stringa univoca nel cluster. L'impostazione predefinita è una stringa vuota.

Impostazione predefinita: nessun valore ID.

Campo obbligatorio: no

-min_srv

Specifica il numero minimo di HSM su cui la chiave importata è sincronizzata prima che il valore del parametro -timeout scada. Se la chiave non è sincronizzata sul numero di server specificato nel tempo allocato, non viene creata.

AWS CloudHSM sincronizza automaticamente ogni chiave su ogni modulo HSM nel cluster. Per velocizzare il processo, imposta il valore di min_srv su un cifra inferiore al numero di moduli HSM nel cluster e imposta un valore di timeout basso. Tuttavia, alcune richieste potrebbero non generare una chiave.

Impostazione predefinita: 1

Campo obbligatorio: no

-m_valore

Specifica il numero di utenti che devono approvare le operazioni di crittografia che utilizzano la chiave importata. Digitare un valore da 0 a 8.

Questo parametro stabilisce un requisito di autenticazione del quorum per la chiave. Il valore predefinito, 0, disabilita la funzionalità di autenticazione del quorum per la chiave. Quando su una chiave è abilitata la funzionalità di autenticazione del quorum, restituisce anche il numero di utenti che devono approvare le operazioni di crittografia che utilizzano la chiave.

Per trovare m_value di una chiave, utilizzare getKeyInfo.

Questo parametro è valido soltanto quando il parametro -u nel comando condivide la chiave con un numero sufficiente di utenti per soddisfare il requisito m_value.

Impostazione Predefinita: 0

Campo obbligatorio: no

-successivo

Rende la chiave non estraibile. La chiave generata non può essere esportata dall'HSM.

Impostazione predefinita: la chiave è estraibile.

Campo obbligatorio: no

-sessione

Crea una chiave che esiste solo nella sessione corrente. La chiave non può essere recuperata dopo la fine della sessione.

Utilizza questo parametro quando hai bisogno di una chiave solo per un breve periodo, ad esempio una chiave di wrapping che crittografa e quindi decodifica rapidamente un'altra chiave. Non utilizzare una chiave di sessione per crittografare dati che potresti aver bisogno di decodificare dopo la fine della sessione.

Per cambiare una chiave di sessione in una chiave persistente (token), usa setAttribute.

Impostazione Predefinita: la chiave è persistente.

Campo obbligatorio: no

timeout

Specifica per quanto tempo (in secondi) il comando attende la sincronizzazione di una chiave con il numero di HSM specificato dal parametro min_srv.

Questo parametro è valido solo quando il parametro min_srv viene utilizzato anche nel comando.

Impostazione Predefinita: No timeout Il comando attende a tempo indefinito e viene restituito solo quando la chiave è sincronizzata con il numero minimo di server.

Campo obbligatorio: no

-u

Condivide la chiave con gli utenti specificati. Questo parametro fornisce agli altri crypto user (CU) HSM l'autorizzazione ad utilizzare questa chiave nelle operazioni di cifratura.

Digita un elenco separato da virgole degli ID utente HSM, come -u 5,6. Non includere l'ID utente dell'HSM dell'utente attuale. Per trovare gli ID utente HSM dei CU su HSM, utilizzare ElencaUtenti. Quindi, per condividere o interrompere la condivisione di una chiave esistente, utilizza shareKey in cloudhsm_mgmt_util.

Impostazione predefinita: soltanto l'utente attuale può utilizzare la chiave.

Campo obbligatorio: no

Argomenti correlati