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 wird.
[in] pbData
Ein BYTE-Array , das einen PUBLICKEYSTRUC-BLOB-Header gefolgt von dem verschlüsselten Schlüssel enthält. Dieses Schlüsselblob wird von der CryptExportKey-Funktion 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üsselblobs 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 Typ des zu importierenden Schlüsselblobs:
- Wenn das Schlüssel-BLOB mit dem Schlüsselaustauschschlüsselpaar verschlüsselt ist, z. B. einem SIMPLEBLOB, kann dieser Parameter das Handle für den Schlüsselaustauschschlüssel sein.
- Wenn das Schlüsselblob mit einem Sitzungsschlüssel verschlüsselt ist, z. B. einem verschlüsselten PRIVATEKEYBLOB, enthält dieser Parameter das Handle dieses Sitzungsschlüssels.
- Wenn das Schlüsselblob nicht verschlüsselt ist, z. B. ein PUBLICKEYBLOB, wird dieser Parameter nicht verwendet und muss 0 sein.
- Wenn das Schlüsselblob mit einem Sitzungsschlüssel in einem Schannel-CSP , z. B. einem verschlüsselten OPAQUEKEYBLOB oder einem anderen anbieterspezifischen OPAQUEKEYBLOB, verschlüsselt wird, wird dieser Parameter nicht verwendet und muss auf Null festgelegt werden.
[in] dwFlags
Wird derzeit nur verwendet, wenn ein öffentliches/privates Schlüsselpaar in Form eines PRIVATEKEYBLOB in den CSP importiert wird.
Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
|
Der importierte Schlüssel soll schließlich erneut exportiert werden. Wenn dieses Flag nicht verwendet wird, schlagen Aufrufe von CryptExportKey mit dem Schlüsselhandle fehl. |
|
Dieses Flag bewirkt, dass die PKCS #1 Version 2-Formatierung beim Importieren von SIMPLEBLOBs mit RSA-Verschlüsselung und -Entschlüsselung überprüft wird. |
|
Ein Wert ohne Salz wird einem symmetrischen 40-Bit-Schlüssel zugeordnet. Weitere Informationen finden Sie unter Salt-Wert-Funktionalität. |
|
Wenn dieses Flag festgelegt ist, benachrichtigt der CSP den Benutzer über ein Dialogfeld oder eine andere Methode, wenn mit diesem Schlüssel versucht wird, bestimmte Aktionen zu verwenden. Das genaue Verhalten wird durch den verwendeten CSP- oder CSP-Typ angegeben. Wenn der Anbieterkontext mit CRYPT_SILENT festgelegt wurde, verursacht die Verwendung dieses Flags einen 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, schlagen Aufrufe der CryptImportKey-Funktion mit RC2-Schlüsseln fehl, die größer als 16 Bytes sind, und ein Aufruf von GetLastError gibt NTE_BAD_DATA zurü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 Funktion CryptDestroyKey aufrufen.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero zurück.
Wenn die Funktion fehlschlägt, gibt sie null zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.
Fehlercodes, die von "NTE" vorangestellt werden, werden vom jeweiligen verwendeten CSP generiert. Es folgen einige mögliche Fehlercodes.
| 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 in den meisten Fällen ein nicht gültiger Zeiger. |
|
Das zu importierende BLOB für einfache Schlüssel wird nicht mit dem erwarteten Schlüsselaustauschalgorithmus verschlüsselt. |
|
Entweder wird der Algorithmus, der mit dem zu importierenden öffentlichen Schlüssel arbeitet, 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üsselblobtyp 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üsselblobs stimmt nicht mit der CSP-Version überein. Dies bedeutet in der Regel, dass der CSP aktualisiert werden muss. |
Hinweise
Beim Importieren eines HMAC-Schlüssels (Hash-Based Message Authentication Code ) muss der Aufrufer den importierten Schlüssel als PLAINTEXTKEYBLOB-Typ identifizieren und den entsprechenden Algorithmusbezeichner im Feld aiKeyAlg des PUBLICKEYSTRUC-BLOB-Headers festlegen.
Die CryptImportKey-Funktion kann verwendet werden, um einen Klartextschlüssel für symmetrische Algorithmen zu importieren. Aus Gründen der Benutzerfreundlichkeit wird jedoch empfohlen, stattdessen die CryptGenKey-Funktion zu verwenden. Wenn Sie einen Klartextschlüssel importieren, ist die Struktur des Schlüsselblobs, das im pbData-Parameter übergeben wird, ein PLAINTEXTKEYBLOB.
Sie können den PLAINTEXTKEYBLOB-Typ mit einem beliebigen Algorithmus oder Einem beliebigen Schlüsselkombinationstyp verwenden, der vom verwendeten CSP unterstützt wird.
Ein Beispiel für das Importieren eines Klartextschlüssels finden Sie unter Beispiel C-Programm: Importieren eines Klartextschlüssels.
Das folgende Beispiel zeigt, wie Sie die Headerfelder 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 Bit |
| CALG_3DES_112 | 128 Bit |
| CALG_3DES | 192 Bits |
Beispiele
Das folgende Beispiel zeigt, wie ein Schlüssel aus einem Schlüsselblob importiert wird. Ein vollständiges Beispiel für diese Funktion finden Sie unter Beispiel C-Programm: Signieren eines Hashs und Überprüfen der Hashsignatur. Zusätzlichen 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 |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | wincrypt.h |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für