CryptMsgControl
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 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.
| Return Code | Description |
|---|---|
CRYPT_E_ALREADY_DECRYPTED |
The message content has already been decrypted. This error can be returned if dwCtrlType equals CMSG_CTRL_DECRYPT. |
CRYPT_E_AUTH_ATTR_MISSING |
The message does not contain an expected authenticated attribute. This error can be returned if dwCtrlType equals CMSG_CTRL_VERIFY_SIGNATURE. |
CRYPT_E_BAD_ENCODE |
An error was encountered while encoding or decoding. This error can be returned if dwCtrlType equals 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 dwCtrlType equals 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 dwCtrlType equals CMSG_CTRL_DECRYPT. |
CRYPT_E_SIGNER_NOT_FOUND |
The specified signer for the message was not found. This error can be returned if dwCtrlType equals 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 dwCtrlType equals CMSG_CTRL_VERIFY_SIGNATURE. |
E_INVALIDARG |
One or more arguments are invalid. This error can be returned if dwCtrlType equals 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 |