Funzione NCryptKeyDerivation (ncrypt.h)

Articolo
02/29/2024

La funzione NCryptKeyDerivation crea una chiave da un'altra chiave usando la funzione di derivazione della chiave specificata. La funzione restituisce la chiave in una matrice di byte.

Sintassi

SECURITY_STATUS NCryptKeyDerivation(
  [in]  NCRYPT_KEY_HANDLE hKey,
  [in]  NCryptBufferDesc  *pParameterList,
  [out] PUCHAR            pbDerivedKey,
  [in]  DWORD             cbDerivedKey,
  [out] DWORD             *pcbResult,
  [in]  ULONG             dwFlags
);

Parametri

[in] hKey

Handle della chiave di derivazione della chiave (KDF).

[in] pParameterList

Indirizzo di una struttura NCryptBufferDesc che contiene i parametri KDF. I parametri possono essere specifici di una funzione KDF o generica. La tabella seguente illustra i parametri obbligatori e facoltativi per KDF specifici implementati dal provider di archiviazione chiavi software Microsoft.

KDF	Parametro	Obbligatoria
SP800-108 HMAC in modalità contatore	KDF_LABEL	sì
	KDF_CONTEXT	Sì
	KDF_HASH_ALGORITHM	sì
SP800-56A	KDF_ALGORITHMID	sì
	KDF_PARTYUINFO	sì
	KDF_PARTYVINFO	sì
	KDF_HASH_ALGORITHM	Sì
	KDF_SUPPPUBINFO	no
	KDF_SUPPPRIVINFO	no
PBKDF2	KDF_HASH_ALGORITHM	Sì
	KDF_SALT	sì
	KDF_ITERATION_COUNT	no
CAPI_KDF	KDF_HASH_ALGORITHM	sì

È possibile usare il parametro generico seguente:

KDF_GENERIC_PARAMETER

I parametri generici eseguono il mapping a parametri specifici di KDF nel modo seguente:

SP800-108 HMAC in modalità contatore:

KDF_GENERIC_PARAMETER = KDF_LABEL||0x00||KDF_CONTEXT

SP800-56A

KDF_GENERIC_PARAMETER = KDF_ALGORITHMID || KDF_PARTYUINFO || KDF_PARTYVINFO {|| KDF_SUPPPUBINFO } {|| KDF_SUPPPRIVINFO }

PBKDF2

KDF_GENERIC_PARAMETER = KDF_SALT
KDF_ITERATION_COUNT: il valore predefinito è 10000

CAPI_KDF

KDF_GENERIC_PARAMETER = Non usato

[out] pbDerivedKey

Indirizzo di un buffer che riceve la chiave. Il parametro cbDerivedKey contiene le dimensioni, in byte, del buffer della chiave.

[in] cbDerivedKey

Dimensioni, in byte, del buffer a cui punta il parametro pbDerivedKey .

[out] pcbResult

Puntatore a un DWORD che riceve il numero di byte copiati nel buffer a cui punta il parametro pbDerivedKey .

[in] dwFlags

Flag che modificano il comportamento della funzione. Il valore seguente può essere usato con il provider di archiviazione chiavi software Microsoft.

Valore	Significato
BCRYPT_CAPI_AES_FLAG	Specifica che l'algoritmo di destinazione è AES e che la chiave deve quindi essere espansa doppia. Questo flag è valido solo con l'algoritmo CAPI_KDF.
NCRYPT_SILENT_FLAG	Richiede che il provider di servizi chiave (KSP) non visualizzi alcuna interfaccia utente. Se il provider deve visualizzare l'interfaccia utente per il funzionamento, la chiamata ha esito negativo e il provider di servizi di configurazione deve impostare il codice di errore NTE_SILENT_CONTEXT come ultimo errore.

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	Gli handle hProvider o hKey non sono validi.
NTE_INVALID_PARAMETER	I parametri pwszDerivedKeyAlg e pParameterList non possono essere NULL.
NTE_NO_MEMORY	Memoria insufficiente per creare la chiave.
NTE_NOT_SUPPORTED	Questa funzione non è supportata dal provider di archiviazione delle chiavi.

Commenti

È possibile usare gli identificatori di algoritmo seguenti nella funzione NCryptCreatePersistedKey prima di chiamare NCryptKeyDerivation:

BCRYPT_CAPI_KDF_ALGORITHM
BCRYPT_SP800108_CTR_HMAC_ALGORITHM
BCRYPT_SP80056A_CONCAT_ALGORITHM
BCRYPT_PBKDF2_ALGORITHM

Requisiti

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

Vedi anche

BCryptKeyDerivation

NCryptDeriveKey

Condividi tramite