Syntax Beispiel Parameter Verwandte Themen

unWrapKey

Der unWrapKey-Befehl im Tool key_mgmt_util importiert einen verschlüsselten symmetrischen oder privaten Schlüssel aus einer Datei in das HSM. Wurde entwickelt, um verschlüsselte Schlüssel zu importieren, die mit dem Befehl wrapKey in key_mgmt_util verpackt wurden. Kann aber auch verwendet werden, um Schlüssel zu entpacken, die mit anderen Tools verpackt wurden. In diesen Situationen empfehlen wir jedoch, die Softwarebibliotheken PKCS#11 oder JCE zu verwenden, um den Schlüssel zu entpacken.

Importierte Schlüssel funktionieren wie Schlüssel, die von generiert wurden. AWS CloudHSM Der Wert ihres Attributs OBJ_ATTR_LOCAL ist jedoch Null, was bedeutet, dass sie nicht lokal generiert wurden.

Stellen Sie nach dem Importieren eines Schlüssels sicher, dass Sie die Schlüsseldatei markieren oder löschen. Dieser Befehl verhindert nicht das wiederholte Importieren der gleichen Schlüsselinformationen. Das Ergebnis – mehrere Schlüssel mit unterschiedlichen Schlüsselhandles und demselben Schlüsselmaterial – macht es schwierig, die Verwendung des Schlüsselmaterials zu verfolgen und zu verhindern, dass die kryptografischen Grenzen überschritten werden.

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


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>]

Beispiel

Diese Beispiele zeigen, wie man mit unWrapKey einen verpackten Schlüssel aus einer Datei in die HSMs importiert. Im ersten Beispiel entpacken wir einen Schlüssel, der mit dem Befehl wrapKey key_mgmt_util verpackt wurde und daher einen Header hat. Im zweiten Beispiel entpacken wir einen Schlüssel, der außerhalb von key_mgmt_util verpackt wurde und daher keinen Header hat.

Beispiel : Einen Schlüssel entpacken (mit Header)


        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

Beispiel : Einen Schlüssel entpacken (kein Header)

Dieser Befehl importiert eine verpackte Kopie eines symmetrischen 3DES-Schlüssels in ein HSM. Der Schlüssel wird mit einem AES-Schlüssel mit dem Bezeichner 6 entpackt, der mit demjenigen kryptographisch identisch ist, der zum Verpacken des 3DES-Schlüssels verwendet wurde. Da dieser 3DES-Schlüssel nicht mit key_mgmt_util verpackt wurde, wird der noheader-Parameter zusammen mit den erforderlichen Begleitparametern angegeben: ein Schlüssellabel (unwrapped3DES), eine Schlüsselklasse (4) und ein Schlüsseltyp (21). Die Ausgabe zeigt, dass der Schlüssel in der Datei entpackt und importiert wurde und dass das Handle des importierten Schlüssels 8 ist.


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

Zeigt Hilfe für den Befehl an.

Erforderlich: Ja

-f

Gibt den Pfad und Namen der Datei an, die den verpackten Schlüssel enthält.

Erforderlich: Ja

-w

Gibt den Wrapping-Schlüssel an. Geben Sie das Schlüssel-Handle eines AES-Schlüssels oder RSA-Schlüssels auf dem HSM ein. Dieser Parameter muss angegeben werden. Verwenden Sie den findKey-Befehl, um Schlüssel-Handles zu finden.

Um einen Wrapping-Schlüssel zu erstellen, verwenden Sie, genSymKeyum einen AES-Schlüssel (Typ 31) zu generieren, oder GenRSA KeyPair, um ein RSA-Schlüsselpaar zu generieren (Typ 0). Wenn Sie ein RSA-Schlüsselpaar verwenden, achten Sie darauf, den Schlüssel mit einem der Schlüssel zu umwickeln und ihn mit dem anderen zu entpacken. Verwenden Sie getAttribute, um zu überprüfen, ob ein Schlüssel als Verpackungsschlüssel verwendet werden kann, und um den Wert des OBJ_ATTR_WRAP-Attributs abzurufen, der von der Konstanten 262 dargestellt wird.

Erforderlich: Ja

-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

-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

-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

-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

-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

-m

Der Wert, der den Verschlüsselungsmechanismus bezeichnet. CloudHSM unterstützt die folgenden Mechanismen:

Mechanismus	Wert
`AES_KEY_WRAP_PAD_PKCS5`	4
`NIST_AES_WRAP_NO_PAD`	5
`NIST_AES_WRAP_PAD`	6
`RSA_AES`	7
`RSA_OAEP` (zur maximalen Datengröße lesen Sie den Hinweis weiter unten in diesem Abschnitt)	8
`AES_GCM`	10
`CLOUDHSM_AES_GCM`	11
`RSA_PKCS` (Zur maximalen Datengröße lesen Sie den Hinweis weiter unten in diesem Abschnitt.) Eine bevorstehende Änderung finden Sie im Hinweis 1 unten.	12

Erforderlich: Ja

Anmerkung

Wenn Sie den RSA_OAEP Wrapping-Mechanismus verwenden, wird die maximale Schlüsselgröße, die Sie umbrechen können, durch den Modul des RSA-Schlüssels und die Länge des angegebenen Hashs wie folgt bestimmt: Maximale Schlüsselgröße = modulusLengthIn Bytes- (2* hashLengthIn Byte) -2.

Wenn Sie den RSA_PKCS-Wrapping-Mechanismus verwenden, wird die maximale Schlüsselgröße, die Sie umbrechen können, durch das Modul des RSA-Schlüssels wie folgt bestimmt: Maximale Schlüsselgröße = (Byte -11). modulusLengthIn

-t

Hash-Algorithmus	Wert
`SHA1`	2
`SHA256`	3
`SHA384`	4
`SHA512`	5
`SHA224` (gültig für `RSA_AES`- und `RSA_OAEP`-Mechanismen)	6

Erforderlich: Nein

-noheader

Wenn Sie einen Schlüssel entpacken, der außerhalb von key_mgmt_util verpackt wurde, müssen Sie diesen Parameter und alle anderen zugehörigen Parameter angeben.

Erforderlich: Nein

Anmerkung

Wenn Sie diesen Parameter angeben, müssen Sie auch die folgenden -noheader-Parameter angeben:

-l

Gibt den Bezeichner an, der dem entpackten Schlüssel hinzugefügt werden soll.

Erforderlich: Ja
-kc

Gibt die Klasse des zu entpackenden Schlüssels an. Die folgenden Werte sind zulässig:

3 = privater Schlüssel aus einem öffentlich-privaten Schlüsselpaar

4 = geheimer Schlüssel (symetrisch)

Erforderlich: Ja
-kt

Gibt den Typ des zu entpackenden Schlüssels an. Die folgenden Werte sind zulässig:

0 = RSA

1 = DSA

3 = ECC

16 = GENERIC_SECRET

21 = DES3

31 = AES

Erforderlich: Ja

Sie können auch optional die folgenden -noheader-Parameter angeben:

-id

Die ID, die dem entpackten Schlüssel hinzugefügt werden soll.

Erforderlich: Nein
-i

Der zu verwendende Initialisierungsvektor (IV) für das Entpacken.

Erforderlich: Nein

[1] 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.