Condividi tramite


Funzione NCryptKeyDerivation (ncrypt.h)

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
KDF_CONTEXT
KDF_HASH_ALGORITHM
SP800-56A KDF_ALGORITHMID
KDF_PARTYUINFO
KDF_PARTYVINFO
KDF_HASH_ALGORITHM
KDF_SUPPPUBINFO no
KDF_SUPPPRIVINFO no
PBKDF2 KDF_HASH_ALGORITHM
KDF_SALT
KDF_ITERATION_COUNT no
CAPI_KDF KDF_HASH_ALGORITHM
 

È 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