# Kerberos v4 for Win32 Release Notes for Software Developers

Thanks to: shabby, Paul Hill, Jenny Khuon, Michael Oltz, Steve Rothwell, Gregory M Diskin, Howard Chu, Pierre Goyette, Danilo Almeida, Jeff Beckley, David Tanner, and Art Leather.

Draft Last modified: 03/04/99, dalmeida@mit.edu

### Table of Contents

- What is Kerberos?
- What's New
- Supported Platforms
- Installation and Configuration
- Command Line Options to Leash and Kview
- Browsing the Source Tree
- Building the Source Tree
- To Do
- API notes - API? What API?

## What's New

### 03/04/98

1. Only Win32 support. Yay! This has been tested on i386. Alpha has not been reccently tested, but it should work.

2. Easier make procedure using MSVC++ 4.x (well, 6.0 works for sure...)

3. Leash does not live here right now.

### Previously

1. integration of Kclient into the source release. Cornell provided this work. We made a small modification ot IsCredExpired (see below). Cornell has wrapped the krbv4w32 functions with MUTEXES so the code should be thread safe.

2. 32-bit support, (tested i386, Alpha so far) Can anybody compile this for MIPS and PowerPC and provide us with binaries or necessary source patches?

3. Modification of the 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 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.

4. Add a new function to 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.

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

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

7. Added two new functions to leashw32.dll, Leash_set_help_file(char*szHelpFile) which allows an application developer to specify which help file to use from the Dialogbox 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 what the name of the help file being used is.

   These are defined in lshfunc.c

8. Broke the OS/2 support. Does anyone care?

9. The krbconf.c file was extensively modified. This is one of the places we broke OS/2 support. The libaries still rely on the krb.con and krbrealm.con files however the location is now much more flexible. Here is the order of searching where $(foo) is the value of the environment variable:
   - $(NDIR)\kerb\
   - The current directory
   - The Windows directory
   - The Windows system directory
   - The directory containing the executable file for the current task
   - The directories in the path
   - The list of directories mapped in a network
   - $(NDIR)\
   - $(ETC)\

10. The 32-bit libraries are linked with libcmt instead of libc.

11. Added to the export section of the def files:
    - krb_set_tkt_string
    - krb_get_in_tkt
    - des_pcbc_encrypt
    - LocalHostAddr
    - krb_get_krbhst
    - krb_get_tf_fullname

12. The optimization flags for the NODEBUG build have been changed. /Ox broke things. We took a more conervative approach. No problems noticed so far.

13. Modified Kclient to NOT use x_htons. Kclient now requires winsock. This allows us to build kclient for the Alpha, and theoretically other NT hardware platforms.

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

## Supported Platforms

This release of Kerberos v4 is for Win32 platforms only. These include Windows NT and Windows 9x. We have only built is on x86, but it should work on other CPUs as well.

The libraries provided for Win32 support are:

krbv4w32.dll, kclnt32.dll - (win32) (tested on x86 only)

The applications provided are:

kview32.exe, kinit.exe, kdestroy.exe, klist.exe, kexpire.exe

Leash is no longer included in this distribution. It has been pulled out as a separate component while it is being rewritten. This new version will enable users to obtain version 4 and version 5 tickets through a single username/password dialog.

## Installation/Configuration

#### Table of Contents

- Binaries
- Services File
- Kerberos Configuration Files (krb.con/krbrealm.con)
- Modifying Kerberos Configuration Files (krb.con/krbrealm.con)
- Ticket Cache
- Date and Time Issues

### Binaries

The DLLs `krbv4w32.dll` and `kclnt32.dll` should be in your path.

At MIT we normally recommend to users that they have a directory `c:\net\mit` on their path and that the files reside in this directory. Many other sites recommend that users place these files in their Windows system directory or the Windows directory. MIT prefers to avoid this for a few reasons.

For MIT users we prefer using `\net\mit` for a few reasons. First this directory historically exists on most of our users' systems. It is also where we normally recommend installing locally developed applications. By using this setup we are able to support users that insist on running multiple operating systems or multiple versions of an operating system on their machine. It is much easier to track down a single copy of a DLL and determine its version number. Also the number of files in this directory is much smaller than in the OS directory so it is much easier for users to locate and determine the version number if this becomes necessary. Finally, very few third party installers will attempt to modify the `\net\mit` directory so we don't worry about what another application will do to our binaries.

The disadvantages to seperating the DLLs from the OS are that users must add yet another directory to their path. And when they do this manually they may make a typing mistake. Sometimes the typing mistakes can be subtle and difficult to resolve. E.g `c:\net\mit` is not the same as `c\net\mit`.

If users like to invoke the applications from a command line instead of just the GUI the applications should also be on the path. Again at MIT we normally install `kview32.exe`, `kinit.exe`, `kdestroy.exe`, and `klist.exe` in `\net\mit`.

### Services File

The Kerberos DLLs need to know what port to talk to the Kerberos server on. They obtain this information from the local services file. In many cases you may to add a line to the services file especially if the vendor did not provide this in the default services file.

If the information is absent from the local services file you will normally get a "Can't send request (send to kdc)" error.

Usually the line that will need adding is:

    kerberos 750/udp kdc #kerberos UDP

In the case of Microsoft NT the default services file normally contains this already. This file is usually located in `\winnt\system32\drivers\etc`.

For other stacks you should consult the vendor documentation or just search your local hard disk for a file named services.

Note: It seems that the "kerberos-master 751/tcp" line in the services file is obsolete and not required.

### Kerberos Configuration Files (krb.con/krbrealm.con)

The Kerberos DLLs normally need two configuration files to function properly. These are krb.con and krbrealm.con. Older releases had overly restrictive locations for these files. Previously the files had to be located in `c:\net\kerb` or `%NDIR%\kerb` where `%NDIR%` was an environment variable e.g. `set NDIR=d:\etc` and the files should be located in `d:\etc\kerb\`

At the suggestion of several sites we relaxed this restriction. The DLLs will now search for the `krb.con` and `krbrealm.con` in the following locations and search oder:

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: `%NDIR%` and `%ETC%` indicate the expansion of the environment variables named `NDIR` and `ETC`, if present.

It is up the local system administrator or end user to configure the machine for reasonable performance.

### Modifying Kerberos Configuration Files (krb.con/krbrealm.con)

It is anticipated that most sites using Kerberos version 4 on Windows will also have an existing UNIX Kerberos infrastrucutre. For that reason we kept the format of the `krb.con` indetical 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 site will be to simply ftp the corresponding files from a local UNIX machine that is already properly configured.

The `krb.con` file contain 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 was 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 realmname 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.

### Ticket Cache

At this time users must store their tickets on the disk. We hope to change this in the near future.

If you are an NT user concerned about security use the NTFS file system and store the tickets in a directory that is writeable and readable by you but no one else. This directory should not be shareable. Nor should it be on a remote machine.

You can specify the name of the ticket file and the directory in which it is stored via the environment variable `KRBTKFILE`. For example, to store your tickets in a file called `tkt-joe.krb` in the directory `c:\users\joe-user`, use the follwing statement:

    set KRBTKFILE=c:\users\joe-user\tkt-joe.krb

If the environment variable `KRBTKFILE` is not used, the default value `%TEMP%\ticket.krb` will be used. That is, tickets will be stored in the file `ticket.krb` in `%TEMP%`. If you do not have an environment variable named `TEMP` the environment variables `TMP` and `HOME` will also be checked and used if present. As a last resort the hard coded path `c:\tmp\ticket.ktb` will be used. Whichever method is used you'll have to make sure the directory exists, or Windows Kerberos will report an error.

[note: which applications produce what error mesage under this condition?]

### Date and Time issues

Why Kerberos cares what time it is...

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 Microsoft Windows will need to be "accurately" set. If the date or time is off "too far", Kerberos authentication will not work.

In this release if a clock skew error is detected the libraries will attempt to resynchronze the clock to the network time automatically one time. The user will be warned that this has occured. If this fails or if a clock skew is detected again later the user will have to manually resynchronize the machine time to the Kerberos server's time. The Leash application provides a buton which will attempt to resynchronize the clock.

By default the server that the libraries will 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 you local system administrators are opposed to doing this for some reason people can edit the resource `LSH_TIME_HOST` in the `leashw32.dll` to the name appropriate for their 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 avoid this problem by running a local, properly configured, NTP program on your machine.

## Command Line Options to Leash and Kview

The command line options for Leash are:

    	-v	skip version checking
    	-kinit	only perform a kinit and then exit Leash

The command line options for Kview are:

    	/clear	destroy all tickets for the user
    	/sync	synchronize the time with a server
    	/hide	remain invisible
    	/quit	exit Kview
    	/ask	ask before synchronizing the time with a server

## Browsing the Source Tree

Here is the layout of the MIT Kerberos v4 for Win32 source tree.

    krb4
    +---bin			The libs, dlls, and exes generated by the build process
    +---com_err		The com_err (common error) compiler and library
    +---doc			The leash.rtf and kerberos.hpj files
    +---include		Most of the header files required for the build and
    |			those that may be required by third party
    |			applications using these libraries
    +---kclient		Cornell's Kclient DLL source
    |   \---include		The Kclient headers
    +---krb			The MIT portion of the tree
    |   +---include		More header files
    |   +---kuser		source for kinit, klist, kdestroy
    |   \---lib
    |       +---cnsdes	The Windows DES source code, from Cygnus
    |       +---krbdll	The Kerberos portion of krbv4wXX.dll
    \---kview		The source for Cornell's Kview.exe and Kview32.exe

## Building the Source Tree

We use Microsoft Visual C++ to build the source tree. Your mileage with other compilers may vary.

1. Unzip the source distribution with the -d option so that the directory structure is preserved.
2. Optionally define the build environment
3. Type `nmake` (with the appropriate options if step 2 is skipped)

The toplevel make file requires a few environment variables to be defined. These can be defined before invoking nmake or they can be specified as arguments to `nmake`. If you invoke nmake without defining these varibles, you will get an error message describing what you need to define.

The variable below are the only ones that you should have to define:

    NODEBUG=		#if undefined, will create debug binaries
    			#setting it will yield symbol free binaries
    KRBV4_PATH=c:\src\krb4	#the path where this makefile resides
    VC32_DIR=c:\msdev	#the toplevel path of your 32-bit compiler

To set these variables at the `nmake` command-line. Here are some examples:

    For a debug Win32 i386 build:
    	nmake KRBV4_PATH=c:\src\krb4 VC32_DIR=c:\msdev

    For a symbol free (nodebug) Win32 i386 build:
    	nmake KRBV4_PATH=c:\src\krb4 VC32_DIR=c:\msdev NODEBUG=1

There are several flags that get set in the make files. By default we build with -DAFS so that the both MIT and Transarc AFS style string to key algorithms will be tried when authenticating.

We need to document other aspects of the make files, any volunteers?

The make files will create logs of the build in makwin32.log. Look there if something fails.

## To Do

1. In memory ticket cache on NT

2. Installer

3. com_err rewrite and well documented way for applications to control error reporting to the end user. Cornell went to a lot of effort to overcome out limitations.

4. Re-implementation of displaying debug messages without using a message box. The intention is to provide similiar functionality to debugwin without having to distribute debugwin to end users.

5. Rewrite of Leash to support v4 and v5 as well as having many improvements in the user interface.

6. People have suggested that we use the registry more.

7. At this time I am delaying that. First I want to know how MS is going to use the resgistry for Kerberos v5 in NT 5.0. I am also in an environment where we are support win16 apps running on win32 and win16. Given the issues that this would involve us in I prefer to punt for now. I agree that Kerberos v5 needs to address this issue. I am not sure that v4 warrents this work at this late date.

8. Other complaints:

   1. Apps that require extra environment variables to be set

      We no longer require environment variables but will use them to modify the behavior of searching for the krb.con and krbrealm.con files (NDIR). KRBTKFILE can be used to modify the location and name of the ticket cache when in memory tickets are not being used. KERB_HELP can be set to specify the name of the Kerberos help file.

   2. Apps that require additions to the PATH variable

      Similar to the above explanation. Modifications to the path are not required but at MIT we prefer to put locally developed DLLs and EXEs in \net\mit and then add this to the path. This makes it easier to support users that run multiple versions of Windows on the same machine. It also allows us to survive OS re-installs. It is also helpful to users that like to start applications from the command line.

   3. Apps that require root level directories to be created

      I am not aware that we ever required this. If someone thought we did it was probably due to poor documentation of the configuration options.

   4. Apps that install lots of stuff to the windows directory

      We have always avoided this. I do not understand why this complaint was raised against the Kerberos implementation.

   5. Apps that don't query the user before overwriting files

      Installer issue. We haven't yet released an installer.

   6. Apps that don't have a full uninstaller (which includes removing registry entries and removing the installation directory once its empty).

      Our installer will address this. It is an unfair complaint when we haven't released the installer yet :)