Projects/Principal entry string mapping

This project was completed in release 1.10.

This project will add string attributes to krb5 principal entries in the KDB, along with kadmin support for displaying and modifying string attributes. KDC plugins (such as preauth plugins) will be able to examine string attributes.

Background

KDC plugins may need to associate data with principal entries which is not known to the core Kerberos code base. For instance, an OTP preauth plugin needs to know what kind of token is associated with a principal and may also need type-specific information about the token.

Principal entries are extensible through tl-data entries, which have two important limitations for this purpose. First, tl-data keys are centrally assigned integers in a 32-bit number space, so plugin developers would need cooperation from the core code base to get keys assigned. Second, there is no general admin user interface for populating tl-data entries in principals.

Data Model

Principal entries will gain a mapping from keys to values (both C strings), stored via tl-data. We assume that strings attributes will be fairly short and limited in number, so no great attention is needed to efficiency. Keys are unique (a given key has only one value). There are no guarantees of any particular key order when string attributes are retrieved. There is no particular discipline for assigning keys names; we assume that plugins will use prefixes like "otp-" to avoid conflicts. At least initially, there will be no validation on values to ensure that they are well-formed for the consuming plugin, although this could be added in the future by adding validation methods to KDC plugin interfaces.

String attributes will be represented by a tl-data value containing a concatenation of alternating zero-terminated key and value strings. This representation is incidentally visible across the kadmin protocol but is explicitly not guaranteed at that layer.

Interface Design

User Interface

The following kadmin commands will be added:

• get_strings, getstrs: View string attributes a principal.
• set_string, setstr: Change or add a string attribute on a principal.
• del_string, delstr: Remove a string attribute from a principal.

get_strings takes one argument, a principal name. set_string takes three arguments: a principal name, a key, and a value. del_string takes two arguments: a principal name and a value.

Admin Protocol

The tl-data representation of string attributes is explicitly not guaranteed across the kadmin protocol. Instead, new RPCs will be added:

• get_strings: Get the list of string attributes on an entry.
• set_string: Change, add, or delete (with a null value) a string attribute on an entry.

The function signatures for these RPCs are:

typedef struct krb5_string_attr_st {
    char *key;
    char *value;
} krb5_string_attr;

kadm5_ret_t    kadm5_get_strings(void *server_handle,
                                 krb5_principal principal,
                                 krb5_string_attr ***strings_out,
                                 int *count_out);

kadm5_ret_t    kadm5_set_string(void *server_handle,
                                krb5_principal principal,
                                const char *key,
                                const char *value);

kadm5_ret_t    kadm5_free_strings(void *server_handle,
                                  krb5_string_attr **strings,
                                  int count);

Propagation and Backup

The tl-data representation of string attributes will be exposed in the dump file format and incremental propagation protocols. As a result, no code modifications will be required for these facilities.

libkdb API

The following accessors allow string attributes for an entry to be manipulated (set_string with a null value deletes a key; get_string returns a null value for a nonexistent key):

krb5_error_code
krb5_dbe_get_strings(krb5_context context, krb5_db_entry *entry,
                     krb5_string_attr **strings_out, int *count_out);

krb5_error_code
krb5_dbe_get_string(krb5_context context, krb5_db_entry *entry,
                    const char *key, char **value_out);

krb5_error_code
krb5_dbe_set_string(krb5_context context, krb5_db_entry *entry,
                    const char *key, const char *value);

void
krb5_dbe_free_strings(krb5_context, krb5_string_attr *, int count);

void
krb5_dbe_free_string(krb5_context, char *);

krb5_dbe_set_string can return KRB5_KDB_STRINGS_TOOLONG if the resulting attribute set won't fit in a tl-data value (64K).

Release notes

Administrator experience:

• Add support for string attributes on principal entries.