CryptImportKey-Funktion (wincrypt.h)

Die funktion CryptImportKey überträgt einen kryptografischen Schlüssel von einem -Schlüssel-BLOB- in einen kryptografischen Dienstanbieter (CSP). Diese Funktion kann zum Importieren eines Schannel-Sitzungsschlüssels, regulärer Sitzungsschlüssel, öffentlichen Schlüsseloder öffentlichen/privaten Schlüsselpaarsverwendet werden. Für alle Schlüssel, aber für den öffentlichen Schlüssel wird das Schlüssel- oder Schlüsselpaar verschlüsselt.

Syntax

BOOL CryptImportKey(
  [in]  HCRYPTPROV hProv,
  [in]  const BYTE *pbData,
  [in]  DWORD      dwDataLen,
  [in]  HCRYPTKEY  hPubKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTKEY  *phKey
);

Parameter

[in] hProv

Das Handle eines CSP, der mit der CryptAcquireContext Funktion abgerufen wurde.

[in] pbData

Ein BYTE- Array, das einen PUBLICKEYSTRUC- BLOB-Header enthält, gefolgt von dem verschlüsselten Schlüssel. Dieser Schlüssel-BLOB wird von der funktion CryptExportKey erstellt, entweder in dieser Anwendung oder von einer anderen Anwendung, die möglicherweise auf einem anderen Computer ausgeführt wird.

[in] dwDataLen

Enthält die Länge des Schlüssel-BLOB in Bytes.

[in] hPubKey

Ein Handle für den kryptografischen Schlüssel, der den in pbData-gespeicherten Schlüssel entschlüsselt. Dieser Schlüssel muss aus demselben CSP stammen, auf den hProv verweist. Die Bedeutung dieses Parameters unterscheidet sich je nach CSP-Typ und dem Typ des zu importierenden Schlüssel-BLOB:

• Wenn das Schlüssel-BLOB mit dem Schlüssel Austauschschlüsselpaarverschlüsselt wird, z. B. ein SIMPLEBLOB-, kann dieser Parameter das Handle für den Schlüsselaustauschschlüssel sein.
• Wenn der Schlüssel-BLOB mit einem Sitzungsschlüssel verschlüsselt ist, z. B. eine verschlüsselte PRIVATEKEYBLOB-, enthält dieser Parameter das Handle dieses Sitzungsschlüssels.
• Wenn der Schlüssel-BLOB nicht verschlüsselt ist, z. B. ein PUBLICKEYBLOB-, wird dieser Parameter nicht verwendet und muss null sein.
• Wenn der Schlüssel-BLOB mit einem Sitzungsschlüssel in einem Schannel CSP verschlüsselt wird, z. B. eine verschlüsselte OPAQUEKEYBLOB oder einen anderen anbieterspezifischen OPAQUEKEYBLOB, wird dieser Parameter nicht verwendet und muss auf Null festgelegt werden.

[in] dwFlags

Wird derzeit nur verwendet, wenn ein öffentliches/privates Schlüssel paar in Form eines PRIVATEKEYBLOB- in den CSP importiert wird.

Dieser Parameter kann einer der folgenden Werte sein:

Wert	Bedeutung
CRYPT_EXPORTABLE	Der importierte Schlüssel wird schließlich erneut ausgeführt. Wenn dieses Flag nicht verwendet wird, schlagen Aufrufe von CryptExportKey fehl.
CRYPT_OAEP	Dieses Kennzeichen bewirkt, dass die PKCS #1 Version 2-Formatierung beim Importieren SIMPLEBLOB-s mit RSA-Verschlüsselung und Entschlüsselung überprüft wird.
CRYPT_NO_SALT	Ein kein Salzwert für einen symmetrischen symmetrischen Schlüsselzugeordnet wird. Weitere Informationen finden Sie unter Salt Value Functionality.
CRYPT_USER_PROTECTED	Wenn dieses Kennzeichen festgelegt ist, benachrichtigt der CSP den Benutzer über ein Dialogfeld oder eine andere Methode, wenn bestimmte Aktionen mit diesem Schlüssel versucht werden. Das genaue Verhalten wird durch den verwendeten CSP oder den verwendeten CSP-Typ angegeben. Wenn der Anbieterkontext mit CRYPT_SILENT festgelegt wurde, führt die Verwendung dieses Flags zu einem Fehler, und der letzte Fehler wird auf NTE_SILENT_CONTEXT festgelegt.
CRYPT_IPSEC_HMAC_KEY	Ermöglicht den Import eines RC2-Schlüssels, der größer als 16 Bytes ist. Wenn dieses Flag nicht festgelegt ist, treten Aufrufe der CryptImportKey--Funktion mit RC2-Schlüsseln, die größer als 16 Byte sind, fehl, und ein Aufruf von GetLastError- gibt NTE_BAD_DATAzurück.

[out] phKey

Ein Zeiger auf einen HCRYPTKEY Wert, der das Handle des importierten Schlüssels empfängt. Wenn Sie die Verwendung des Schlüssels abgeschlossen haben, lassen Sie das Handle los, indem Sie die CryptDestroyKey--Funktion aufrufen.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion "nonzero" zurück.

Wenn die Funktion fehlschlägt, wird null zurückgegeben. Rufen Sie für erweiterte Fehlerinformationen GetLastError-auf.

Fehlercodes, die von "NTE" vorangestellt werden, werden von dem verwendeten CSP generiert. Einige mögliche Fehlercodes folgen.

Rückgabecode	Beschreibung
ERROR_BUSY	Einige CSPs legen diesen Fehler fest, wenn ein privater Schlüssel in einen Container importiert wird, während ein anderer Thread oder Prozess diesen Schlüssel verwendet.
ERROR_INVALID_HANDLE	Einer der Parameter gibt ein ungültiges Handle an.
ERROR_INVALID_PARAMETER	Einer der Parameter enthält einen ungültigen Wert. Dies ist am häufigsten ein ungültiger Zeiger.
NTE_BAD_ALGID	Die zu importierenden BLOB- für den einfachen Schlüssel wird nicht mit dem erwarteten Schlüsselaustauschalgorithmusverschlüsselt.
NTE_BAD_DATA	Entweder der Algorithmus, der mit dem zu importierenden öffentlichen Schlüssel arbeitet, wird von diesem CSP nicht unterstützt, oder es wurde versucht, einen Sitzungsschlüssel zu importieren, der mit einem anderen als einem Ihrer öffentlichen Schlüssel verschlüsselt wurde.
NTE_BAD_FLAGS	Der angegebene dwFlags Parameter ist ungültig.
NTE_BAD_TYPE	Der Schlüssel-BLOB-Typ wird von diesem CSP nicht unterstützt und ist möglicherweise ungültig.
NTE_BAD_UID	Der hProv--Parameter enthält kein gültiges Kontexthandle.
NTE_BAD_VER	Die Versionsnummer des Schlüssel-BLOB stimmt nicht mit der CSP-Version überein. Dies weist in der Regel darauf hin, dass der CSP aktualisiert werden muss.

Bemerkungen

Beim Importieren eines Hash-Based Nachrichtenauthentifizierungscode- (HMAC)-Schlüssels muss der Aufrufer den importierten Schlüssel als PLAINTEXTKEYBLOB Typ identifizieren und den entsprechenden Algorithmusbezeichner im aiKeyAlg Feld des PUBLICKEYSTRUC BLOB-Header festlegen.

Die CryptImportKey--Funktion kann verwendet werden, um einen Nur-Text-Schlüssel für symmetrische Algorithmen zu importieren; Es wird jedoch empfohlen, stattdessen die CryptGenKey-Funktion zu verwenden. Beim Importieren eines Nur-Text-Schlüssels ist die Struktur des Schlüssel-BLOB, das im pbData--Parameter übergeben wird, ein PLAINTEXTKEYBLOB-.

Sie können die PLAINTEXTKEYBLOB- Typs mit einem beliebigen Algorithmus oder tastenkombinationstyp verwenden, der vom verwendeten CSP unterstützt wird.

Ein Beispiel für das Importieren eines Nur-Text-Schlüssels finden Sie unter Beispiel C-Programm: Importieren eines Nur-Text-Schlüssels.

Das folgende Beispiel zeigt, wie Sie die Kopfzeilenfelder festlegen können.

keyBlob.header.bType = PLAINTEXTKEYBLOB;
keyBlob.header.bVersion = CUR_BLOB_VERSION;
keyBlob.header.reserved = 0;
// CALG_AES_128 is used as an example. You would set this to the 
// algorithm id that corresponds to the one used by the key.
keyBlob.header.aiKeyAlg = CALG_AES_128;

Die Länge des Schlüssels wird in keyBlob.keyLength angegeben, gefolgt von den tatsächlichen Schlüsseldaten.

Für jede der Data Encryption Standard (DES)-Schlüssel permutationen, die PLAINTEXTKEYBLOB-verwenden, können nur die vollständige Schlüsselgröße, einschließlich des Paritätsbits, importiert werden.

Die folgenden Schlüsselgrößen werden unterstützt.

Algorithmus	Unterstützte Schlüsselgröße
CALG_DES	64 Bits
CALG_3DES_112	128 Bit
CALG_3DES	192 Bits

 

Beispiele

Das folgende Beispiel zeigt, wie Sie einen Schlüssel aus einem Schlüssel-BLOB importieren. Ein vollständiges Beispiel für diese Funktion finden Sie unter Beispiel-C-Programm: Signieren eines Hashs und Überprüfen der Hashsignatur. Weitere Code, der diese Funktion verwendet, finden Sie unter Beispiel-C-Programm: Entschlüsseln einer Datei.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>

BOOL ImportKey(HCRYPTPROV hProv, LPBYTE pbKeyBlob, DWORD dwBlobLen)
{
    HCRYPTKEY hPubKey;

    //---------------------------------------------------------------
    // This code assumes that a cryptographic provider (hProv) 
    // has been acquired and that a key BLOB (pbKeyBlob) that is 
    // dwBlobLen bytes long has been acquired. 

    //---------------------------------------------------------------
    // Get the public key of the user who created the digital 
    // signature and import it into the CSP by using CryptImportKey. 
    // The key to be imported is in the buffer pbKeyBlob that is  
    // dwBlobLen bytes long. This function returns a handle to the 
    // public key in hPubKey.

    if(CryptImportKey(
        hProv,
        pbKeyBlob,
        dwBlobLen,
        0,
        0,
        &hPubKey))
    {
        printf("The key has been imported.\n");
    }
    else
    {
        printf("Public key import failed.\n");
        return FALSE;
    }

    //---------------------------------------------------------------
    // Insert code that uses the imported public key here.
    //---------------------------------------------------------------

    //---------------------------------------------------------------
    // When you have finished using the key, you must release it.
    if(CryptDestroyKey(hPubKey))
    {
        printf("The public key has been released.");
    }
    else
    {
        printf("The public key has not been released.");
        return FALSE;
    }

    return TRUE;
}

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	wincrypt.h
Library	Advapi32.lib
DLL-	Advapi32.dll

Siehe auch

CryptAcquireContext-

CryptDestroyKey-

CryptExportKey-

Schlüsselgenerierung und Exchange-Funktionen