diff options
Diffstat (limited to 'crypto/krb5/doc/admin/advanced')
| -rw-r--r-- | crypto/krb5/doc/admin/advanced/index.rst | 8 | ||||
| -rw-r--r-- | crypto/krb5/doc/admin/advanced/retiring-des.rst | 422 |
2 files changed, 0 insertions, 430 deletions
diff --git a/crypto/krb5/doc/admin/advanced/index.rst b/crypto/krb5/doc/admin/advanced/index.rst deleted file mode 100644 index 834f453c37de..000000000000 --- a/crypto/krb5/doc/admin/advanced/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -Advanced topics -=============== - - -.. toctree:: - :maxdepth: 1 - - retiring-des.rst diff --git a/crypto/krb5/doc/admin/advanced/retiring-des.rst b/crypto/krb5/doc/admin/advanced/retiring-des.rst deleted file mode 100644 index 38f76d3f4522..000000000000 --- a/crypto/krb5/doc/admin/advanced/retiring-des.rst +++ /dev/null @@ -1,422 +0,0 @@ -.. _retiring-des: - -Retiring DES -======================= - -Version 5 of the Kerberos protocol was originally implemented using -the Data Encryption Standard (DES) as a block cipher for encryption. -While it was considered secure at the time, advancements in computational -ability have rendered DES vulnerable to brute force attacks on its 56-bit -keyspace. As such, it is now considered insecure and should not be -used (:rfc:`6649`). - -History -------- - -DES was used in the original Kerberos implementation, and was the -only cryptosystem in krb5 1.0. Partial support for triple-DES (3DES) was -added in version 1.1, with full support following in version 1.2. -The Advanced Encryption Standard (AES), which supersedes DES, gained -partial support in version 1.3.0 of krb5 and full support in version 1.3.2. -However, deployments of krb5 using Kerberos databases created with older -versions of krb5 will not necessarily start using strong crypto for -ordinary operation without administrator intervention. - -MIT krb5 began flagging deprecated encryption types with release 1.17, -and removed DES (single-DES) support in release 1.18. As a -consequence, a release prior to 1.18 is required to perform these -migrations. - -Types of keys -------------- - -* The database master key: This key is not exposed to user requests, - but is used to encrypt other key material stored in the kerberos - database. The database master key is currently stored as ``K/M`` - by default. -* Password-derived keys: User principals frequently have keys - derived from a password. When a new password is set, the KDC - uses various string2key functions to generate keys in the database - for that principal. -* Keytab keys: Application server principals generally use random - keys which are not derived from a password. When the database - entry is created, the KDC generates random keys of various enctypes - to enter in the database, which are conveyed to the application server - and stored in a keytab. -* Session keys: These are short-term keys generated by the KDC while - processing client requests, with an enctype selected by the KDC. - -For details on the various enctypes and how enctypes are selected by the KDC -for session keys and client/server long-term keys, see :ref:`enctypes`. -When using the :ref:`kadmin(1)` interface to generate new long-term keys, -the **-e** argument can be used to force a particular set of enctypes, -overriding the KDC default values. - -.. note:: - - When the KDC is selecting a session key, it has no knowledge about the - kerberos installation on the server which will receive the service ticket, - only what keys are in the database for the service principal. - In order to allow uninterrupted operation to - clients while migrating away from DES, care must be taken to ensure that - kerberos installations on application server machines are configured to - support newer encryption types before keys of those new encryption types - are created in the Kerberos database for those server principals. - -Upgrade procedure ------------------ - -This procedure assumes that the KDC software has already been upgraded -to a modern version of krb5 that supports non-DES keys, so that the -only remaining task is to update the actual keys used to service requests. -The realm used for demonstrating this procedure, ZONE.MIT.EDU, -is an example of the worst-case scenario, where all keys in the realm -are DES. The realm was initially created with a very old version of krb5, -and **supported_enctypes** in :ref:`kdc.conf(5)` was set to a value -appropriate when the KDC was installed, but was not updated as the KDC -was upgraded: - -:: - - [realms] - ZONE.MIT.EDU = { - [...] - master_key_type = des-cbc-crc - supported_enctypes = des-cbc-crc:normal des:normal des:v4 des:norealm des:onlyrealm des:afs3 - } - -This resulted in the keys for all principals in the realm being forced -to DES-only, unless specifically requested using :ref:`kadmin(1)`. - -Before starting the upgrade, all KDCs were running krb5 1.11, -and the database entries for some "high-value" principals were: - -:: - - [root@casio krb5kdc]# kadmin.local -r ZONE.MIT.EDU -q 'getprinc krbtgt/ZONE.MIT.EDU' - [...] - Number of keys: 1 - Key: vno 1, des-cbc-crc:v4 - [...] - [root@casio krb5kdc]# kadmin.local -r ZONE.MIT.EDU -q 'getprinc kadmin/admin' - [...] - Number of keys: 1 - Key: vno 15, des-cbc-crc - [...] - [root@casio krb5kdc]# kadmin.local -r ZONE.MIT.EDU -q 'getprinc kadmin/changepw' - [...] - Number of keys: 1 - Key: vno 14, des-cbc-crc - [...] - -The ``krbtgt/REALM`` key appears to have never been changed since creation -(its kvno is 1), and all three database entries have only a des-cbc-crc key. - -The krbtgt key and KDC keys -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Perhaps the biggest single-step improvement in the security of the cell -is gained by strengthening the key of the ticket-granting service principal, -``krbtgt/REALM``---if this principal's key is compromised, so is the -entire realm. Since the server that will handle service tickets -for this principal is the KDC itself, it is easy to guarantee that it -will be configured to support any encryption types which might be -selected. However, the default KDC behavior when creating new keys is to -remove the old keys, which would invalidate all existing tickets issued -against that principal, rendering the TGTs cached by clients useless. -Instead, a new key can be created with the old key retained, so that -existing tickets will still function until their scheduled expiry -(see :ref:`changing_krbtgt_key`). - -:: - - [root@casio krb5kdc]# enctypes=aes256-cts-hmac-sha1-96:normal,\ - > aes128-cts-hmac-sha1-96:normal,des3-hmac-sha1:normal,des-cbc-crc:normal - [root@casio krb5kdc]# kadmin.local -r ZONE.MIT.EDU -q "cpw -e ${enctypes} -randkey \ - > -keepold krbtgt/ZONE.MIT.EDU" - Authenticating as principal root/admin@ZONE.MIT.EDU with password. - Key for "krbtgt/ZONE.MIT.EDU@ZONE.MIT.EDU" randomized. - -.. note:: - - The new ``krbtgt@REALM`` key should be propagated to replica KDCs - immediately so that TGTs issued by the primary KDC can be used to - issue service tickets on replica KDCs. Replica KDCs will refuse - requests using the new TGT kvno until the new krbtgt entry has - been propagated to them. - -It is necessary to explicitly specify the enctypes for the new database -entry, since **supported_enctypes** has not been changed. Leaving -**supported_enctypes** unchanged makes a potential rollback operation -easier, since all new keys of new enctypes are the result of explicit -administrator action and can be easily enumerated. -Upgrading the krbtgt key should have minimal user-visible disruption other -than that described in the note above, since only clients which list the -new enctypes as supported will use them, per the procedure -in :ref:`session_key_selection`. -Once the krbtgt key is updated, the session and ticket keys for user -TGTs will be strong keys, but subsequent requests -for service tickets will still get DES keys until the service principals -have new keys generated. Application service -remains uninterrupted due to the key-selection procedure on the KDC. - -After the change, the database entry is now: - -:: - - [root@casio krb5kdc]# kadmin.local -r ZONE.MIT.EDU -q 'getprinc krbtgt/ZONE.MIT.EDU' - [...] - Number of keys: 5 - Key: vno 2, aes256-cts-hmac-sha1-96 - Key: vno 2, aes128-cts-hmac-sha1-96 - Key: vno 2, des3-cbc-sha1 - Key: vno 2, des-cbc-crc - Key: vno 1, des-cbc-crc:v4 - [...] - -Since the expected disruptions from rekeying the krbtgt principal are -minor, after a short testing period, it is -appropriate to rekey the other high-value principals, ``kadmin/admin@REALM`` -and ``kadmin/changepw@REALM``. These are the service principals used for -changing user passwords and updating application keytabs. The kadmin -and password-changing services are regular kerberized services, so the -session-key-selection algorithm described in :ref:`session_key_selection` -applies. It is particularly important to have strong session keys for -these services, since user passwords and new long-term keys are conveyed -over the encrypted channel. - -:: - - [root@casio krb5kdc]# enctypes=aes256-cts-hmac-sha1-96:normal,\ - > aes128-cts-hmac-sha1-96:normal,des3-hmac-sha1:normal - [root@casio krb5kdc]# kadmin.local -r ZONE.MIT.EDU -q "cpw -e ${enctypes} -randkey \ - > kadmin/admin" - Authenticating as principal root/admin@ZONE.MIT.EDU with password. - Key for "kadmin/admin@ZONE.MIT.EDU" randomized. - [root@casio krb5kdc]# kadmin.local -r ZONE.MIT.EDU -q "cpw -e ${enctypes} -randkey \ - > kadmin/changepw" - Authenticating as principal root/admin@ZONE.MIT.EDU with password. - Key for "kadmin/changepw@ZONE.MIT.EDU" randomized. - -It is not necessary to retain a single-DES key for these services, since -password changes are not part of normal daily workflow, and disruption -from a client failure is likely to be minimal. Furthermore, if a kerberos -client experiences failure changing a user password or keytab key, -this indicates that that client will become inoperative once services -are rekeyed to non-DES enctypes. Such problems can be detected early -at this stage, giving more time for corrective action. - -Adding strong keys to application servers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before switching the default enctypes for new keys over to strong enctypes, -it may be desired to test upgrading a handful of services with the -new configuration before flipping the switch for the defaults. This -still requires using the **-e** argument in :ref:`kadmin(1)` to get non-default -enctypes: - -:: - - [root@casio krb5kdc]# enctypes=aes256-cts-hmac-sha1-96:normal,\ - > aes128-cts-hmac-sha1-96:normal,des3-cbc-sha1:normal,des-cbc-crc:normal - [root@casio krb5kdc]# kadmin -r ZONE.MIT.EDU -p zephyr/zephyr@ZONE.MIT.EDU -k -t \ - > /etc/zephyr/krb5.keytab -q "ktadd -e ${enctypes} \ - > -k /etc/zephyr/krb5.keytab zephyr/zephyr@ZONE.MIT.EDU" - Authenticating as principal zephyr/zephyr@ZONE.MIT.EDU with keytab /etc/zephyr/krb5.keytab. - Entry for principal zephyr/zephyr@ZONE.MIT.EDU with kvno 4, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:/etc/zephyr/krb5.keytab. - Entry for principal zephyr/zephyr@ZONE.MIT.EDU with kvno 4, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:/etc/zephyr/krb5.keytab. - Entry for principal zephyr/zephyr@ZONE.MIT.EDU with kvno 4, encryption type des3-cbc-sha1 added to keytab WRFILE:/etc/zephyr/krb5.keytab. - Entry for principal zephyr/zephyr@ZONE.MIT.EDU with kvno 4, encryption type des-cbc-crc added to keytab WRFILE:/etc/zephyr/krb5.keytab. - -Be sure to remove the old keys from the application keytab, per best -practice. - -:: - - [root@casio krb5kdc]# k5srvutil -f /etc/zephyr/krb5.keytab delold - Authenticating as principal zephyr/zephyr@ZONE.MIT.EDU with keytab /etc/zephyr/krb5.keytab. - Entry for principal zephyr/zephyr@ZONE.MIT.EDU with kvno 3 removed from keytab WRFILE:/etc/zephyr/krb5.keytab. - -Adding strong keys by default -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once the high-visibility services have been rekeyed, it is probably -appropriate to change :ref:`kdc.conf(5)` to generate keys with the new -encryption types by default. This enables server administrators to generate -new enctypes with the **change** subcommand of :ref:`k5srvutil(1)`, -and causes user password -changes to add new encryption types for their entries. It will probably -be necessary to implement administrative controls to cause all user -principal keys to be updated in a reasonable period of time, whether -by forcing password changes or a password synchronization service that -has access to the current password and can add the new keys. - -:: - - [realms] - ZONE.MIT.EDU = { - supported_enctypes = aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal des3-cbc-sha1:normal des3-hmac-sha1:normal des-cbc-crc:normal - -.. note:: - - The krb5kdc process must be restarted for these changes to take effect. - -At this point, all service administrators can update their services and the -servers behind them to take advantage of strong cryptography. -If necessary, the server's krb5 installation should be configured and/or -upgraded to a version supporting non-DES keys. See :ref:`enctypes` for -krb5 version and configuration settings. -Only when the service is configured to accept non-DES keys should -the key version number be incremented and new keys generated -(``k5srvutil change && k5srvutil delold``). - -:: - - root@dr-willy:~# k5srvutil change - Authenticating as principal host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU with keytab /etc/krb5.keytab. - Entry for principal host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU with kvno 3, encryption type AES-256 CTS mode with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5.keytab. - Entry for principal host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU with kvno 3, encryption type AES-128 CTS mode with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5.keytab. - Entry for principal host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU with kvno 3, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab. - Entry for principal host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU with kvno 3, encryption type DES cbc mode with CRC-32 added to keytab WRFILE:/etc/krb5.keytab. - root@dr-willy:~# klist -e -k -t /etc/krb5.keytab - Keytab name: WRFILE:/etc/krb5.keytab - KVNO Timestamp Principal - ---- ----------------- -------------------------------------------------------- - 2 10/10/12 17:03:59 host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU (DES cbc mode with CRC-32) - 3 12/12/12 15:31:19 host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU (AES-256 CTS mode with 96-bit SHA-1 HMAC) - 3 12/12/12 15:31:19 host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU (AES-128 CTS mode with 96-bit SHA-1 HMAC) - 3 12/12/12 15:31:19 host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU (Triple DES cbc mode with HMAC/sha1) - 3 12/12/12 15:31:19 host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU (DES cbc mode with CRC-32) - root@dr-willy:~# k5srvutil delold - Authenticating as principal host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU with keytab /etc/krb5.keytab. - Entry for principal host/dr-willy.xvm.mit.edu@ZONE.MIT.EDU with kvno 2 removed from keytab WRFILE:/etc/krb5.keytab. - -When a single service principal is shared by multiple backend servers in -a load-balanced environment, it may be necessary to schedule downtime -or adjust the population in the load-balanced pool in order to propagate -the updated keytab to all hosts in the pool with minimal service interruption. - -Removing DES keys from usage -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This situation remains something of a testing or transitory state, -as new DES keys are still being generated, and will be used if requested -by a client. To make more progress removing DES from the realm, the KDC -should be configured to not generate such keys by default. - -.. note:: - - An attacker posing as a client can implement a brute force attack against - a DES key for any principal, if that key is in the current (highest-kvno) - key list. This attack is only possible if **allow_weak_crypto = true** - is enabled on the KDC. Setting the **+requires_preauth** flag on a - principal forces this attack to be an online attack, much slower than - the offline attack otherwise available to the attacker. However, setting - this flag on a service principal is not always advisable; see the entry in - :ref:`add_principal` for details. - -The following KDC configuration will not generate DES keys by default: - -:: - - [realms] - ZONE.MIT.EDU = { - supported_enctypes = aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal des3-cbc-sha1:normal des3-hmac-sha1:normal - -.. note:: - - As before, the KDC process must be restarted for this change to take - effect. It is best practice to update kdc.conf on all KDCs, not just the - primary, to avoid unpleasant surprises should the primary fail and a - replica need to be promoted. - -It is now appropriate to remove the legacy single-DES key from the -``krbtgt/REALM`` entry: - -:: - - [root@casio krb5kdc]# kadmin.local -r ZONE.MIT.EDU -q "cpw -randkey -keepold \ - > krbtgt/ZONE.MIT.EDU" - Authenticating as principal host/admin@ATHENA.MIT.EDU with password. - Key for "krbtgt/ZONE.MIT.EDU@ZONE.MIT.EDU" randomized. - -After the maximum ticket lifetime has passed, the old database entry -should be removed. - -:: - - [root@casio krb5kdc]# kadmin.local -r ZONE.MIT.EDU -q 'purgekeys krbtgt/ZONE.MIT.EDU' - Authenticating as principal root/admin@ZONE.MIT.EDU with password. - Old keys for principal "krbtgt/ZONE.MIT.EDU@ZONE.MIT.EDU" purged. - -After the KDC is restarted with the new **supported_enctypes**, -all user password changes and application keytab updates will not -generate DES keys by default. - -:: - - contents-vnder-pressvre:~> kpasswd zonetest@ZONE.MIT.EDU - Password for zonetest@ZONE.MIT.EDU: [enter old password] - Enter new password: [enter new password] - Enter it again: [enter new password] - Password changed. - contents-vnder-pressvre:~> kadmin -r ZONE.MIT.EDU -q 'getprinc zonetest' - [...] - Number of keys: 3 - Key: vno 9, aes256-cts-hmac-sha1-96 - Key: vno 9, aes128-cts-hmac-sha1-96 - Key: vno 9, des3-cbc-sha1 - [...] - - [kaduk@glossolalia ~]$ kadmin -p kaduk@ZONE.MIT.EDU -r ZONE.MIT.EDU -k \ - > -t kaduk-zone.keytab -q 'ktadd -k kaduk-zone.keytab kaduk@ZONE.MIT.EDU' - Authenticating as principal kaduk@ZONE.MIT.EDU with keytab kaduk-zone.keytab. - Entry for principal kaduk@ZONE.MIT.EDU with kvno 3, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:kaduk-zone.keytab. - Entry for principal kaduk@ZONE.MIT.EDU with kvno 3, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:kaduk-zone.keytab. - Entry for principal kaduk@ZONE.MIT.EDU with kvno 3, encryption type des3-cbc-sha1 added to keytab WRFILE:kaduk-zone.keytab. - -Once all principals have been re-keyed, DES support can be disabled on the -KDC (**allow_weak_crypto = false**), and client machines can remove -**allow_weak_crypto = true** from their :ref:`krb5.conf(5)` configuration -files, completing the migration. **allow_weak_crypto** takes precedence over -all places where DES enctypes could be explicitly configured. DES keys will -not be used, even if they are present, when **allow_weak_crypto = false**. - -Support for legacy services -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If there remain legacy services which do not support non-DES enctypes -(such as older versions of AFS), **allow_weak_crypto** must remain -enabled on the KDC. Client machines need not have this setting, -though---applications which require DES can use API calls to allow -weak crypto on a per-request basis, overriding the system krb5.conf. -However, having **allow_weak_crypto** set on the KDC means that any -principals which have a DES key in the database could still use those -keys. To minimize the use of DES in the realm and restrict it to just -legacy services which require DES, it is necessary to remove all other -DES keys. The realm has been configured such that at password and -keytab change, no DES keys will be generated by default. The task -then reduces to requiring user password changes and having server -administrators update their service keytabs. Administrative outreach -will be necessary, and if the desire to eliminate DES is sufficiently -strong, the KDC administrators may choose to randkey any principals -which have not been rekeyed after some timeout period, forcing the -user to contact the helpdesk for access. - -The Database Master Key ------------------------ - -This procedure does not alter ``K/M@REALM``, the key used to encrypt key -material in the Kerberos database. (This is the key stored in the stash file -on the KDC if stash files are used.) However, the security risk of -a single-DES key for ``K/M`` is minimal, given that access to material -encrypted in ``K/M`` (the Kerberos database) is generally tightly controlled. -If an attacker can gain access to the encrypted database, they likely -have access to the stash file as well, rendering the weak cryptography -broken by non-cryptographic means. As such, upgrading ``K/M`` to a stronger -encryption type is unlikely to be a high-priority task. - -Is is possible to upgrade the master key used for the database, if -desired. Using :ref:`kdb5_util(8)`'s **add_mkey**, **use_mkey**, and -**update_princ_encryption** commands, a new master key can be added -and activated for use on new key material, and the existing entries -converted to the new master key. |