White Paper
© 1996 Microsoft Corporation. All rights reserved.
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.
This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.
Microsoft, MS-DOS, Win32, Windows, and Windows NT are registered trademarks and the BackOffice logo is a trademark of Microsoft Corporation in the United States and/or other countries.
Macintosh is a registered trademark of Apple Computer, Inc.
Other product or company names mentioned herein may be the trademarks of their respctive owners.
1196
Abstract
Microsoft Security Support Provider Interface (SSPI) is the well-defined common API for obtaining integrated security services for authentication, message integrity, message privacy, and security quality of service for any distributed application protocol. Application protocol designers can take advantage of this interface to obtain different security services without modification to the protocol itself.
This white paper describes how SSPI APIs can be used directly, as well as through other application interfaces, such as DCOM, secure RPC, WinSock 2.0, and WinInet.
Introduction
Microsoft's Security Support Provider Interface (SSPI) is the Win32 interface between transport level applications and network security service providers. The interface is not specific to the Microsoft Windows NT network operating system; it is also supported by the Microsoft RPC run time for the
Windows 95 operating system, as well as the RPC run time for MS-DOS®, Windows 3.11, and Macintosh operating system.
This paper describes Microsoft SSPI and discusses the following issues:
To unfold the SSPI story, the paper will start with a review of the SSPI APIs and how to integrate Windows NT authentication, message integrity, and privacy into distributed applications. Then the paper will look at how application developers use the DCOM application framework and authenticated RPC to take advantage of SSPI services from higher-level interfaces. Finally, the paper will look at other examples of how SSPI security services are available using application level interfaces such as WinSock 2.0 and WinInet.
The diagram below shows where the SSPI security services fit into the overall distributed application architecture.
Figure 1: Where does SSPI fit in the Windows NT Security Model?
The architecture diagram shows that application developers have many options today for building distributed applications. The SSPI provides an abstraction layer between application-level protocols and security protocols. But there are many ways to take advantage of integrated security protocols and one approach might be better than another to fit the application design. Here are some of the ways to use SSPI services:
The organization of the rest of the document is designed to help both application developers and security support provider writers understand how to use SSPI. First the paper will review the SSPI APIs and the security provider concepts. Then the paper will describe how SSPI APIs are used to establish secure connections, with descriptions of the SSPI-related samples in the Windows NT SDK.
SSPI API
The Security Support Provider Interface (SSPI) provides a common interface between transport-level applications, such as Microsoft RPC or a file system redirector, and security providers, such as Windows NT Distributed Security. SSPI provides a mechanism by which a distributed application can call one of several security providers to obtain an authenticated connection without knowledge of the details of the security protocol.
SSPI consists of following APIs:
Credential Management APIs—Credential Management APIs provide access to credentials (password data, tickets, and so on) of a principal or free such access. The APIs are:
AcquireCredentialsHandle—This method acquires a handle to the reference credentials.
FreeCredentialsHandle—This method releases a credential handle and associated resources.
QueryCredentialAttributes—This method allows queries on various credential attributes like associated name, domain name, and so forth.
Context Management APIs—Context management APIs provide methods for creating and using security contexts. The contexts are created on both the client and the server side of a communication link. These contexts can then be used later with the message support APIs. The APIs are:
InitializeSecurityContext—Initiates a security context by generating an opaque message (security token) that can be passed to the server.
AcceptSecurityContext—Creates a security context using the opaque message received from the client.
DeleteSecurityContext—Frees a security context and associated
resources.
QueryContextAttributes—Allows queries on various context attributes.
ApplyControlToken—Applies a supplemental security message to an existing security context.
CompleteAuthToken—Completes an authentication token, since some protocols, like DCE RPC, need to revise the security information once the transport has updated some message fields.
ImpersonateSecurityContext—Attaches the client's security context as an impersonation token to the calling thread.
RevertSecurityContext—Ceases impersonation and defaults the calling thread to its primary token.
Message Support APIs—Message support APIs provide communication integrity and privacy services based on a security context. The APIs are:
MakeSignature—Generates a secure signature based on a message and a security context.
VerifySignature—Verifies that the signature matches a received message.
Package Management APIs—Package Managment APIs provide services for different security packages that the security provider supports. The APIs are:
EnumerateSecurityPackages—Lists available security packages and their capabilities.
QuerySecurityPackageInfo—Queries an individual security package for its capabilities.
SSPI does not currently provide any public interfaces for encryption/decryption functionality. Future versions of the SSPI will make message support routines for encryption available.
A security provider is a dynamic-link library that implements the Security Support Provider Interface and makes one or more security packages available to applications. A security package maps the SSPI functions to an implementation of the security protocol specific to that package, such as NTLM, Kerberos, or SSL. Security packages are sometimes referred to as "SSPs," such as the "NTLM SSP." The name of the security package is used in the initialization step to identify a specific package.
The Security Support Provider Interface allows an application to use any of the available security packages on a system without changing the interface to use security services. SSPI does not establish logon credentials because that is generally a privileged operation handled by the operating system.
An application can use the package management functions to list the security packages available and select one to support its needs. The application then uses the credential management functions to obtain a handle to the credentials of the user on whose behalf they are executing. With this handle, the application can use the context management functions to create a security context to a service. A security context is an opaque data structure that contains the security data relevant to a connection, such as a session key, the duration of the session, and so on. Finally, the application uses the security context with the message support functions to ensure message integrity and privacy during the connection.