Building & Running Kerberos 5 on Windows
----------------------------------------
-This file documents how to build the standalone source distribution of
-Kerberos 5 on Windows. The MIT Kerberos for Windows distribution
-contains additional components not present in the Kerberos 5 source
-code.
-
-To build Kerberos 5 on Windows, you will need the Windows SDK (XP SP2
-or later) and a version of Perl installed in the command-line path.
-Current versions of the Windows SDK require the .NET framework to be
-installed.
-
-There are two methods for building a Windows version of Kerberos 5.
-The traditional method involves starting on a Unix machine and
-creating a distribution that can be built on Windows. The second
-method works from the sources that come from the Unix distribution if
-you have certain Unix-type utilities (see below).
+This file documents how to build MIT Kerberos for Windows.
+The MIT Kerberos for Windows distribution contains additional components
+not present in the Unix krb5 distribution, most notably the
+MIT Kerberos Ticket Manager application.
+
+To build Kerberos 5 on Windows, you will need the Windows SDK (XP SP3
+or later), VisualStudio (2010 Professional), a version of Perl, and some
+common Unix utilities such as sed/awk/cp/cat installed in the
+command-line path. To build an MSI installer, you will additionally
+need the Windows Installer XML (WiX) toolkit, and to ensure that
+the HTML Help Compiler (hhc.exe) and the WiX tools are in your command-line
+path.
+
+The Unix utilities can be obtained via the Utilities and SDK for UNIX-based
+Aplications, which may be enabled as a Windows feature and then the
+components installed. Note that the Windows nmake will not find the
+SUA awk utility in the path unless it is named awk.exe; the permissions
+on the utility may need correcting if awk.exe is created as a copy of
+the original awk.
+
+There is a version of perl available through the SUA, but it is not
+sufficient to build krb5. An external perl such as Strawberry Perl
+or ActiveState Perl is necessary.
+
+The krb5 source tree may be obtained either directly on the Windows
+machine with a native git client cloning the krb5 public mirror
+at https://github.com/krb5/krb5.git or on a separate (Unix) machine
+and copied over, such as from a VM host onto a Windows VM.
+The kerbsrc.zip method is no longer supported.
After the Windows SDK is installed, you should be able to invoke an
SDK command prompt via the start menu (All Programs -> Microsoft
IMPORTANT NOTE: By default, the sources are built with debug
information and linked against the debug version of the Microsoft C
Runtime library, which is not found on most Windows systems unless
-they have development tools. To build a release version, you need to
-define NODEBUG either in the environment or the nmake command-line.
-
-DNS Support: To support DNS lookups, you will need to define
-KRB5_DNS_LOOKUP, KRB5_DNS_LOOKUP_KDC, or KRB5_DNS_LOOKUP_REALMS. When
-any of the KRB5_DNS_LOOKUP definitions are used, the default build will use
-the WSHelper library which is part of the Kerberos for Windows (Kfw)
-distribution. If you are building outside of KfW and wish to build Krb5
-with DNS support, you must provide a resolver library whose include files
-match the Unix resolver library. You will need to define KRB5_NO_WSHELPER,
-define DNS_INC to point to the include directory for the library and DNS_LIB
-to library itself. The default is not to support DNS because the build
-cannot know whether there is a DNS resolver library around for it to use.
-
-
-Traditional Build Method:
-------------------------
-
-On the Unix side
-1) cd xxx/src # Go to where the source lives
-2) make -f Makefile.in kerbsrc.zip # Do some Unix-side configuring
- # ...and create kerbsrc.zip
-3) <transfer kerbsrc.zip to the PC>
-
+they have development tools, and requires a separate license to distribute.
+To build a release version, you need to define NODEBUG either in the
+environment or the nmake command-line and use setenv to enter a release
+build environment with "setenv /release".
+Debug information in the compiled binaries and libraries may be retained
+by defining DEBUG_SYMBOL in the environment or on the nmake command line.
-On the PC side
-1) md \krb5 # Create dir where we'll put the tree
-2) cd \krb5
-3) unzip kerbsrc.zip
- - or -
- pkunzip -d kerbsrc.zip
-4) nmake [NODEBUG=1] [DNS-options] # Build the sources
-5) nmake install [NODEBUG=1] [options] # Copy headers, libs, executables
-
-All-Windows Build Method:
+Building the code and installer
------------------------
-First, make sure you have sed, gawk, cat, and cp.
-
-1) cd xxx/src # Go to where the source lives
-2) nmake -f Makefile.in prep-windows # Create Makefile for Windows
-3) nmake [NODEBUG=1] [DNS-options] # Build the sources
-4) nmake install [NODEBUG=1] [options] # Copy headers, libs, executables
-
-
-Notes on the install Target:
----------------------------
-
-For the install target, you will need to define KRB_INSTALL_DIR to
-point to the directory where the header, library, and executable files
-will be installed. You can either define this in the environment or
-at the nmake command-line. For example:
-
-nmake install [NODEBUG=1] KRB_INSTALL_DIR=c:\sdk\krb5
-
-Make sure you create the directory first. Otherwise, nmake will
-complain. The files will get installed into include, lib, and bin
-subdirectories. You can then copy the binaries to where ever you want
-have them (probably somewhere in your path).
+First, make sure you have sed, (g)awk, cat, and cp.
+You must also define KRB_INSTALL_DIR either in the environment or
+on the command line (for nmake install). If you are proceeding to build
+the MSI installer, this directory should be a temporary staging area in or
+near your build tree. The directory must exist before nmake install
+is run. The 64-bit installer provides 32-bit libraries, so a 32-bit build
+and install must be performed before the 64-bit build.
+
+ 1) set CPU=i386 # Get 32-bit target in environment
+ 2) set KRB_INSTALL_DIR=\path\to\dir # Where bin/include/lib lives
+ 3) setenv /x86 [/release] # Tell nmake to target 32-bit
+ 4) cd xxx/src # Go to where the source lives
+ 5) nmake -f Makefile.in prep-windows # Create Makefile for Windows
+ 6) nmake [NODEBUG=1] # Build the sources
+ 7) nmake install [NODEBUG=1] # Copy headers, libs, executables
+ 8) cd windows\installer\wix # Go to where the installer source is
+ 9) nmake # Build the installer
+10) rename kfw.msi kfw32.msi # Save the 32-bit installer
+11) set CPU=AMD64 # Proceed to the 64-bit build
+12) setenv /x64 [/release] # Must set both CPU and nmake env
+13) cd ..\..\.. # Back to the sources
+14) nmake clean # Clean up the 32-bit objects
+15) nmake [NODEBUG=1] # Build the sources for 64-bit
+16) nmake install [NODEBUG=1] # Copy 64-bit lib/executables
+17) cd windows\installer\wix # Back to the installer source
+18) nmake clean # Remove 32-bit leavings
+19) nmake # Build the 64-bit installer
+20) rename kfw.msi kfw64.msi # And name it usefully
Running Kerberos 5 Apps:
-----------------------
-Make sure you have a valid krb5.ini file. That will look just like a
-Unix krb5.conf file. You can place this file in the same directory as
-your krb5_32.dll (this will be the bin subdirectory of your install
-directory, if you did not move the binaries) or in your Windows
-directory (typically "C:\Windows"). You should then be able to run
-the applications that are built. Note that Kerberos 5 will not look
-for the krb5.ini file in your path.
+Make sure you have a valid krb5.ini file.
+By default, an empty krb5.ini is installed in CSIDL_COMMON_APPDATA
+(that is, %SystemDrive%\ProgramData\MIT\Kerberos5\ on newer-than-XP).
+(ProgramData is a hidden folder.) You may need to customize it with
+settings for your site, but since DNS lookups are enabled for locating
+KDCs, many sites will not need further customization. The file format is
+identical to that of a Unix krb5.conf file.
krb5.ini File:
Configuration File:
- Environment: KRB5_CONFIG
- Registry Value: config
-- Default: looks in krb5_32.dll's dir and Windows directory
+- Default: looks in the user's AppData directory, the machine's ProgramData
+ directory, krb5_32.dll's dir and Windows directory
Default Credentials Cache:
- Environment: KRB5CCNAME
- Registry Value: ccname
-- Default: API:krb5cc or FILE:%TEMP%\krb5cc or FILE:<windows dir>\krb5cc
+- Default: API:
Credentials Cache:
In addition to standard FILE: (disk file) and MEMORY: (in-process
non-shared memory) Windows supports the API: cache type, which is a
-shared memory cache. This is implemented by krbcc32.dll, which is not
-included the the krb5-only distribution. Rather, it is part of MIT's
-Kerberos for Win32 suite.
-
-As of the 1.3.2 release, a new cache type, MSLSA:, has been added for
-use in accessing the Microsoft Kerberos Logon Session credentials
-cache. The MSLSA: cache is available when the user logon is performed
-using Kerberos either to an Active Directory Domain or a non-Microsoft
-KDC.
+shared memory cache. Kerberos for Windows also has access to an
+MSLSA: cache type, which directly accesses the Microsoft Kerberos
+Logon Session credentials cache. The MSLSA: cache is available when the
+user logon is performed using Kerberos either to an Active Directory Domain
+or a non-Microsoft KDC; the ms2mit and mit2ms utilities can also be used
+to interact with it, though there are some limitations.
A user is able to logon to Windows using the Kerberos LSA if the machine
-is part of a Windows 2000 or Windows 2003 Active Directory domain or
-if the machine has been configured to authenticate to a non-Microsoft KDC
-such as MIT. The instructions for configuring a Windows 2000 XP
-workstation to authenticate to a non-Microsoft KDC are documented
-in TechNet somewhere. In brief:
-
- 1. Install the Windows 2000 or XP support tools in order to obtain
- the tools: KSETUP.EXE and KTPASS.EXE.
- 2. Install the Windows 2000 or XP Resource Kit to obtain the tools
- KERBTRAY.EXE and KLIST.EXE
+is part of a Windows Active Directory domain or if the machine has been
+configured to authenticate to a non-Microsoft KDC such as MIT.
+The instructions for configuring a Windows 2000 XP workstation to
+authenticate to a non-Microsoft KDC are documented in TechNet somewhere.
+In brief:
+
+ 1. Install the Windows support tools in order to obtain KSETUP.EXE
+ and KTPASS.EXE.
+ 2. Install the Windows Resource Kit to obtain KERBTRAY.EXE and KLIST.EXE
3. Add Realms and associated KDCs with: *KSETUP /AddKdc <realm>
[<kdcname>]*. If you leave off the <kdcname> DNS SRV records will
be used.
HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos
AllowTGTSessionKey = 0x01 (DWORD)
+The Kerberos for Windows installer automatically sets this key on installation
+and unsets it on uninstall, allowing the MSLSA: cache type to be used.
+
It has been noted that the Microsoft Kerberos LSA does not provide enough
information within its KERB_EXTERNAL_TICKET structure to properly construct
the Client Principal simply by examining a single ticket. From the MSDN
projects / thirdparty / krb5.git / commitdiff
