Función BCryptDecrypt (bcrypt.h)

  • Artículo

La función BCryptDecrypt descifra un bloque de datos.

Sintaxis

NTSTATUS BCryptDecrypt(
  [in, out]           BCRYPT_KEY_HANDLE hKey,
  [in]                PUCHAR            pbInput,
  [in]                ULONG             cbInput,
  [in, optional]      VOID              *pPaddingInfo,
  [in, out, optional] PUCHAR            pbIV,
  [in]                ULONG             cbIV,
  [out, optional]     PUCHAR            pbOutput,
  [in]                ULONG             cbOutput,
  [out]               ULONG             *pcbResult,
  [in]                ULONG             dwFlags
);

Parámetros

[in, out] hKey

Identificador de la clave que se va a usar para descifrar los datos. Este identificador se obtiene de una de las funciones de creación de claves, como BCryptGenerateSymmetricKey, BCryptGenerateKeyPair o BCryptImportKey.

[in] pbInput

Dirección de un búfer que contiene el texto cifrado que se va a descifrar. El parámetro cbInput contiene el tamaño del texto cifrado que se va a descifrar. Para obtener más información, vea la sección Comentarios.

[in] cbInput

Número de bytes del búfer pbInput que se va a descifrar.

[in, optional] pPaddingInfo

Puntero a una estructura que contiene información de relleno. Este parámetro solo se usa con claves asimétricas y modos de cifrado autenticados. Si se usa un modo de cifrado autenticado, este parámetro debe apuntar a una estructura de BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO . Si se usan claves asimétricas, el tipo de estructura a la que apunta este parámetro viene determinado por el valor del parámetro dwFlags . De lo contrario, el parámetro debe establecerse en NULL.

[in, out, optional] pbIV

Dirección de un búfer que contiene el vector de inicialización (IV) que se va a usar durante el descifrado. El parámetro cbIV contiene el tamaño de este búfer. Esta función modificará el contenido de este búfer. Si necesita volver a usar el IV más adelante, asegúrese de realizar una copia de este búfer antes de llamar a esta función.

Este parámetro es opcional y puede ser NULL si no se usa ningún IV.

El tamaño necesario del IV se puede obtener llamando a la función BCryptGetProperty para obtener la propiedad BCRYPT_BLOCK_LENGTH . Esto proporcionará el tamaño de un bloque para el algoritmo, que también es el tamaño del IV.

[in] cbIV

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

[out, optional] pbOutput

Dirección de un búfer para recibir el texto no cifrado generado por esta función. El parámetro cbOutput contiene el tamaño de este búfer. Para obtener más información, vea la sección Comentarios.

Si este parámetro es NULL, la función BCryptDecrypt calcula el tamaño necesario para el texto no cifrado de los datos cifrados pasados en el parámetro pbInput . En este caso, la ubicación a la que apunta el parámetro pcbResult contiene este tamaño y la función devuelve STATUS_SUCCESS.

Si los valores de los parámetros pbOutput y pbInput son NULL, se devuelve un error a menos que se use un algoritmo de cifrado autenticado. En este último caso, la llamada se trata como una llamada de cifrado autenticada con datos de longitud cero y se comprueba la etiqueta de autenticación, pasada en el parámetro pPaddingInfo .

[in] cbOutput

Tamaño, en bytes, del búfer pbOutput . Este parámetro se omite si el parámetro pbOutput es NULL.

[out] pcbResult

Puntero a una variable ULONG para recibir el número de bytes copiados en el búfer pbOutput . Si pbOutput es NULL, recibe el tamaño, en bytes, necesario para el texto no cifrado.

[in] dwFlags

Conjunto de marcas que modifican el comportamiento de esta función. El conjunto permitido de marcas depende del tipo de clave especificado por el parámetro hKey .

Si la clave es una clave simétrica, puede ser cero o el valor siguiente.

Valor Significado
BCRYPT_BLOCK_PADDING
 Los datos se rellenaron en el siguiente tamaño de bloque cuando se cifró. Si esta marca se usó con la función BCryptEncrypt , también debe especificarse en esta función. Esta marca no se debe usar con los modos de cifrado autenticados (AES-CCM y AES-GCM).
 

Si la clave es una clave asimétrica, puede ser uno de los siguientes valores.

Valor Significado
BCRYPT_PAD_NONE
 No use ningún relleno. No se usa el parámetro pPaddingInfo . El parámetro cbInput debe ser un múltiplo del tamaño de bloque del algoritmo.

El tamaño del bloque se puede obtener llamando a la función BCryptGetProperty para obtener la propiedad BCRYPT_BLOCK_LENGTH de la clave. Esto proporcionará el tamaño de un bloque para el algoritmo.
BCRYPT_PAD_OAEP
 El esquema de relleno óptimo de cifrado asimétrico (OAEP) se usó cuando se cifraron los datos. El parámetro pPaddingInfo es un puntero a una estructura BCRYPT_OAEP_PADDING_INFO .
BCRYPT_PAD_PKCS1
 Los datos se rellenaron con un número aleatorio cuando los datos se cifraron. No se usa el parámetro pPaddingInfo .

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
STATUS_SUCCESS
 La función se realizó correctamente.
STATUS_AUTH_TAG_MISMATCH
 La etiqueta de autenticación calculada no coincide con el valor proporcionado en el parámetro pPaddingInfo .
STATUS_BUFFER_TOO_SMALL
 El tamaño especificado por el parámetro cbOutput no es lo suficientemente grande como para contener el texto cifrado.
STATUS_INVALID_BUFFER_SIZE
 El parámetro cbInput no es un múltiplo del tamaño de bloque del algoritmo y la marca BCRYPT_BLOCK_PADDING no se especificó en el parámetro dwFlags .
STATUS_INVALID_HANDLE
 El identificador de clave del parámetro hKey no es válido.
STATUS_INVALID_PARAMETER
 Uno o más parámetros no son válidos.
STATUS_NOT_SUPPORTED
 El algoritmo no admite el descifrado.

Comentarios

Los parámetros pbInput y pbOutput pueden ser iguales. En este caso, esta función realizará el descifrado en su lugar. Si pbInput y pbOutput no son iguales, es posible que los dos búferes no se superpongan.

En función de los modos de procesador que admita un proveedor, se puede llamar a BCryptDecrypt 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 hKey debe derivarse de un identificador de algoritmo devuelto por un proveedor que se abrió con la marca BCRYPT_PROV_DISPATCH y los punteros pasados a la función BCryptDecrypt deben hacer referencia a la memoria no paginada (o bloqueada).

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

   
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

BCryptEncrypt