krb5 commit [krb5-1.11]: Document account lockout configuration

[Tom Yu]

https://github.com/krb5/krb5/commit/97808aa54e315be8b919d1df6dab4dd828392789
commit 97808aa54e315be8b919d1df6dab4dd828392789
Author: Greg Hudson <ghudson at mit.edu>
Date:   Mon Dec 3 13:24:36 2012 -0500

    Document account lockout configuration
    
    (cherry picked from commit 3ad47a81c7e0e8a8952251e22e0056548597f462)
    
    ticket: 7477
    version_fixed: 1.11
    status: resolved

 doc/admin/index.rst   |    1 +
 doc/admin/lockout.rst |  140 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 141 insertions(+), 0 deletions(-)

diff --git a/doc/admin/index.rst b/doc/admin/index.rst
index 0bcf77a..b27354a 100644
--- a/doc/admin/index.rst
+++ b/doc/admin/index.rst
@@ -8,6 +8,7 @@ For administrators
    conf_files/index.rst
    realm_config.rst
    database.rst
+   lockout.rst
    conf_ldap.rst
    appl_servers.rst
    host_config.rst
diff --git a/doc/admin/lockout.rst b/doc/admin/lockout.rst
new file mode 100644
index 0000000..8260cb2
--- /dev/null
+++ b/doc/admin/lockout.rst
@@ -0,0 +1,140 @@
+Account lockout
+===============
+
+As of release 1.8, the KDC can be configured to lock out principals
+after a number of failed authentication attempts within a period of
+time.  Account lockout can make it more difficult to attack a
+principal's password by brute force, but also makes it easy for an
+attacker to deny access to a principal.
+
+
+Configuring account lockout
+---------------------------
+
+Account lockout only works for principals with the
+**+requires_preauth** flag set.  Without this flag, the KDC cannot
+know whether or not a client successfully decrypted the ticket it
+issued.  It is also important to set the **-allow_svr** flag on a
+principal to protect its password from an off-line dictionary attack
+through a TGS request.  You can set these flags on a principal with
+:ref:`kadmin(1)` as follows::
+
+    kadmin: modprinc +requires_preauth -allow_svr PRINCNAME
+
+Account lockout parameters are configured via password policies.  The
+policy parameters are:
+
+* **maxfailure**: the maximum number of failed attempts before the
+  principal is locked out.  For example, if **maxfailure** is set to
+  10, the principal would be locked out after ten failed attempts.
+  The counter of failed attempts resets to 0 after a successful
+  attempt to authenticate.  A **maxfailure** value of 0 (the default)
+  disables account lockout.
+
+* **failurecountinterval**: if this interval elapses between failed
+  attempts, the counter of failed attempts resets to 1 for the most
+  recent failure.  A **failurecountinterval** of 0 (the default) means
+  the counter only resets on a successful attempt to authenticate.
+
+* **lockoutduration**: if a principal is locked out, it remains locked
+  out for this amount of time.  A **lockoutduration** of 0 (the
+  default) means the principal remains locked out until it is
+  administratively unlocked.
+
+Here is an example of setting these attributes on a new policy and
+associating it with a principal::
+
+    kadmin: addpol -maxfailure 10 -failurecountinterval 180
+        -lockoutduration 60 lockout_policy
+    kadmin: modprinc -policy lockout_policy PRINCNAME
+
+
+Testing account lockout
+-----------------------
+
+To test that account lockout is working, try authenticating as the
+principal (hopefully not one that might be in use) multiple times with
+the wrong password.  For instance, if **maxfailure** is set to 2, you
+might see::
+
+    $ kinit user
+    Password for user at KRBTEST.COM:
+    kinit: Password incorrect while getting initial credentials
+    $ kinit user
+    Password for user at KRBTEST.COM:
+    kinit: Password incorrect while getting initial credentials
+    $ kinit user
+    kinit: Clients credentials have been revoked while getting initial credentials
+
+
+Account lockout principal state
+-------------------------------
+
+A principal entry keeps three pieces of state related to account
+lockout:
+
+* The time of last successful authentication
+* The time of last failed authentication
+* A counter of failed attempts
+
+The time of last successful authentication is not actually needed for
+the account lockout system to function, but may be of administrative
+interest.  These fields can be observed with the **getprinc** kadmin
+command.  For example::
+
+    kadmin: getprinc user
+    Principal: user at KRBTEST.COM
+    ...
+    Last successful authentication: [never]
+    Last failed authentication: Mon Dec 03 12:30:33 EST 2012
+    Failed password attempts: 2
+    ...
+
+A principal which has been locked out can be administratively unlocked
+with the **-unlock** option to the **modprinc** kadmin command::
+
+    kadmin: modprinc -unlock PRINCNAME
+
+This command will reset the number of failed attempts to 0.
+
+
+KDC replication and account lockout
+-----------------------------------
+
+The account lockout state of a principal is not replicated between
+KDCs.  Because of this, the number of attempts an attacker can make
+within a time period is multiplied by the number of KDCs.  For
+instance, if the **maxfailure** parameter on a policy is 10 and there
+are four KDCs in the environment (a master and three slaves), an
+attacker could make as many as 40 attempts before the principal is
+locked out on all four KDCs.
+
+An administrative unlock is propagated from the master to the slave
+KDCs during the next propagation.  Propagation of an administrative
+unlock will cause the counter of failed attempts on each slave to
+reset to 1 on the next failure.
+
+
+KDC performance and account lockout
+-----------------------------------
+
+In order to fully track account lockout state, the KDC must write to
+the the database on each successful and failed authentication.
+Writing to the database is generally more expensive than reading from
+it, so these writes may have a significant impact on KDC performance.
+As of release 1.9, it is possible to turn off account lockout state
+tracking in order to improve performance, by setting the
+**disable_last_success** and **disable_lockout** variables in the
+database module subsection of :ref:`kdc.conf(5)`.  For example::
+
+    [dbmodules]
+        DB = {
+            disable_last_success = true
+            disable_lockout = true
+        }
+
+Of the two variables, setting **disable_last_success** will usually
+have the largest positive impact on performance, and will still allow
+account lockout policies to operate.  However, it will make it
+impossible to observe the last successful authentication time with
+kadmin.