Función BCryptDeriveKey (bcrypt.h)
La función BCryptDeriveKey deriva una clave de un valor de acuerdo secreto.
Para obtener la derivación de claves de un secreto determinado, 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 contrato 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 . 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 |
| KDF_TLS_PRF_PROTOCOL |
Valor DWORD que especifica la versión del protocolo TLS cuyo algoritmo PRF se va a usar.
Los valores válidos son:
Windows Server 2008 y Windows Vista: no se admiten TLS1_1_PROTOCOL_VERSION, TLS1_2_PROTOCOL_VERSION y DTLS1_0_PROTOCOL_VERSION. Windows Server 2008 R2, Windows 7, Windows Server 2008 y Windows Vista: no se admite DTLS1_0_PROTOCOL_VERSION. |
Opcionales |
| KDF_HASH_ALGORITHM | Identificador del algoritmo CNG del hash que se va a usar con el HMAC en el PRF, para la versión del protocolo TLS 1.2. Las opciones válidas son SHA-256 y SHA-384. Si no se especifica, se usa SHA-256. | Opcionales |
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.
BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")
Devuelve la representación little-endian del secreto sin procesar sin ninguna modificación.
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.
Windows 8, Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: este valor no se admite.
[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 el ULONG 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 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.
| Código devuelto | Descripción |
|---|---|
|
La función se realizó correctamente. |
|
Se ha producido un error interno. |
|
El identificador del parámetro hSharedSecret no es válido. |
|
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
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 CNG, ya que la mayoría de ellos toman entradas codificadas en big-endian.
En función de los modos de procesador que admita un proveedor, 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
| 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 | bcrypt.h |
| Library | Bcrypt.lib |
| Archivo DLL | Bcrypt.dll |
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de