Condividi tramite

Funzione NCryptDeriveKey (ncrypt.h)

  • Articolo

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.

Parametro Descrizione Obbligatoria o facoltativa
KDF_HASH_ALGORITHM Stringa Unicode con terminazione null che identifica l'algoritmo hash da usare. Questo può essere uno degli identificatori dell'algoritmo hash standard da Identificatori di algoritmo CNG o l'identificatore per un altro algoritmo hash registrato.

Se questo parametro non è specificato, viene usato l'algoritmo hash SHA1.

 Facoltativo
KDF_SECRET_PREPEND Valore da aggiungere all'inizio dell'input del messaggio alla funzione hash. Per altre informazioni, vedere la sezione Osservazioni. Facoltativo
KDF_SECRET_APPEND Valore da aggiungere alla fine dell'input del messaggio alla funzione hash. Per altre informazioni, vedere la sezione Osservazioni. Facoltativo
 

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.

Parametro Descrizione Obbligatoria o facoltativa
KDF_HASH_ALGORITHM Stringa Unicode con terminazione null che identifica l'algoritmo hash da usare. Questo può essere uno degli identificatori dell'algoritmo hash standard da Identificatori di algoritmo CNG o l'identificatore per un altro algoritmo hash registrato.

Se questo parametro non è specificato, viene usato l'algoritmo hash SHA1.

 Facoltativo
KDF_HMAC_KEY Chiave da usare per la funzione pseudo-casuale (PRF). Facoltativo
KDF_SECRET_PREPEND Valore da aggiungere all'inizio dell'input del messaggio alla funzione hash. Per altre informazioni, vedere la sezione Osservazioni. Facoltativo
KDF_SECRET_APPEND Valore da aggiungere alla fine dell'input del messaggio alla funzione hash. Per altre informazioni, vedere la sezione Osservazioni. Facoltativo
 

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.

Parametro Descrizione Obbligatoria o facoltativa
KDF_TLS_PRF_LABEL Stringa ANSI contenente l'etichetta PRF. Necessario
KDF_TLS_PRF_SEED Seeding PRF. Il valore di inizializzazione deve essere di 64 byte. Necessario
 

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.

Parametro Descrizione Obbligatoria o facoltativa
KDF_ALGORITHMID Specifica il sottocampo AlgorithmID del campo OtherInfo nella funzione di derivazione della chiave SP800-56A. Indica lo scopo previsto della chiave derivata. Necessario
KDF_PARTYUINFO Specifica il sottocampo PartyUInfo del campo OtherInfo nella funzione di derivazione della chiave SP800-56A. Il campo contiene informazioni pubbliche fornite dall'iniziatore. Necessario
KDF_PARTYVINFO Specifica il sottocampo PartyVInfo del campo OtherInfo nella funzione di derivazione della chiave SP800-56A. Il campo contiene informazioni pubbliche fornite dal risponditore. Necessario
KDF_SUPPPUBINFO Specifica il sottocampo SuppPubInfo del campo OtherInfo nella funzione di derivazione della chiave SP800-56A. Il campo contiene informazioni pubbliche note sia all'iniziatore che al risponditore. Facoltativo
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. Facoltativo
 

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 Significato
KDF_USE_SECRET_AS_HMAC_KEY_FLAG
 Il valore del contratto segreto fungerà anche da chiave HMAC. Se questo flag viene specificato, 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, a titolo esemplificativo, quanto segue.

Codice restituito Descrizione
ERROR_SUCCESS
 La funzione ha avuto esito positivo.
NTE_INVALID_HANDLE
 Il parametro hSharedSecret non è valido.
NTE_INVALID_PARAMETER
 Uno o più parametri non sono validi.

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

Requisito Valore
Client minimo supportato Windows Vista [app desktop | App UWP]
Server minimo supportato Windows Server 2008 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione ncrypt.h
Libreria Ncrypt.lib
DLL Ncrypt.dll

Vedi anche

NCryptBufferDesc