$Id: README,v 1.13 2003/03/18 18:43:04 kenh Exp $

This is the README for version 2.0 of the NRL AFS-Kerberos 5 migration kit.

Please note this is an UNOFFICIAL kit, and none of the procedures or
code contained within are endorsed by MIT, the OpenAFS Elders, or the
Postmaster General.  Consider yourself warned.


INTRODUCTION
------------

Welcome to the README for the NRL AFS-Kerberos 5 migration kit.  The purpose
of this kit is to aid people who wish to migrate an AFS cell from the
Transarc KA server to a Kerberos 5 server.

Why would you wish to do this?  For a couple of reasons:

- Having one Kerberos database is a lot easier to maintain than two Kerberos
  databases (if you decided to run the Transarc KA server and a Kerberos 5
  server, for example).

- Kerberos 5 clients tend to be more secure.

- While you can use Kerberos 4 clients with a Kerberos 5 server, the
  reverse is not possible.

- Kerberos 5 has some nifty features, like forwardable tickets, that are
  extremely desirable.

The code and directions contained herein have been developed here at
NRL, MIT, ANL, CMU, and other places.  My hope is that this will aid
other sites that wish to transition their AFS cell to Kerberos 5.

Please note that all of the code herein was developed with MIT Kerberos 5
Release 1.2, and will probably not work with earlier releases, nor with DCE
(actually, it _might_ work with DCE, but I have no way or interest in
testing it with DCE).


TABLE OF CONTENTS
-----------------

The following is a list of files included with this kit, and a brief
description of their function:

    README	- This file.  Includes package overview and instructions.

    COPYRIGHT	- Descriptions of all relevant copyright information.

    THEORY	- The theory behind the migration kit, in high-level terms.

    ISSUES	- Issues that are important to understand before you
		  perform a site migration to Kerberos 5.

    KERBEROS-ADDITIONS -
		  Documentation about the things that "monster-patch"
		  adds to Kerberos 5.

    AFS_K5_NAME_CHANGE -
		  Documentation on how to run your site with a different
		  AFS cell name than your Kerberos realm.

    patches     - A directory containing patches to apply to a vanilla
    		  Kerberos 5 1.0.6 release tree.  Currently this directory
		  contains one file: "monster-patch"

    src		- A directory containing various migration programs
		  and utilities (more detail below).

    xdm		- A directory containing a V5-aware XDM, based on the
		  MIT X11R6.3 distribution.  This also includes the
		  3D shadow hilighting patch, and modifications to
		  work with multi-line messages.  It has been modified
		  to work as a replacement for XDM on Irix systems.

    Previously, the migration kit used to include "xlockmore", but the
    Kerberos-specific changes to xlockmore have been folded back into
    the xlockmore distribution.

Under the "src" directory, the following programs are included:

    afs2k5db	- This is a program that converts an AFS KA database
		  into a MIT Kerberos 5 database.  Given the .DB0
		  file from the KA database, it will convert it
		  into a MIT Kerberos 5 dump file, which you can
		  load into your database using "kdb5_util".

    asetkey	- This is a version of the "asetkey" program from MIT, but
		  updated to use the Kerberos 5 keytab routines.  This is
		  used to extract the AFS service key from a V5 keytab
		  and put it into the AFS KeyFile.  You can also use it
		  to manipulate the KeyFile, a la "bos {add/list/remove}key"

    aklog	- This is a version of "aklog", which has been modified
		  to work with V5 by Doug Engert of ANL.  It has been
		  further modified by me to work with cross-cell
		  authentication (and to automatically create PTS entries
		  in foreign realms if you so desire).

    fakeka	- This is a "fake" KA server which understands just enough
		  of the KA RX protocol to make "klog" work.  It was
		  originally developed by Jeffrey Hutzelman of CMU for
		  Kerberos 4, and modified for Kerberos 5 by me.  Note
		  that MIT Kerberos 5 versions 1.3 and later will ship
		  with a version of fakeka; you should use that version
		  in preference to the one provided here.

    ka-forwarder - This is a program to forward KA requests from your AFS
		  database servers to your V5 KDC (if you aren't running
		  your KDC on the same hosts as your database servers).
		  It is used in conjunction with "fakeka".

    keyfile_dump - This is a program to take an AFS KeyFile and create a file
		  that can be loaded into the KDC with "kdb5_util load".
		  You can use it to convert an AFS KeyFile to something
		  the KDC can understand instead of extracting out an
		  AFS service key and placing it in the KeyFile.
		  Contributed by Matt Crawford of Fermilab.

MIGRATING YOUR SITE: THE DETAILS
--------------------------------

These are (roughly) the steps that our site used to successfully
migrate from an AFS KA server to a V5 KDC.  While it is strongly
recommended that you follow them in the order listed, it's not required
in all cases.  If you feel confident that you understand the issues
involved, then you are free to rearrange the order (it's not like I
could really stop you, now could I?)  Steps that _are_ order dependent
are noted.

Note that as outlined, this entire migration process could take from
a few weeks to a few months.  It is designed to be as gradual and as
painless as possible.


STEP ONE: PREP WORK
-------------------

First off, READ THE ANCILLARY DOCUMENTATION!  By this, I mean the
THEORY and ISSUES file included with this distribution.  I _cannot_
stress this enough.  You should first decide if this migration is
even appropriate for your site before you invest any time in it.
The more you understand about how this migration actually works,
the smoother it will go.

If you _didn't_ understand all of the stuff in the THEORY and ISSUES
file, then you can come back to it later.

STEP TWO: BUILD KERBEROS 5
--------------------------

Once you feel confident you understand the issues and theory regarding
this kit (or not), download the Kerberos 5 distribution from:

ftp://athena-dist.mit.edu/pub/kerberos

Following the directions included with the Kerberos 5 distribution,
compile it for all of the architectures you wish to support.

NOTE: You may or may not want to apply the so-called "monster-patch"
included in the "patches" subdirectory, but it is NOT required.  It
merely makes things easier when using AFS with Kerberos 5.  The file
"KERBEROS-ADDITIONS" documents the additions that the monster-patch
provides.  You may wish to hold off and test Kerberos first, and _then_
apply the monster patch once you have Kerberos working.

The current version of the monster patch is designed to be applied to
Kerberos 5 Release 1.2.7.  If you need a patch for a different version
of Kerberos, please contact the me (kenh@cmf.nrl.navy.mil) and I'll
try to help you out.

AN ADDIOTIONAL NOTE ABOUT THE MONSTER-PATCH

My eventual goal is to incorporate all of the AFS-related changes into the
MIT Kerberos 5 distribution.  Many of these changes will already be in
the Kerberos 1.3 release.

When applying the monster-patch, feed it into the root of the Kerberos
source tree (called KRB5SRCDIR for short).  For instance:

% cd $KRB5SRCDIR
% patch < monster-patch

You should have only three rejected patches for the following files:

kadmin/server/kadm_rpc_svc.c
lib/kadm5/srv/adb_free.c
lib/rpc/svc_auth_gssapi.c

All three of these patches are for RCS Log keywords, and can be
safely ignored.

This patch modifies many of the Kerberos configure.in templates,
so you will need to regenerate all of the "configure" files using
$KRB5SRCDIR/util/reconf.  Before you run reconf, be sure to build the
included "autoconf" in $KRB5SRCDIR/util/reconf (you cannot use a stock
"autoconf" with "reconf" -- the included autoconf has been specially modified
to work with the Kerberos build system).  For instance:

% cd $KRB5SRCDIR/util/autoconf
% ./configure
% make
% cd $KRB5SRCDIR
% util/reconf --force

When using the monster-patch, be sure to use the --with-afs flag to
"configure" as this enables most of the AFS compatibility features.

Even if you don't apply the monster-patch, you should specify the
--with-afs option regardless, as this adds in some limited AFS
compatibility.  You should also be sure to build with --with-krb4 (it's
the default, but some of the migration kit depends on it).

STEP THREE: TEST KERBEROS 5
---------------------------

Once you have Kerberos 5 compiled, you should then follow the Kerberos
5 install guide and bring up a test KDC.  You can name your test realm
anything you want, but you can't change the database realm name once
you create it, so it might be a good idea to create one that's the same
name as your AFS cell (but all uppercase, of course).

Don't try to do anything with AFS at this point; just see if you can
get the Kerberos basics working.  Make sure Kerberos "telnet"/"rlogin" work,
forwarding your tickets, you understand how to administrate your
database, extract host keys, etc etc.  A good understanding of Kerberos
5 is important for the steps to come.

If you didn't understand the ISSUES and the THEORY file, now might be
a good time to reread them and see if they make more sense.

Once you feel confident with Kerberos 5, you might want to take some
time and organize your Kerberos setup.  Plan out where the binaries are
going to live (we put everything in /usr/krb5), who is going to
administrate your Kerberos database, how many (if any) backup KDC's you
are going to have, etc etc.

STEP FOUR: TEST AFS WITH KERBEROS 5
-----------------------------------

This is where the interesting stuff starts happening! (Finally)

Compile (if you haven't already) the software found in "src".  It uses
GNU Autoconf and should be fairly straightforward.  Extra options to
configure are:

--with-krb5=PATH	Location of the Kerberos 5 libraries and
			include files.  This option assumes
			that the libraries live in PATH/lib, and
			the include files live in PATH/include.
--with-afs=AFSDIR	Location of the AFS dest tree.  This option
			also assumes that libraries are in
			AFSDIR/lib and include files are in
			AFSDIR/include.
--with-krb5-src=DIR	The location of the Kerberos source tree
			(needed to build "afs2k5db")
--with-krb5-obj=DIR	The location of the Kerberos build tree,
			if different from the source tree.  Also
			needed to build "afs2k5db".

If you built Kerberos in the same directory as the source for it,
only use the --with-krb5-obj flag.

Once you've built the software, you will want to test out the included
V5 "aklog".  To do this, do the following things: (Note!  These are order
dependent).

1) Create an AFS principal in the Kerberos database.  Call it:

	afs@YOUR.CELL.NAME

   The password doesn't matter; it will be changed.  Use "modprinc" to
   give it a kvno that is the _same_ as the highest kvno in your
   AFS KeyFile, e.g.:

	% ./asetkey list
	kvno    3: key is: ...
	kvno    5: key is: ...
	All done.
	% kadmin.local -q "modprinc -kvno 5 afs@YOUR.CELL.NAME"

2) If you're not running it already, start "krb524d" on all of your
   KDC server machines.  This translates V5 tickets to V4 tickets, and
   is used by "aklog".  Unless you want to have to have the AFS key in a
   keytab on your KDC, add the "-m" option to krb524d when starting it up.

3) On your AFS update server (or wherever your master KeyFile is), use
   "kadmin" to extract the afs key into the keytab on that machine with
   the "ktadd" command:

	% kadmin
	...
	kadmin:  ktadd -k /etc/krb5.keytab -e des-cbc-crc afs@YOUR.CELL.NAME
	Entry for principal afs@YOUR.CELL.NAME with kvno 6, ... added to ...

   Note that "ktadd" actually _changes_ the key to a new random key
   and will increment the kvno, so the key that ends up in the keytab
   (and in the database) will have a kvno that is one higher than the
   highest kvno in your KeyFile, so there won't be a conflict.  Also
   note that make sure you that you're using a single-DES enctype
   (the -e des-cbc-crc option) is very important, since at this writing,
   AFS only supports single-DES.

4) Use the provided "asetkey" to copy the new AFS key from the
   Kerberos 5 keytab into the AFS KeyFile. E.g.:

	% ./asetkey add 6 /etc/krb5.keytab afs

   This would copy the key for the "afs" principal with a kvno of 6
   from /etc/krb5.keytab to wherever your AFS KeyFile is.

   Note that you don't need the afs key in the Kerberos 5 keytab after
   using "asetkey", so you can remove it from there if you wish:

	% kadmin
	...
	kadmin:  ktremove -k /etc/krb5.keytab afs@YOUR.CELL.NAME all

5) Once the new KeyFile is distributed to your AFS servers,
   authenticate to Kerberos 5 using "kinit", and try running "aklog".
   If all goes well, then it _should_ give you an afs@YOUR.CELL.NAME
   token (check this with "klist").  Try actually reading/writing some
   files with that token to make sure it works correctly.

   If you get a Kerberos 5 error at this point, you will have to try
   to diagnose what the problem is based on the error you are
   getting.
   
   If you get a strange rxkad error when you try to use your token,
   use "translate_et" to find out the error message that corresponds
   to that number, and go from there.  The most common error at this
   point is a mismatch of kvno's between the V5 database and the
   AFS KeyFile.  Use "kadmin/getprinc" and "asetkey list" to check.

If all _THAT_ works, then give yourself a big pat on the back, because
you've done the hard part!

STEP FIVE: TEST USER MIGRATION
------------------------------

Note: If you're not migrating your users from an AFS KA database, then
you can skip this part.

Now that you've proven that you can use a V5 "aklog" to successfully
authenticate to AFS, you should now verify that you can migrate your
users over without having to change their passwords.

You will use the supplied "afs2k5db" tool to do this.  "Afs2k5db" takes
the following options:

	-m		Prompt for the master key, instead of reading it from
			the stash file.
	-r realm	Use realm "realm" instead of the default as the
			default salt data.
	-l lifetime	Use "lifetime" as the maximum ticket lifetime
			instead of the lifetime in the KA database.
	-k kvno		Use "kvno" as the key version number instead of
			the kvno in the KA database.

To convert your database, you will either need to move the KA database
over to your KDC, or use the -m flag and input the KDC master key.  If
you move the KA database to the KDC, you should insure that it is
encrypted during transit.

Either way, you will need to use the kaserver.DB0 file usually found in
the /usr/afs/db directory.  By default, "afs2k5db" converts all of the users
in your database, but you can give a list of users to convert instead.

For this test, you'll probably want to just convert one.  Use "afs2k5db"
to convert one user (whom you know the password), with a command-line
similar to this:

% afs2k5db ./kaserver.DB0 testuser > testuser.out

This will place a dump file in "testuser.out" that contains the V5 record
for this user.  Note: a "short read" at the end of the database is normal
and is nothing to be worried about.

Before you go any further, MAKE A BACKUP OF YOUR KDC!  Use "kdb5_util dump"
to dump the database just in case something happens.

Next, use "kdb5_util load" to load in the record for your test user.  YOU
MUST USE THE -update OPTION OR YOU WILL TRASH YOUR DATABASE!  Using the
-update option will tell kdb5_util not to delete the current database
before it loads in your record, and this is critical.  For instance:

% kdb5_util load -update -verbose testuser.out

Once you've successfully loaded this user into your Kerberos database,
you should be able to run "kinit" with the user's original password
without any problems.

STEP SIX: TEST FAKEKA (OPTIONAL)
--------------------------------

If you decide that you need the ability to have clients still use the old
AFS KA-based authentication protocol (including allowing access from other
cells), then you will need to run "fakeka" and optionally "ka-forwarder".
However, testing "fakeka" will require some AFS "kaserver" outage, so plan
this according to the needs of your site.

Before beginning actual testing, shut down the "kaserver" instance
temporarily on each AFS database host:

% bos shutdown <AFS server> kaserver

"Fakeka" is always run on your KDC, since it needs access to the
database.  Always start it up with the "-m" option (it will fork itself
and place itself into the background).  For reliability, you should run
it on all of your KDC's (including slaves).

If your KDC's are on the same hosts as your database servers, then
there's nothing else you need to do.

If your KDC's are _not_ on the same hosts as your database servers,
then you'll need to run "ka-forwarder" on your database servers.

The syntax for running "ka-forwarder" is as follows:

% ka-forwarder kdc1 [kdc2 ...]

You'll need to run this on all database servers.

When you use "ka-forwarder", you'll need to add a corresponding -f option
to "fakeka".  The syntax for "fakeka" in this case is:

% fakeka -m -f dbhost1 [-f dbhost2 ...]

The reason for the -f option is that "ka-forwarder" adds the originating
host to the end of the packet, and "fakeka" needs to be able to know when
a request has been forwarded to it or not.

Once you have "fakeka" and optionally "ka-forwarder" running, test out
using "klog" with principals in your V5 KDC.  You should be able to
"klog" with your original password.  Note that you will need to use
it on a principal that has either a V4-style or AFS-style key --
it won't work with a V5 key.

If you have problems, look at the syslog information put out by "fakeka"
and "ka-forwarder", which goes to the "daemon" facility.

STEP SEVEN: THE DREADED MIGRATION
---------------------------------

At this step, you should have verified that all of the pieces work
independently.  Now it comes time to put them together.

Unfortunately there is no good cookie-cutter set of directions I can
give at this stage, since a lot of this is heavily site-dependent.
Here are the steps we took; I hope it is of some use to you.

1) First, I converted my desktop machine to completely Kerberos 5.
   All incoming services were Kerberos, and I replaced "login"
   with "login.krb5".  I altered my path so I used the Kerberos
   binaries instead of the system ones.

2) I added Kerberos "rlogind"/"rshd" on a few of our server machines, and
   added Kerberos "telnetd" on an alternate port, all per the Kerberos
   installation instructions.

3) I tested this out for a few weeks to see what kind of usability
   problems I would encounter, and to make sure all of the things that
   I normally did I could still do.

4) I had a few other knowledgeable people do the same thing on their
   desktops to widen the coverage.

5) Once I was confident that there were no significant usability problems,
   we announced to our users the conversion date, and explained the
   changes that they would encounter.  We also explained that there would
   be some AFS server outage during the switchover.

6) The first step we took on the actual migration date was to shutdown
   the "kaserver".

7) We then ftp'd the database over (using Kerberos "ftp" with encryption)
   to the KDC, and we used "afs2k5db" to convert the database over.

   Note for this step: you probably don't want to convert _all_ principals
   over (like the krbtgt, afs, and the AuthServer principals).  Since
   the file that is output by "afs2k5db" is an ASCII file with each line
   as a record, we simply edited it and deleted the entries we didn't
   want to convert, such as:

	AuthServer/Admin@YOUR.CELL.NAME
	krbtgt/YOUR.CELL.NAME@YOUR.CELL.NAME
	afs@YOUR.CELL.NAME
	admin@YOUR.CELL.NAME

8) We then brought up "fakeka" on the KDC and created a special "ka-forwarder"
   instance in "bos" on the database servers:

	% bos create <AFS server> ka-forwarder \
	  simple /usr/krb5/sbin/ka-forwarder

   This made KA authentication requests start working with our V5 KDC.
   The total outage time was only approximately five minutes.

9) For the rest of the day the administrators went around and placed
   host keys on all of the machines, placed the Kerberos client binaries
   on all machines, and modified all of the inetd.conf files to point
   to the Kerberized services.  Since at this stage both AFS and Kerberos 5
   authentication worked, we had no further service outages.

And we all lived happily ever after ...

FILLING IN THE GAPS
-------------------

Once you have accomplished the Dreaded Migration, you will no doubt want
to start migrating all of your programs that use the AFS KA_* based
authentication routines to Kerberos 5.  Two such programs like this
are xdm and xlock.

Included with this kits are Kerberos 5 aware versions of xdm and xlockmore.
(I know both of these programs claim to support Kerberos 5 already, but
IHMO the Kerberos 5 support in both of these programs is badly broken).

Xlockmore should be relatively simple to compile and install; modify
the Imakefile appropriately and compile it in the normal way.

The XDM that is included with this kit was originally based on the
XDM that comes with X11R6.3, but has some substantial modifications.  It
includes the "3D" shadow box code, support for multi-line messages in
the login banner, and displays a picture of Kerberos on the login banner.
It also contains the right magic to make it serve as a replacement
for XDM under Irix.

An additional note about XDM: If you leave in the default -D switch that
defines NRL, it will place X server magic cookies in ~/private/.Xauthority
instead of ~/.Xauthority.  This is designed for AFS sites that want
the top level of user directories world-readable, but want to keep
X server keys private.  If you choose to use this, you will need to
modify the XDM startup files so that they set the XAUTHORITY environment
variable to the right value.

ADDENDUM: AFS WITH CROSS-CELL AUTHENTICATION
---------------------------------------------

As mentioned elsewhere, it's possible to do cross-cell authentication
with the V5 and make it work with AFS.  Here's how that works.

1) First, set up the V5 cross-realm authentication.  This is unfortunately
   poorly documented, but it's actually quite simple.  On each realm, you'll
   need to create two principals:

   krbtgt/REALM.ONE@REALM.TWO
   krbtgt/REALM.TWO@REALM.ONE

   Make sure that the corresponding principals have an identical kvno and
   key.  Both copies of krbtgt/REALM.ONE@REALM.TWO have to be the same,
   but krbtgt/REALM.ONE@REALM.TWO and krbtgt/REALM.TWO@REALM.ONE do not.

   Note that two principals are needed to do cross-cell authentication
   both ways.  If you are only authenticating one way, then you only
   need to create krbtgt/FOREIGN.REALM@LOCAL.REALM.

2) Once this is setup, test out cross-cell authentication just using
   the V5 programs.  You should be able to telnet to their site and
   automatically login to accounts there (it will require appropriate
   entries in your .k5login file).

3) Once V5 cross-cell is working correctly, you will need to setup the
   AFS component.  When using cross-cell authentication with AFS, you
   will appear to the AFS server as "user@your.original.cell" (note
   that in this case, the cell name is lower case).  Thus, you will
   need to create PTS entries for "user@your.original.cell" and
   add this user to the appropriate ACL's.  Foreign PTS users are
   _not_ members of system:authuser (since that's for people in the
   local cell only).

4) The recommended way to handle the creation of these users is have
   it done automatically.  If you create a PTS group called
   "system:authuser@your.original.cell" (in the foreign PTS cell, of
   course), _and_ you give it a non-zero group quota, aklog will
   automatically create those cross-cell entries when it finds that
   they don't exist.  The foreign PTS user will also automatically
   be added to "system:authuser@your.original.cell" when they
   are created in this manner.  Every time a user is created in this
   way, the group quota for the cross-cell PTS group is decremented
   by one.

If you create your cross-cell PTS users by hand, it is recommended that
you add them to "system:authuser@your.original.cell" as well, as that
is a useful convention.

EPILOGUE
--------

I hope this kit was of some use to you.  I am happy to answer questions
or help you with problems you have with this kit.  However, there is no
support available for this kit, so while I will try to help as much as
I can, I cannot promise to solve all of your problems.

My most sincere thanks go to:

- Doug Engert of ANL for making available his V5 aklog.
- Jeffrey Hutzelman of CMU for providing fakeka (a lifesaver!) and
  making sure I didn't do anything stupid when I converted it to V5.
- Von Welch of NCSA for testing out a prerelease of this code,
  providing bug fixes and enhancements, and doing the great work
  on the realm name change code.
- John Jackson of Purdue for feedback on this documentation and a
  bunch of typographical fixes.
- Matt Crawford for a bunch of fixes to the MIT codebase (especially the
  cracklib cleanup!)

Questions, comments, suggestions, bug fixes, fan and hate mail can be sent to:

Ken Hornstein
Naval Research Laboratory
kenh@cmf.nrl.navy.mil

9/24/99
