Context Semantics

The SSPI supports three types of security contexts: connection, datagram, and stream contexts.

With a connection context, the caller of the function is responsible for formatting messages. The caller also relies on the security provider to authenticate connections and to ensure the integrity of specific parts of the message. Most context options are available to connection contexts. These options include mutual authentication, replay detection, and sequence detection. A security package sets the SECPKG_FLAG_CONNECTION flag to indicate that it supports connection semantics.

A datagram context, or connectionless context, has slightly different semantics from a connection context. A connectionless context implies that the server has no way of determining when the client has shut down or otherwise terminated the connection. In other words, no termination notice is passed from the transport application to the server, as would occur in a connection context. A security package sets the SECPKG_FLAG_DATAGRAM flag to indicate that it supports datagram semantics. If a client specifies the ISC_REQ_DATAGRAM flag in its call to the InitializeSecurityContext function, the following characteristics apply:

• The security package does not produce an authentication binary large object (BLOB) on the first call to InitializeSecurityContext. However, the client can immediately use the returned security context in a call to the MakeSignature function to generate a message signature.
• The security package must enable the context to be reestablished multiple times to enable the server to drop the connection without notice. This also implies that any keys used in the MakeSignature and VerifySignature functions can be reset to a consistent state. For more information on key states, see Cryptography.
• The security package must enable the caller to specify sequence data, and must enable the receiver to return that same sequence data back to the caller. This is not exclusive of any sequence data maintained by the package.

A stream context is different from a connection context and a datagram context. A stream context handles secure stream protocols. A security package that supports stream contexts has the following characteristics:

• The package sets the SECPKG_FLAG_STREAM flag to indicate that it supports stream semantics, just as it would set a flag to indicate support for connection and datagram semantics.
• A transport application requests stream semantics by setting the ISC_REQ_STREAM and ASC_REQ_STREAM flags in the calls to the InitializeSecurityContext and AcceptSecurityContext functions.
• The application calls the QueryContextAttributes 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 extra buffer descriptors during actual data processing.

By specifying stream semantics, the caller indicates it will perform extra operations so that the security provider can block messages. These extra operations include passing a list of buffers when the MakeSignature and VerifySignature functions are called. When a message is received from a stream-oriented channel, the caller passes a buffer. The following table shows the buffers.

The security package then authenticates the BLOB. The following table shows what the buffer list looks like, if the function returns successfully.

The following table shows an alternate return value for buffer 4.

The buffer listed in the previous table indicates data in this buffer is part of the next record, and has not yet been processed.

Conversely, the following table shows what the returned buffer list would look like if the message function returns the SEC_E_INCOMPLETE_MESSAGE error message.

The buffer described in this table indicates that more data is 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. Security providers must not update their state in this condition.

Similarly, on the sender's side of the communication, the caller can call MakeSignature, in which case the security package may need to reallocate the buffer. The following table shows the buffer list that the caller can provide to be more efficient.

Using a buffer, like the one described in the previous table, enables the caller to use 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.