krb5 commit: Add documentation on dictionary attacks

https://github.com/krb5/krb5/commit/93204537f12ef6b7de86d9a82423bcacc2005537
commit 93204537f12ef6b7de86d9a82423bcacc2005537
Author: Greg Hudson <[email protected]>
Date:   Thu Jun 14 17:51:43 2018 -0400

    Add documentation on dictionary attacks
    
    ticket: 8694 (new)

 doc/admin/dictionary.rst |   88 ++++++++++++++++++++++++++++++++++++++++++++++
 doc/admin/index.rst      |    1 +
 doc/admin/lockout.rst    |    2 +
 doc/admin/spake.rst      |   12 ++++---
 4 files changed, 98 insertions(+), 5 deletions(-)

diff --git a/doc/admin/dictionary.rst b/doc/admin/dictionary.rst
new file mode 100644
index 0000000..a5c5786
--- /dev/null
+++ b/doc/admin/dictionary.rst
@@ -0,0 +1,88 @@
+.. _dictionary:
+
+Addressing dictionary attack risks
+==================================
+
+Kerberos initial authentication is normally secured using the client
+principal's long-term key, which for users is generally derived from a
+password.  Using a pasword-derived long-term key carries the risk of a
+dictionary attack, where an attacker tries a sequence of possible
+passwords, possibly requiring much less effort than would be required
+to try all possible values of the key.  Even if :ref:`password policy
+objects <policies>` are used to force users not to pick trivial
+passwords, dictionary attacks can sometimes be successful against a
+significant fraction of the users in a realm.  Dictionary attacks are
+not a concern for principals using random keys.
+
+A dictionary attack may be online or offline.  An online dictionary
+attack is performed by trying each password in a separate request to
+the KDC, and is therefore visible to the KDC and also limited in speed
+by the KDC's processing power and the network capacity between the
+client and the KDC.  Online dictionary attacks can be mitigated using
+:ref:`account lockout <lockout>`.  This measure is not totally
+satisfactory, as it makes it easy for an attacker to deny access to a
+client principal.
+
+An offline dictionary attack is performed by obtaining a ciphertext
+generated using the password-derived key, and trying each password
+against the ciphertext.  This category of attack is invisible to the
+KDC and can be performed much faster than an online attack.  The
+attack will generally take much longer with more recent encryption
+types (particularly the ones based on AES), because those encryption
+types use a much more expensive string-to-key function.  However, the
+best defense is to deny the attacker access to a useful ciphertext.
+The required defensive measures depend on the attacker's level of
+network access.
+
+An off-path attacker has no access to packets sent between legitimate
+users and the KDC.  An off-path attacker could gain access to an
+attackable ciphertext either by making an AS request for a client
+principal which does not have the **+requires_preauth** flag, or by
+making a TGS request (after authenticating as a different user) for a
+server principal which does not have the **-allow_svr** flag.  To
+address off-path attackers, a KDC administrator should set those flags
+on principals with password-derived keys::
+
+    kadmin: add_principal +requires_preauth -allow_svr princname
+
+An attacker with passive network access (one who can monitor packets
+sent between legitimate users and the KDC, but cannot change them or
+insert their own packets) can gain access to an attackable ciphertext
+by observing an authentication by a user using the most common form of
+preauthentication, encrypted timestamp.  Any of the following methods
+can prevent dictionary attacks by attackers with passive network
+access:
+
+* Enabling :ref:`SPAKE preauthentication <spake>` (added in release
+  1.17) on the KDC, and ensuring that all clients are able to support
+  it.
+
+* Using an :ref:`HTTPS proxy <https>` for communication with the KDC,
+  if the attacker cannot monitor communication between the proxy
+  server and the KDC.
+
+* Using FAST, protecting the initial authentication with either a
+  random key (such as a host key) or with :ref:`anonymous PKINIT
+  <anonymous_pkinit>`.
+
+An attacker with active network access (one who can inject or modify
+packets sent between legitimate users and the KDC) can try to fool the
+client software into sending an attackable ciphertext using an
+encryption type and salt string of the attacker's choosing.  Any of the
+following methods can prevent dictionary attacks by active attackers:
+
+* Enabling SPAKE preauthentication and setting the
+  **disable_encrypted_timestamp** variable to ``true`` in the
+  :ref:`realms` subsection of the client configuration.
+
+* Using an HTTPS proxy as described above, configured in the client's
+  krb5.conf realm configuration.  If :ref:`KDC discovery
+  <kdc_discovery>` is used to locate a proxy server, an active
+  attacker may be able to use DNS spoofing to cause the client to use
+  a different HTTPS server or to not use HTTPS.
+
+* Using FAST as described above.
+
+If :ref:`PKINIT <pkinit>` or :ref:`OTP <otp_preauth>` are used for
+initial authentication, the principal's long-term keys are not used
+and dictionary attacks are usually not a concern.
diff --git a/doc/admin/index.rst b/doc/admin/index.rst
index fbe5e42..d87b003 100644
--- a/doc/admin/index.rst
+++ b/doc/admin/index.rst
@@ -17,6 +17,7 @@ For administrators
    pkinit.rst
    otp.rst
    spake.rst
+   dictionary.rst
    princ_dns.rst
    enctypes.rst
    https.rst
diff --git a/doc/admin/lockout.rst b/doc/admin/lockout.rst
index c7e4e33..446b91d 100644
--- a/doc/admin/lockout.rst
+++ b/doc/admin/lockout.rst
@@ -1,3 +1,5 @@
+.. _lockout:
+
 Account lockout
 ===============
 
diff --git a/doc/admin/spake.rst b/doc/admin/spake.rst
index 4f6eeaf..8b9f471 100644
--- a/doc/admin/spake.rst
+++ b/doc/admin/spake.rst
@@ -1,12 +1,14 @@
+.. _spake:
+
 SPAKE Preauthentication
 =======================
 
 SPAKE preauthentication (added in release 1.17) uses public key
-cryptography techniques to protect against password dictionary
-attacks.  Unlike :ref:`PKINIT <pkinit>`, it does not require any
-additional infrastructure such as certificates; it simply needs to be
-turned on.  Using SPAKE preauthentication may modestly increase the
-CPU and network load on the KDC.
+cryptography techniques to protect against :ref:`password dictionary
+attacks <dictionary>`.  Unlike :ref:`PKINIT <pkinit>`, it does not
+require any additional infrastructure such as certificates; it simply
+needs to be turned on.  Using SPAKE preauthentication may modestly
+increase the CPU and network load on the KDC.
 
 SPAKE preauthentication can use one of four elliptic curve groups for
 its password-authenticated key exchange.  The recommended group is