Syntax Beispiele Parameter Verwandte Themen

exSymKey

Der exSymKey-Befehl im Tool key_mgmt_util exportiert eine Klartextkopie eines symmetrischen Schlüssels aus dem HSM und speichert sie in einer Datei auf der Festplatte. Um eine verschlüsselte (verpackte) Kopie eines Schlüssels zu exportieren, verwenden Sie wrapKey. Um einen Klartext-Schlüssel zu importieren, wie z. B. diejenigen, die exportiert werden, verwenden Sie. exSymKey imSymKey

Während des Exportvorgangs verwendet exSymKey einen AES-Schlüssel, den Sie angeben (der wrapping key (Verpackungsschlüssel)), um den zu exportierenden Schlüssel zu packen (verschlüsseln) und anschließend zu entpacken (entschlüsseln). Das Ergebnis des Exportvorgangs ist jedoch ein Klartextschlüssel (entpackter Schlüssel) auf einem Datenträger.

Nur der Eigentümer eines Schlüssels, d. h., der CU-Benutzer, der den Schlüssel erstellt hat, kann ihn exportieren. Benutzer, für die der Schlüssel freigegeben ist, können ihn in kryptografischen Vorgängen verwenden, können ihn aber nicht exportieren.

Der Vorgang exSymKey kopiert die Schlüsselinformationen in eine Datei, die Sie angeben, entfernt den Schlüssel jedoch nicht aus dem HSM, ändert seine key attributes (Schlüsselattribute) nicht oder verhindert, dass Sie den Schlüssel in kryptografischen Vorgänge verwenden. Sie können den gleichen Schlüssel mehrmals exportieren.

exSymKey exportiert nur symmetrische Schlüssel. Zum Exportieren von öffentlichen Schlüsseln verwenden Sie exportPubKey. Zum Exportieren von privaten Schlüsseln verwenden Sie exportPrivateKey.

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


exSymKey -h

exSymKey -k <key-to-export>
         -w <wrapping-key>
         -out <key-file>
         [-m 4] 
         [-wk <unwrapping-key-file> ]

Beispiele

Diese Beispiele zeigen, wie Sie mit exSymKey symmetrische Schlüssel, deren Eigentümer Sie sind, von Ihren HSMs exportieren.

Beispiel : Exportieren eines symmetrischen 3DES-Schlüssels

Mit diesem Befehl wird ein symmetrischer Triple DES (3DES)-Schlüssel exportiert (Schlüssel-Handle 7). Er verwendet einen vorhandenen AES-Schlüssel (Schlüssel-Handle 6) im HSM als Verpackungsschlüssel. Anschließend wird der Klartext des 3DES-Schlüssels in die Datei 3DES.key geschrieben.

Die Ausgabe zeigt, dass der Schlüssel 7 (der 3DES-Schlüssel) erfolgreich verpackt und entpackt und anschließend in die angegebene Datei 3DES.key geschrieben wurde.

Warnung

Obwohl die Ausgabe besagt, dass ein „verpackter symmetrischer Schlüssel“ in die Ausgabedatei geschrieben wurden, enthält die Ausgabedatei einen (entpackten) Klartextschlüssel.


        Command: exSymKey -k 7 -w 6 -out 3DES.key

       Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "3DES.key"

Beispiel : Exportieren mit einem nur für die aktuelle Sitzung gültigen Verpackungsschlüssel

Das folgende Beispiel zeigt, wie Sie einen Schlüssel verwenden, der nur in dieser Sitzung als Verpackungsschlüssel vorhanden ist. Da der zu exportierende Schlüssel verpackt ist, anschließend sofort entpackt und als Klartext bereitgestellt wird, ist es nicht nötig, den Verpackungsschlüssel aufzubewahren.

Anhand dieser Befehle wird ein AES-Schlüssel mit der Schlüssel-Handle 8 aus dem HSM exportiert. Dabei wird ein AES-Sitzungsschlüssel verwendet, der speziell zu diesem Zweck erstellt wurde.

Der erste Befehl dient genSymKeyzur Erstellung eines 256-Bit-AES-Schlüssels. Dabei wird der -sess-Parameter zum Erstellen eines Schlüssels verwendet, der nur in der aktuellen Sitzung vorhanden ist.

Die Ausgabe zeigt, dass das HSM den Schlüssel 262168 erstellt.


        Command:  genSymKey -t 31 -s 32 -l AES-wrapping-key -sess

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 262168

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

Als Nächstes wird im Beispiel sichergestellt, dass es sich bei dem Schlüssel 8, dem zu exportierenden Schlüssel, um einen symmetrischen Schlüssel handelt, der extrahierbar ist. Außerdem wird überprüft, ob der Verpackungsschlüssel, der Schlüssel 262168, ein AES-Schlüssel ist, der nur in dieser Sitzung vorhanden ist. Sie können den Befehl findKey verwenden, aber in diesem Beispiel werden die Attribute beider Schlüssel in Dateien exportiert und anschließend grep verwendet, um die relevanten Attributwerte in der Datei zu finden.

Diese Befehle verwenden getAttribute mit einem -a Wert von 512 (alle), um alle Attribute für die Schlüssel 8 und 262168 aufzurufen. Weitere Informationen zu den Schlüsselattributen finden Sie unter Schlüsselattributreferenz.


getAttribute -o 8 -a 512 -out attributes/attr_8
getAttribute -o 262168 -a 512 -out attributes/attr_262168

Diese Befehle verwenden grep, um die Attribute des zu exportierenden Schlüssels (Schlüssel 8) und des nur für die aktuelle Sitzung gültigen Verpackungsschlüssels (Schlüssel 262168) zu überprüfen.


    // Verify that the key to be exported is a symmetric key.
    $  grep -A 1 "OBJ_ATTR_CLASS" attributes/attr_8    
    OBJ_ATTR_CLASS
    0x04
   
    // Verify that the key to be exported is extractable.
    $  grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_8
    OBJ_ATTR_EXTRACTABLE
    0x00000001

    // Verify that the wrapping key is an AES key
    $  grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_262168
    OBJ_ATTR_KEY_TYPE
    0x1f

    // Verify that the wrapping key is a session key
    $  grep -A 1 "OBJ_ATTR_TOKEN" attributes/attr_262168
    OBJ_ATTR_TOKEN
    0x00    
    
    // Verify that the wrapping key can be used for wrapping
     $  grep -A 1 "OBJ_ATTR_WRAP" attributes/attr_262168
    OBJ_ATTR_WRAP
    0x00000001

Schließlich verwenden wir den Befehl exSymKey, um den Schlüssel 8 mithilfe des Sitzungsschlüssels (Schlüssel 262168) als Verpackungsschlüssel zu exportieren.

Wenn die Sitzung beendet wird, wird der Schlüssel 262168 nicht länger vorhanden sein.


        Command:  exSymKey -k 8 -w 262168 -out aes256_H8.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "aes256_H8.key"

Beispiel : Verwenden eines externen Entpackungsschlüssels

Das folgende Beispiel zeigt, wie Sie mit einem externen Entpackungsschlüssel einen Schlüssel aus dem HSM exportieren.

Wenn Sie einen Schlüssel aus dem HSM exportieren, geben Sie einen AES-Schlüssel im HSM als Verpackungsschlüssel an. Standardmäßig wird dieser Schlüssel dazu verwendet, den zu exportierenden Schlüssel zu verpacken und zu entpacken. Sie können jedoch mithilfe des -wk-Parameters exSymKey anweisen, zum Entpacken einen externen Schlüssel in einer Datei auf einem Datenträger zu verwenden. Wenn Sie sich dafür entscheiden, verpackt der vom -w-Parameter angegebene Schlüssel den Ziel-Schlüssel, und der Schlüssel, der sich in der vom -wk-Parameter angegebenen Datei befindet, entpackt den Schlüssel.

Da der Verpackungsschlüssel ein AES-Schlüssel sein muss, und dieser symmetrisch ist, müssen der Verpackungsschlüssel im HSM und der Entpackungsschlüssel auf dem Datenträger über die gleichen Schlüsselinformationen verfügen. Hierzu müssen Sie vor dem Exportvorgang den Verpackungsschlüssel in das HSM importieren oder den Verpackungsschlüssel aus dem HSM exportieren.

In diesem Beispiel wird ein Schlüssel außerhalb des HSM erstellt und in das HSM importiert. Dabei wird eine interne Kopie des Schlüssels verwendet, um den zu exportierenden symmetrischen Schlüssel zu verpacken, und anschließend die Kopie des Schlüssels in der Datei dazu benutzt, um ihn zu entpacken.

Der erste Befehl verwendet OpenSSL, um einen 256-Bit-AES-Schlüssel zu generieren. Der Schlüssel wird in der Datei aes256-forImport.key gespeichert. Der OpenSSL-Befehl gibt keine Ausgabe zurück, jedoch können Sie mehrere Befehle verwenden, um zu überprüfen, ob der Vorgang erfolgreich war. Dieses Beispiel verwendet das wc-Tool (Wordcount), das bestätigt, dass die Datei 32 Byte an Daten umfasst.


$  openssl rand -out keys/aes256-forImport.key 32

$ wc keys/aes256-forImport.key
 0  2 32 keys/aes256-forImport.key

Dieser Befehl verwendet den imSymKeyBefehl, um den AES-Schlüssel aus der aes256-forImport.key Datei in das HSM zu importieren. Wenn der Befehl abgeschlossen ist, ist der Schlüssel im HSM mit dem Schlüssel-Handle 262167 und in der Datei aes256-forImport.key vorhanden.


Command:  imSymKey -f keys/aes256-forImport.key -t 31 -l aes256-imported -w 6

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 262167

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

Dieser Befehl verwendet den Schlüssel in einem Exportvorgang. Der Befehl verwendet exSymKey, um den Schlüssel 21, ein 192-Bit-AES-Schlüssel, zu exportieren. Um den Schlüssel zu verpacken, wird der Schlüssel 262167 verwendet. Dabei handelt es sich um die Kopie des Schlüssels, die in das HSM importiert wurde. Um den Schlüssel zu entpacken, werden die gleichen Schlüsselinformationen in der Datei aes256-forImport.key verwendet. Nach der Ausführung des Befehls wird der Schlüssel 21 in die Datei aes192_h21.key exportiert.


        Command:  exSymKey -k 21 -w 262167 -out aes192_H21.key -wk aes256-forImport.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

Wrapped Symmetric Key written to file "aes192_H21.key"

Parameter

-h

Zeigt Hilfe für den Befehl an.

Erforderlich: Ja

-k

Gibt das Schlüssel-Handle des zu exportierenden Schlüssels an. Dieser Parameter muss angegeben werden. Geben Sie das Schlüssel-Handle eines symmetrischen Schlüssels ein, dessen Eigentümer Sie sind. Dieser Parameter muss angegeben werden. Verwenden Sie den findKey-Befehl, um Schlüssel-Handles zu finden.

Verwenden Sie den Befehl getAttribute, um sicherzustellen, dass ein Schlüssel exportiert werden kann, und um den Wert des Attributs OBJ_ATTR_EXTRACTABLE abzurufen, der von der Konstanten 354 dargestellt wird. Zudem können Sie nur Schlüssel exportieren, deren Eigentümer Sie sind. Verwenden Sie den getKeyInfoBefehl, um den Besitzer eines Schlüssels zu ermitteln.

Erforderlich: Ja

-w

Gibt das Schlüssel-Handle des Verpackungsschlüssels an. Dieser Parameter muss angegeben werden. Verwenden Sie den findKey-Befehl, um Schlüssel-Handles zu finden.

Ein Verpackungsschlüssel ist ein Schlüssel im HSM, der zum Verschlüsseln (Verpacken) und zum anschließenden Entschlüsseln (Entpacken) des zu exportierenden Schlüssels verwendet wird. Nur AES-Schlüssel können als Verpackungsschlüssel verwendet werden.

Sie können jeden AES-Schlüssel (in jeder beliebigen Größe) als Verpackungsschlüssel verwenden. Da der Verpackungsschlüssel den Zielschlüssel verpackt und danach sofort entpackt, können Sie einen nur für die aktuelle Sitzung gültigen AES-Schlüssel als Verpackungsschlüssel verwenden. 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. Um einen Wrapping-Schlüssel genSymKeyzu erstellen, verwenden Sie, um einen AES-Schlüssel zu erstellen (Typ 31).

Wenn Sie den Parameter -wk zum Angeben eines externen Entschlüsselungsschlüssels verwenden, wird der -w-Schlüssel während des Exportvorgangs zum Verpacken, aber nicht zum Entpacken des Schlüssels verwendet.

Anmerkung

Schlüssel 4 stellt einen nicht unterstützten internen Schlüssel dar. Wir empfehlen, dass Sie einen AES-Schlüssel als Umhüllungsschlüssel verwenden, den Sie erstellen und verwalten.

Erforderlich: Ja

-out

Gibt den Pfad und Namen der Ausgabedatei an. Wenn der Befehl erfolgreich ist, enthält diese Datei den exportierten Schlüssel als Klartext. Wenn die Datei bereits vorhanden ist, überschreibt der Befehl sie ohne Warnung.

Erforderlich: Ja

-m

Gibt den Verpackungsmechanismus an. Der einzige gültige Wert ist 4, der den NIST_AES_WRAP-Mechanismus darstellt.

Erforderlich: Nein

Standard: 4

-wk

Verwenden Sie den AES-Schlüssel in der angegebenen Datei, um den Schlüssel, der exportiert wird, zu entpacken. Geben Sie den Pfad und den Namen einer Datei an, die einen Klartext-AES-Schlüssel enthält.

Wenn Sie diesen Parameter angeben, verwendet exSymKey den Schlüssel im HSM, der durch den -w-Parameter angegeben wird, um den zu exportierenden Schlüssel zu verpacken, und verwendet den Schlüssel in der -wk-Datei, um ihn zu entpacken. Die Parameterwerte -w und -wk müssen durch denselben Klartextschlüssel aufgelöst werden.

Erforderlich: Nein

Standard: Verwenden Sie den Verpackungsschlüssel auf dem HSM zum Entpacken.