CryptMsgOpenToDecode

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function opens a cryptographic message for decoding and returns a handle of the opened message. The message remains open until CryptMsgClose is called.

Important changes that affect the handling of enveloped messages have been made to CryptoAPI to support S/MIME e-mail interoperability. For details, see the Remarks section in CryptMsgOpenToEncode.

Syntax

HCRYPTMSG WINAPI CryptMsgOpenToDecode(
  DWORD dwMsgEncodingType,
  DWORD dwFlags,
  DWORD dwMsgType,
  HCRYPTPROV hCryptProv,
  PCERT_INFO pRecipientInfo,
  PCMSG_STREAM_INFO pStreamInfo
);

Parameters

• dwMsgEncodingType
  [in] Specifies the encoding type used. 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:

  X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

  The message encoding type defines how the message is encoded. The message encoding type is stored in the high-order word of the encoding type structure.

  The following list shows the currently defined encoding types:

  • CRYPT_ASN_ENCODING
  • X509_ASN_ENCODING
  • PKCS_7_ASN_ENCODING

• dwFlags
  [in] The following flags are defined.

  Value	Description
  CMSG_DETACHED_FLAG	Indicates that the message to be decoded is detached. If this flag is not set, the message is not detached.
  CMSG_CRYPT_RELEASE_CONTEXT_FLAG	If set, the hCryptProv passed to this function is freed on the final CryptMsgUpdate. The handle is not freed if the function fails.

• dwMsgType
  [in] In most cases message type is determined from the message header and zero is passed. In some cases, notably with Internet Explorer 3.0, messages do not have headers and the type of message to be decoded must be supplied in the function call. If the header is missing and zero (0) is passed, the function fails.

  The following list shows the non-zero, currently predefined message types:

  • CMSG_DATA
  • CMSG_ENVELOPED
  • CMSG_HASHED
  • CMSG_SIGNED
  • CMSG_SIGNED_AND_ENVELOPED

• hCryptProv
  [in] Specifies a handle for 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, set this parameter to zero. Passing in zero causes the default RSA or DSS provider to be acquired before performing hash, signature verification, or recipient encryption operations.

• pRecipientInfo
  [in] This parameter is reserved for future use and must be NULL.

• pStreamInfo
  [in, optional] When streaming is not being used, this parameter must be set to NULL.

  Note

  Streaming is not used with CMSG_HASHED. When dealing with hashed data, this parameter must be set to NULL.

  When streaming is being used, pStreamInfo is a pointer to a CMSG_STREAM_INFO structure that contains a pointer to a callback to be called when CryptMsgUpdate is executed or when CryptMsgControl is executed when decoding a streamed enveloped message.

  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, after each call to CryptMsgUpdate, check to see if CMSG_ENVELOPE_ALGORITHM_PARAM is available by calling CryptMsgGetParam. CryptMsgGetParam will fail with LastError CRYPT_E_STREAM_MSG_NOT_READY until CryptMsgUpdate has processed enough of the message to make CMSG_ENVELOPE_ALGORITHM_PARAM available. Once CMSG_ENVELOPE_ALGORITHM_PARAM is available, the application can iterate through the recipients, retrieving a CERT_INFO structure for each one using CryptMsgGetParam (CMSG_RECIPIENT_INFO_PARAM).

  CERT_INFO is used to find a matching certificate in a previously opened certificate store by using CertGetSubjectCertificateFromStore. When the correct certificate is found, CertGetCertificateContextProperty with a CERT_KEY_PROV_INFO_PROP_ID parameter is called to retrieve a CRYPT_KEY_PROV_INFO structure. The structure contains the information necessary to acquire the recipient's private key by calling CryptAcquireContext, by using the pwszContainerName, pwszProvName, dwProvType, and dwFlags members of CRYPT_KEY_PROV_INFO. The hCryptProv acquired 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. The resulting blocks of plaintext are passed to the callback function specified by pfnStreamOutput to handle the output of the decrypted message.

  Note

  Streaming decoding of an enveloped message queues the ciphertext in memory until CryptMsgControl is called to start the decryption. The application must initiate decryption 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.

  In 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 to process the signed message.

Return Value

If successful, returns the handle of the opened message. Returns NULL if the operation failed.

To retrieve extended error information, use the GetLastError function.

The following table shows the error codes that are most commonly returned by the GetLastError function.

Requirements

See Also

Reference

Cryptography Functions
CryptMsgClose
CryptMsgUpdate
CryptMsgGetParam
CryptMsgOpenToEncode