The Essentials of Replacing the Microsoft Graphical Identification and Authentication Dynamic Link Library
Abstract
This white paper expands upon and clarifies the current documentation for replacing the Microsoft Graphical Identification and Authentication Dynamic Link Library (MSGINA DLL) and is presented in the context of how the MSGINA DLL works. The content presented here is related to the documentation released by MSDN (Microsoft Developer Network) in October 2000.
On This Page
Warning: Potential System Failure Introduction Responsibilities of Winlogon Standard Features of the MSGINA DLL Necessary Functions of Msgina.dll Helper Functions Called by the MSGINA DLL Summary For More Information
Warning: Potential System Failure
Attempting to use a new GINA can cause a system to fail to boot correctly. If a new GINA is created, the registry is changed to use this new GINA, and attempts to restart the system are met with a Failed to Load xyz.dll error message.
Recovering from a GINA-related System Failure
Recovery is possible without reinstalling the system. This requires having a boot disk, or equivalent workaround, that will boot the system without using a normal hard disk boot.
To recover from this situation:
Boot the auxiliary system—potentially by using a boot disk.
Go to the System32 folder where the new, failed GINA DLL is located.
Move the failed GINA to a different folder.
Copy the original MSGINA DLL in the System32 folder and rename it with the name of the failed GINA.
Restart the computer and the original MSGINA DLL will load under the new name. At this point fixes can be made in the modified GINA.
Introduction
The Winlogon system component provides interactive logon support.
Winlogon Interactive Logon Model
Winlogon uses an interactive logon model consisting of three components:
Winlogon executable program.
Graphical Identification and Authentication DLL (the GINA).
Any number of network providers.
Each network provider is a DLL that enables the operating system to interact with non-Microsoft Windows networks by implementing network-specific actions, such as making a connection and exposing a common interface called the Network Provider API.
During the boot process, Winlogon creates three desktops: a user desktop, a system desktop, and a screen saver desktop. The system desktop is the secure desktop where Winlogon does its work.
The GINA—a DLL component loaded by Winlogon—implements the authentication policy of the interactive logon model. It performs all user identification and authentication interactions. Msgina.dll, the standard GINA provided by Microsoft and loaded by Winlogon, can be replaced by a GINA that is custom-built by a third party.
Winlogon and the GINA
Winlogon and the standard GINA interact as follows:
Winlogon detects a Secure Action Sequence (SAS) event.
Winlogon determines the system state when the SAS was detected.
Winlogon calls the appropriate GINA function.
The GINA function called performs the necessary operation.
The GINA passes a return value to Winlogon.
Winlogon and a custom GINA interact as above or as follows:
The GINA detects a predefined Secure Attention Sequence (SAS) event.
The GINA calls WlxSasNotify to inform Winlogon of this event.
Winlogon determines the system state when the SAS was detected.
Winlogon calls the appropriate GINA function.
The GINA function called performs the necessary operation.
The GINA passes a return value to Winlogon.
This document contains definitions of the functions that a GINA DLL must have and describes each function’s required capabilities. Prototypes of these functions are fixed and must remain unchanged, but the developer controls the implementation methods of each function.
While Winlogon identifies standard SAS events and calls an appropriate GINA function, the GINA itself can raise an SAS event to Winlogon as described earlier.
Before Replacing the Entire GINA
Before replacing the entire GINA mechanism, developers should consider the following options first.
Options
Registry Settings The Standard Features of MSGINA DLL section of this document outlines the registry settings that can be changed to modify the behavior of msgina.dll.
Ginastub If you simply want to provide some pre- or post-processing that is in addition to the functionality of MSGINA DLL, you should look at the “ginastub” sample in MSDN.
Ginahook If you want to modify a smaller part of MSGINA, or perhaps change how it processes a particular action, you should look into the “ginahook” sample in MSDN.
If none of these three methods suffices, then you will be forced to replace the entire mechanism, which is the case treated by this document.
Responsibilities of Winlogon
Window Station and Desktop Protection
Winlogon sets the protection of the window station—and the corresponding desktops, system, user, and screen saver—to ensure that each is properly accessible:
In general, the local system will have full access to these objects.
An interactively logged-on user will have read access to the window station object, the system desktop, and the screen saver desktop.
An interactively logged-on user will have full access to the user desktop.
Standard SAS Recognition
Winlogon defines a special SAS monitor class window and registers it with the Windows operating system as the "Logon Notify Window":
The kernel sends this window SAS messages for Control+Alt+Delete SAS events.
A resource manager sends this window messages for any smart card SAS events.
In general, a GINA uses the Winlogon mechanism for Control+Alt+Delete and smart card SAS events, but needs to monitor for other SAS events.
Loading the GINA
Winlogon loads the GINA DLL by first calling GetProfileString to retrieve the name of the GINA DLL, which is located in HKLM\\Software\\Microsoft\\WindowsNT\\CurrentVersion\\Winlogon\\GinaDLL. Winlogon then calls LoadGinaDll using the name retrieved from the registry.
If the name retrieved is not msgina.dll, Winlogon uses WlxNegotiate, puts the dispatch table into HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion\\Winlogon, and then uses LoadLibraryW to load the DLL. This function also gets all the function pointers, using WlxNegotiate to verify that Winlogon supports that version.
SAS Routine Dispatching
When Winlogon receives an SAS event, or when the GINA calls WlxSasNotify to notify Winlogon of an SAS event, Winlogon sets the state accordingly; it changes to the Winlogon desktop and calls one of the following GINA SAS processing functions:
WlxLoggedOnSas
WlxLoggedOutSas
WlxWkstaLockSas
User Profile Loading
At logon, Winlogon loads the user's profile into the registry so that the user's processes can employ the special registry key, HKEY_LOCAL_USER. Winlogon loads this profile after a successful logon, and before activation of the shell for the newly logged-on user.
Assignment of Security to User Shell
When a user logs on, the GINA creates one or more initial processes for that user, preferably by calling the Microsoft Win32 function CreateProcessAsUser and letting the system provide the service.
Screen Saver Control
Winlogon monitors keyboard and mouse activity to determine when to activate screen savers:
When the screen saver is activated, Winlogon switches to the screen saver desktop and continues to monitor keyboard and mouse activity to determine when to switch desktops.
If the screen saver is marked as secure, Winlogon treats the workstation as locked. When there is mouse or keyboard activity, Winlogon returns to the system desktop and invokes the GINA's WlxDisplayLockedNotice function.
If the screen saver is not secure, any keyboard or mouse activity returns to the user desktop without notification to the GINA.
Multiple Network Provider Support
Multiple networks installed on a Windows system can be included in the authentication process and in password-updating operations. This inclusion lets additional networks use Winlogon's secure desktop to gather identification and authentication information all at once during normal logon.
Some of the parameters required in the Winlogon services available to the GINA explicitly support these additional network providers. These parameters are used to gather credentials at logon and pass them to non-Windows resources.
Standard Features of the MSGINA DLL
A custom GINA written to replace the Microsoft standard GINA DLL (msgina.dll) may provide some or all of the standard GINA functionality. Following is a list of standard features and a brief description of how they are controlled.
Registry Key Values
Registry key values control the availability or behavior of many of these standard GINA features. Unless otherwise noted, these key values belong to the Winlogon registry key and have a value type of [REG_SZ].
The actual path of the Winlogon key is:
\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Winlogon.
The [REG_SZ] value type makes it convenient to query the key values using the GetProfileString and GetProfileInt functions.
Legal Notification Dialog Box
In some places, it is allowable for anyone who has access to a workstation to log on and begin working, unless there is a notice indicating that the system is for authorized users only. Also, many users want company-specific messages displayed before normal logon.
The standard GINA uses two Winlogon registry key values to allow a system to display information before logon. If either key value is present and contains a non-null string, a Legal Notice dialog box is displayed before the usual Welcome screen. These key value names are shown in the following table.
Key Values for Displaying Information Before Logon
Key value name |
Contents |
---|---|
LegalNoticeCaption |
The string to display as the caption of the Legal Notice dialog box |
LegalNoticeText |
The string to display as the message of the Legal Notice dialog box |
Display Last User Name
By default, the logon screen displays the name of the last user to successfully log on to the workstation. This feature is controlled by the DontDisplayLastUserName registry key value.
When this key value is set to 1, the last user name is not displayed in the logon dialog box.
Automatic Logon
The automatic logon feature allows a Microsoft Windows NT system to:
When this key value is set to 1, the last user name is not displayed in the logon dialog box.
Log on a user automatically every time the system boots using default information.
Disable the Control+Alt+Delete logon box.
This feature uses the values of the Winlogon keys listed in a table later in this paper.
Registry Key Values for Automatic Logon
Value |
Contents |
---|---|
AutoAdminLogon |
1 |
AutoLogonCount |
The number of times to do an automatic logon |
DefaultUserName |
The name of the user account |
DefaultDomainName |
The name of the domain that the user account is in |
DefaultPassword |
The password of the user account, in clear text |
If the AutoAdminLogon key value is present and contains a 1, and the AutoLogonCount key value is not present:
An automatic logon will occur every time the current user logs off or the system is rebooted.
The account being logged on to is specified using the DefaultUserName and DefaultDomainName key values, and the password is specified in DefaultPassword key value.
If the AutoAdminLogon key value is present and contains a 1, and the AutoLogonCount key value is present and is not zero:
AutoLogonCount will determine the number of automatic logons that occur.
Each time the system is rebooted, the value of AutoLogonCount will be decremented by 1, until it reaches 0.
When AutoLogonCount reaches 0, no account will be logged on automatically, the AutoLogonCount and DefaultPassword key values will be deleted from the registry, and AutoAdminLogon will be set to 0.
The automatic logon is often used during setups to do automatic restarts without having to prompt the user for credentials in the middle of setup. The registry values are then reset after the setup has been completed.
Caution: The password is normally stored in plain text in the registry. |
State of the SHIFT Key By default, MSGINA checks the state of the SHIFT key when AutoAdminLogon is 1. If the SHIFT key is held down during the boot process, MSGINA ignores the AutoAdminLogon key value and prompts the user for identification and authentication information. This feature helps in debugging a dedicated application. Set the IgnoreShiftOverride key value to 1 to disable this feature.
Allow Unauthenticated Shutdown
The default GINA can be configured to include a Shutdown button on the Logon dialog box that enables a user to shut down the system without first logging on. The following registry key value controls whether this button is included.
Registry Key Value for Controlling Shutdown Button
Value |
Description |
---|---|
ShutdownWithoutLogon |
1 to include the button; 0 to exclude the button |
Userinit.exe Activation
The GINA executes Userinit.exe when a user has logged on, running it on the application desktop in the newly logged-on user's context. Userinit.exe sets up the user's environment. This includes:
Restoring network connections.
Establishing profile settings, such as fonts and screen colors.
Running the user's logon scripts.
Running any user shell programs.
Shell Programs
The shell programs inherit the environment that Userinit.exe sets up:
Userinit.exe runs the shell programs named in the shell key value of the Winlogon registry key.
The shell key value can contain a comma-separated list of programs to run.
Windows Explorer, the default shell program, is executed if the shell key value is null or not present. By default, Explorer is listed.
The Microsoft-provided GINA's WlxActivateUserShell function calls the CreateProcessAsUser function to start Userinit.exe in the user's context. (Sample code in MSDN shows how to set the parameters for CreateProcessAsUser.)
The registry value HKLM\\Software\\WindowsNT\\CurrentVersion\\Winlogon\\Userinit names the executable that the GINA should run when a user logs on. To change the startup program, replace this key value with the name of the new startup program. It is good practice to call Userinit.exe from any new startup program.
Userinit.exe Context Winlogon also calls Userinit.exe in the system context, not the user's context. Userinit.exe is called in the system context to set up some machine policy.
Disabling Domain Option of Logon Dialog Box
It is possible to disable the domain option on the dialog box brought up by WlxLoggedOutSas. To do this, set the registry value NoDomainUI of type [Reg_Dword] to a value of 1. This would have users enter their user names in the form—for example, username@domain.
Logged-On Security Options
Entering an SAS while logged on switches the user to the secure desktop and presents a Security Options screen. Among the options listed are:
Shut down the system.
Log off.
Change your password.
Go to the task list.
Lock the workstation.
A replacement GINA can provide similar or additional options to the Security Options screen.
Smart Card Logon
Winlogon also monitors smart card events:
When Winlogon detects a smart card event, it calls the appropriate GINA function with dwSasType set to WLX_SAS_TYPE_SC_INSERT or WLX_SAS_TYPE_SC_REMOVE.
Msgina.dll uses the WlxGetOption function (with the parameter as WLX_OPTION_SMART_CARD_PRESENT or WLX_OPTION_USE_SMART_CARD) to determine what to do from Winlogon.
WlxGetOption WlxGetOption with the parameter set to WLX_OPTION_SMART_CARD_INFO returns the set of strings indicating the reader and cryptographic service provider (CSP) to be used for the smart card.
During the logon process it is necessary to fix up the user name with the user principal name (UPN) from the certificate, so that Unlock and other actions work correctly. If a smart card is present, msgina.dll forces on c-a-d to distinguish between a keyboard logon and a smart card logon.
During WlxIsLockOk, msgina.dll checks for the presence of a smart card. If a smart card is found, msgina.dll calls the WlxSetOption function with WLX_OPTION_USE_SMART_CARD set to ensure that the user can only unlock the workstation with the smart card. The same is true in WlxScreenSaverNotify.
Other GINAs and Smart Cards Any other GINA that enables smart card logon must be set up to check WlxGetOption for smart cards whenever it receives an SAS event that could possibly involve smart cards.
Defining a New SAS Type
Winlogon identifies Microsoft-predefined SAS types and calls the appropriate GINA functions; however, a third party can define its own SAS types and monitor for them independently.
When a custom SAS is detected, Winlogon is notified by the GINA with a call to the WlxSasNotify function, and the normal SAS sequence is followed.
Reserved SAS Values Microsoft has reserved the use of SAS values up to WLX_SAS_TYPE_MAX_MSFT_VALUE, all values between 0 and 127.
Biometric Authentication
Implementing biometrics as an authentication scheme is a case where a GINA from a third party might define new SAS types. This would be done by the custom GINA calling the WlxSasNotify function with the new biometric SAS value. Winlogon would identify the system state and call the appropriate GINA function, perhaps WlxLoggedOnSas, with the dwSasType parameter set to the third-party SAS value received from WlxSasNotify. The custom GINA's WlxLoggedOnSas function can then contain the code necessary to do the steps for the biometric authentication.
Necessary Functions of Msgina.dll
WlxNegotiate
WlxNegotiate allows the GINA to verify that it supports the installed version of Winlogon. If the wlx version is less than WLX_VERSION_1_1, then this function should fail. Otherwise, if the wlx version is less than the Winlogon version, then there is a version mismatch, and the function table must be updated to the correct pointers. (See WlxInitialize.)
Prototype for WlxNegotiate
BOOL WlxNegotiate( DWORD dwWinLogonVersion, PDWORD pdwDllVersion);
Return Values for WlxNegotiate
WlxNegotiate should return the following values.
Value |
Meaning |
---|---|
TRUE |
Return TRUE if the Winlogon version specified by dwWinLogonVersion is greater than or equal to the version returned in pdwDllVersion. When TRUE is returned, Winlogon will continue to initialize. |
FALSE |
Return FALSE if dwWinLogonVersion is less than pdwDllVersion. When FALSE is returned, Winlogon will terminate and the system will not boot. |
Remarks
Before calling WlxNegotiate, Winlogon sets the desktop and workstation states as follows.
Sets the |
So that |
---|---|
Desktop state |
The current desktop is the system desktop. |
Workstation state |
The desktop is locked. |
Key for WLX_VERSION Values
GINA Version |
Corresponding Versions of Windows |
---|---|
WLX_VERSION_1_0 |
Windows NT 3.5.0 |
WLX_VERSION_1_1 |
Windows NT 3.5.1 |
WLX_VERSION_1_2 |
Windows NT 4.0 |
WLX_VERSION_1_3 |
Windows 2000 |
WlxInitialize
Winlogon calls this function once for each window station present on the computer. Currently, the operating system supports one window station per workstation.
The context returned by this function will be passed back to the GINA in all subsequent calls.
WlxInitialize Functions In msgina.dll WlxInitialize also allocates space for the credentials UserName, Domain, Password, and OldPassword. This routine enables SeTcbPrivilege, hooks up to the Local Security Authority (LSA), and locates the authentication package by calling LsaRegisterLogonProcess.
This routine clears out all globals, gets the session ID, and saves it in the globals. It also checks if Control+Alt+Delete is disabled. Control+Alt+Delete is disabled through the registry key or through a policy.
Types of Logons
Smart Card If this is a smart card logon, Control+Alt+Delete is forced to be enabled so that Winlogon can distinguish between the different logon methods.
Terminal Server If this is a terminal server session and there was a version mismatch, then this routine must fail. Terminal server sessions do not check for autoadmin logon.
Autoadmin Logon Do an autoadmin logon with the necessary housekeeping, using AUOLOGONCOUNT_KEY, DEFAULTPASSWORD_KEY, and AUTOADMINLOGON_KEY.
Check for a Safeboot Check to see if this is a safe boot.
Prototype for WlxInitialize
BOOL WlxInitialize( LPWSTR lpWinsta, HANDLE hWlx, PVOID pvReserved, PVOID pvReserved, PVOID *pWlxContext);
Return Values for WlxInitialize
Value |
Meaning |
---|---|
TRUE |
Return TRUE if the GINA DLL was successfully initialized. |
FALSE |
Return FALSE if the GINA DLL was not initialized. Winlogon will quit, and the system will not boot. |
Remarks
Before calling WlxInitialize, Winlogon sets the desktop and workstation states as follows.
Sets the |
So that |
---|---|
Desktop state |
The current desktop is the system desktop. |
Workstation state |
The desktop is locked. |
The Dispatch Table
The dispatch table is always of type WLX_DISPATCH_VERSION_1_3:
If the Winlogon version is less than WLX_CURRENT_VERSION, then you must do some work to pass the proper table.
If the current version is 1_1, then the table will be the size of WLX_DISPATCH_VERSION_1_1.
If the version is 1_2 or 1_3, then the table will be of size WLX_DISPATCH_VERSION_1_2. It then assigns the values of the fixed-up table to the correct function pointers.
WlxDisplaySASNotice
Winlogon calls WlxDisplaySASNotice to display a notice when no users are logged on. This function calls LinkWindow_RegisterClass to register the link window and WlxDialogBoxParam to display the notice.
In msgina.dll this notice typically informs users that they must enter CONTROL+ALT+DELETE to log on.
Prototype for WlxDisplaySASNotice
VOID WlxDisplaySASNotice( PVOID pWlxContext);
Remarks
Before calling WlxDisplaySASNotice, Winlogon sets the desktop and workstation states as follows.
Sets the |
So that |
---|---|
Desktop state |
The current desktop is the system desktop. |
Workstation state |
The desktop is locked. |
WlxLoggedOutSAS
Winlogon calls this function when it receives an SAS event while no users are logged on. This routine clears out the user process information and then calls Logon.
LsaGetUserName is used to get the user name and domain and uses the information to fill in pMprNotifyInfo. If this is a terminal server session, then it must also create the home directory and set appropriate security on it.
This routine does the following:
Fills in pProfile information after checking if this is a local, domain, or cached logon.
Makes sure to close connections on failed authentication.
Do not activate the user shell program in WlxLoggedOutSAS. The user shell program should always be activated in WlxActivateUserShell.
Prototype for WlxLoggedOutSAS
int WlxLoggedOutSAS( PVOID pWlxContext, DWORD dwSasType, PLUID pAuthenticationId, PSID pLogonSid, PDWORD pdwOptions, PHANDLE phToken, PWLX_MPR_NOTIFY_INFO pNprNotifyInfo, PVOID *pProfile);
Return Values for WlxLoggedOutSAS
Value |
Meaning |
---|---|
WLX_SAS_ACTION_LOGON |
Indicates a user has logged on |
WLX_SAS_ACTION_NONE |
Indicates the logged attempt was unsuccessful or canceled |
WLX_SAS_ACTION_SHUTDOWN |
Indicates the user requested that the system be shut down |
Remarks
Before calling WlxLoggedOutSAS, Winlogon sets the desktop and workstation states as follows.
Sets the |
So that |
---|---|
Desktop state |
The current desktop is the system desktop. |
Workstation state |
The desktop is locked. |
Predefined SAS Types
Type |
Description |
---|---|
WLX_SAS_TYPE_CTRL_ALT_DEL |
Indicates a user has typed the standard CTRL+ALT+DEL SAS |
WLX_SAS_TYPE_SC_INSERT |
Indicates that a smart card has been inserted into a compatible device |
WLX_SAS_TYPE_SC_REMOVE |
Indicates that a smart card has been removed from a compatible device |
WLX_SAS_TYPE_TIMEOUT |
Indicates that no user input was received within the specified time-out period |
WlxActivateUserShell
WinLogon calls this function following a successful logon to request that the GINA activate the user's shell program.
Always activate the user shell program in WlxActivateUserShell rather than WlxLoggedOutSAS. This gives Winlogon a chance to update its state and sets workstation and desktop protections before any logged-on user processes are allowed to run.
This routine needs to write out the current user name to a place where shell logoff can read it.
Prototype for WlxActivateUserShell
BOOL WlxActivateUserShell( PVOID pWlxContext, PWSTR pszDesktopName, PWSTR pAuthenticationId, PVOID pEnvironment);
Return Values for WlxActivateUserShell
Value |
Meaning |
---|---|
TRUE |
Return TRUE if the shell process was started. |
FALSE |
Return FALSE if the shell process could not be started. When FALSE is returned, Winlogon cancels the logon in process. |
Remarks
Before calling WlxActivateUserShell, Winlogon sets the desktop and workstation states as follows.
Sets the |
So that |
---|---|
Desktop state |
The current desktop is the system desktop. |
Workstation state |
The desktop is locked. |
WlxLoggedOnSAS
Winlogon calls this function when it receives an SAS event while the user is logged on and the workstation is not locked.
Winlogon calls WlxLoggedOnSAS when the logged-on user wants to shut down, log off, or lock the workstation. The GINA DLL can lock the workstation by returning WLX_SAS_LOCK_WKSTA. When this value is returned, Winlogon locks the workstation and calls WlxWkstaLockedSAS the next time it receives an SAS.
Prototype for WlxLoggedOnSAS
int WlxLoggedOnSAS( PVOID pWlxContext, DWORD dwSasType, PVOID pReserved);
Return Values for WlxLoggedOnSAS
The WlxLoggedOnSAS function should return one of the following values.
Value |
Meaning |
---|---|
WLX_SAS_ACTION_NONE |
Returns to the default desktop. |
WLX_SAS_ACTION_LOCK_WKSTA |
Locks the workstation and waits for the next SAS. |
WLX_SAS_ACTION_LOGOFF |
Logs the user off the workstation. |
WLX_SAS_ACTION_SHUTDOWN |
Logs the user off and shuts down the computer. |
WLX_SAS_ACTION_SHUTDOWN_REBOOT |
Logs the user off, shuts down the computer, and then reboots the computer. |
WLX_SAS_ACTION_SHUTDOWN_POWER_OFF |
Logs the user off (if hardware allows),, shuts down the computer, and then turns off the computer. |
WLX_SAS_ACTION_PWD_CHANGE |
Notifies network providers that the user changed his or her password. Obsolete GINA DLLs should call WlxPasswordChangeNotify whenever a password is changed. |
WLX_SAS_ACTION_TASKLIST |
Invokes the task list. |
WLX_SAS_ACTION_FORCE_LOGOFF |
Forcibly logs the user off. |
WLX_SAS_ACTION_SHUTDOWN_SLEEP |
Puts the computer in suspend mode. |
WLX_SAS_ACTION_SHUTDOWN_SLEEP2 |
Shuts down the system into an ACPI power-down state. If the machine is not an ACPI machine, this option will have no effect. |
WLX_SAS_ACTION_SHUTDOWN_HIBERNATE |
Shuts down the system into hibernation. If the system was not configured for hibernation, this option will have no effect. |
Remarks
Before calling WlxLoggedOnSAS, Winlogon sets the desktop and workstation states as follows.
Sets the |
So that |
---|---|
Desktop state |
The current desktop is the system desktop. |
Workstation state |
The desktop is locked. |
WlxDisplayLockedNotice
Winlogon calls this function when the workstation is placed in the locked state.
WlxDisplayLockedNotice allows the GINA to display information about the lock, such as who locked the workstation and when it was locked.
To display lock information, the GINA must display a dialog box that will be interrupted by a WLX_WM_SAS message.
Remarks
Before calling WlxDisplayLockedNotice, Winlogon sets the desktop and workstation states as follows.
Sets the |
So that |
---|---|
Desktop state |
The current desktop is the system desktop. |
Workstation state |
The desktop is locked. |
WlxWkstaLockedSAS
Winlogon calls this function when it receives an SAS event and the workstation is locked.
The GINA should return one of the following values to indicate the state of the workstation:
Prototype for WlxDisplayLockedNotice
The workstation is to remain locked.
The workstation is to be unlocked.
The logged-on user is being forced to log off (which leaves the workstation locked until the logoff is completed).
This function calls a dialog box to reauthenticate the user, and calls LsaLogonUser to attempt to authenticate the user with the resulting credentials.
Prototype for WlxWkstaLockedSAS
int WlxWkstaLockedSAS( PVOID pWlxContext, DWORD dwSasType);
Return Values for WlxWkstaLockedSA
WlxWkstaLockedSAS should return the following values.
Value |
Meaning |
---|---|
WLX_SAS_ACTION_NONE |
Tells Winlogon to keep the workstation locked |
WLX_SAS_ACTION_UNLOCK_WKSTA |
Tells Winlogon to unlock the workstation |
WLX_SAS_ACTION_FORCE_LOGOFF |
Tells Winlogon to force the user to log off |
Remarks
Before calling WlxWkstaLockedSAS, Winlogon sets the desktop and workstation states as follows.
Sets the |
So that |
---|---|
Desktop state |
The current desktop is the system desktop. |
Workstation state |
The desktop is locked. |
WlxIsLockOk
Winlogon calls this function before attempting to lock the workstation.
The GINA should return one of the following values to indicate the state of the workstation:
If a smart card is present this function also sets the option with WlxSetOption that a smart card must be used to unlock the workstation.
Prototype for WlxIsLockOk
BOOL WlxIsLockOk( PVOID pWlxContext);
Return Values for WlxIsLockOk
Value |
Meaning |
---|---|
TRUE |
Return TRUE if it is acceptable to lock the workstation. |
FALSE |
Return FALSE if it is not acceptable to lock the workstation. |
WlxIsLogoffOk
Winlogon calls this function when the user initiates a logoff operation.
WlxIsLogoffOk can return FALSE to prevent the user from logging off the workstation.
Prototype for WlxIsLogoffOk
BOOL WlxIsLogoffOk( PVOID pWlxContext);
Return Values for WlxIsLogoffOk
Value |
Meaning |
---|---|
TRUE |
Return TRUE if it is acceptable to perform the logoff operation. |
FALSE |
Return FALSE if it is not acceptable to perform the logoff operation. |
WlxLogoff
Winlogon calls this function to notify the GINA of a logoff operation on this workstation. This allows the GINA to perform any logoff operations that may be required.
This routine is typically used to clear out user-specific information.
Prototype for WlxLogoff
VOID WlxLogoff( PVOID pWlxContext);
Remarks
Before calling WlxLogoff, Winlogon sets the desktop and workstation states as follows.
Sets the |
So that |
---|---|
Desktop state |
The current desktop is the system desktop. |
Workstation state |
The desktop is locked. |
WlxShutdown
Winlogon calls this function just before shutting down. This allows the GINA to perform any necessary shutdown tasks.
Winlogon calls WlxShutdown after the user has logged off and the WlxLogoff function has been called.
Prototype for WlxShutdown
VOID WlxShutdown( PVOID pWlxContext, DWORD ShutdownType);
Return Values
This function has no return values.
Remarks
Before calling WlxShutdown, Winlogon sets the desktop and workstation states as follows.
Sets the |
So that |
---|---|
Desktop state |
The current desktop is the system desktop. |
Workstation state |
The desktop is locked. |
WlxNetworkProviderLoad
Winlogon calls this function to collect valid authentication and identification information.
This function is used to put the user’s credentials in a structure to be passed to the network provider.
Prototype for WlxNetworkProviderLoad
BOOL WlxNetworkProviderLoad( PVOID pWlxContext, PWLX_MPR_NOTIFY_INFO pNprNotifyInfo);
Return Values for WlxNetworkProviderLoad
Value |
Meaning |
---|---|
TRUE |
Return TRUE if the user was authenticated. |
FALSE |
Return FALSE if the user was not authenticated. |
WlxDisplayStatusMessage
Winlogon calls this function when the GINA DLL should display a message.
Prototype for WlxDisplayStatusMessage
BOOL WlxDisplayStatusMessage( PVOID pWlxContext, HDESK hDesktop, DWORD dwOptions, PWSTR pTitle, PWSTR pMessage);
Return Values for WlxDisplayStatusMessage
Value |
Meaning |
---|---|
TRUE |
Return TRUE if the message was displayed. |
FALSE |
Return FALSE if the message was not displayed. |
WlxGetStatusMessage
Winlogon calls this function to get the status message being displayed by the GINA DLL.
Prototype for WlxGetStatusMessage
BOOL WlxGetStatusMessage( PVOID pWlxContext, DWORD *pdwOptions, PWSTR pMessage, DWORD dwBufferSize);
Return Values for WlxGetStatusMessage
Value |
Meaning |
---|---|
TRUE |
Return TRUE if the message was retrieved. |
FALSE |
Return FALSE if the message was not retrieved. |
WlxRemoveStatusMessage
Winlogon calls this function to tell the GINA DLL to stop displaying the status message.
Prototype for WlxRemoveStatusMessage
BOOL WlxRemoveStatusMessage( PVOID pWlxContext);
Return Values for WlxRemoveStatusMessage
Value |
Meaning |
---|---|
TRUE |
Return TRUE if the message was removed. |
FALSE |
Return FALSE if the message was not removed. |
Helper Functions Called by the MSGINA DLL
Note on writing dialog helper functions: The dialog helper functions should only be used on the initial thread. Any additional threads should use the normal Win32 functions. If this is not done, it is possible to be in a state where SAS events will not be processed. Be aware that these additional threads will not receive Windows notifications.
Logon
This routine displays the LogonUI—depending on the SAS type. If the logon is successful the global structure is filled in with the logon information, and if necessary, displays legal notices with DisplayLegalNotices.
The audit log status is obtained with GetAuditLogStatus. If the log is full, only administrators are allowed to log on, and a different dialog box is displayed. To actually log them on, set a time-out limit with WlxSetTimeout and display the dialog box with WlxDialogBoxParam. This routine uses the LsaLogonUser function to actually log on the user.
Failed Logon MSGINA_DLG_FAILURE, or DLG_INTERRUPTED (a set defined in WinLogon) is returned if the logon failed.
Successful Logon The dialog box returns MSGINA_DLG_SUCCESS if the user was logged on successfully. With a successful logon, the global structure is filled in with the logon information. The successful logon routine notifies credential managers of the successful logon and replaces the user name with the name (User Principal Name) from the certificate, so that Unlock and other variables work correctly.
The return value is an INT_PTR, which returns WLX_SAS_ACTION_NONE or WLX_SAS_ACTION_LOGON. Do not forget to check for smart card action.
Note: This function is specific to the msgina.dll and does not need to be explicitly called or implemented. It ultimately calls LsaLogonUser to authenticate the user. |
LsaLogonUser
This routine is used to authenticate a user logon attempt. It is only used for the initial logon that is necessary to gain access to Windows. Subsequent (supplementary) authentication requests must be done using LsaCallAuthenticationPackage.
This service will cause a logon session to be created that represents the new logon. It will also return a token representing the newly logged-on user.
Prototype for LsaLogonUser
NTSTATUS LsaLogonUser( Handle LsaHandle, PString OriginName, Security_Logon_Type LogonType, Ulong AuthenticationPackage, PVoid AuthenticationInformation, Ulong AuthenticationInformationLength, Ptoken_Groups LocalGroupsOptional, Ptoken_Source SourceContext, PVOID *ProfileBuffer, PULong ProfileBufferLength, Pluid LogonID, Phandle Token, Pquota_Limits Quotas, PNTStataus SubStatus);
LsaRegisterLogonProcess must be called before this function to establish a connection to the LSA server and verify that the caller is a logon application.
Return Values for LsaLogonUser
Value |
Meaning |
---|---|
STATUS_SUCCESS |
Indicates the service completed successfully. |
STATUS_QUOTA_EXCEEDED |
Indicates the caller does not have enough quota to allocate the profile data being returned by the authentication package. |
STATUS_NO_LOGON_SERVERS |
Indicates that no domain controllers are currently able to service the authentication request. |
STATUS_LOGON_FAILURE |
Indicates the logon attempt failed. No indication as to the reason for failure is given, but typical reasons include misspelled user names and passwords. |
STATUS_ACCOUNT_RESTRICTION |
Indicates the user account and password were legitimate, but the user account has some restriction preventing successful logon at this time. |
STATUS_NO_SUCH_PACKAGE |
Indicates the specified authentication package is unknown to the LSA. |
STATUS_BAD_VALIDATION_CLASS |
Indicates the authentication information provided is not a validation class known to the specified authentication package. |
LsaFreeReturnBuffer
The LsaFreeReturnBuffer function frees the memory used by a buffer previously allocated by the Local Security Authority (LSA).
Some of the LSA authentication functions allocate memory buffers to hold returned information, for example: LsaLogonUser and LsaCallAuthenticationPackage.
Your application should call LsaFreeReturnBuffer to free these buffers when they are no longer needed.
Prototype for LsaFreeReturnBuffer
NTSTATUS LsaFreeReturnBuffer( PVOID Buffer);
Return Values for LsaFreeReturnBuffer
Value |
Meaning |
---|---|
STATUS_SUCCESS |
The function succeeded. |
NTSTATUS |
If the function fails, it returns an NTSTATUS code. |
Possible Error Codes
Error code |
Description |
---|---|
STATUS_PRIVILEGE_NOT_HELD |
The caller does not have the SeTcbPrivilege privilege, which is required to call this function. You can set this privilege either by using Windows NT User Manager or by calling LsaAddAccountRights. |
STATUS_NAME_TOO_LONG |
The specified logon process name exceeds 127 bytes. |
The LsaNtStatusToWinError function converts an NTSTATUS code to a Win32 error code.
LsaRegisterLogonProcess
The LsaRegisterLogonProcess function establishes a connection to the LSA server and verifies that the caller is a logon application. For this function to succeed the GINA must have the SeTcbPrivilege privilege enabled. This function also opens the application's process for PROCESS_DUP_HANDLE access in anticipation of future LSA authentication calls.
This function must be called before a logon process can use any other logon authentication functions provided by the LSA.
Prototype for LsaRegisterLogonProcess
NTSTATUS LsaRegisterLogonProcess( PLSA_STRING LogonProcessName, PHANDLE LsaHandle, PLSA_OPERATIONAL_MODE SecurityMode);
Return Values for LsaRegisterLogonProcess
Value |
Meaning |
---|---|
STATUS_SUCCESS |
The function succeeded. |
NTSTATUS |
If the function fails, it returns an NTSTATUS code. |
Possible Error Codes
Error code |
Description |
---|---|
STATUS_PRIVILEGE_NOT_HELD |
The caller does not have the SeTcbPrivilege privilege, which is required to call this function. You can set this privilege by either using Windows NT User Manager or by calling LsaAddAccountRights. |
STATUS_NAME_TOO_LONG |
The specified logon process name exceeds 127 bytes. |
The LsaNtStatusToWinError function converts an NTSTATUS code to a Win32 error code.
For more information, see “Standard LSA Function Return Values” in MSDN.
WlxDialogBoxParam
The WlxDialogBoxParam function is called by the GINA to initialize dialog box controls; it is then used to create a modal dialog box from a dialog box template resource. WlxDialogBoxParam duplicates the Win32 DialogBoxParam function and allows Winlogon to close the dialog box.
Prototype for WlxDialogBoxParam
int WlxDialogBoxParam( HANDLE hWlx, HANDLE hInst, LPWSTR lpszTemplate, HWND hwndOwner, DLGPROC dlgprc, LPARAM dwInitParam);
Return Values for WlxDialogBoxParam
If the WlxDialogBoxParam function succeeds, the return value is the value of the nResult parameter given in the call to the EndDialog function used to close the dialog box.
If the function fails, the return value is -1.
LsaGetUserName
This function returns the caller’s user name and domain name.
Prototype for LsaGetUserName
NTSTATUS LsaGetUserName( PUnicode_String *UserName, Punicode_String *DomainName Optional);
Return Values for LsaGetUserName
Value |
Meaning |
---|---|
NT_STATUS |
The privilege was found and returned. |
Summary
The information in this white paper expands upon and clarifies the current documentation for replacing the Microsoft Graphical Identification and Authentication Dynamic Link Library (MSGINA DLL), and is presented in the context of how the MSGINA DLL works. This content is related to the documentation released by MSDN (Microsoft Developer Network) in October 2000.
Be aware that attempting to use a new GINA can cause a system to not boot correctly. If this problem affects you, refer to the section Recovering from a GINA-related System Failure at the beginning of this document.
Other MSGINA topics covered include: the responsibilities for Winlogon, standard features, necessary functions and helper functions.