krb5 commit: Document localauth interface

[Greg Hudson]

https://github.com/krb5/krb5/commit/4aec0626fffea5d7e060979c2a4dc9555beae96a
commit 4aec0626fffea5d7e060979c2a4dc9555beae96a
Author: Greg Hudson <ghudson at mit.edu>
Date:   Fri Mar 1 13:12:19 2013 -0500

    Document localauth interface
    
    ticket: 7583

 doc/admin/conf_files/krb5_conf.rst |   35 +++++++++++++++++++++++++++++
 doc/plugindev/index.rst            |    1 +
 doc/plugindev/localauth.rst        |   43 ++++++++++++++++++++++++++++++++++++
 3 files changed, 79 insertions(+), 0 deletions(-)

diff --git a/doc/admin/conf_files/krb5_conf.rst b/doc/admin/conf_files/krb5_conf.rst
index 4c8f756..e326cf3 100644
--- a/doc/admin/conf_files/krb5_conf.rst
+++ b/doc/admin/conf_files/krb5_conf.rst
@@ -733,6 +733,41 @@ built-in modules exist for these interfaces:
 **encrypted_timestamp**
     This module implements the encrypted timestamp mechanism.
 
+.. _localauth:
+
+localauth interface
+###################
+
+The localauth section (introduced in release 1.12) controls modules
+for the local authorization interface, which affects the relationship
+between Kerberos principals and local system accounts.  The following
+built-in modules exist for this interface:
+
+**auth_to_local**
+    This module processes **auth_to_local** values in the default
+    realm's section, and applies the default method if no
+    **auth_to_local** values exist.
+
+**an2ln**
+    This module authorizes a principal to a local account if the
+    principal name maps to the local account name.
+
+**default**
+    This module implements the **DEFAULT** type for **auth_to_local**
+    values.
+
+**k5login**
+    This module authorizes a principal to a local account according to
+    the account's :ref:`.k5login(5)` file.
+
+**names**
+    This module looks for an **auth_to_local_names** mapping for the
+    principal name.
+
+**rule**
+    This module implements the **RULE** type for **auth_to_local**
+    values.
+
 
 PKINIT options
 --------------
diff --git a/doc/plugindev/index.rst b/doc/plugindev/index.rst
index 06d1754..548d23e 100644
--- a/doc/plugindev/index.rst
+++ b/doc/plugindev/index.rst
@@ -25,6 +25,7 @@ Contents
    ccselect.rst
    pwqual.rst
    kadm5_hook.rst
+   localauth.rst
    locate.rst
    profile.rst
    gssapi.rst
diff --git a/doc/plugindev/localauth.rst b/doc/plugindev/localauth.rst
new file mode 100644
index 0000000..8a87f3e
--- /dev/null
+++ b/doc/plugindev/localauth.rst
@@ -0,0 +1,43 @@
+.. _localauth_plugin:
+
+Local authorization interface (localauth)
+=========================================
+
+The localauth interface was first introduced in release 1.12.  It
+allows modules to control the relationship between Kerberos principals
+and local system accounts.  When an application calls
+:c:func:`krb5_kuserok` or :c:func:`krb5_aname_to_localname`, localauth
+modules are consulted to determine the result.  For a detailed
+description of the localauth interface, see the header file
+``<krb5/localauth_plugin.h>``.
+
+A module can create and destroy per-library-context state objects
+using the **init** and **fini** methods.  If the module does not need
+any state, it does not need to implement these methods.
+
+The optional **userok** method allows a module to control the behavior
+of :c:func:`krb5_kuserok`.  The module receives the authenticated name
+and the local account name as inputs, and can return either 0 to
+authorize access, KRB5_PLUGIN_NO_HANDLE to defer the decision to other
+modules, or another error (canonically EPERM) to authoritatively deny
+access.  Access is granted if at least one module grants access and no
+module authoritatively denies access.
+
+The optional **an2ln** method can work in two different ways.  If the
+module sets an array of uppercase type names in **an2ln_types**, then
+the module's **an2ln** method will only be invoked by
+:c:func:`krb5_aname_to_localname` if an **auth_to_local** value in
+:ref:`krb5.conf(5)` refers to one of the module's types.  In this
+case, the *type* and *residual* arguments will give the type name and
+residual string of the **auth_to_local** value.
+
+If the module does not set **an2ln_types** but does implement
+**an2ln**, the module's **an2ln** method will be invoked for all
+:c:func:`krb5_aname_to_localname` operations before the built-in
+mechanisms are applied, with *type* and *residual* set to NULL.  The
+module can return KRB5_LNAME_NO_TRANS to defer mapping to the built-in
+mechanisms.
+
+If a module implements **an2ln**, it must also implement
+**free_string** to ensure that memory is allocated and deallocated
+consistently.