Difference between revisions of "Projects/Local authorization pluggable interface"

Revision as of 15:45, 31 January 2013

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.

The free_string method will be used to return any local names returned by the an2ln or an2ln_all methods. It is mandatory if either of those methods 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 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.