Funzione NCryptDeriveKey (ncrypt.h)

La funzione NCryptDeriveKey deriva una chiave da un valore del contratto segreto. Questa funzione deve essere usata come parte di una procedura di contratto segreto usando chiavi del contratto segreto persistenti. Per derivare materiale chiave usando invece un segreto persistente, usare la funzione NCryptKeyDerivation .

Sintassi

SECURITY_STATUS NCryptDeriveKey(
  [in]            NCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  NCryptBufferDesc     *pParameterList,
  [out, optional] PBYTE                pbDerivedKey,
  [in]            DWORD                cbDerivedKey,
  [out]           DWORD                *pcbResult,
  [in]            ULONG                dwFlags
);

Parametri

[in] hSharedSecret

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

[in] pwszKDF

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

BCRYPT_KDF_HASH (L"HASH")

Usare la funzione 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 delle dimensioni della chiave derivata, questa funzione copia la chiave nel buffer pbDerivedKey e imposta la variabile puntata da pcbResult al 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 alla 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 delle dimensioni della chiave derivata, questa funzione copia la chiave nel buffer pbDerivedKey e imposta la variabile puntata da pcbResult al 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 alla 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 pseudo-casuale (PRF) di transport layer security (TLS). Le dimensioni della chiave derivata sono sempre 48 byte, quindi 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 alla 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 derivazione 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.

[in, optional] pParameterList

Indirizzo di una struttura NCryptBufferDesc 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 necessarie, in byte, nel DWORD a cui punta il parametro pcbResult .

[in] cbDerivedKey

Dimensione, in byte, del buffer pbDerivedKey .

[out] pcbResult

Puntatore a un DWORD che riceve il numero di byte copiati nel buffer pbDerivedKey . Se il parametro pbDerivedKey è NULL, questa funzione inserisce le dimensioni richieste, in byte, in DWORD 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, a titolo esemplificativo, quanto segue.

Commenti

La struttura BCryptBufferDesc nel parametro pParameterList può contenere più parametri KDF_SECRET_PREPEND e KDF_SECRET_APPEND . Se viene specificato più di uno di questi parametri, i valori dei parametri vengono concatenati nell'ordine in cui sono contenuti nella matrice prima della chiamata a 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

Un servizio non deve chiamare questa funzione dalla funzione StartService. Se un servizio chiama questa funzione dalla funzione StartService, può verificarsi un deadlock e il servizio potrebbe smettere di rispondere.

Requisiti

Vedi anche

NCryptBufferDesc