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
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.
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.
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
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.
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.
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.
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:
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.
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.confand 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.
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.krbIf 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?]
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.
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
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
We use Microsoft Visual C++ to build the source tree. Your mileage with other compilers may vary.
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.
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.
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.
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.
We have always avoided this. I do not understand why this complaint was raised against the Kerberos implementation.
Installer issue. We haven't yet released an installer.
Our installer will address this. It is an unfair complaint when we haven't released the installer yet :)