$Id: ISSUES,v 1.8 1999/05/25 18:40:59 kenh Exp $

There are a number of issues that one should be prepared to deal with
before they attempt a cell conversion.  I have tried to cover all of
the ones I'm aware of here.


STRING TO KEY MADNESS
---------------------

It's important to understand that the database conversion tool _only_
is smart enough to extract keys out of an AFS KA database file and store
them in a format understood by a V5 KDC.  What it _cannot_ do is
convert the keys into V5-salted keys.

To understand the implications here, it's crucial to know that no
actual passwords are stored in a Kerberos database; only encryption
keys.  User passwords are converted to an encryption key by a function
known as "stringtokey()".  This algorithm is much like the unix crypt()
function in that it is designed to be one-way - it is (theoretically)
impossible to discover a plaintext password from the corresponding
encryption key.

What complicates this matter is that each version of Kerberos AND AFS
has a _different_ string to key function.  The same password will
generate different encryption keys in a V4, V5, and AFS database.

Fortunately, the V5 KDC stores with each encryption key the algorithm
used to generate that key.  That means that a V5 client can know which
algorithm to use when it has to convert a password to an encryption
key.  Thus, even though a migrated AFS database will contain keys
generated by the AFS string-to-key algorithm _instead_ of the V5
string-to-key algorithm, it can use the information provided by the KDC
to select the correct algorithm to use.

This functionality is already part of the MIT V5 release, and as a
result any client based on the MIT V5 release will handle AFS-style keys
correctly.  Some V5 implementations (Cisco routers are one case I'm
aware of) do _not_ handle this correctly.

Unfortunately, V4 clients are another matter completely.  Since AFS has
a fairly large installed base, some V4 clients will automagically try
the AFS string to key function if the V4 one didn't work.  For example,
KClient for the Mac will work with AFS-style keys ... but the MIT Kerberos
client for the PC will not.  The exact coverage is unknown, unfortunately.
You should test all of the V4 _and_ V5 services with AFS-style keys
_before_ you convert.  Even worse, while some of the AFS tools will
try the V4 salt algorithm if the AFS one fails, not all of them will
(emt is one example), so to maintain complete backwards coverage, you
will need to keep a V5, V4, and an AFS-style key around for each user.

The _only_ way to convert a key to one of a different type is to change
a user's password.  If you plan on supporting some V4 and/or AFS services,
you should configure your admin server to generate multiple keys for
new passwords.  You can do this via the "supported_enctypes" field in
your kdc.conf file.  Here's what mine looks like:

    supported_enctypes = des-cbc-crc:normal des-cbc-crc:v4 des-cbc-crc:afs3

I would suggest that you try to have your user's change their passwords
as soon as possible after the conversion date.  This isn't critical,
depending on your site; if you just use AFS and the supplied tools, it
won't be a problem.

Note that the conversion tool provided blindly assumes that all of your
keys in your AFS database are AFS-style keys.  If you have V4 keys in your
AFS KA database, you will need to modify "afs2k5db".  If you have a mixture
of V4 and AFS-style keys ... you're on your own :-/


FAKE KA SERVER
--------------

As discussed in the THEORY file, AFS programs use the RX protocol to
communicate with the AFS KA servers for authentication.  Since this
protocol is non-standard and specific to AFS, the MIT KDC doesn't
implement it.

This isn't a problem for the normal case; once you've converted your
clients over, you'll be using a V5-aware "aklog" that talks to your V5
KDC.  However, this breaks people who are using "klog" off-site, as well
as any other native AFS tools that talk to the KA server.

To support these users, included with this kit is a server which
emulates enough of the KA protocol to make authentication requests
work.  It is called "fakeka".  It was developed originally at CMU to
work with a V4 KDC; I modified it to work with a V5 KDC.

This "fakeka" server runs on the same host as your KDC (it needs access
to your KDC database) and can decode just enough of the AFS RX packet
to make "klog" work correctly.  I have modified it enough so that it
will also make CMU's "emt" and "adm" daemons work with it.  It _cannot_
make AFS "kpasswd" work correctly; you should have all users change their
passwords with the V5 "kpasswd".

It's worth noting that "other native AFS tools" which will stop working
include things like "kas" (you'll use "kadmin" instead) and "uss" (which
needs to talk to the KA server).  So you'll probably need to retrofit
your account creation process as well.


CROSS-CELL AND AFS
------------------

(Note - this section only applies when using cross-cell authentication)

With the improved cross-cell support in V5, it's only natural that you
would want to use this with AFS.  This _is_ possible, and it works fine;
but it may not be what you expect.

When using cross-cell authentication, you are identified as
"user@YOUR.REALM" in the foreign realm.  In other words, if you
authenticate as "user@YOUR.REALM", and then use a service in
FOREIGN.REALM, then you will appear as "user@YOUR.REALM" to
applications in FOREIGN.REALM.

This is already a known behavior of Kerberos.  To let other people
log into your account, you just add them to your ~/.k5login file.  Thus,
if you have an account in FOREIGN.REALM, you will want to add
"user@YOUR.REALM" to the .k5login file in your home directory on
your account in FOREIGN.REALM, and you will be permitted to login
to that account.  But AFS is another story.

When authenticating to a foreign realm, you will appear as
"user@your.realm" (note all lower case) to the file server and the
protection database.  If a PTS entry does not exist for
"user@your.realm", then you will not be able to access any protected
files.  Regardless, since your credentials will _not_ be the same as
your primary userid in that cell, by default you won't be able access
your files, since you are (to AFS at least) a completely different
user.

The basic solution is to create a "user@your.realm" PTS entry in the
FOREIGN.REALM cell, and give it the same ACL's to your files as you do
for your regular account.  A cell can be configured so that the
accounts are created automatically by "aklog" (see the README for more
details).  If you only plan on accessing this realm via cross-cell, you
can make the "user@your.realm" PTS entry be the only entry associated for
your account.

It's worth noting that once you migrate your site to V5, you'll only be
able to use cross-cell authentication with other sites who have
migrated to V5 as well (it _might_ work with sites using a V4 KDC, but
it will be tricky).  If you want to do cross-cell with other sites who
are using AFS KA servers, you'll have to do some hacking on "fakeka".


A REALM BY ANY OTHER NAME ...
-----------------------------

You may want to have a different realm name than your AFS cell name.
This is _possible_, but tricky, and I don't recommend it.  But if you're
curious ...

The basic problem is that the principals in AFS are salted with the
cell name (actually, the Kerberos realm name of your AFS cell, which
is just the cell name uppercased).  When the client utilities create
the encryption key from your password, the wrong salt will be used,
and the wrong key will be generated.

There is room in the KDC to store the name of an alternate salt.  By
default, "afs2k5db" will store the name of the current realm in the
database, but you can change this with the "-r" option.  Thus you
can give the name of the Kerberos realm of your AFS cell to "afs2k5db"
and it will be stored in the database.

There is code in the monster patch to deal with these issues correctly.
This code was developed by Von Welch at NCSA, who runs their site in
in this configuration.  The file AFS_K5_NAME_CHANGE explains the issues
and the procedures necessary to run your site this way.
