Configuration interface (profile)

The profile interface allows a module to control how krb5 configuration information is obtained by the Kerberos library and applications. For a detailed description of the profile interface, see the header file <profile.h>.

A profile module exports a function named profile_module_init matching the signature of the profile_module_init_fn type. This function accepts a residual string, which may be used to help locate the configuration source. The function fills in a vtable and may also create a per-profile state object. If the module uses state objects, it should implement the copy and cleanup methods to manage them.

A basic read-only profile module need only implement the get_values and free_values methods. The get_values method accepts a null-terminated list of C string names (e.g. an array containing “libdefaults”, “clockskew”, and NULL for the clockskew variable in the [libdefaults] section) and returns a null-terminated list of values, which will be cleaned up with the free_values method when the caller is done with them.

Iterable profile modules must also define the iterator_create, iterator, iterator_free, and free_string methods. The core krb5 code does not require profiles to be iterable, but some applications may iterate over the krb5 profile object in order to present configuration interfaces.

Writable profile modules must also define the writable, modified, update_relation, rename_section, add_relation, and flush methods. The core krb5 code does not require profiles to be writable, but some applications may write to the krb5 profile in order to present configuration interfaces.

The following is an example of a very basic read-only profile module which returns a hardcoded value for the default_realm variable in [libdefaults], and provides no other configuration information. (For conciseness, the example omits code for checking the return values of malloc and strdup.)

#include <stdlib.h>
#include <string.h>
#include <profile.h>

static long
get_values(void *cbdata, const char *const *names, char ***values)
{
    if (names[0] != NULL && strcmp(names[0], "libdefaults") == 0 &&
        names[1] != NULL && strcmp(names[1], "default_realm") == 0) {
        *values = malloc(2 * sizeof(char *));
        (*values)[0] = strdup("ATHENA.MIT.EDU");
        (*values)[1] = NULL;
        return 0;
    }
    return PROF_NO_RELATION;
}

static void
free_values(void *cbdata, char **values)
{
    char **v;

    for (v = values; *v; v++)
        free(*v);
    free(values);
}

long
profile_module_init(const char *residual, struct profile_vtable *vtable,
                    void **cb_ret);

long
profile_module_init(const char *residual, struct profile_vtable *vtable,
                    void **cb_ret)
{
    *cb_ret = NULL;
    vtable->get_values = get_values;
    vtable->free_values = free_values;
    return 0;
}