Función CryptEncrypt (wincrypt.h)

Artículo
07/16/2024

importante Esta API está en desuso. El software nuevo y existente debe empezar a usar las API de Cryptography Next Generation. Microsoft puede quitar esta API en futuras versiones.

La función CryptEncrypt cifra los datos. El algoritmo usado para cifrar los datos se designa mediante la clave que mantiene el módulo CSP y se hace referencia a ellos mediante el parámetro hKey .

Se han realizado cambios importantes para admitir interoperabilidad de correo electrónico seguro/multipropósito de extensiones de correo electrónico (S/MIME) en CryptoAPI que afectan al control de mensajes sobres. Para obtener más información, vea la sección Comentarios de CryptMsgOpenToEncode.

Importante La función CryptEncrypt no está garantizada para ser segura para subprocesos y puede devolver resultados incorrectos si se invocan simultáneamente por varios autores de llamada.

Sintaxis

BOOL CryptEncrypt(
  [in]      HCRYPTKEY  hKey,
  [in]      HCRYPTHASH hHash,
  [in]      BOOL       Final,
  [in]      DWORD      dwFlags,
  [in, out] BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwBufLen
);

Parámetros

[in] hKey

Identificador de la clave de cifrado. Una aplicación obtiene este identificador mediante la de CryptGenKey o la función CryptImportKey de .

La clave especifica el algoritmo de cifrado utilizado.

[in] hHash

Identificador de un objeto hash de . Si los datos se van a aplicar hash y cifrar simultáneamente, se puede pasar un identificador a un objeto hash en el parámetro hHash. El valor hash se actualiza con el texto no cifrado pasado. Esta opción es útil al generar texto firmado y cifrado.

Antes de llamar a CryptEncrypt, la aplicación debe obtener un identificador para el objeto hash llamando a la función CryptCreateHash. Una vez completado el cifrado, el valor hash se puede obtener mediante la función CryptGetHashParam o el hash se puede firmar mediante la función CryptSignHash.

Si no se va a realizar ningún hash, este parámetro debe ser NULL.

[in] Final

Valor booleano que especifica si se trata de la última sección de una serie que se está cifrando. Final se establece en TRUE para el último bloque o solo para FALSE si hay más bloques que se van a cifrar. Para obtener más información, vea Comentarios.

[in] dwFlags

Se define el siguiente valor dwFlags, pero está reservado para uso futuro.

Valor	Significado
CRYPT_OAEP	Use el relleno óptimo de cifrado asimétrico (OAEP) (PKCS #1 versión 2). Esta marca solo es compatible con el proveedor criptográfico mejorado de Microsoft con cifrado y descifrado RSA.

[in, out] pbData

Puntero a un búfer que contiene el texto no cifrado que se va a cifrar. El texto no cifrado de este búfer se sobrescribe con el texto cifrado creado por esta función.

El parámetro pdwDataLen apunta a una variable que contiene la longitud, en bytes, del texto no cifrado. El parámetro dwBufLen contiene el tamaño total, en bytes, de este búfer.

Si este parámetro contiene NULL, esta función calculará el tamaño necesario para el texto cifrado y colocará el valor al que apunta el parámetro pdwDataLen.

[in, out] pdwDataLen

Puntero a un valor D WORD que , en la entrada, contiene la longitud, en bytes, del texto sin formato en el búfer de pbData. Al salir, este DWORD contiene la longitud, en bytes, del texto cifrado escrito en el búfer de pbData de .

Si el búfer asignado para pbData no es lo suficientemente grande como para contener los datos cifrados, GetLastError devuelve ERROR_MORE_DATA y almacena el tamaño de búfer necesario, en bytes, en el valor de DWORD apuntado por pdwDataLen.

Si pbData es null, no se devuelve ningún error y la función almacena el tamaño de los datos cifrados, en bytes, en el valor de DWORD al que apunta pdwDataLen. Esto permite a una aplicación determinar el tamaño correcto del búfer.

Cuando se usa un de cifrado de bloques de , esta longitud de datos debe ser un múltiplo del tamaño del bloque a menos que se cifre la sección final de los datos y el parámetro Final sea TRUE.

[in] dwBufLen

Especifica el tamaño total, en bytes, del búfer de pbData de entrada.

Tenga en cuenta que, dependiendo del algoritmo utilizado, el texto cifrado puede ser mayor que el texto sin formato original. En este caso, el pbData búfer debe ser lo suficientemente grande como para contener el texto cifrado y cualquier relleno.

Como regla, si se usa un cifrado de flujo, el texto cifrado tiene el mismo tamaño que el texto sin formato. Si se usa un de cifrado de bloques de , el texto cifrado es hasta una longitud de bloque mayor que el texto no cifrado.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero (TRUE).

Si se produce un error en la función, devuelve cero (FALSE). Para obtener información de error extendida, llame a GetLastError.

Los códigos de error precedidos por NTE se generan mediante el CSP en particular que se usa. A continuación se indican algunos códigos de error posibles.

Valor	Descripción
ERROR_INVALID_HANDLE	Uno de los parámetros especifica un identificador que no es válido.
ERROR_INVALID_PARAMETER	Uno de los parámetros contiene un valor que no es válido. Suele ser un puntero que no es válido.
NTE_BAD_ALGID	El de clave de sesión hKeyespecifica un algoritmo que este CSP no admite.
NTE_BAD_DATA	Los datos que se van a cifrar no son válidos. Por ejemplo, cuando se usa un cifrado de bloque y la marca Final es FALSE, el valor especificado por pdwDataLen debe ser un múltiplo del tamaño del bloque.
NTE_BAD_FLAGS	El parámetro dwFlags es distinto de cero.
NTE_BAD_HASH	El parámetro hHash contiene un identificador que no es válido.
NTE_BAD_HASH_STATE	Se intentó agregar datos a un objeto hash que ya está marcado como "finalizado".
NTE_BAD_KEY	El parámetro hKey no contiene un identificador válido para una clave.
NTE_BAD_LEN	El tamaño del búfer de salida es demasiado pequeño para contener el texto cifrado generado.
NTE_BAD_UID	No se encuentra el contexto de CSP que se especificó cuando se creó la clave.
NTE_DOUBLE_ENCRYPT	La aplicación intentó cifrar los mismos datos dos veces.
NTE_FAIL	Error en la función de alguna manera inesperada.
NTE_NO_MEMORY	El CSP se quedó sin memoria durante la operación.

Observaciones

Si se va a cifrar una gran cantidad de datos, se puede realizar en secciones llamando a CryptEncrypt repetidamente. El parámetro Final debe establecerse en TRUE en la última llamada a CryptEncrypt, para que el motor de cifrado pueda finalizar correctamente el proceso de cifrado. Las siguientes acciones adicionales se realizan cuando final es TRUE:

Si la clave es una clave de cifrado de bloque, los datos se rellenan en un múltiplo del tamaño del bloque del cifrado. Si la longitud de los datos es igual al tamaño de bloque del cifrado, se anexa un bloque adicional de relleno a los datos. Para buscar el tamaño de bloque de un cifrado, use CryptGetKeyParam para obtener el valor KP_BLOCKLEN de la clave.
Si el cifrado funciona en un modo de encadenamiento de , la siguiente operación CryptEncrypt restablece el registro de comentarios del cifrado al valor KP_IV de la clave.
Si el cifrado es unde cifrado de flujo de , el siguiente CryptEncrypt restablece el cifrado a su estado de inicial.

No hay ninguna manera de establecer el registro de comentarios del cifrado en el valor de KP_IV de la clave sin establecer el parámetro Final en TRUE. Si esto es necesario, como en el caso de que no desee agregar un bloque de relleno adicional o cambiar el tamaño de cada bloque, puede simularlo creando un duplicado de la clave original mediante la función CryptDuplicateKey y pasando la clave duplicada a la función CryptEncrypt. Esto hace que la KP_IV de la clave original se coloque en la clave duplicada. Después de crear o importar la clave original, no puede usar la clave original para el cifrado porque se cambiará el registro de comentarios de la clave. El pseudocódigo siguiente muestra cómo se puede hacer esto.

// Set the IV for the original key. Do not use the original key for 
// encryption or decryption after doing this because the key's 
// feedback register will get modified and you cannot change it.
CryptSetKeyParam(hOriginalKey, KP_IV, newIV)

while(block = NextBlock())
{
    // Create a duplicate of the original key. This causes the 
    // original key's IV to be copied into the duplicate key's 
    // feedback register.
    hDuplicateKey = CryptDuplicateKey(hOriginalKey)

    // Encrypt the block with the duplicate key.
    CryptEncrypt(hDuplicateKey, block)

    // Destroy the duplicate key. Its feedback register has been 
    // modified by the CryptEncrypt function, so it cannot be used
    // again. It will be re-duplicated in the next iteration of the 
    // loop.
    CryptDestroyKey(hDuplicateKey)
}

El proveedor de servicios criptográficos mejorado de Microsoft admite el cifrado directo con RSAclaves públicas y descifrado con claves privadas de RSA . El cifrado usa el relleno PKCS #1 . En el descifrado, se comprueba este relleno. La longitud de los datos de texto no cifrado que se pueden cifrar con una llamada a CryptEncrypt con una clave RSA es la longitud del módulo de clave menos once bytes. Los once bytes son el mínimo elegido para el relleno PKCS #1. El texto cifrado se devuelve en formato little-endian.

Ejemplos

Para obtener ejemplos que usan esta función, vea Programa C de ejemplo: Cifrado de un archivo y Programa C de ejemplo: Descifrado de un archivo.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	wincrypt.h
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll