krb5 commit: Document enctype migration
Greg Hudson <[email protected]>
| Newsgroups | gmane.comp.encryption.kerberos.cvs |
|---|---|
| Message-ID | <[email protected]> |
https://github.com/krb5/krb5/commit/0c0887988d937bb797139e449c5da845ea5b1a85 commit 0c0887988d937bb797139e449c5da845ea5b1a85 Author: Greg Hudson <[email protected]> Date: Wed Sep 16 19:12:34 2020 -0400 Document enctype migration In enctypes.rst, note that des3-cbc-sha1 and arcfour-hmac are deprecated, and add a paragraph about des3-cbc-sha1 support being removed in the future. Add a section on migrating away from legacy enctypes (briefer than the existing advanced/retiring-des.rst and not specific to single-DES). In kdc_conf.rst, note that des3-cbc-sha1 and arcfour-hmac are deprecated. ticket: 8950 (new) doc/admin/conf_files/kdc_conf.rst | 8 ++-- doc/admin/database.rst | 4 ++ doc/admin/enctypes.rst | 91 ++++++++++++++++++++++++++++++------- 3 files changed, 83 insertions(+), 20 deletions(-) diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst index 7b1b9fc..1dc958d 100644 --- a/doc/admin/conf_files/kdc_conf.rst +++ b/doc/admin/conf_files/kdc_conf.rst @@ -844,17 +844,17 @@ 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. -Encryption types marked as "weak" are available for compatibility but -not recommended for use. +Encryption types marked as "weak" and "deprecated" are available for +compatibility but not recommended for use. ==================================================== ========================================================= des3-cbc-raw Triple DES cbc mode raw (weak) -des3-cbc-sha1 des3-hmac-sha1 des3-cbc-sha1-kd Triple DES cbc mode with HMAC/sha1 +des3-cbc-sha1 des3-hmac-sha1 des3-cbc-sha1-kd Triple DES cbc mode with HMAC/sha1 (deprecated) aes256-cts-hmac-sha1-96 aes256-cts aes256-sha1 AES-256 CTS mode with 96-bit SHA-1 HMAC aes128-cts-hmac-sha1-96 aes128-cts aes128-sha1 AES-128 CTS mode with 96-bit SHA-1 HMAC aes256-cts-hmac-sha384-192 aes256-sha2 AES-256 CTS mode with 192-bit SHA-384 HMAC aes128-cts-hmac-sha256-128 aes128-sha2 AES-128 CTS mode with 128-bit SHA-256 HMAC -arcfour-hmac rc4-hmac arcfour-hmac-md5 RC4 with HMAC/MD5 +arcfour-hmac rc4-hmac arcfour-hmac-md5 RC4 with HMAC/MD5 (deprecated) arcfour-hmac-exp rc4-hmac-exp arcfour-hmac-md5-exp Exportable RC4 with HMAC/MD5 (weak) camellia256-cts-cmac camellia256-cts Camellia-256 CTS mode with CMAC camellia128-cts-cmac camellia128-cts Camellia-128 CTS mode with CMAC diff --git a/doc/admin/database.rst b/doc/admin/database.rst index 1ce74b3..eb64172 100644 --- a/doc/admin/database.rst +++ b/doc/admin/database.rst @@ -252,6 +252,8 @@ be modified by using the **-policy** or **-clearpolicy** flag to :ref:`modify_principal`. +.. _updating_history_key: + Updating the history key ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -470,6 +472,8 @@ Examples shell% +.. _updating_master_key: + Updating the master key ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/admin/enctypes.rst b/doc/admin/enctypes.rst index caf6d92..047185a 100644 --- a/doc/admin/enctypes.rst +++ b/doc/admin/enctypes.rst @@ -123,24 +123,83 @@ Enctype compatibility See :ref:`Encryption_types` for additional information about enctypes. -========================== ===== ======== ======= -enctype weak? krb5 Windows -========================== ===== ======== ======= -des-cbc-crc weak <1.18 >=2000 -des-cbc-md4 weak <1.18 ? -des-cbc-md5 weak <1.18 >=2000 -des3-cbc-sha1 >=1.1 none -arcfour-hmac >=1.3 >=2000 -arcfour-hmac-exp weak >=1.3 >=2000 -aes128-cts-hmac-sha1-96 >=1.3 >=Vista -aes256-cts-hmac-sha1-96 >=1.3 >=Vista -aes128-cts-hmac-sha256-128 >=1.15 none -aes256-cts-hmac-sha384-192 >=1.15 none -camellia128-cts-cmac >=1.9 none -camellia256-cts-cmac >=1.9 none -========================== ===== ======== ======= +========================== ========== ======== ======= +enctype weak? krb5 Windows +========================== ========== ======== ======= +des-cbc-crc weak <1.18 >=2000 +des-cbc-md4 weak <1.18 ? +des-cbc-md5 weak <1.18 >=2000 +des3-cbc-sha1 deprecated >=1.1 none +arcfour-hmac deprecated >=1.3 >=2000 +arcfour-hmac-exp weak >=1.3 >=2000 +aes128-cts-hmac-sha1-96 >=1.3 >=Vista +aes256-cts-hmac-sha1-96 >=1.3 >=Vista +aes128-cts-hmac-sha256-128 >=1.15 none +aes256-cts-hmac-sha384-192 >=1.15 none +camellia128-cts-cmac >=1.9 none +camellia256-cts-cmac >=1.9 none +========================== ========== ======== ======= krb5 releases 1.18 and later do not support single-DES. krb5 releases 1.8 and later disable the single-DES enctypes by default. Microsoft Windows releases Windows 7 and later disable single-DES enctypes by default. + +krb5 releases 1.17 and later flag deprecated encryption types +(including ``des3-cbc-sha1`` and ``arcfour-hmac``) in KDC logs and +kadmin output. krb5 release 1.19 issues a warning during initial +authentication if ``des3-cbc-sha1`` is used. Future releases will +disable ``des3-cbc-sha1`` by default and eventually remove support for +it. + + +Migrating away from older encryption types +------------------------------------------ + +Administrator intervention may be required to migrate a realm away +from legacy encryption types, especially if the realm was created +using krb5 release 1.2 or earlier. This migration should be performed +before upgrading to krb5 versions which disable or remove support for +legacy encryption types. + +If there is a **supported_enctypes** setting in :ref:`kdc.conf(5)` on +the KDC, make sure that it does not include weak or deprecated +encryption types. This will ensure that newly created keys do not use +those encryption types by default. + +Check the ``krbtgt/REALM`` principal using the :ref:`kadmin(1)` +**getprinc** command. If it lists a weak or deprecated encryption +type as the first key, it must be migrated using the procedure in +:ref:`changing_krbtgt_key`. + +Check the ``kadmin/history`` principal, which should have only one key +entry. If it uses a weak or deprecated encryption type, it should be +upgraded following the notes in :ref:`updating_history_key`. + +Check the other kadmin principals: kadmin/changepw, kadmin/admin, and +any kadmin/hostname principals that may exist. These principals can +be upgraded with **change_password -randkey** in kadmin. + +Check the ``K/M`` entry. If it uses a weak or deprecated encryption +type, it should be upgraded following the procedure in +:ref:`updating_master_key`. + +User and service principals using legacy encryption types can be +enumerated with the :ref:`kdb5_util(8)` **tabdump keyinfo** command. + +Service principals can be migrated with a keytab rotation on the +service host, which can be accomplished using the :ref:`k5srvutil(1)` +**change** and **delold** commands. Allow enough time for existing +tickets to expire between the change and delold operations. + +User principals with password-based keys can be migrated with a +password change. The realm administrator can set a password +expiration date using the :ref:`kadmin(1)` **modify_principal +-pwexpire** command to force a password change. + +If a legacy encryption type has not yet been disabled by default in +the version of krb5 running on the KDC, it can be disabled +administratively with the **permitted_enctypes** variable. For +example, setting **permitted_enctypes** to ``DEFAULT -des3 -rc4`` will +cause any database keys of the triple-DES and RC4 encryption types to +be ignored.