Authentication functions are categorized according to usage as follows:
SSPI Functions
Security Support Provider Interface (SSPI) functions fall into the following major categories.
Package Management
SSPI package management functions initiate a security package, enumerate available packages, and query the attributes of a security package.
The following SSPI functions provide management services for security packages.
| Function | Description |
| EnumerateSecurityPackages |
Lists available security packages and their capabilities.
|
| InitSecurityInterface |
Retrieves a pointer to a security support provider (SSP) dispatch table.
|
| QuerySecurityPackageInfo |
Retrieves information about a specified security package. This information includes the bounds on sizes of authentication information, credentials, and contexts.
|
Credential Management
SSPI credential management functions provide a credentials handle, a reference to an opaque security object, for accessing a principal. The security object is opaque because the application has access only to the handle and not to the actual contents of the structure.
All references to the contents of a credential context are through the object's handle and the security package dereferences the handle to access the specifics of credentials. A credential handle is a 64-bit value between {0x00000000, 0x00000000} and {0xFFFFFFFF, 0xFFFFFFFE}.
Applications use the credentials handle with
context management functions to create a security context.
Credential management functions also release credential handles and query the attributes of credentials. At present, the name associated with a credential is the only attribute that can be queried.
The following functions are used with credentials management.
Context Management
SSPI context management functions create and use security contexts.
In a communication link, the client and server cooperate to create a shared security context. The client and server both use the security context with
message support functions to ensure message integrity and privacy during the connection.
Security contexts are opaque security objects. Information in the security context is not available to the application. Context management functions create and use context handles and the security package dereferences the context handle to access its security content.
A context handle is a 64-bit value between {0x00000000, 0x00000000} and {0xFFFFFFFF, 0xFFFFFFFE}.
The following functions are used with context management.
Message Support
SSPI message support functions enable an application to transmit and receive tamper-resistant messages and to encrypt and decrypt messages. These functions work with one or more buffers that contain a message and with a security context created by the
context management functions. The functions' behavior differs based on whether a connection, datagram, or stream context is in use. For a description of these differences, see
SSPI Context Semantics.
The following functions provide security support for messages.
| Function | Description |
| DecryptMessage (General) |
Decrypts an encrypted message by using the session key from a security context.
|
| EncryptMessage (General) |
Encrypts a message by using the session key from a security context.
|
| MakeSignature |
Generates a cryptographic checksum of the message, and also includes sequencing information to prevent message loss or insertion.
|
| VerifySignature |
Verifies the signature of a message received that was signed by the sender by using the
MakeSignature function.
|
Functions Implemented by SSP/APs
The following functions are implemented by
security packages contained in Security Support Provider/Authentication Packages (SSP/APs).
In the following tables, the first set of functions is implemented by Windows XP and Windows 2000 SSP/AP security packages. The second set of functions is implemented by SSP/AP security packages only.
The Local Security Authority (LSA) accesses these functions by using the
SECPKG_FUNCTION_TABLE structure provided by the SSP/AP's
SpLsaModeInitialize function.
The following functions are implemented by all authentication packages.
| Function | Description |
| LsaApCallPackage |
Called by the Local Security Authority (LSA) when a logon application with a trusted connection to the LSA calls the
LsaCallAuthenticationPackage function and specifies the authentication package's identifier.
|
| LsaApCallPackagePassthrough |
The dispatch function for pass-through logon requests sent to the
LsaCallAuthenticationPackage function.
|
| LsaApCallPackageUntrusted |
Called by the Local Security Authority (LSA) when an application with an untrusted connection to the LSA calls the
LsaCallAuthenticationPackage function and specifies the authentication package's identifier.
|
| LsaApInitializePackage |
Called once by the Local Security Authority (LSA) during system initialization to provide the authentication package a chance to initialize itself.
|
| LsaApLogonTerminated |
Used to notify an authentication package when a logon session terminates.
A logon session terminates when the last token referencing the logon session is deleted.
|
| LsaApLogonUser |
Authenticates a user's logon credentials.
|
| LsaApLogonUserEx |
Authenticates a user's logon credentials.
|
| LsaApLogonUserEx2 |
Used to authenticate a user logon attempt on the user's initial logon.
A new logon session is established for the user, and validation information for the user is returned.
|
The following additional functions are implemented by SSP/AP security packages.
Functions Implemented by User-mode SSP/APs
The following functions are implemented by security support provider/authentication packages (SSP/APs) that can be loaded into client/server applications.
An SSP/AP indicates that it implements the user-mode functions by returning TRUE in the MappedContext parameter of the
SpInitLsaModeContext and
SpAcceptLsaModeContext functions. The SpInitLsaModeContext function is used by the client side of a transport level application, while SpAcceptLsaModeContext is used by the server side.
Loading an SSP/AP into the client process or server process is handled by the security provider DLL, either Security.dll or Secur32.dll. The security provider DLL loads the SSP/AP by locating the address of the
SpUserModeInitialize function implemented by the SSP/AP and calling it. This function returns a set of tables that contain pointers to the user-mode functions implemented in each security package.
After the SSP/AP is loaded into the client or server process, the Local Security Authority (LSA) will copy the security context information (returned by
SpInitLsaModeContext or
SpAcceptLsaModeContext) and any additional context-related data to the process and call the security package's
SpInitUserModeContext function.
Client/server applications access user-mode functionality by calling
Security Support Provider Interface (SSPI) functions. The SSPI functions are mapped by the security provider DLL by using the
SECPKG_USER_FUNCTION_TABLE supplied by the package.
| Function | Description |
| SpCompleteAuthToken |
Completes an authentication token.
Implements the SSPI
CompleteAuthToken function.
|
| SpDeleteContext |
Deletes a security context.
Implements the SSPI
DeleteSecurityContext function.
|
| SpExportSecurityContext |
Exports a security context to another process.
Implements the SSPI
ExportSecurityContext function.
|
| SpFormatCredentials |
Formats credentials to be stored in a user object.
|
| SpGetContextToken |
Obtains the token to impersonate.
Used by the SSPI
ImpersonateSecurityContext function.
|
| SpImportSecurityContext |
Imports a security context from another process.
Implements the SSPI
ImportSecurityContext function.
|
| SpInitUserModeContext |
Creates a user-mode security context from a packed Local Security Authority (LSA)-mode context.
|
| SpInstanceInit |
Initializes user-mode security packages in an SSP/AP.
|
| SpMakeSignature |
Generates a signature based on the specified message and security context.
Implements the SSPI
MakeSignature function.
|
| SpMarshallSupplementalCreds |
Converts supplemental credentials from a public format into a format suitable for local procedure calls.
|
| SpQueryContextAttributes |
Retrieves the attributes of a security context.
Implements the SSPI
QueryContextAttributes (General) function.
|
| SpSealMessage |
Encrypts a message exchanged between a client and server.
Implements the SSPI
EncryptMessage (General) function.
|
| SpUnsealMessage |
Decrypts a message that was previously encrypted with the
SpSealMessage function.
Implements the SSPI
DecryptMessage (General) function.
|
| SpUserModeInitialize |
Called when a security support provider/authentication package (SSP/AP) DLL is loaded into the process space of a client/server application. This function provides the
SECPKG_USER_FUNCTION_TABLE tables for each security package in the SSP/AP DLL.
|
| SpVerifySignature |
Verifies that the message received is correct according to the signature.
Implements the SSPI
VerifySignature function.
|
LSA Functions Called by SSP/APs
The Local Security Authority (LSA) provides the following functions to security packages deployed in security support provider/authentication packages (SSP/APs). The functions are available in the
LSA_SECPKG_FUNCTION_TABLE structure and can be called while the SSP/AP is loaded into the LSA's process space. The following functions are available to all APs.
The following functions are available to SSP/APs.
LSA Functions Called By User-mode SSP/APs
A security package in a security support provider/authentication package (SSP/AP) executing in a user-mode process can use the pointers in the
SECPKG_DLL_FUNCTIONS table to access the following functions.
| Function | PSDK status |
| AllocateHeap |
Allocates memory for buffers that are returned to the Local Security Authority (LSA).
|
| FreeHeap |
Frees memory that was previously allocated by using AllocateHeap.
|
| RegisterCallback |
Registers user-mode callback functions.
|
GINA Export Functions
A GINA DLL must export the following functions.
Note GINA DLLs are ignored in Windows Vista.
| Function | Description |
| WlxActivateUserShell |
Activates the user shell program.
|
| WlxDisplayLockedNotice |
Allows the GINA to display information about the lock, such as who locked the workstation and when it was locked.
|
| WlxDisplaySASNotice |
Winlogon calls this function when no user is logged on.
|
| WlxDisplayStatusMessage |
Winlogon calls this function when the GINA DLL should display a message.
|
| WlxGetConsoleSwitchCredentials |
Winlogon calls this function to read the currently logged on user's credentials to transparently transfer them to a target session.
|
| WlxGetStatusMessage |
Winlogon calls this function to get the status message being displayed by the GINA DLL.
|
| WlxInitialize |
Winlogon calls this function once for each window station present on the computer. Currently, the operating system supports one window station per workstation.
|
| WlxIsLockOk |
Winlogon calls this function before attempting to lock the workstation.
|
| WlxIsLogoffOk |
Winlogon calls this function when the user initiates a logoff operation.
|
| WlxLoggedOnSAS |
Winlogon calls this function when it receives a secure attention sequence (SAS) event while the user is logged on and the workstation is not locked.
|
| WlxLoggedOutSAS |
Winlogon calls this function when it receives a secure attention sequence (SAS) event while no user is logged on.
|
| WlxLogoff |
Winlogon calls this function to notify the GINA of a logoff operation on this workstation, allowing the GINA to perform any logoff operations that may be required.
|
| WlxNegotiate |
The WlxNegotiate function must be implemented by a replacement GINA DLL. This is the first call made by Winlogon to the GINA DLL. WlxNegotiate allows the GINA to verify that it supports the installed version of Winlogon.
|
| WlxNetworkProviderLoad |
Winlogon calls this function to collect valid authentication and identification information.
|
| WlxRemoveStatusMessage |
Winlogon calls this function to tell the GINA DLL to stop displaying the status message.
|
| WlxScreenSaverNotify |
Winlogon calls this function immediately before a screen saver is activated, allowing the GINA to interact with the screen saver program.
|
| WlxShutdown |
Winlogon calls this function just before shutting down, allowing the GINA to perform any shutdown tasks, such as ejecting a smart card from a reader.
|
| WlxStartApplication |
Winlogon calls this function when the system needs an application to be started in the context of the user.
|
| WlxWkstaLockedSAS |
Winlogon calls this function when it receives a secure attention sequence (SAS) and the workstation is locked.
|
Logon User Functions
The following functions provide the ability to log on a user.
| Function | Description |
| LogonUser |
Attempts to log a user on to the local computer.
|
| LogonUserEx |
Attempts to log a user on to the local computer. This function is an extended version of the LogonUser function and retrieves information about the logged-on user's security identifier (SID), profile, and quota limits.
|
| LogonUserExExW |
The LogonUserExExW function attempts to log a user on to the local computer. This function is not declared in a public header and has no associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to Advapi32.dll.
|
Winlogon Support Functions
GINA DLLs can call the following Winlogon support functions.
Note GINA DLLs are ignored in Windows Vista.
| Function | Called by GINA |
| WlxAssignShellProtection |
Called by GINA to assign protection to the shell program of a newly logged-on user.
|
| WlxChangePasswordNotify |
Called by GINA to indicate it has changed a password.
|
| WlxChangePasswordNotifyEx |
Called by GINA to tell a specific network provider (or all network providers) that a password has changed.
|
| WlxCloseUserDesktop |
Called by GINA to close an alternate user desktop and clean up after the desktop is closed.
|
| WlxCreateUserDesktop |
Called by GINA to create alternate application desktops for the user.
|
| WlxDialogBox |
Called by the GINA to create a modal dialog box from a dialog box template.
|
| WlxDialogBoxIndirect |
Called by GINA to create a modal dialog box from a dialog box template in memory.
|
| WlxDialogBoxIndirectParam |
Called by GINA to initialize dialog box controls and then create a modal dialog box from a dialog box template in memory.
|
| WlxDialogBoxParam |
Called by GINA to initialize dialog box controls and then create a modal dialog box from a dialog box template resource.
|
| WlxDisconnect |
Called by a replacement GINA DLL if Terminal Services is enabled. GINA calls this function to disconnect from a Terminal Services network session.
|
| WlxGetOption |
Called by GINA to retrieve the current value of an option.
|
| WlxGetSourceDesktop |
Called by GINA to determine the name and handle of the desktop that was current before Winlogon switched to the Winlogon desktop.
|
| WlxMessageBox |
Called by GINA to create, display, and operate a message box.
|
| WlxQueryClientCredentials |
Called by a replacement GINA DLL if Terminal Services is enabled. GINA calls this function to retrieve the credentials of remote Terminal Services clients that are not using an Internet connector license.
|
| WlxQueryConsoleSwitchCredentials |
Called by GINA to read the credentials transferred from the Winlogon of the temporary session to the Winlogon of the destination session.
|
| WlxQueryInetConnectorCredentials |
Called by a replacement GINA DLL if Terminal Services is enabled.
GINA calls this function to determine whether the terminal server is using Internet connector licensing and to retrieve credentials information.
|
| WlxQueryTerminalServicesData |
Called by GINA to retrieve Terminal Services user configuration information after a user has logged on.
|
| WlxSasNotify |
Called by GINA to notify Winlogon of a secure attention sequence (SAS) event.
|
| WlxSetContextPointer |
Called by GINA to specify the context pointer passed by Winlogon as the first parameter to all future calls to GINA functions.
|
| WlxSetOption |
Called by GINA to set the value of an option.
|
| WlxSetReturnDesktop |
Called by GINA to specify the alternate application desktop that Winlogon will switch to when the current secure attention sequence (SAS) event processing function is complete.
|
| WlxSetTimeout |
Called by GINA to change the time-out associated with a dialog box. The default time-out is two minutes.
|
| WlxSwitchDesktopToUser |
Called by GINA to switch to the application desktop.
|
| WlxSwitchDesktopToWinlogon |
Lets the GINA DLL switch to the Winlogon desktop.
|
| WlxUseCtrlAltDel |
Called by GINA to tell Winlogon to use the standard CTRL+ALT+DEL key combination as a secure attention sequence (SAS).
|
| WlxWin31Migrate |
Called by a replacement GINA DLL if Terminal Services is enabled.
GINA calls this function to complete the setup of the Terminal Services client.
|
Network Provider Functions
The following topics provide reference information for the network provider functions.
| Topic | Description |
| Functions Implemented by Network Providers |
Details functions that can be implemented by network providers.
|
| Support Functions |
Details a function that is implemented by the operating system and can be called by network providers.
|
| Connection Notification Functions |
Details functions that are implemented by applications that need to receive notification from the Multiple Provider Router (MPR) when a network resource is connected or disconnected.
|
Functions Implemented by Network Providers
The following functions can be implemented by network providers. The only function that network providers are required to support is NPGetCaps.
| Function | Description |
| NPAddConnection |
Connects a local device to a network resource.
|
| NPAddConnection3 |
Connects a local device to a network resource.
|
| NPCancelConnection |
Disconnects a network connection.
|
| NPCloseEnum |
Closes an enumeration.
|
| NPDeviceMode |
Specifies the parent window of a device. This window owns any dialog boxes that originate from the device.
|
| NPDirectoryNotify |
Notifies the network provider of certain directory operations.
|
| NPEnumResource |
Performs an enumeration based on a handle returned by
NPOpenEnum.
|
| NPFormatNetworkName |
Formats a network name in a provider-specific format for display in a control.
|
| NPGetCaps |
Returns information about which services are supported on the network.
|
| NPGetConnection |
Retrieves information about a connection.
|
| NPGetConnection3 |
Retrieves information about a network connection, even if it is currently disconnected.
|
| NPGetConnectionPerformance |
Returns information about the expected performance of a connection used to access a network resource. The request can only be for a network resource that is currently connected.
|
| NPGetDirectoryType |
Determines the type of a network directory.
|
| NPGetPropertyText |
Retrieves the names of buttons to add to a property dialog box for a network resource.
|
| NPGetResourceInformation |
Separates the part of a network resource accessed through the WNet API from the part accessed through APIs specific to the resource type.
|
| NPGetResourceParent |
Retrieves the parent of a specified network resource in the browse hierarchy.
|
| NPGetUniversalName |
Retrieves the universal name of a network resource. The NPGetUniversalName function can retrieve this universal name in UNC format or in the older, remote-name format.
|
| NPGetUser |
Retrieves the value of the current default user name or the user name used to establish a network connection.
|
| NPOpenEnum |
Opens an enumeration of network resources or existing connections. The NPOpenEnum function must be called to obtain a valid handle for an enumeration.
|
| NPPropertyDialog |
Called when the user clicks a button added by using the NPPropertyDialog function. The NPPropertyDialog function is called only for file and directory network properties.
|
| NPSearchDialog |
Enables network vendors to supply their own form of browsing and search, beyond the hierarchical view presented in the Connection dialog box.
|
Support Functions
The following function is implemented by the operating system and can be called by network providers.
Connection Notification Functions
The following functions are implemented by applications that need to receive notification from the Multiple Provider Router (MPR) when a network resource is connected or disconnected. For more information about how to write an application that receives such notifications, see
Receiving Connection Notifications.
LSA Logon Functions
The following Local Security Authority (LSA) authentication functions authenticate and log on users, and they provide logon session information.
Functions Implemented by Authentication Packages
Custom authentication packages must implement these functions, which are called by the Local Security Authority (LSA). These functions are implemented by the MSV1_0 and Kerberos authentication packages provided by Microsoft.
| Function | Description |
| LsaApCallPackage |
Called when the authentication package's identifier has been specified in a call to LsaCallAuthenticationPackage by an application that is using a trusted connection.
This function provides a way for logon applications to communicate directly with authentication packages.
|
| LsaApCallPackagePassthrough |
Called when the authentication package's identifier has been specified in a call to LsaCallAuthenticationPackage for a pass-through logon request.
|
| LsaApCallPackageUntrusted |
Called when the authentication package's identifier has been specified in a call to LsaCallAuthenticationPackage by an application using an untrusted connection. This function is used for communicating with processes that do not have the SeTcbPrivilege privilege.
|
| LsaApInitializePackage |
Called during system initialization to permit the authentication package to perform initialization tasks.
|
| LsaApLogonTerminated |
Called when a logon session ends to permit the authentication package to free any resources allocated for the logon session.
|
| LsaApLogonUser |
Called when the authentication package has been specified in a call to LsaLogonUser. This function authenticates a security principal's logon data.
|
| LsaApLogonUserEx |
Identical to LsaApLogonUser except that it returns the workstation name for audit purposes.
An authentication package can implement LsaApLogonUser, LsaApLogonUserEx, or LsaApLogonUserEx2. It does not need to implement them all.
|
| LsaApLogonUserEx2 |
Identical to LsaApLogonUserEx except that it returns the security principal's primary and supplemental credentials. An authentication package can implement LsaApLogonUser, LsaApLogonUserEx, or LsaApLogonUserEx2. It does not need to implement them all.
|
LSA Functions Called by Authentication Packages
The following Local Security Authority (LSA) functions can be called from a custom authentication package. When the LSA calls
LsaApInitializePackage to initialize the package, it passes a table of support functions.
| Function | Description |
| AddCredential |
Adds credentials to a logon session.
|
| AllocateClientBuffer |
Allocates a buffer in the client's address space.
|
| AllocateLsaHeap |
Allocates buffers that must be returned from the authentication package to the LSA.
|
| CopyFromClientBuffer |
Copies the contents of a buffer in the client's address space into a local buffer.
|
| CopyToClientBuffer |
Copies the contents of a local buffer into the client's address space.
|
| CreateLogonSession |
Used by authentication packages to create a logon session.
|
| DeleteCredential |
Deletes an existing credential.
|
| DeleteLogonSession |
Cleans up any logon sessions created while determining whether a user's authentication information is legitimate.
|
| FreeClientBuffer |
Frees a client buffer previously allocated with the
AllocateClientBuffer function.
|
| FreeLsaHeap |
Frees buffers previously allocated by using the AllocateLsaHeap function.
|
| GetCredentials |
Retrieves credentials previously cached by AddCredential.
|
Subauthentication Functions
The following subauthentication functions can be called by Microsoft-provided authentication packages to provide additional, user-created logon authentication.
Credentials Management Functions
The following topics provide reference information for the credentials management functions.
| Topic | Description |
| Credentials Management UI Functions |
Details functions used for credentials management UI.
|
| Low-level Credentials Management Functions |
Details functions used for low-level credentials management.
|
| Credential Management Notification Functions |
Details functions that are implemented by credential managers to receive notifications when authentication information changes.
|
Credentials Management UI Functions
The following are credentials management UI functions.
Low-level Credentials Management Functions
The following are low-level credentials management functions.
Credential Management Notification Functions
The following functions are implemented by credential managers to receive notifications when authentication information changes.
| Function | Description |
| NPLogonNotify |
MPR calls this function to notify the credential manager that a logon event has occurred, allowing the credential manager to return a logon script.
|
| NPPasswordChangeNotify |
MPR calls this function to notify the credential manager of a password change event.
|
Smart Card Functions
The Smart Card SDK provides the following functions.
SASL Functions
The Simple Authentication and Security Layer (SASL) provides the following functions.
Other Functions
Here are other functions used for Authentication.
Send comments about this topic to Microsoft
Build date: 11/19/2009