Función NCryptKeyDerivation (ncrypt.h)

  • Artículo

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 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í
 

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