Using SecBufferDesc and SecBuffer
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:
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.