Projects/Lockout

This project was completed in release 1.8.

Background

This project aims to provide principal lockout functionality similar to that of Active Directory and the LDAP password policy draft (draft-behera-ldap-password-policy). 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.

Note: lockout only works with principals that require preauthentication.

Design

Lockout policy

There are three new attributes associated with a Kerberos administrative policy:

• pw_max_fail (maximum number of attempts before lockout)
• 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 associated with a principal:

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

Only the latter is actually a new attribute. These four attributes are non-replicated: that is, each KDC has its own set of values. The lockout time is stored in TL data; all other attributes reuse existing fields in the principal entry. (However, the lockout time is surfaced as an explicit attribute at the kadm5 layer.)

UPDATE: The lockout time attribute was removed from the implementation before it was merged to the trunk, and computed dynamically from the other principal fields and the policy fields.

Mapping to LDAP password policy draft

This mapping is provided for convenience only; no attempt has been made to re-use the same attribute names for the LDAP KDB backend, owing to the existing divergence between the two schema.

Attribute mapping

kadm5 attribute	draft-behera-ldap-password-policy	KDB LDAP schema
pw_max_fail	pwdMaxFailure	krbPwdMaxFailure
pw_failcnt_interval	pwdFailureCountInterval	krbPwdFailureCountInterval
pw_lockout_duration	pwdLockoutDuration	krbPwdLockoutDuration
last_success	-	krbLastSuccessfulAuth
last_failed	pwdFailureTime	krbLastFailedAuth
fail_auth_count	n(failures in window)	krbLoginFailedCount
locked_time	pwdAccountLockedTime	krbPwdPrincipalLockedTime

Replication

For DB2 backends, per-principal lockout state will be per KDC: replicated updates will not overwrite this information. (Care is taken to both avoid sending non-replicated updates, as well as to avoid updating them.) Because of this, 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 always attempt to update the lockout count; we assume the LDAP client library can chase referrals, or that it is multi-master. Ideally the administrator should be able to configure some attributes on the LDAP server as non-replicated, but doing so is vendor-specific.

Before authentication

The following pseudo-code checks whether a principal is already locked:

if ( entry.locked_time != 0 &&
      ( policy.lockout_duration == 0 ||
        now < entry.locked_time + policy.lockout_duration ) )
    result ::= CLIENT_REVOKED

After authentication

if ( preauth_success )
{
    entry.fail_auth_count ::= 0
    if (entry.locked_time)
        entry.locked_time ::= 0
    entry.last_success ::= now
}
else if ( preauth_failure )
{
    if (entry.locked_time != 0)
    {
        /* automatically unlock account if required */
        entry.locked_time ::= 0
    }

    if (policy.failcnt_interval != 0 &&
        now > entry.last_failed + policy.failcnt_interval)
    {
        /* automatically reset fail_auth_count after failcnt_interval */
        entry.fail_auth_count ::= 0
    }

    entry.last_failed ::= now
    entry.fail_auth_count ::= entry.fail_auth_count + 1

    if (policy.max_fail != 0 &&
        entry.fail_auth_count >= policy.max_fail)
    {
        entry.locked_time ::= now
    }
}

Implementation details

KDC

Lockout policy is implemented within the backend itself; the previous code that managed static lockouts on the master KDC has been removed. The implementation makes use of the KRB5_KDB_METHOD_CHECK_POLICY_AS and KRB5_KDB_METHOD_AUDIT_AS methods introduced in MIT 1.7, so no architectural changes to the KDC were required.

KRB5_KDB_METHOD_CHECK_POLICY_AS

This implements the logic described in "before authentication", above. The policy associated with the principal is retrieved from the policy database, and then it is determined whether the account is locked. If the account is locked, KRB5KDC_ERR_CLIENT_REVOKED is returned.

KRB5_KDB_METHOD_AUDIT_AS

This implements the logic described in "after authentication", above.

Backend-specific implementation notes follow:

DB2

If the entry needs to be updated, it is updated directly with krb5_db2_db_put_principal(); thus, this modification is not added to the update (replication) log. This should not present a problem as the only attributes being managed are non-replicated ones.

LDAP

Presently, if the entry needs to be updated, it is updated directly with krb5_ldap_put_principal(). If the LDAP server we are connected to supports RFC 4525 (modify increment), then we use that to atomically update krbLoginFailedCount; otherwise, we assert the old value. Unfortunately, it's not possible to assert the old value if the failed count was previously zero, as krb5_ldap_put_principal() has no way of distinguishing between the attribute being previously absent and it being zero-valued. (True, if this was really a problem, we could use some magic TL data to indicate its presence.) So, there will always be a race here. (But there is an issue anyway if the server does not support RFC 4525, because the update may fail.)

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: three integer fields are added, corresponding to the three new fields added to the policy structure. 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 to its header:

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. Note that this applies to the DB2 backend only; it's anticipated that LDAP deployments will use the directory server's native replication protocol (except perhaps for some special migration cases).

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 added to the replication log (by being committed to the database directly, or by being masked out by ulog_conv_2logentry())
• 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.

There are no changes to the behaviour of IPROP_FULL_RESYNC; kpropd will fall back to this RPC if IPROP_FULL_RESYNC_EXT is unavailable. Nor are there any changes to GET_UPDATES: there are no backwards incompatible changes to the principal data format (there is no incremental replication of policies).

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.

Open Issues

• Currently it is not possible to manually unlock a principal across all KDCs, because the lockout time is a non-replicated attribute. We could make it a replicated attribute, but this would mean that a principal automatically unlocked on the master KDC would then be unlocked on all others (because we do not distinguish between manual and automatic unlocking).
• We need to move towards convergence with the LDAP password policy draft, but that is a bigger issue and I didn't wish to begin addressing that within the limited scope of this project.

Status

Code is in the users/lhoward/lockout branch.

Currently have tested:

• lockout with DB2 backend
• v2 kadmin with v3 kadmind
• v3 kadmin with v3 kadmind
• v3 kpropd with v3 kadmind

Need to test:

• lockout with LDAP backend
• v2 kpropd with v3 kadmind
• v3 kpropd with v2 kadmind
• v3 kadmin with v2 kadmind

Review

This section documents the review of the project according to Project policy. It is divided into multiple sections. First, approvals should be listed. To list an approval type

#~~~~

on its own line. The next section is for summarizing discussion, which should take place on krbdev@mit.edu. Provide links to the archive at http://mailman.mit.edu/pipermail/krbdev/ if appropriate. Blocking objections can be noted with {{project-block}}.

Approvals

Steve 15:49, 21 September 2009 (UTC)