Projects/Lockout

This is an early stage project for MIT Kerberos. It is being fleshed out by its proponents. Feel free to help flesh out the details of this project. After the project is ready, it will be presented for review and approval.

Background

This project aims to provide principal lockout functionality similar to that of Active Directory. After a certain number of preauthentication failures with a given time limit, a principal will be locked out from authenticating for a certain period of time.

Design

Lockout policy

There are three attributes which will be associated with a Kerberos policy:

• pw_max_fail (number of attempts)
• pw_failcnt_interval (period after which bad preauthentication count will be reset)
• pw_lockout_duration (period in which lockout is enforced; a duration of zero means that the principal must be manually unlocked)

There are four attributes which will be associated with each principal:

• last_success (time of last preauthentication success)
• last_failed (time of last preauthentication failure)
• fail_auth_count (number of preauthentication failures)
• lockout time

These are non-replicated attributes. The lockout time is stored in TL data; all other attributes reuse existing fields in the principal entry.

Replication

For DB2 backends, per-principal lockout state will be per KDC: replicated updates will not overwrite this information. Thus, the effective value of pw_max_fail is N * pw_max_fail, where N is the number of KDCs in the realm.

For LDAP backends, we will rely on the LDAP server to update the lockout count; we assume a password policy confirming LDAP server.

Mapping to LDAP password policy draft

• pw_max_fail - pwdMaxFailure
• pw_failcnt_interval - pwdFailureCountInterval
• pw_lockout_duration duration - pwdLockoutDuration

• last_failed - pwdFailureTime
• fail_auth_count - number of preauthentication failures (within observation window) - n(pwdFailureTime)
• KRB5_TL_LOCKED_TIME - pwdAccountLockedTime

Before authentication

Check whether account is already locked out:

if (locked_time != 0 &&
     stamp < locked_time + lockout_duration)
    return kdc_err_client_revoked

Implementation details

kdb5_util

Two new dump formats are defined:

• kdb5_util load_dump version 6
• ipropx

The former is the new default version; the previous version can be requested with the -r13 option to kdb5_util. The ipropx format is specified by passing the -iN option when dumping (where N is a version number indicating the highest version the caller is willing to accept). There is no corresponding option on load, as the header contains the version information.

The principal change is support for replicating lockout policies. The policy dump format now contains (effectively) an extensibility marker, in that unknown fields after the last recognised field are ignored.

The ipropx format also adds a version number:

ipropx version last_sno last_seconds last_useconds

Finally, kdb5_util passes the "merge_nra" argument to the database. The backend can use this as a hint to merge non-replicated attributes from the previous instance upon promotion.

kprop/iprop

This is the most complicated part: in order to provide per-KDC lockout counts, as well as support replication of lockout policy, some changes have been made to the replication protocols.

We define the following attributes of a principal as non-replicated attributes:

• last_success
• last_failed
• fail_auth_count
• any TL data values with a negative TL data type

Non-replicated attributes have the following properties:

• they are not sent to replicas (TL data types are omitted; other fields set to zero)
• when applying incremental updates, they are masked out
• when applying full updates, the values from the existing database are merged in

A new RPC is added to the iprop service, IPROP_FULL_RESYNC_EXT. This adds an integer argument indicating the highest ipropx dump format the caller is willing to accept. The iprop service passes this argument to kdb5_util when generating the dump.

kadmin

A new kadm5 API version is defined, KADM5_API_VERSION_3. This adds support for managing lockout policies as well as the per-principal lockout time. The client library will fall back to KADM5_API_VERSION_2 if the remote server does not support the protocol variant. The RPC protocol itself has not changed (no new procedures are added). Instead, additional fields are encoded at the XDR layer based on the negotiated version.

#define KADM5_PW_MAX_FAILURE           0x100000
#define KADM5_PW_FAILURE_COUNT_INTERVAL        0x200000
#define KADM5_PW_LOCKOUT_DURATION      0x400000

#define KADM5_API_VERSION_3    (KADM5_API_VERSION_MASK|0x03)

The following field is added to kadm5_principal_ent_rec, conditional on KADM5_API_VERSION_3:

krb5_timestamp locked_time;

The following fields are added to kadm5_policy_ent_rec, conditional on KADM5_API_VERSION_3:

krb5_kvno       pw_max_fail;
krb5_deltat     pw_failcnt_interval;
krb5_deltat     pw_lockout_duration;

Tools

kadmin

kadmin has been enhanced with the following arguments for managing lockout policies:

• -maxfailure
• -failurecountinterval
• -lockoutduration

Additionally, one can pass the -unlock option to modprinc to explicitly force a principal to be unlocked.