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
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.