Edit

Using SecBufferDesc and SecBuffer

  • Article

Communication often involves potentially large amounts of data or data of unknown length. Sending and receiving data is done in similar or identical fashion in both of these cases. To deal with unknown length and potentially large amounts of data, SSPI communication is done using two structures, SecBufferDesc and SecBuffer.

A SecBufferDesc structure is a container for an array of SecBuffer structures. A SecBufferDesc structure has the following members:

  • Version number
  • Number of SecBuffer elements
  • Address of the array of SecBuffer structures

A SecBuffer structure contains the following three members:

  • Number of bytes in the buffer
  • Type of information contained in the data item
  • The bytes themselves

A whole SSPI message often consists of an array of SecBuffer structures.

The following buffer data types are defined as follows.

Buffer type Meaning
SECBUFFER_EMPTY Undefined, replaced by the security package function
SECBUFFER_DATA Packet data
SECBUFFER_TOKEN Security token
SECBUFFER_PKG_PARAMS Package-specific parameters
SECBUFFER_MISSING Missing data indicator
SECBUFFER_EXTRA Extra data
SECBUFFER_STREAM Security stream data
SECBUFFER_STREAM_TRAILER Security stream trailer
SECBUFFER_STREAM_HEADER Security stream header

 

The buffer types above can be combined using a bitwise-OR operation with either of the following buffer types.

Buffer type Meaning
SECBUFFER_ATTRMASK Mask security attributes by separating the attribute flags from the buffer type.
SECBUFFER_READONLY Buffer is read-only

 

Before each call to an SSPI API that requires a SecBufferDesc parameter, one or more SecBuffer array elements are declared and initialized. For example, there can be two security buffers: one that contains input message data and the other for the output opaque security token returned by the security package. The order of security buffers in the security buffer descriptor is not important, but each buffer must be tagged with its appropriate type. A read-only tag can be used with any input buffer that must not be modified by the security package.

The size of the output buffer that is expected to contain the security token is important. An application can find the maximum token size for a security package during initial setup. The call to EnumerateSecurityPackages returns an array of pointers to security package information. The security package information structure contains the maximum token size for each package. In the example, the information is in the cbMaxToken member of the SecPkgInfo structure. The same information can be obtained later using QuerySecurityPackageInfo.

The application initializes the buffer pointers and sizes in the buffer description to indicate where message data and other information can be found.

For details, see SecBuffer and SecBufferDesc Example Code.