Función BCryptDeriveKey (bcrypt.h)

La función BCryptDeriveKey deriva una clave de un BCRYPT_SECRET_HANDLE. Normalmente, esto se hace como parte de un procedimiento de acuerdo secreto.

Para obtener la derivación de claves de un secreto proporcionado directamente por el autor de la llamada, consulte BCryptKeyDerivation.

Sintaxis

NTSTATUS BCryptDeriveKey(
  [in]            BCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  BCryptBufferDesc     *pParameterList,
  [out, optional] PUCHAR               pbDerivedKey,
  [in]            ULONG                cbDerivedKey,
  [out]           ULONG                *pcbResult,
  [in]            ULONG                dwFlags
);

Parámetros

[in] hSharedSecret

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

[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 . Esto suele ser una práctica incorrecta, ya que puede reducir significativamente la seguridad de la clave resultante.

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 contener o deben contener los parámetros siguientes, como se indica en la columna Requerida o opcional.

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

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 (HMAC)Hash-Based.

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 . Esto suele ser una práctica incorrecta, ya que puede reducir significativamente la seguridad de la clave resultante.

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 contener o deben contener los parámetros siguientes, como se indica en la columna Requerida o opcional.

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

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 contener o deben contener los parámetros siguientes, como se indica en la columna Requerida o opcional.

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. Esto también se conoce como SP800-56C rev2 KDF de un paso.

KDF toma una función hash aprobada como parámetro, pero esta API elige internamente la función hash, que coincide con la seguridad del algoritmo hash que se usa para generar el identificador de secreto. (es decir, ECDH P-256 usa SHA256, ECDH P-384 usa SHA384)

Los parámetros identificados por el parámetro pParameterList pueden contener 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 opacas.

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.

BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")

Devuelve la representación little-endian del secreto sin procesar sin ninguna modificación. El uso de esta opción suele ser un procedimiento incorrecto, pero puede ser necesario si necesita interoperar con una KDF no admitida.

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 . Esto suele ser una práctica incorrecta, ya que puede reducir significativamente la seguridad de la clave resultante.

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.

Windows 8, Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este valor no se admite.

BCRYPT_KDF_HKDF (L"HKDF")

Use la función HKDF (HMAC-based Extract-and-Expand KDF) de RFC 5869.

En HKDF, se hace una distinción entre derivar una clave de cualquiera de las siguientes:

1. La salida de una función de acuerdo secreto, que no es aleatoria uniformemente, y se considera material de clave de entrada (IKM). Casi todos los usuarios de BCryptDeriveKey tendrán un identificador secreto de este formulario.
2. Valor secreto uniformemente aleatorio.

El primer paso es "Extraer" una clave pseudoaleatoria (PRK) del identificador secreto.

Este paso se realiza mediante una llamada a BCryptSetProperty en un identificador secreto con BCRYPT_HKDF_HASH_ALGORITHM para establecer el algoritmo hash que se usará en los cálculos HMAC en HKDF. Esto va seguido de una segunda llamada a BCryptSetProperty con una de las siguientes:

1. Si el identificador secreto representa IKM, use BCRYPT_HKDF_SALT_AND_FINALIZE para proporcionar el valor de sal opcional y extraer el PRK del IKM y finalizar el identificador del secreto.
2. De lo contrario, use BCRYPT_HKDF_PRK_AND_FINALIZE para transformar directamente el valor del secreto en el PRK de HKDF y finalizar el identificador del secreto.

El segundo paso consiste en "Expandir" el PRK en una clave derivada de salida.

Este paso se realiza llamando a BCryptDeriveKey en un identificador de secreto finalizado.

Los parámetros identificados por el parámetro pParameterList pueden contener 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 opacas.

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

KDF-Output = HKDF-Expand(
    hSharedSecret.PRK,
    info,
    cbDerivedKey)

Windows 10: Comienza la compatibilidad con HKDF.

[in, optional] pParameterList

Dirección de una estructura BCryptBufferDesc 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 ULONG al que apunta el parámetro pcbResult .

[in] cbDerivedKey

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

[out] pcbResult

Puntero a un ULONG 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 la ULONG a la que apunta este parámetro.

[in] dwFlags

Conjunto de marcas que modifican el comportamiento de esta función.

Puede ser cero o el siguiente valor:

Valor devuelto

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

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

Observaciones

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 abValue0[] = {0x01};
BYTE abValue1[] = {0x04, 0x05};
BYTE abValue2[] = {0x10, 0x11, 0x12};
BYTE abValue3[] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = abValue0;
Parameter[0].length = sizeof (abValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = abValue1;
Parameter[1].length = sizeof (abValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = abValue2;
Parameter[2].length = sizeof (abValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = abValue3;
Parameter[3].length = sizeof (abValue3);

Si se especifican los valores de parámetro anteriores, los valores concatenados a 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

Si el parámetro pwszKDF se establece en BCRYPT_KDF_RAW_SECRET, el secreto devuelto (a diferencia de los demás valores pwszKDF ) se codificará en formato little-endian. Es importante tener en cuenta esto al usar el secreto sin procesar en cualquier otra función de CNG, ya que la mayoría de ellas toman entradas codificadas en big-endian.

Cuando se usa un proveedor de algoritmos compatible, se puede llamar a BCryptDeriveKey desde el modo de usuario o el modo kernel. Los autores de llamadas en modo kernel se pueden ejecutar en PASSIVE_LEVELIRQL o DISPATCH_LEVEL IRQL. Si el nivel IRQL actual es DISPATCH_LEVEL, el identificador proporcionado en el parámetro hSharedSecret debe encontrarse en memoria no paginada (o bloqueada) y debe derivarse de un identificador de algoritmo devuelto por un proveedor que se abrió mediante la marca BCRYPT_PROV_DISPATCH .

Para llamar a esta función en modo kernel, use Cng.lib, que forma parte del Kit de desarrollo de controladores (DDK). Windows Server 2008 y Windows Vista: Para llamar a esta función en modo kernel, use Ksecdd.lib.

Requisitos

Consulte también

BCryptBufferDesc

BCryptSecretAgreement