Función CryptDecrypt (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 CryptDecrypt descifra los datos cifrados anteriormente mediante la función CryptEncrypt.

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 CryptDecrypt(
  [in]      HCRYPTKEY  hKey,
  [in]      HCRYPTHASH hHash,
  [in]      BOOL       Final,
  [in]      DWORD      dwFlags,
  [in, out] BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen
);

Parámetros

[in] hKey

Identificador de la clave que se va a usar para el descifrado. Una aplicación obtiene este identificador mediante la de CryptGenKey o CryptImportKey función.

Esta clave especifica el algoritmo de descifrado que se va a usar.

[in] hHash

Identificador de un objeto hash de . Si los datos se van a descifrar y aplicar hash simultáneamente, se pasa un identificador a un objeto hash en este parámetro. El valor hash se actualiza con el texto sin formato descifrado. Esta opción es útil al descifrar y comprobar simultáneamente una firma.

Antes de llamar a CryptDecrypt, la aplicación debe obtener un identificador para el objeto hash llamando a la función CryptCreateHash. Una vez completado el descifrado, el valor hash se puede obtener mediante la función CryptGetHashParam, también se puede firmar mediante la función CryptSignHash, o bien se puede usar para comprobar una firma digital mediante la función CryptVerifySignature.

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

[in] Final

Valor booleano que especifica si se trata de la última sección de una serie que se descifra. Este valor es TRUE si es el último o solo bloque. Si no es el último bloque, este valor es FALSE. Para obtener más información, vea Comentarios.

[in] dwFlags

Se definen los siguientes valores de marca.

Valor	Significado
CRYPT_OAEP 0x00000040	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. Esta marca no se puede combinar con la marca CRYPT_DECRYPT_RSA_NO_PADDING_CHECK.
CRYPT_DECRYPT_RSA_NO_PADDING_CHECK 0x00000020	Realice el descifrado en el BLOB sin comprobar el relleno. Esta marca solo es compatible con el proveedor criptográfico mejorado de Microsoft con cifrado y descifrado RSA. Esta marca no se puede combinar con la marca CRYPT_OAEP.

[in, out] pbData

Puntero a un búfer que contiene los datos que se van a descifrar. Después de realizar el descifrado, el texto no cifrado se vuelve a colocar en este mismo búfer.

El número de bytes cifrados de este búfer se especifica mediante pdwDataLen.

[in, out] pdwDataLen

Puntero a un valor DWORD que indica la longitud del búfer de pbData. Antes de llamar a esta función, la aplicación que llama establece el valor DWORD en el número de bytes que se van a descifrar. Tras la devolución, el valor DWORD contiene el número de bytes del texto no cifrado descifrado.

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 descifre la sección final de los datos y el parámetro Final sea TRUE.

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 descifrar 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. Este error también se puede devolver cuando se encuentra que el de relleno de no es válido.
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_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 no 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ó descifrar los mismos datos dos veces.
NTE_FAIL	Error en la función de alguna manera inesperada.

Observaciones

Si se va a descifrar una gran cantidad de datos, se puede realizar en secciones llamando a CryptDecrypt repetidamente. El parámetro Final debe establecerse en TRUE solo en la última llamada a CryptDecrypt, para que el motor de descifrado pueda finalizar correctamente el proceso de descifrado. 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. 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 de CryptDecrypt restablece el registro de comentarios del cifrado al valor KP_IV de la clave.
Si el cifrado es un cifrado de flujo, la siguiente CryptDecrypt llamada 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 CryptDecrypt. 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)

    // Decrypt the block with the duplicate key.
    CryptDecrypt(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 texto cifrado los datos que se van a descifrar deben tener la misma longitud que el módulo de la clave RSA que se usa para descifrar los datos. Si el texto cifrado tiene ceros en los bytes más significativos, estos bytes deben incluirse en el búfer de datos de entrada y en la longitud del búfer de entrada. El texto cifrado debe estar en formato little-endian.

Ejemplos

Para obtener un ejemplo que use esta función, vea Programa C de ejemplo: Descifrar 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