Kerberos Testing Information

This document describes the testing of all aspects of the Kerberos V4 library release of Summer 95. This includes everything from building Kerberos on supported platforms to building and running client applications using the new libraries, as well as the testing of backward-compatibility of old clients.

The first step in this process is starting with a clean build machine of each platform. Currently supported platforms are:

DOS, Windows, or NT with Microsoft Visual C++ 1.51. This platform can be used to build:
- (DOS16) the DOS static com_err library,
- (DOS16) the DOS static DES library,
- (DOS16) the DOS static Kerberos library,
- (DOS16) DOS command-line clients,
- (WIN16) the Windows 16-bit static com_err library,
- (WIN16) the Windows 16-bit Kerberos DLL,
- (WIN16) the Windows 16-bit Leash DLL, and
- (WIN16) the Windows 16-bit Leash application.
Note: building the DOS libraries requires access to the Novell LAN WorkPlace Programmer's toolkit, and the libraries and executables produced are only compatible with Novell LAN WorkPlace for DOS.
Windows NT 3.1 or higher on an i386 platform with Visual C++ 2.0. This platform can be used to build:
- (WIN32) the Win32 static com_err library,
- (WIN32) the Win32 Kerberos DLL,
- (WIN32) the Win32 Leash DLL,
- (WIN32) the Win32 Leash application, and
- (WIN32) the Win32 command-line clients,
all for the Win32 i386 platform.
Windows NT 3.1 or higher on an Alpha platform with Visual C++ 2.0. This platform can be used to build the same libraries as Visual C++ 2.0 on the i386, except for the Alpha platform.
OS/2 Warp with C/Set++ FirstStep. I expect the code to build on a newer or more complete version of the compiler, but have no way of testing this. This platform can be used to build:
- (OS2) the OS/2 static 32-bit com_err library,
- (OS2) the OS/2 32-bit Kerberos DLL, and
- (OS2) the OS/2 32-bit command-line clients.

The first step to the process is the creation of an install target directory \ATHENA with the following structure:

ATHENA
- BIN
  - WIN16
  - WIN32
    - I386
    - ALPHA
  - OS2
- LIB
  - WIN16
  - WIN32
    - I386
    - ALPHA
  - OS2
- INCLUDE

The platform-specific leaves are only necessary when building for the specified platform, but this is the structure assumed by the installation procedure below, so the paths to leaves in use should not change. The root of the tree can be placed anywhere you like, ATHENA is just a suggestion.

The new version of the library uses a configuration include file that allows a single MAKEFILE to be used for builds on all platforms for all libraries and clients, theoretically. The variables that need to be set for proper operation of this MAKEFILE scheme are:

PLATFORM

This environment variable must contain a string denoting the target platform of the library or client being compiled. The string is one of DOS16, WIN16, WIN32, or OS2, as denoted in parentheses above in the list of available target libraries and clients.

CPU

This environment variable only needs to be set when compiling with the WIN32 target platform. Currently supported values for this value are i386 and ALPHA.

ATHENA

This environment variable is used by NMAKE INSTALL to copy the libraries and binaries to the correct location. It should be set to the directory name of the athena distribution root directory, e.g. d:\ATHENA.

INCLUDE

This environment variable must have as one entry the directory containing CONFIGUR.MAK, most likely d:\ATHENA\INCLUDE. For WIN16 compiling, it must also have an entry containing DOSWIN16.MAK (provided with the distribution.) For WIN32 compiling, the variable must also have an entry containing NTWIN32.MAK (provided with MS VC++ 2.0 in the \MSVC20\INCLUDE directory.)

The INCLUDE environment variable should be purged of all links to old include directories, such as LOCALH. The include files were updated quite a bit this summer, and the current makefiles and source files are incompatible with the old includes.

Under DOS, the INCLUDE variable also needs to have a pointer to the Novell LAN WorkPlace programmer's toolkit include directory.

LIB

The environment variable should contain a pointer to the appropriate subdirectory of \ATHENA\LIB for the platform being developed for. This directory is used as a repository for the static libraries and import libraries for the specified platforms.

The source code distribution should be unzipped with paths preserved (using PKUNZIP -d or InfoZip's unzip) into any directory. This directory is referred to below as the "build directory."

The "standard build sequence" referred to below is the process undergone for most of the libraries and applications in the Kerberos release. The sequence consists of two steps:

NMAKE - type this to build the default target in the approriate subdirectory. Use NMAKE /a to force a complete recompilation of all default targets.
NMAKE INSTALL - type this after the completed build of a target to copy the output files to the appropriate install target directory (pointed to by the ATHENA environment variable at the time of this writing.)

Another NMAKE target available in most directories is NMAKE clean, a command that clears out the output directory for the current platform, allowing a complete recompilation of the targets.

Descriptions of available targets

com_err

This is the port of the Unix com_err utilities to the PC platform. The com_err library creates a global error code space that allows mappings of many error codes to string tables. It also allows for the installation of hooks for custom error handlers. It's installed into the appropriate subdirectory of ATHENA\LIB.

More information on com_err is given below in the com_err Programmer's Guide.

DES library

This is the DES encryption library. It's compiled into a static library. Except under DOS, it's linked into the Kerberos dynamic link library and exported from there. Under DOS, it's installed in ATHENA\LIB\DOS16.

Kerberos library

This is the Kerberos client library. Under DOS it's a static library in ATHENA\LIB\DOS16, while under other platforms it's a DLL with exports for the Kerberos API as well as the DES API. If you use the lsh_* APIs in this library, you must also have the Leash UI library compiled, since the Kerberos library now simply searches the Leash UI library for the new versions of these APIs.

Leash UI library

This is the new location for the user interface code, relocated from KRBV4WIN in preparation for the future possibility of inserting code to call Kerberos v5 APIs in the future, making one integrated interface for the two Security libraries in the future.

This library is currently only available under Win16 and Win32.

Command-line utilities

These utilities are KINIT, KLIST, KDESTROY, and KEXPIRE. These ticket handling programs get tickets, list them, destroy them, and check for valid ones, respectively.

These utilities are available on systems with command-line interfaces, namely DOS, Win32, and OS/2.

Leash

Leash is the standard GUI app to manage a user's Kerberos tickets. It's available for Win16 and Win32.

Build Instructions

DOS

The DOS Kerberos suite consists of a set of libraries and programs. These are, in the order they should be built:

The static com_err library - to build this, perform the standard build sequence in the COM_ERR subdirectory of the build directory. This library is optional, and is not used in or required for any currently existent DOS applications.
The static DES library - to build this, perform the standard build sequence in the KRB\LIB\CNSDES subdirectory of the build directory. This library is required for almost all Kerberos DOS utilities.
The static Kerberos library - to build this, do not perform the standard build sequence. The correct procedure to follow to build this library is as follows:
- Change directory to KRB\LIB\KRB. The DOS static Kerberos library is the only version of the Kerberos library built out of this directory.
- Type NMAKE /f krblib.mak.
- Neither NMAKE install nor NMAKE clean are availble in this directory. The former should be replaced by an explicit copy command from KRBLIB.LIB to the LIB\DOS16 subdirectory of the ATHENA directory.
  NMAKE clean can be simulated by deleting the files *.OBJ and *.LIB from the directory.
The Kerberos command line utilities - to build these, perform the standard build sequence in the KRB\KUSER subdirectory of the build directory.

Windows 16-bit

The Windows 16-bit Kerberos suite consists of a set of static libraries, dynamic link libraries, and programs. These are, in the order they should be built:

The static com_err library - to build this, perform the standard build sequence in the COM_ERR subdirectory of the build directory. This library is required if you plan to compile any applications that use the Leash user interface dynamic link library, including the Leash application included in this distribution.
The static DES library - to build this, perform half of the standard build sequence in the KRB\LIB\CNSDES subdirectory of the build directory. It is not necessary to install this in the install target directory, since it is simply linked into the Kerberos DLL, and is available by export from there. The Kerberos DLL build procedure expects this library to be in the appropriate subdirectory of KRB\LIB\CNSDES.
The Kerberos dynamic link library - to build this, follow the standard build sequence in the KRB\LIB\KRBDLL subdirectory of the build directory.
The Leash user interface dynamic link library - to build this, follow the standard build sequence in the LEASH subdirectory of the build directory.

Win32

The Win32 Kerberos suite consists of a set of static libraries, dynamic link libraries, and programs, very much like the Win16 libraries. These are, in the order they should be built:

The static com_err library - to build this, perform the standard build sequence in the COM_ERR subdirectory of the build directory. This library is required if you plan to compile any applications that use the Leash user interface dynamic link library, including the Leash application included in this distribution.
The static DES library - to build this, perform half of the standard build sequence in the KRB\LIB\CNSDES subdirectory of the build directory. It is not necessary to install this in the install target directory, since it is simply linked into the Kerberos DLL, and is available by export from there. The Kerberos DLL build procedure expects this library to be in the appropriate subdirectory of KRB\LIB\CNSDES.
The Kerberos dynamic link library - to build this, follow the standard build sequence in the KRB\LIB\KRBDLL subdirectory of the build directory.
The Leash user interface dynamic link library - to build this, follow the standard build sequence in the KRB\LIB\LEASHDLL subdirectory of the build directory.
Leash, the kerberos ticket management application. To build this, follow the standard build sequence in the LEASH subdirectory of the build directory.
The Kerberos command line utilities - to build these, perform the standard build sequence in the KRB\KUSER subdirectory of the build directory.

OS/2

The OS/2 Kerberos suite consists of a set of static libraries, dynamic link libraries, and programs, very much like the other of the libraries. These are, in the order they should be built:

The static com_err library - to build this, perform the standard build sequence in the COM_ERR subdirectory of the build directory. This library is required if you plan to compile any applications that use the Leash user interface dynamic link library, including the Leash application included in this distribution.
The static DES library - to build this, perform half of the standard build sequence in the KRB\LIB\CNSDES subdirectory of the build directory. It is not necessary to install this in the install target directory, since it is simply linked into the Kerberos DLL, and is available by export from there. The Kerberos DLL build procedure expects this library to be in the appropriate subdirectory of KRB\LIB\CNSDES.
The Kerberos dynamic link library - to build this, follow the standard build sequence in the KRB\LIB\KRBDLL subdirectory of the build directory.
Leash, the kerberos ticket management application. To build this, follow the standard build sequence in the LEASH subdirectory of the build directory.
The Kerberos command line utilities - to build these, perform the standard build sequence in the KRB\KUSER subdirectory of the build directory.

Expected Build Output

The following tree is the expected output of the build process described above. It is also a complete build environment for developing Kerberized applications. For an environment of user apps in the Kerberos distribution only, only the files marked with a '*' are necessary. There is no problem with copying only the files for the desired platform.

ATHENA
- BIN
  - DOS16
    - ECOMPILE.EXE
    - *KINIT.EXE
    - *KLIST.EXE
    - *KDESTROY.EXE
    - *KEXPIRE.EXE
  - WIN16
    - ECOMPILE.EXE (DOS executable, actually)
    - *KRBV4WIN.DLL
    - *LEASHWIN.DLL
    - *LEASH.EXE
  - WIN32
    - I386
      - ECOMPILE.EXE
      - *KRBV4W32.DLL
      - *LEASHW32.DLL
      - *LEASH.EXE
      - *KINIT.EXE
      - *KLIST.EXE
      - *KDESTROY.EXE
      - *KEXPIRE.EXE
    - ALPHA
      - ECOMPILE.EXE
      - *KRBV4W32.DLL
      - *LEASHW32.DLL
      - *LEASH.EXE
      - *KINIT.EXE
      - *KLIST.EXE
      - *KDESTROY.EXE
      - *KEXPIRE.EXE
  - OS2
    - ECOMPILE.EXE
    - *KRBV4OS2.DLL
    - *KINIT.EXE
    - *KLIST.EXE
    - *KDESTROY.EXE
    - *KEXPIRE.EXE
- LIB
  - DOS16
    - CERR.LIB
    - DES.LIB
    - KRBLIB.LIB
  - WIN16
    - CERRWIN.LIB
    - KRBV4WIN.LIB
    - LEASHWIN.LIB
  - WIN32
    - I386
      - CERRW32.LIB
      - KRBV4W32.LIB
      - LEASHW32.LIB
    - ALPHA
      - CERRW32.LIB
      - KRBV4W32.LIB
      - LEASHW32.LIB
  - OS2
    - CERROS2.LIB
    - KRBV4OS2.LIB
- INCLUDE
  - COM_ERR.H
  - CONF-PC.H
  - CONF.H
  - CONFIGUR.MAK
  - DES.H
  - DOSWIN16.MAK
  - HESIOD.H
  - KADM_ERR.H
  - KRB.H
  - KRBERR.H
  - KRB_ERR.H
  - LEASHERR.H
  - LEASHWIN.H
  - MIT_COPY.H
  - OSCONF.H
  - WINKRBID.H
  - KRBLAYER.H (ONLY for KRBTEST)
  - LSH_PWD.H (ONLY for KRBTEST)

Testing Kerberos

The testing that the Kerberos libraries have undergone is enumerated here.

(_/ is supposed to be a stylized ASCII checkmark symbol)
(Left two columns blank indicate untested feature)
(** indicate a known bug)

Leash API

_/Leash_changepwd_dlg 		leash
_/Leash_kinit_dlg 		leash
_/Leash_kdestroy		leash
_/Leash_klist			leash
  Leash_get_lsh_errno
_/Leash_kinit			krbtest (via compatibility)
_/Leash_changepwd		krbtest (via compatibility)
_/Leash com_err items		leash
_/proper function of error 	TechMail
    messages (see known bugs)

Backwards compatibility of old Lsh API

_/Lsh_Enter_Password_Dialog	TechMail, TechNotify
_/Lsh_Change_Password_Dialog	krbtest
_/lsh_kinit			krbtest
_/lsh_kdestroy			krbtest
_/lsh_klist			TechMail
_/lsh_checkpwd			krbtest
_/lsh_changepwd			krbtest
_/proper loading and 		TechMail
    unloading of library
_/proper function of error 	TechMail
    messages (see known bugs)

New DES and string_to_key code

_/MIT password recognized	leash (shabby@ATHENA.MIT.EDU)
_/MIT password changed properly	leash (shabby@ATHENA.MIT.EDU)
_/CMU password recognized	leash (pbh@UMICH.EDU)
_/CMU password changed properly leash (pbh@UMICH.EDU)
    (used debugger to verify
    correct string_to_key used)
  Migration from CMU to MIT
  umich_string_to_key

Win32 port of Kerberos
_/kinit
_/klist
_/kdestroy
_/kexpire
_/Leash
_/com_err stuff

Win16 com_err testing

Loading leash alone

_/Incorrect password (krb error 62)
_/Cleartext password did not match key (kadm error 33)
_/Leash-specific error - tickets about to expire, with %b
    MessageBox attributes passed along

Using backward compatibility alone

_/Incorrect password (krb error 62)
_/Insecure password (kadm error 32)

Starting leash, then, while leash is running, starting techmail

See known bugs #2.

Known Bugs

"Press F1 for help" on com_err dialogs even when support not installed.
com_err loaded twice doesn't work - static "link" variable is the heart of the problem. Replace this with an GlobalAlloc'ed link. Another redesign of com_err is necessary for this, to allow freeing of the link as well to make the rest of com_err compatible with a handle for a link instead of static heap memory. This is also why Leash contains kadm and krb error forwarders in leasherr.c currently.
kcomt does not seem to work with the Kerberos library. Since I have no source access to this driver at the time, I am unable to debug the code.

See the Programmer's Guide for information on using these APIs in your own applications:

com_err
Kerberos V4
Leash UI