The CryptMsgOpenToEncode function opens a cryptographic message for encoding and returns a handle of the opened message. The message remains open until CryptMsgClose is called.
HCRYPTMSG WINAPI CryptMsgOpenToEncode( _In_ DWORD dwMsgEncodingType, _In_ DWORD dwFlags, _In_ DWORD dwMsgType, _In_ const void *pvMsgEncodeInfo, _In_opt_ LPSTR pszInnerContentObjID, _In_ PCMSG_STREAM_INFO pStreamInfo );
- 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
Currently defined encoding types are:
- dwFlags [in]
Currently defined dwFlags are shown in the following table.
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.
There is detached data being supplied for the subsequent calls to CryptMsgUpdate.
Authenticated attributes are forced to be included in the SignerInfo (as defined by PKCS #7) in cases where they would not otherwise be required.
Used when calculating the size of a message that has been encoded by using Distinguished Encoding Rules (DER) and that is nested inside an enveloped message. This is particularly useful when performing streaming.
When set, non-data type-inner content is encapsulated within an OCTET STRING. Applicable to both signed and enveloped messages.
If set, the hCryptProv that is passed to this function is released on the final CryptMsgUpdate. The handle is not released if the function fails.
Note The hCryptProvs of the envelope recipients are not released.
- dwMsgType [in]
Indicates the message type. This must be one of the following values.
This value is not used.
The pvMsgEncodeInfo parameter is the address of a CMSG_SIGNED_ENCODE_INFO structure that contains the encoding information.
The pvMsgEncodeInfo parameter is the address of a CMSG_ENVELOPED_ENCODE_INFO structure that contains the encoding information.
This value is not currently implemented.
The pvMsgEncodeInfo parameter is the address of a CMSG_HASHED_ENCODE_INFO structure that contains the encoding information.
- pvMsgEncodeInfo [in]
The address of a structure that contains the encoding information. The type of data depends on the value of the dwMsgType parameter. For details, see dwMsgType.
- pszInnerContentObjID [in, optional]
If CryptMsgCalculateEncodedLength is called and the data for CryptMsgUpdate has already been message encoded, the appropriate object identifier (OID) is passed in pszInnerContentObjID. If pszInnerContentObjID is NULL, then the inner content type is assumed not to have been previously encoded and is therefore 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.
The following algorithm OIDs are commonly used. 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 OID.
- pStreamInfo [in]
When streaming is being used, this parameter is the address of a CMSG_STREAM_INFO structure. The callback function specified by the pfnStreamOutput member of the CMSG_STREAM_INFO structure is called when CryptMsgUpdate is executed. The callback is passed the encoded bytes that result from the encoding. For more information about how to use the callback, see CMSG_STREAM_INFO.
Note When streaming is being used, the application must not release any data handles that are passed in the pvMsgEncodeInfo parameter, such as the provider handle in the hCryptProv member of the CMSG_SIGNER_ENCODE_INFO structure, until after the message handle returned by this function is closed by using the CryptMsgClose function.
When streaming is not being used, this parameter is set to NULL.
Streaming is not used with the CMSG_HASHED message type. When dealing with hashed data, this parameter must be set to NULL.
Consider the case of a signed message being 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.
If the function succeeds, it returns a handle to the opened message. This handle must be closed when it is no longer needed by passing it to the CryptMsgClose function.
If this function fails, NULL is returned.
To retrieve extended error information, use the GetLastError function.
The following table lists the error codes most commonly returned by the GetLastError function.
The message type is not valid.
The OID is badly formatted.
The cryptographic algorithm is unknown.
One or more arguments are not valid.
There is not enough memory.
In addition, if dwMsgType is CMSG_SIGNED, errors can be propagated from CryptCreateHash.
If dwMsgType is CMSG_HASHED, errors can be propagated from CryptCreateHash.
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.
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.
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.
For examples that use this function, see Example C Program: Signing, Encoding, Decoding, and Verifying a Message, Alternate Code for Encoding an Enveloped Message, Example C Program: Encoding an Enveloped, Signed Message, and Example C Program: Encoding and Decoding a Hashed Message.
Minimum supported client
|Windows XP [desktop apps only]|
Minimum supported server
|Windows Server 2003 [desktop apps only]|
- Low-level Message Functions
- Simplified Message Functions
Build date: 10/26/2012