Compartir a través de

CryptMsgControl (Windows Embedded CE 6.0)

  • Artículo

1/6/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.

    Ee498201.note(en-US,WinEmbedded.60).gifNote:
    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:

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

See Also

Reference

Cryptography Functions