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