Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function performs a control operation after a message has been decoded by a final CryptMsgUpdatecall. 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 CryptMsgControlfails.

If dwCtrlTypedoes 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 pvCtrlParastructures.

Value Description

CMSG_CTRL_VERIFY_SIGNATURE

CERT_INFOthat identifies the signer of the message whose signature is to be verified.

CMSG_CTRL_DECRYPT

CMSG_CTRL_DECRYPT_PARAused 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_INFOthat 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_PARAthat 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_PARAthat 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_INFOstructure 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_PARAstructure 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_INFOstructure 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_PARAthat specifies the signer index and public key to verify the message signature. The signer public key can be a CERT_PUBLIC_KEY_INFOstructure, a certificate context, or a certificate chain context.
pvCtrlPara

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

If dwCtrlTypeis . . . 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, CryptMsgControlis 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

pvCtrlParapoints to a CMSG_SIGNER_ENCODE_INFOstructure 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 GetLastErrorreturns an ASN.1 encoding/decoding error.

When a streamed, enveloped message is being decoded, errors encountered in the application-defined callback function specified by pStreamInfoin CryptMsgOpenToDecodemight be propagated to CryptMsgControl. If this happens, SetLastErroris not called by CryptMsgControlafter 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 SetLastErrorif an error occurs while the application is processing the streamed data.

Propagated errors might be encountered from the following functions:

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

Return Code Description

CRYPT_E_ALREADY_DECRYPTED

The message content has already been decrypted. This error can be returned if dwCtrlTypeequals CMSG_CTRL_DECRYPT.

CRYPT_E_AUTH_ATTR_MISSING

The message does not contain an expected authenticated attribute. This error can be returned if dwCtrlTypeequals CMSG_CTRL_VERIFY_SIGNATURE.

CRYPT_E_BAD_ENCODE

An error was encountered while encoding or decoding. This error can be returned if dwCtrlTypeequals CMSG_CTRL_VERIFY_SIGNATURE.

CRYPT_E_CONTROL_TYPE

The control type is not valid.

CRYPT_E_HASH_VALUE

The hash value is incorrect.

CRYPT_E_INVALID_INDEX

The index value is not valid.

CRYPT_E_INVALID_MSG_TYPE

The message type is not valid.

CRYPT_E_OID_FORMAT

The object identifier is badly formatted. This error can be returned if dwCtrlTypeequals CMSG_CTRL_ADD_SIGNER.

CRYPT_E_RECIPIENT_NOT_FOUND

The enveloped data message does not contain the specified recipient. This error can be returned if dwCtrlTypeequals CMSG_CTRL_DECRYPT.

CRYPT_E_SIGNER_NOT_FOUND

The specified signer for the message was not found. This error can be returned if dwCtrlTypeequals CMSG_CTRL_VERIFY_SIGNATURE.

CRYPT_E_UNKNOWN_ALGO

The cryptographic algorithm is unknown.

CRYPT_E_UNEXPECTED_ENCODING

The message is not encoded as expected. This error can be returned if dwCtrlTypeequals CMSG_CTRL_VERIFY_SIGNATURE.

E_INVALIDARG

One or more arguments are invalid. This error can be returned if dwCtrlTypeequals CMSG_CTRL_DECRYPT.

E_OUTOFMEMORY

Ran out of memory.

Requirements

Header wincrypt.h
Library crypt32.lib
Windows Embedded CE Windows CE 5.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also