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 opens a cryptographic message for encoding and returns a handle of the opened message. The message remains open until CryptMsgCloseis called.

Syntax 

HCRYPTMSG WINAPI CryptMsgOpenToEncode(
  DWORD 
dwMsgEncodingType,
  DWORD 
dwFlags,
  DWORD 
dwMsgType,
  const void* 
pvMsgEncodeInfo,
  LPSTR 
pszInnerContentObjID,
  PCMSG_STREAM_INFO 
pStreamInfo
);

Parameters

dwMsgEncodingType

[in] Specifies the encoding type used. It is always acceptable to specify both the certificate and message encoding types by combining them with a bitwise-OR operation as shown in the following example:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

The message encoding type defines how the message is encoded. The message encoding type is stored in the high-order word of the encoding type structure.

Currently defined encoding types are:

  • CRYPT_ASN_ENCODING

  • X509_ASN_ENCODING

  • PKCS_7_ASN_ENCODING

dwFlags

[in] Currently defined dwFlags are shown in the following table.

Value Description

CMSG_BARE_CONTENT_FLAG

The streamed output will not have an outer ContentInfo wrapper (as defined by PKCS #7). This makes it suitable to be streamed into an enclosing message.

CMSG_DETACHED_FLAG

There is detached data being supplied for the subsequent calls to CryptMsgUpdate.

CMSG_AUTHENTICATED_ATTRIBUTES_FLAG

Authenticated attributes are forced to be included in the SignerInfo (as defined by PKCS #7) in cases where they would not otherwise be required.

CMSG_CONTENTS_OCTETS_FLAG

Used when calculating the size of a DER-encoded message that is nested inside an enveloped message. This is particularly useful when performing streaming

CMSG_CMS_ENCAPSULATED_CONTENT_FLAG

When set, non-Data type inner content is encapsulated within an OCTET STRING. Applicable to both Signed and Enveloped messages.

CMSG_CRYPT_RELEASE_CONTEXT_FLAG

If set, the hCryptProv passed to this function is freed on the final CryptMsgUpdate. The handle is not freed if the function fails.

Note:
Envelope recipients' hCryptProvs are not freed.
dwMsgType

[in] Indicates message type. Currently defined message types are shown in the following table.

Value Description

CMSG_DATA

Not used.

CMSG_SIGNED

CMSG_SIGNED_ENCODE_INFO

CMSG_ENVELOPED

CMSG_ENVELOPED_ENCODE_INFO

CMSG_SIGNED_AND_ENVELOPED

Not currently implemented.

CMSG_HASHED

CMSG_HASHED_ENCODE_INFO

pvMsgEncodeInfo

[in] Pointer to the data to be encoded. The type of data pointed to depends on the value of dwMsgType. For details, see the dwMsgType table.

pszInnerContentObjID

[in, optional] If CryptMsgCalculateEncodedLengthis called and the data for CryptMsgUpdatehas already been message encoded, the appropriate object identifier is passed in pszInnerContentObjID. If pszInnerContentObjIDis NULL, the inner content type is assumed not to have been previously encoded, and is encoded as an octet string and given the type CMSG_DATA.

Note:
When streaming is being used, pszInnerContentObjIDmust be either NULL or szOID_RSA_data.

A user can define new inner content usage by ensuring that the sender and receiver of the message agree upon the semantics associated with the object identifier. The following list shows the algorithm object identifiers that are commonly used:

  • szOID_RSA_data

  • szOID_RSA_signedData

  • szOID_RSA_envelopedData

  • szOID_RSA_signEnvData

  • szOID_RSA_digestedData

  • szOID_RSA_encryptedData

  • SPC_INDIRECT_DATA_OBJID

pStreamInfo

[in] When streaming is not being used, this parameter is set to NULL.

Note:
Streaming is not used with CMSG_HASHED. When dealing with hashed data, this parameter must be set to NULL.

When streaming is being used, this parameter points to a CMSG_STREAM_INFOstructure. The callback specified by pfnStreamOutput in the CMSG_STREAM_INFOstructure is called when CryptMsgUpdateis executed. The callback is passed the encoded bytes resulting from the encoding. For more information about how to use the callback, see CMSG_STREAM_INFO.

Consider the case of a signed message enclosed in an enveloped message. The encoded output from the streamed encoding of the signed message feeds into another streaming encoding of the enveloped message. The callback for the streaming encoding calls CryptMsgUpdateto encode the enveloped message. The callback for the enveloped message receives the encoded bytes of the nested signed message.

Return Value

If the function succeeds, it returns a handle of the opened message. If it fails, NULL is returned.

To retrieve extended error information, use the GetLastErrorfunction.

The following table shows the error codes most commonly returned by the GetLastErrorfunction.

Return Code Description

CRYPT_E_INVALID_MSG_TYPE

One or more arguments are invalid.

CRYPT_E_OID_FORMAT

Ran out of memory.

CRYPT_E_UNKNOWN_ALGO

The cryptographic algorithm is unknown.

E_INVALIDARG

One or more arguments are invalid.

E_OUTOFMEMORY

Ran out of memory.

In addition, if dwMsgTypeis CMSG_SIGNED, errors can be propagated from CryptCreateHash.

If dwMsgTypeis CMSG_ENVELOPED, errors can be propagated from CryptGenKey, CryptImportKey, and CryptExportKey.

If dwMsgTypeis CMSG_HASHED, errors can be propagated from CryptCreateHash.

Remarks

Important changes have been made to the CryptoAPI that affects the handling of enveloped messages to support S/MIME e-mail interoperability. The changes take effect for products freed after Service Pack 3, such as Internet Explorer 4.0 and Windows 2000. The following list shows the changes that have been made:

  • For functions that perform encryption, the encrypted symmetric keys are reversed from little-endian format to big-endian format after CryptExportKeyis called internally. For functions that perform decryption, the encrypted symmetric keys are reversed from big-endian format to little-endian format before CryptImportKeyis called.

  • CRYPT_NO_SALT is specified when symmetric keys are generated and imported with CryptGenKeyand CryptImportKey. Previously, 11 bytes of zero value salt was used instead of no salt.

  • Messages encrypted with the RC2 encryption algorithm use KP_EFFECTIVE_KEYLEN with CryptGetKeyParamto determine the effective key length of the RC2 key importing or exporting keys. Previously, a default key length of 40 bits was always used to import or export keys.

  • For messages encrypted with the RC2 encryption algorithm, encode and decode operations have been updated to handle ASN RC2 parameters for the ContentEncryptionAlgorithmmember of the CMSG_ENVELOPED_ENCODE_INFOstructure. Previously, the values were not supported.

  • For messages encrypted with the RC4, DES, and 3DES encryption algorithms, encode and decode operations now handle the ASN IV octet string parameter for the ContentEncryptionAlgorithmmember of the CMSG_ENVELOPED_ENCODE_INFOstructure. Previously, that value was not supported.

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