Funzione CryptImportKey (wincrypt.h)

  • Articolo
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 CryptImportKey trasferisce una chiave crittografica da un BLOB di chiavi in un provider di servizi di crittografia (CSP). Questa funzione può essere usata per importare una chiave sessioneSchannel, una chiave di sessione regolare, una chiave pubblica o una coppia di chiavi pubblica/privata. Per tutte le chiavi pubbliche, la chiave o la coppia di chiavi viene crittografata.

Sintassi

BOOL CryptImportKey(
  [in]  HCRYPTPROV hProv,
  [in]  const BYTE *pbData,
  [in]  DWORD      dwDataLen,
  [in]  HCRYPTKEY  hPubKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTKEY  *phKey
);

Parametri

[in] hProv

Handle di un CSP ottenuto con la funzione CryptAcquireContext .

[in] pbData

Matrice BYTE che contiene un'intestazione BLOB PUBLICKEYSTRUC seguita dalla chiave crittografata. Questo BLOB di chiavi viene creato dalla funzione CryptExportKey , in questa applicazione o da un'altra applicazione eventualmente in esecuzione in un computer diverso.

[in] dwDataLen

Contiene la lunghezza, in byte, del BLOB della chiave.

[in] hPubKey

Handle alla chiave crittografica che decrittografa la chiave archiviata in pbData. Questa chiave deve venire dallo stesso CSP a cui si riferisce hProv . Il significato di questo parametro varia a seconda del tipo CSP e del tipo di BLOB della chiave da importare:

  • Se il BLOB della chiave viene crittografato con la coppia di chiavi di scambio delle chiavi, ad esempio un SIMPLEBLOB, questo parametro può essere l'handle per la chiave di scambio delle chiavi.
  • Se il BLOB della chiave viene crittografato con una chiave di sessione, ad esempio un PRIVATEKEYBLOB crittografato, questo parametro contiene l'handle di questa chiave di sessione.
  • Se il BLOB della chiave non è crittografato, ad esempio un PUBLICKEYBLOB, questo parametro non viene usato e deve essere zero.
  • Se il BLOB della chiave viene crittografato con una chiave di sessione in un CSP Schannel , ad esempio, un BLOB OPACOBLOB crittografato o qualsiasi altro tipo DI OPACKEYBLOB specifico del fornitore, questo parametro non viene usato e deve essere impostato su zero.
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] dwFlags

Attualmente usato solo quando una coppia di chiavi pubblica/privata sotto forma di PRIVATEKEYBLOB viene importata nel CSP.

Questo parametro può avere uno dei valori seguenti.

Valore Significato
CRYPT_EXPORTABLE
 La chiave importata deve essere rieseportata. Se questo flag non viene usato, le chiamate a CryptExportKey hanno esito negativo.
CRYPT_OAEP
 Questo flag causa la verifica della formattazione PKCS #1 versione 2 con crittografia RSA e decrittografia durante l'importazione di SIMPLEBLOBs.
CRYPT_NO_SALT
 Un valore senza sale viene allocato per una chiave simmetrica a 40 bit. Per altre informazioni, vedere Funzionalità del valore salt.
CRYPT_USER_PROTECTED
 Se questo flag è impostato, il CSP notifica all'utente tramite una finestra di dialogo o un altro metodo quando si tenta di usare questa chiave. Il comportamento preciso viene specificato dal CSP o dal tipo CSP usato. Se il contesto del provider è stato acquisito con CRYPT_SILENT impostato, l'uso di questo flag causa un errore e l'ultimo errore è impostato su NTE_SILENT_CONTEXT.
CRYPT_IPSEC_HMAC_KEY
 Consente l'importazione di una chiave RC2 maggiore di 16 byte. Se questo flag non è impostato, le chiamate alla funzione CryptImportKey con chiavi RC2 superiori a 16 byte non riescono e una chiamata a GetLastError restituirà NTE_BAD_DATA.

[out] phKey

Puntatore a un valore HCRYPTKEY che riceve l'handle della chiave importata. Al termine dell'uso della chiave, rilasciare l'handle chiamando la funzione CryptDestroyKey .

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero.

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

I codici di errore preceduti da "NTE" vengono generati dal particolare CSP usato. Alcuni codici di errore possibili seguono.

Codice restituito Descrizione
ERROR_BUSY
 Alcuni provider di servizi di configurazione impostano questo errore se una chiave privata viene importata in un contenitore mentre un altro thread o un processo usa questa chiave.
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.
NTE_BAD_ALGID
 Il BLOB della chiave semplice da importare non viene crittografato con l'algoritmo di scambio delle chiavi previsto.
NTE_BAD_DATA
 L'algoritmo che funziona con la chiave pubblica da importare non è supportato da questo CSP o un tentativo di importare una chiave di sessione crittografata con un elemento diverso da una delle chiavi pubbliche.
NTE_BAD_FLAGS
 Il parametro dwFlags specificato non è valido.
NTE_BAD_TYPE
 Il tipo BLOB della chiave non è supportato da questo CSP e potrebbe non essere valido.
NTE_BAD_UID
 Il parametro hProv non contiene un handle di contesto valido.
NTE_BAD_VER
 Il numero di versione del BLOB della chiave non corrisponde alla versione CSP. Questo indica in genere che il provider di servizi di configurazione deve essere aggiornato.

Commenti

Quando si importa una chiave HMAC ( Hash-Based Message Authentication Code ), il chiamante deve identificare la chiave importata come tipo PLAINTEXTKEYBLOB e impostare l'identificatore dell'algoritmo appropriato nel campo aiKeyAlg dell'intestazione BLOB PUBLICKEYSTRUC .

La funzione CryptImportKey può essere usata per importare una chiave di testo non crittografato per gli algoritmi simmetrici; Tuttavia, è consigliabile, per semplificare l'uso, usare invece la funzione CryptGenKey . Quando si importa una chiave di testo non crittografato, la struttura del BLOB della chiave passata nel parametro pbData è un OGGETTO PLAINTEXTKEYBLOB.

È possibile usare il tipo PLAINTEXTKEYBLOB con qualsiasi algoritmo o tipo di combinazione di chiavi supportata dal CSP in uso.

Per un esempio di importazione di una chiave di testo non crittografato, vedere Esempio di programma C: Importazione di una chiave di testo non crittografato.

Nell'esempio seguente viene illustrato come impostare i campi di intestazione.

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;

La lunghezza della chiave viene specificata in keyBlob.keyLength, seguita dai dati delle chiavi effettivi.

Nota Gli algoritmi HMAC non hanno i propri identificatori di algoritmo; usare CALG_RC2 invece. CRYPT_IPSEC_HMAC_KEY consente l'importazione di chiavi RC2 più lunghe di 16 byte.
 
Per una delle permutazioni delle chiavi standard (DES) di Data Encryption Standard che usano PLAINTEXTKEYBLOB, è possibile importare solo le dimensioni complete della chiave, incluso 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 importare una chiave da un BLOB di chiavi. Per un esempio completo per questa funzione, vedere Esempio di programma C: firma di un hash e verifica della firma hash. Per codice aggiuntivo che usa questa funzione, vedere Esempio di programma C: Decrittografia di un file.

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

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

Cryptacquirecontext

CryptDestroyKey

CryptExportKey

Generazione di chiavi e funzioni di Exchange