$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 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 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