Funzione BCryptGenerateSymmetricKey (bcrypt.h)

Articolo
07/16/2024

La funzione BCryptGenerateSymmetricKey crea un oggetto chiave da usare con un algoritmo di crittografia con chiave simmetrica da una chiave fornita.

Sintassi

NTSTATUS BCryptGenerateSymmetricKey(
  [in, out]       BCRYPT_ALG_HANDLE hAlgorithm,
  [out]           BCRYPT_KEY_HANDLE *phKey,
  [out, optional] PUCHAR            pbKeyObject,
  [in]            ULONG             cbKeyObject,
  [in]            PUCHAR            pbSecret,
  [in]            ULONG             cbSecret,
  [in]            ULONG             dwFlags
);

Parametri

[in, out] hAlgorithm

Handle di un provider di algoritmi creato con la funzione BCryptOpenAlgorithmProvider . L'algoritmo specificato al momento della creazione del provider deve supportare la crittografia della chiave simmetrica.

[out] phKey

Puntatore a un BCRYPT_KEY_HANDLE che riceve l'handle della chiave. 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. 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.

Se il valore di questo parametro è NULL e il valore del parametro cbKeyObject è zero, la memoria per l'oggetto chiave viene allocata e liberata da questa funzione.Windows 7: Questa funzionalità di gestione della memoria è disponibile a partire da Windows 7.

[in] cbKeyObject

Dimensioni, in byte, del buffer pbKeyObject .

Se il valore di questo parametro è zero e il valore del parametro pbKeyObject è NULL, la memoria per l'oggetto chiave viene allocata e liberata da questa funzione.Windows 7: Questa funzionalità di gestione della memoria è disponibile a partire da Windows 7.

[in] pbSecret

Puntatore a un buffer contenente la chiave da cui creare l'oggetto chiave. Il parametro cbSecret contiene le dimensioni di questo buffer. Si tratta in genere di un hash di una password o di altri dati riproducibili. Se i dati passati superano le dimensioni della chiave di destinazione, i dati verranno troncati e l'eccesso verrà ignorato.

Si noti è consigliabile che le applicazioni passino il numero esatto di byte richiesti dalla chiave di destinazione.

[in] cbSecret

Dimensioni, in byte, del buffer pbSecret .

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

Osservazioni

A seconda delle modalità del processore supportate da un provider, è possibile chiamare BCryptGenerateSymmetricKey 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 nel parametro hAlgorithm deve essere stato aperto usando il flag BCRYPT_PROV_DISPATCH e qualsiasi puntatore passato alla funzione BCryptGenerateSymmetricKey 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

Condividi tramite