[krbdev.mit.edu #8505] krb5.conf(5): documentation of auth_to_local unclear and ambiguous

[Markus Kuhn via RT]

The krb5.conf(5) man page currently says:

    [realms]
        Each tag in the [realms] section of the file is the name of a  Kerberos
        realm.  The value of the tag is a subsection with relations that define
        the properties of that particular realm.  For each realm, the following
        tags may be specified in the realm's subsection:
        [...]

         auth_to_local
               This tag allows you to set a general rule for mapping  principal
               names  to  local user names.  It will be used if there is not an
               explicit mapping for the principal name  that  is  being  trans‐
               lated.

At no point does the manual page say, what meaning the tag in the [realms]
section has in the context of auth_to_local, i.e. how the realm tag affects
under which condition the specifiedauth_to_local rule is applied.

In other words, if I have in krb5.conf something like

[realms]
    REALM1.COM = {
        auth_to_local = ...
    }
    REALM2.COM = {
        auth_to_local = ...
    }

please explain more clearly under which condition the first or the second
auth_to_local tag is applied.

If a client user A at REALM1.COM connects to a server B at REALM2.COM, and I want to
use auth_to_local to translate A at REALM1.COM into a local user A, do I have to
place that auth_to_local tag in a subsection

    REALM1.COM = { auth_to_local = ... }

or

    REALM2.COM = { auth_to_local = ... }

Is the realm tag here the one of the client principal in the ticket, or
the one of the server principal in the ticket, or even just the
default_realm of the server?

It would be great if the krb5.conf man page answered that question
in a clear manner, in order to clarify the semantics of auth_to_local
in a cross-realm context.

One common use of auth_to_local is to allow users from other realms into
a server, as mentioned at

   http://superuser.com/questions/808461/cross-realm-kerberos-authentication-with-ssh

Unfortunately, the current krb5.conf doesn't document the semantics
currently clearly enough to make it obvious how to do that.

In addition: since auth_to_local uses regular expressions, it would be
most helpful if the documentation stated which of the many regular expression
languages out there is used (POSIX BRE/ERE/SRE, PCRE, etc.), with a
reference to its full documentation.

Thanks,

Markus

-- 
Markus Kuhn, Computer Laboratory, University of Cambridge
http://www.cl.cam.ac.uk/~mgk25/ || CB3 0FD, Great Britain