[krbdev.mit.edu #2559] Replacement Text Explaining [capaths] for Admin Guide

[Ken Raeburn via RT]

Looks quite good.  This is mostly nitpicking...

> [capaths]
>
> In order to perform direct (non-hierarchical) cross-realm 
> authentication,
> a database is needed to specify the authentication paths between the
> various source and destination realms. This section defines the 
> database.
>
> The database is used for different purposes by a Kerberos client and
> a Kerberos server (kdc and application server).

Uppercase "KDC".  I'd use "or" instead of "and"; by "Kerberos server" 
we mean either one, not a combination of both.

>   The client uses the
> capaths to determine

"the [capaths] section", or something like that.

> The database defines for each source and destination pair an ordered 
> list
> of intermediary realms

"sequence" might be simpler than "ordered list"; perhaps "describes" or 
"indicates" rather than "defines", but maybe "defines" is good too.

>  which represent cross realm relationships.  The
> authentication paths specified in the database are unidirectional.
> Each direction of a bidirectional path must be specified separately.

Can this be said in somewhat plainer language?

> The best way to explain how to construct the database is to show by 
> example.

Yes, but a small example to start with would be better.

> The realms ANL.GOV, PNL.GOV, and NERSC.GOV all wish to use the ES.NET 
> realm
> as an intermediate realm.  TEST.ANL.GOV is a sub realm of ANL.GOV 
> which must
> authenticate with NERSC.GOV but not PNL.GOV.

What's a "sub realm"?

Yes, I know what you mean.  In the context of capaths specs, the 
hierarchical relationship seems moot.  And I could be wrong, but I 
don't think we've introduced the term "sub realm" before.  You can use 
it, but I'd put it in quotes.

We might want to switch to .EXAMPLE names or FOO/BAR/etc, so it 
couldn't be inferred that we're describing the way certain real US 
government installations' policies work.  Or if we keep the names, 
start with "Assume that...."

>                                      NERSC.GOV
>                                     /
>                                    /
>   TEST.ANL.GOV -- ANL.GOV -- ES.NET
>                                    \
>                                     \
>                                      PNL.GOV
>

Oooh, ASCII graphics.  What fun we'll have formatting that. :-)

> Enumerating the desired relationships results in the following table.
>
>
>   Client                                   Service
>  Principal      Intermediary              Principal
>   Realm            Realms                   Realm

I'd suggest swapping the last two columns.  Client and service realms, 
or specifically successful communication between them, are the desired 
result that the reader would start with, and the intermediate realms 
are the result of checking the graph.

>   TEST.ANL.GOV    ANL.GOV     ES.NET      NERSC.GOV

A comma-separated list with three more widely separated columns might 
be a little clearer.

>  From the table we can then produce the [capaths] sections for each of
> the five realms.  The section consists of a separate subsection for 
> each
> client principal realm.  Within each subsection are one or more entries
> for each destination realm specifying the intermediate realm(s) used
> on the path.  A path with no intermediary realms is indicated by the
> symbol "." (period).
>
> The [capaths] section for ANL.GOV systems would look like this:

I'd suggest starting with a small example or two, perhaps going from 
TEST to NERSC and TEST to ANL since it'll demonstrate both the use of 
"." and the use of a multiple intermediate realms.  List the 
intermediate realms, and show just that tiny set of entries from the 
config file.  Perhaps with some tedious, redundant explanation of the 
ordering of entries and what tickets will be acquired.  Then, once 
we've taken the reader through the construction of some config file 
entries, go into the full config data for each realm, with less 
explanation.

> In the above [capaths] sections, the ordering of the destination realm
> values
> are not important except when the same destination realm is used more
> then once
> to specify a sequence of intermediary realms.  (Ordering is never
> important to
> the server since the transited realm field in the ticket is not 
> ordered.)

It's also the case that the server won't require that all the specified 
realms be used.

For the admin guide, I'd suggest talking about the mechanism rather 
than the ticket fields.  The server treats the list from the config 
file as the list of realms that are allowed for intermediate realms, 
and only needs to check whether any realms were used that are not in 
the permitted set.  That's the reason that the order doesn't matter, 
both for the server and in the protocol.  (So, really, if there are two 
possible paths that are considered acceptable, the server's config file 
should list all the intermediate realms from both paths, and the 
client's config file should describe one path, in order.  Ugh.)


> Client systems from which client principals issued by multiple realms
> are used
> must include the transited realm rules appropriate for each of the 
> client
> principals.
>
> The error message "Illegal cross-realm ticket" implies that a [capaths]
> section for the authentication path must be added to the server 
> machine.
> The error message "KDC policy rejects request" implies that the 
> [capaths]
> section on the server specifies an authentication path which does not 
> match
> the authentication path that was actually used.

We could also mention that the old MIT code had bugs in the transited 
path verification, causing the addition of the KDC-based policy check.  
(The protocol allows for the KDC to do a policy check and set a flag in 
the issued ticket; we simply refuse to issue the ticket if the check 
fails.  But we do now set the flag if it passes.)

Ken