Funzione BCryptDeriveKey (bcrypt.h)

La funzione BCryptDeriveKey deriva una chiave da un valore del contratto segreto.

Per la derivazione della chiave da un determinato segreto, vedere BCryptKeyDerivation.

Sintassi

NTSTATUS BCryptDeriveKey(
  [in]            BCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  BCryptBufferDesc     *pParameterList,
  [out, optional] PUCHAR               pbDerivedKey,
  [in]            ULONG                cbDerivedKey,
  [out]           ULONG                *pcbResult,
  [in]            ULONG                dwFlags
);

Parametri

[in] hSharedSecret

Handle del contratto segreto da cui creare la chiave. Questo handle viene ottenuto dalla funzione BCryptSecretAgreement.

[in] pwszKDF

Puntatore a una stringa Unicode con terminazione Null che identifica la funzione di derivazione della chiave (KDF) da usare per derivare la chiave. Può trattarsi di una delle stringhe seguenti.

BCRYPT_KDF_HASH (L"HASH")

Usare la funzione di derivazione della chiave hash.

Se il parametro cbDerivedKey è minore delle dimensioni della chiave derivata, questa funzione copia solo il numero specificato di byte nel buffer pbDerivedKey. Se il parametro cbDerivedKey è maggiore della dimensione della chiave derivata, questa funzione copia la chiave nel buffer pbDerivedKey e imposta la variabile a cui punta il pcbResult sul numero effettivo di byte copiati.

I parametri identificati dal parametro pParameterList possono o devono contenere i parametri seguenti, come indicato dalla colonna Obbligatoria o facoltativa.

La chiamata a KDF viene eseguita come illustrato nello pseudocodice seguente.

KDF-Prepend = KDF_SECRET_PREPEND[0] + 
    KDF_SECRET_PREPEND[1] + 
    ... +
    KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] + 
    KDF_SECRET_APPEND[1] + 
    ... + 
    KDF_SECRET_APPEND[n]

KDF-Output = Hash(
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_HMAC (L"HMAC")

Usare la funzione di derivazione della chiave (HMAC) Hash-Based Message Authentication Code.

Se il parametro cbDerivedKey è minore delle dimensioni della chiave derivata, questa funzione copia solo il numero specificato di byte nel buffer pbDerivedKey. Se il parametro cbDerivedKey è maggiore della dimensione della chiave derivata, questa funzione copia la chiave nel buffer pbDerivedKey e imposta la variabile a cui punta il pcbResult sul numero effettivo di byte copiati.

I parametri identificati dal parametro pParameterList possono o devono contenere i parametri seguenti, come indicato dalla colonna Obbligatoria o facoltativa.

La chiamata a KDF viene eseguita come illustrato nello pseudocodice seguente.

KDF-Prepend = KDF_SECRET_PREPEND[0] + 
    KDF_SECRET_PREPEND[1] + 
    ... +
    KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] + 
    KDF_SECRET_APPEND[1] + 
    ... + 
    KDF_SECRET_APPEND[n]

KDF-Output = HMAC-Hash(
    KDF_HMAC_KEY,
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")

Usare la funzione di derivazione della chiave (TLS) funzione pseudo-casuale (PRF). La dimensione della chiave derivata è sempre di 48 byte, pertanto il parametro cbDerivedKey deve essere 48.

I parametri identificati dal parametro pParameterList possono o devono contenere i parametri seguenti, come indicato dalla colonna Obbligatoria o facoltativa.

La chiamata a KDF viene eseguita come illustrato nello pseudocodice seguente.

KDF-Output = PRF(
    hSharedSecret, 
    KDF_TLS_PRF_LABEL, 
    KDF_TLS_PRF_SEED)

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

Usare la funzione di derivazione della chiave SP800-56A.

I parametri identificati dal parametro pParameterList possono o devono contenere i parametri seguenti, come indicato dalla colonna Obbligatoria o facoltativa. Tutti i valori dei parametri vengono considerati come matrici di byte opache.

La chiamata a KDF viene eseguita come illustrato nello pseudocodice seguente.

KDF-Output = SP_800-56A_KDF(
	   hSharedSecret,
	   KDF_ALGORITHMID,
	   KDF_PARTYUINFO,
	   KDF_PARTYVINFO,
	   KDF_SUPPPUBINFO,
	   KDF_SUPPPRIVINFO)

Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo valore non è supportato.

BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")

Restituisce la rappresentazione little-endian del segreto non elaborato senza alcuna modifica.

Se il parametro cbDerivedKey è minore delle dimensioni della chiave derivata, questa funzione copia solo il numero specificato di byte nel buffer pbDerivedKey. Se il parametro cbDerivedKey è maggiore della dimensione della chiave derivata, questa funzione copia la chiave nel buffer pbDerivedKey e imposta la variabile a cui punta il pcbResult sul numero effettivo di byte copiati.

Windows 8, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo valore non è supportato.

[in, optional] pParameterList

Indirizzo di una struttura di BCryptBufferDesc che contiene i parametri KDF. Questo parametro è facoltativo e può essere NULL se non è necessario.

[out, optional] pbDerivedKey

Indirizzo di un buffer che riceve la chiave. Il parametro cbDerivedKey contiene le dimensioni di questo buffer. Se questo parametro è NULL, questa funzione inserisce le dimensioni richieste, in byte, nel ULONG a cui punta il parametro pcbResult.

[in] cbDerivedKey

Dimensione, in byte, del buffer pbDerivedKey .

[out] pcbResult

Puntatore a un ULONG che riceve il numero di byte copiati nel buffer pbDerivedKey. Se il parametro pbDerivedKey è NULL, questa funzione inserisce le dimensioni richieste, in byte, nel ULONG a cui punta questo parametro.

[in] dwFlags

Set di flag che modificano il comportamento di questa funzione. Può essere zero o il valore seguente.

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.

Osservazioni

La struttura di BCryptBufferDesc nel parametro pParameterList può contenere più di uno dei parametri KDF_SECRET_PREPEND e KDF_SECRET_APPEND. Se vengono specificati più di uno di questi parametri, i valori dei parametri vengono concatenati nell'ordine in cui sono contenuti nella matrice prima che venga chiamata la funzione KDF. Si supponga, ad esempio, che vengano specificati i valori dei parametri seguenti.

BYTE pbValue0[1] = {0x01};
BYTE pbValue1[2] = {0x04, 0x05};
BYTE pbValue2[3] = {0x10, 0x11, 0x12};
BYTE pbValue3[4] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = pbValue0;
Parameter[0].length = sizeof  (pbValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = pbValue1;
Parameter[1].length = sizeof (pbValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = pbValue2;
Parameter[2].length = sizeof (pbValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = pbValue3;
Parameter[3].length = sizeof (pbValue3);

Se vengono specificati i valori dei parametri precedenti, i valori concatenati alla KDF effettiva sono i seguenti.

Type: KDF_SECRET_PREPEND
Value: {0x04, 0x05, 0x20, 0x21, 0x22, 0x23}, length 6

Type: KDF_SECRET_APPEND
Value: {0x01, 0x10, 0x11, 0x12}, length 4

Se il parametro pwszKDF è impostato su BCRYPT_KDF_RAW_SECRET, il segreto restituito (a differenza degli altri valori di pwszKDF) verrà codificato in formato little-endian. È importante prendere nota di questo aspetto quando si usa il segreto non elaborato in qualsiasi altra funzione CNG, perché la maggior parte di essi accetta input codificati big-endian.

A seconda delle modalità del processore supportate da un provider, è possibile chiamare BCryptDeriveKey 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 hSharedSecret deve trovarsi nella memoria non di paging (o bloccata) e deve essere derivato da un handle di algoritmo restituito da un provider aperto tramite il flag BCRYPT_PROV_DISPATCH.

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

Vedere anche

BCryptSecretAgreement