Función BCryptEncrypt (bcrypt.h)

  • Artículo

La función BCryptEncrypt cifra un bloque de datos.

Sintaxis

NTSTATUS BCryptEncrypt(
  [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 cifrar 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 no cifrado que se va a cifrar. El parámetro cbInput contiene el tamaño del texto no cifrado que se va a cifrar. 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 cifrar.

[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 cifrado. 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 del búfer que recibe el texto 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 BCryptEncrypt calcula el tamaño necesario para el texto cifrado de los datos 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. El parámetro pPaddingInfo no se modifica.

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 la etiqueta de autenticación se devuelve 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 que recibe 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 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
 Permite que el algoritmo de cifrado acolcha los datos al siguiente tamaño de bloque. Si no se especifica esta marca, el tamaño del texto no cifrado especificado en 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.

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 tamaño del texto no cifrado especificado en el parámetro cbInput debe ser un múltiplo del tamaño de bloque del algoritmo.
BCRYPT_PAD_OAEP
 Use el esquema de relleno óptimo de cifrado asimétrico (OAEP). El parámetro pPaddingInfo es un puntero a una estructura BCRYPT_OAEP_PADDING_INFO .
BCRYPT_PAD_PKCS1
 Los datos se rellenarán con un número aleatorio para redondear el tamaño del bloque. 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_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 el BCRYPT_BLOCK_PADDING o la marca BCRYPT_PAD_NONE 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 cifrado.

Comentarios

Los parámetros pbInput y pbOutput pueden ser iguales. En este caso, esta función realizará el cifrado en su lugar. Es posible que el tamaño de los datos cifrados sea mayor que el tamaño de los datos sin cifrar, por lo que el búfer debe ser lo suficientemente grande como para contener los datos cifrados. 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 BCryptEncrypt 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 BCryptEncrypt 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

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

BCryptDecrypt