Función CryptEncrypt (wincrypt.h)

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.

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.

[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.

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

Consulte también

CryptCreateHash

CryptDecrypt

CryptGenKey

CryptGetHashParam

CryptGetKeyParam

CryptImportKey

CryptMsgOpenToEncode

CryptSignHash

funciones de cifrado y descifrado de datos