Projects/Local authorization pluggable interface

An announcement has been sent to krbdev@mit.edu starting a review of this project. That review will conclude on 2012-02-08.

Comments can be sent to krbdev@mit.edu.

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);
   
   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 module returns EPERM or another error, remaining modules will be skipped and krb5_kuserok will return false.

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.

If an2ln types is not set, but the an2ln method is implemented, the module's an2ln method will be consulted for all krb5_aname_to_localname operations, with type and residual set to NULL. If multiple modules implement an2ln without setting an2ln_types, the order in which they are consulted is not defined, except that all such modules will be consulted before the built-in mechanisms.

The free_string method will be used to return any local names returned by the an2ln methods. It is mandatory if an2ln is implemented.

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.

Rationale

We expect two different kinds of aname-to-lname modules:

• A module which implements a parameterized operation for auth_to_local processing, such as database support or an augmented version of rule processing. An administrator might register multiple modules of this type, and might invoke a module multiple times with different parameters. A module of this type would register one or more an2ln_types values.

• A module which wants to delegate all aname-to-lname processing to another system facility such as sssd. Most likely it would be unnecessary to register more than one module of this type, but the interface leaves open the possibility for a module to override only a segment of the principal namespace and return KRB5_PLUGIN_NO_HANDLE for other principals. A module of this type would leave an2ln_types as NULL.

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.