From: Greg Hudson Date: Mon, 3 Dec 2012 18:24:36 +0000 (-0500) Subject: Document account lockout configuration X-Git-Tag: krb5-1.12-alpha1~445 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=3ad47a81c7e0e8a8952251e22e0056548597f462;p=thirdparty%2Fkrb5.git Document account lockout configuration ticket: 7477 (new) target_version: 1.11 tags: pullup --- diff --git a/doc/admin/index.rst b/doc/admin/index.rst index 0bcf77aa7c..b27354abbc 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 0000000000..8260cb2367 --- /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@KRBTEST.COM: + kinit: Password incorrect while getting initial credentials + $ kinit user + Password for user@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@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.