Projects/Local authorization pluggable interface

This is an early stage project for MIT Kerberos. It is being fleshed out by its proponents. Feel free to help flesh out the details of this project. After the project is ready, it will be presented for review and approval.

This project is targeted at release 1.12.

Description

This project adds a pluggable interface to affect the behavior of the krb5_kuserok() and krb5_aname_to_localname() functions.

Background

The krb5_aname_to_localname() function attempts to convert a krb5 principal name into a local account name according to policy. The default behavior maps single-component principals within the default realm to their values without realm (e.g. ghudson@ATHENA.MIT.EDU to ghudson, if ATHENA.MIT.EDU is the default realm). Its behavior can be modified through profile configuration as outlined below:

   [realms]
       DEFREALMNAME = {
           auth_to_local_names = {
               princname = localname
           }
           auth_to_local = RULE:[selstring](regexp)s/pattern/replacement/
           auth_to_local = DEFAULT
       }

The krb5_kuserok() function decides whether a principal name is authorized to control a particular local account name. The current implementation looks for a .k5login file in the local account's home directory and searches it for the principal name; if no .k5login file exists, authorization succeeds if krb5_aname_to_localname maps the principal name to the local account name.

Proposal

Since both operations are about the relationship of krb5 principals to local accounts, a single pluggable interface allows modules to affect either operation or both of them.

The pluggable interface will have four methods (plus initialization and finalization methods):

   krb5_error_code (*kuserok)(krb5_context context, krb5_localauth_moddata data,
                              krb5_const_principal princ, const char *lname);
   
   const char **an2ln_types;
   krb5_error_code (*an2ln)(krb5_context context, krb5_localauth_moddata data,
                            const char *type, const char *residual,
                            krb5_const_principal princ, char **lname_out);
   
   krb5_error_code (*an2ln_all)(krb5_context context, krb5_localauth_moddata data,
                                krb5_const_principal princ, char **lname_out);
   
   void (*free_string)(krb5_context context, krb5_localauth_moddata data,
                       char *str);

The kuserok method is optional. If it is implemented, it will be invoked for krb5_kuserok operations. It should return 0 if authorization is allowed, EPERM if authorization is authoritatively denied, KRB5_PLUGIN_NO_HANDLE if the module cannot determine whether authorization is allowed, and any other error code on a serious failure. krb5_kuserok will return true if at least one module returns success and all other modules return success or KRB5_PLUGIN_NO_HANDLE. If any modules return EPERM or another error, krb5_kuserok will return false. Remaining modules will be skipped if

an2ln_types is optional. If it is set, it contains a null-terminated array of uppercase string constants which act as type names. As krb5_aname_to_localname processes the auth_to_local values in the profile, any values with type strings matching a string in an2ln_types will result in calls to the an2ln method, with the residual string (or NULL if there is none) as an argument. The method should return 0 and set *lname_out if it can translate the principal, KRB5_PLUGIN_NO_HANDLE if it cannot, and any other error code on a serious failure. The an2ln method will be invoked multiple times if multiple auth_to_local values reference its types, if it returns KRB5_PLUGIN_NO_HANDLE on prior invocations.

The an2ln_all method is optional. If it is set, it will be consulted for all krb5_aname_to_localname operations. The method should return 0 and set *lname_out if it can translate the principal, KRB5_PLUGIN_NO_HANDLE to fall back to other mechanisms, and any other error code if it cannot. If multiple modules implement an2ln_all, the order in which they are consulted is not defined, except that all such modules will be consulted before the built-in mechanisms.

Module registration will fail (with a trace log message, but without disabling all kuserok or an2ln library operations) if it tries to register an already registered an2ln_types value or if it implements an2ln_all and a previous module already implements that method.

Testing

A test module will be added to plugins/localauth, to be built by default but not installed. A test harness and script will use the module to exercise the pluggable interface.

Documentation

A new page under doc/plugindev will document the pluggable interface. krb5_conf.rst will be amended to briefly describe the interface.

Release notes

Developer experience:

• Add a plugin interface to control krb5_aname_to_localname and krb5_kuserok behavior.