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:

1. Boot the auxiliary system—potentially by using a boot disk.

2. Go to the System32 folder where the new, failed GINA DLL is located.

3. Move the failed GINA to a different folder.

4. Copy the original MSGINA DLL in the System32 folder and rename it with the name of the failed GINA.

5. 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:

1. Winlogon detects a Secure Action Sequence (SAS) event.

2. Winlogon determines the system state when the SAS was detected.

3. Winlogon calls the appropriate GINA function.

4. The GINA function called performs the necessary operation.

5. The GINA passes a return value to Winlogon.

Winlogon and a custom GINA interact as above or as follows:

1. The GINA detects a predefined Secure Attention Sequence (SAS) event.

2. The GINA calls WlxSasNotify to inform Winlogon of this event.

3. Winlogon determines the system state when the SAS was detected.

4. Winlogon calls the appropriate GINA function.

5. The GINA function called performs the necessary operation.

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

For More Information

MSDN Online

Windows Technical Library

Microsoft TechNet