Stream Contexts

Stream contexts handle the secure stream-oriented protocols such as SSL or PCT. In the interest of sharing the same interface and similar credential management, SSPI provides support for stream contexts. The security protocol incorporates both the stream authentication scheme and record formats.

To provide stream-oriented protocols, security packages that support stream contexts have the following process characteristics:

• The package sets the SECPKG_FLAG_STREAM flag to indicate that it supports stream semantics.

• Transport applications requests stream semantics by setting the ISC_REQ_STREAM and ASC_REQ_STREAM flags in the calls to the InitializeSecurityContext (General) and AcceptSecurityContext (General) functions.

• The application calls the QueryContextAttributes (General) function with a SecPkgContext_StreamSizes structure to query the security context for the number of buffers to provide and the sizes to reserve for headers or trailers.

• The application provides buffer descriptors to spare during the actual processing of the data. By specifying stream semantics, the caller indicates willingness to do extra processing so that the security package can handle the blocking of the messages. In essence, for the MakeSignature and VerifySignature functions, the caller passes in a list of buffers. When a message is received from a channel that is stream-oriented (such as a TCP port), the caller passes in a buffer list as follows.

  Buffer	Length	Buffer type
  1	Message Length	SECBUFFER_DATA
  2	0	SECBUFFER_EMPTY
  3	0	SECBUFFER_EMPTY
  4	0	SECBUFFER_EMPTY
  5	0	SECBUFFER_EMPTY

   

  The security package then works on the BLOB. If the function returns successfully, the buffer list looks like the following.

  Buffer	Length	Buffer type
  1	Header Length	SECBUFFER_STREAM_HEADER
  2	Data Length	SECBUFFER_DATA
  3	Trailer Length	SECBUFFER_STREAM_TRAILER
  4	0	SECBUFFER_EMPTY
  5	0	SECBUFFER_EMPTY

   

  The package could have also returned buffer #4 with length x and buffer type SECBUFFER_EXTRA indicating that the data in this buffer is part of the next record and has not yet been processed. Conversely, if the message function returns the SEC_E_INCOMPLETE_MESSAGE error code, the returned buffer list would look like the following.

  Buffer	Length	Buffer type
  1	x	SECBUFFER_MISSING

   

  This indicates that more data was needed to process the record. Unlike most errors returned from a message function, this buffer type does not indicate that the context has been compromised. Instead, it indicates that more data is needed. security packages must not update their state in this condition.

  Similarly, on the sender side of the communication, the caller can call the MakeSignature function. The security package may need to reallocate the buffer or copy things around. The caller can be more efficient by providing a buffer list as follows.

  Buffer	Length	Type
  1	Header Length	SECBUFFER_STREAM_HEADER
  2	Data Length	SECBUFFER_DATA
  3	Trailer Length	SECBUFFER_STREAM_TRAILER

   

  This allows the caller to use the buffers more efficiently. By calling the QueryContextAttributes function to determine the amount of space to reserve before calling MakeSignature, the operation is more efficient for the application and the security package.