Customizing GINA, Part 1
Keith Brownmore ...PrintE-mailAdd to FavoritesRateRSS (Security Briefs) Add RSS to Any Related Articles Live Spaces Digg This BlogThis! Slashdot del.icio.us Technorati Explore the code.
Download the code.
Get the sample code for this article. NEW:
Explore the sample code online!
- or -
Code download available at:
SecurityBriefs0505.exe (286KB)
ContentsWhat is GINA and Why Replace It?Where to StartSecure Attention SequenceStructure of GINAWinLogon StatesInitializationA Day in the Life of GINAGINA Modal Dialogs and ThreadsDeploying GINADebugging GINAOverthe years I‘ve had many people ask me to write about GINA, theGraphical Identification and Authentication component that serves asthe gateway for interactive logons. This month I‘ll begin my coverageof this topic to help you get started if you‘re tasked to build such abeast. I‘ll build a sample called KIOSKGNA, which is the simplestpossible GINA implementation I could think of. Next time I‘ll introducea sample called FULLGINA, a more fully featured GINA. The examples andcode snippets presented here are in unmanaged C++, which is the mostnatural way to do GINA development these days.
GINAis the pluggable part of WinLogon that third parties may replace inorder to customize the functionality or the UI of the logon experiencein Windows®. By replacing GINA, you canchoose the authentication mechanism Windows will use for interactiveusers. This is often useful for smartcard or biometric logons.
Letme state up front that replacing the GINA is an advanced technique thatshould not be taken lightly. You should only do this if you have noother choice (if, for example, you are implementing a new logonmechanism that Windows does not support).
Think for a momentabout what GINA does. It collects credentials from local and remoteusers (the latter via Terminal Services) who want to establish aninteractive logon on the machine. It then establishes a logon sessionfor that user. If GINA were compromised, it could be used to stealplaintext user passwords, user biometric data, smartcard PIN codes, andso on. A compromised GINA could act as a back door, letting a certainnormal user log in with administrative privileges. In short, if youreplace GINA, be sure to put your best programmers on the job, and thenyou should carefully review their work.
One other thing: smalland simple is best here. This component runs as SYSTEM, accepts inputfrom local and remote users, and runs all the time. Therefore this isone piece of code that must be absolutely bulletproof.
Asof this writing, you‘ll find very little documentation on customizingGINA. There are a couple of samples in the Platform SDK, GINASTUB, andGINAHOOK. GINASTUB simply loads MSGINA.DLL, the default GINAimplementation that ships with Windows, and delegates all calls throughto it. If you build and install this sample, you‘ll see no visiblechange on your system. Because GINASTUB wraps MSGINA, it can pre- andpost-process each request. This simple technique might be enough tosolve your problem, but it certainly won‘t help if you need to dosomething important and nontrivial like replace the login mechanismwith biometric authentication.
There is also a second samplecalled GINAHOOK which looks exactly like GINASTUB, except that it goesone step further by hooking into the dialogs that MSGINA displays.Using this technique you can change the look of any of the defaultlogin dialogs, and even change their behavior to some extent. But thedanger here is that you‘ll be relying on internals of MSGINA that arenot documented. This includes simple stuff like IDs for dialog controlsbut also includes behaviors of the underlying dialog procedures. Bewary of going down this road if you need to support many differentversions of the operating system, as your GINA may break when the nextservice pack is installed!
For most nontrivial GINA replacements,writing a custom GINA from the ground up is the best choice. But therearen‘t any examples of such a beast out in the wild (certainly none forfree). I‘m going to remedy this right now.
Given the complexityof the subject, I‘ll be presenting a couple of columns on the topic,and won‘t have the space to explore every dark corner of GINAdevelopment, but my goal is to give you a great head start if you needto build a GINA yourself. For further information, I‘m setting up aGINA development Wiki where you can find (and contribute) additionalinformation and sample code. Just look for Keith Brown‘s Wiki at
pluralsight.com/wiki.
Secure Attention Sequence
Beforediving in head first, let me explain a concept that you‘ll often runinto. A secure attention sequence (SAS) is something that a user doesto get the attention of the real operating system so that she canperform some secure action such as logging on, unlocking herworkstation, or changing her password.
The SAS most users arefamiliar with is Ctrl+Alt+Del, which is trapped by the kernel. Thishelps thwart malware that may try to spoof the logon dialog and stealcredentials from the user because when WinLogon receives a SASnotification, it literally switches away from the normal user desktoponto a secure desktop before prompting the user for credentials. Everwonder where your taskbar and desktop go when you press Ctrl+Alt+Del?They‘re still there; they‘re just not the current desktop anymore. Thegoal is to train users to type their password only after they pressCtrl+Alt+Del.
Now a SAS isn‘t restricted to just Ctrl+Alt+Del. Ifyou‘ve got a biometric device that can signal a driver on the computerwhen it‘s in use, that could be used as a SAS instead (for example, auser placing her finger on a print scanner). Another common SAS isgenerated by a smartcard reader when a card is inserted or removed.When you write your own GINA, you get to decide which mechanism(s) willbe used to generate a SAS. There‘s a function (WlxSasNotify) that youcall in WinLogon when you detect a SAS or want to simulate one. Ofcourse, you can tell WinLogon to use Ctrl+Alt+Del if you don‘t haveanything more appropriate.
Structure of GINA
GINAis a DLL that WinLogon loads and calls at various times while thecomputer is running. It‘s a long-running DLL that is typically unloadedonly when the machine reboots, so an absence of memory leaks is afeature!
A custom GINA must expose several entrypoints defined by Microsoft. I have listed these functions in
Figure 1.A custom GINA will almost always maintain some internal state, andWinLogon will help you here by passing a void* as the first argument tothose functions. You can decide what that pointer points to. In mysample, I will have it point to an instance of a class called Gina,where all the state and behavior of my custom GINA will be defined.
Nowone thing that confuses people who are new to GINA development is thatbesides the Wlx* functions that the custom GINA must implement,WinLogon also exposes several functions that the GINA may optionallycall (see
Figure 2).Since these functions all have the same prefix, Wlx, it‘s easy to getthem confused. A quick way to tell the difference is to look at thefirst parameter to the function. If it is HANDLE hWlx, this is afunction that WinLogon exposes for GINA to call. If it is PVOIDpWlxContext, that‘s a function that your GINA is supposed to implement.
WinLogon States
WinLogoncan be in one of three states at any given time, and for the purposesof this column, I‘ll label them whenever I refer to them so they standout clearly. The states are: LOGGED_OFF, which means that WinLogon hasno current logged on user, LOGGED_ON, which means the user is currentlylogged on, and LOCKED, which refers to being logged on with workstationlocked.
WinLogon will call some of the most important functionsin your GINA when it transitions between these various states. Now thatyou know about SAS and the WinLogon state machine, let me show you GINAin action.
Figure 3 GINA State Diagram
Figure 3shows a more fleshed-out diagram of GINA states and transitions, andyou‘ll want to refer to it as you read. It includes many of the majorfunctions in your GINA that WinLogon will call, showing the normalsequence of events.
Initialization
Whenthe machine boots up, once the operating system has initialized andstarted any services marked as automatic, WinLogon loads GINA and callsWlxNegotiate followed by WlxInitialize.
Negotiate is trivial toimplement. It simply gives GINA and WinLogon a chance to verify eachother‘s version so that things work smoothly later on. The version youchoose determines how much functionality WinLogon will expect from yourGINA, and also how much functionality you can expect from WinLogon. Asof this writing, the most current version you can implement is 1.4,which provides a bit of extra support for Remote Desktop in Windows XP,so that‘s the version I‘ll use in my FULLGINA sample.
InInitialize, you will receive a handle (hWlx) that represents WinLogon,along with a pointer to a table of functions that your GINA may call.These are the Wlx* functions that WinLogon implements, the ones thattake a HANDLE as their first argument. In order to call these functionslater on, you‘ll need to store this handle and pointer somewhere.That‘s where the last argument comes in, pWlxContext, which is an outparameter that you pass back to WinLogon. The simplest approach is topoint this at a data structure (class or struct) that you use to holdyour GINA‘s state, which includes the handle and dispatch table pointergiven to you by WinLogon.
Figure 4 shows a very simple example of this.
Theactual implementation in my sample is a bit more sophisticated thanthis, but this clearly demonstrates the idea. From now on, whenWinLogon calls any of the functions in your GINA, pWlxContext will bepassed as the first argument, so you‘ll always have access to yourstate. For example:
BOOL WINAPI WlxIsLogoffOk(PVOID pWlxContext) {return ((Gina*)pWlxContext)->IsLogoffOk();}By simply dispatching each call to the GINA class, I can simplyadd member variables to the class to hold any state my GINA needs. It‘sa very natural way to develop a GINA, and you can reuse the stub codeon any project.
A Day in the Life of GINA
OnceGINA is initialized, WinLogon will start running its state machine,calling functions exported from GINA as its state changes. Afterinitialization, no user is logged on yet, so WinLogon will ask you todisplay a logon prompt by calling WlxDisplaySASNotice. A typical GINApops up a familiar dialog that says "Press Ctrl+Alt+Del to log in" atthis point.
When the user presses Ctrl+Alt+Del, or GINA callsWlxSasNotify to generate a SAS of some other type, WinLogon dismissesyour dialog (more on this later), and calls the next function in yourGINA: WlxLoggedOutSAS.
WlxLoggedOutSAS may seem like a funnyname, but it completely describes what‘s going on in your GINA. You arecurrently in the LOGGED_OUT state, and you‘ve received a SAS. Your jobhere is to authenticate the user who is trying to log on. My FULLGINAsample opens a dialog to retrieve the user‘s name and password, andcalls LsaLogonUser to see if the password is valid. If it‘s not valid,I present an error message, then loop back around and ask for a username and password once again. Once given a valid set of credentials,LsaLogonUser establishes a logon session for the user and returns atoken handle to my code, which I then return to WinLogon.
WinLogontakes the token returned from the GINA and configures the accesscontrol list (ACL) on the default desktop to make it private for thisuser‘s logon session. No other logged on user is allowed to access thisdesktop, except for administrators and the operating system itself. Nowthat the default desktop is ready to go, WinLogon calls back into GINAthrough WlxActivateUserShell. GINA must now launch the user‘s shell andreturn to WinLogon.
It‘s interesting that in theWlxActivateUserShell call, WinLogon does not provide the user‘s tokenhandle that your GINA gave it in the last step. This is an example ofstate that your GINA must maintain internally. Now WinLogon is in theLOGGED_ON state, and the logged on user is in control. Just for kicks,let‘s say the user presses Ctrl+Alt+Del. Can you guess the name of thefunction WinLogon will call?
If you guessed WlxLoggedOnSAS, you‘re right. Here, you will likely give the user a set of options. Figure 5shows the typical dialog displayed at this point. It should lookfamiliar. This dialog is a lot easier to implement than it looksbecause WinLogon provides most of the functionality for you. GINA justneeds to tell WinLogon which option the user chose by returning one ofseveral predefined constants from WlxLoggedOnSAS. Handling the changepassword request is the only thing that requires much programmingeffort, and if you‘re using passwords, you‘ll need this functionalityelsewhere in the GINA anyway.
Figure 5 WlxLoggedOnSAS
Let‘ssay the user chooses to lock the workstation. At this point, WinLogonwill call GINA‘s WlxDisplayLockedNotice. This is similar to theWlxDisplaySASNotice. You simply display a modal dialog box and wait forGINA to dismiss it.
When the user presses Ctrl+Alt+Del, WinLogonwill call WlxWkstaLockedSAS, at which time you should ask the user toauthenticate once again. The tricky part here is that your GINA needsto tell WinLogon whether this is the same user who originally lockedthe workstation and is returning to unlock it, or if it‘s someone elseentirely. In the latter case, you‘ll verify that this new user is anadministrator and ask if he would like to forcefully log off thecurrent user, in which case you‘ll eventually see a WlxLogoff call intoyour GINA followed by a return to WlxDisplaySASNotify, asking the userto log in.
If the user simply unlocks her workstation, WinLogonwill return to the LOGGED_ON state and once again the user will be incontrol of her desktop. Now keep in mind that the user might log off,shut down, or even lock her workstation without necessarily pressingCtrl+Alt+Del and going through the GINA. For example, theLockWorkstation API or even ExitWindowsEx can be called from anyapplication, including Windows Explorer. Of course, the GINA will benotified if the user does log off or lock the workstation, but it‘sgood to keep in mind that not all of these user actions will beinitiated via GINA.
GINA Modal Dialogs and Threads
Anymodal dialog you show from GINA needs to be interruptible by WinLogon.There are several reasons WinLogon might need to interrupt GINA‘s userinterface: the user might be idle for several minutes, a SAS couldoccur, a screen saver might kick in, and so on. WinLogon has a verysimple way of dealing with this. Instead of calling the normal Win32®functions DialogBox, DialogBoxParam, and so forth, GINA instead callsequivalent functions exposed through WinLogon‘s dispatch table.WinLogon can then hook into the dialog box procedure and end the modaldialog whenever it needs to. So if you‘re using a framework like MFC toimplement your dialog boxes, you‘ll need to tweak it a bit to callthrough WinLogon‘s APIs.
But if you‘re pulling in MFC or evensomething more sophisticated, you might ask yourself if GINA is theright place for such application frameworks. Remember that a good GINAis small, simple, and bulletproof. Try to keep the amount of code yourGINA loads to an absolute minimum.
While I‘m on the subject ofuser interface code, I want to point out that the GINA really is a GUIcomponent. It‘s designed to be single threaded, at least as far asWinLogon is concerned. WinLogon doesn‘t expect to be called back on anythread other than the one it used to call into GINA in the first place.For example, if GINA detects a SAS from an external device, itshouldn‘t call WlxSaSNotify on some random thread. It should insteaduse WinLogon‘s thread to make the call. Your best bet is to use thethread that called into WlxDisplaySAS/LockedNotice to let WinLogon knowthat the user generated a SAS via your device and wants to log in orunlock the workstation. If you do have a secondary thread that receivesthe device notification, you can simply post a message to your dialogthat‘s displaying the SAS or Locked notice. The UI thread can thensafely call WlxSasNotify.
Deploying GINA
Onceyour GINA is built, you‘ll want to deploy it and test it out. Istrongly recommend that you don‘t deploy the GINA to your developmentbox. Use a separate machine to host your GINA for testing. My own setuprelies on Virtual PC with its undo disk feature. If something goesreally wrong and I end up in an infinite reboot loop (yes, this willhappen to you at some point), I just close down the Virtual PC anddiscard changes. Another option is to jump into Safe mode to remove amisbehaving GINA.
To deploy the GINA for testing, just copy theDLL onto the target machine (it is appropriate to place it in theSystem32 directory), and update that machine‘s registry by adding anamed value under WinLogon‘s key:
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WinLogon
The named value should be GinaDLL, of type REG_SZ, andits value should be the name of the DLL. Reboot the machine, and you‘llfind your GINA running when the machine boots back up. If you aretrying to redeploy a new version of your GINA, you may find that theexisting version is locked by the operating system and that you cannotoverwrite the file. In this case, rename the GINA file on disk beforecopying the new one. Then you can simply delete the old GINA later.
Ifyou get into trouble and need to restore the old GINA, just delete theGinaDLL key and remember that you can access the registry of anymachine remotely, as long as you can be authenticated as anadministrator on the target machine. Just bring up REGEDIT.EXE andchoose File | Connect Network Registry.
When you have finishedall your testing and are finally deploying for real, after copying yourGINA DLL onto the user‘s disk, you should make sure to set the ACL onthe GINA DLL to ensure that only administrators are allowed to modifythe file. You won‘t get this level of protection by default simply byinstalling into the System32 directory.
Debugging GINA
Unlessyou‘re someone who regularly uses low-level symbolic debuggers, youwon‘t enjoy debugging a custom GINA while it‘s running inside WinLogon.That‘s why I designed my sample so that it can be run outside ofWinLogon, and I recommend you design yours the same way. I simplyexpose one extra entry point, called DebugGINA, into my GINA DLL. Innon-debug builds, this function does absolutely nothing. In debugbuilds, however, I can use this entrypoint to drive the GINA throughany scenario that I want to debug. The key to making this possible isto abstract your interface to WinLogon so that when debugging, you cansimulate the WinLogon dispatch table by providing your ownimplementation. The standard way of doing this in unit testing circlesis to use interfaces coupled with mock objects.
I use a verysimple interface called IWinLogon that has methods for each of thefunctions my GINA needs to call in WinLogon. WlxDialogBox becomesIWinLogon::wlxDialogBox, for example. Then during normal operation, Iuse an implementation of IWinLogon that actually calls throughWinLogon‘s dispatch table. During debugging, I substitute a mockimplementation that in many cases can get away with doing absolutelynothing. My mock object‘s implementation of IWinLogon::wlxDialogBox,simply calls DialogBox. It‘s dirt simple, and it works like a charm.
Ofcourse, you‘ll need a program to load your GINA and call that debugentry point, but that‘s easy. Here‘s a simple snippet of code thatcalls LoadLibrary and GetProcAddress to call the DebugGINA entrypoint.Just build something like this as an EXE and you can step right intoyour GINA from the debugger.
void main() {GetProcAddress(LoadLibrary("mygina.dll"),"DebugGINA")();}
Now before you do this, you‘ll want to ensure thatyou‘re debugging the program while running as SYSTEM to simulate theWinLogon environment. When I‘m doing a lot of GINA debug sessions, Ikeep a command prompt running as SYSTEM open, and just type DEVENV fromthere to launch my debugger, load the project, and trace right in.
Howdo you get a command prompt running as SYSTEM? One way to do it is toschedule an interactive job with CMD.EXE as the target application:
at 7:32pm /interactive cmdOf course the time you choose should be sometime in the very nearfuture, like one minute from now. This causes the scheduler service(which runs as SYSTEM) to launch the command prompt, which inherits thesecurity context of SYSTEM. Your debugger will inherit that securitycontext as well when launched from your SYSTEM command prompt, whichyou should title as such (type this into the command prompt after itstarts):title SYSTEM (DANGER, WILL ROBINSON)
The silly title is actually quite serious—you shouldclose this command prompt when you‘re not debugging because SYSTEM hasfull control of everything on your machine, and mistyping in thiscommand prompt could have serious consequences.
In the nextinstallment of this column, I‘ll drill down into some of the morecomplicated aspects of GINA development such as calling LsaLogonUser toestablish a logon, using CreateProcessAsUser to launch the shell, andother important topics. At the end of this series, you‘ll have a simplebut fully featured GINA implementation to start working with.
Send your questions or comments for Keith to
briefs@microsoft.com.
NEW:
Explore the sample code online! - or - Code download available at:
SecurityBriefs0505.exe (286KB)
