From 23a75649277afc24a9dfea199689e18129fa390c Mon Sep 17 00:00:00 2001 From: Tom Yu Date: Mon, 9 Dec 2013 15:48:02 -0500 Subject: 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(-) (limited to 'doc') 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` |defkeysalts| Permitted enctypes |defetypes| KDC default port 88 Second KDC default port 750 -- cgit