krb5 commit: Better keysalt docs
Tom Yu
tlyu at MIT.EDU
Mon Dec 9 18:17:27 EST 2013
https://github.com/krb5/krb5/commit/23a75649277afc24a9dfea199689e18129fa390c
commit 23a75649277afc24a9dfea199689e18129fa390c
Author: Tom Yu <tlyu at mit.edu>
Date: Mon Dec 9 15:48:02 2013 -0500
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
doc/admin/admin_commands/kadmin_local.rst | 33 +++++++++++++-----------
doc/admin/admin_commands/kdb5_util.rst | 6 ++--
doc/admin/conf_files/kdc_conf.rst | 39 ++++++++++++++++++++++------
doc/admin/conf_files/krb5_conf.rst | 18 ++++++------
doc/admin/enctypes.rst | 3 +-
doc/mitK5defaults.rst | 2 +-
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 bcae5d4..7f334a5 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 4a90eb6..a10e6d8 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 b78d45b..be9064d 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 ff6a861..1518949 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 57ebae4..44b6a8c 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 84b9df8..89b8f4c 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
More information about the cvs-krb5
mailing list