Kerberos for Windows 3.2.1

Release Notes

15 August 2007

Table of Contents

• Overview
• What's New in KfW 3.2.1
• 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

• netidmgr.exe
• kinit.exe
• klist.exe
• kdestroy.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

• 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.6.2, Kerberos v5 GSS API library, Kerberos 524 library, KClient API library, Leash API library, Network Identity Manager, kinit/klist/kdestroy/krb524init/ms2mit/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 3.2.1

• Network Identity Manager Application

• The display of the logo watermark in the lower right corner of the main window can be controlled with a registry entry.
• The default identity background color has been removed.
• The Basic view updates to reflect deleted and modified identities.

• Kerberos v5 Library Improvements
  • Based on MIT release krb5-1.6.2.

What's New in Kerberos for Windows 3.2

• Network Identity Manager Application

• A simplified basic mode has been added to the “obtain new credentials dialog”.   The basic mode replaces the credential browser with a button that can be used to access the advanced configuration functions.   This advanced mode provides the credential browser and a tabbed view of the configuration dialogs for each of the available credential providers.
• A new command-line option to netidmgr.exe is available to shutdown a running instance of Network Identity Manager.  Specify “-x” or “—exit” to force the existing instance to terminate.
• The use of ellipsis on menu items now follows the Windows Style Guide.  Ellipsis is only used when additional information is required from the user before carrying out the designated action.  If displaying a dialog is the action, no ellipsis is used.
• Improved handling of window focus when opening and closing modal dialogs.
• Reduce the number of alerts presented to the user by combining duplicates into a single alert.
• Do not generate alerts if there is nothing that the user can do to correct the situation.  Alerts that are displayed provide actions the user can take if desired.
• Renew and Destroy menus provide “All” and “Individual identity names” as choices.
• The Renew and Destroy toolbar buttons provide dropdown menus permitting the action to be applied to either “All” or one specific identity.
• The "default" action of left clicking the notification icon is now configurable.  The default configuration is "open/close NIM window".  The alternate is to open the new credentials dialog.  This can be specified by the user on the General Options page.
• The alerter window can now display multiple alerts simultaneously.
• Ensure that the NIM window is displayed on an active desktop.  If not, move it to the primary desktop and center it.
• New Basic mode display that shows only the state of the identity and its expiration time.  Use F7 or View->Advanced to switch to the previous display that is configurable by the user to show details about each credential.
• New Color Scheme derived from current Windows Desktop Color Scheme.
• Improved display updating algorithms reduce flicker
• The proper icon sizes are now used in the information bubble and the status bar.
• Plug-in Help can now be added to the Help menu
• A Taskbar button is visible when the Application Window or Dialog is created.

• Network Identity Manager Kerberos v5 Support

• Do not show cached prompts to user if they have expired
• Correct the possibility that a krb5_ccache handle might be freed twice.
• Import settings from Kerberos Profile if there are no equivalent defaults specified in the registry.  Support per-realm settings.
• An identity that matches the MSLSA will not renew its credentials from the MSLSA if the user obtained the credentials from elsewhere.
• When importing an identity from the MSLSA that has never been seen before, create an entry in the identity database.
• Do not attempt to renew non-renewable identities
• Permit an identity to be configured as the default identity even if it doesn't have any credentials.

• Kerberos v5 Library Improvements

• Based on MIT release 1.6.1.
• On Vista MSLSA: krb5_ccache can be used to store tickets including TGTs for alternative principals to the LSA credential cache
• On Vista a more efficient interface for enumerating the contents of the LSA credential cache is available.
• Vista support is only built if the Vista SDK version of NTSecAPI.H is used.
• On Vista, if a process is UAC limited, the MSLSA will report that no tickets are present in the cache rather than return tickets with invalid session keys.
• get_os_ccname() uses GetEnvironmentVariable() instead of getenv() to read the KRB5CCNAME environment variable.  This allows the      correct default credential cache name to be returned by krb5_cc_default_name().   This works around a problem where a gssapi application would trigger an Obtain New Credentials prompt from NIM only to have it obtain the wrong credential cache.

• Winsock Helper Library Improvements

• DNS queries that terminate with a dot would not properly match the hostnames listed within the DNS response preventing a successful return.   This resulted in "kinit -4" failing to find the KDCs.

• Integrated Logon Improvements

• Remove the reliance on the Windows Logon Event handler and replace it with a LogonScript that executes kfwlogon.dll via a call to rundll32.exe.  This change permits the integrated logon functionality to work on all supported platforms: Windows 2000 to Windows Vista.
• Disable the use of integrated logon if the Network Provider is called as a result of a non-interactive logon.  The non-interactive logon does not process the specified LogonScript.  As a result, the intermediate credential cache file would not be processed nor cleaned up.
• Obtained credentials are stored into an API credential cache whose name is API:<principal>
• Add a debugging mode which when activated logs to the Windows Application Event Log.  
  [HKLM\System\CurrentControlSet\Services\MIT Kerberos\NetworkProvider] 
  DWORD "Debug"

• Leash32 Library Changes

• Modify the leash functions to use krb5_string_to_deltat() to parse ticket_lifetime and renew_lifetime from the profile.  Previously the leash functions expected those fields to be integer representation of minutes without the use of any units.  This change is for consistency with KFM and the rest of the krb5 library.
• Modify the private functions acquire_tkt_for_princ() and acquire_tkt_no_princ() that are called from gssapi32.dll so that they will work on Windows Vista and so that the MSLSA: principal is only imported if it matches the default identity and no credentials for that identity are present.
• Remove all AFS functionality.

---

System Requirements

Operating System

Kerberos for Windows 3.2 is designed for 32-bit versions of Windows 2000, XP, 2003, 2003 R2, Vista and WOW64 environments.  There is no native 64-bit process support at the current time.

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 SP1 C/C++ compiler:

	Filename	Version	Description
*	mfc71.dll	7.10.3077.0	MSVS.NET 2003 MFCDLL Shared Library - Retail Version
*	msvcr71.dll	7.10.3031.4	MSVS.NET 2003 Microsoft (R) C Runtime Library
*	msvcp71.dll	7.10.3077.0	MSVS.NET 2003 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.

---

Installation and Configuration

Binaries

Core Binaries

Filename	Description
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 (deprecated)
krb5_32.dll	Kerberos 5 library
krb524.dll	Kerberos 524 compatibility library
leashw32.dll	Exports Ticket Init and Change Password dialogs as well as registry get/set/reset functions for managing Leash configurations.  (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.
mit2ms.exe	command-line app to transfer MIT Kerberos v5 credentials cache contents to the Microsoft Kerberos LSA credentials cache.  This application can be used on Microsoft Vista.
kvno.exe	command-line app used to obtain one or more service tickets and report the associated key version numbers.  This tool is useful for testing the ability to obtain a service ticket via a TGT in an existing ccache, with a keytab file, or when restricted to a specific enc-type.
kcpytkt.exe	command-line app used to copy a specific ticket between credential caches.
kdeltkt.exe	command-line app used to delete a specific ticket from a credential cache.

Network Identity Manager Binaries

netidmgr.exe	Network Identity Manager main executable.
krb4cred.dll	Provides information to Windows about which versions of libraries should be associated with netidmgr.exe.
krb4cred_en_us.dll	Kerberos 4 credentials provider plugin.
krb5cred.dll	English (US) language resources for the Keberos 4 credentials provider.
krb5cred_en_us.dll	Kerberos 5 credentials provider and identity provider plugin.
nidmgr32.dll	English (US) language resources for the Kerberos 5 credentials provider.

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.  The default location is “%ProgramFiles%\MIT\Kerberos\bin”.

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 and WIX installers search 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: The Network Identity Manager can be used to manage the Kerberos 5 and Kerberos 4 configuration files. NetIDMgr 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 NetIDMgr 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

netidmgr

The command line options for netidmgr are:

--kinit, -i               only perform a kinit and then exit
--ms2mit, -import, -m     only perform a ms2mit import and then exit
--renew, -r               only perform a credential renewal and then exit
--destroy, -d             only perform a kdestroy and then exit
--autoinit, -a            perform a kinit if credential cache is empty
--exit, -x                shutdown any running instance of netidmgr

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)
   -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)
        -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

---

Building from Sources

Building KfW is supported on Windows 2000, Windows XP, Windows 2003 and Windows Vista.

First, make sure that you have a Microsoft Visual .NET 2003 C++ compiler, a recent release of the Microsoft Platform SDK (XP SP2 SDK should be used if Windows 2000 support is desired, the NTSecAPI.H file from the Vista SDK must be used in place of the XP SP2 SDK version if Vista MSLSA ccache extensions are to be supported), ActiveState Perl (build 820 is known to work), doxygen, 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.exe) so that the Makefiles work properly.

Microsoft Visual Studio 2005 cannot be used to compile the KfW CCAPI implementation.  In order to compile KfW with VS2005, the “krbcc” directory must be removed from the pismire/athena/auth/Makefile.dir file.  When built without CCAPI, only the MSLSA: and FILE: credential cache types will be available for use.

Note that all KFW installers contain debugging symbols as an optional component.  Rebuilding from sources is not required in order to debug KFW as packaged by MIT.

A script to build, sign and package all the KfW distribution components is provided.  To use it:

• Unzip the KfW source zip

• cd to kfw-version/src/athena/auth/krb5/src/windows/build

• Make sure the environment is set up as specified in bkw-automation.html

• Run "bkw.pl /config bkwconfig.xml" 

See the usage (bkw.pl /?) and krb5/windows/build/bkw-automation.html for more details.

---

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	3	Major Version number of the installed files
KFW_MINORVERSION	2	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
CL_1400		Indicator that MSVS 2005 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

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 three 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\3.2.1
Class Name:        <NO CLASS>
Last Write Time:   1/31/2004 - 3:47 AM
Value 0
  Name:            VersionString
  Type:            REG_SZ
  Data:            3.2.1
 
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:            3.2.1
 
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:            0x3
 
Value 6
  Name:            MinorVersion
  Type:            REG_DWORD
  Data:            0x0
 
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\3.2.1
Class Name:        <NO CLASS>
Last Write Time:   1/31/2004 - 3:47 AM
Value 0
  Name:            VersionString
  Type:            REG_SZ
  Data:            3.2.1
 
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:            0x3
 
Value 6
  Name:            MinorVersion
  Type:            REG_DWORD
  Data:            0x0
 
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:            3.2.1
 
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:            0x3
 
Value 6
  Name:            MinorVersion
  Type:            REG_DWORD
  Data:            0x1
 
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\3.2.1
Class Name:        <NO CLASS>
Last Write Time:   1/31/2004 - 3:47 AM
Value 0
  Name:            VersionString
  Type:            REG_SZ
  Data:            3.2.1
 
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:            0x3
 
Value 6
  Name:            MinorVersion
  Type:            REG_DWORD
  Data:            0x1
 
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:            3.2.1
 
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:            0x3
 
Value 6
  Name:            MinorVersion
  Type:            REG_DWORD
  Data:            0x1
 
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

Network Identity Manager Settings

Configuration options for Network Identity Manager (NetIDMgr) are stored in the Windows registry.  Each option can exist in the user registry hive or the machine registry hive or both.  The value defined in the user hive always overrides the value defined in the machine registry hive.  All registry keys used by NetIDMgr exist under the key HKCU\Software\MIT\NetIDMgr under the user and machine hive. 

Common settings for NetIDMgr

The following sections describe a partial list of options that can be specified for NetIDMgr.  Each set of options is described as a set of registry values.  Each section is preceded by the registry key under which the values of that section must be specified.

General settings

    Registry key: 'Software\MIT\NetIDMgr\CredWindow'
    --------------
    Value   : AutoInit
    Type    : DWORD  (0 or 1)
    Default : 0
 
        If this value is '1', shows the new credentials dialog if
        there are no credentials when NetIDMgr starts.
 
    Value   : AutoImport
    Type    : DWORD  (0 or 1)
    Default : 1
 
        If '1', imports credentials from the Windows LSA cache when
        NetIDMgr starts.
 
    Value   : AutoDetectNet
    Type    : DWORD  (0 or 1)
    Default : 1
 
        If '1', automatically detects network connectivity changes.
        Network connectivity change notifications are then sent out to
        individual plug-ins which can perform actions such as renewing
        credentials or obtaining new credentials.
 
    Value   : DestroyCredsOnExit
    Type    : DWORD  (0 or 1)
    Default : 0
 
        If '1', all credentials will be destroyed when NetIDMgr exits.
 
    Value   : HideWatermarks
    Type    : DWORD  (0 or 1)
    Default : 0
 
        If '1', the large shaded NIM logo will not be displayed in the 

        lower right corner of the main window.
 
    Value   : KeepRunning
    Type    : DWORD  (0 or 1)    Default : 1         If '1', when NetIDMgr application is closed, it will continue        to run in the Windows System Notification Area (System Tray).        The application can be exited by choosing the 'Exit' menu        option.  If '0', closing the application will cause it to        exit completely. 

Common Plug-in settings

     Registry key: 'Software\MIT\NetIDMgr\PluginManager\Plugins\<plug-in name>'    --------------     The '<plug-in name>' is one of the following for the standard plug-ins :     Krb5Cred : Kerberos 5 credentials provider    Krb5Ident: Kerberos 5 Identity provider    Krb4Cred : Kerberos 4 credentials provider     Consult the vendors for the plug-in names of other third party    plug-ins.  Additionally, the plug-ins configuration panel in the    NetIDMgr application provides a list of currently registered    plug-ins.     Value   : Disabled    Type    : DWORD (0 or 1)    Default : 0         If '1', the plug-in will not be loaded.     Value   : NoUnload    Type    : DWORD (0 or 1)    Default : 0         If '1', the plug-in will not be unloaded from memory when the        NetIDMgr application exits or if the plug-in is stopped.  The        plug-in binary will remain loaded until NetIDMgr terminates. 

Settings for the Kerberos 5 credentials provider
plug-in

     Registry key: 'Software\MIT\NetIDMgr\PluginManager\Plugins\Krb5Cred\Parameters'    --------------     Value   : CreateMissingConfig    Type    : DWORD (0 or 1)    Default : 0         If '1', creates any missing configuration files.     Value   : MsLsaImport    Type    : DWORD (0, 1 or 2)    Default : 1         Controls how credentials are imported from the MSLSA cache.        This setting can be one of the following.         0 : Never        1 : Always        2 : Only if the principal matches         Note that this setting only controls how the Kerberos 5        plug-in handles importing of credentials from the MSLSA cache.        Whether or not credentials are imported at start-up is        controlled via general NetIDMgr settings as described in        section 3.1.1.     Value   : MsLsaList    Type    : DWORD (0 or 1)    Default : 1         If '1', includes credentials from the MSLSA cache in the        credentials listing.     Value   : AutoRenewTickets    Type    : DWORD (0 or 1)    Default : 1         If '1', automatically renews expiring tickets.  The thresholds        at which renewals happen are controlled in general NetIDMgr        settings.     Value   : UseFullRealmList    Type    : DWORD (0 or 1)    Default : 0         If '1', uses the full realms list as determined by parsing the        krb5.ini configuration file in the new credentials dialog box.        If this is '0', only the last recently used list of realms        will be used. 

Per-identity settings

     Registry key 1: 'Software\MIT\NetIDMgr\KCDB\Identity\<principal name>\Krb5Cred'    Registry key 2: 'Software\MIT\NetIDMgr\PluginManager\Plugins\Krb5Cred\Parameters\Realms\<realm>'    Registry key 3: 'Software\MIT\NetIDMgr\PluginManager\Plugins\Krb5Cred\Parameters'    --------------     These settings are generally maintained per-identity.  However, if    a particular setting is not specified for an identity or if the    identity is new, then the values will be looked up in the    per-realm configuration key and in the global parameters key in    turn.  Global defaults should be set in the global parameters key    (key 3).     Value   : DefaultLifetime    Type    : DWORD    Default : 36000         Default ticket lifetime, in seconds.     Value   : MaxLifetime    Type    : DWORD    Default : 86400         Maximum lifetime, in seconds.  This value is used to set the        range of the user interface controls that allow setting the        lifetime of a ticket.     Value   : MinLifetime    Type    : DWORD    Default : 60         Minimum lifetime, in seconds.  This value is used to set the        range of the user interface controls that allow setting the        lifetime of a ticket.     Value   : Forwardable    Type    : DWORD (0 or 1)    Default : 1         Obtain forwardable tickets.     Value   : Proxiable    Type    : DWORD (0 or 1)    Default : 0         Obtain proxiable tickets.     Value   : Addressless    Type    : DWORD (0 or 1)    Default : 1         Obtain addressless tickets.     Value   : Renewable    Type    : DWORD (0 or 1)    Default : 1         Obtain renewable tickets.     Value   : DefaultRenewLifetime    Type    : DWORD    Default : 604800         Default renewable lifetime, in seconds.     Value   : MaxRenewLifetime    Type    : DWORD    Default : 2592000         Maximum renewable lifetime, in seconds.  The value is used to        set the range of the user interface controls that allow        setting the renewable lifetime of a ticket.     Value   : MinRenewLifetime    Type    : DWORD    Default : 60         Minimum renewable lifetime, in seconds.  This value is used to        set the range of the user interface controls that allow        setting the renewable lifetime of a ticket. 

Settings for the Kerberos 4 Credentials Provider
Plug-in

     Registry key 1: 'Software\MIT\NetIDMgr\KCDB\Identity\<principal name>\Krb4Cred'    Registry key 2: 'Software\MIT\NetIDMgr\PluginManager\Plugins\Krb4Cred\Parameters'    ---------------     Theses settings are also maintained per identity.  However, if the    setting is not specified for some identity or if the identity is    new, then the global default will be used (registry key 2).    Global defaults should be set in the second registry key.     Value   : Krb4NewCreds    Type    : DWORD (0 or 1)    Default : 1         If '1', obtains Kerberos 4 credentials.  Note that currently,        only one identity can have Kerberos 4 credentials at one time.     Value   : Krb4Method    Type    : DWORD (0, 1 or 2)    Default : 0         Method for obtaining Kerberos 4 credentials.  The values are        as follows:         0 : Automatically determine method        1 : Use password        2 : Use Kerberos 5 to 4 translation     Value   : DefaultLifetime    Type    : DWORD    Default : 36000         The default ticket lifetime, in seconds.     Value   : MaxLifetime    Type    : DWORD    Default : 86400         Maximum lifetime, in seconds.  This value is used to set the        range of the user interface controls that allow setting the        lifetime.     Value   : MinLifetime    Type    : DWORD    Default : 60         Minimum lifetime, in seconds.  This value is used to set the        range of the user interface controls that allow setting the        lifetime.

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 0.

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.