Freigeben über


CryptExportKey-Funktion (wincrypt.h)

Wichtig Diese API ist veraltet. Neue und vorhandene Software sollten mit der Verwendung von Kryptografie-APIs der nächsten Generation beginnen. Microsoft kann diese API in zukünftigen Releases entfernen.
 
Die CryptExportKey-Funktion exportiert einen kryptografischen Schlüssel oder ein Schlüsselpaar von einem Kryptografiedienstanbieter (CSP ) auf sichere Weise.

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.

Hinweis Einige CSPs können diesen Parameter als Ergebnis des Vorgangs ändern. Anwendungen, die diesen Schlüssel anschließend für andere Zwecke verwenden, sollten die CryptDuplicateKey-Funktion aufrufen, um ein doppeltes Schlüsselhandle zu erstellen. Wenn die Anwendung die Verwendung des Handles abgeschlossen hat, lassen Sie es los, indem Sie die Funktion CryptDestroyKey aufrufen.
 

[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
OPAQUEKEYBLOB
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.
PRIVATEKEYBLOB
Wird zum Transport von öffentlichen/privaten Schlüsselpaaren verwendet.
PUBLICKEYBLOB
Wird zum Transport öffentlicher Schlüssel verwendet.
SIMPLEBLOB
Wird zum Transport von Sitzungsschlüsseln verwendet.
PLAINTEXTKEYBLOB
Ein PLAINTEXTKEYBLOB , der zum Exportieren eines beliebigen Schlüssels verwendet wird, der vom verwendeten CSP unterstützt wird.
SYMMETRICWRAPKEYBLOB
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.

Wert Bedeutung
CRYPT_BLOB_VER3
0x00000080
Dieses Flag bewirkt, dass diese Funktion Version 3 eines BLOB-Typs exportiert.
CRYPT_DESTROYKEY
0x00000004
Dieses Flag zerstört den ursprünglichen Schlüssel im OPAQUEKEYBLOB. Dieses Flag ist nur in Schannel-CSPs verfügbar.
CRYPT_OAEP
0x00000040
Dieses Flag bewirkt, dass beim Exportieren von SIMPLEBLOBs EINE PKCS #1 Version 2-Formatierung mit der RSA-Verschlüsselung und -Entschlüsselung erstellt wird.
CRYPT_SSL2_FALLBACK
0x00000002
Die ersten acht Bytes der RSA-Verschlüsselungsblockfüllung müssen auf 0x03 und nicht auf zufällige Daten festgelegt werden. Dies verhindert Versionsrollbackangriffe und wird in der SSL3-Spezifikation erläutert. Dieses Flag ist nur für Schannel-CSPs verfügbar.
CRYPT_Y_ONLY
0x00000001
Dieses Flag wird nicht verwendet.

[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.

Hinweis Bei der Verarbeitung der im Puffer zurückgegebenen Daten müssen Anwendungen die tatsächliche Größe der zurückgegebenen Daten verwenden. Die tatsächliche Größe kann etwas kleiner sein als die Größe des Puffers, der bei der Eingabe angegeben wird. Bei der Eingabe werden Puffergrößen in der Regel groß genug angegeben, um sicherzustellen, dass die größtmöglichen Ausgabedaten in den Puffer passen. Bei der Ausgabe wird die Variable aktualisiert, auf die dieser Parameter verweist, um die tatsächliche Größe der in den Puffer kopierten Daten widerzuspiegeln.
 
Um die erforderliche Größe des pbData-Puffers abzurufen, übergeben Sie NULL für pbData. Die erforderliche Puffergröße wird in den Wert eingefügt, auf den dieser Parameter verweist.

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
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 in den meisten Fällen ein nicht gültiger Zeiger.
ERROR_MORE_DATA
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.
NTE_BAD_DATA
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.
NTE_BAD_FLAGS
Der dwFlags-Parameter ist nonzero.
NTE_BAD_KEY
Ein oder beide der von hKey und hExpKey angegebenen Schlüssel sind ungültig.
NTE_BAD_KEY_STATE
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.
NTE_BAD_PUBLIC_KEY
Der durch dwBlobType angegebene Schlüsselblobtyp ist PUBLICKEYBLOB, hExpKey enthält jedoch kein Handle mit öffentlichem Schlüssel.
NTE_BAD_TYPE
Der dwBlobType-Parameter gibt einen unbekannten BLOB-Typ an.
NTE_BAD_UID
Der CSP-Kontext, der beim Erstellen des hKey-Schlüssels angegeben wurde, kann nicht gefunden werden.
NTE_NO_KEY
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

Weitere Informationen

CryptImportKey

Schlüsselgenerierung und Exchange-Funktionen