CMSG_STREAM_INFO (Compact 2013)

  • Article

3/28/2014

This structure is used to enable stream data processing rather than single block processing. Stream processing is most often used when processing large messages. Stream-process messages can originate from any serialized source such as a file on a hard disk, a server, or a CD ROM.

This structure is passed to CryptMsgOpenToEncode and CryptMsgOpenToDecode.

Syntax

typedef struct _CMSG_STREAM_INFO {
  DWORD cbContent;
  PFN_CMSG_STREAM_OUTPUT pfnStreamOutput;
  void* pvArg;
} CMSG_STREAM_INFO, *PCMSG_STREAM_INFO;

Members

  • cbContent
    Specifies the size of the content in bytes. Normal Distinguised Encoding Rules (DER) encoding is used unless a 0xFFFFFFFF is passed indicating that the application is not specifying the content length. This forces the use of indefinite-length Basic Encoding Rules (BER) encoding.

  • pfnStreamOutput
    Address of a callback function used to read from and write data to a disk when processing large messages.

    The callback function must have the following signature and parameters:

    BOOL WINAPI CmsgStreamOutputCallback(
  const void *pvArg,  //in
  BYTE *pbData,       //in
  DWORD cbData,       //in
  BOOL fFinal         //in
);

    Parameter

    Description

    pvArg

    The arguments that are specified by CMSG_STREAM_INFO.

    pbData

    Pointer to a block of processed data that is available to the application.

    cbData

    Size, in bytes, of the block of processed data at pbData.

    fFinal

    Specifies that the last block of data is being processed and that this is the last time the callback will be executed.
  • pvArg
    Pointer to the argument to pass to the callback function. Typically, this is used for state data that includes the handle to a more deeply nested message (when decoding) or a less deeply nested message (when encoding).

Remarks

Messages can be so large that processing them all at once by storing the whole message in memory can be difficult, if not impossible. It is possible to process large messages without encountering memory limitations by streaming the data that is to be processed into manageable sized blocks. The low-level message functions can be used with streaming to encode or decode a message. Any level of nesting of messages is supported when streaming to encode and streaming to decode.

The input message to be processed as a stream feeds into CryptMsgUpdate one block at a time, with the application determining the size of the block. As the streamed message is processed for encoding or decoding, the resulting output data is passed back to the application through an application-specified callback function specified by the pfnStreamOutput member.

No assumptions can be made about the block size of the output data because the size can vary for several reasons such as the jitter in output block size caused by the block size for the encryption algorithm when processing an enveloped message, or when blocks that contain the message header and the SignerInfo as defined by PKCS # 7 are processed.

The size of the output block is passed to the callback function in its cbData parameter The use of output data is determined in the calling application. Typically, output from stream processing will not be persisted in memory as a whole due to memory limitations, but will be serialized to a disk or server file.

Requirements

Header

wincrypt.h

See Also

Reference

Cryptography Structures