# Kerberos for Windows 2.6.4

## Release Notes

### 12 July 2004

### Table of Contents

- Overview
- What's New in KfW 2.6
- System Requirements
- Installation and Configuration
  - Binaries
  - Locating Kerberos Configuration Files
    - Kerberos 5
    - Kerberos 4
  - Modifying Kerberos Configuration Files
    - Kerberos 5
    - Kerberos 4
  - Using DNS Lookups for Kerberos Configuration
  - Services File
  - Ticket Cache
  - Date and Time Issues
- Command Line Options

- leash32.exe
- kinit.exe
- klist.exe
- kdestroy.exe
- aklog.exe

- Building from Sources
- Notes on the NSIS Installer Scripts
- Leashw32 API
- Registry and Environment Settings
- Integration with Microsoft Kerberos LSA
- GSS Sample Client
- Known Issues
- Release History
- To Do
- Developer Notes
  - KClient
  - Some older notes from prior releases...

## Overview

MIT Kerberos for Windows (KfW) is an integrated Kerberos release for Microsoft Windows operating systems. It includes the Kerberos v4 library, Kerberos v5 library version 1.3.2, Kerberos v5 GSS API library, Kerberos 524 library, KClient API library, Leash API library, Leash GUI credentials manager, kinit/klist/kdestroy/krb524init/aklog command-line credentials managers, and an in-memory credentials cache.

### Terminology

Kerberos v4 (also Kerberos 4 or Kerberos version 4) and Kerberos v5 (also Kerberos 5 or Kerberos version 5) refer to versions 4 and 5 of the Kerberos protocol. A protocol is a specification for how data is transmitted on a network.

Kerberos credentials and Kerberos tickets are the same thing.

## What's New in Kerberos for Windows 2.6

### 2.6.4

- Solve problem in MSLSA: ccache which would result in premature process termination on non-English versions of Windows if Kerberos credentials were not available from LSA credential manager.

- Apply automatic import restrictions from the MSLSA credentials cache to the GSSAPI acquire credentials code when necessary.

- Kerberos 5 library updated to release 1.3.4. See the Kerberos 5 README file for details of the changes in the Kerberos 5 version 1.3.4 distribution.

- Add support for the location of the AllowTGTSessionKey registry value in Windows XP SP2 to the installer

- Add support for Terminal Server compatibility flags to the installer

### 2.6.3

- Prevent Leash from flooding the KDC with TGS_REQ messages when the Windows Logon Session is authenticated using Kerberos.

### 2.6.2

- The behavior of the Leash automatic importing of credentials from the MSLSA credentials cache is now configurable. Options include never, always, and only if the MSLSA principal belongs to the default realm as specified in krb5.ini.

- Keberos Ticket Initialization options modified within the Ticket Initialization dialog may now optionally be preserved.

- A memory access error introduced in 2.6.1 has been eliminated. This problem was traced to errors in implementation of the MFC CSingleLock class.

### 2.6.1

- Kerberos 5 library updated to release 1.3.3. See the Kerberos 5 README file for details of the changes in the Kerberos 5 version 1.3.3 distribution.

- Fixes a compatibility issue with Windows 98 and ME discovered after the 2.6 release.

- Leash and aklog obtain AFS tokens via Kerberos 5 without requiring the use of a krb524 daemon.

- The Kerberos 5 command line utilities kvno.exe and kpasswd.exe are now included in the distribution.

- The Leash Change Password function once again works when passwords are expired.

### 2.6.0

- Leash has been turned into a System Tray application

- Leash implements IP address change detection which is used in conjunction with KDC Probing to determine when dialogs for obtaining tickets should be displayed to the end user

- Leash API functions no longer display dialogs to the end user on failure

- Kerberos 5 Credential Cache Name changes are now functional

- aklog support for Kerberos 5 credentials has been added and is now the default. Use the -4 switch if you wish to use aklog with Kerberos 4 credentials.

- krb5_cc api support for accessing the Microsoft Kerberos LSA cache in read-only mode. Use a ccache name of "MSLSA:".

- KClient and GSSAPI libraries will now automatically display the Leash Obtain Ticket Getting Tickets dialog box when a request for service tickets is made and no TGTs exist. This can be disabled by defining the environment variable KERBEROSLOGIN_NEVER_PROMPT.

- The Leash online help functionality has been updated. The HtmlHelp engine is now used instead of WinHelp. All content has been updated.

- A new installer based on the open source NullSoft Installation System is provided. Source is provided as part of the SDK to allow for customization.

- A new GSS Sample Application client has been added to the distribution which is compatible with the Unix gss-server sample service.

- Improvements to the Winsock Helper Library (WSHELP32.DLL) to avoid several problems related to initializing the list of DNS servers. Whenever possible the operating system versions of resolver functions are used instead of the internal versions.

### What's New in Kerberos for Windows 2.5

### 2.5.1

- The order of Kerberos 5 and Kerberos 4 tickets in the Leash credential tree are reversed

- Status Bar string formatting corrected for AFS Token lifetimes

- Automatic Ticket Renewals performed on AFS Token expiration

- Error dialogs are suppressed for when using Leash API calls for check password, kinit, and change password

- AFS Tokens are obtained via a krb524 of a Kerberos 5 AFS ticket in preference to obtaining a Kerberos 4 AFS Ticket

### 2.5.0 (includes all changes since 2.1)

- Kerberos v5 support is from MIT Kerberos v5 Release 1.3.1. In addition to bug fixes, this release of Kerberos 5 includes several important changes:

  - The public API has been more clearly defined. The krb5.h header file now marks non-public functions with KRB5_PRIVATE and deprecated functions with KRB5_DEPRECATED. You should not define these in your builds.

  - The krb5_32.dll exports have been cleaned up (most private functions are no longer exported) to try to reflect that API. However, the Kerberos 5 DLL still exports some private functions that are currently used by the GSSAPI implementation. Make sure you do not use these (check krb5.h or krb5_32.def).

  - The Kerberos 5 ccache and keytab accessors are now functions instead of macros.
  - The Kerberos 524 ticket conversion functions are now integrated into the Kerberos 5 library. A krb524.dll is provided for backward compatibility with the krb524.dll distributed by http://www.rose-hulman.edu/TSC/software/wake/documentation/compiling/krb524/
  - The library default is now to retrieve addressless tickets. This can be a problem for DCE based systems. To restore the previous behavior and enable Leash configurable control, add "noaddresses = false" to the "[libdefaults]" section of the KRB5.INI file.
  - GSS Kerberos OID constants are exported by GSSAPI32.DLL
- Leash Credential Manager improvements:

- Leash behaves nicely with missing or incomplete configuration files

- Autogeneration of missing configuration files based upon DNS records or Microsoft Windows Domain configuration. Configurable by registry setting or Leash Properties dialog.

- Importation of Microsoft Windows Domain credentials into the MIT Credentials Cache supported via Actions->Import Tickets (^I)

- Ability to manage DNS KDC Lookup setting from Kerberos Properties Dialog

- Renew Kerberos credentials without password. Actions->Renew Tickets (^R)

- KRB524 support

- used to retrieve Kerberos 4 credentials in preference to Kerberos 4 kinit
- used to retrieve Kerberos 4 credentials during ticket renewal
- used to retrieve Kerberos 4 credentials during Windows credential importation

- New Ticket Initialization and Change Password dialogs

- Addressless Kerberos 5 tickets configuration (when KRB5.INI contains [libdefaults] noaddresses = false)

- Renewable Kerberos 5 tickets configuration

- Automatic Ticket Renewal re-news/re-imports Kerberos 5 tickets and obtains new Kerberos 4 tickets via KRB524 when either Kerberos 4 or Kerberos 5 credentials are about to expire. Options->Automatic Ticket Renewal

- On startup, if the credential cache is empty and the Windows logon session is Kerberos authenticated, the Windows Kerberos credentials are imported

- New command line options:

- -ms2mit, -import, -m imports credentials from the Windows Logon Session (and exit)
- -renew, -r renews credentials (and exit)
- -destroy, -d destroys credentials (and exit)
- -autoinit, -a performs ticket initialization only if the credential cache is empty

- Expired Tickets can now be destroyed

- Prompter dialogs added to support hardware pre-authentication mechanisms

- Kerberos 4 ticket retrieval can now be disabled without deleting the KRBV4W32.DLL via the Leash Properties dialog

- Kerberos 4 and Kerberos 5 configuration file locations may now be locked

- Leash now obeys instructions for Minimize, Maximize and Normal window creation

- New Icons and Toolbar images

- Ticket Encryption Types and Addresses are displayed for Kerberos 5 tickets

- Andrew File System token retrieval (if either OpenAFS or IBM AFS® Version 3.6 are installed.)

- Leashw32 API expanded to provide access to the new Ticket Initialization and Change Passwords dialogs; and get/set/reset functions to alter Leash and Kerberos behavior
- New Leash End User documentation provided in PDF format

## System Requirements

### Operating System

KfW requires Windows 98, 98SE, ME, NT 4.0, 2000, XP, 2003 or higher.

### Microsoft Redistributable DLLs

The following versions or newer of several freely redistributable Microsoft DLLs are required depending on the compiler release used to build the distribution. The MIT distribution is built using the Microsoft Visual Studio .NET 2003 C/C++ compiler:

| Filename |  | Version |  | Description
* | mfc71.dll |  | 7.10.3077.0 |  | MSVS.NET 2003 MFCDLL Shared Library - Retail Version
* | msvcr71.dll |  | 7.10.3052.4 |  | MSVS.NET 2003 Microsoft (R) C Runtime Library
* | msvcp71.dll |  | 7.10.3077.0 |  | MSVS.NET 2003 Microsoft (R) C Runtime Library
| mfc70.dll |  | 7.00.9466.0 |  | MSVS.NET MFCDLL Shared Library - Retail Version
| msvcr70.dll |  | 7.00.9466.0 |  | MSVS.NET Microsoft (R) C Runtime Library
| msvcp70.dll |  | 7.00.9466.0 |  | MSVS.NET Microsoft (R) C Runtime Library
| mfc42.dll |  | 6.0.8665.0 |  | MSVC++ 6.0 MFCDLL Shared Library - Retail Version
| msvcrt.dll |  | 6.0.8168.0 |  | MSVC++ 6.0 Microsoft (R) C Runtime Library
| msvcp60.dll |  | 6.0.8168.0 |  | MSVC++ 6.0 Microsoft (R) C++ Runtime Library
* | psapi.dll |  | 4.0.1198.1 |  | Process Status Helper [not used in Windows 95/98/98SE/ME]

The KfW Installer will install the DLLs marked by an asterisk.

To see what Microsoft products ship with which version of these DLLs, you can use the DLL Help Database.

If you are not using the installer and you are missing some of these DLLs, you can download the Microsoft Redistributable Components component from the MIT Kerberos download site and manually install each missing DLL.

Note: `psapi.dll` is also available by itself from the Microsoft Download Center. The other DLLs can also be retrieved from the Visual Studio Service Pack 5 Merge Modules, though that is kind of difficult to do.

## Installation and Configuration

### Binaries

#### Core Binaries

| Filename |  | Description
| aklog.exe |  | command-line app to retrieve AFS tokens using Kerberos tickets
| krbv4w32.dll |  | Kerberos 4 library
| krbcc32.dll |  | Kerberos credentials cache library -- required by Kerberos 4; used by Kerberos 5 for in-memory credentials cache
| krbcc32s.exe |  | Kerberos credentials cache -- required by krbcc32.dll
| kclnt32.dll |  | KClient library -- required by some Kerberos 4 applications (such as Eudora)
| krb5_32.dll |  | Kerberos 5 library
| krb524.dll |  | Kerberos 524 compatibility library
| leash32.exe |  | Leash32 GUI Kerberos credentials manager
| leashw32.dll |  | Exports Ticket Init and Change Password dialogs as well as registry get/set/reset functions for managing Leash configurations. (required by Leash32.exe and may be used by third party applications.)
| xpprof32.dll |  | Kerberos 5 Profile Management library (required by leashw32.dll)
| comerr32.dll |  | Kerberos 5 Common Error Library (required by Kerberos 5 and Leash32.exe)
| gssapi32.dll |  | GSS API for Kerberos 5
| wshelp32.dll |  | winsock helper used by various things
| kinit.exe |  | command-line app to get Kerberos credentials
| klist.exe |  | command-line app to list Kerberos credentials
| kdestroy.exe |  | command-line app to destroy Kerberos credentials
| k524init.exe |  | command-line app to get Kerberos 4 credentials using Kerberos 5 credentials instead of a password
| ms2mit.exe |  | command-line app to transfer Microsoft Kerberos v5 domain credentials into the MIT Kerberos v5 credentials cache.

It is recommended that all binaries be installed into a single directory in the user's PATH. Make sure that you do not have other Kerberos binaries in your PATH.

### Locating Kerberos Configuration Files

The simplest configuration is to put the `krb5.ini`, `krb.con`, and `krbrealm.con` configuration files in the Windows directory (or in the same directory as the Kerberos DLLs). The NSIS installer looks for configuration files only in the Windows directory.

#### Kerberos 5

Kerberos 5 needs a single configuration file: `krb5.ini`. You can put it in the Windows directory; or you can put it in the same directory as the DLL; or you can point to an arbitrary file by setting the `KRB5_CONFIG` environment variable.

#### Kerberos 4

Kerberos 4 needs two configuration files, typically called `krb.con` and `krbrealm.con`. You can put these files in the same directory as the DLL and everything should work. You can also set KRB4_KRB.REALMS or KRB4_KRB.CONF to override each file. Or you can set KRB4_CONFIG to force Kerberos 4 to look for both files in a particular directory. If you do none of these, this is where Kerberos 4 will search:

1. %NDIR%\kerb\
2. The current directory
3. The Windows directory
4. The Windows system directory
5. The directory containing the executable file for the current task
6. The directories in the path (*)
7. The list of directories mapped in a network
8. %NDIR%\
9. %ETC%\

(*) Note: If you put the files in the DLL's directory, this part of the search is what will take you there. If you have another config file earlier in the search, that will take precedence, so be careful.

### Modifying Kerberos Configuration Files

IMPORTANT: Leash can be used to manage the Kerberos 5 and Kerberos 4 configuration files. Leash enforces a requirement that the Realm, KDC, and Realm/DNS mapping information is equivalent for both Kerberos 4 and Kerberos 5. If this is not true for your Realms, you should not use Leash to manage the configuration files. Instead use a text editor such as Notepad.

#### Kerberos 5

See the krb5.conf (MIT website)section in the Kerberos v5 System Administrator's Guide (MIT website).

#### Kerberos 4

It is anticipated that most sites using Kerberos version 4 on Windows also will have an existing UNIX Kerberos infrastructure. For that reason, the format of the `krb.con` is identical to the UNIX `krb.conf` and the format of `krbrealm.con` identical to the UNIX `krb.realms`. For many users, the easiest way to configure these files for use at their local sites will be to ftp the corresponding files from a local UNIX machine that is already properly configured.

The `krb.con` file contains configuration information describing the Kerberos realm and the Kerberos key distribution center (KDC) servers for known realms.

`krb.con` contains the name of the local realm in the first line, followed by lines indicating realm/host entries. The first token is a realm name, and the second is a hostname of a host running a KDC for that realm. The words "admin server" following the hostname indicate that the host also provides an administrative database server which is contacted when changing a user's password. For example:

    ATHENA.MIT.EDU
    ATHENA.MIT.EDU kerberos.mit.edu admin server
    ATHENA.MIT.EDU kerberos-1.mit.edu
    ATHENA.MIT.EDU kerberos-2.mit.edu
    LCS.MIT.EDU kerberos.lcs.mit.edu admin server

If this were your `krb.con` file and you wanted to change the default local realm to `CIT.CORNELL.EDU` you would edit it to look like:

    CIT.CORNELL.EDU
    CIT.CORNELL.EDU kerberos.cit.cornell.edu admin server
    ATHENA.MIT.EDU kerberos.mit.edu admin server
    ATHENA.MIT.EDU kerberos-1.mit.edu
    ATHENA.MIT.EDU kerberos-2.mit.edu
    LCS.MIT.EDU kerberos.lcs.mit.edu admin server

The `krbrealm.con` file is the host-to-Kerberos realm translation file. This provides a translation from a local hostname to the Kerberos realm name for the services provided by that host.

Each line of the translation file is in one the following forms (domain_name should be of the form `.XXX.YYY`, e.g., `.LCS.MIT.EDU`):

    	host_name kerberos_realm
    	domain_name kerberos_realm

If a hostname exactly matches the host_name field in a line of the first form, the corresponding realm is the realm of the host. If a hostname does not match any host_name in the file, but its domain exactly matches the domain_name field in a line of the second form, the corresponding realm is the realm of the host.

If no translation entry applies, the host's realm is considered to be the hostname's domain portion converted to uppercase.

### Using DNS Lookups for Kerberos Configuration

#### What is it?

DNS lookups provide Kerberos the ability to determine the Kerberos Realm that a host belongs to and to find the servers associated with a given Realm by using the Domain Name Service instead of or in addition to local configuration files.

#### When are DNS Lookups used?

DNS lookups are used in either of these two circumstances:

- No `krb.con` file is found for Kerberos 4 or no `krb5.ini` file is found for Kerberos 5.
- The `krb.con` file or `krb5.ini` file contains a command to activate DNS Lookups and the lookup cannot be answered by data found in the appropriate configuration file.

To activate DNS lookups for Kerberos 4 when the `krb.con` file is present, add the following line to the file as a realm-to-host entry (usually to the end):

>     .KERBEROS.OPTION. dns

When DNS lookups are used, the first line in the `krb.con` file (which would contain the default realm) may be left blank to indicate that the default realm should be determined by a DNS lookup.

To activate DNS lookups for Kerberos 5 when the `krb5.ini` file is present, place:

>     dns_lookup_kdc = true
>     dns_lookup_realm = true

into the `[libdefaults]` section. If a "default_realm" entry is not provided, a DNS lookup will be performed to determine the default realm.

#### What entries go into the DNS?

Host to realm lookups are performed using DNS TXT records. Example records are:

>     _kerberos.yclept.kermit.columbia.edu.  IN TXT "KRB5.COLUMBIA.EDU"
>     _kerberos.columbia.edu.                IN TXT "CC.COLUMBIA.EDU"

Realm to server lookups are performed using DNS SRV records. Example records are:

>     _kerberos._udp.KRB5.COLUMBIA.EDU.    IN SRV 0 0 88      yclept.kermit.columbia.edu
>     _kerberos._tcp.KRB5.COLUMBIA.EDU.    IN SRV 0 0 0       .
>     _krb524._udp.KRB5.COLUMBIA.EDU.      IN SRV 0 0 4444	yclept.kermit.columbia.edu
>     _kerberos-iv._udp.KRB5.COLUMBIA.EDU. IN SRV 0 0 750     yclept.kermit.columbia.edu
>     _kerberos-adm._tcp.KRB5.COLUMBIA.EDU IN SRV 0 0 749     yclept.kermit.columbia.edu
>     _kpasswd._udp.KRB5.COLUMBIA.EDU      IN SRV 0 0 464     yclept.kermit.columbia.edu

A DNS SRV record which specifies a port of "0" and a hostname of "." indicates that the requested service is not available in the requested realm.

### Services File

The Kerberos DLLs need to know what port to use to talk to the Kerberos server. Kerberos 4 now defaults to ports 750 (kerberos 750/udp kdc) and 751 (kerberos-master 751/tcp) if there are no kerberos or kerberos-master entries in the services file. Kerberos 5 also has proper defaults (port 88 with a fallback to 750) in case the services file is missing the entries for kerberos and kerberos-sec.

If your site uses non-standard ports, you will still need a services file appropriate for your site.

### Ticket Cache

The default for both Kerberos 4 and 5 is to store credentials in memory.

You can specify the name of the ticket file and the directory in which it is stored via the environment variables `KRBTKFILE` (krb4) and `KRB5CCNAME` (krb5). The krb4 credentials are always stored in memory. In memory credential caches have a prefix of "API:" in front of the name.

There are also registry settings for these locations. Playing with Leash will reveal where they are (look in HKCU\Software\MIT\Kerberos4 and Kerberos5). You can set machine-wide values by playing with these settings in HKLM.

Kerberos 5 does support using file-based tickets, but their use is not recommend, as they are potentially less secure.

### Date and Time Issues

Kerberos authentication uses time stamps as part of its protocol. When the clocks of the Kerberos server and your computer are too far out of synchronization, you cannot authenticate properly. Both the Kerberos server and the Kerberos client depend on having clocks that are synchronized within a certain margin. This margin is normally 5 minutes.

The date and time on the machine running Kerberos must be "accurately" set. If the date or time is off "too far", Kerberos authentication will not work.

You can synchronize your clock using Leash32. It allows you to set the name of the host to which you will synchronize. It saves this information in the registry (under HKCU\Software\MIT\Leash32 -- you can set machine-wide defaults in HKLM).

By default, the server that the libraries contact when synchronizing the time is `time`. The domain name has been left off on purpose. If local system administrators create a machine with a CNAME of time within the local domain the clients will contact this machine by default.

If local system administrators are opposed to doing this for some reason, you can edit the resource `LSH_TIME_HOST` in the `leashw32.dll` to the name appropriate for your local site. You can also edit the header files from the source distribution and recompile for your local site. However, this is not recommended. You can also tweak the registry setting Leash32 uses.

You can also avoid this problem by running a local, properly configured, NTP program on your machine.

## Command Line Options

### leash32

The command line options for leash32 are:

    -kinit, -i		only perform a kinit and then exit Leash
    -ms2mit, -import, -m	only perform a ms2mit import and then exit Leash
    -renew, -r		only perform a credential renewal and then exit Leash
    -destroy, -d		only perform a kdestroy and then exit Leash
    -autoinit, -a		perform a kinit if credential cache is empty

###

### kinit

    Usage: kinit [-5] [-4] [-V] [-l lifetime] [-s start_time]
            [-r renewable_life] [-f | -F | --forwardable | --noforwardable]
            [-p | -P | --proxiable | --noproxiable]
            [-A | --addresses | --noaddresses]
            [-v] [-R] [-k [-t keytab_file]]
            [-c cachename] [-S service_name] [principal]

        options:                                          valid with Kerberos:
    	-5 Kerberos 5 (available)
    	-4 Kerberos 4 (available)
    	   (Default behavior is to try Kerberos 5 and Kerberos 4)
    	-V verbose                                        Either 4 or 5
    	-l lifetime                                       Either 4 or 5
    	-s start time                                     5
    	-r renewable lifetime                             5
    	-f forwardable                                    5
    	-F not forwardable                                5
    	-p proxiable                                      5
    	-P not proxiable                                  5
    	-A do not include addresses                       5
    	-v validate                                       5
    	-R renew                                          5, or both 5 and 4
    	-k use keytab                                     5, or both 5 and 4
    	-t filename of keytab to use                      5, or both 5 and 4
    	-c Kerberos 5 cache name                          5
    	-S service                                        5, or both 5 and 4

### klist

    Usage: klist.exe [-5] [-4] [-e] [[-c] [-C] [-f] [-s] [-a [-n]]] [-k [-t] [-K]] [name]

            -5 Kerberos 5 (available)
            -4 Kerberos 4 (available)
               (Default is Kerberos 5 and Kerberos 4)
            -c specifies credentials cache
    	-C enumerates all credentials caches
            -k specifies keytab
               (Default is credentials cache)
            -e shows the encryption type
            options for credential caches:
                    -f shows credentials flags
                    -s sets exit status based on valid tgt existence
                    -a displays the address list
                            -n do not reverse-resolve
            options for keytabs:
                    -t shows keytab entry timestamps
                    -K shows keytab entry DES keys

### kdestroy

    Usage: kdestroy.exe [-5] [-4] [-q] [-c cache_name]
            -5 Kerberos 5 (available)
            -4 Kerberos 4 (available)
               (Default is Kerberos 5 and Kerberos 4)
            -q quiet mode
            -c specify name of credentials cache

### aklog

    Usage: aklog [-d] [[-cell | -c] cell [-k krb_realm]] [[-p | -path] pathname]
        [-noprdb] [-force] [-5 | -4]

        -d gives debugging information.
        krb_realm is the kerberos realm of a cell.
        pathname is the name of a directory to which you wish to authenticate.
        -noprdb means don't try to determine AFS ID.
        -5 or -4 selects whether to use Kerberos V or Kerberos IV
        No commandline arguments means authenticate to the local cell.

## Building from Sources

Building KfW is supported on Windows NT 4.0, Windows 2000, and Windows XP. While building on Windows 9x/Me might work, it is not supported.

First, make sure that you have a Microsoft Visual C++ compiler (version 6.0 or newer), a recent release of the Microsoft Platform SDK (August 2001 or higher is known to work), ActiveState Perl (build 631 is known to work), sed, gawk, cat, and rm in your PATH. You can get sed, gawk, cat, and rm from the Cygwin distribution. Also make sure that your INCLUDE path includes the Microsoft Platform SDK before the Microsoft Visual C++ include files and that perl has been installed so that .pl files are automatically executed with perl. You will also need to be using the default system shell (cmd or command, depending on whether you're running NT/2000 or 9x/Me) so that the Makefiles work properly.

Then, go into the `athena` directory and type

> `..\scripts\build.pl --softdirs`

to build everything with debug information. For a release build, run

> `..\scripts\build.pl --softdirs NODEBUG=1`

For help, do

> `..\scripts\build.pl -?`

and

> `..\scripts\build.pl --docs`
> [NOTE: does not work in 9x/Me]

If you are running 9x/Me, you will need to invoke the build.pl script using perl. For example:

> `perl ..\scripts\build.pl [args]`

If krb5 does not build properly, it is probably because sed/gawk were not in your path. To fix this, delete `athena/auth/krb5/src/Makefile`, fix your `PATH`, and try again.

To make your life easier, you might try putting the `scripts` directory in your path. (Under 9x/Me, that will not help you since you always need to invoke the script through perl.)

If you use the `build.pl` script, the targets should get copied into the `target` directory at the same level as the `athena` directory. You can go into `target\bin\i386\dbg` (replacing `i386` with the right CPU and `dbg` with `rel` if building release targets), and run the binaries. The debug symbols for the debug build also get placed there in case you need to debug.

## Notes on the NSIS Installer scripts

The Kerberos for Windows installer is built using the Nullsoft Scriptable Installation System Version 2.0. The source files for the installer script are included as part of the KfW SDK component. These include:

Edit | File Name | Description
N | kfw.nsi | Top level install script
N | kfw-fixed.nsi | script containing kfw install functions
N | utils.nsi | script containing general purpose nsis functions useful to other installers
Y | site-local.nsi | script containing site local definitions detailing how the distribution was compiled and where the source binaries are to be found
N | KfWConfigPage.ini | page layout information for the first configuration page
N | KfWConfigPage2.ini | page layout information for the second configuration page
N | licenses.rtf | Kerberos 5 and Kerberos for Windows License text
N | kfw.ico | Kerberos for Windows icon file
N | killer.cpp | Source code to executable used to terminate running programs during uninstall

To build an installer the site-local.nsi file must be modified to specify the appropriate values for the source files and type of installer you wish to build.

Name | Default Value | Description
KFW_TARGETDIR |  | path to directory containing the subdirectories (bin\i386, lib\i386, doc, inc, install) where the target files may be found
KFW_CONFIG_DIR |  | path to directory containing config files (krb5.ini, krb.con, krbrealm.con) to be bundled with installer
KFW_MAJORVERSION | 2 | Major Version number of the installed files
KFW_MINORVERSION | 6 | Minor Version number of the installed files
KFW_PATCHLEVEL | 0000 | Four digit patchlevel of the installed files
SAMPLE_CONFIG_REALM | ATHENA.MIT.EDU | Default realm specified in the bundled configuration files
HTTP_CONFIG_URL |  | Default URL for obtaining config files via HTTP
must define one of: |  |
CL_1200 |  | Indicator that MSVC 6.0 was used to build the binaries
CL_1300 |  | Indicator that MSVS .NET was used to build the binaries
CL_1310 |  | Indicator that MSVS .NET 2003 was used to build the binaries
define at most one of: |  | if neither are specified, a time stamped installer containing release versions of the runtime components.
RELEASE |  | Indicates that a release installer is being built. Installer includes release versions of the runtime components.
DEBUG |  | Indicates that a debug installer is being built. Installer includes debug versions of runtime components.
optional defines: |  |
BETA |  | A numeric beta version number
OLDHELP |  | Specifies the use of the old leash32.hlp file instead of the new leash32.chm file

To build an installer execute the following steps:

- cl.exe killer.cpp advapi32.lib
- "%PROGRAMFILES%\nsis\makensis.exe" kfw.nsi

It is worth noting that the "makensis.exe" used to build the MIT distributed installer was built from the NSIS sources with two modifications to the NSIS\Source\exehead\config.h file:

- NSIS_MAX_STRLEN is defined to be 4096 to support systems with very long PATH environment variables
- NSIS_CONFIG_LOG is defined
- NSIS_CONFIG_LOG_ODS is defined

The installer constructs the following registry keys for maintaining version and module specific information:

    Key Name:          HKEY_LOCAL_MACHINE\SOFTWARE\MIT\Kerberos
    Class Name:        <NO CLASS>
    Last Write Time:   1/15/2004 - 9:59 PM
    Value 0
      Name:            InstallDir
      Type:            REG_SZ
      Data:            C:\Program Files\MIT\Kerberos

    Value 1
      Name:            Installer Language
      Type:            REG_SZ
      Data:            1033

    Key Name:          HKEY_LOCAL_MACHINE\SOFTWARE\MIT\Kerberos\Client
    Class Name:        <NO CLASS>
    Last Write Time:   1/31/2004 - 3:47 AM

    Key Name:          HKEY_LOCAL_MACHINE\SOFTWARE\MIT\Kerberos\Client\2.6
    Class Name:        <NO CLASS>
    Last Write Time:   1/31/2004 - 3:47 AM
    Value 0
      Name:            VersionString
      Type:            REG_SZ
      Data:            2.6

    Value 1
      Name:            Title
      Type:            REG_SZ
      Data:            KfW

    Value 2
      Name:            Description
      Type:            REG_SZ
      Data:            Kerberos for Windows

    Value 3
      Name:            PathName
      Type:            REG_SZ
      Data:            C:\Program Files\MIT\Kerberos

    Value 4
      Name:            Software Type
      Type:            REG_SZ
      Data:            Authentication

    Value 5
      Name:            MajorVersion
      Type:            REG_DWORD
      Data:            0x2

    Value 6
      Name:            MinorVersion
      Type:            REG_DWORD
      Data:            0x6

    Value 7
      Name:            PatchLevel
      Type:            REG_DWORD
      Data:            0x0

    Value 8
      Name:            AllowTGTSessionKeyBackup
      Type:            REG_DWORD
      Data:            0x1

    Value 9
      Name:            AllowTGTSessionKeyBackupXP
      Type:            REG_DWORD
      Data:            0x1

    Key Name:          HKEY_LOCAL_MACHINE\SOFTWARE\MIT\Kerberos\Client\CurrentVersion
    Class Name:        <NO CLASS>
    Last Write Time:   1/31/2004 - 3:47 AM
    Value 0
      Name:            VersionString
      Type:            REG_SZ
      Data:            2.6

    Value 1
      Name:            Title
      Type:            REG_SZ
      Data:            KfW

    Value 2
      Name:            Description
      Type:            REG_SZ
      Data:            Kerberos for Windows

    Value 3
      Name:            PathName
      Type:            REG_SZ
      Data:            C:\Program Files\MIT\Kerberos

    Value 4
      Name:            Software Type
      Type:            REG_SZ
      Data:            Authentication

    Value 5
      Name:            MajorVersion
      Type:            REG_DWORD
      Data:            0x2

    Value 6
      Name:            MinorVersion
      Type:            REG_DWORD
      Data:            0x6

    Value 7
      Name:            PatchLevel
      Type:            REG_DWORD
      Data:            0x0

    Key Name:          HKEY_LOCAL_MACHINE\SOFTWARE\MIT\Kerberos\Documentation
    Class Name:        <NO CLASS>
    Last Write Time:   1/31/2004 - 3:47 AM

    Key Name:          HKEY_LOCAL_MACHINE\SOFTWARE\MIT\Kerberos\Documentation\2.6
    Class Name:        <NO CLASS>
    Last Write Time:   1/31/2004 - 3:47 AM
    Value 0
      Name:            VersionString
      Type:            REG_SZ
      Data:            2.6

    Value 1
      Name:            Title
      Type:            REG_SZ
      Data:            KfW

    Value 2
      Name:            Description
      Type:            REG_SZ
      Data:            Kerberos for Windows

    Value 3
      Name:            PathName
      Type:            REG_SZ
      Data:            C:\Program Files\MIT\Kerberos

    Value 4
      Name:            Software Type
      Type:            REG_SZ
      Data:            Authentication

    Value 5
      Name:            MajorVersion
      Type:            REG_DWORD
      Data:            0x2

    Value 6
      Name:            MinorVersion
      Type:            REG_DWORD
      Data:            0x6

    Value 7
      Name:            PatchLevel
      Type:            REG_DWORD
      Data:            0x0

    Key Name:          HKEY_LOCAL_MACHINE\SOFTWARE\MIT\Kerberos\Documentation\CurrentVersion
    Class Name:        <NO CLASS>
    Last Write Time:   1/31/2004 - 3:47 AM
    Value 0
      Name:            VersionString
      Type:            REG_SZ
      Data:            2.6

    Value 1
      Name:            Title
      Type:            REG_SZ
      Data:            KfW

    Value 2
      Name:            Description
      Type:            REG_SZ
      Data:            Kerberos for Windows

    Value 3
      Name:            PathName
      Type:            REG_SZ
      Data:            C:\Program Files\MIT\Kerberos

    Value 4
      Name:            Software Type
      Type:            REG_SZ
      Data:            Authentication

    Value 5
      Name:            MajorVersion
      Type:            REG_DWORD
      Data:            0x2

    Value 6
      Name:            MinorVersion
      Type:            REG_DWORD
      Data:            0x6

    Value 7
      Name:            PatchLevel
      Type:            REG_DWORD
      Data:            0x0

    Key Name:          HKEY_LOCAL_MACHINE\SOFTWARE\MIT\Kerberos\SDK
    Class Name:        <NO CLASS>
    Last Write Time:   1/31/2004 - 3:47 AM

    Key Name:          HKEY_LOCAL_MACHINE\SOFTWARE\MIT\Kerberos\SDK\2.6
    Class Name:        <NO CLASS>
    Last Write Time:   1/31/2004 - 3:47 AM
    Value 0
      Name:            VersionString
      Type:            REG_SZ
      Data:            2.6

    Value 1
      Name:            Title
      Type:            REG_SZ
      Data:            KfW

    Value 2
      Name:            Description
      Type:            REG_SZ
      Data:            Kerberos for Windows

    Value 3
      Name:            PathName
      Type:            REG_SZ
      Data:            C:\Program Files\MIT\Kerberos

    Value 4
      Name:            Software Type
      Type:            REG_SZ
      Data:            Authentication

    Value 5
      Name:            MajorVersion
      Type:            REG_DWORD
      Data:            0x2

    Value 6
      Name:            MinorVersion
      Type:            REG_DWORD
      Data:            0x6

    Value 7
      Name:            PatchLevel
      Type:            REG_DWORD
      Data:            0x0

    Key Name:          HKEY_LOCAL_MACHINE\SOFTWARE\MIT\Kerberos\SDK\CurrentVersion
    Class Name:        <NO CLASS>
    Last Write Time:   1/31/2004 - 3:47 AM
    Value 0
      Name:            VersionString
      Type:            REG_SZ
      Data:            2.6

    Value 1
      Name:            Title
      Type:            REG_SZ
      Data:            KfW

    Value 2
      Name:            Description
      Type:            REG_SZ
      Data:            Kerberos for Windows

    Value 3
      Name:            PathName
      Type:            REG_SZ
      Data:            C:\Program Files\MIT\Kerberos

    Value 4
      Name:            Software Type
      Type:            REG_SZ
      Data:            Authentication

    Value 5
      Name:            MajorVersion
      Type:            REG_DWORD
      Data:            0x2

    Value 6
      Name:            MinorVersion
      Type:            REG_DWORD
      Data:            0x6

    Value 7
      Name:            PatchLevel
      Type:            REG_DWORD
      Data:            0x0

## Known Issues

- The Kerberos Credentials Cache implementation does not support locking across calls. Each call is atomic, however.

- If the krbcc32s LRPC server process is ever terminated while another process is supposed to have a valid handle to it, the other process will need to grab new handles. The moral of the story is: do not kill krbcc32s if you have any such processes around (e.g., if Leash is running). In fact, you generally should never have to kill krbcc32s.

- If writing a server that uses Kerberos and might use the Kerberos Credentials Cache as opposed to the Kerberos v5 file credentials cache (`FILE:`), please read the krbcc32 Architecture documentation. (krbcc32 Architecture link works only if this is the source package.)

## Leashw32 API

The list of functions exported from Leashw32.dll which may be used by third party developers is specified below. Every effort is made to ensure that these functions will remain backward compatible in future releases. However, no effort is made to ensure that subsequent releases of Leashw32.dll will maintain consistent entry point values. The header file describing these functions is located in the source tree at pismere/athena/auth/leash/include/leashwin.h or in the SDK at inc/leash/leashwin.h.

    Leash_kinit_dlg

    Leash_kinit_dlg_ex

    Leash_changepwd_dlg

    Leash_changepwd_dlg_ex

    Leash_kinit

    Leash_kinit_ex

    Leash_kdestroy

    Leash_klist

    Leash_checkpwd

    Leash_changepwd

    Leash_import

    Leash_importable

    Leash_renew

    Leash_reset_defaults

    Leash_timesync

    Leash_get_default_lifetime

    Leash_set_default_lifetime

    Leash_reset_default_lifetim

    Leash_get_default_renew_till

    Leash_set_default_renew_till

    Leash_reset_default_renew_till

    Leash_get_default_forwardable

    Leash_set_default_forwardable

    Leash_reset_default_forwardable

    Leash_get_default_renewable

    Leash_set_default_renewable

    Leash_reset_default_renewable

    Leash_get_default_noaddresses

    Leash_set_default_noaddresses

    Leash_reset_default_noaddresses

    Leash_get_default_proxiable

    Leash_set_default_proxiable

    Leash_reset_default_proxiable

    Leash_get_default_publicip

    Leash_reset_default_publicip

    Leash_get_default_use_krb4

    Leash_set_default_use_krb4

    Leash_reset_default_use_krb4

    Leash_get_default_life_min

    Leash_set_default_life_min

    Leash_reset_default_life_min

    Leash_get_default_life_max

    Leash_set_default_life_max

    Leash_reset_default_life_max

    Leash_get_default_renew_min

    Leash_set_default_renew_min

    Leash_reset_default_renew_min

    Leash_get_default_renew_max

    Leash_set_default_renew_max

    Leash_reset_default_renew_max

    Leash_get_lock_file_locations

    Leash_set_lock_file_locations

    Leash_reset_lock_file_locations

    Leash_get_default_uppercaserealm

    Leash_set_default_uppercaserealm

    Leash_reset_default_uppercaserealm

    Leash_get_default_mslsa_import

    Leash_set_default_mslsa_import

    Leash_reset_default_mslsa_import

    Leash_get_default_preserve_kinit_settings

    Leash_set_default_preserve_kinit_settings

    Leash_reset_default_preserve_kinit_settings

    Leash_get_lsh_errno

    initialize_lsh_error_table

    lsh_com_err_proc

    Leash_initialize_krb_error_func

    Leash_initialize_kadm_error_table

    Leash_krb_err_func

    Leash_load_com_err_callback

    Leash_set_help_file

    Leash_get_help_file

## Registry and Environment Settings

### Leash GUI

#### afs token retrieval ( 0 or 1 )

       1. Use value from registry
          (HKCU\Software\MIT\Leash32\Settings,AfsStatus) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash32\Settings,AfsStatus) if present.
       3. Otherwise, use resource string if present.
       4. Otherwise, default to 1.

#### automatic generation of missing configuration files ( 0 or 1 )

       1. Use value from registry
          (HKCU\Software\MIT\Leash32\Settings,createmissingconfig) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash32\Settings,createmissingconfig) if present.
       3. Otherwise, use resource string if present.
       4. Otherwise, default to 0.

#### automatic ticket renewal ( 0 or 1 )

       1. Use value from registry
          (HKCU\Software\MIT\Leash32\Settings,AutoRenewTickets) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash32\Settings,AutoRenewTickets) if present.
       3. Otherwise, use resource string if present.
       4. Otherwise, default to 1.

#### lock configuration files location ( 0 or 1 )

       1. Use value from registry
          (HKCU\Software\MIT\Leash,lock_file_locations) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,lock_file_locations) if present.
       3. Otherwise, use resource string if present.
       4. Otherwise, default to 0.

#### automatic importation of MSLSA credentials ( 0 - never, 1 - always, or 2 - matching realms )

       1. Use value from registry
          (HKCU\Software\MIT\Leash32,MsLsaImport) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,MsLsaImport) if present.
       3. Otherwise, use resource string if present.
       4. Otherwise, default to 2.

### Leash32 DLL

#### default lifetime ( minutes )

       1. Use LIFETIME environment value if defined.
       2. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,lifetime) if present.
       3. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,lifetime) if present.
       4. Otherwise, use Kerberos 5 profile if present
       5. Otherwise, use resource string if present.
       6. Otherwise, default to 0.

#### default renew till time ( minutes )

       1. Use RENEW_TILL environment value if defined.
       2. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,renew_till) if present.
       3. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,renew_till) if present.
       4. Otherwise, use Kerberos 5 profile if present
       5. Otherwise, use resource string if present.
       6. Otherwise, default to 0.

#### default renewable tickets setting ( 0 or 1 )

       1. Use RENEWABLE environment value if defined.
       2. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,renewable) if present.
       3. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,renewable) if present.
       4. Otherwise, use Kerberos 5 profile if present
       5. Otherwise, use resource string if present.
       6. Otherwise, default to 0.

#### default forwardable tickets setting ( 0 or 1 )

       1. Use FORWARDABLE environment value if defined.
       2. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,forwardable) if present.
       3. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,forwardable) if present.
       4. Otherwise, use Kerberos 5 profile if present
       5. Otherwise, use resource string if present.
       6. Otherwise, default to 1.

#### default addressless tickets setting ( 0 or 1 )

       1. Use Kerberos 5 profile setting (or default) if TRUE.
       2. Otherwise, use NOADDRESSES environment value if defined.
       3. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,noaddresses) if present.
       4. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,noaddresses) if present.
       5. Otherwise, use resource string if present.
       6. Otherwise, default to 1.

#### default proxiable tickets setting ( 0 or 1 )

       1. Use PROXIABLE environment value if defined.
       2. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,proxiable) if present.
       3. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,proxiable) if present.
       4. Otherwise, use Kerberos 5 profile if present
       5. Otherwise, use resource string if present.
       6. Otherwise, default to 0.

#### default public ipv4 address ( unsigned long, network byte order )

       1. Use PUBLICIP environment value if defined.
       2. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,publicip) if present.
       3. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,publicip) if present.
       4. Otherwise, use resource string if present.
       5. Otherwise, default to 0.

#### request kerberos iv tickets ( 0 or 1 )

       1. Use USEKRB4 environment value if defined.
       2. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,usekrb4) if present.
       3. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,usekrb4) if present.
       4. Otherwise, use resource string if present.
       5. Otherwise, default to 1.

#### hide advanced kinit options in dialog ( 0 or 1 )

       1. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,hide_kinit_options) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,hide_kinit_options) if present.
       3. Otherwise, use resource string if present.
       4. Otherwise, default to 0.

#### minimum kinit dialog lifetime ( minutes )

       1. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,life_min) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,life_min) if present.
       3. Otherwise, use resource string if present.
       4. Otherwise, default to 5.

#### maxmimum kinit dialog lifetime ( minutes )

       1. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,life_max) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,life_max) if present.
       3. Otherwise, use resource string if present.
       4. Otherwise, default to 1440.

#### minimum kinit dialog renew till time ( minutes )

       1. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,renew_min) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,renew_min) if present.
       3. Otherwise, use resource string if present.
       4. Otherwise, default to 600.

#### maximum kinit dialog renew till ( minutes )

       1. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,renew_max) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,renew_max) if present.
       3. Otherwise, use resource string if present.
       4. Otherwise, default to 43200.

#### upper case realm:

       1. Use value from registry
          (HKCU\Software\MIT\Leash32\Settings,uppercaserealm) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash32\Settings,uppercaserealm) if present.
       3. Otherwise, use resource string if present.
       4. Otherwise, default to 1.

#### timesync host:

       1. Use TIMEHOST environment value if defined.
       2. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash32\Settings,timehost) if present.
       3. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash32\Settings,timehost) if present.
       4. Otherwise, use resource string if present.
       5. Otherwise, default to #defined value "time".

#### Preserve ticket initialization dialog options:

       1. Otherwise, use value from registry
          (HKCU\Software\MIT\Leash,preserve_kinit_options) if present.
       2. Otherwise, use value from registry
          (HKLM\Software\MIT\Leash,preserve_kinit_options) if present.
       4. Otherwise, use resource string if present.
       5. Otherwise, default to 0.

### Kerberos 4:

#### A. location of krbrealm & krbconf:

       1. First, check for environment overrides:
          a. Use %KRB4_KRB.REALMS% as full filename for realms file if defined.
          a. Use %KRB4_KRB.CONF% as full filename for config file if defined.
          b. Otherwise, look for krbrealm.con and krb.con in dir %KRB4_CONFIG%.
       2. If nothing defined so far, look in registry:
          a. HKCU\Software\MIT\Kerberos4,krb.realms for realms full pathname.
          a. HKCU\Software\MIT\Kerberos4,krb.conf for config full pathname.
          b. HKCU\Software\MIT\Kerberos4,config as dir for both files.
          c. HKLM\Software\MIT\Kerberos4,krb.realms for realms full pathname .
          c. HKLM\Software\MIT\Kerberos4,krb.conf for config full pathname.
          d. HKLM\Software\MIT\Kerberos4,configdir as dir for both files.
       3. If any of the above are set, use it even if the files are not there.
          If none of them are set, use the old krb4 search.

#### B. ticket file

       1. %KRBTKFILE% if defined
       2. Registry setting, if setting is present
          (HKCU\MIT\Kerberos4,ticketfile)
       3. Registry setting, if setting is present
          (HKLM\MIT\Kerberos4,ticketfile)
       4. Otherwise, "API:krb4cc".
      (
       If a file-based cache is ever supported for Kerberos 4, code should do this:
       4. %TEMP%\ticket.krb, if var defined and dir exists
       5. %TMP%\ticket.krb, if var defined and dir exists
       6. c:\temp\ticket.krb if c:\temp exists
       7. c:\tmp\ticket.krb if c:\tmp exists
       8. GetWindowsDirectory()\ticket.krb as a last-ditch default?  It's
          either that or c:\ticket.krb!
       )

### Kerberos 5:

#### A. location of krb5.ini:

       1. %KRB5_CONFIG% if defined
       2. (HKCU\Software\MIT\kerberos5,config) if defined
       3. (HKCU\Software\MIT\kerberos5,config) if defined
       4. Otherwise, use GetWindowsDirectory()\krb5.ini

#### B. Default credentials cache name

       1. %KRB5CCNAME% if defined
       2. (HKCU\Software\MIT\kerberos5,ccname) if defined
       3. (HKLM\Software\MIT\kerberos5,ccname) if defined
       4. If RegKRB5CCNAME is set under [Files] in kerberos.ini,
          look at that path in the registry (code already in krb5 for compat
          with Gradient DCE installations, I believe).
       5. Otherwise, if using CCAPI, default to "API:krb5cc".
                     if no CCAPI, use "FILE:" with:
          a. %TEMP%\krb5cc, if var defined and dir exists
          b. %TMP%\krb5cc, if var defined and dir exists
          c. c:\temp\krb5cc if c:\temp exists
          d. c:\tmp\krb5cc if c:\tmp exists
          e. GetWindowsDirectory()\krb5cc as a last-ditch default?
             it's either that or c:\krb5cc!

#### C. MSLSA: credential cache client principal identity generation

       1. (HKCU\Software\MIT\Kerberos5,PreserveInitialTicketIdentity) if defined
       2. (HKLM\Software\MIT\Kerberos5,PreserveInitialTicketIdentity) if defined
       3. Default is 1.

## Integration with Microsoft Kerberos LSA

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.

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
3. Add Realms and associated KDCs with: KSETUP /AddKdc <realm> [<kdcname>]. If you leave off the <kdcname> DNS SRV records will be used.
4. Specify the password change service host for the realm with: KSETUP /AddKpasswd <realm> <Kpwdhost>
5. Assign the realm of the local machine with: KSETUP /SetRealm <realm> where realm must be all upper case.
6. Assign the local machine's password with: KSETUP /SetComputerPassword <Password>
7. Specify the capabilities of the Realm KDC with: KSETUP /SetRealmFlags <realm> <flag> [<flag> ...] where flags may be None, SendAddress, TcpSupported, Delegate, or NcSupported,
8. Map principal names to local accounts with: KSETUP /MapUser <principal> <account>

On the MIT KDC, you must then create service principals using the "Password"
assigned to the machine. So far the minimum list of principals required appear
to be for a machine named "mymachine" in the realm "EXAMPLE.COM" with a
domain name of "example.com":

- host/mymachine@EXAMPLE.COM
- host/mymachine.example.com@EXAMPLE.COM
- cifs/mymachine@EXAMPLE.COM
- cifs/mymachine.example.com@EXAMPLE.COM

There may very well be other services for which principals must be created depending on what services are being executed on the machine.

It is very important to note that while you can successfully log into a Windows workstation by authenticating to the KDC without creating a host key; the logon session you receive will not be a Kerberos Logon Session. There will be no Kerberos principal and no LSA cache to access.

The result of a real KSETUP configuration looks like this:

       [C:\4\4NT]ksetup

       default realm = KRB5.COLUMBIA.EDU (external)

       ATHENA.MIT.EDU:

               kdc = kerberos.mit.edu

               kdc = kerberos-1.mit.edu

               kdc = kerberos-2.mit.edu

               kdc = kerberos-3.mit.edu

               Realm Flags = 0x0 none

       CC.COLUMBIA.EDU:

               kdc = kerberos.cc.columbia.edu

               Realm Flags = 0x0 none

       GRAND.CENTRAL.ORG:

               kdc = penn.central.org

               kdc = grand-opening.mit.edu

               Realm Flags = 0x0 none

       KRB5.COLUMBIA.EDU:

               kdc = yclept.kermit.columbia.edu

               Realm Flags = 0x0 none

       OPENAFS.ORG:

               kdc = virtue.openafs.org

               Realm Flags = 0x0 none

       Mapping jaltman@KRB5.COLUMBIA.EDU to jaltman.

       Mapping jaltman@CC.COLUMBIA.EDU to jaltman.

       Mapping jaltman@ATHENA.MIT.EDU to jaltman.

       Mapping all users (*) to a local account by the same name (*).

The MSLSA: credential cache relies on the ability to extract the entire Kerberos ticket including the session key from the Kerberos LSA. In an attempt to increase security Microsoft has begun to implement a feature by which they no longer export the session keys for Ticket Getting Tickets. This has the side effect of making them useless to the MIT krb5 library when attempting to request additional service tickets.

This new feature has been seen in Windows 2003 Server, Windows 2000 Server SP4, and Windows XP SP2. We assume that it will be implemented in all future Microsoft operating systems supporting the Kerberos SSPI. Microsoft does work closely with MIT and has provided a registry key to disable this new feature.

      HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters

        AllowTGTSessionKey = 0x01 (DWORD)

On Windows XP SP2 the key is specified as

      HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos

        AllowTGTSessionKey = 0x01 (DWORD)

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 Library:

ClientName
KERB_EXTERNAL_NAME structure that contains the client name in the ticket.
This name is relative to the current domain.
DomainName
UNICODE_STRING that contains the name of the domain that corresponds to
the ServiceName member. This is the domain that issued the ticket.
TargetDomainName
UNICODE_STRING that contains the name of the domain in which the ticket is
valid. For an interdomain ticket, this is the destination domain.
AltTargetDomainName
UNICODE_STRING that contains a synonym for the destination domain. Every
domain has two names: a DNS name and a NetBIOS name. If the name returned
in the ticket is different from the name used to request the ticket (the
Kerberos Key Distribution Center (KDC) may do name mapping), this string
contains the original name.

Unfortunately, there is no field here which contains the domain of the client. In order for the krb5_ccache to properly report the client principal name, the client principal name is constructed by utilizing the ClientName and DomainName fields of the Initial TGT associated with the Kerberos LSA credential cache. To disable the use of the TGT info and instead simply use the "DomainName" field of the current ticket define one of the following registry keys depending on whether the change should be system global or just for the current user.

       HKLM\Software\MIT\Kerberos5\

          PreserveInitialTicketIdentity = 0x0 (DWORD)

       HKCU\Software\MIT\Kerberos5\

          PreserveInitialTicketIdentity = 0x0 (DWORD)

As of KFW 2.6.4 it may be possible sometime in the future for the correct client realm to be obtained from the LSA credential cache contents. However, it will require a fix from Microsoft which at the present time is not available.

## GSSAPI Sample Client (gss.exe):

The GSS API Sample Client provided in this distribution is compatible with the gss-server application built on Unix/Linux systems. This client is not compatible with the Platform SDK/Samples/Security/SSPI/GSS/ samples which Microsoft has been shipping as of January 2004. Revised versions of these samples are available upon request to krbdev@mit.edu. Microsoft is committed to distribute revised samples which are compatible with the MIT distributed tools in a future SDK and via MSDN.

The following configuration options may be set for testing GSSAPI connections with a compatible server:

- Hostname The fully qualified domain name of the host on which the GSS Sample Server is running. The previous ten hostnames used will be preserved between invocations.
- Port The port number on the host at which the GSS Sample Server is listening. A value of 0 means use the default or port 4444.
- GSS Service Name This is the GSS formatted name of the service. This is not a Kerberos 5 principal. The format is service-name@fqdn which will be converted to the Kerberos 5 principal service-name/fqdn@REALM where REALM is derived from the fully qualified domain name by use of the domain to REALM mapping table in the KRB5.INI file. The previous ten GSS Service Names will be preserved between invocations.
- Test Message A string of up to 256 characters in length which will be used as a test message to send to the GSS Sample Server. The previous ten Test Messages will be preserved between invocations.
- CCache Name The name of the Kerberos 5 Credentials Cache which contains the client principal's credentials for use with this GSS session. A blank entry means to use the default credential cache as specified by the KRB5CCNAME environment variable or the registry. The drop down list is populated with the names of the existing Kerberos 5 credential caches. To use a new credential cache which does not already exist, simply enter the name in the text field.
- Mechanism (OID) An Object Identifier is used to specify which GSS Mechanism should be used when negotiating the connection. In all cases it should not be necessary for an OID to be specified or even known by the application developer. This field is therefore only to be used by developers of gssapi implementations.
- Verbose Output Generate lots of messages into the output window. Unchecking this option will significantly reduce the amount of information output.
- Delegation Checking this box will cause the GSS API to delegate (or in Kerberos speak, forward) its user credentials (a TGT) to the GSS Sample Server. You must have acquired forwardable TGTs for this to work. (default is off)
- Mutual This option specifies whether or not mutual authentication will be requested. (default is on)
- Replay This option specifies whether or not replay detection will be requested. (default is on)
- Sequence This option specifies whether or not message sequencing will be requested. (default is off)
- Version 1 This option is for use only with very old versions of the MIT Kerberos 5 GSS Sample Server. Certainly anything post the Krb5 1.2 release does not use Version 1 protocol.
- No Auth Do not negotiate any form of authentication. Just send the test message. Without authentication GSS Wrap, GSS Encrypt, and GSS Mic operations are not available.
- No Wrap Do not perform GSS Wrap operations on the test messages.
- No Encrypt Do not preform GSS Encrypt operations on the test messages.
- No Mic Do not perform GSS Mic operations on the test messages.
- Call Count How many times should a connection to the GSS Server be established?
- Message Count For each connection, how many copies of the test message should be sent?

The Output window is a read-only text edit field which will allow text to be selected and copied to the clipboard with Ctrl-C.
Press the Test button to begin a test and the Exit button to quit the application.

## Release History

In general, the latest release of KfW is recommended. However, it may be useful (and entertaining) to understand the history of KfW by looking at its release history.

### KfW 2.5

- Kerberos v5 support from MIT Kerberos v5 Release 1.3.1
- k524init.exe and krb524.dll added to the Standard distribution
- Significant enhancements to Leash GUI application functionality
- Leashw32 API enhanced
- Numerous new registry settings are supported
- Leash End user documentation provided in PDF format
- Last release to support Windows 95

### KfW 2.2

- Never officially released beyond Beta form.
- Kerberos v5 support from MIT Kerberos v5 Release 1.2.5 Beta 1.

### KfW 2.1.2

- Kerberos v5 support is from MIT Kerberos v5 Release 1.2.3. This release of Kerberos v5 includes the ms2mit program to transfer a user's Microsoft Windows domain Kerberos credentials into the MIT Kerberos 5 credentials cache.

- ms2mit was removed from the Extra Binaries package since it is now part of the included MIT Kerberos v5 component.

- The Microsoft Redistributable Components package no longer includes the Winsock 2 Update for Windows 95. A pointer to download it from Microsoft is now included.

- The release notes have been significantly revamped.

### KfW 2.1.1

- Kerberos v5 support is from MIT Kerberos v5 Release 1.2.2.

- KfW now works on Windows XP. (The RPC endpoint names used by the credentials cache had to be shortened for XP.)

### KfW 2.1

- "Kerberos for Win32" is now "Kerberos for Windows", or "KfW" for short.

- Kerberos v4 and v5 now build with DNS support by default.

- Kerberos v5 support is from MIT Kerberos v5 Release 1.2.1.

- Various buffer overflow vulnerabilities in Kerberos 4 have been fixed.

- The in-memory Kerberos Credentials Cache implementation is brand new. Fleavius is now obsolete. In-memory credentials cache is now implemented via a LRPC (local remote procedure call) mechanism. The tickets live in the krbcc32s process (which is automatically started). On Windows NT/2000, There is at most one such process per Windows login session.

  Each Windows NT/2000 login session can access only its own credentials cache. Even Windows NT/2000 security impersonation will not allow a process to access the cache of the user the process is impersonating. This is by design.

  This implementation has a much smaller memory footprint and is far more robust than the fleavius implementation. It can support a very large number of caches and credentials. The only downside to the LRPC implementation is that it is currently about 35% slower than the fleavius implementation.

  For more information, read the krbcc32 Architecture and krbcc32 Implementation documentation at `athena/auth/krbcc/doc/architecture.txt` and `athena/auth/krbcc/doc/implementation.txt`. (krbcc32 documentation links work only if this is the source package.)

### Pre-KfW Era

Before there was KfW, MIT had other Kerberos releases for Windows and even for DOS (gasp!). Read on if you dare...

#### Kerberos for Microsoft Operating Systems Release 2.0

This was a version of KfW before it was called KfW. It had an in-memory credentials cache (called fleavius) that had many problems, including large memory footprint, a single per-machine shared cache (even on NT).

#### A Long, Long Time Ago...

Once upon a time, 16-bit Windows was supported. There was even DOS support at one point. As far as MIT Kerberos is concerned, those days are best forgotten.

## To Do

- Improve the documentation.

- Replace krbv4w32.dll with the krb4_32.dll compatibility library provided by the Kerberos v5 distribution

- The tf_close() in tf_save_cred() is puzzling. Figure out what the spec is supposed to be there (if there is supposed to be one at all) and document the heck out of it. :)

- Make Kerberos 4 and 5 thread-safe.

- Use krb5's com_err instead of the current krb4 mess. Make sure all logging is funneled through one place and provide a way to control where that goes.

## Developer Notes

### KClient

- As of KfW 2.2, KClient will try to get tickets for foreign principals if you pass in a service with a non-local realm. It will use the service's realm instead of the default local realm.
- KClient now looks in the ticket file for the realm info before looking for the local default realm.

Below is Jeffrey Altman's explanation of the problem. The patch he submitted for the first 2 items in his 3-item solution below has been put in.

> The design of the KClient interface is so simplified that applications cannot easily get access to necessary information. This has resulted in the need for the Kerberos configuration page in Eudora which includes fields for:

>       Realm:          CC.COLUMBIA.EDU
>       Service name:   pop
>       Service format: %1.%4@%3

> The specification of a Realm here without a "Principal name" is interesting.

> Some information on my system. The local realm is KRB5.COLUMBIA.EDU and the POP server is pop.cc.columbia.edu which is in realm CC.COLUMBIA.EDU. With a ticket manager I retrieve a TGT for CC.COLUMBIA.EDU. Kstatus.exe reports that I am authenticated. Kstatus uses the kclnt32.dll interface just as Eudora does. However, when I ask Eudora to check my mail an interesting thing happens:

> GetTicketForService() is called which results in a dialog being displayed

>         Please enter your Network ID and password.

>         Network ID: jaltman
>         Password:

> So I enter my password for CC.COLUMBIA.EDU and am told sorry but the password is incorrect.

> What happened here?

> First, Eudora does not include a field for the principal name to go along with the realm. So it does not call SetUserName() which should have been set to

>       jaltman@CC.COLUMBIA.EDU

> to match the realm specified in Eudora for the POP host. Eudora needs the realm so it can construct the service ticket name

>       pop.mailhub@CC.COLUMBIA.EDU

> but without setting the username it has no mechanism to report the desired realm to kclnt32.dll.

> GetTicketForService() calls an internal function to verify the TGT. But because no realm has been set and data is not shared between process boundaries this instance of kclnt32.dll has no idea that the ticket manager realm is CC.COLUMBIA.EDU. Instead of attempting to load the Ticket File Realm it calls krb_get_lrealm(). So it tries to verify a TGT

>       krbtgt.KRB5.COLUMBIA.EDU@KRB5.COLUMBIA.EDU

> which does not exist. So it destroys the existing tickets and then attempts to get a new TGT for

>       jaltman

> in the default realm which again is KRB5.COLUMBIA.EDU. But of course kclnt32.dll does not display the realm in the dialog box so the user has no idea that kclnt32.dll is confused.

> In order to correct this situation the following needs to be done to kclnt32.dll:

> 1. all calls to krb_get_lrealm() should be preceded by an attempt to retrieve the realm from the ticket file with krb_get_tf_realm(). Only if krb_get_tf_realm() fails should krb_get_lream() be called.
> 2. if a realm is specified in the GetTicketForService() request that realm should be used for the verification of the TGT.
> 3. the dialog box displayed by UserInfo() should append the realm to the szNetID (if it is not already part of the string) when setting the default value for the box. This will indicate to the user which realm s/he is being authenticated against.

> Then the author's of Eudora should add a principal name to the configuration for Kerberos and call SetUserName() to set the principal and realm to the values needed to authenticate against the POP server.

### Some older notes from prior releases...

1. Modification of the Kerberos 4 credential cache:

   We encountered a problem at MIT that we felt needed to be addressed even though it broke some backwards compatibility. We found that if someone used a Kerberized application spanning multiple PPP sessions a Kerberos error would be generated and few applications would catch this error and try to get new tickets instead. E.g. Suppose a user starts a PPP connection and then starts Eudora, fetching mail. The user then decides to close down the PPP connection while they read their mail and compose responses. Next they initiate a new PPP connection and incorporate mail again. Note that the user never exited Eudora. Instead of prompting the user for their name and password Eudora will generate and error message. The only way for the user to recover the functionality would be to use Leash, Kview, or kdestroy to destroy their old tickets so that Eudora would get new tickets.

   This happened because many ISPs hand out a new IP address to a user each time that user reconnects to the system. Also a Kerberos ticket includes the machines local IP address in an encrypted form this is used by most severs to insure that the ticket has not been copied to another users machine.

   Since the local IP address is stored in the ticket it seems that it should be easy to compare this data to the machine's local IP address at the same time that an application is checking to see if the ticket has expired. Unfortunately the IP address in the ticket is encrypted in the server's session key and so is inaccessible to the local machine.

   Instead we borrowed an idea from Kerberos version 5 and decided to store the local IP address, unencrypted, in the credential which is cached in the local cache. Within the KClient function IsCredExpired() or the krbv4wXX.dll function kchktkt we verify that the ticket has not expired and that the local IP address matches the IP address stored in the ticket.

   This implies that machines with multiple copies of kclnt32.dll or krbv4w32.dll, of different versions, may encounter unexpected errors when using Kerberized applications. The normal error message generated will be BAD_TKT_FILE_FORMAT or NO_TKT_FILE.

   Users of applications that use other vendors Kerberos implementations may also be affected. E.g. some software from FTP, Inc.

2. Add a new function to the KClient DLL. This function is SendTicketsForService(). It is basically a send_auth() type function. Before everyone complains please read the following explanation.

   Qualcomm has been working with Platinum on a 32-bit KClient which would supports both Kerberos v4 and v5. From what I have heard this is a commercial implementation. It ignores GSS or other abstraction layers above the Kerberos layer that application developers should write to. It keeps its ticket cache in the DLL, as such it will not share the ticket cache with other Kerberos implementations that may reside on the user's system.

   Platinum and Qualcomm decide to add a new API call to the KClient interface. Eudora uses this new function if it finds a KCLNT32.DLL. In this case it does not use the thunking application KERB16.

   We have duplicated this function in our release of KCLNT32 so that Eudora will not GPF. Please DO NOT WRITE APPLICATIONS TO THIS FUNCTION.

3. We stole an idea from Cornell. If the clock is out of synch when we are trying to obtain a ticket we synchronize the clock and try again. We inform the user if this occurred.

4. Fixed up some problems relating to DLL initialization. WSAStartup() will be called if necessary by a few functions. This was needed to handle some differences in DLL initialization under Win32 when multiple applications were using the DLL at the same time. Also fixed up some initialization of the com_err functions due to similar issues.

5. Added two new functions to leashw32.dll. The first is Leash_set_help_file(char*szHelpFile) which allows an application developer to specify which help file to use from the dialog box presented when using the Leash_kinit() function. If the argument is NULL the function will check the environment variable KERB_HELP. If this is not set the hard coded value of kerberos.hlp will be used. The other function is Leash_get_help_file() which allows an application developer to determine the name of the help file being used. These are defined in lshfunc.c.

6. Fix the send_auth so that we do not fail on a null realm. Also detects when an invalid socket descriptor has been passed. (Special thanks to Eudora 3.0 for providing a test case.)