Funzione CryptImportKey (wincrypt.h)
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 provider di servizi di configurazione ottenuto con la funzione CryptAcquireContext.
[in] pbData
Matrice di BYTE che contiene un 'intestazione PUBLICKEYSTRUC BLOB seguita dalla chiave crittografata. Questo BLOB di chiavi viene creato dalla funzione
[in] dwDataLen
Contiene la lunghezza, in byte, del BLOB della chiave.
[in] hPubKey
Handle per la chiave crittografica che decrittografa la chiave archiviata in pbData. Questa chiave deve provenire dallo stesso provider di servizi di configurazione a cui fa riferimento hProv. Il significato di questo parametro varia a seconda del tipo CSP e del tipo di BLOB della chiave da importare:
- Se la chiave BLOB viene crittografata con la chiave coppia di chiavi di scambio, ad esempio un SIMPLEBLOB, questo parametro può essere l'handle per la chiave di scambio delle chiavi.
- Se la chiave BLOB viene crittografata 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 la chiave BLOB viene crittografata con una chiave di sessione in un provider di servizi di configurazione Schannel, ad esempio, un ENCRYPTKEYBLOB o qualsiasi altro OPACKEYBLOB specifico del fornitore, questo parametro non viene usato e deve essere impostato su zero.
[in] dwFlags
Attualmente usato solo quando una coppia di chiavi pubblica/privata sotto forma di PRIVATEKEYBLOB viene importata nel provider di servizi di configurazione.
Questo parametro può essere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
La chiave da importare alla fine deve essere riesportata. Se questo flag non viene usato, le chiamate a CryptExportKey con l'handle di chiave hanno esito negativo. |
|
Questo flag causa la verifica della formattazione PKCS #1 versione 2 con crittografia e decrittografia RSA durante l'importazione di SIMPLEBLOBs. |
|
Un valore senza salt viene allocato per una chiave simmetrica a 40 bit. Per altre informazioni, vedere funzionalità valore salt. |
|
Se questo flag è impostato, il provider di servizi di configurazione notifica all'utente tramite una finestra di dialogo o un altro metodo quando vengono tentate determinate azioni usando 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 viene impostato su NTE_SILENT_CONTEXT. |
|
Consente l'importazione di una chiave RC2 maggiore di 16 byte. Se questo flag non è impostato, le chiamate alla funzione CryptImportKey con chiavi RC2 maggiori di 16 byte hanno esito negativo 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 sugli errori estesi, chiamare GetLastError.
I codici di errore preceduti da "NTE" vengono generati dal provider di servizi di configurazione specifico usato. Di seguito sono riportati alcuni possibili codici di errore.
| Codice restituito | Descrizione |
|---|---|
|
Alcuni CSP impostano questo errore se una chiave privata viene importata in un contenitore mentre un altro thread o processo sta usando questa chiave. |
|
Uno dei parametri specifica un handle non valido. |
|
Uno dei parametri contiene un valore non valido. Si tratta più spesso di un puntatore non valido. |
|
La BLOB di chiavi semplice da importare non viene crittografata con l'algoritmo di scambio di chiavi previsto. |
|
L'algoritmo che funziona con la chiave pubblica da importare non è supportato da questo CSP oppure è stato effettuato un tentativo di importare una chiave di sessione crittografata con un valore diverso da una delle chiavi pubbliche. |
|
Il parametro dwFlags |
|
Il tipo di BLOB della chiave non è supportato da questo provider di servizi di configurazione ed è probabilmente non valido. |
|
Il parametro hProv non contiene un handle di contesto valido. |
|
Il numero di versione del BLOB della chiave non corrisponde alla versione CSP. Ciò indica in genere che il provider di servizi di configurazione deve essere aggiornato. |
Osservazioni
Quando si importa una chiave HMAC (Message Authentication Code) di
La funzione CryptImportKey
È possibile usare il tipo
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 effettivi della chiave.
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 |
Esempi
Nell'esempio seguente viene illustrato come importare una chiave da un BLOB di chiavi. Per un esempio completo di questa funzione, vedere Programma C di esempio: Firma di un hash e verifica della firma hash. Per codice aggiuntivo che usa questa funzione, vedere Programma C di esempio: 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;
}
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [solo app desktop] |
| server minimo supportato | Windows Server 2003 [solo app desktop] |
| piattaforma di destinazione | Finestre |
| intestazione |
wincrypt.h |
| libreria |
Advapi32.lib |
| dll | Advapi32.dll |