CryptMsgControl

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function performs a control operation after a message has been decoded by a final CryptMsgUpdate call. The control operations that are provided by this function are used for decryption, signature and hash verification, and the addition and deletion of certificates, certificate revocation lists (CRLs), signers, and unauthenticated attributes.

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

Syntax

BOOL WINAPI CryptMsgControl(
  HCRYPTMSG hCryptMsg,
  DWORD dwFlags,
  DWORD dwCtrlType,
  const void* pvCtrlPara
);

Parameters

• hCryptMsg
  [in] Handle of a cryptographic message for which a control is to be applied.

• dwFlags
  [in] The value for CMSG_CRYPT_RELEASE_CONTEXT_FLAG is defined when dwCtrlType is one of the following:

  • CMSG_CTRL_DECRYPT
  • CMSG_CTRL_KEY_TRANS_DECRYPT
  • CMSG_CTRL_KEY_AGREE_DECRYPT
  • CMSG_CTRL_MAIL_LIST_DECRYPT

  CMSG_CRYPT_RELEASE_CONTEXT_FLAG is the handle to the cryptographic provider is freed on the final call to CryptMsgClose. This handle is not freed if CryptMsgControl fails.

  If dwCtrlType does not specify a decrypt operation, set this value to zero.

• dwCtrlType
  [in] Specifies the type of operation to be performed. The following table shows the currently defined message control types and their associated pvCtrlPara structures.

  Value	Description
  CMSG_CTRL_VERIFY_SIGNATURE	CERT_INFO that identifies the signer of the message whose signature is to be verified.
  CMSG_CTRL_DECRYPT	CMSG_CTRL_DECRYPT_PARA used to decrypt the message for the specified key transport recipient. Applicable to RSA recipients.
  CMSG_CTRL_VERIFY_HASH	Not used. Set to NULL.
  CMSG_CTRL_ADD_SIGNER	CMSG_SIGNER_ENCODE_INFO that contains the signer information to be added to the message.
  CMSG_CTRL_DEL_SIGNER	The index of the signer to be deleted.
  CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR	CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA that contains the index of the signer and a BLOB that contains the unauthenticated attribute information to be added to the message.
  CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR	CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA that contains an index that specifies the signer and the index that specifies the signer's unauthenticated attribute to be deleted.
  CMSG_CTRL_ADD_CERT	CRYPTOAPI_BLOB that contains the encoded bytes of the certificate to be added to the message.
  CMSG_CTRL_DEL_CERT	Index of the certificate to be deleted from the message.
  CMSG_CTRL_ADD_CRL	BLOB that contains the encoded bytes of the CRL to be added to the message.
  CMSG_CTRL_DEL_CRL	Index of the CRL to be deleted from the message.
  CMSG_CTRL_ADD_ATTR_CERT	BLOB that contains the encoded bytes of attribute certificate.
  CMSG_CTRL_DEL_ATTR_CERT	Index of the attribute certificate to be removed.
  CMSG_CTRL_KEY_TRANS_DECRYPT	CMSG_KEY_TRANS_RECIPIENT_INFO structure used to decrypt the message for the specified key transport recipient. Key transport is used with RSA encryption/decryption.
  CMSG_CTRL_KEY_AGREE_DECRYPT	CMSG_CTRL_KEY_AGREE_DECRYPT_PARA structure used to decrypt the message for the specified key agreement session key. Key agreement is used with Diffie Hellman encryption/decryption.
  CMSG_CTRL_MAIL_LIST_DECRYPT	CMSG_MAIL_LIST_RECIPIENT_INFO structure used to decrypt the message for the specified recipient using a previously distributed key-encryption key (KEK).
  CMSG_CTRL_VERIFY_SIGNATURE_EX	CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA that specifies the signer index and public key to verify the message signature. The signer public key can be a CERT_PUBLIC_KEY_INFO structure, a certificate context, or a certificate chain context.

• pvCtrlPara
  [in] Pointer to a structure determined by the value of dwCtrlType.

  If dwCtrlType is . . .	Description
  CMSG_CTRL_DECRYPT, CMSG_CTRL_KEY_TRANS_DECRYPT, CMSG_CTRL_KEY_AGREE_DECRYPT, or CMSG_CTRL_MAIL_LIST_DECRYPT, and the streamed enveloped message is being decoded	Decoding will be done as if the streamed content were being decrypted. If any encrypted streamed content has accumulated prior to this call, some or all of the plaintext that results from the decryption of the cipher text is passed back to the application through the callback function specified in the call to CryptMsgOpenToDecode. > [!NOTE] > When streaming an enveloped message, CryptMsgControl is not called until the polling for the availability of the CMSG_ENVELOPE_ALGORITHM_PARAM succeeds. If the polling does not succeed, an error results. For a description of that polling, see CryptMsgOpenToDecode.
  CMSG_CTRL_VERIFY_HASH	The hash computed from the content of the message is compared against the hash contained in the message.
  CMSG_CTRL_ADD_SIGNER	pvCtrlPara points to a CMSG_SIGNER_ENCODE_INFO structure that contains the signer information to be added to the message.
  CMSG_CTRL_DEL_SIGNER	After a deletion is made, any other signer indexes in use for this message are invalidated and must be reacquired by calling CryptMsgGetParam.
  CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR	After a deletion is made, any other unauthenticated attribute indexes in use for this signer are invalidated and must be reacquired by calling CryptMsgGetParam.
  CMSG_CTRL_DEL_CERT	After a deletion is made, any other certificate indexes in use for this message are invalidated and must be reacquired by calling CryptMsgGetParam.
  CMSG_CTRL_DEL_CRL	After a deletion is made, any other CRL indexes in use for this message are invalidated and will need to be reacquired by calling CryptMsgGetParam.

Return Value

If the function succeeds, the return value is nonzero (TRUE).

If the function fails, the return value is zero (FALSE) and GetLastError returns an ASN.1 encoding/decoding error.

When a streamed, enveloped message is being decoded, errors encountered in the application-defined callback function specified by pStreamInfo in CryptMsgOpenToDecode might be propagated to CryptMsgControl. If this happens, SetLastError is not called by CryptMsgControl after the callback returns. This 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.

Propagated errors might be encountered from the following functions:

• CryptCreateHash
• CryptHashData
• CryptGetHashParam
• CryptVerifySignature
• CryptGetUserKey
• CryptImportKey
• CryptDecrypt
• CryptSignHash

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

Requirements

See Also

Reference

Cryptography Functions