diff options
author | Greg Hudson <ghudson@mit.edu> | 2012-12-03 13:24:36 -0500 |
---|---|---|
committer | Greg Hudson <ghudson@mit.edu> | 2012-12-03 13:26:15 -0500 |
commit | 3ad47a81c7e0e8a8952251e22e0056548597f462 (patch) | |
tree | 28773c836b8ae9a1e240f1297bdcaac366005baf /doc/admin/lockout.rst | |
parent | e5b3c98f2bdd5dfea1eee75edca8dcdf4af3bb0b (diff) | |
download | krb5-3ad47a81c7e0e8a8952251e22e0056548597f462.tar.gz krb5-3ad47a81c7e0e8a8952251e22e0056548597f462.tar.xz krb5-3ad47a81c7e0e8a8952251e22e0056548597f462.zip |
Document account lockout configuration
ticket: 7477 (new)
target_version: 1.11
tags: pullup
Diffstat (limited to 'doc/admin/lockout.rst')
-rw-r--r-- | doc/admin/lockout.rst | 140 |
1 files changed, 140 insertions, 0 deletions
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. |