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

2 files changed, 39 insertions, 18 deletions

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