$Id: THEORY,v 1.3 1997/03/28 19:25:40 kenh Exp $

KERBEROS WITH AFS 
-----------------

This file explains the theory behind running a Kerberos 5 KDC instead
of the Transarc "kaserver".  If you feel confident that you understand
all of this, feel free to skip this section.

Unfortunately, this document assumes some familiarity with the way
Kerberos works.  If you are even _considering_ migrating your site, you
should make sure you understand the theory presented herein, otherwise
you are setting yourself up for a MAJOR headache!

AUTHENTICATING TO AFS
---------------------

When you authenticate to AFS (either by running "klog", or entering your
password in at the login prompt), the following things happen:

- A Kerberos ticket-granting-ticket is requested from the "kaserver".

- The "kaserver" sends you a ticket granting ticket, encrypted with your
  secret key.

- Your password is converted to an encryption key, using the AFS string-to-key
  function.  Note that the Kerberos realm (in this case, your cell name)
  is used as a salt for the string-to-key function.

- Your ticket-granting-ticket is decrypted with your secret key (obtained from
  your password in the above step).

- The ticket-granting-ticket is sent to the AFS "kaserver" along with a request
  for an AFS ticket.

- An AFS ticket is sent back, encrypted with the session key from the 
  ticket-granting-ticket.

- The AFS ticket is decrypted, using the session key from the user's
  ticket-granting-ticket.

- The ticket-granting-ticket is discarded.

- The AFS ticket is installed in the kernel, and is used by the cache manager
  for authentication with the AFS fileserver.


AUTHENTICATION TO AFS WITH KERBEROS 5
-------------------------------------

Most of the same steps need to occur when using Kerberos 5, but a few things
are different:

- The AFS ka_* routines (used by "klog", AFS login, etc etc), use RX to
  communicate with the AFS "kaserver".  Normal Kerberos clients use the
  Kerberos protocol to communicate with the Kerberos server.

- Kerberos 5 uses separate programs to obtain the TGT and get the AFS
  ticket, and the TGT is preserved for future use.  In AFS only one program
  is used to get a TGT and an AFS ticket, and the TGT is discarded after
  the program exits.

- The default string-to-key function with MIT Kerberos 5 is not compatible
  with the AFS string-to-key.

- The ticket stored in the kernel is a Kerberos 4 ticket, which has a
  different format than a Kerberos 5 ticket.

So with these things known, here's a list of things that would happen
if you authenticated to AFS using Kerberos 5:

- User runs "kinit" or logs in via a Kerberos 5 login, and enters a password.

- A Kerberos 5 ticket-granting ticket is requested from the KDC.

- The KDC sends you a TGT, encrypted with your secret key.

- Your password is converted to an encryption key.  Note that the
  string-to-key function used is dependent on the salt type returned by
  the KDC.

- The key generated above is used to decrypt the TGT.

- The TGT is written into a file in /tmp, and "kinit" or "login" exits.

- User runs "aklog".

- Aklog takes the user's TGT out of the file in /tmp, and sends a request
  for an AFS ticket (using the previously mentioned TGT).

- An AFS ticket is sent back, encrypted with the TGT session key.

- Since this is a V5 ticket, send it to a Kerberos 5 to 4 daemon to have
  it converted to a V4 ticket (you cannot convert it yourself, since it
  needs to be encrypted with the AFS server key, which you do not know).

- Take the converted V4 ticket and store it in the kernel to be used by
  the AFS Cache Manager.

Fortunately, this can be made nearly transparent to your users.  The
patches included with this kit try to address some of these concerns.
For example, the patches give you the ability to configure "login" to
automatically run "aklog", thus freeing the need for the user to do so.

YES VIRGINIA, YOUR USERS CAN KEEP THEIR PASSWORDS
-------------------------------------------------

The anxious system administrator is no doubt wondering at this point, "Can
I migrate my current KA database to V5?".  The answer is, thankfully, "Yes!".
A database conversion tool is provided.  However, this is _only_ possible
because V5 already has support for the AFS string-to-key function built-in.
V5 clients will automatically know to use the proper string-to-key function
for users that still have AFS-salted keys.  There are some issues that
need to be dealt with w.r.t. this; the ISSUES file covers this in greater
detail.

SUMMARY OF THE CONVERSION PROCESS
---------------------------------

In a nutshell, to convert your AFS cell to use Kerberos 5, you have to:

- Migrate your KA database to your Kerberos 5 KDC.

- Store your AFS server key in your Kerberos 5 database.

- Shut down your KA servers.

- (Optional) - run the "fakeka" server in place of the KA server.

- Install Kerberos 5 everywhere.

- Switch all of your authentication methods (e.g. - "login", "ftp",
  "klog") to their corresponding Kerberos 5 counterparts.
