"Fossies" - the Fresh Open Source Software Archive

Member "krb5-1.18/src/windows/README" (12 Feb 2020, 14577 Bytes) of package /linux/misc/krb5-1.18.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 1.17.1_vs_1.18.

    1 	       Building & Running Kerberos 5 on Windows
    2 	       ----------------------------------------
    3 
    4 This file documents how to build MIT Kerberos for Windows.
    5 The MIT Kerberos for Windows distribution contains additional components
    6 not present in the Unix krb5 distribution, most notably the
    7 MIT Kerberos Ticket Manager application.
    8 
    9 To 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 
   29 A simple way to get the necessary Unix utilities is to install Git
   30 BASH from https://gitforwindows.org and configure it to add the Unix
   31 utilities to the command-line path.  In some versions of Windows (not
   32 the most current versions), the Unix utilities can alternatively be
   33 obtained via the Utilities and SDK for UNIX-based Applications, which
   34 may be enabled as a Windows feature and then the components installed.
   35 Note that the Windows nmake will not find the SUA awk utility in the
   36 path unless it is named awk.exe; the permissions on the utility may
   37 need correcting if awk.exe is created as a copy of the original awk.
   38 
   39 Git BASH contains a version of Perl, which will work to build krb5 if
   40 the newlines in the source tree are not translated to native newlines.
   41 Strawberry Perl will work regardless of whether newlines are
   42 translated.  If both Git BASH and Strawberry Perl are installed, you
   43 may need to adjust the command line path to ensure that the preferred
   44 Perl appears first.
   45 
   46 The krb5 source tree may be obtained either directly on the Windows
   47 machine with a native git client cloning the krb5 public mirror at
   48 https://github.com/krb5/krb5.git or on a separate (Unix) machine and
   49 copied over, such as from a VM host onto a Windows VM.  If you are
   50 checking out the sources with git and are using the Git BASH Perl,
   51 make sure to set git's core.autocrlf variable to "input" or "false" to
   52 avoid translating newlines.
   53 
   54 After Visual Studio is installed, you should be able to invoke 32-bit
   55 and 64-bit command prompts via the start menu (Visual Studio 2017 ->
   56 x86 Native Tools Command Prompt and x64 Native Tools Command Prompt).
   57 At the current time, Kerberos 5 can only be built for the x64 target
   58 if the host platform is also 64-bit, because it compiles and runs
   59 programs during the build.
   60 
   61 IMPORTANT NOTE: By default, the sources are built with debug
   62 information and linked against the debug version of the Microsoft C
   63 Runtime library, which is not found on most Windows systems unless
   64 they have development tools, and requires a separate license to
   65 distribute.  To build a release version, you need to define NODEBUG
   66 either in the environment or the nmake command-line.  Debug
   67 information in the compiled binaries and libraries may be retained by
   68 defining DEBUG_SYMBOL in the environment or on the nmake command line.
   69 
   70 
   71 Building the code and installer:
   72 -------------------------------
   73 
   74 First, make sure you have sed, (g)awk, cat, and cp.
   75 You must also define KRB_INSTALL_DIR either in the environment or
   76 on the command line (for nmake install).  If you are proceeding to build
   77 the MSI installer, this directory should be a temporary staging area in or
   78 near your build tree.  The directory must exist before nmake install
   79 is run.  The 64-bit installer provides 32-bit libraries, so a 32-bit build
   80 and install must be performed before the 64-bit build.
   81 
   82 To skip building the graphical ticket manager, run "set NO_LEASH=1"
   83 before building, and do not build the installers.
   84 
   85 In 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 
   96 In a 64-bit command shell:
   97 
   98  9) set PATH=%PATH%;"%WindowsSdkVerBinPath%"\x86  # To get uicc.exe
   99 10) set KRB_INSTALL_DIR=\path\to\dir    # Where bin/include/lib lives
  100 11) cd xxx\src                          # Go to where source lives
  101 12) nmake clean                         # Clean up the 32-bit objects
  102 13) nmake [NODEBUG=1]                   # Build the sources for 64-bit
  103 14) nmake install [NODEBUG=1]           # Copy 64-bit lib/executables
  104 15) cd windows\installer\wix            # Back to the installer source
  105 16) nmake clean                         # Remove 32-bit leavings
  106 17) nmake [NODEBUG=1]                   # Build the 64-bit installer
  107 18) rename kfw.msi kfw64.msi            # And name it usefully
  108 
  109 Step 9 may be skipped if uicc is already in the command-line path (try
  110 running "uicc" to see if you get a usage message or a not-found
  111 error), or if you are not building the graphical ticket manager.
  112 
  113 Visual Studio 2013 and 2015 provide only a single command prompt.
  114 Within this prompt, use "vcvarsall.bat x86" and "vcvarsall.bat amd64"
  115 to switch to 32-bit and 64-bit mode.
  116 
  117 
  118 Running Kerberos 5 Apps:
  119 -----------------------
  120 
  121 Make sure you have a valid krb5.ini file.
  122 By 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
  125 settings for your site, but since DNS lookups are enabled for locating
  126 KDCs, many sites will not need further customization.  The file format is
  127 identical to that of a Unix krb5.conf file.
  128 
  129 
  130 krb5.ini File:
  131 -------------
  132 
  133 WARNING: Despite its name, this is not a Windows .ini file.
  134 Therefore, do not try to use any .ini tools, including the Windows API
  135 or any installer tools to manipulate this file.  Its format is subtly
  136 different from Windows .ini files!
  137 
  138 
  139 Controlling the Kerberos 5 Run-Time Environment:
  140 -----------------------------------------------
  141 
  142 The Kerberos 5 configuration file and credentials cache can be
  143 controlled with environment variables and registry settings.  The
  144 environment variable for a particular setting always takes precedence.
  145 Next in precedence comes the setting in the registry under
  146 HKEY_CURRENT_USER\Software\MIT\Kerberos5.  Then comes the registry
  147 setting under HKEY_LOCAL_MACHINE\Software\MIT\Kerberos5.  If none of
  148 those are found, a default value is used.
  149 
  150 Configuration 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 
  156 Default Credentials Cache:
  157 - Environment: KRB5CCNAME
  158 - Registry Value: ccname
  159 - Default: API:
  160 
  161 
  162 Credentials Cache:
  163 -----------------
  164 
  165 In addition to standard FILE: (disk file) and MEMORY: (in-process
  166 non-shared memory) Windows supports the API: cache type, which is a
  167 shared memory cache.  Kerberos for Windows also has access to an
  168 MSLSA: cache type, which directly accesses the Microsoft Kerberos
  169 Logon Session credentials cache.  The MSLSA: cache is available when the
  170 user logon is performed using Kerberos either to an Active Directory Domain
  171 or a non-Microsoft KDC; the ms2mit and mit2ms utilities can also be used
  172 to interact with it, though there are some limitations.
  173 
  174 A user is able to logon to Windows using the Kerberos LSA if the machine
  175 is part of a Windows Active Directory domain or if the machine has been
  176 configured to authenticate to a non-Microsoft KDC such as MIT.
  177 The instructions for configuring a Windows 2000 XP workstation to
  178 authenticate to a non-Microsoft KDC are documented in TechNet somewhere.
  179 In 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 
  200 On the MIT KDC, you must then create service principals using the "Password"
  201 assigned to the machine.  So far the minimum list of principals required appear
  202 to be for a machine named "mymachine" in the realm "EXAMPLE.COM" with a
  203 domain 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 
  210 There may very well be other services for which principals must be created depending
  211 on what services are being executed on the machine.
  212 
  213 It is very important to note that while you can successfully log into a Windows
  214 workstation by authenticating to the KDC without creating a host key; the logon
  215 session you receive will not be a Kerberos Logon Session.  There will be no Kerberos
  216 principal and no LSA cache to access.
  217 
  218 The 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 
  246 The MSLSA: credential cache relies on the ability to extract the entire
  247 Kerberos ticket including the session key from the Kerberos LSA.  In an
  248 attempt to increase security Microsoft has begun to implement a feature
  249 by which they no longer export the session keys for Ticket Getting Tickets.
  250 This has the side effect of making them useless to the MIT krb5 library
  251 when attempting to request additional service tickets.
  252 
  253 This new feature has been seen in Windows 2003 Server, Windows 2000 Server SP4,
  254 and Windows XP SP2.  We assume that it will be implemented in all future
  255 Microsoft operating systems supporting the Kerberos SSPI.  Microsoft does work
  256 closely with MIT and has provided a registry key to disable this new feature.
  257 On server platforms the key is specified as:
  258 
  259   HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters
  260     AllowTGTSessionKey = 0x01 (DWORD)
  261 
  262 On workstation platforms the key is specified as:
  263 
  264   HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos
  265     AllowTGTSessionKey = 0x01 (DWORD)
  266 
  267 The Kerberos for Windows installer automatically sets this key on installation
  268 and unsets it on uninstall, allowing the MSLSA: cache type to be used.
  269 
  270 It has been noted that the Microsoft Kerberos LSA does not provide enough
  271 information within its KERB_EXTERNAL_TICKET structure to properly construct
  272 the Client Principal simply by examining a single ticket. From the MSDN
  273 Library:
  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 
  294 Unfortunately, there is no field here which contains the domain of the client.
  295 In order for the krb5_ccache to properly report the client principal name, the
  296 client principal name is constructed by utilizing the ClientName and DomainName
  297 fields of the Initial TGT associated with the Kerberos LSA credential cache.
  298 To disable the use of the TGT info and instead simply use the "DomainName" field
  299 of the current ticket define one of the following registry keys depending on
  300 whether 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 
  308 GSSAPI Sample Client:
  309 ---------------------
  310 
  311 The GSS API Sample Client provided in this distribution is compatible with the
  312 gss-server application built on Unix/Linux systems.  This client is not compatible
  313 with the Platform SDK/Samples/Security/SSPI/GSS/ samples which Microsoft has been
  314 shipping as of January 2004.  Revised versions of these samples are available upon
  315 request to krbdev@mit.edu.
  316 
  317 More Information:
  318 ----------------
  319 
  320 For more information, please read the Kerberos 5 documentation in
  321 the doc directory of the distribution.