CryptMsgOpenToDecode

The CryptMsgOpenToDecode function opens a cryptographic message for decoding. The message remains open until CryptMsgClose is called.

Important changes have been made to the CryptoAPI in order to support S/MIME e-mail interoperability, which affect the handling of enveloped messages. See the Remarks for CryptMsgOpenToEncode for details.

#include <wincrypt.h>
HCRYPTMSG WINAPI CryptMsgOpenToDecode(
  DWORD dwMsgEncodingType,         // in
  DWORD dwFlags,                   // in
  DWORD dwMsgType,                 // in
  HCRYPTPROV hCryptProv,           // in
  PCERT_INFO pRecipientInfo,       // in/optional
  PCMSG_STREAM_INFO pStreamInfo    // in/optional
);
 

Parameters

dwMsgEncodingType
Type of message encoding used. Note that it is always acceptable to specify both the certificate and message encoding types, by combining them with a bitwise OR operation, as shown in the following example:
CRYPT_ASN_ENCODING | PKCS_7_ASN_ENCODING
 

However, it is required only to specify the message encoding here. Currently defined encoding types are shown in the following table.
Encoding type Value
CRYPT_ASN_ENCODING 0x00000001
PKCS_7_ASN_ENCODING 0x00010000

dwFlags
Flag values. The CMSG_DETACHED_FLAG indicates that there is detached data being supplied for the subsequent calls to CryptMsgUpdate.
dwMsgType
Message type. Currently defined types are shown in the following table.
Message type Associated structures Value
CMSG_DATA Raw data (no associated structure) 1
CMSG_ENCRYPTED Not implemented. 6
CMSG_ENVELOPED CMSG_ENVELOPED_ENCODE_INFO 3
CMSG_HASHED CMSG_HASHED_ENCODE_INFO 5
CMSG_SIGNED CMSG_SIGNER_ENCODE_INFO, CMSG_SIGNED_ENCODE_INFO 2
CMSG_SIGNED_AND_ENVELOPED Not implemented. 4

For the Message type descriptions, see CryptMsgOpenToEncode.

Signed messages created with Microsoft® Internet Explorer version 3.0 do not contain header information. To maintain compatibility with Internet Explorer version 3.0, the dwMsgType parameter is provided. Therefore, if a signed message from Internet Explorer version 3.0 is received, the message type must be passed in to the function.

When zero is passed in for the dwMsgType parameter, this function will attempt to read the message type from the header on the message. If the header is missing, as in the case of some Internet Explorer version 3.0 messages, the function call will fail.

hCryptProv
Specifies a handle to the cryptographic provider to use for hashing the message. For signed messages, hCryptProv is used for signature verification.

Unless there is a strong reason for passing in a specific cryptographic provider in hCryptProv, zero should be passed in. Passing in zero causes the default RSA or DSS provider to be acquired before doing hash, signature verification or recipient encryption operations.

pRecipientInfo
This parameter is reserved for future use and should be set to NULL in the interim.
pStreamInfo
When streaming is not being used, this parameter must be set to NULL.

When streaming is being used, this parameter should point to a CMSG_STREAM_INFO structure. The callback specified by pfnStreamOutput in the CMSG_STREAM_INFO structure is called when CryptMsgUpdate is executed (and also when CryptMsgControl is executed when decoding a streamed enveloped message). For more information on how to use the callback, see CMSG_STREAM_INFO.

For a signed message, the callback is passed a block of the decoded bytes from the inner content of the message.

For an enveloped message, periodic checks should be made to see if the CMSG_ENVELOPE_ALGORITHM_PARAM is available yet by calling CryptMsgGetParam (CMSG_ENVELOPE_ALGORITHM_PARAM after each call to CryptMsgUpdate. CryptMsgGetParam will fail with LastError == CRYPT_E_STREAM_MSG_NOT_READY until enough of the message has been processed by CryptMsgUpdate to make the CMSG_ENVELOPE_ALGORITHM_PARAM available. Once it is available, the application can then iterate through the recipients, retrieving the CERT_INFO for each using CryptMsgGetParam (CMSG_RECIPIENT_INFO_PARAM).

The CERT_INFO for a recipient is used to call CertGetSubjectCertificateFromStore to see if a matching certificate is in the "my" certificate store (CertOpenSystemStore or CertOpenStore must have been previously called to open the "my" store). When a match is found, CertGetCertificateContextProperty(CERT_KEY_PROV_INFO_PROP_ID) is called which returns a CRYPT_KEY_PROV_INFO structure that contains the information necessary to acquire the private key for that recipient. CryptAcquireContext is called using the pwszContainerName, pwszProvName, dwProvType, and dwFlags members of CRYPT_KEY_PROV_INFO as parameters to get the desired hCryptProv. This hCryptProv and the dwKeySpec from the CRYPT_KEY_PROV_INFO are passed to CryptMsgControl (as a member of the CMSG_CTRL_DECRYPT_PARA structure) to permit the start of the decryption of the inner content. The streaming code will then perform the decryption as the data is input, and the resulting blocks of plaintext gets passed to the callback specified by pfnStreamOutput where an application may save it to a file.

Note  The streaming decode for an enveloped message queues up the ciphertext in memory until CryptMsgControl is called to start the decryption. It is up to the application to initiate decrypting in a timely manner so that the data can be saved to disk (or routed elsewhere) before the accumulated ciphertext becomes too large and the system runs out of memory.

Consider the case of a signed message enclosed in an enveloped message. The plaintext output from the streaming decode of the enveloped message can be fed into another streaming decode which can process the signed message.

Return Values

Returns a handle to the opened message if successful. Returns NULL if the operation failed.

To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function.

Error code Description
E_INVALIDARG One or more arguments are invalid.
E_OUTOFMEMORY Ran out of memory.

Example

See Signed Message Example Code.

See Enveloped Message Example 1.

See Hashed Message Example Code.

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later. Available also in IE 3.02 and later.
  Windows: Requires Windows 98 (or Windows 95 with IE 3.02 or later).
  Windows CE: Unsupported.
  Header: Declared in wincrypt.h.
  Import Library: Use crypt32.lib.

See Also

CryptMsgClose, CryptMsgUpdate, CryptMsgGetParam, CryptMsgOpenToEncode