Projects/Principal entry string mapping

An announcement has been sent to krbdev@mit.edu starting a review of this project. That review will conclude on 2011-09-22.

Comments can be sent to krbdev@mit.edu.

This project is targeted at 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 and 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. 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: Set 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 or unset a string attribute on an entry.

The function signatures for these RPCs are:

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:

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 *);