krb5 commit: Document LDAP SASL configuration

[Greg Hudson]

https://github.com/krb5/krb5/commit/15b7e405ff7b62ab96af45999d1350455948e602
commit 15b7e405ff7b62ab96af45999d1350455948e602
Author: Greg Hudson <ghudson at mit.edu>
Date:   Mon Jun 16 13:15:33 2014 -0400

    Document LDAP SASL configuration
    
    Document the LDAP SASL profile tags and DB options.  For consistency,
    also condense the kdc.conf documentation for the two bind DN variables
    into one entry.
    
    ticket: 7944

 doc/admin/admin_commands/kadmin_local.rst   |   29 +++++++++++--
 doc/admin/admin_commands/kdb5_ldap_util.rst |   14 ++++--
 doc/admin/conf_files/kdc_conf.rst           |   60 ++++++++++++++++++++------
 3 files changed, 80 insertions(+), 23 deletions(-)

diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index e7e2d5a..8409303 100644
--- a/doc/admin/admin_commands/kadmin_local.rst
+++ b/doc/admin/admin_commands/kadmin_local.rst
@@ -162,13 +162,32 @@ Supported options for the LDAP module are:
     **-x binddn=**\ *bind_dn*
         Specifies the DN used to bind to the LDAP server.
 
-    **-x bindpwd=**\ *bind_password*
-        Specifies the password for the above mentioned binddn.  Using
-        this option may expose the password to other users on the
-        system via the process list; to avoid this, instead stash the
-        password using the **stashsrvpw** command of
+    **-x bindpwd=**\ *password*
+        Specifies the password or SASL secret used to bind to the LDAP
+        server.  Using this option may expose the password to other
+        users on the system via the process list; to avoid this,
+        instead stash the password using the **stashsrvpw** command of
         :ref:`kdb5_ldap_util(8)`.
 
+    **-x sasl_mech=**\ *mechanism*
+        Specifies the SASL mechanism used to bind to the LDAP server.
+        The bind DN is ignored if a SASL mechanism is used.  New in
+        release 1.13.
+
+    **-x sasl_authcid=**\ *name*
+        Specifies the authentication name used when binding to the
+        LDAP server with a SASL mechanism, if the mechanism requires
+        one.  New in release 1.13.
+
+    **-x sasl_authzid=**\ *name*
+        Specifies the authorization name used when binding to the LDAP
+        server with a SASL mechanism.  New in release 1.13.
+
+    **-x sasl_realm=**\ *realm*
+        Specifies the realm used when binding to the LDAP server with
+        a SASL mechanism, if the mechanism uses one.  New in release
+        1.13.
+
     **-x debug=**\ *level*
         sets the OpenLDAP client library debug level.  *level* is an
         integer to be interpreted by the library.  Debugging messages
diff --git a/doc/admin/admin_commands/kdb5_ldap_util.rst b/doc/admin/admin_commands/kdb5_ldap_util.rst
index 4516e04..cbf313f 100644
--- a/doc/admin/admin_commands/kdb5_ldap_util.rst
+++ b/doc/admin/admin_commands/kdb5_ldap_util.rst
@@ -273,7 +273,7 @@ stashsrvpw
 
     **stashsrvpw**
     [**-f** *filename*]
-    *servicedn*
+    *name*
 
 Allows an administrator to store the password for service object in a
 file so that KDC and Administration server can use it to authenticate
@@ -283,9 +283,15 @@ to the LDAP server.  Options:
     Specifies the complete path of the service password file. By
     default, ``/usr/local/var/service_passwd`` is used.
 
-*servicedn*
-    Specifies Distinguished Name (DN) of the service object whose
-    password is to be stored in file.
+*name*
+    Specifies the name of the object whose password is to be stored.
+    If :ref:`krb5kdc(8)` or :ref:`kadmind(8)` are configured for
+    simple binding, this should be the distinguished name it will
+    use as given by the **ldap_kdc_dn** or **ldap_kadmind_dn**
+    variable in :ref:`kdc.conf(5)`.  If the KDC or kadmind is
+    configured for SASL binding, this should be the authentication
+    name it will use as given by the **ldap_kdc_sasl_authcid** or
+    **ldap_kadmind_sasl_authcid** variable.
 
 Example::
 
diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst
index 9878266..6a05cc4 100644
--- a/doc/admin/conf_files/kdc_conf.rst
+++ b/doc/admin/conf_files/kdc_conf.rst
@@ -342,7 +342,15 @@ definitions of these relations.
 
 * **ldap_kerberos_container_dn**
 * **ldap_kdc_dn**
+* **ldap_kdc_sasl_authcid**
+* **ldap_kdc_sasl_authzid**
+* **ldap_kdc_sasl_mech**
+* **ldap_kdc_sasl_realm**
 * **ldap_kadmind_dn**
+* **ldap_kadmind_sasl_authcid**
+* **ldap_kadmind_sasl_authzid**
+* **ldap_kadmind_sasl_mech**
+* **ldap_kadmind_sasl_realm**
 * **ldap_service_password_file**
 * **ldap_servers**
 * **ldap_conns_per_server**
@@ -394,18 +402,41 @@ The following tags may be specified in a [dbmodules] subsection:
     This LDAP-specific tag indicates the number of connections to be
     maintained per LDAP server.
 
-**ldap_kadmind_dn**
-    This LDAP-specific tag indicates the default bind DN for the
-    :ref:`kadmind(8)` daemon.  kadmind does a login to the directory
-    as this object.  This object should have the rights to read and
-    write the Kerberos data in the LDAP database.
-
-**ldap_kdc_dn**
-    This LDAP-specific tag indicates the default bind DN for the
-    :ref:`krb5kdc(8)` daemon.  The KDC does a login to the directory
-    as this object.  This object should have the rights to read the
-    Kerberos data in the LDAP database, and to write data unless
-    **disable_lockout** and **disable_last_success** are true.
+**ldap_kdc_dn** and **ldap_kadmind_dn**
+    These LDAP-specific tags indicate the default DN for binding to
+    the LDAP server.  The :ref:`krb5kdc(8)` daemon uses
+    **ldap_kdc_dn**, while the :ref:`kadmind(8)` daemon and other
+    administrative programs use **ldap_kadmind_dn**.  The kadmind DN
+    must have the rights to read and write the Kerberos data in the
+    LDAP database.  The KDC DN must have the same rights, unless
+    **disable_lockout** and **disable_last_success** are true, in
+    which case it only needs to have rights to read the Kerberos data.
+    These tags are ignored if a SASL mechanism is set with
+    **ldap_kdc_sasl_mech** or **ldap_kadmind_sasl_mech**.
+
+**ldap_kdc_sasl_mech** and **ldap_kadmind_sasl_mech**
+    These LDAP-specific tags specify the SASL mechanism (such as
+    ``EXTERNAL``) to use when binding to the LDAP server.  New in
+    release 1.13.
+
+**ldap_kdc_sasl_authcid** and **ldap_kadmind_sasl_authcid**
+    These LDAP-specific tags specify the SASL authentication identity
+    to use when binding to the LDAP server.  Not all SASL mechanisms
+    require an authentication identity.  If the SASL mechanism
+    requires a secret (such as the password for ``DIGEST-MD5``), these
+    tags also determine the name within the
+    **ldap_service_password_file** where the secret is stashed.  New
+     in release 1.13.
+
+**ldap_kdc_sasl_authzid** and **ldap_kadmind_sasl_authzid**
+    These LDAP-specific tags specify the SASL authorization identity
+    to use when binding to the LDAP server.  In most circumstances
+    they do not need to be specified.  New in release 1.13.
+
+**ldap_kdc_sasl_realm** and **ldap_kadmind_sasl_realm**
+    These LDAP-specific tags specify the SASL realm to use when
+    binding to the LDAP server.  In most circumstances they do not
+    need to be set.  New in release 1.13.
 
 **ldap_kerberos_container_dn**
     This LDAP-specific tag indicates the DN of the container object
@@ -421,8 +452,9 @@ The following tags may be specified in a [dbmodules] subsection:
 **ldap_service_password_file**
     This LDAP-specific tag indicates the file containing the stashed
     passwords (created by ``kdb5_ldap_util stashsrvpw``) for the
-    **ldap_kadmind_dn** and **ldap_kdc_dn** objects.  This file must
-    be kept secure.
+    **ldap_kdc_dn** and **ldap_kadmind_dn** objects, or for the
+    **ldap_kdc_sasl_authcid** or **ldap_kadmind_sasl_authcid** names
+    for SASL authentication.  This file must be kept secure.
 
 The following tag may be specified directly in the [dbmodules]
 section to control where database modules are loaded from: