Guide to Building KerbNet

KerbNet includes software and documentation developed at the Massachusetts Institute of Technology, which includes this copyright information:

Export of software employing encryption from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.

WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

KerbNet includes software and documentation developed by OpenVision Technologies, Inc., which includes this copyright notice:

The following copyright and permission notice applies to the OpenVision Kerberos Administration system located in kadmin/create, kadmin/dbutil, kadmin/server, lib/kadm, and portions of lib/rpc:

Copyright, OpenVision Technologies, Inc., 1996, All Rights Reserved WARNING: Retrieving the OpenVision Kerberos Administration system source code, as described below, indicates your acceptance of the following terms. If you do not agree to the following terms, do not retrieve the OpenVision Kerberos administration system. You may freely use and distribute the Source Code and Object Code compiled from it, but this Source Code is provided to you "AS IS" EXCLUSIVE OF ANY WARRANTY, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, OR ANY OTHER WARRANTY, WHETHER EXPRESS OR IMPLIED. IN NO EVENT WILL OPENVISION HAVE ANY LIABILITY FOR ANY LOST PROFITS, LOSS OF DATA OR COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY SPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT, INCLUDING, WITHOUT LIMITATION, THOSE RESULTING FROM THE USE OF THE SOURCE CODE, OR THE FAILURE OF THE SOURCE CODE TO PERFORM, OR FOR ANY OTHER REASON.
OpenVision retains all rights, title, and interest in the donated Source Code. With respect to OpenVision's copyrights in the donated Source Code, OpenVision also retains rights to derivative works of the Source Code whether created by OpenVision or a third party. OpenVision Technologies, Inc. has donated this Kerberos Administration system to MIT for inclusion in the standard Kerberos 5 distribution. This donation underscores our commitment to continuing Kerberos technology development and our gratitude for the valuable work which has been performed by MIT and the Kerberos community.

KerbNet includes software and documentation developed at the University of California at Berkeley, which includes this copyright notice:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
All advertising materials mentioning features or use of this software must display the following acknowledgement:
This product includes software developed by the University of California, Berkeley and its contributors.
Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notices and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

Introduction

KerbNet is supplied in source form for a number of reasons:

You can examine the source yourself, and verify the behavior of the system to your satisfaction. This is especially important with security software.
You can make your own changes.

KerbNet is a large package. Cygnus Solutions has streamlined the build process through use of several tools and packages, and through use of a build script, `buildcns5full'. This script is set up with conditionalized defaults, such that using the defaults will result in a successful build on each supported platform. (For example, the default compiler is the vendor-supplied C compiler on systems where the native compiler is known to work, and is `gcc' on systems where the native compiler is known not to work.) For this reason, Cygnus Solutions recommends running `buildcns5full', specifying only those options for which you require behavior different from the defaults.

Requirements

At the very minimum, you need a UNIX-like operating system with an ANSI C compiler. (The MacOS and Windows ports are not discussed here.) While the build process checks for particular requirements and is often able to compensate if they are not met, this is not possible in every instance. Of course, Cygnus Solutions recommends gcc, but we have attempted to make the compilation work with both gcc and the "native" or OS-vendor-supplied compiler, whenever possible.

You need GNU make(1) and GNU m4(2).

In order to run all of the tests in the built-in KerbNet test suite, you will need to have runtest from the DejaGnu package (3) installed. You will also need Tcl, Tk, and expect, which are required by the DejaGnu package.

If you will be making an install kit (See section Constructing an Install Kit.), you will need gzip(4).

Finally, if you will be building `xdm', the X display manager, you need the following:

`xmkmf' needs to know where to find header files and libraries. An easy way to test this is to make sure
```
% xmkmf ; make
```
works on a simple X program.
Note: If you are using gcc, the imake config files should check for the HasGcc and HasGcc2 flags, and set the compiler options appropriately if needed. If
```
% xmkmf ; make CC=gcc
```
works, you should still be able to build Xdm.
The programs `xterm', `X' (the X server), and `xrdb' must be found.
The Athena widget set (the library and header files) must be available.

Performing the Build

Unpack the source tar file from the top-level (`/') directory. It will unpack into /usr/cygnus/kerbnet-1.2/source/krb5.
If you will be building the Cygnus Solutions versions of Tcl and Tk, unpack the source tar file from the top-level (`/') directory. It will unpack into /usr/cygnus/kerbnet-1.2/source/progressive.
Change directories into /usr/cygnus/kerbnet-1.2/source.
If there is a `src' directory from a previous build, do:
```
% rm -rf src
```
Run the `buildcns5full' command as follows, with the options you need. (See section buildcns5full Options and section configure Options for the complete list of options.)
```
% ./krb5/etc/buildcns5full --option1 --option2 ...
```
substituting the options you need in place of --option1 and --option2.
Wait for the build to finish. It should take approximately two hours on a reasonably fast machine (e.g., a 166 MHz Pentium with 64 Mb of memory).
Assuming the `buildcns5full' script finishes the builds and the tests, you should now have a working set of KerbNet binaries. Note that even if you build the KerbNet Tcl package, `buildcns5full' skips the Tcl tests. If you were to run make check in the Tcl directory, the tests would fail because the KerbNet Tcl setup is different from the setup for which the tests were designed. These Tcl test failures do not affect the use of Tcl and Tk in KerbNet.

buildcns5full Options

The following options are defined in the `buildcns5full' script:

--config: Run configure before performing build. This is the default.
--no-config: Do not run configure before performing the build.
--wipe: Remove any existing build before performing the new build.
--no-wipe: Do not remove any existing build before performing the new build. This is the default.
--clean: Run make clean before performing the build.
--no-clean: Do not run make clean before performing the build. This is the default.
--pack: After the build is complete, make a gzipped tarfile of the executables and place it in a directory called `pkgdir' under the build directory. Note that this requires that you have `gzip' installed. (see section Requirements.)
--no-pack: Do not make a gzipped tarfile of the executables. This is the default.
--check: Run make check after performing the build. This is the default.
--no-check: Do not run make check after performing the build.
--top TOPDIR
--top=TOPDIR: Sets the location of the top of the source tree to be TOPDIR. The default value is krb5.
--make MAKE-PROGRAM
--make=MAKE-PROGRAM: Uses MAKE-PROGRAM as the make program. Default value is gmake for NetBSD; make for other platforms. Note, however, that the values of the variable refer to the name of the make program. The make program must be the GNU version. (see section Requirements.)

configure Options

In addition to those listed in the previous section, you can give `buildcns5full' any of the standard options to configure, or any of the options defined below, and `buildcns5full' will pass those options to configure. The available options, as defined in `aclocal.m4' and/or in the `configure.in' files are:

--enable-athena: If V4 compatibility is also enabled (the default), construct kadmin.v4, the KerbNet V4 compatible Kerberos Administration Server, and krb524, the conversion tools to allow users to generate V4 tickets from V5 tickets. For further details, see the section `KerbNet V4 Backward Compatibility Support' in Cygnus Network Security -- Version 5.
It also causes KRB5_ATHENA_COMPAT to be defined, which may have affects in future releases, but is currently unused.
--prefix pathname: Specify that the installed tree be rooted at pathname. The MIT default is to use `/krb5', but the default in Cygnus Solutions KerbNet is to use `/usr/cygnus/kerbnet-1.2'.
--with-cc=COMPILER: Select compiler to use, and write it into the constructed Makefiles as the default value of CC.
--with-linker=LINKER: Select linker to use, and write it into the constructed Makefiles as the default value of LD. This is useful for building with Purify.
--with-ccopts=CCOPTS: Select compiler command line options, and write it into the constructed Makefiles as the default value of CCOPTS. This is useful for building with debugging or optimization.
--with-cppopts=CPPOPTS: Select compiler preprocessor command line options, and write it into the constructed Makefiles as the default value of CPPOPTS. useful for setting flags.
--with-netlib=libs: Use user-defined resolve library. Normally, the resolver is part of the C library, but on SunOS systems using NIS, you may need to specify -lresolv in order to get a proper domain name resolver.
--enable-shared: Construct KerbNet shared libraries. This is the default.
--disable-shared: Construct KerbNet static libraries.
--with-shared: Use already-constructed KerbNet shared (default) libraries.
--without-shared: Don't use already-constructed KerbNet shared (default) libraries.
--enable-telnet-encryption: Use non-standard encryption in telnet. The telnet implementation provides for the use of DES in a stream mode to encrypt the connection, but there are some user interface issues that may make it less safe. Always verify that encryption is being used by using ^[ enc status RET rather than trusting the message, which may have been inserted by an attacker. For this and other reasons, the encryption mode is not yet an Internet Standard, but work is expected in the near future to change that.
--disable-telnet-encryption: Don't enable the non-standard telnet encryption mode described above.
--enable-xdm: Build Xdm. This is the default. Be sure your system meets the requirements for building Xdm (See section Requirements).
--disable-xdm: Do not build Xdm.
--with-oracle: Use Oracle for backend database. (Works only on Solaris 2.5.)
--with-oracle-logging: Allow Oracle to be used for logging info. (Works only on Solaris 2.5.)
--with-tcl=TCL-PATH: Use the copy of Tcl that resides at TCL-PATH.
--with-tk
--with-tk=TK-PATH: Build the Tcl installation and admin (GUI) programs. If TK-PATH is specified, use the copy of Tk that resides there. If --with-tk is specified without a value for TK-PATH, use the version of Tcl and Tk preinstalled in `/usr/local/lib' or `/usr/lib'. If the `tkConfig.sh'(5) script does not exist in either of these directories, build and use the versions of Tk and Tcl that were included in the source tarfile. The default value is --with-tk.
--with-netscape=NETSCAPEDIR: Build the Netscape plug-in using the preinstalled Netscape header files in NETSCAPEDIR. (Works only on Solaris 2.5.)
--without-netscape: Do not build the Netscape plug-in. This is the default.
--with-predictive-securid: Use the SecurID code, which provides for hardware preauthentication using a SecurID device. Note that this requires the proprietary SecurID libraries.
--without-predictive-securid: Do not use the SecurID code. This is the default.
--with-vague-errors: Do not supply helpful error messages to clients.
--without-vague-errors: Supply helpful error messages to clients. This is the default.
--with-kdc-kdb-update: Force the KDC to update the database with the last request.
--without-kdc-kdb-update: Do not force the KDC to update the database with the last request. This is the default.
--enable-des-cbc-crc: Enable the des-cbc-crc encryption type. This is the default. des-cbc-crc is the only currently supported encryption type.
--disable-des-cbc-crc: Disable the des-cbc-crc encryption type.

Running Tests Manually

If, for any reason, you need to run the KerbNet tests manually, cd to the `tests' directory under the `build' directory, and run make check. This will run a number of built-in tests of:

raw database code
raw encryption code
various Kerberos V5 interfaces including kadmin

The test suite will also run a set of live application tests, creating a test realm, starting a Kerberos server (krb5kdc), admin server (kadmind), and clients, and testing their features the way a user would use them. The end summary should list no unexpected failures.

If you do find problems, you can get specific details by changing to the `tests/dejagnu' directory and running runtest with the `-d' option, and examining the `dbg.log' file produced. (This will not be necessary with any platform supported by Cygnus Solutions.)

Note also that some of the tests are run as root. If you are not able to log in as root using the command rlogin -l root hostname, this will result in at least two untested test cases.

Constructing an Install Kit

An install kit is a gzipped tarfile that will unpack from / into the install directory (/usr/cygnus/kerbnet-1.2 unless otherwise specified by the --prefix option). You can make an install kit by giving the --pack option to the `buildcns5full' script. Alternatively, once your build is complete, you can make an install kit by running make tgz-bin from the build directory. Note that this requires that you have `gzip' installed. (see section Requirements.)

Unsupported Configure Options

The following configure options appear in the source code. However, Cygnus Solutions does not support them, and they are not known to work. (In fact, some of these are known not to work.) They are included in this document for completeness.

--with-dbm: Use native dbm for the key database. This optional database is most useful when users have principals in multiple realms that have common access. However, this situation rarely occurs.
--without-dbm: Use included version of Berkeley db. This is the default.
--with-dbm-lname: Use native dbm for aname to lname conversion database. This optional database is most useful when users have principals in multiple realms that have common access. However, this situation rarely occurs.
--without-dbm-lname: Use included version of Berkeley db. This is the default.
--without-krb4: Don't include any Kerberos V4 backwards compatibility support in applications, and don't build the V4 libraries either.
--with-krb4: KerbNet V4 libraries (enhanced for compatibility use) are included as part of the KerbNet V5 source tree. By default, or with this option, these are built and installed in `libkrb4.a' and are used in various utilities.
--with-krb4=KRB4DIR: Enable V4 backwards compatibility support, but use existing Kerberos libraries as preinstalled in KRB4DIR. Generally not used now that the V4 libraries are included.
--without-afs: The default, indicating that you don't have AFS libraries to build with and therefore can't build asetkey, aklog, and kascvt.
--with-afs=AFSDIR: Use preinstalled AFS library tree located under AFSDIR to build the TransArc AFS support and conversion tools. These require V4 compatibility to operate, and work in conjunction with krb524d.
--enable-popmail: Build popmail tools.
--disable-popmail: Do not build popmail tools. This is the default.
--enable-minimal-ftp: Build only the minimal ftp client. This is deprecated, and should not be necessary with the current `ftplib'.
--disable-minimal-ftp: Build the complete ftp client. This is the default.
--enable-des-cbc-md5: Enable the des-cbc-md5 encryption type. This is the default.
--disable-des-cbc-md5: Disable the des-cbc-md5 encryption type.
--enable-des3-cbc-sha: Enable the des3-cbc-sha encryption type. This is the default.
--disable-des3-cbc-sha: Disable the des3-cbc-sha encryption type.
--enable-des-cbc-raw: Enable the des-cbc-raw encryption type. This is the default.
--disable-des-cbc-raw: Disable the des-cbc-raw encryption type.
--enable-des3-cbc-raw: Enable the des3-cbc-raw encryption type. This is the default.
--disable-des3-cbc-raw: Disable the des3-cbc-raw encryption type.
--enable-des-cbc-cksum: Enable the des-cbc-cksum encryption type. This is the default.
--disable-des-cbc-cksum: Disable the des-cbc-cksum encryption type.
--enable-crc32: Enable the crc32 encryption type. This is the default.
--disable-crc32: Disable the crc32 encryption type
--enable-rsa-md4: Enable the rsa-md4 encryption type. This is the default.
--disable-rsa-md4: Disable the rsa-md4 encryption type.
--enable-rsa-md5: Enable the rsa-md5 encryption type. This is the default.
--disable-rsa-md5: Disable the rsa-md5 encryption type.
--enable-nist-sha: Enable the nist-sha encryption type. This is the default.
--disable-nist-sha: Disable the nist-sha encryption type.