CONTENT:
1. Introduction
2. How does it work?
3. Installation
4. Registry entries
5. Messages during operation
6. System requirements
7. GinaSetup program
8. Uninstallation
9. Notes
10 Bugs
11. History
12. Future
13. Contacts (with some details about the author)
14. Additional Utilities
What does SAS, Winlogon and Gina mean?
Winlogon is a component of Microsoft® Windows NT® that provides
interactive, logon support. To allow for independent software vendor (ISV)
and developer modifications to the interactive logon model, some aspects
of Winlogon are replaceable. Specifically, the identification and authentication
aspects of Winlogon are implemented in a replaceable dynamic-link library
(DLL). This replaceable DLL is referred to as the Graphical Identification
and Authentication DLL, or GINA. GINA lets developers implement smart-card,
retinal-scan, or other authentication mechanisms in place of the standard
Windows NT user name and password authentication.
Winlogon
WINLOGON.EXE is the executable image responsible for implementing interactive
logon support. There are many aspects of interactive logon support, including
an actual collection of identification and authentication information (as
described under the term GINA), and a number of other functions such as
window station and desktop management, screen-saver control, and multiple-network
provider notifications.
GINA
This specification is used by developers who want to replace the component
of Windows NT that performs identification and authentication of interactive
users. This replaceable functionality is implemented as a dynamic-link
library (DLL) which is loaded and called by WINLOGON.EXE. This DLL is referred
to as the Graphical Identification and Authentication DLL, or GINA.
MSGINA.DLL
The standard GINA shipped with Windows NT is MSGINA.DLL.
Secure Attention Sequence (SAS)
Winlogon uses a special sequence of events to recognize when a user wants to log on or perform other secure operations. This sequence of events is referred to as the secure attention sequence or SAS. The SAS provides a secure way for users to enter identification and authentication information. In this way, users are protected from password-collection programs and other flaws inherent in timeshare systems.
As an example, in earlier timeshare systems, users could walk up to an apparently unused terminal and press the ENTER key. The system would then prompt for username and password information. The problem with this was that the terminal could sometimes be in use and with a password collector program running which made the logon appear like a normal logon. However, in reality, the "Trojan horse" program would store away the user's password and then indicate that the user had entered an invalid password (or indicate some other reason why the logon failed). The end result would be that the user just gave his or her password to someone else.
In Windows NT, users can enter a secure attention sequence (SAS). This
prompts Winlogon to switch to a secure desktop that no "Trojan horse" program
has access to. The SAS for a standard Windows NT system is the CTRL+ALT+DEL
key combination. Developers writing a replacement GINA are encouraged to
achieve the same level of security with their SAS. By using a device such
as a smart-card reader, the SAS could be the insertion or removal of a
smart card. Developers can also choose to retain the CTRL+ALT+DEL key combination
as the SAS.
Winlogon Process
Winlogon serves as the process that authenticates and logs on the interactive user. Winlogon is in one of three states at any given time. These states are illustrated in the following diagram.
When Winlogon is in the logged-off state, users are prompted to identify themselves and provide authentication information. If a user provides correct user account information and no restrictions prevent it, the user is logged on and a shell program (such as EXPLORER.EXE) is activated in the user's context. Winlogon changes into the logged-on state.
Logged-on State
When Winlogon is in the logged-on state, users can interact with the shell, activate additional applications, and generally perform their work. From the logged-on state, users can either stop all work and log off, or lock their workstations (leaving all work in place). If the user decides to log off, Winlogon will terminate all processes associated with that logon session and the window station will be available for another user. If, instead, the user decides to lock the workstation, then a secure desktop is displayed.
Workstation-locked State
When Winlogon is in the workstation-locked state, the secure desktop
is displayed either until the user unlocks the workstation (by providing
identification and authentication information that matches the information
provided by the user who originally logged on), or until an administrator
forces a logoff. If the workstation is unlocked, the user's typical desktop
is again displayed and work can resume. If, however, an administrator unlocks
the workstation (by providing the identification and authentication information
of an administrator account), the logged-on user's processes are terminated
and the workstation becomes available for another user. However, the adminstrator
must be in front of that workstation to log off the user.
Development of the provided GINA:
Microsoft® provides the required information in its development environment called Microsoft® Visual Studio 97 in two subdirectories called "Gina" and Ginastub" in DevStudio\Vc\Samples\Sdk\Winnt\Security\. Most of the information in this readme file is from the help file found in the Gina dirs called "gina.hlp".
There are two ways now to provide GINA functionality:
This GINA uses some of the functionality of Alexander Frinks GINA
found at http://wwwthep.physik.uni-mainz.de/~frink/nt.html.
I have tried to contact Alexander at Alexander.Frink@Uni-Mainz.DE
but he never responded to my emails. I wanted to incorporate some/all of
his GINA's functionality (not neccessarily using his code). The functionality
of his GINA is provided by the GINA in this archive.
Back to the top.
KeyName: \Software\Microsoft\Windows NT\CurrentVersion\Winlogon
ValueName: GinaDLL
ValueType: [REG_SZ]
If this value is present, it should have a GINA name and the GINA MUST reside in the system32 directory. The name of the PATH does not need to be included in the valuename, it is known to be found in the system32 directory. Winlogon will load and use that GinaDll.
Note: Failure to provide a dll in the system32 once you have set the registry entry will hang your system upon the next boot, because Winlogon will try to load a GinaDll with the specified name and its not there. If you just make the value and do not provide a name and keace it empty the system will try to load a GINA with a name "" and hence stall!
Upon system startup the GinaDll is loaded and stays in memory for the
entire system uptime.
At startup it sets up some default values and provides functionality
to the LAUNCHER program (provided in this archive) and acts upon the FLAG
SETTINGS which are under the root HKEY_LOCAL_MACHINE of the registry under
the keys:
\Software\Microsoft\Windows NT\CurrentVersion\Winlogon
\Software\Microsoft\Windows NT\CurrentVersion\Winlogon\ForceLogoff
\Software\Microsoft\Windows NT\CurrentVersion\Winlogon\Logoff
\Software\Microsoft\Windows NT\CurrentVersion\Winlogon\Logon
\Software\Microsoft\Windows NT\CurrentVersion\Winlogon\Shutdown
and
\Software\UserCommandLauncher\System
\Software\UserCommandLauncher\User
These flags decide what the GINA does when certain system events occur, eg the user presses the SAS, logoff, logon and even forcelogoff. These flags (registry entries) are explained below in Registry Entries.
You must make sure that you can recover you system to its original
working state.
You have a number of possibilites:
Unzip the archive into a temporary directory. You can keep this directory afterwards to keep all the binaries at a position related to Gina and Launcher and rename it as you wish.
The only files needed are the Launcher in the \\PDC\netlogon directory
and Gina in the system32 directory.
All other files are optional one you have installed everything.
Do it by hand:
Copy the Gina in this archive to the system32 directory.
If you have had a GINA before you must move the old GinaDll to some
other name eg Gina.old, Windows uses THAT GinaDll until you reboot! Once
you have moved the original gina to a "backup gina" you can copy the new
gina into the system32 directory.
Note that you cannot copy over the original GinaDll since the file
is IN USE, hence the move first and then the copy.
If you never had a GINA before simply copy the gina into the system32
directory.
The same is valid if your previous GINA has a different name. You can
simply copy the new GinaDll into the system dir and set the value GinaDLL
in the Winlogon registry entry to point to the new gina and REBOOT to make
that Gina the current one.
Example where the gina is in the current directory with a previous gina installed:
del d:\winnt\system32\LauncherGina.old
move d:\winnt\system32\LauncherGina.dll d:\winnt\system32\LauncherGina.old
copy LauncherGina.dll d:\winnt\system32\LauncherGina.dll
Once you have copied the gina you must set the registry entry of GinaDLL
to point to this Gina for the GINA to become active.
If you have had a Gina and the GinaNames are the same you do not need
to do anything other then set the registry entries
to suit your needs. You can just call GinaSetup.exe
to setup some default values and reboot!
If you never had a Gina you must enter the GinaDLL
into the registry for the gina to become active. If you do not enter a
name and you reboot nothing will happen, the gina will simply not load!
Use Utils provided:
for /f "skip=3 eol=T" %i in ('net view') do regini -m \\%i winlogon.regini
which would find all the machines on the network and "regini" would set the registry entries on all machines found to the registry values found in the file "usercommandlauncher.regini". I use this command quite often.
KEY: SOFTWARE\Microsoft\Windows
NT\CurrentVersion\Winlogon\Logon
This values in this key set the values for LOGON scripts:
|
||
ValueName | Value Range | Description |
LogFile | Empty
or Name of file |
This is the name of the logfile.
All output produced by the logoff script end up in this file or are discarded if no file is specified. |
SystemScript | Empty
or Name of File |
If set it is the name of the script which should be executed when logon
occurs. This script runs under the context of "SYSTEM ACCOUNT" so make
sure that the file is READ ONLY (or none) by everyone!
If empty no system script will be executed. |
UserScript | Empty
or Name of File |
If set it is the name of the script which should be executed when logon
occurs and be run under the context of the user.
You simply could point this to a script in the user dirs called z:\logon.cmd. If empty no user script will be executed. |
Timeout | time in seconds | This makes sure that hang scripts are killed after an elapsed time
to make sure no zombies are hanging around and users can't do silly things
in their scripts.
The disadavantage is that the time must be long enough for the script to finish properly or it will be killed before it finshed. |
KEY: SOFTWARE\Microsoft\Windows
NT\CurrentVersion\Winlogon\Logoff
This values in this key set the values for LOGOFF scripts:
|
||
ValueName | Value Range | Description |
LogFile | Empty
or Name of file |
This is the name of the logfile.
All output produced by the logoff script end up in this file or are discarded if no file is specified. |
SystemScript | Empty
or Name of file |
If set it is the name of the script which should be executed when a
logoff occurs. This script runs under the context of "SYSTEM ACCOUNT" so
make sure that the file is READ ONLY (or none) by everyone!
If empty no system script will be executed. |
UserScript | Empty
or Name of file |
If set it is the name of the script which should be executed when a
logoff occurs and be run under the context of the user.
You simply could point this to a script in the user dirs called z:\logoff.cmd. If empty no user script will be executed. |
Timeout | time in seconds | This makes sure that hang scripts are killed after an elapsed time
to make sure no zombies are hanging around and users can't do silly things
in their scripts.
The disadavantage is that the time must be long enough for the script to finish properly or it will be killed before it finshed. |
KEY: SOFTWARE\Microsoft\Windows
NT\CurrentVersion\Winlogon\Shutdown
This values in this key set the values for SHUTDOWN scripts:
|
||
ValueName | Value Range | Description |
Logfile | Empty
or Name of file |
This is the name of the logfile.
All output produced by the logoff script end up in this file or are discarded if no file is specified. |
Account | Empty
or Name of User |
This is the name of the account under which context the shutdown script
should be run, it should be a valid account or the script will fail as
the underlying layer will log into that account before executing the script!
If this is empty it default to the "SYSTEM ACCOUNT" so make sure that the script file has the appropriate security settings! |
Password | Empty
or password of account |
This should be the password for the above account.
Note that the password is in straight ASCII so make sure that permissions
are set appropriately for this key!
|
Script | Empty
or Name of file |
If set it is the name of the script which should be executed when logon
occurs and be run under the context ACCOUNT.
Make sure that the script receives the appropriate security settings!
|
Timeout | timeout in seconds | This makes sure that hang scripts are killed after an elapsed time
to make sure no zombies are hanging around and users can't do silly things
in their scripts.
The disadavantage is that the time must be long enough for the script to finish properly or it will be killed before it finshed. |
KEY: SOFTWARE\Microsoft\Windows
NT\CurrentVersion\Winlogon\ForceLogoff
This values in this key set the values for FORCELOGOFF scripts:
Note that the LOGOFF process is initiated within GinaDll and does not require an external logoff utility. The logoff script can be used to warn the user with a *TIMED* message. Once the script finishes the user is logged out, hence if the script is empty, the user is logged out straight away. Note there is a small timedelay in the response to the setting of the flag as the checking of the "Forcelogoff flag" is done every 60 seconds with very little overhead for the system. |
||
ValueName | Value Range | Description |
Logfile | Empty
or Name of file |
This is the name of the logfile.
All output produced by the logoff script will end up in this file or are discarded if no file is specified. The output of the Logoff process will be written to this file as well.
|
Script | Empty
or Name of file |
If set it is the name of the script which should be executed when a
forced logoff occurs. This script runs under the context of the current
user account.
If empty no script will be executed but the user will still be logged off! Note the script does not need to include a logoff program (as this is done within the GinaDll), it should contain a message for the user that a logoff is pending and s/he should save the work and maybe some cleanup stuff! Not that the script SHOULD CONTAIN a SLEEP function as the user is logged
off as soon as the script is finished.
|
Timeout | timeout in seconds | This makes sure that hung scripts are killed after an elapsed time
to make sure no zombies are hanging around and users can't do silly things
in their scripts.
This makes sure too that the user MUST LOGOFF or SAVE THE DATA within a certain timeout, if the user does not press the Messagebox "OK" button and the messagebox is not started using "start" then the script would never return. The timeout makes sure that the user will be logged out once the timeout is elapsed. If you specify a SLEEP within the script which is LONGER than the timeout,
the script is terminated after the timeout time elapses!
|
Upon starting GinaSetup checks whether the registry entries required for GINA are available and if available it displays the values as found in the field boxes.
If they are not available the field boxes will be blank and you need to use the "Initialize" button to enter the entries (with default values) into the registry. This has the advantage that you can setup other machines without setting up the machine you are working on (my servers do not have the gina running as no user can log onto them anyway).
You can change the values simply by typing into the field boxes and
then press update to write the values into the registry. Pressing cancel
will close the setup program without updating the values.
Upon startup you see:
Install Only
The disadavantage is that the user needs to know the limitations
The original GinaDll (if one is there) MUST BE MOVED to anotherfile
eg:
move mygina.dll mygina.old
before the a new gina can be copied since IN USE system files cannot
be deleted but can be MOVED!
WindowsNT then "knows" that the original GinaDll now has a different
file name and the file in USE is now the one with the new name. The advantage
is you can copy as many as you like to the original name (or leave it blank
if you leave the entry to GinaDll in the registry blank as well!)
You cant move another file to mygina.old since that file is now in
USE!
Normal working conditions:
You need to have the GINA setup and running (rebooted) for these to work!
SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLLand reboot the machine. You may not leave the value empty, you MUST DELETE IT.
After this step you must reboot the computer so the DLL will not be
loaded upn startup.
Then you are able to remove the files:
LauncherGina.dllfrom the \winnt\system32 directory. You cannot delete the DLL before reboot since WinNT has a lock on it (as it is using it)!
LauncherGina.dll.old (if exist)
Once you have rebooted you can delete the following values within the
keys:
HKEY_LOCAL_MACHINE\software\microsoft\windows nt\currentversion\winlogon
GinaDLL
NeedCtrlAltDel
CtrlAltDelBox
CtrlAltDelBoxNever
UseCtrlAltDelBox
ShutdownWithoutLogon
RunLogonScriptSync
ForceLogoff
AllowProtectedSS
SomeBodyLoggedOn
HKEY_LOCAL_MACHINE\software\microsoft\windows nt\currentversion\winlogon\ForceLogoff
Script
Logfile
Timeout
HKEY_LOCAL_MACHINE\software\microsoft\windows nt\currentversion\winlogon\Logoff
UserScript
SystemScript
LogFile
timeout
HKEY_LOCAL_MACHINE\software\microsoft\windows nt\currentversion\winlogon\Logon
SystemScript
LogFile
timeout
UserScript
HKEY_LOCAL_MACHINE\software\microsoft\windows nt\currentversion\winlogon\Shutdown
Script
Logfile
Timeout
Account
Password
If you delete these values before you have rebooted the machine some
of the values will reappear as the still loaded GinaDll will set some of
the values again. So make sure the GinaDll is not loaded upon startup before
you remove the values or you have to do some of the removals again.
If you used SETUP.EXE you can simply run the UNISTALL option from the
Add/Remove panel of the control panel. The name of the unistall option
is "LanucherGina".
Please! If you find one dont throw the utility away! Send me some mail and I fix it!
|
used it for my own company with hardcoded settings |
|
bugfix as I forgot to pass on some messages. (It hung on occasions one of my machines). |
|
Changes to the program
- registry use: away from hardcoded - added readme file(s) |
|
First release to friends to give it a test. |
|
Logoff scripts
Logon scripts Copy gina button on GUI A few more switches avaiable on the GUI |
|
ForceLogoff user on remote machines.
Furthermore it took a while to update this as I my son was born last year! Lots of nappy changes instead of code changes. |
|
Made Launcher/Gina compatible.
Added a setup program to make administration easier. (Although I dont use it, I have my little script files in Perl inc using some of the NTRESKIT utils). |
I have been programming for years in different environments including various flavours of UNIX, OS/2 (Initor is one of my programs there) and for my PhD (some 30000 lines of code!). I have been a Tutor/Demonstrator for various languages including ASM, FORTRAN, PASCAL, COBOL, C and C++. This program is written in C as it would be total overkill to write it in C++!
I look after the LAN in a company (I own it 50%). We had OS/2 but due
to companies not providing code for Win3.1 anymore I needed to move to
NT. NT certainly has some good features and is better than OS/2 in some
cases, but note(!) that in 3.5 years of OS/2 (WARP3) I had not ONE day
where the system wasn't working at *ALL* times and the only problem I had
every now and then is that an application send some funny chars to the
printer and that stopped it working (a little reset fixed that!).
Jobst Schmalenbach
Technical Director of Barrett Consulting Group PTY LTD and Part time
PhD student
PO Box 277
782 Glenhuntly Road
Caulfield South, Vic, 3162
Australia
Phone : 61 3 9532 7677
Fax : 61 3 9532 7388
Mobile: 61 41 161 1855
Email : jobst@senna.eng.monash.edu.au (and soon jobst@barrett.com.au)
Back to the top.
Enjoy the "LauncherGina".
Jobst Schmalenbach
Copyright March 1999