CryptExportKey-Funktion (wincrypt.h)
Ein Handle für den zu exportierenden Schlüssel wird an die Funktion übergeben, und die Funktion gibt ein Schlüsselblob zurück. Dieses Schlüsselblob kann über einen unsicheren Transport gesendet oder an einem unsicheren Speicherort gespeichert werden. Diese Funktion kann einen Schannel-Sitzungsschlüssel , einen regulären Sitzungsschlüssel, einen öffentlichen Schlüssel oder ein paar öffentliche/private Schlüssel exportieren. Das zu exportierende Schlüsselblob ist nutzlos, bis der beabsichtigte Empfänger die CryptImportKey-Funktion verwendet, um das Schlüssel- oder Schlüsselpaar in den CSP eines Empfängers zu importieren.
Syntax
BOOL CryptExportKey(
[in] HCRYPTKEY hKey,
[in] HCRYPTKEY hExpKey,
[in] DWORD dwBlobType,
[in] DWORD dwFlags,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen
);
Parameter
[in] hKey
Ein Handle für den zu exportierenden Schlüssel.
[in] hExpKey
Ein Handle für einen kryptografischen Schlüssel des Zielbenutzers. Die Schlüsseldaten innerhalb des exportierten Schlüsselblobs werden mit diesem Schlüssel verschlüsselt. Dadurch wird sichergestellt, dass nur der Zielbenutzer das Schlüsselblob verwenden kann. Sowohl hExpKey als auch hKey müssen aus demselben CSP stammen.
In den meisten Fällen ist dies der öffentliche Schlüsselaustauschschlüssel des Zielbenutzers. Bestimmte Protokolle in einigen CSPs erfordern jedoch, dass zu diesem Zweck ein Sitzungsschlüssel des Zielbenutzers verwendet wird.
Wenn der durch dwBlobType angegebene Schlüssel-BLOB-TypPUBLICKEYBLOB ist, ist dieser Parameter nicht verwendet und muss auf 0 festgelegt werden.
Wenn der von dwBlobType angegebene BLOB-SchlüsseltypPRIVATEKEYBLOB ist, handelt es sich in der Regel um ein Handle für einen Sitzungsschlüssel, der zum Verschlüsseln des Schlüsselblobs verwendet werden soll. Einige CSPs lassen zu, dass dieser Parameter 0 ist. In diesem Fall muss die Anwendung das BLOB des privaten Schlüssels manuell verschlüsseln, um es zu schützen.
Informationen zur Reaktion von Microsoft-Kryptografiedienstanbietern auf diesen Parameter finden Sie in den Blob-Abschnitten für private Schlüssel von Microsoft Cryptographic Service Providers.
[in] dwBlobType
Gibt den Typ des Schlüsselblobs an, das in pbData exportiert werden soll. Dies muss eine der folgenden Konstanten sein, wie unter Kryptografieschlüsselspeicher und Exchange erläutert.
| Wert | Bedeutung |
|---|---|
|
Dient zum Speichern von Sitzungsschlüsseln in einem Schannel-CSP oder einem anderen anbieterspezifischen Format. OPAQUEKEYBLOBs sind nicht übertragbar und müssen innerhalb des CSP verwendet werden, der das BLOB generiert hat. |
|
Wird zum Transport von öffentlichen/privaten Schlüsselpaaren verwendet. |
|
Wird zum Transport öffentlicher Schlüssel verwendet. |
|
Wird zum Transport von Sitzungsschlüsseln verwendet. |
|
Ein PLAINTEXTKEYBLOB , der zum Exportieren eines beliebigen Schlüssels verwendet wird, der vom verwendeten CSP unterstützt wird. |
|
Wird zum Exportieren und Importieren eines symmetrischen Schlüssels verwendet, der mit einem anderen symmetrischen Schlüssel umschlossen ist. Der eigentliche umschlossene Schlüssel hat das Format, das im IETF RFC 3217-Standard angegeben ist. |
[in] dwFlags
Gibt zusätzliche Optionen für die Funktion an. Dieser Parameter kann null oder eine Kombination aus einem oder mehreren der folgenden Werte sein.
[out] pbData
Ein Zeiger auf einen Puffer, der die schlüsseligen BLOB-Daten empfängt. Das Format dieses BLOB variiert je nach dem BLOB-Typ, der im dwBlobType-Parameter angefordert wird. Das Format für PRIVATEKEYBLOBs, PUBLICKEYBLOBs und SIMPLEBLOBs finden Sie unter Basisanbieterschlüssel-BLOBs.
Wenn dieser Parameter NULL ist, wird die erforderliche Puffergröße in dem Wert platziert, auf den der pdwDataLen-Parameter verweist. Weitere Informationen finden Sie unter Abrufen von Daten unbekannter Länge.
[in, out] pdwDataLen
Ein Zeiger auf einen DWORD-Wert , der bei einem Eintrag die Größe des Puffers in Bytes enthält, auf den der pbData-Parameter verweist. Wenn die Funktion zurückgibt, enthält dieser Wert die Anzahl der im Puffer gespeicherten Bytes.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero (TRUE) zurück.
Wenn die Funktion fehlschlägt, gibt sie null (FALSE) zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.
Die von "NTE" vorangestellten Fehlercodes werden vom verwendeten CSP generiert. In der folgenden Tabelle sind einige der möglichen Fehlercodes aufgeführt.
| Rückgabecode | Beschreibung |
|---|---|
|
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. |
|
Wenn der vom pbData-Parameter angegebene Puffer nicht groß genug ist, um die zurückgegebenen Daten aufzunehmen, legt die Funktion den ERROR_MORE_DATA Code fest und speichert die erforderliche Puffergröße in Bytes in der Variablen, auf die von pdwDataLen verwiesen wird. |
|
Entweder wird der Algorithmus, der mit dem zu exportierenden öffentlichen Schlüssel arbeitet, von diesem CSP nicht unterstützt, oder es wurde versucht, einen Sitzungsschlüssel zu exportieren, der mit einem anderen als einem Ihrer öffentlichen Schlüssel verschlüsselt wurde. |
|
Der dwFlags-Parameter ist nonzero. |
|
Ein oder beide der von hKey und hExpKey angegebenen Schlüssel sind ungültig. |
|
Sie verfügen nicht über die Berechtigung zum Exportieren des Schlüssels. Das heißt, beim Erstellen des hKey-Schlüssels wurde das flag CRYPT_EXPORTABLE nicht angegeben. |
|
Der durch dwBlobType angegebene Schlüsselblobtyp ist PUBLICKEYBLOB, hExpKey enthält jedoch kein Handle mit öffentlichem Schlüssel. |
|
Der dwBlobType-Parameter gibt einen unbekannten BLOB-Typ an. |
|
Der CSP-Kontext, der beim Erstellen des hKey-Schlüssels angegeben wurde, kann nicht gefunden werden. |
|
Ein Sitzungsschlüssel wird exportiert, und der hExpKey-Parameter gibt keinen öffentlichen Schlüssel an. |
Hinweise
Für jede der DES-Schlüsselpermutationen, die ein PLAINTEXTKEYBLOB verwenden, kann nur die vollständige Schlüsselgröße, einschließlich des Paritätsbits, exportiert werden. 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 Sie einen kryptografischen Schlüssel oder ein Schlüsselpaar sicherer exportieren. In diesem Beispiel wird davon ausgegangen, dass ein kryptografischer Kontext abgerufen wurde und dass ein öffentlicher Schlüssel für den Export verfügbar ist. Ein Beispiel, das den vollständigen Kontext für die Verwendung dieser Funktion enthält, finden Sie unter Beispiel C-Programm: Signieren eines Hashs und Überprüfen der Hashsignatur. Ein weiteres Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel C-Programm: Exportieren eines Sitzungsschlüssels.
#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
BOOL GetExportedKey(
HCRYPTKEY hKey,
DWORD dwBlobType,
LPBYTE *ppbKeyBlob,
LPDWORD pdwBlobLen)
{
DWORD dwBlobLength;
*ppbKeyBlob = NULL;
*pdwBlobLen = 0;
// Export the public key. Here the public key is exported to a
// PUBLICKEYBLOB. This BLOB can be written to a file and
// sent to another user.
if(CryptExportKey(
hKey,
NULL,
dwBlobType,
0,
NULL,
&dwBlobLength))
{
printf("Size of the BLOB for the public key determined. \n");
}
else
{
printf("Error computing BLOB length.\n");
return FALSE;
}
// Allocate memory for the pbKeyBlob.
if(*ppbKeyBlob = (LPBYTE)malloc(dwBlobLength))
{
printf("Memory has been allocated for the BLOB. \n");
}
else
{
printf("Out of memory. \n");
return FALSE;
}
// Do the actual exporting into the key BLOB.
if(CryptExportKey(
hKey,
NULL,
dwBlobType,
0,
*ppbKeyBlob,
&dwBlobLength))
{
printf("Contents have been written to the BLOB. \n");
*pdwBlobLen = dwBlobLength;
}
else
{
printf("Error exporting key.\n");
free(*ppbKeyBlob);
*ppbKeyBlob = NULL;
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 |