Función CryptMsgOpenToDecode (wincrypt.h)

Artículo
03/15/2023

La función CryptMsgOpenToDecode abre un mensaje criptográfico para descodificar y devuelve un identificador del mensaje abierto. El mensaje permanece abierto hasta que se llama a la función CryptMsgClose .

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

Sintaxis

HCRYPTMSG CryptMsgOpenToDecode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           HCRYPTPROV_LEGACY hCryptProv,
  [in]           PCERT_INFO        pRecipientInfo,
  [in, optional] PCMSG_STREAM_INFO pStreamInfo
);

Parámetros

[in] dwMsgEncodingType

Especifica el tipo de codificación utilizado. Siempre es aceptable especificar los tipos de codificación de certificados y mensajes mediante su combinación con una operación OR bit a bit, como se muestra en el ejemplo siguiente:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

Los tipos de codificación definidos actualmente son:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFlags

Este parámetro puede ser una de las marcas siguientes.

Valor	Significado
CMSG_DETACHED_FLAG	Indica que el mensaje que se va a descodificar está desasociado. Si no se establece esta marca, el mensaje no se desasocia.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Si se establece, el hCryptProv pasado a esta función se libera en el CryptMsgUpdate final. El identificador no se libera si se produce un error en la función.

[in] dwMsgType

Especifica el tipo de mensaje que se va a descodificar. En la mayoría de los casos, el tipo de mensaje se determina a partir del encabezado del mensaje y se pasa cero para este parámetro. En algunos casos, especialmente con Internet Explorer 3.0, los mensajes no tienen encabezados y el tipo de mensaje que se va a descodificar debe proporcionarse en esta llamada de función. Si falta el encabezado y se pasa cero para este parámetro, se produce un error en la función.

Este parámetro puede ser uno de los siguientes tipos de mensajes predefinidos.

Valor	Significado
CMSG_DATA	El mensaje es datos codificados.
CMSG_ENVELOPED	El mensaje es un mensaje sobre.
CMSG_HASHED	El mensaje es un mensaje con hash.
CMSG_SIGNED	El mensaje es un mensaje firmado.
CMSG_SIGNED_AND_ENVELOPED	El mensaje es un mensaje con signo y sobre.

[in] hCryptProv

Este parámetro no se usa y debe establecerse en NULL.

Windows Server 2003 y Windows XP: Especifica un identificador para que el proveedor criptográfico use para aplicar un algoritmo hash al mensaje. En el caso de los mensajes firmados, hCryptProv se usa para la comprobación de firmas. El tipo de datos de este parámetro es HCRYPTPROV.

A menos que haya un motivo seguro para pasar un proveedor criptográfico específico en hCryptProv, establezca este parámetro en NULL. Pasar NULL hace que el proveedor RSA o DSS predeterminado se adquiera antes de realizar operaciones de hash, comprobación de firma o cifrado de destinatarios.

[in] pRecipientInfo

Este parámetro está reservado para uso futuro y debe ser NULL.

[in, optional] pStreamInfo

Cuando no se usa el streaming, este parámetro debe establecerse en NULL.

Nota El streaming no se usa con mensajes de CMSG_HASHED. Al tratar con datos con hash, este parámetro debe establecerse en NULL.

Cuando se usa el streaming, el parámetro pStreamInfo es un puntero a una estructura de CMSG_STREAM_INFO que contiene un puntero a una devolución de llamada a la que se llamará cuando se ejecuta CryptMsgUpdate o cuando se ejecuta CryptMsgControl al descodificar un mensaje sobre transmitido en secuencias.

Para un mensaje firmado, la devolución de llamada se pasa a un bloque de los bytes descodificados del contenido interno del mensaje.

Para un mensaje sobre, después de cada llamada a CryptMsgUpdate, debe comprobar si la propiedad CMSG_ENVELOPE_ALGORITHM_PARAM está disponible llamando a la función CryptMsgGetParam . Se producirá un error en CryptMsgGetParam y GetLastError devolverá CRYPT_E_STREAM_MSG_NOT_READY hasta que CryptMsgUpdate haya procesado suficiente el mensaje para que la propiedad CMSG_ENVELOPE_ALGORITHM_PARAM esté disponible. Cuando la propiedad CMSG_ENVELOPE_ALGORITHM_PARAM está disponible, puede recorrer en iteración los destinatarios, recuperando una estructura de CERT_INFO para cada destinatario mediante la función CryptMsgGetParam para recuperar la propiedad CMSG_RECIPIENT_INFO_PARAM. Para evitar un ataque por denegación de servicio de un mensaje sobre que tiene un bloque de encabezado artificialmente grande, debe realizar un seguimiento de la cantidad de memoria que se ha pasado a la función CryptMsgUpdate durante este proceso. Si la cantidad de datos supera un límite definido por la aplicación antes de que la propiedad CMSG_ENVELOPE_ALGORITHM_PARAM esté disponible, debe detener el procesamiento del mensaje y llamar a la función CryptMsgClose para que el sistema operativo libere cualquier memoria asignada para el mensaje. Un límite sugerido es el tamaño máximo permitido de un mensaje. Por ejemplo, si el tamaño máximo del mensaje es de 10 MB, el límite de esta prueba debe ser de 10 MB.

La estructura CERT_INFO se usa para buscar un certificado coincidente en un almacén de certificados abierto previamente mediante la función CertGetSubjectCertificateFromStore . Cuando se encuentra el certificado correcto, se llama a la función CertGetCertificateContextProperty con un parámetro CERT_KEY_PROV_INFO_PROP_ID para recuperar una estructura CRYPT_KEY_PROV_INFO . La estructura contiene la información necesaria para adquirir la clave privada del destinatario mediante una llamada a CryptAcquireContext mediante los miembros pwszContainerName, pwszProvName, dwProvType y dwFlags de la estructura CRYPT_KEY_PROV_INFO . El hCryptProv adquirido y el miembro dwKeySpec de la estructura CRYPT_KEY_PROV_INFO se pasan a la estructura CryptMsgControl como miembro de la estructura CMSG_CTRL_DECRYPT_PARA para permitir el inicio del descifrado del contenido interno. A continuación, el código de streaming realizará el descifrado a medida que se introducen los datos. Los bloques resultantes de texto no cifrado se pasan a la función de devolución de llamada especificada por el miembro pfnStreamOutput de la estructura CMSG_STREAM_INFO para controlar la salida del mensaje descifrado.

Nota La descodificación transmitida de un mensaje sobre pone en cola el texto cifrado en la memoria hasta que se llama a CryptMsgControl para iniciar el descifrado. La aplicación debe iniciar el descifrado de forma oportuna para que los datos se puedan guardar en el disco o enrutarse a otro lugar antes de que el texto cifrado acumulado sea demasiado grande y el sistema se quede sin memoria.

En el caso de un mensaje firmado incluido en un mensaje sobre, la salida de texto no cifrado de la descodificación de streaming del mensaje sobre se puede introducir en otra descodificación de streaming para procesar el mensaje firmado.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve el identificador del mensaje abierto.

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

En la tabla siguiente se enumeran los códigos de error devueltos normalmente por la función GetLastError .

Valor	Descripción
E_INVALIDARG	Uno o varios argumentos no son válidos.
E_OUTOFMEMORY	Error de asignación de memoria.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	wincrypt.h
Library	Crypt32.lib
Archivo DLL	Crypt32.dll

Consulte también

Funciones de mensaje de bajo nivel

Funciones de mensaje simplificadas

Compartir a través de