CryptMsgControl (Windows CE 5.0)

  • Article

Send Feedback

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.

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 Values

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:

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

OS Versions: Windows CE 5.0 and later.
Header: Wincrypt.h.
Link Library: Coredll.lib.

See Also

Cryptography Functions

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.