Función NCryptDeriveKey (ncrypt.h)

  • Artículo

La función NCryptDeriveKey deriva una clave de un valor de acuerdo secreto. Esta función está pensada para usarse como parte de un procedimiento de acuerdo secreto mediante claves de contrato secreta persistentes. Para derivar material de clave mediante un secreto persistente en su lugar, use la función NCryptKeyDerivation .

Sintaxis

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
);

Parámetros

[in] hSharedSecret

Identificador del contrato secreto desde el que se va a crear la clave. Este identificador se obtiene de la función NCryptSecretAgreement .

[in] pwszKDF

Puntero a una cadena Unicode terminada en null que identifica la función de derivación de claves (KDF) que se va a usar para derivar la clave. Puede ser una de las siguientes cadenas.

BCRYPT_KDF_HASH (L"HASH")

Use la función de derivación de clave hash.

Si el parámetro cbDerivedKey es menor que el tamaño de la clave derivada, esta función solo copiará el número especificado de bytes en el búfer pbDerivedKey . Si el parámetro cbDerivedKey es mayor que el tamaño de la clave derivada, esta función copiará la clave en el búfer pbDerivedKey y establecerá la variable a la que apunta el pcbResult en el número real de bytes copiados.

Los parámetros identificados por el parámetro pParameterList pueden o deben contener los parámetros siguientes, como se indica en la columna Requerida o opcional.

Parámetro Descripción Obligatorio u opcional
KDF_HASH_ALGORITHM Cadena Unicode terminada en null que identifica el algoritmo hash que se va a usar. Puede ser uno de los identificadores de algoritmo hash estándar de identificadores de algoritmo CNG o el identificador de otro algoritmo hash registrado.

Si no se especifica este parámetro, se usa el algoritmo hash SHA1.

 Opcionales
KDF_SECRET_PREPEND Valor que se va a agregar al principio de la entrada del mensaje a la función hash. Para obtener más información, vea la sección Comentarios. Opcionales
KDF_SECRET_APPEND Valor que se va a agregar al final de la entrada del mensaje a la función hash. Para obtener más información, vea la sección Comentarios. Opcionales
 

La llamada a KDF se realiza como se muestra en el pseudocódigo siguiente.

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")

Use la función de derivación de claves de código de autenticación de mensajes basado en hash (HMAC).

Si el parámetro cbDerivedKey es menor que el tamaño de la clave derivada, esta función solo copiará el número especificado de bytes en el búfer pbDerivedKey . Si el parámetro cbDerivedKey es mayor que el tamaño de la clave derivada, esta función copiará la clave en el búfer pbDerivedKey y establecerá la variable a la que apunta el pcbResult en el número real de bytes copiados.

Los parámetros identificados por el parámetro pParameterList pueden o deben contener los parámetros siguientes, como se indica en la columna Requerida o opcional.

Parámetro Descripción Obligatorio u opcional
KDF_HASH_ALGORITHM Cadena Unicode terminada en null que identifica el algoritmo hash que se va a usar. Puede ser uno de los identificadores de algoritmo hash estándar de identificadores de algoritmo CNG o el identificador de otro algoritmo hash registrado.

Si no se especifica este parámetro, se usa el algoritmo hash SHA1.

 Opcionales
KDF_HMAC_KEY Clave que se va a usar para la función pseudoaleatoria (PRF). Opcionales
KDF_SECRET_PREPEND Valor que se va a agregar al principio de la entrada del mensaje a la función hash. Para obtener más información, vea la sección Comentarios. Opcionales
KDF_SECRET_APPEND Valor que se va a agregar al final de la entrada del mensaje a la función hash. Para obtener más información, vea la sección Comentarios. Opcionales
 

La llamada a KDF se realiza como se muestra en el pseudocódigo siguiente.

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")

Use la función de derivación de claves de la función pseudoaleatoria de seguridad de la capa de transporte (TLS). El tamaño de la clave derivada siempre es de 48 bytes, por lo que el parámetro cbDerivedKey debe ser 48.

Los parámetros identificados por el parámetro pParameterList pueden o deben contener los parámetros siguientes, como se indica en la columna Requerida o opcional.

Parámetro Descripción Obligatorio u opcional
KDF_TLS_PRF_LABEL Cadena ANSI que contiene la etiqueta PRF. Requerido
KDF_TLS_PRF_SEED Inicialización del PRF. La inicialización debe tener 64 bytes de longitud. Requerido
 

La llamada a KDF se realiza como se muestra en el pseudocódigo siguiente.

KDF-Output = PRF(
    hSharedSecret, 
    KDF_TLS_PRF_LABEL, 
    KDF_TLS_PRF_SEED)

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

Use la función de derivación de claves SP800-56A.

Los parámetros identificados por el parámetro pParameterList pueden o deben contener los parámetros siguientes, como se indica en la columna Requerida o opcional. Todos los valores de parámetro se tratan como matrices de bytes opacos.

Parámetro Descripción Obligatorio u opcional
KDF_ALGORITHMID Especifica el subcampo AlgorithmID del campo OtherInfo de la función de derivación de claves SP800-56A. Indica el propósito previsto de la clave derivada. Requerido
KDF_PARTYUINFO Especifica el subcampo PartyUInfo del campo OtherInfo en la función de derivación de claves SP800-56A. El campo contiene información pública aportada por el iniciador. Requerido
KDF_PARTYVINFO Especifica el subcampo PartyVInfo del campo OtherInfo en la función de derivación de claves SP800-56A. El campo contiene información pública aportada por el respondedor. Requerido
KDF_SUPPPUBINFO Especifica el subcampo SuppPubInfo del campo OtherInfo en la función de derivación de claves SP800-56A. El campo contiene información pública conocida tanto para el iniciador como para el respondedor. Opcionales
KDF_SUPPPRIVINFO Especifica el subcampo SuppPrivInfo del campo OtherInfo en la función de derivación de claves SP800-56A. Contiene información privada conocida tanto para el iniciador como para el respondedor, como un secreto compartido. Opcionales
 

La llamada a KDF se realiza como se muestra en el pseudocódigo siguiente.

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 y Windows XP: Este valor no se admite.

[in, optional] pParameterList

Dirección de una estructura NCryptBufferDesc que contiene los parámetros KDF. Este parámetro es opcional y puede ser NULL si no es necesario.

[out, optional] pbDerivedKey

Dirección de un búfer que recibe la clave. El parámetro cbDerivedKey contiene el tamaño de este búfer. Si este parámetro es NULL, esta función colocará el tamaño necesario, en bytes, en el DWORD al que apunta el parámetro pcbResult .

[in] cbDerivedKey

Tamaño, en bytes, del búfer pbDerivedKey .

[out] pcbResult

Puntero a un DWORD que recibe el número de bytes que se copiaron en el búfer pbDerivedKey . Si el parámetro pbDerivedKey es NULL, esta función colocará el tamaño necesario, en bytes, en el DWORD al que apunta este parámetro.

[in] dwFlags

Conjunto de marcas que modifican el comportamiento de esta función. Puede ser cero o el valor siguiente.

Valor Significado
KDF_USE_SECRET_AS_HMAC_KEY_FLAG
 El valor del contrato secreto también servirá como clave HMAC. Si se especifica esta marca, el parámetro KDF_HMAC_KEY no debe incluirse en el conjunto de parámetros del parámetro pParameterList . Esta marca solo la usa la función de derivación de claves BCRYPT_KDF_HMAC .

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
 El parámetro hSharedSecret no es válido.
NTE_INVALID_PARAMETER
 Uno o más parámetros no son válidos.

Comentarios

La estructura BCryptBufferDesc del parámetro pParameterList puede contener más de uno de los parámetros KDF_SECRET_PREPEND y KDF_SECRET_APPEND . Si se especifica más de uno de estos parámetros, los valores de parámetro se concatenan en el orden en que se encuentran en la matriz antes de llamar a KDF. Por ejemplo, suponga que se especifican los siguientes valores de parámetro.

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);

Si se especifican los valores de parámetro anteriores, los valores concatenados en la KDF real son los siguientes.

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 servicio no debe llamar a esta función desde su función StartService. Si un servicio llama a esta función desde su función StartService, se puede producir un interbloqueo y el servicio puede dejar de responder.

Requisitos

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

Consulte también

NCryptBufferDesc