CryptMsgControl

The CryptMsgControl function performs a special control function after the final CryptMsgUpdate call on a decoded cryptographic message. The controls include decryption, signature and hash verification, and the addition and deletion of certificates, CRLs, signers, and unauthenticated attributes.

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>
BOOL WINAPI CryptMsgControl(
  HCRYPTMSG hCryptMsg,       // in
  DWORD dwFlags,             // in
  DWORD dwCtrlType,          // in
  const void *pvCtrlPara     // in
);
 

Parameters

hCryptMsg

Handle to a cryptographic message for which a control is to be applied.

dwFlags

Flag values. This parameter is reserved for future use and should be set to zero in the interim.

dwCtrlType

Specifies the type of operation to be performed. Currently defined message control types are shown in the following table.

Message Control type	Value
CMSG_CTRL_VERIFY_SIGNATURE	1
CMSG_CTRL_DECRYPT	2
CMSG_CTRL_VERIFY_HASH	5
CMSG_CTRL_ADD_SIGNER	6
CMSG_CTRL_DEL_SIGNER	7
CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR	8
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR	9
CMSG_CTRL_ADD_CERT	10
CMSG_CTRL_DEL_CERT	11
CMSG_CTRL_ADD_CRL	12
CMSG_CTRL_DEL_CRL	13

pvCtrlPara

For a value of CMSG_CTRL_VERIFY_SIGNATURE in dwCtrlType, pvCtrlPara points to a CERT_INFO structure. It identifies the signer of the message for which the signature is to be verified.

For a value of CMSG_CTRL_DECRYPT in dwCtrlType, pvCtrlPara points to a CMSG_CTRL_DECRYPT_PARA structure used to decrypt the message for the specified recipient. For the case of decoding an streamed enveloped message, this value will initiate the decryption of the streamed content. If any encrypted streamed content has accumulated prior to this call, some or all of the plaintext resulting from the decryption of the ciphertext is passed back to the application through the callback function specified in the call to CryptMsgOpenToDecode. Note that when streaming an enveloped message, CryptMsgControl should not be called until the polling for the availability of the CMSG_ENVELOPE_ALGORITHM_PARAM succeeds or an error will result. See CryptMsgOpenToDecode for a description of that polling.

For a value of CMSG_CTRL_VERIFY_HASH in dwCtrlType, pvCtrlPara is not used, and should be set to NULL. The hash that was computed from the content of the message is compared against the hash that is contained in the message.

For a value of CMSG_CTRL_ADD_SIGNER in dwCtrlType, pvCtrlPara points to a CMSG_SIGNER_ENCODE_INFO structure containing the signer information to be added to the message.

For a value of CMSG_CTRL_DEL_SIGNER in dwCtrlType, pvCtrlPara points to a DWORD containing the index of the signer to be deleted. Note that once a deletion is made, any other signer indices in use for this message are invalidated and will need to be reacquired by calling CryptMsgGetParam.

For a value of CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR in dwCtrlType, pvCtrlPara points to a CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA structure containing the index of the signer and a blob containing the unauthenticated attribute information to be added to the message.

For a value of CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR in dwCtrlType, pvCtrlPara points to a CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA structure which contains the index specifying the signer and the index specifying the unauthenticated attribute (for that signer) to be deleted. Note that once a deletion is made, any other unauthenticated attribute indices in use for this signer are invalidated and will need to be reacquired by calling CryptMsgGetParam.

For a value of CMSG_CTRL_ADD_CERT in dwCtrlType, pvCtrlPara points to a BLOB Structure structure named CRYPT_DATA_BLOB that contains the encoded bytes of the certificate to be added to the message.

For a value of CMSG_CTRL_DEL_CERT in dwCtrlType, pvCtrlPara points to a DWORD containing the index of the certificate to be deleted from the message. Note that once a deletion is made, any other certificate indices in use for this message are invalidated and will need to be reacquired by calling CryptMsgGetParam.

For a value of CMSG_CTRL_ADD_CRL in dwCtrlType, pvCtrlPara points to a BLOB Structure named CRYPT_DATA_BLOB that contains the encoded bytes of the CRL to be added to the message.

For a value of CMSG_CTRL_DEL_CRL in dwCtrlType, pvCtrlPara points to a DWORD containing the index of the CRL to be deleted from the message. Note that once a deletion is made, any other CRL indices in use for this message are invalidated and will need to be reacquired by calling CryptMsgGetParam.

Return Values

If the function being performed per the dwCtrlType fails, the return value is FALSE (zero). If it succeeds, the return value is true (non-zero).

When an streamed enveloped message is being decoded, errors encountered in the application defined callback function specified by pStreamInfo in CryptMsgOpenToDecode may be propagated to CryptMsgControl. If this happens, SetLastError is not called by CryptMsgControl after the callback returns, which preserves any errors encountered under the control of the application. It is the responsibility of the callback function (or one of the APIs that it calls) to call SetLastError if an error occurs while the application is processing the streamed data.

To retrieve extended error information, use the GetLastError function.

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

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.