Compartir a través de


Función NCryptKeyDerivation (ncrypt.h)

La función NCryptKeyDerivation crea una clave a partir de otra clave mediante la función de derivación de claves especificada. La función devuelve la clave en una matriz de bytes.

Sintaxis

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

Parámetros

[in] hKey

Identificador de la clave de la función de derivación de claves (KDF).

[in] pParameterList

Dirección de una estructura NCryptBufferDesc que contiene los parámetros KDF. Los parámetros pueden ser específicos de un KDF o genérico. En la tabla siguiente se muestran los parámetros obligatorios y opcionales para KDF específicos implementados por el proveedor de almacenamiento de claves de software de Microsoft.

KDF Parámetro Obligatorio
SP800-108 HMAC en modo contador 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
 

Se puede usar el siguiente parámetro genérico:

  • KDF_GENERIC_PARAMETER
Los parámetros genéricos se asignan a parámetros específicos de KDF de la siguiente manera:

SP800-108 HMAC en modo contador:

  • 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: el valor predeterminado es 10000

CAPI_KDF

  • KDF_GENERIC_PARAMETER = No usado

[out] pbDerivedKey

Dirección de un búfer que recibe la clave. El parámetro cbDerivedKey contiene el tamaño, en bytes, del búfer de claves.

[in] cbDerivedKey

Tamaño, en bytes, del búfer al que apunta el parámetro pbDerivedKey .

[out] pcbResult

Puntero a un DWORD que recibe el número de bytes copiados en el búfer al que apunta el parámetro pbDerivedKey .

[in] dwFlags

Marcas que modifican el comportamiento de la función. El siguiente valor se puede usar con el proveedor de almacenamiento de claves de software de Microsoft.

Valor Significado
BCRYPT_CAPI_AES_FLAG
Especifica que el algoritmo de destino es AES y que la clave debe expandirse doblemente. Esta marca solo es válida con el algoritmo CAPI_KDF.
NCRYPT_SILENT_FLAG
Solicita que el proveedor de servicios clave (KSP) no muestre ninguna interfaz de usuario. Si el proveedor debe mostrar la interfaz de usuario para funcionar, se produce un error en la llamada y el KSP debe establecer el código de error NTE_SILENT_CONTEXT como último error.

Valor devuelto

Devuelve un código de estado que indica el éxito o error de la función.

Entre los posibles códigos de retorno se incluyen, entre otros, los siguientes.

Código devuelto Descripción
ERROR_SUCCESS
La función se realizó correctamente.
NTE_INVALID_HANDLE
Los identificadores hProvider o hKey no son válidos.
NTE_INVALID_PARAMETER
Los parámetros pwszDerivedKeyAlg y pParameterList no pueden ser NULL.
NTE_NO_MEMORY
No había suficiente memoria para crear la clave.
NTE_NOT_SUPPORTED
El proveedor de almacenamiento de claves no admite esta función.

Comentarios

Puede usar los siguientes identificadores de algoritmo en la función NCryptCreatePersistedKey antes de llamar a NCryptKeyDerivation:

  • BCRYPT_CAPI_KDF_ALGORITHM
  • BCRYPT_SP800108_CTR_HMAC_ALGORITHM
  • BCRYPT_SP80056A_CONCAT_ALGORITHM
  • BCRYPT_PBKDF2_ALGORITHM

Requisitos

Requisito Value
Cliente mínimo compatible Windows 8 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2012 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado ncrypt.h
Library Ncrypt.lib
Archivo DLL Ncrypt.dll

Consulte también

BCryptKeyDerivation

NCryptDeriveKey