Projects/Password expiration API

An announcement has been sent to krbdev@mit.edu starting a review of this project. That review will conclude on August 13, 2010.

Comments can be sent to krbdev@mit.edu.

This project is to add a client API giving programmatic access to password expiration as conveyed in an AS request.

Background

There are two places in the encrypted part of a KDC reply which can indicate the time of password expiration: the key-expiration field, which is a timestamp, and the last-req field, which is a sequence of tagged timestamps. These fields exist for both AS and TGS requests, but are typically omitted in TGS requests.

According to RFC 4120, the key-expiration field is deprecated, and should contain the minimum of the password and account expiration fields. The MIT KDC fills this field in with the account expiration time; this is a bug (#2032 in RT). The Heimdal KDC correctly fills in this field.

last-req entries with tags of 6 or -6 convey password expiration time; last-req entries with tags 7 or -7 convey account expiration time. Positive tags refer to all servers and negative tags to only one server for the realm; this distinction has meaning for other kinds of last-req entries but not for expiry. The MIT KDC never includes last-req information. The Heimdal KDC provides last-req information for account expiration, and for password expiration only if the password will expire within a configurable amount of time from the current time.

In the MIT krb5 client code as of release 1.8, krb5_get_init_creds_password examines the key-expiration and last-req fields with the following behavior:

• If the key-expiration field indicates a positive timestamp within the next seven days, the prompter is invoked with no prompts, and a banner containing an English string in one of three formats. Each format indicates that the password will expire and roughly when.

• Otherwise, if a last-req entry with tag 6 or -6 exists, the prompter is invoked as above, using one of three slightly different formats. No bounds check on the last-req value is performed since it is assumed that such a last-req entry would only be included if the KDC desires a warning to be issued (as in Heimdal).

The current client behavior does not give applications programmatic control over expiration warnings.

Proposal

Bug #2032 should be fixed in the KDC. This is a simple matter and is out of scope for the project.

A new get_init_creds option will be added as follows:

 typedef void
 krb5_expire_callback_func(krb5_context context, void *data,
                           krb5_timestamp password_expiration,
                           krb5_timestamp account_expiration,
                           krb5_boolean is_last_req);

 krb5_error_code KRB5_CALLCONV
 krb5_get_init_creds_opt_set_expire_callback(krb5_context context,
                                             krb5_get_init_creds_opt *opt,
                                             krb5_expiration_callback_func cb,
                                             void *data);

If this callback is provided, the prompter will not be invoked with warning messages. Instead, the callback will be invoked as follows:

 * If last-req entries with tags 6, -6, 7, or -7 exist, those will be used for the password and account expiration timestamps (0 if one or the other is not specified), and is_last_req will be true.

 * Otherwise, password_expiration will be the key-expiration value (which may be 0), account_expiration will be 0, and is_last_req will be false.