Edit

Share via

Security Service Providers

  • Article

The Security Service Provider Interface (SSPI) provides a universal, industry-standard interface for secure distributed applications. The Peer Graphing API provides a way for applications to secure links in a graph by specifying a Security Service Provider (SSP), which is a DLL that implements an SSPI interface. An application specifies an SSP when it creates a graph by using PeerGraphCreate.

For more information about creating your own SSP, see the SSPI documentation link in the list of Graphing Reference Links.

Programming Considerations for Implementing an SSP

Use caution when calling into an application from within an SSP. The following considerations apply to SSP callbacks:

  • Callbacks should not take a long time to return, because they are called during connection negotiation. If it takes too long for a connection to be established, the connection can be dropped.
  • The Peer Graphing API dynamically adjusts connection timeout values, based on the actual load of a system. The lowest timeout value is 20 seconds.
  • To avoid potential deadlock situations, an application must not access the peer graphing database from a callback. If an application requires information from the graphing database, the application can cache the necessary information, and then refer to the cache from within the callback. Caching can also help decrease connection time.

When calling the SSPI entry points, the Peer Graphing Infrastructure requires specific values for specific parameters of five (5) functions. You cannot change these parameter values provided to SSP, and the SSP can either ignore the values for the five parameters or handle them gracefully. The following list identifies these specific parameters and required values:

  • AcquireCredentialsHandle

    Specify one (1) for the pvGetKeyArgument parameter. Specifies NULL for the pszPrincipal, pvLogonID, and pGetKeyFn parameters.

  • InitializeSecurityContext

    Specify the following flags for the fContextReq parameter: ISC_REQ_MUTUAL_AUTH | ISC_REQ_CONFIDENTIALITY | ISC_REQ_INTEGRITY | ISC_REQ_SEQUENCE_DETECT | ISC_REQ_STREAM | ISC_REQ_ALLOCATE_MEMORY.

  • AcceptSecurityContext

    Specify the following flags for the fContextReq parameter: ASC_REQ_MUTUAL_AUTH | ASC_REQ_CONFIDENTIALITY | ASC_REQ_INTEGRITY | ASC_REQ_SEQUENCE_DETECT | ASC_REQ_STREAM | ASC_REQ_ALLOCATE_MEMORY.

  • EncryptMessage

    Specify zero (0) for the fQOP and MessageSeqNo parameters.

  • DecryptMessage

    Specify zero (0) for the MessageSeqNo parameter and NULL for the pfQOP parameter.

When calling EncryptMessage, four buffers are passed in the SecBufferDesc structure. The following table identifies the order to pass the buffers.

SSP-specific structure Description
SECBUFFER_STREAM_HEADER Contains the security header data. The size of the header buffer is obtained by calling QueryContextAttributes and specifying the SECPKG_ATTR_STREAM_SIZES attribute.
SECBUFFER_DATA Contains the plain-text message to be encrypted.
SECBUFFER_STREAM_TRAILER Contains the security trailer data. The size of the header buffer is obtained by calling QueryContextAttributes and specifying the SECPKG_ATTR_STREAM_SIZES attribute.
SECBUFFER_EMPTY Not initialized. The size of this buffer is zero (0).

 

When calling DecryptMessage, the Peer Graphing API passes exactly four SecBuffer structures. The first buffer is SECBUFFER_DATA, and contains an encrypted message. The remaining buffers are used for output, and are of type SECBUFFER_EMPTY.

The SSP needs to support encrypting and decrypting user data buffers with sizes of 16K and greater in one call.