Kerberos v4 for Microsoft operating systems release notes for software developers:
Thanks to: shabby, Jenny Khuon, Michael Oltz, Steve Rothwell, Gregory M Diskin, Howard Chu, Pierre Goyette, Danillo Dalmeida and Jeff Beckley
Draft Last modified:3/10/95, pbh
This release of Kerberos v4 libraries and applications provides support for Windows NT, Windows 95, Windows 3.11, WFWG 3.11 and a limited amount of support for DOS. The DOS support is limited to machines using Novell's LAN Workplace for DOS TCP/IP stack.
Actually the DOS support is pretty broken at the moment. It builds. Klist and Kdestroy work if you go to some additional setup trouble. Because of changes made to the credential cache kinit and other applications like from do not work. This may be fixed in afuture release, if enough people complain.
Previously there was some support for native OS/2 libraries and applications. We broke that in this release. We no longer have any OS/2 resources in our programming group. If someone wants to work on this please let us know.
All other libraries and applications require Winsock 1.1 support. This includes the LAN Workplace stack, the stacks provided by Microsoft in Windows 95 and NT, and stacks from several other vendors.
The libraries provided for Win16 and Win32 support are:
krbv4win.dll, lshwin.dll, kclient.dll - (win16)
krbv4w32.dll, lshwin32.dll, kclnt32.dll - (win32) (i386, Alpha, ?, ?)
The applications provided are:
Leash.exe, leash32.exe, kview.exe, kview32.exe, kinit.exe, kdestroy.exe, klist.exe, kexpire.exe
Please note that the leash32.exe is not intended for distribution to end users at this time. It functions but has several painting and redraw problems. We have not put any effort into fixing these problems and we do not expect to. We will instead be working on a complete rewrite of Leash which will incorporate many requested features. More importantly the future version will enable users to obtain version 4 and version 5 tickets through a single username/password dialog.
Configuration of the binaries
The DLLs krbv4win.dll, kclient.dll, leashwin.dll should be on your path for all 16 bit applications to be able to use them. If your operating system is Windows 95 or Windows NT you should also have copies of krbv4w32.dll, kclnt32.dll, and leashw32.dll on 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 leash.exe, kview.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 Novell's LAN WorkPlace you will probably have to enter this manually. Some version locate this file in \net\tcp. In the case of Microsoft NT the default services file normally contains this already. This file is located in \winn5\system32\drivers\etc.
For other stacks you should consult the vendor documentation or just search your local hard disk for a file named services.
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.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_realmIf 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.
Storing tickets - file or memory? The choice is sometimes yours.
Previous versions of MIT's Windows Kerberos required a small memory resident (TSR) program, kerbmem.exe, be run prior to starting Windows. This set aside a small chunk of memory in DOS in which to store Kerberos tickets. Kerbmem.exe is now optional for Windows 3.x and Windows 95 users, and as an alternative, Windows Kerberos can store tickets in a file on disk.
At this time Windows NT users must store their tickets on the disk. We hope to change this in the near future.
There is some controversy over storing Kerberos tickets on disk for microcomputer operating systems like Windows, OS/2, and Macintosh. If stroring Kerberos tickets on disk gives you the heebie-jeebies, go with kerbmem.exe. If running yet another DOS TSR gives you the heebie-jeebies, go with tickets on disk.
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.
If kerbmem.exe is not loaded, Windows Kerberos will store tickets in a file on disk. 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?]
Why doesKerberos care 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 leashwXX.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 LeashThe 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
KERB16.EXE is a thunking layer for use by a 32 bit application to the 16 bit kclient.dll. It was written by Qualcomm for use by Eudora Pro previous to the availability of kclint32.dll. Qualcomm has granted us permission to distribute kerb16.exe in this release. However, Qualcomm has not released the source code.
32 bit versions of Eudora Pro will use the kclnt32.dll if it is present of the path. If klcnt32 is not present of the path the application will fall back to using kerb16. Eudora Pro 3.0 exhibits this behavior however this version calls kclnt32 with some invalid parameters. If you are using Eudora Pro 3.0 you should upgrade. In the meantime remove kclnt32.dll from your path so that Eudora Pro 3.0 will use kerb16.exe.
A description of the source tree
Please note that there is often some confusion about the DES, CNSDES, KRB and KRBDLL portions of the tree. The lib\DES and lib\KRB directories are specific to the DOS16 target. The lib\CNSDES and lib\KRBDLL are used for the Win16, Win32, and formerly OS/2 versions of the libraries.
C:.
+---bin The libs, dlls, and exes generated by the build process
| +---dos
| +---win16
| \---win32
| +---alpha
| \---i386
+---com_err The com_err (common error) compiler and library
| +---dos16dbg
| +---DOS16REL
| +---os2dbg
| +---win16dbg
| +---WIN16REL
| +---win32dbg
| | +---alpha
| | \---i386
| \---WIN32REL
| \---i386
+---doc The leash.rtf and kerberos.hpj files
| +---DOS16DBG
| +---DOS16REL
| +---WIN16DBG
| +---WIN16REL
| +---WIN32DBG
| | \---i386
| \---WIN32REL
| \---i386
+---ext-lib External libaries from MIT used in the build
+---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
| +---WIN16DBG
| +---WIN16REL
| +---WIN32DBG
| | \---i386
| \---WIN32REL
| \---i386
+---krb The MIT portion of the tree
| +---include More header files
| +---ksample original UNIX sample source code
| +---kuser source for kinit, klist, kdestroy
| | +---dos16dbg
| | +---DOS16REL
| | +---os2dbg
| | +---rapp
| | +---win
| | +---WIN16DBG
| | +---win32dbg
| | | +---alpha
| | | \---i386
| | \---WIN32REL
| | \---i386
| +---lib
| | +---cnsdes The Windows DES source code, from Cygnus
| | | +---doc
| | | +---dos16dbg
| | | +---os2dbg
| | | +---win16dbg
| | | +---WIN16REL
| | | +---win32dbg
| | | | +---alpha
| | | | \---i386
| | | +---WIN32REL
| | | | \---i386
| | | \---windbg
| | +---des The DOS DES source code, from an older MIT release
| | +---krb The DOS Kerberos library
| | | +---dos16dbg
| | | \---win32dbg
| | +---krbdll The Kerberos portion of krbv4wXX.dll
| | | +---dos16dbg
| | | +---os2dbg
| | | +---win16dbg
| | | +---WIN16REL
| | | +---win32dbg
| | | | +---alpha
| | | | \---i386
| | | +---WIN32REL
| | | | \---i386
| | | \---windbg
| | +---leashdll The source for leashwXX.dll
| | | +---binsafe
| | | +---dos16dbg
| | | +---win16dbg
| | | +---WIN16REL
| | | +---win32dbg
| | | | \---i386
| | | \---WIN32REL
| | | \---i386
| | \---win16dbg
| +---makedepd
| \---win
+---kview The source for Cornell's Kview.exe and Kview32.exe
| +---win16dbg
| +---WIN16REL
| +---win32dbg
| | \---i386
| \---WIN32REL
| \---i386
\---leash The source code for Leash.exe and Leash32.exe
+---win16dbg
+---WIN16REL
+---win32dbg
| +---alpha
| \---i386
\---WIN32REL
\---i386
Preparing to build the source
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:
PLATFORM=WIN32 #choose your target (DOS16, WIN16, WIN32) CPU=i386 #choose the CPU for Win32 builds (i386, alpha, mips, ppc) NODEBUG= #leaving this variable undefined will create binaries with debugging information #setting it to TRUE 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 VC16_DIR=c:\msvc #the toplevel path of your 16 bit compiler
To set these variables at the nmake command-line. Here are some examples:
For a debug Win32 i386 build: nmake PLATFORM=WIN32 CPU=i386 KRBV4_PATH=c:\src\krb4 VC32_DIR=c:\msdev For a symbol free (nodebug) Win32 i386 build: nmake PLATFORM=WIN32 CPU=i386 KRBV4_PATH=c:\src\krb4 VC32_DIR=c:\msdev NODEBUG=TRUE For a debug Win16 build: nmake PLATFORM=WIN16 CPU=i386 KRBV4_PATH=c:\src\krb4 VC16_DIR=c:\msvc For a symbol free (nodebug) Win16 build: nmake PLATFORM=WIN16 CPU=i386 KRBV4_PATH=c:\src\krb4 VC16_DIR=c:\msvc NODEBUG=TRUE For a debug DOS build: nmake PLATFORM=DOS16 CPU=i386 KRBV4_PATH=c:\src\krb4 VC16_DIR=c:\msvc For a symbol free (nodebug) DOS build: nmake PLATFORM=DOS16 CPU=i386 KRBV4_PATH=c:\src\krb4 VC16_DIR=c:\msvc NODEBUG=TRUE
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 by default. The name of the log file depends on the target build. They will normally be named makDOS16.log, makWIN16.log and makWIN32.log.
If you want to build all i386 targets in both debug and nodebug form, first set VC32_DIR to point to your 32-bit compiler, VC16_DIR to your 16-bit compiler, and KRBV4_PATH to the location of the main Makefile. Then just run the make.bat file.
What have we accomplished in this release?
1) easier make procedure.
Win32 binaries require MSVC++ 4.x
Win16 binaries require MSVC++ 1.5x
2) 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.
3) 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?
4) 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 older DOS applications or machines with multiple copies of kclient.dll or krbv4win.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.
5. 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 whatI 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.
6. 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.
7. 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.
8. Added two new functions to leashwxx.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
9. Broke the OS/2 support. Does anyone care?
10. 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)\
11. The 32 libraries are linked with libcmt instead of libc.
12. 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
The Win16 DLL should be much easier to link to from languages other than C, but it retains backwards compatibilty with previous versions. To see how read windes.def, and retch :)
13. The optimization flags for the NODEBUG build have been changed. /Ox broke things. We took a more conervative approach. No problems noticed so far.
14. 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.
15. 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.)
What have we NOT accomplished in this release?
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.
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.
7) Other complaints:
a) 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.
b) 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.
c) 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.
d) 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.
e) Apps that don't query the user before overwriting files
Installer issue. We haven't yet released an installer.
f) 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 :)
3/11/96 CMU reported that Kview and Kview32 would GPF when a user entered a username of the form username.realm instead of username@realm, this only occured when forcing the realm to uppercase. UMich provided a bug fix.
3/11/96 UMich reported that some obj files remained after the clean targets were made. The provided changes to krb\lib\krb\makefile.bc, krb\kusr\makefile.bc, and krb\lib\cnsdes\makefile
3/11/96 UMich reported formatting problem and fix with kerb-rel.html page.
3/11/96 UMich asked about "kerberos-master 751/tcp" line in a services file and asked if it was required. We believe that it is obsolete and not required.
3/11/96 UMich reported errors inbuilding the kerberos.hlp file during the WIN16 build. The MessageBox title was "HC31.exe OS/2 Subsystem Application Load Failure". The message was "You are attempting to execute a bound DOS-OS/2 application. The application uses an unsupported OS/2 API and therefore cannot be executed by the OS/2 subsystem. ..." Pressing enter allows the make to continue. It looks like the ~\doc\makefile needs further configuration work. I have not been able to reproduce this or offer a fix. unresolved