Syntax Beispiele Parameter Verwandte Themen

genSymKey

Der genSymKey-Befehl im key_mgmt_util-Tool generiert einen symmetrischen Schlüssel in Ihren HSMs. Sie können Schlüsseltyp und Größe festlegen, eine ID und Bezeichnung zuweisen und den Schlüssel für andere HSM-Benutzer freigeben. Sie können auch nicht extrahierbare Schlüssel erstellen sowie Schlüssel, die ablaufen, wenn die Sitzung endet. Wenn der Befehl erfolgreich ausgeführt wurde, wird ein Schlüssel-Handle zurückgegeben, das das HSM zum Schlüssel zuweist. Sie können das Schlüssel-Handle nutzen, damit der Schlüssel für andere Befehle identifizierbar ist.

Bevor Sie einen key_mgmt_util-Befehl ausführen, müssen Sie key_mgmt_util starten und sich am HSM als Crypto-Benutzer (CU) anmelden.

Syntax


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]

Beispiele

Diese Beispiele verdeutlichen, wie mit genSymKey symmetrische Schlüssel in Ihren HSMs erstellt werden.

Tipp

Um die Schlüssel, die Sie mit diesen Beispielen erstellen, für HMAC-Operationen zu verwenden, müssen Sie nach dem Generieren des Schlüssels den Wert OBJ_ATTR_SIGN und OBJ_ATTR_VERIFY auf TRUE festlegen. Verwenden Sie setAttribute in CloudHSM Management Utility (CMU), um diese Werte festzulegen. Weitere Informationen finden Sie unter setAttribute.

Beispiel : Generieren eines AES-Schlüssels

Mit diesem Befehl wird ein 256-Bit-AES-Schlüssel mit der Bezeichnung aes256 erstellt. Die Ausgabe zeigt, dass das Schlüssel-Handle des neuen Schlüssels 6 ist.


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

Beispiel : Erstellen eines Sitzungsschlüssels

Mit diesem Befehl wird ein nicht extrahierbarer 192-Bit-AES-Schlüssel erstellt, der nur für die aktuelle Sitzung gültig ist. Sie können einen solchen Schlüssel erstellen, um einen Schlüssel, der exportiert wird, zu verpacken (und dann sofort zu entpacken).


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

Beispiel : Schnelles Zurückgeben

Mit diesem Befehl wird ein generischer 512-Byte-Schlüssel mit der Bezeichnung IT_test_key erstellt. Der Befehl wartet nicht, bis der Schlüssel für alle HSMs in dem Cluster synchronisiert wird. Stattdessen wird er zurückgegeben, sobald der Schlüssel in einem der HSMs erstellt ist (-min_srv 1) oder nach Ablauf von 1 Sekunde (-timeout 1), je nachdem, was kürzer ist. Falls der Schlüssel vor Ablauf des Zeitlimits nicht für die vorgegebene Mindestanzahl von HSMs synchronisiert wird, wird er nicht erstellt. Sie können einen solchen Befehl in einem Skript verwenden, das zahlreiche Schlüssel erstellt, wie die for-Schleife im folgenden Beispiel.


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;

Beispiel : Erstellen eines allgemeinen Schlüssels mit Quorum-Autorisierung

Mit diesem Befehl wird ein allgemeiner geheimer 2048-Bit-Schlüssel mit der Bezeichnung generic-mV2 erstellt. Der Befehl verwendet den -u-Parameter, um den Schlüssel mit einem anderen CU, Benutzer 6, zu teilen. Er verwendet den -m_value-Parameter, damit für alle kryptografischen Vorgänge, die den Schlüssel verwenden, ein Quorum aus mindestens zwei Genehmigungen erforderlich ist. Der Befehl verwendet auch den -attest-Parameter, um die Integrität der Firmware zu überprüfen, auf der der Schlüssel generiert wird.

Die Ausgabe zeigt, dass der Befehl einen Schlüssel mit dem Schlüssel-Handle 9 generiert hat und dass die Bescheinigungsprüfung auf der Cluster-Firmware erfolgreich bestanden wurde.



                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

Beispiel : Erstellen und Untersuchen eines Schlüssels

Mit diesem Befehl wird ein Triple-DES-Schlüssel mit der Bezeichnung 3DES_shared und der ID IT-02 erstellt. Der Schlüssel kann von dem aktuellen Benutzer und den Benutzern 4 und 5 verwendet werden. Der Befehl schlägt fehl, wenn die ID im Cluster nicht eindeutig ist oder wenn der aktuelle Benutzer der Benutzer 4 oder 5 ist.

Die Ausgabe zeigt, dass der neue Schlüssel das Schlüssel-Handle 7 aufweist.


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

Um zu überprüfen, ob der neue 3DES-Schlüssel im Besitz des aktuellen Benutzers ist und gemeinsam mit den Benutzern 4 und 5 genutzt wird, verwenden Sie getKeyInfo. Der Befehl verwendet das Handle, das dem neuen Schlüssel zugewiesen wurde (Key Handle: 7).

Die Ausgabe bestätigt, dass der Schlüssel im Besitz des Benutzers 3 ist und gemeinsam mit den Benutzern 4 und 5 verwendet wird.


Command:  getKeyInfo -k 7

        Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS

        Owned by user 3

        also, shared to following 2 user(s):

                 4, 5

Verwenden Sie getAttribute, um die anderen Eigenschaften des Schlüssels zu bestätigen. Der erste Befehl verwendet getAttribute, um alle Attribute (-a 512) von Schlüssel-Handle 7 (-o 7) abzurufen. Sie werden in die Datei attr_7 geschrieben. Der zweite Befehl verwendet cat, um den Inhalt der attr_7-Datei abzurufen.

Mit diesem Befehl wird bestätigt, dass Schüssel 7 ein symmetrischer 192-Bit-(OBJ_ATTR_VALUE_LEN 0x00000018 oder 24-Byte)-3DES (OBJ_ATTR_KEY_TYPE 0x15)-Schlüssel (OBJ_ATTR_CLASS 0x04) mit der Bezeichnung 3DES_shared (OBJ_ATTR_LABEL 3DES_shared) und der ID IT_02 ist (OBJ_ATTR_ID IT-02). Der Schlüssel ist persistent (OBJ_ATTR_TOKEN 0x01) und extrahierbar (OBJ_ATTR_EXTRACTABLE 0x01) und kann für das Verschlüsseln, Entschlüsseln und Verpacken verwendet werden.

Tipp

Um die Attribute eines von Ihnen erstellten Schlüssels wie Typ, Länge, Bezeichnung und ID zu finden, verwenden Sie getAttribute. Um die Schlüssel für einen bestimmten Benutzer zu finden, verwenden Sie. getKeyInfo Verwenden Sie findKey, um Schlüssel anhand ihrer Attributwerte zu finden.

Hilfe zur Interpretation der Schlüsselattribute finden Sie unter Schlüsselattributreferenz.


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

Tipp

Um die Schlüssel, die Sie mit diesen Beispielen erstellen, für HMAC-Operationen zu verwenden, müssen Sie nach dem Generieren des Schlüssels den Wert OBJ_ATTR_SIGN und OBJ_ATTR_VERIFY auf TRUE festlegen. Verwenden Sie setAttribute in CMU, um diese Werte festzulegen. Weitere Informationen finden Sie unter setAttribute.

Parameter

-h

Zeigt Hilfe für den Befehl an.

Erforderlich: Ja

-t

Gibt den Typ des symmetrischen Schlüssels an. Geben Sie die Konstante ein, die den Schlüsseltyp darstellt. Zum Erstellen eines AES-Schlüssels geben Sie beispielsweise -t 31 ein.

Zulässige Werte:

16: GENERIC_SECRET. Ein allgemeiner geheimer Schlüssel ist ein Byte-Array, das keinem speziellen Standard entspricht, wie etwa den Anforderungen an einen AES-Schlüssel.
18: RC4. RC4-Schlüssel sind in FIPS-Modus-HSMs nicht gültig.
21: Triple DES (3DES). Gemäß den NIST-Richtlinien ist dies für Cluster im FIPS-Modus nach 2023 nicht zulässig. Für Cluster im Nicht-FIPS-Modus ist dies auch nach 2023 zulässig. Details dazu finden Sie unter FIPS-140-Konformität: Mechanismus 2024 nicht mehr unterstützt.
31: AES

Erforderlich: Ja

-s

Gibt die Schlüsselgröße in Byte an. Um beispielsweise einen 192-Bit-Schlüssel zu erstellen, geben Sie 24 ein.

Gültige Werte für jeden Schlüsseltyp:

AES: 16 (128 Bit), 24 (192 Bit), 32 (256 Bit)
3DES: 24 (192 Bit)
Allgemeiner geheimer Schlüssel: <3584 (28672 Bit)

Erforderlich: Ja

-l

Gibt eine benutzerdefinierte Bezeichnung für den Schlüssel an. Geben Sie eine Zeichenfolge ein.

Sie können eine beliebige Phrase verwenden, die Ihnen bei der Identifizierung des Schlüssels hilft. Da die Bezeichnung nicht eindeutig sein muss, können Sie sie verwenden, um Schlüssel zu gruppieren und zu kategorisieren.

Erforderlich: Ja

-attest

Führt eine Integritätsprüfung durch, die sicherstellt, dass die Firmware, auf der der Cluster läuft, nicht manipuliert wurde.

Standard: Keine Bescheinigungsprüfung.

Erforderlich: Nein

-id

Gibt einen benutzerdefinierten Bezeichner für den Schlüssel an. Geben Sie eine Zeichenfolge ein, die im Cluster eindeutig ist. Der Standardwert ist eine leere Zeichenfolge.

Standard : Kein ID-Wert.

Erforderlich: Nein

-min_srv

Gibt die Mindestanzahl der HSMs an, in denen der Schlüssel synchronisiert wird, bevor der Wert des Parameters -timeout verfällt. Falls der Schlüssel nicht in der zulässigen vorgegebenen Zeit mit der angegebenen Anzahl von Servern synchronisiert wird, wird er nicht erstellt.

AWS CloudHSM synchronisiert automatisch jeden Schlüssel mit jedem HSM im Cluster. Zur Beschleunigung Ihres Prozesses legen Sie den Wert von min_srv auf weniger als die Anzahl der HSMs im Cluster fest und stellen einen niedrigen Zeitüberschreitungswert ein. Beachten Sie jedoch, dass einige Anfragen möglicherweise keinen Schlüssel generieren.

Standard: 1

Erforderlich: Nein

-m_value

Gibt die Anzahl der Benutzer an, die einen kryptografischen Vorgang genehmigen müssen, der den Schlüssel verwendet. Geben Sie einen Wert von 0 bis 8 ein.

Dieser Parameter legt eine Quorum-Authentifizierungsanforderung für den Schlüssel fest. Der Standardwert, 0, deaktiviert die Quorum-Authentifizierungsfunktion für den Schlüssel. Wenn die Quorumauthentifizierung aktiviert ist, muss die angegebene Anzahl von Benutzern ein Token signieren, um kryptografische Operationen, bei denen der Schlüssel verwendet wird, sowie Operationen, bei denen der Schlüssel gemeinsam genutzt oder die gemeinsame Nutzung aufgehoben wird, zu genehmigen.

Um den Wert m_value eines Schlüssels zu finden, verwenden Sie. getKeyInfo

Dieser Parameter ist nur gültig, wenn der -u-Parameter im Befehl den Schlüssel für ausreichend Benutzer freigibt, um die m_value-Anforderung zu erfüllen.

Standard: 0

Erforderlich: Nein

-nex

Macht den Schlüssel nicht extrahierbar. Der generierte Schlüssel kann nicht aus dem HSM exportiert werden.

Standard: Der Schlüssel ist extrahierbar.

Erforderlich: Nein

-sess

Erstellt einen Schlüssel, der nur in der aktuellen Sitzung existiert. Der Schlüssel kann nach Ende der Sitzung nicht wiederhergestellt werden.

Verwenden Sie diesen Parameter, wenn Sie einen Schlüssel zum Packen nur für kurze Zeit benötigen, z. B. einen Schlüssel, der einen anderen Schlüssel verschlüsselt und dann schnell entschlüsselt. Verwenden Sie keinen Sitzungsschlüssel, um Daten zu verschlüsseln, die Sie nach dem Ende der Sitzung möglicherweise entschlüsseln müssen.

Um einen Sitzungsschlüssel in einen persistenten (Token-)Schlüssel zu ändern, verwenden Sie setAttribute.

Standard: Der Schlüssel ist persistent.

Erforderlich: Nein

-timeout

Gibt an, wie lange (in Sekunden) der Befehl darauf wartet, dass ein Schlüssel mit der im min_srv-Parameter angegebenen Anzahl von HSMs synchronisiert wird.

Dieser Parameter ist nur gültig, wenn der min_srv-Parameter auch im Befehl verwendet wird.

Voreinstellung: Keine Zeitüberschreitung. Der Befehl wartet auf unbestimmte Zeit und kehrt erst zurück, wenn der Schlüssel mit der Mindestanzahl von Servern synchronisiert ist.

Erforderlich: Nein

-u

Gibt den Schlüssel für die angegebenen Benutzer frei. Dieser Parameter erteilt anderen HSM-Crypto-Benutzern die Berechtigung zur Verwendung dieses Schlüssels in kryptographischen Vorgängen.

Geben Sie eine durch Kommas getrennte Liste der HSM-Benutzer-IDs ein, wie etwa -u 5,6. Fügen Sie die HSM-Benutzer-ID des aktuellen Benutzers nicht ein. Verwenden Sie listUsers, um im HSM nach den HSM-Benutzer-IDs von CUs zu suchen. Nutzen Sie zum Freigeben oder zum Aufheben der Freigabe vorhandener Schlüssel shareKey in cloudhsm_mgmt_util.

Standard: Nur der aktuelle Benutzer kann den Schlüssel verwenden.

Erforderlich: Nein