1 Building & Running Kerberos 5 on Windows 2 ---------------------------------------- 3 4This file documents how to build MIT Kerberos for Windows. 5The MIT Kerberos for Windows distribution contains additional components 6not present in the Unix krb5 distribution, most notably the 7MIT Kerberos Ticket Manager application. 8 9To build Kerberos 5 on Windows, you will need the following: 10 11* A version of Visual Studio (at least 2013) which includes the 12 Microsoft Foundation Classes libraries. These instructions will 13 work for Visual Studio 2017 Community or Professional, both of which 14 include the MFC libraries if the "Visual C++ MFC" checkbox is 15 selected after enabling the "Desktop development with C++" workload. 16 If you do not plan to build the graphical ticket manager 17 application, the MFC libraries are not required. 18 19* A version of Perl. 20 21* Some common Unix utilities such as sed/awk/cp/cat installed in the 22 command-line path. 23 24* To build an MSI installer, the Windows Installer XML (WiX) toolkit, 25 and to ensure that the HTML Help Compiler (hhc.exe) and the WiX 26 tools are in your command-line path. WiX version 3.11.1 is verified 27 to work with this codebase. 28 29A simple way to get the necessary Unix utilities is to install Git 30BASH from https://gitforwindows.org and configure it to add the Unix 31utilities to the command-line path. In some versions of Windows (not 32the most current versions), the Unix utilities can alternatively be 33obtained via the Utilities and SDK for UNIX-based Applications, which 34may be enabled as a Windows feature and then the components installed. 35Note that the Windows nmake will not find the SUA awk utility in the 36path unless it is named awk.exe; the permissions on the utility may 37need correcting if awk.exe is created as a copy of the original awk. 38 39Git BASH contains a version of Perl, which will work to build krb5 if 40the newlines in the source tree are not translated to native newlines. 41Strawberry Perl will work regardless of whether newlines are 42translated. If both Git BASH and Strawberry Perl are installed, you 43may need to adjust the command line path to ensure that the preferred 44Perl appears first. 45 46The krb5 source tree may be obtained either directly on the Windows 47machine with a native git client cloning the krb5 public mirror at 48https://github.com/krb5/krb5.git or on a separate (Unix) machine and 49copied over, such as from a VM host onto a Windows VM. If you are 50checking out the sources with git and are using the Git BASH Perl, 51make sure to set git's core.autocrlf variable to "input" or "false" to 52avoid translating newlines. 53 54After Visual Studio is installed, you should be able to invoke 32-bit 55and 64-bit command prompts via the start menu (Visual Studio 2017 -> 56x86 Native Tools Command Prompt and x64 Native Tools Command Prompt). 57At the current time, Kerberos 5 can only be built for the x64 target 58if the host platform is also 64-bit, because it compiles and runs 59programs during the build. 60 61IMPORTANT NOTE: By default, the sources are built with debug 62information and linked against the debug version of the Microsoft C 63Runtime library, which is not found on most Windows systems unless 64they have development tools, and requires a separate license to 65distribute. To build a release version, you need to define NODEBUG 66either in the environment or the nmake command-line. Debug 67information in the compiled binaries and libraries may be retained by 68defining DEBUG_SYMBOL in the environment or on the nmake command line. 69 70 71Building the code and installer: 72------------------------------- 73 74First, make sure you have sed, (g)awk, cat, and cp. 75You must also define KRB_INSTALL_DIR either in the environment or 76on the command line (for nmake install). If you are proceeding to build 77the MSI installer, this directory should be a temporary staging area in or 78near your build tree. The directory must exist before nmake install 79is run. The 64-bit installer provides 32-bit libraries, so a 32-bit build 80and install must be performed before the 64-bit build. 81 82To skip building the graphical ticket manager, run "set NO_LEASH=1" 83before building, and do not build the installers. 84 85In a 32-bit command shell: 86 87 1) set KRB_INSTALL_DIR=\path\to\dir # Where bin/include/lib lives 88 2) cd xxx\src # Go to where source lives 89 3) nmake -f Makefile.in prep-windows # Create Makefile for Windows 90 4) nmake [NODEBUG=1] # Build the sources 91 5) nmake install [NODEBUG=1] # Copy headers, libs, executables 92 6) cd windows\installer\wix # Go to where the installer source is 93 7) nmake [NODEBUG=1] # Build the installer 94 8) rename kfw.msi kfw32.msi # Save the 32-bit installer 95 96In a 64-bit command shell: 97 98 9) set PATH=%PATH%;"%WindowsSdkVerBinPath%"\x86 # To get uicc.exe 9910) set KRB_INSTALL_DIR=\path\to\dir # Where bin/include/lib lives 10011) cd xxx\src # Go to where source lives 10112) nmake clean # Clean up the 32-bit objects 10213) nmake [NODEBUG=1] # Build the sources for 64-bit 10314) nmake install [NODEBUG=1] # Copy 64-bit lib/executables 10415) cd windows\installer\wix # Back to the installer source 10516) nmake clean # Remove 32-bit leavings 10617) nmake [NODEBUG=1] # Build the 64-bit installer 10718) rename kfw.msi kfw64.msi # And name it usefully 108 109Step 9 may be skipped if uicc is already in the command-line path (try 110running "uicc" to see if you get a usage message or a not-found 111error), or if you are not building the graphical ticket manager. 112 113Visual Studio 2013 and 2015 provide only a single command prompt. 114Within this prompt, use "vcvarsall.bat x86" and "vcvarsall.bat amd64" 115to switch to 32-bit and 64-bit mode. 116 117 118Running Kerberos 5 Apps: 119----------------------- 120 121Make sure you have a valid krb5.ini file. 122By default, an empty krb5.ini is installed in CSIDL_COMMON_APPDATA 123(that is, %SystemDrive%\ProgramData\MIT\Kerberos5\ on newer-than-XP). 124(ProgramData is a hidden folder.) You may need to customize it with 125settings for your site, but since DNS lookups are enabled for locating 126KDCs, many sites will not need further customization. The file format is 127identical to that of a Unix krb5.conf file. 128 129 130krb5.ini File: 131------------- 132 133WARNING: Despite its name, this is not a Windows .ini file. 134Therefore, do not try to use any .ini tools, including the Windows API 135or any installer tools to manipulate this file. Its format is subtly 136different from Windows .ini files! 137 138 139Controlling the Kerberos 5 Run-Time Environment: 140----------------------------------------------- 141 142The Kerberos 5 configuration file and credentials cache can be 143controlled with environment variables and registry settings. The 144environment variable for a particular setting always takes precedence. 145Next in precedence comes the setting in the registry under 146HKEY_CURRENT_USER\Software\MIT\Kerberos5. Then comes the registry 147setting under HKEY_LOCAL_MACHINE\Software\MIT\Kerberos5. If none of 148those are found, a default value is used. 149 150Configuration File: 151- Environment: KRB5_CONFIG 152- Registry Value: config 153- Default: looks in the user's AppData directory, the machine's ProgramData 154 directory, krb5_32.dll's dir and Windows directory 155 156Default Credentials Cache: 157- Environment: KRB5CCNAME 158- Registry Value: ccname 159- Default: API: 160 161 162Credentials Cache: 163----------------- 164 165In addition to standard FILE: (disk file) and MEMORY: (in-process 166non-shared memory) Windows supports the API: cache type, which is a 167shared memory cache. Kerberos for Windows also has access to an 168MSLSA: cache type, which directly accesses the Microsoft Kerberos 169Logon Session credentials cache. The MSLSA: cache is available when the 170user logon is performed using Kerberos either to an Active Directory Domain 171or a non-Microsoft KDC; the ms2mit and mit2ms utilities can also be used 172to interact with it, though there are some limitations. 173 174A user is able to logon to Windows using the Kerberos LSA if the machine 175is part of a Windows Active Directory domain or if the machine has been 176configured to authenticate to a non-Microsoft KDC such as MIT. 177The instructions for configuring a Windows 2000 XP workstation to 178authenticate to a non-Microsoft KDC are documented in TechNet somewhere. 179In brief: 180 181 1. Install the Windows support tools in order to obtain KSETUP.EXE 182 and KTPASS.EXE. 183 2. Install the Windows Resource Kit to obtain KERBTRAY.EXE and KLIST.EXE 184 3. Add Realms and associated KDCs with: *KSETUP /AddKdc <realm> 185 [<kdcname>]*. If you leave off the <kdcname> DNS SRV records will 186 be used. 187 4. Specify the password change service host for the realm with: 188 *KSETUP /AddKpasswd <realm> <Kpwdhost>* 189 5. Assign the realm of the local machine with: *KSETUP /SetRealm 190 <realm>* where realm must be all upper case. 191 6. Assign the local machine's password with: *KSETUP 192 /SetComputerPassword <Password> 193 * 194 7. Specify the capabilities of the Realm KDC with: *KSETUP 195 /SetRealmFlags <realm> <flag> [<flag> ...]* where flags may be 196 *None, SendAddress, TcpSupported, Delegate, *and *NcSupported*, 197 8. Map principal names to local accounts with: *KSETUP /MapUser 198 <principal> <account>* 199 200On the MIT KDC, you must then create service principals using the "Password" 201assigned to the machine. So far the minimum list of principals required appear 202to be for a machine named "mymachine" in the realm "EXAMPLE.COM" with a 203domain name of "example.com": 204 205 * host/mymachine@EXAMPLE.COM 206 * host/mymachine.example.com@EXAMPLE.COM 207 * cifs/mymachine@EXAMPLE.COM 208 * cifs/mymachine.example.com@EXAMPLE.COM 209 210There may very well be other services for which principals must be created depending 211on what services are being executed on the machine. 212 213It is very important to note that while you can successfully log into a Windows 214workstation by authenticating to the KDC without creating a host key; the logon 215session you receive will not be a Kerberos Logon Session. There will be no Kerberos 216principal and no LSA cache to access. 217 218The result of a real KSETUP configuration looks like this: 219 220 [C:\4\4NT]ksetup 221 default realm = KRB5.COLUMBIA.EDU (external) 222 ATHENA.MIT.EDU: 223 kdc = kerberos.mit.edu 224 kdc = kerberos-1.mit.edu 225 kdc = kerberos-2.mit.edu 226 kdc = kerberos-3.mit.edu 227 Realm Flags = 0x0 none 228 CC.COLUMBIA.EDU: 229 kdc = kerberos.cc.columbia.edu 230 Realm Flags = 0x0 none 231 GRAND.CENTRAL.ORG: 232 kdc = penn.central.org 233 kdc = grand-opening.mit.edu 234 Realm Flags = 0x0 none 235 KRB5.COLUMBIA.EDU: 236 kdc = yclept.kermit.columbia.edu 237 Realm Flags = 0x0 none 238 OPENAFS.ORG: 239 kdc = virtue.openafs.org 240 Realm Flags = 0x0 none 241 Mapping jaltman@KRB5.COLUMBIA.EDU to jaltman. 242 Mapping jaltman@CC.COLUMBIA.EDU to jaltman. 243 Mapping jaltman@ATHENA.MIT.EDU to jaltman. 244 Mapping all users (*) to a local account by the same name (*). 245 246The MSLSA: credential cache relies on the ability to extract the entire 247Kerberos ticket including the session key from the Kerberos LSA. In an 248attempt to increase security Microsoft has begun to implement a feature 249by which they no longer export the session keys for Ticket Getting Tickets. 250This has the side effect of making them useless to the MIT krb5 library 251when attempting to request additional service tickets. 252 253This new feature has been seen in Windows 2003 Server, Windows 2000 Server SP4, 254and Windows XP SP2. We assume that it will be implemented in all future 255Microsoft operating systems supporting the Kerberos SSPI. Microsoft does work 256closely with MIT and has provided a registry key to disable this new feature. 257On server platforms the key is specified as: 258 259 HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters 260 AllowTGTSessionKey = 0x01 (DWORD) 261 262On workstation platforms the key is specified as: 263 264 HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos 265 AllowTGTSessionKey = 0x01 (DWORD) 266 267The Kerberos for Windows installer automatically sets this key on installation 268and unsets it on uninstall, allowing the MSLSA: cache type to be used. 269 270It has been noted that the Microsoft Kerberos LSA does not provide enough 271information within its KERB_EXTERNAL_TICKET structure to properly construct 272the Client Principal simply by examining a single ticket. From the MSDN 273Library: 274 275 ClientName 276 KERB_EXTERNAL_NAME structure that contains the client name in the ticket. 277 This name is relative to the current domain. 278 279 DomainName 280 UNICODE_STRING that contains the name of the domain that corresponds to 281 the ServiceName member. This is the domain that issued the ticket. 282 283 TargetDomainName 284 UNICODE_STRING that contains the name of the domain in which the ticket is 285 valid. For an interdomain ticket, this is the destination domain. 286 287 AltTargetDomainName 288 UNICODE_STRING that contains a synonym for the destination domain. Every 289 domain has two names: a DNS name and a NetBIOS name. If the name returned 290 in the ticket is different from the name used to request the ticket (the 291 Kerberos Key Distribution Center (KDC) may do name mapping), this string 292 contains the original name. 293 294Unfortunately, there is no field here which contains the domain of the client. 295In order for the krb5_ccache to properly report the client principal name, the 296client principal name is constructed by utilizing the ClientName and DomainName 297fields of the Initial TGT associated with the Kerberos LSA credential cache. 298To disable the use of the TGT info and instead simply use the "DomainName" field 299of the current ticket define one of the following registry keys depending on 300whether the change should be system global or just for the current user. 301 302 HKLM\Software\MIT\Kerberos5\ 303 PreserveInitialTicketIdentity = 0x0 (DWORD) 304 305 HKCU\Software\MIT\Kerberos5\ 306 PreserveInitialTicketIdentity = 0x0 (DWORD) 307 308GSSAPI Sample Client: 309--------------------- 310 311The GSS API Sample Client provided in this distribution is compatible with the 312gss-server application built on Unix/Linux systems. This client is not compatible 313with the Platform SDK/Samples/Security/SSPI/GSS/ samples which Microsoft has been 314shipping as of January 2004. Revised versions of these samples are available upon 315request to krbdev@mit.edu. 316 317More Information: 318---------------- 319 320For more information, please read the Kerberos 5 documentation in 321the doc directory of the distribution. 322