Update windows/README

The build instructions have changed somewhat, as have the requirements
for a build environment.
The default behavior for KRB5_CONFIG and KRB5CCNAME has also changed.
Attempt to remove mention of overly specific Windows versions that
are now quite old when the behavior persists in newer versions of Windows.
Document the usage of DNS by default and the reduced need for a large
krb5.ini file.
Talk a little more about the LSA cache.

The kerbsrc.win target is no longer supported.

ticket: 7363 (new)
target_version: 1.10.4
tags: pullup

1 files changed, 92 insertions, 99 deletions

diff --git a/src/windows/README b/src/windows/README
index 47261f7467..dee7045347 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