Funzione BCryptImportKey (bcrypt.h)

Articolo
07/16/2024

La funzione BCryptImportKey importa una chiave simmetrica da una chiave BLOB. La funzione BCryptImportKeyPair viene usata per importare una coppia di chiavi pubblica/privata.

Sintassi

NTSTATUS BCryptImportKey(
  [in]            BCRYPT_ALG_HANDLE hAlgorithm,
  [in, optional]  BCRYPT_KEY_HANDLE hImportKey,
  [in]            LPCWSTR           pszBlobType,
  [out]           BCRYPT_KEY_HANDLE *phKey,
  [out, optional] PUCHAR            pbKeyObject,
  [in]            ULONG             cbKeyObject,
  [in]            PUCHAR            pbInput,
  [in]            ULONG             cbInput,
  [in]            ULONG             dwFlags
);

Parametri

[in] hAlgorithm

Handle del provider di algoritmi per importare la chiave. Questo handle viene ottenuto chiamando la funzione BCryptOpenAlgorithmProvider.

[in, optional] hImportKey

Handle della chiave di crittografia della chiave necessaria per annullare il wrapping del BLOB della chiave nel parametro pbInput .

Nota L'handle deve essere fornito dallo stesso provider che ha fornito la chiave da importare.

Windows Server 2008 e Windows Vista: Questo parametro non viene usato e deve essere impostato su NULL.

[in] pszBlobType

Stringa Unicode con terminazione Null contenente un identificatore che specifica il tipo di BLOB contenuto nel buffer pbInput . Può trattarsi di uno dei valori seguenti.

Valore	Significato
BCRYPT_AES_WRAP_KEY_BLOB	Importare una chiave simmetrica da un BLOB di chiavi AES con wrapping. Il parametro hImportKey deve fare riferimento a un puntatore BCRYPT_KEY_HANDLE valido alla chiave di crittografia della chiave. Windows Server 2008 e Windows Vista: Questo tipo di BLOB non è supportato.
BCRYPT_KEY_DATA_BLOB	Importare una chiave simmetrica da un BLOB di dati. Il parametro pbInput è un puntatore a una struttura BCRYPT_KEY_DATA_BLOB_HEADER immediatamente seguita dal BLOB della chiave.
BCRYPT_OPAQUE_KEY_BLOB	Importare un BLOB di chiavi simmetriche in un formato specifico di un singolo provider di servizi di configurazione. I BLOB opachi non sono trasferiscibili e devono essere importati usando lo stesso CSP che ha generato il BLOB. I BLOB opachi devono essere usati solo per il trasferimento interprocesso delle chiavi e non sono adatti per essere salvati in modo permanente e letti in tutte le versioni di un provider.

[out] phKey

Puntatore a un BCRYPT_KEY_HANDLE che riceve l'handle della chiave importata. Questo handle viene usato nelle funzioni successive che richiedono una chiave, ad esempio BCryptEncrypt. Questo handle deve essere rilasciato quando non è più necessario passandolo alla funzione BCryptDestroyKey .

[out, optional] pbKeyObject

Puntatore a un buffer che riceve l'oggetto chiave importato. Il parametro cbKeyObject contiene le dimensioni di questo buffer. Le dimensioni necessarie di questo buffer possono essere ottenute chiamando la funzione BCryptGetProperty per ottenere la proprietà BCRYPT_OBJECT_LENGTH. In questo modo verranno fornite le dimensioni dell'oggetto chiave per l'algoritmo specificato.

Questa memoria può essere liberata solo dopo che l'handle della chiave phKey viene eliminato definitivamente.

[in] cbKeyObject

Dimensioni, in byte, del buffer pbKeyObject .

[in] pbInput

Indirizzo di un buffer contenente il BLOB della chiave da importare. Il parametro cbInput contiene le dimensioni di questo buffer. Il parametro pszBlobType specifica il tipo di chiave BLOB contenuto nel buffer.

[in] cbInput

Dimensioni, in byte, del buffer pbInput .

[in] dwFlags

Set di flag che modificano il comportamento di questa funzione. Non sono attualmente definiti flag, quindi questo parametro deve essere zero.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione.

I codici restituiti possibili includono, ma non solo, quanto segue.

Codice restituito	Descrizione
STATUS_SUCCESS	La funzione ha avuto esito positivo.
STATUS_BUFFER_TOO_SMALL	Le dimensioni dell'oggetto chiave specificato dal parametro cbKeyObject non sono sufficienti per contenere l'oggetto chiave.
STATUS_INVALID_HANDLE	L'handle dell'algoritmo nel parametro hAlgorithm non è valido.
STATUS_INVALID_PARAMETER	Uno o più parametri non sono validi.
STATUS_NOT_SUPPORTED	Il provider di algoritmi specificato dal parametro hAlgorithm non supporta il tipo BLOB specificato dal parametro pszBlobType.

Osservazioni

A seconda delle modalità del processore supportate da un provider, è possibile chiamare BCryptImportKey dalla modalità utente o dal kernel. I chiamanti in modalità kernel possono essere eseguiti in PASSIVE_LEVELirQL o DISPATCH_LEVEL IRQL. Se il livello IRQL corrente è DISPATCH_LEVEL, l'handle fornito nella parametro hAlgorithm deve essere stato aperto usando il flag di BCRYPT_PROV_DISPATCH e qualsiasi puntatore passato alla funzione BCryptImportKey deve fare riferimento a memoria non di pagina (o bloccata).

Per chiamare questa funzione in modalità kernel, usare Cng.lib, che fa parte del Driver Development Kit (DDK). Windows Server 2008 e Windows Vista: Per chiamare questa funzione in modalità kernel, usare Ksecdd.lib.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [app desktop \| App UWP]
server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	bcrypt.h
libreria	Bcrypt.lib
dll	Bcrypt.dll

Vedere anche

BCryptDestroyKey

BCryptExportKey

BCryptImportKeyPair

Condividi tramite