Funzione CryptExportKey (wincrypt.h)

Importante Questa API è deprecata. Il software nuovo e esistente deve iniziare a usare le API di nuova generazione di crittografia. Microsoft può rimuovere questa API nelle versioni future.

 

La funzione CryptExportKey esporta una chiave crittografica o una coppia di chiavi da un provider di servizi di crittografia (CSP) in modo sicuro.

Un handle alla chiave da esportare viene passato alla funzione e la funzione restituisce un BLOB di chiavi. Questo BLOB di chiavi può essere inviato su un trasporto non sicuro o archiviato in un percorso di archiviazione non sicuro. Questa funzione può esportare una chiave di sessione Schannel , una chiave di sessione regolare, una chiave pubblica o una coppia di chiavi pubblica/privata. Il BLOB della chiave da esportare non è inutile finché il destinatario non usa la funzione CryptImportKey su di esso per importare la chiave o la coppia di chiavi nel CSP di un destinatario.

Sintassi

BOOL CryptExportKey(
  [in]      HCRYPTKEY hKey,
  [in]      HCRYPTKEY hExpKey,
  [in]      DWORD     dwBlobType,
  [in]      DWORD     dwFlags,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen
);

Parametri

[in] hKey

Handle alla chiave da esportare.

[in] hExpKey

Handle a una chiave crittografica dell'utente di destinazione. I dati chiave all'interno del BLOB della chiave esportata vengono crittografati usando questa chiave. Ciò garantisce che solo l'utente di destinazione sia in grado di usare il BLOB della chiave. Sia hExpKey che hKey devono venire dallo stesso CSP.

La maggior parte delle volte è la chiave pubblica di scambio delle chiavi dell'utente di destinazione. Tuttavia, alcuni protocolli in alcuni provider di servizi di configurazione richiedono che una chiave di sessione appartenente all'utente di destinazione venga usata per questo scopo.

Se il tipo BLOB di chiave specificato da dwBlobType è PUBLICKEYBLOB, questo parametro è inutilizzato e deve essere impostato su zero.

Se il tipo BLOB di chiave specificato da dwBlobType è PRIVATEKEYBLOB, questo è in genere un handle per una chiave di sessione da usare per crittografare il BLOB della chiave. Alcuni provider di servizi di rete consentono a questo parametro di essere zero, nel qual caso l'applicazione deve crittografare manualmente il BLOB della chiave privata in modo da proteggerlo.

Per determinare il modo in cui i provider di servizi di crittografia Microsoft rispondono a questo parametro, vedere le sezioni BLOB delle chiavi private dei provider di servizi di crittografia Microsoft.

Nota Alcuni provider di servizi di configurazione possono modificare questo parametro come risultato dell'operazione. Le applicazioni che successivamente usano questa chiave per altri scopi devono chiamare la funzione CryptDuplicateKey per creare un handle di chiavi duplicato. Al termine dell'uso dell'applicazione, rilasciarla chiamando la funzione CryptDestroyKey .

 

[in] dwBlobType

Specifica il tipo di BLOB della chiave da esportare in pbData. Questa deve essere una delle costanti seguenti, come illustrato in Archiviazione chiavi crittografiche e Exchange.

Valore	Significato
OPACKEYBLOB	Usato per archiviare le chiavi di sessione in un CSP Schannel o in qualsiasi altro formato specifico del fornitore. I BLOB OPACOKEYBLOB non sono trasferibili e devono essere usati all'interno del provider di servizi di certificazione che ha generato il BLOB.
PRIVATEKEYBLOB	Usato per trasportare coppie di chiavi pubbliche/private.
PUBLICKEYBLOB	Usato per trasportare chiavi pubbliche.
SIMPLEBLOB	Usato per trasportare le chiavi di sessione.
PLAINTEXTKEYBLOB	Un oggetto PLAINTEXTKEYBLOB usato per esportare qualsiasi chiave supportata dal CSP in uso.
SYMMETRICWRAPKEYBLOB	Usato per esportare e importare una chiave simmetrica con un'altra chiave simmetrica. La chiave di wrapping effettiva è nel formato specificato nello standard IETF RFC 3217 .

[in] dwFlags

Specifica opzioni aggiuntive per la funzione. Questo parametro può essere zero o una combinazione di uno o più dei valori seguenti.

Valore	Significato
CRYPT_BLOB_VER3 0x00000080	Questo flag causa l'esportazione della funzione versione 3 di un tipo BLOB.
CRYPT_DESTROYKEY 0x00000004	Questo flag elimina la chiave originale in OPAQUEKEYBLOB. Questo flag è disponibile solo nei provider di servizi di configurazione Schannel.
CRYPT_OAEP 0x00000040	Questo flag causa la creazione della formattazione PKCS #1 versione 2 con la crittografia RSA e la decrittografia durante l'esportazione di SIMPLEBLOBs.
CRYPT_SSL2_FALLBACK 0x00000002	I primi otto byte del riempimento del blocco di crittografia RSA devono essere impostati su 0x03 anziché su dati casuali. Ciò impedisce attacchi di rollback della versione e viene descritto nella specifica SSL3. Questo flag è disponibile solo per i provider di servizi di rete Schannel.
CRYPT_Y_ONLY 0x00000001	Questo flag non viene usato.

[out] pbData

Puntatore a un buffer che riceve i dati BLOB delle chiavi . Il formato di questo BLOB varia a seconda del tipo BLOB richiesto nel parametro dwBlobType . Per il formato per PRIVATEKEYBLOBs, PUBLICKEYBLOBs e SIMPLEBLOBs, vedere BLOBS chiave provider di base.

Se questo parametro è NULL, la dimensione del buffer necessaria viene inserita nel valore a cui punta il parametro pdwDataLen . Per altre informazioni, vedere Recupero dei dati di lunghezza sconosciuta.

[in, out] pdwDataLen

Puntatore a un valore DWORD che, nella voce, contiene le dimensioni, in byte, del buffer a cui punta il parametro pbData . Quando la funzione restituisce, questo valore contiene il numero di byte archiviati nel buffer.

Nota Quando si elaborano i dati restituiti nel buffer, le applicazioni devono usare le dimensioni effettive dei dati restituiti. Le dimensioni effettive possono essere leggermente inferiori rispetto alle dimensioni del buffer specificato nell'input. In input le dimensioni del buffer vengono in genere specificate abbastanza grandi per garantire che i dati di output più grandi siano adatti al buffer. Nell'output la variabile a cui punta questo parametro viene aggiornata per riflettere le dimensioni effettive dei dati copiati nel buffer.

 

Per recuperare le dimensioni necessarie del buffer pbData , passare NULL per pbData. Le dimensioni del buffer necessarie verranno posizionate nel valore a cui fa riferimento questo parametro.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce non zero (TRUE).

Se la funzione ha esito negativo, restituisce zero (FALSE). Per informazioni sull'errore estese, chiamare GetLastError.

I codici di errore preceduti da "NTE" vengono generati dal particolare CSP usato. La tabella seguente mostra alcuni dei possibili codici di errore.

Codice restituito	Descrizione
ERROR_INVALID_HANDLE	Uno dei parametri specifica un handle non valido.
ERROR_INVALID_PARAMETER	Uno dei parametri contiene un valore non valido. Questo è più spesso un puntatore che non è valido.
ERROR_MORE_DATA	Se il buffer specificato dal parametro pbData non è sufficiente per contenere i dati restituiti, la funzione imposta il codice ERROR_MORE_DATA e archivia le dimensioni del buffer necessarie, in byte, nella variabile a cui punta pdwDataLen.
NTE_BAD_DATA	L'algoritmo che funziona con la chiave pubblica da esportare non è supportato da questo CSP o un tentativo di esportazione di una chiave di sessione crittografata con un elemento diverso da una delle chiavi pubbliche.
NTE_BAD_FLAGS	Il parametro dwFlags è diverso da zero.
NTE_BAD_KEY	Una o entrambe le chiavi specificate da hKey e hExpKey non sono valide.
NTE_BAD_KEY_STATE	Non si dispone dell'autorizzazione per esportare la chiave. Ovvero, quando è stata creata la chiave hKey , il flag di CRYPT_EXPORTABLE non è stato specificato.
NTE_BAD_PUBLIC_KEY	Il tipo BLOB della chiave specificato da dwBlobType è PUBLICKEYBLOB , ma hExpKey non contiene un handle di chiave pubblica.
NTE_BAD_TYPE	Il parametro dwBlobType specifica un tipo BLOB sconosciuto.
NTE_BAD_UID	Impossibile trovare il contesto CSP specificato quando è stata creata la chiave hKey .
NTE_NO_KEY	Una chiave di sessione viene esportata e il parametro hExpKey non specifica una chiave pubblica.

Commenti

Per una delle permutazioni delle chiavi DES che usano un file PLAINTEXTKEYBLOB, è possibile esportare solo le dimensioni complete della chiave, incluso il bit di parità. Sono supportate le dimensioni delle chiavi seguenti.

Algoritmo	Dimensioni della chiave supportate
CALG_DES	64 bit
CALG_3DES_112	128 bit
CALG_3DES	192 bit

 

Esempio

Nell'esempio seguente viene illustrato come esportare una chiave crittografica o una coppia di chiavi in modo più sicuro. In questo esempio si presuppone che sia stato acquisito un contesto crittografico e che una chiave pubblica sia disponibile per l'esportazione. Per un esempio che include il contesto completo per l'uso di questa funzione, vedere Esempio di programma C: firma di un hash e verifica della firma hash. Per un altro esempio che usa questa funzione, vedere Esempio di programma C: Esportazione di una chiave di sessione.

#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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wincrypt.h
Libreria	Advapi32.lib
DLL	Advapi32.dll

Vedi anche

CryptImportKey

Generazione di chiavi e funzioni di Exchange