diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/windows/README | 191 |
1 files changed, 92 insertions, 99 deletions
diff --git a/src/windows/README b/src/windows/README index 47261f746..dee704534 100644 --- a/src/windows/README +++ b/src/windows/README @@ -1,21 +1,35 @@ 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 @@ -29,78 +43,57 @@ during the build. 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: @@ -126,12 +119,13 @@ those are found, a default value is used. 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: @@ -139,27 +133,23 @@ 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. @@ -243,6 +233,9 @@ On workstation platforms the key is specified as: 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 |