CryptImportKey-Funktion (wincrypt.h)
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 |
|---|---|
|
Der importierte Schlüssel wird schließlich erneut ausgeführt. Wenn dieses Flag nicht verwendet wird, schlagen Aufrufe von CryptExportKey fehl. |
|
Dieses Kennzeichen bewirkt, dass die PKCS #1 Version 2-Formatierung beim Importieren SIMPLEBLOB-s mit RSA-Verschlüsselung und Entschlüsselung überprüft wird. |
|
Ein kein Salzwert für einen symmetrischen symmetrischen Schlüsselzugeordnet wird. Weitere Informationen finden Sie unter Salt Value Functionality. |
|
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. |
|
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 |
|---|---|
|
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. |
|
Einer der Parameter gibt ein ungültiges Handle an. |
|
Einer der Parameter enthält einen ungültigen Wert. Dies ist am häufigsten ein ungültiger Zeiger. |
|
Die zu importierenden BLOB- für den einfachen Schlüssel wird nicht mit dem erwarteten Schlüsselaustauschalgorithmusverschlüsselt. |
|
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. |
|
Der angegebene dwFlags Parameter ist ungültig. |
|
Der Schlüssel-BLOB-Typ wird von diesem CSP nicht unterstützt und ist möglicherweise ungültig. |
|
Der hProv--Parameter enthält kein gültiges Kontexthandle. |
|
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.
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 |