CryptMsgOpenToEncode

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function opens a cryptographic message for encoding and returns a handle of the opened message. The message remains open until CryptMsgClose is 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 CryptMsgCalculateEncodedLength is called and the data for CryptMsgUpdate has already been message encoded, the appropriate object identifier is passed in pszInnerContentObjID. If pszInnerContentObjID is 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, pszInnerContentObjID must 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_INFO structure. The callback specified by pfnStreamOutput in the CMSG_STREAM_INFO structure is called when CryptMsgUpdate is 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 CryptMsgUpdate to 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 GetLastError function.

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

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

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

If dwMsgType is 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 CryptExportKey is called internally. For functions that perform decryption, the encrypted symmetric keys are reversed from big-endian format to little-endian format before CryptImportKey is called.
• CRYPT_NO_SALT is specified when symmetric keys are generated and imported with CryptGenKey and 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 CryptGetKeyParam to 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 ContentEncryptionAlgorithm member of the CMSG_ENVELOPED_ENCODE_INFO structure. 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 ContentEncryptionAlgorithm member of the CMSG_ENVELOPED_ENCODE_INFO structure. Previously, that value was not supported.

Requirements

See Also

Reference

Cryptography Functions
CryptMsgClose
CryptMsgUpdate
CryptMsgGetParam
CryptMsgOpenToDecode