Kerberos for Windows 3.2.2

Release Notes

22 October 2007

Table of Contents

• Overview
• What's New in KfW 3.2.2
• 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.3, Kerberos v5 GSS API library, Kerberos 524 library, KClient API library, Leash API library, Network Identity Manager, kinit/klist/kdestroy/krb524init/ms2mit/mit2ms 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.2

• Network Identity Manager Application

• Always raise NetIdMgr window to foreground if displayed when prompting for new credentials.
• Password entry field now accepts 1024 characters.
• Add --show and --hide command line options.
• Add View->All Identities menu item.
• Add Set Default menu item to notification icon menu.
• Replace usage text with command-line option display window.
• Defines a new color schema.  Color values are no longer imported from the user's desktop theme.
• Notification icon reflects status of the default identity instead of all identities.
• Add default identity information to notification icon tooltip.
• Fix resource leaks; erroneous return codes.
• Correct behavior when new identity already exists or is restored.
• Correctly position context menus when opened via the keyboard.
• Correct selected identity display problems.
• Correctly position New Credentials dialog.
• Correct various race conditions and selection problems that resulted in the display not being updated.
• Correct column resizing problems.
• Correct configuration cleanup problems.
• Eliminate deadlock conditions.
• Improve response to external registry changes.
• FILE: ccache performance improvements.
• "Unable to load" errors are no longer reported for uninstalled plug-ins.
• Kerberos v5 identity provider dialog password prompt permits horizontal scrolling.

• Credential Cache API changes

• The CCAPI implementation is now compatible with Windows Terminal Server.

• Kerberos v5 Library Improvements

• Based on MIT release 1.6.3.
• MSLSA: ccache properly translates Unicode strings to the local ANSI character set.
• krb5_get_profile() is exported from krb5_32.dll.

• Installer Changes

• Fix problems uninstalling older versions.
• Remove the registration requirement for administrative installations when using the MSI installer.
• MSVC DLLs include DST 2007 changes.

• Build system changes

• NIM Schema files can now support external file inclusion.
• Add static ordinals to DLL exports.
• krbcc credential cache api implementation can now be compiled with Microsoft Visual Studio 2005.
• Enable builds on 64 bit Windows.
• NIM API version is now 10.

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.  Native 64-bit Windows XP, 2003, and Vista applications are not being distributed as part of this release.

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:

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

Network Identity Manager Binaries

Network Identity Manager main executable.

Provides information to Windows about which versions of libraries should be associated with netidmgr.exe.

Kerberos 4 credentials provider plug-in.

English (US) language resources for the Kerberos 4 credentials provider.

Kerberos 5 credentials provider and identity provider plug-in.

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

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

--minimized               start netidmgr in minimized mode

--show                    unhide the Network Identity Manager window

--hide                    hide the Network Identity Maganer window

--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++ or Visual Studio 2005 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.

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:

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:

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.