logo_kerberos.gif

Difference between revisions of "Projects/Principal entry string mapping"

From K5Wiki
Jump to: navigation, search
(Admin Protocol)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{project-early}}
+
{{project-rel|1.10}}
{{project-target|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 mappings.
+
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==
 
==Background==
Line 11: Line 11:
 
==Data Model==
 
==Data Model==
   
Principal entries will gain a mapping from UTF-8 keys to UTF-8 values, 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.
+
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.
   
Mappings 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.
+
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==
 
==Interface Design==
Line 22: Line 22:
   
 
* get_strings, getstrs: View string attributes a principal.
 
* get_strings, getstrs: View string attributes a principal.
* set_string, setstr: Set a string attribute on a principal.
+
* set_string, setstr: Change or add a string attribute on a principal.
 
* del_string, delstr: Remove a string attribute from a principal.
 
* del_string, delstr: Remove a string attribute from a principal.
   
Line 29: Line 29:
 
===Admin Protocol===
 
===Admin Protocol===
   
The tl-data representation of string mappings will guaranteed across the kadmin protocol. Instead, new RPCs will be added:
+
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 mappings on an entry.
+
* get_strings: Get the list of string attributes on an entry.
* set_string: Change or unset a string attribute 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:
 
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,
 
kadm5_ret_t kadm5_get_strings(void *server_handle,
 
krb5_principal principal,
 
krb5_principal principal,
Line 52: Line 57:
 
===Propagation and Backup===
 
===Propagation and Backup===
   
The tl-data representation of string mappings will be exposed in the dump file format and incremental propagation protocols.
+
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===
 
===libkdb API===
   
The following accessors allow string mappings for an entry to be manipulated:
+
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_error_code
 
krb5_dbe_get_strings(krb5_context context, krb5_db_entry *entry,
 
krb5_dbe_get_strings(krb5_context context, krb5_db_entry *entry,
krb5_string_attr ***strings_out);
+
krb5_string_attr **strings_out, int *count_out);
+
 
krb5_error_code
 
krb5_error_code
 
krb5_dbe_get_string(krb5_context context, krb5_db_entry *entry,
 
krb5_dbe_get_string(krb5_context context, krb5_db_entry *entry,
Line 69: Line 74:
 
krb5_dbe_set_string(krb5_context context, krb5_db_entry *entry,
 
krb5_dbe_set_string(krb5_context context, krb5_db_entry *entry,
 
const char *key, const char *value);
 
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.

Latest revision as of 12:20, 11 November 2011

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.