Authentication Functions

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.

FunctionDescription
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.

FunctionDescription
AcquireCredentialsHandle (General)

Acquires a handle to the preexisting credentials of a specified principal.

ExportSecurityContext

Exports a security context into a context buffer.

FreeCredentialsHandle

Releases a credential handle and associated resources.

ImportSecurityContext

Imports a security context exported by using ExportSecurityContext into the current process.

QueryCredentialsAttributes

Retrieves the attributes of a credential, such as the name associated with the credential.

 

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.

FunctionDescription
AcceptSecurityContext (General)

Used by a server to create a security context based on an opaque message received from a client.

ApplyControlToken

Applies a supplemental security message to an existing security context.

CompleteAuthToken

Completes an authentication token. This function is used by protocols, such as DCE, that need to revise the security information after the transport application has updated some message parameters.

DeleteSecurityContext

Frees a security context and associated resources.

FreeContextBuffer

Frees a memory buffer allocated by a security package.

ImpersonateSecurityContext

Impersonates the security context to appear as the client to the system.

InitializeSecurityContext (General)

Used by a client to initiate a security context by generating an opaque message to be passed to a server.

QueryContextAttributes (General)

Enables a transport application to query a security package for certain attributes of a security context.

QuerySecurityContextToken

Obtains the access token for a client security context and uses it directly.

SetContextAttributes

Enables a transport application to set attributes of a security context for a security package. This function is supported only by the Schannel security package.

RevertSecurityContext

Allows a security package to discontinue the impersonation of the caller and restore its own security context.

 

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.

FunctionDescription
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 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.

FunctionDescription
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.

FunctionDescription
SpAcceptCredentials

Called by the Local Security Authority (LSA) to pass the security package any credentials stored for the authenticated security principal.

SpAcceptLsaModeContext

Server dispatch function used to create a security context shared by a server and client.

SpAcquireCredentialsHandle

Called to obtain a handle to a principal's credentials.

SpAddCredentials

Used to add credentials for a security principal.

SpApplyControlToken

Applies a control token to a security context. This function is not currently called by the Local Security Authority (LSA).

SpDeleteContext

Deletes a security context.

SpDeleteCredentials

Deletes credentials from a security package's list of primary or supplemental credentials.

SpFreeCredentialsHandle

Frees credentials acquired by calling the SpAcquireCredentialsHandle function.

SpGetCredentials Retrieves user credentials.
SpGetExtendedInformation

Provides extended information about a security package.

SpGetInfo

Provides general information about the security package, such as its name and capabilities.

SpGetUserInfo

Retrieves information about a logon session.

SPInitialize

Is called once by the Local Security Authority (LSA) to provide a security package with general security information and a dispatch table of support functions.

SpInitLsaModeContext

The client dispatch function used to establish a security context between a server and client.

SpQueryContextAttributes

Retrieves the attributes of a security context.

SpQueryCredentialsAttributes

Retrieves the attributes for a credential.

SpSaveCredentials

Saves a supplemental credential to the user object.

SpSetExtendedInformation

Sets extended information about the security package.

SpShutdown

Performs any cleanup required before the SSP/AP is unloaded.

SslCrackCertificate

Returns an X509Certificate structure with the information contained in the specified certificate BLOB.

SslEmptyCache

Removes the specified string from the Schannel cache.

SslFreeCertificate

Frees a certificate that was allocated by a previous call to the SslCrackCertificate function.

 

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.

FunctionDescription
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.

FunctionDescription
AddCredential

Adds user credentials.

AllocateClientBuffer

Allocates memory in the address space of the package's client.

AllocateLsaHeap

Allocates memory on the heap. Some information passed back to the LSA is expected to be allocated using this function.

CopyFromClientBuffer

Copies information from the address space of a client process into a buffer in the current process.

CopyToClientBuffer

Copies information from a buffer in the current process into a client process's address space.

CreateLogonSession

Creates logon sessions.

DeleteCredential

Deletes user credentials.

DeleteLogonSession

Deletes an LSA logon session.

FreeClientBuffer

Frees memory in the address space of the package's client.

FreeLsaHeap

Deallocates heap memory previously allocated by AllocateLsaHeap.

GetCredentials

Retrieves credentials associated with a logon session.

 

The following functions are available to SSP/APs.

FunctionDescription
AllocateSharedMemory

Allocates a section of shared memory.

AuditAccountLogon

Creates audit records for attempted logons.

AuditLogon

Creates an audit trail for a logon session.

CallPackage

Calls a package.

CallPackageEx

Calls another package.

CallPackagePassthrough

Calls one security package from another.

CancelNotification

Cancels notification for special events.

ClientCallback

Allows a security package to invoke a function in the client process.

For a ClientCallback function prototype, see ClientCallback Function Prototype.

CloseSamUser

Closes a handle to a Security Accounts Manager database entry.

ConvertAuthDataToToken

Converts authorization data to a user token.

CrackSingleName

Converts a name from one format to another.

CreateSharedMemory

Creates a section of memory shared between clients and the SSP/AP.

CreateThread

Creates a new thread.

CreateToken

Creates a token.

DeleteSharedMemory

Deletes a section of shared memory.

DuplicateHandle

Duplicates a handle.

FreeReturnBuffer

Frees a buffer allocated by the LSA.

FreeSharedMemory

Frees a section of shared memory.

GetAuthDataForUser

Retrieves authorization data for a user account.

GetCallInfo

Retrieves information about the most recent function call.

GetClientInfo

Retrieves information about the security package's user process.

GetUserAuthData

Returns the authorization data for a user.

GetUserCredentialsNot yet implemented.
ImpersonateClient

Called by security packages to impersonate the package user.

MapBuffer

Maps a SecBuffer structure into the address space of the security support provider/authentication package (SSP/AP).

OpenSamUser

Retrieves a handle to a user account in the Security Accounts Manager (SAM) database.

RegisterNotification

Provides a mechanism whereby the security package is notified. Notification can occur at fixed intervals, when an event object is signaled, or during certain system events.

SaveSupplementalCredentials

Obsolete. Do not use.

UnloadPackage

Unloads an security support provider/authentication package (SSP/AP).

UpdateCredentials

Provides a mechanism for one security package to notify other packages that the credentials for a logon session have changed.

 

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.

FunctionPSDK 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.

FunctionDescription
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.

FunctionDescription
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.

FunctionCalled 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

Allows 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.

TopicDescription
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.

FunctionDescription
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.

FunctionDescription
WNetSetLastError

Sets extended error information. Network providers should call this function instead of SetLastError.

 

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.

FunctionDescription
AddConnectNotify

Called before and after each add connection operation (WNetAddConnection, WNetAddConnection2, and WNetAddConnection3).

CancelConnectNotify

Called before and after each cancel connection operation (WNetCancelConnection or WNetCancelConnection2).

 

LSA Logon Functions

The following Local Security Authority (LSA) authentication functions authenticate and log on users, and they provide logon session information.

FunctionDescription
LsaCallAuthenticationPackage

Requests a package-specific service from an authentication package.

LsaConnectUntrusted

Establishes an untrusted connection to the LSA.

LsaDeregisterLogonProcess

Disconnects from the LSA and frees resources allocated to the caller's context.

LsaEnumerateLogonSessions

Retrieves locally unique identifiers (LUIDs) for existing logon sessions.

LsaFreeReturnBuffer

Frees memory allocated for a buffer returned to a caller.

LsaGetLogonSessionData

Retrieves information about a specified logon session.

LsaLogonUser

Authenticates user logon data against stored credentials. If successful, it creates a new logon session and returns a user token.

LsaLookupAuthenticationPackage

Obtains the unique identifier of an authentication package.

LsaQueryDomainInformationPolicy

Retrieves domain information from the Policy object.

LsaQueryForestTrustInformation

Retrieves forest trust information for the specified Local Security Authority TrustedDomain object.

LsaRegisterLogonProcess

Establishes a connection to the LSA server and verifies that the caller is a logon application.

LsaSetDomainInformationPolicy

Sets domain information to the Policy object.

LsaSetForestTrustInformation

sets the forest trust information for a specified Local Security Authority TrustedDomain object.

 

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.

FunctionDescription
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.

FunctionDescription
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.

FunctionDescription
Msv1_0SubAuthenticationFilter

Performs user logon authentication that is specific to domain controllers.

Msv1_0SubAuthenticationRoutine

Performs client/server-specific authentication.

 

Credentials Management Functions

The following topics provide reference information for the credentials management functions.

TopicDescription
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.

FunctionDescription
CredUICmdLinePromptForCredentials

Prompt for and accept user credentials information from a user working in a command-line program.

CredUIConfirmCredentials

Confirm the validity of credentials returned by CredUIPromptForCredentials or CredUICmdLinePromptForCredentials.

CredUIParseUserName

Extract the domain and user account name from a fully qualified user name.

CredUIPromptForCredentials

Display a dialog box that accepts credentials information from a user.

CredUIPromptForWindowsCredentials

Creates and displays a configurable dialog box that allows users to supply credential information by using any credential provider installed on the local computer.

CredUIReadSSOCredW

Retrieves the user name for a single logon credential.

CredUIStoreSSOCredW

Stores a single logon credential.

 

Low-level Credentials Management Functions

The following are low-level credentials management functions.

FunctionDescription
CredDelete

Delete a credential from a user's credentials set.

CredEnumerate

List the credentials in a user's credentials set.

CredFindBestCredential

Searches the Credentials Management (CredMan) database for the set of generic credentials that are associated with the current logon session and that best match the specified target resource.

CredFree

Free the memory used for a buffer returned by any of the credentials management functions.

CredGetSessionTypes

Retrieve the maximum persistence supported by the current logon session.

CredGetTargetInfo

Retrieve all known target name information for a named resource.

CredIsMarshaledCredential

Determines whether a specified user name string is a marshaled credential previously marshaled by CredMarshalCredential.

CredIsProtected

Specifies whether the specified credentials are encrypted by a previous call to the CredProtect function.

CredMarshalCredential

Transform a credential into a text string.

CredPackAuthenticationBuffer

Converts a string user name and password into an authentication buffer.

CredProtect

Encrypts the specified credentials so that only the current security context can decrypt them.

CredRead

Read a credential from a user's credentials set.

CredReadDomainCredentials

Read the domain credentials from a user's credentials set.

CredRename

Rename a credential from a user's credentials set.

CredUnmarshalCredential

Transform a marshaled credential string back into its nonmarshaled form.

CredUnPackAuthenticationBuffer

Converts an authentication buffer returned by a call to the CredUIPromptForWindowsCredentials function into a string user name and password.

CredUnprotect

Decrypts credentials that were previously encrypted by using the CredProtect function.

CredWrite

Create a new credential or modify an existing credential in a user's credentials set.

CredWriteDomainCredentials

Write domain credentials to a user's credentials set.

 

Credential Management Notification Functions

The following functions are implemented by credential managers to receive notifications when authentication information changes.

FunctionDescription
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.

FunctionDescription
GetOpenCardName

Replaced by SCardUIDlgSelectCard, which displays the smart card Select Card dialog box.

SCardAccessStartedEvent Gets an event handle when the starting of a smart card resource manager is signaled.
SCardAddReaderToGroup Adds a reader to a reader group.
SCardAudit Writes event messages to the Windows application log Microsoft-Windows-SmartCard-Audit/Authentication.
SCardBeginTransaction Starts a transaction.
SCardCancel Terminates all outstanding actions within a context.
SCardCancelTransactionReserved for future use.
SCardConnect Establishes a connection between the calling application and a smart card.
SCardControl Gets direct control of the reader after SCardConnect is called.
SCardDisconnect Terminates a connection between the calling application and a smart card.
SCardEndTransaction Completes a transaction.
SCardEstablishContext Establishes a resource manager context for accessing the smart card database.
SCardForgetCardType Removes a previously defined smart card from the smart card subsystem.
SCardForgetReader Removes a previously defined reader from the smart card subsystem.
SCardForgetReaderGroup Removes a previously defined reader group from the smart card subsystem.
SCardFreeMemory Releases memory allocated by resource manager.
SCardGetAttrib Gets the current reader's attributes from a given reader, driver, or smart card.
SCardGetCardTypeProviderName Gets the provider name given a card name and provider type.
SCardGetDeviceTypeId Gets the device type identifier of the card reader for the given reader name. This function does not affect the state of the reader.
SCardGetProviderId Gets the identifier (GUID) of the primary service provider for a smart card.
SCardGetReaderDeviceInstanceId Gets the device instance identifier of the card reader for the given reader name. This function does not affect the state of the reader.
SCardGetReaderIcon Gets an icon of the smart card reader for a given reader's name.
SCardGetStatusChange Blocks execution until status of the readers changes.
SCardGetTransmitCount Retrieves the number of transmit operations that have completed since the specified card reader was inserted.
SCardIntroduceCardType Introduces a new smart card to the smart card subsystem.
SCardIntroduceReader Introduces a new reader to the smart card subsystem.
SCardIntroduceReaderGroup Introduces a new reader group to the smart card subsystem.
SCardIsValidContext Verifies a smart card context handle.
SCardListCards Provides a list of smart cards already introduced to the subsystem.
SCardListInterfaces Provides a list of interfaces supplied by a given smart card.
SCardListReaderGroups Provides a list of reader groups already introduced to the subsystem.
SCardListReaders Provides a list of readers already introduced to the subsystem.
SCardListReadersWithDeviceInstanceId Gets the list of readers that have provided a device instance identifier. This function does not affect the state of the reader.
SCardLocateCards Locates the cards that match a given ATR string.
SCardLocateCardsByATR Locates the cards that match a given ATR string.
SCardReadCache Retrieves the value portion of a name-value pair from the global cache maintained by the Smart Card Resource Manager.
SCardReconnect Reestablishes an existing connection from the calling application to the smart card.
SCardReleaseContext Closes an established resource manager context.
SCardReleaseStartedEvent Decrements the reference count for a handle acquired by using the SCardAccessStartedEvent function.
SCardRemoveReaderFromGroup Removes a reader from an existing reader group.
SCardSetAttrib Sets a given reader attribute.
SCardSetCardTypeProviderName Sets the provider name for a card name and provider type.
SCardStatus Gets the current state of a reader.
SCardTransmit Sends a service request to a smart card.
SCardUIDlgSelectCard Displays the smart card Select Card dialog box.
SCardWriteCache Writes a name-value pair from a smart card to the global cache maintained by the Smart Card Resource Manager.

 

SASL Functions

The Simple Authentication and Security Layer (SASL) provides the following functions.

FunctionsDescription
SaslAcceptSecurityContext Wraps a standard call to the SSPI AcceptSecurityContext (General) function and includes creation of SASL server cookies.
SaslEnumerateProfiles Lists the packages that provide a SASL interface.
SaslGetContextOption Retrieves the specified property of the specified SASL context.
SaslGetProfilePackage Returns the package information for the specified package.
SaslIdentifyPackage Returns the negotiate prefix that matches the specified SASL negotiation buffer.
SaslInitializeSecurityContext Wraps a standard call to the SSPI InitializeSecurityContext (General) function and processes SASL server cookies from the server.
SaslSetContextOption Sets the value of the specified property for the specified SASL context.

 

Other Functions

Here are other functions used for Authentication.

FunctionDescription
AddSecurityPackage

Adds a security support provider to the list of providers supported by Microsoft Negotiate.

ChangeAccountPassword

Changes the password for a Windows domain account by using the specified Security Support Provider.

CredMarshalTargetInfo

Serializes the specified target into an array of byte values.

DeleteSecurityPackage

Deletes a security support provider from the list of providers supported by Microsoft Negotiate.

LsaManageSidNameMapping

Adds or removes SID/name mappings from the mapping set registered with the LSA Lookup Service.

LsaOpenPolicy

Opens a handle to the Policy object on a local or remote system.

LsaQueryInformationPolicy

Retrieves information about a Policy object.

LsaSetInformationPolicy

Modifies information in a Policy object.

NPFMXEditPerm

Enables network vendors to supply their own permission editor dialog boxes.

NPFMXGetPermCaps

Retrieves the capabilities of the permission editor. The return value is a bitmask that indicates which of the Security menu items in File Manager are to be enabled.

NPFMXGetPermHelp

Retrieves the help file and help context of the permission editor dialog boxes when a menu item in the Security menu of File Manager is selected and F1 is pressed.

SpGetCredUIContextFn

Retrieves context information from a credential provider.

SpLsaModeInitialize

Provides the LSA with pointers to the functions implemented by each security package in the SSP/AP DLL.

SpQueryMetaDataFn

Gets metadata from a security support provider (SSP) when it is initiating a security context.

SpUpdateCredentialsFn

Updates the credentials associated with the specified context.

SspiCompareAuthIdentities

Compares the two specified credentials.

SspiCopyAuthIdentity

Creates a copy of the specified opaque credential structure.

SspiDecryptAuthIdentity

Decrypts the specified encrypted credential.

SspiEncodeAuthIdentityAsStrings

Encodes the specified authentication identity as three strings.

SspiEncodeStringsAsAuthIdentity

Encodes a set of three credential strings as an authentication identity structure.

SspiEncryptAuthIdentity

Encrypts the specified identity structure.

SspiExcludePackage

Creates a new identity structure that is a copy of the specified identity structure modified to exclude the specified security support provider (SSP).

SspiFreeAuthIdentity

Frees the memory allocated for the specified identity structure.

SspiGetCredUIContext

Retrieves context information from a credential provider.

SspiGetTargetHostName

Gets the host name associated with the specified target.

SspiIsAuthIdentityEncrypted

Indicates whether the specified identity structure is encrypted.

SspiIsPromptingNeeded

Indicates whether an error returned after a call to either the InitializeSecurityContext or the AcceptSecurityContext function requires an additional call to the SspiPromptForCredentials function.

SspiLocalFree

Frees the memory associated with the specified buffer.

SspiMarshalAuthIdentity

Serializes the specified identity structure into a byte array.

SspiPrepareForCredRead

Generates a target name and credential type from the specified identity structure.

SspiPrepareForCredWrite

Generates values from an identity structure that can be passed as the values of parameters in a call to the CredWrite function.

SspiPromptForCredentials

Allows a Security Support Provider Interface (SSPI) application to prompt a user to enter credentials.

SspiUnmarshalAuthIdentity

Deserializes the specified array of byte values into an identity structure.

SspiUnmarshalCredUIContext

Deserializes credential information obtained by a credential provider during a previous call to the ICredentialProvider::SetSerialization method.

SspiUpdateCredentials

Updates the credentials associated with the specified context.

SspiValidateAuthIdentity

Indicates whether the specified identity structure is valid.

SspiZeroAuthIdentity

Fills the block of memory associated with the specified identity structure with zeros.

WlxQueryTsLogonCredentials

Called by a replacement GINA DLL to retrieve credentials information if Terminal Services is enabled. The GINA DLL can then use this information to fill in a logon box automatically and attempt to log the user in.

 

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.