Funzione BCryptDeriveKey (bcrypt.h)

Articolo
07/16/2024

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.

Parametro	Descrizione	Obbligatorio o facoltativo
KDF_HASH_ALGORITHM	Stringa Unicode con terminazione Null che identifica l'algoritmo hash da usare. Può trattarsi di uno degli identificatori dell'algoritmo hash standard di identificatori dell'algoritmo CNG o dell'identificatore per un altro algoritmo hash registrato. Se questo parametro non viene specificato, viene utilizzato l'algoritmo hash SHA1.	Opzionale
KDF_SECRET_PREPEND	Valore da aggiungere all'inizio dell'input del messaggio alla funzione hash. Per altre informazioni, vedere Osservazioni.	Opzionale
KDF_SECRET_APPEND	Valore da aggiungere alla fine dell'input del messaggio alla funzione hash. Per altre informazioni, vedere Osservazioni.	Opzionale

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.

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

Parametro	Descrizione	Obbligatorio o facoltativo
KDF_HASH_ALGORITHM	Stringa Unicode con terminazione Null che identifica l'algoritmo hash da usare. Può trattarsi di uno degli identificatori dell'algoritmo hash standard di identificatori dell'algoritmo CNG o dell'identificatore per un altro algoritmo hash registrato. Se questo parametro non viene specificato, viene utilizzato l'algoritmo hash SHA1.	Opzionale
KDF_HMAC_KEY	Chiave da usare per la funzione pseudo-casuale (PRF).	Opzionale
KDF_SECRET_PREPEND	Valore da aggiungere all'inizio dell'input del messaggio alla funzione hash. Per altre informazioni, vedere Osservazioni.	Opzionale
KDF_SECRET_APPEND	Valore da aggiungere alla fine dell'input del messaggio alla funzione hash. Per altre informazioni, vedere Osservazioni.	Opzionale

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.

Parametro	Descrizione	Obbligatorio o facoltativo
KDF_TLS_PRF_LABEL	Stringa ANSI che contiene l'etichetta PRF.	Obbligatorio
KDF_TLS_PRF_SEED	Valore di inizializzazione PRF. Il valore di inizializzazione deve essere lungo 64 byte.	Obbligatorio
KDF_TLS_PRF_PROTOCOL	Valore DWORD che specifica la versione del protocollo TLS il cui algoritmo PRF deve essere usato. I valori validi sono: SSL2_PROTOCOL_VERSION (0x0002) SSL3_PROTOCOL_VERSION (0x0300) TLS1_PROTOCOL_VERSION (0x0301) TLS1_0_PROTOCOL_VERSION (0x0301) TLS1_1_PROTOCOL_VERSION (0x0302) TLS1_2_PROTOCOL_VERSION (0x0303) DTLS1_0_PROTOCOL_VERSION (0xfeff) Windows Server 2008 e Windows Vista: TLS1_1_PROTOCOL_VERSION, TLS1_2_PROTOCOL_VERSION e DTLS1_0_PROTOCOL_VERSION non sono supportati. Windows Server 2008 R2, Windows 7, Windows Server 2008 e Windows Vista: DTLS1_0_PROTOCOL_VERSION non è supportato.	Opzionale
KDF_HASH_ALGORITHM	ID algoritmo CNG dell'hash da usare con HMAC nella richiesta pullF per la versione del protocollo TLS 1.2. Le scelte valide sono SHA-256 e SHA-384. Se non specificato, viene usato SHA-256.	Opzionale

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.

Parametro	Descrizione	Obbligatorio o facoltativo
KDF_ALGORITHMID	Specifica il AlgorithmID sottocampo del campo OtherInfo nella funzione di derivazione della chiave SP800-56A. Indica lo scopo previsto della chiave derivata.	Obbligatorio
KDF_PARTYUINFO	Specifica il campo secondario PartyUInfo del campo OtherInfo nella funzione di derivazione della chiave SP800-56A. Il campo contiene informazioni pubbliche fornite dall'iniziatore.	Obbligatorio
KDF_PARTYVINFO	Specifica il campo secondario PartyVInfo del campo OtherInfo nella funzione di derivazione della chiave SP800-56A. Il campo contiene informazioni pubbliche fornite dal risponditore.	Obbligatorio
KDF_SUPPPUBINFO	Specifica il campo secondario SuppPubInfo del campo OtherInfo nella funzione di derivazione della chiave SP800-56A. Il campo contiene informazioni pubbliche note sia all'iniziatore che al risponditore.	Opzionale
KDF_SUPPPRIVINFO	Specifica il sottocampo SuppPrivInfo del campo OtherInfo nella funzione di derivazione della chiave SP800-56A. Contiene informazioni private note sia all'iniziatore che al risponditore, ad esempio un segreto condiviso.	Opzionale

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.

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	Significato
KDF_USE_SECRET_AS_HMAC_KEY_FLAG	Il valore del contratto segreto fungerà anche da chiave HMAC. Se si specifica questo flag, il parametro KDF_HMAC_KEY non deve essere incluso nel set di parametri nel parametro pParameterList. Questo flag viene usato solo dalla funzione di derivazione della chiave BCRYPT_KDF_HMAC.

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_INTERNAL_ERROR	Si è verificato un errore interno.
STATUS_INVALID_HANDLE	L'handle nel parametro hSharedSecret non è valido.
STATUS_INVALID_PARAMETER	Uno o più parametri non sono validi.

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

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

BCryptSecretAgreement

Condividi tramite

Funzione BCryptDeriveKey (bcrypt.h)

Sintassi

Parametri

BCRYPT_KDF_HASH (L"HASH")

BCRYPT_KDF_HMAC (L"HMAC")

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")

Valore restituito

Osservazioni

Fabbisogno

Vedere anche

Commenti e suggerimenti

Risorse aggiuntive