1.. _profile_plugin: 2 3Configuration interface (profile) 4================================= 5 6The profile interface allows a module to control how krb5 7configuration information is obtained by the Kerberos library and 8applications. For a detailed description of the profile interface, 9see the header file ``<profile.h>``. 10 11.. note:: 12 13 The profile interface does not follow the normal conventions 14 for MIT krb5 pluggable interfaces, because it is part of a 15 lower-level component of the krb5 library. 16 17As with other types of plugin modules, a profile module is a Unix 18shared object or Windows DLL, built separately from the krb5 tree. 19The krb5 library will dynamically load and use a profile plugin module 20if it reads a ``module`` directive at the beginning of krb5.conf, as 21described in :ref:`profile_plugin_config`. 22 23A profile module exports a function named ``profile_module_init`` 24matching the signature of the profile_module_init_fn type. This 25function accepts a residual string, which may be used to help locate 26the configuration source. The function fills in a vtable and may also 27create a per-profile state object. If the module uses state objects, 28it should implement the **copy** and **cleanup** methods to manage 29them. 30 31A basic read-only profile module need only implement the 32**get_values** and **free_values** methods. The **get_values** method 33accepts a null-terminated list of C string names (e.g., an array 34containing "libdefaults", "clockskew", and NULL for the **clockskew** 35variable in the :ref:`libdefaults` section) and returns a 36null-terminated list of values, which will be cleaned up with the 37**free_values** method when the caller is done with them. 38 39Iterable profile modules must also define the **iterator_create**, 40**iterator**, **iterator_free**, and **free_string** methods. The 41core krb5 code does not require profiles to be iterable, but some 42applications may iterate over the krb5 profile object in order to 43present configuration interfaces. 44 45Writable profile modules must also define the **writable**, 46**modified**, **update_relation**, **rename_section**, 47**add_relation**, and **flush** methods. The core krb5 code does not 48require profiles to be writable, but some applications may write to 49the krb5 profile in order to present configuration interfaces. 50 51The following is an example of a very basic read-only profile module 52which returns a hardcoded value for the **default_realm** variable in 53:ref:`libdefaults`, and provides no other configuration information. 54(For conciseness, the example omits code for checking the return 55values of malloc and strdup.) :: 56 57 #include <stdlib.h> 58 #include <string.h> 59 #include <profile.h> 60 61 static long 62 get_values(void *cbdata, const char *const *names, char ***values) 63 { 64 if (names[0] != NULL && strcmp(names[0], "libdefaults") == 0 && 65 names[1] != NULL && strcmp(names[1], "default_realm") == 0) { 66 *values = malloc(2 * sizeof(char *)); 67 (*values)[0] = strdup("ATHENA.MIT.EDU"); 68 (*values)[1] = NULL; 69 return 0; 70 } 71 return PROF_NO_RELATION; 72 } 73 74 static void 75 free_values(void *cbdata, char **values) 76 { 77 char **v; 78 79 for (v = values; *v; v++) 80 free(*v); 81 free(values); 82 } 83 84 long 85 profile_module_init(const char *residual, struct profile_vtable *vtable, 86 void **cb_ret); 87 88 long 89 profile_module_init(const char *residual, struct profile_vtable *vtable, 90 void **cb_ret) 91 { 92 *cb_ret = NULL; 93 vtable->get_values = get_values; 94 vtable->free_values = free_values; 95 return 0; 96 } 97