Better keysalt docs

Add a new section to kdc_conf.rst to describe keysalt lists, and
update other documentation to better distinguish enctype lists from
keysalt lists.

ticket: 7608
target_version: 1.12
tags: pullup

6 files changed, 62 insertions, 39 deletions

diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index bcae5d4d26..7f334a518e 100644
--- a/doc/admin/admin_commands/kadmin_local.rst
+++ b/doc/admin/admin_commands/kadmin_local.rst
@@ -127,9 +127,9 @@ OPTIONS
     instead of reading it from a stash file.
 
 **-e** "*enc*:*salt* ..."
-    Sets the list of encryption types and salt types to be used for
-    any new keys created.  See :ref:`Encryption_and_salt_types` in
-    :ref:`kdc.conf(5)` for a list of possible values.
+    Sets the keysalt list to be used for any new keys created.  See
+    :ref:`Keysalt_lists` in :ref:`kdc.conf(5)` for a list of possible
+    values.
 
 **-O**
     Force use of old AUTH_GSSAPI authentication flavor.
@@ -307,8 +307,9 @@ Options:
     via the process list.
 
 **-e** *enc*:*salt*,...
-    Uses the specified list of enctype-salttype pairs for setting the
-    key of the principal.
+    Uses the specified keysalt list for setting the keys of the
+    principal.  See :ref:`Keysalt_lists` in :ref:`kdc.conf(5)` for a
+    list of possible values.
 
 **-x** *db_princ_args*
     Indicates database-specific options.  The options for the LDAP
@@ -439,8 +440,9 @@ The following options are available:
     the process list.
 
 **-e** *enc*:*salt*,...
-    Uses the specified list of enctype-salttype pairs for setting the
-    key of the principal.
+    Uses the specified keysalt list for setting the keys of the
+    principal.  See :ref:`Keysalt_lists` in :ref:`kdc.conf(5)` for a
+    list of possible values.
 
 **-keepold**
     Keeps the existing keys in the database.  This flag is usually not
@@ -580,8 +582,8 @@ modules.  The following string attributes are recognized by the KDC:
 **session_enctypes**
     Specifies the encryption types supported for session keys when the
     principal is authenticated to as a server.  See
-    :ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)` for a list
-    of the accepted values.
+    :ref:`Encryption_types` in :ref:`kdc.conf(5)` for a list of the
+    accepted values.
 
 This command requires the **modify** privilege.
 
@@ -668,10 +670,10 @@ The following options are available:
 **-allowedkeysalts**
     Specifies the key/salt tuples supported for long-term keys when
     setting or changing a principal's password/keys.  See
-    :ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)` for a list
-    of the accepted values, but note that key/salt tuples must be
-    separated with commas (',') only.  To clear the allowed key/salt
-    policy use a value of '-'.
+    :ref:`Keysalt_lists` in :ref:`kdc.conf(5)` for a list of the
+    accepted values, but note that key/salt tuples must be separated
+    with commas (',') only.  To clear the allowed key/salt policy use
+    a value of '-'.
 
 Example:
 
@@ -819,8 +821,9 @@ The options are:
     used.
 
 **-e** *enc*:*salt*,...
-    Use the specified list of enctype-salttype pairs for setting the
-    new keys of the principal.
+    Uses the specified keysalt list for setting the new keys of the
+    principal.  See :ref:`Keysalt_lists` in :ref:`kdc.conf(5)` for a
+    list of possible values.
 
 **-q**
     Display less verbose information.
diff --git a/doc/admin/admin_commands/kdb5_util.rst b/doc/admin/admin_commands/kdb5_util.rst
index 4a90eb66ee..a10e6d86be 100644
--- a/doc/admin/admin_commands/kdb5_util.rst
+++ b/doc/admin/admin_commands/kdb5_util.rst
@@ -262,9 +262,9 @@ add_mkey
 Adds a new master key to the master key principal, but does not mark
 it as active.  Existing master keys will remain.  The **-e** option
 specifies the encryption type of the new master key; see
-:ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)` for a list of
-possible values.  The **-s** option stashes the new master key in the
-stash file, which will be created if it doesn't already exist.
+:ref:`Encryption_types` in :ref:`kdc.conf(5)` for a list of possible
+values.  The **-s** option stashes the new master key in the stash
+file, which will be created if it doesn't already exist.
 
 After a new master key is added, it should be propagated to slave
 servers via a manual or periodic invocation of :ref:`kprop(8)`.  Then,
diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst
index b78d45bd43..be9064d772 100644
--- a/doc/admin/conf_files/kdc_conf.rst
+++ b/doc/admin/conf_files/kdc_conf.rst
@@ -267,7 +267,7 @@ The following tags may be specified in a [realms] subsection:
 **master_key_type**
     (Key type string.)  Specifies the master key's key type.  The
     default value for this is |defmkey|.  For a list of all possible
-    values, see :ref:`Encryption_and_salt_types`.
+    values, see :ref:`Encryption_types`.
 
 **max_life**
     (:ref:`duration` string.)  Specifies the maximum time period for
@@ -327,7 +327,7 @@ The following tags may be specified in a [realms] subsection:
     combinations of principals for this realm.  Any principals created
     through :ref:`kadmin(1)` will have keys of these types.  The
     default value for this tag is |defkeysalts|.  For lists of
-    possible values, see :ref:`Encryption_and_salt_types`.
+    possible values, see :ref:`Keysalt_lists`.
 
 
 .. _dbdefaults:
@@ -679,10 +679,10 @@ For information about the syntax of some of these options, see
     policy is such that up-to-date CRLs must be present for every CA.
 
 
-.. _Encryption_and_salt_types:
+.. _Encryption_types:
 
-Encryption and salt types
--------------------------
+Encryption types
+----------------
 
 Any tag in the configuration files which requires a list of encryption
 types can be set to some combination of the following strings.
@@ -726,10 +726,31 @@ implementation (krb5-1.3.1 and earlier).  Services running versions of
 krb5 without AES support must not be given AES keys in the KDC
 database.
 
-Kerberos keys for users are usually derived from passwords.  To ensure
-that people who happen to pick the same password do not have the same
-key, Kerberos 5 incorporates more information into the key using
-something called a salt.  The supported salt types are as follows:
+
+.. _Keysalt_lists:
+
+Keysalt lists
+-------------
+
+Kerberos keys for users are usually derived from passwords.  Kerberos
+commands and configuration parameters that affect generation of keys
+take lists of enctype-salttype ("keysalt") pairs, known as *keysalt
+lists*.  Each keysalt pair is an enctype name followed by a salttype
+name, in the format *enc*:*salt*.  Individual keysalt list members are
+separated by comma (",") characters or space characters.  For example:
+
+ ::
+
+    kadmin -e aes256-cts:normal,aes128-cts:normal
+
+would start up kadmin so that by default it would generate
+password-derived keys for the **aes256-cts** and **aes128-cts**
+encryption types, using a **normal** salt.
+
+To ensure that people who happen to pick the same password do not have
+the same key, Kerberos 5 incorporates more information into the key
+using something called a salt.  The supported salt types are as
+follows:
 
 ================= ============================================
 normal            default for Kerberos Version 5
diff --git a/doc/admin/conf_files/krb5_conf.rst b/doc/admin/conf_files/krb5_conf.rst
index ff6a861e9d..151894937a 100644
--- a/doc/admin/conf_files/krb5_conf.rst
+++ b/doc/admin/conf_files/krb5_conf.rst
@@ -99,14 +99,14 @@ Additionally, krb5.conf may include any of the relations described in
 The libdefaults section may contain any of the following relations:
 
 **allow_weak_crypto**
-    If this flag is set to false, then weak encryption types (as noted in
-    :ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)`) will be filtered
-    out of the lists **default_tgs_enctypes**, **default_tkt_enctypes**, and
-    **permitted_enctypes**.  The default value for this tag is false, which
-    may cause authentication failures in existing Kerberos infrastructures
-    that do not support strong crypto.  Users in affected environments
-    should set this tag to true until their infrastructure adopts
-    stronger ciphers.
+    If this flag is set to false, then weak encryption types (as noted
+    in :ref:`Encryption_types` in :ref:`kdc.conf(5)`) will be filtered
+    out of the lists **default_tgs_enctypes**,
+    **default_tkt_enctypes**, and **permitted_enctypes**.  The default
+    value for this tag is false, which may cause authentication
+    failures in existing Kerberos infrastructures that do not support
+    strong crypto.  Users in affected environments should set this tag
+    to true until their infrastructure adopts stronger ciphers.
 
 **ap_req_checksum_type**
     An integer which specifies the type of AP-REQ checksum to use in
@@ -160,7 +160,7 @@ The libdefaults section may contain any of the following relations:
     Identifies the supported list of session key encryption types that
     the client should request when making a TGS-REQ, in order of
     preference from highest to lowest.  The list may be delimited with
-    commas or whitespace.  See :ref:`Encryption_and_salt_types` in
+    commas or whitespace.  See :ref:`Encryption_types` in
     :ref:`kdc.conf(5)` for a list of the accepted values for this tag.
     The default value is |defetypes|, but single-DES encryption types
     will be implicitly removed from this list if the value of
diff --git a/doc/admin/enctypes.rst b/doc/admin/enctypes.rst
index 57ebae4d99..44b6a8c471 100644
--- a/doc/admin/enctypes.rst
+++ b/doc/admin/enctypes.rst
@@ -122,8 +122,7 @@ generation of long-term keys.
 Enctype compatibility
 ---------------------
 
-See :ref:`Encryption_and_salt_types` for additional information about
-enctypes.
+See :ref:`Encryption_types` for additional information about enctypes.
 
 ======================= ===== ======== =======
 enctype                 weak? krb5     Windows
diff --git a/doc/mitK5defaults.rst b/doc/mitK5defaults.rst
index 84b9df8810..89b8f4c452 100644
--- a/doc/mitK5defaults.rst
+++ b/doc/mitK5defaults.rst
@@ -20,7 +20,7 @@ Admin server ACL file :ref:`kadm5.acl(5)`   |kdcdir|\ ``/kadm5.acl``
 Plugin base directory                       |libdir|\ ``/krb5/plugins``
 :ref:`rcache_definition` directory          ``/var/tmp``                   **KRB5RCACHEDIR**
 Master key default enctype                  |defmkey|
-Supported :ref:`Encryption_and_salt_types`  |defkeysalts|
+Default :ref:`keysalt list<Keysalt_lists>`  |defkeysalts|
 Permitted enctypes                          |defetypes|
 KDC default port                            88
 Second KDC default port                     750