1General plugin concepts 2======================= 3 4A krb5 dynamic plugin module is a Unix shared object or Windows DLL. 5Typically, the source code for a dynamic plugin module should live in 6its own project with a build system using automake_ and libtool_, or 7tools with similar functionality. 8 9A plugin module must define a specific symbol name, which depends on 10the pluggable interface and module name. For most pluggable 11interfaces, the exported symbol is a function named 12``INTERFACE_MODULE_initvt``, where *INTERFACE* is the name of the 13pluggable interface and *MODULE* is the name of the module. For these 14interfaces, it is possible for one shared object or DLL to implement 15multiple plugin modules, either for the same pluggable interface or 16for different ones. For example, a shared object could implement both 17KDC and client preauthentication mechanisms, by exporting functions 18named ``kdcpreauth_mymech_initvt`` and ``clpreauth_mymech_initvt``. 19 20.. note: The profile, locate, and GSSAPI mechglue pluggable interfaces 21 follow different conventions. See the documentation for 22 those interfaces for details. The remainder of this section 23 applies to pluggable interfaces which use the standard 24 conventions. 25 26A plugin module implementation should include the header file 27``<krb5/INTERFACE_plugin.h>``, where *INTERFACE* is the name of the 28pluggable interface. For instance, a ccselect plugin module 29implementation should use ``#include <krb5/ccselect_plugin.h>``. 30 31.. note: clpreauth and kdcpreauth module implementations should 32 include <krb5/preauth_plugin.h>. 33 34initvt functions have the following prototype:: 35 36 krb5_error_code interface_modname_initvt(krb5_context context, 37 int maj_ver, int min_ver, 38 krb5_plugin_vtable vtable); 39 40and should do the following: 41 421. Check that the supplied maj_ver argument is supported by the 43 module. If it is not supported, the function should return 44 KRB5_PLUGIN_VER_NOTSUPP. 45 462. Cast the supplied vtable pointer to the structure type 47 corresponding to the major version, as documented in the pluggable 48 interface header file. 49 503. Fill in the structure fields with pointers to method functions and 51 static data, stopping at the field indicated by the supplied minor 52 version. Fields for unimplemented optional methods can be left 53 alone; it is not necessary to initialize them to NULL. 54 55In most cases, the context argument will not be used. The initvt 56function should not allocate memory; think of it as a glorified 57structure initializer. Each pluggable interface defines methods for 58allocating and freeing module state if doing so is necessary for the 59interface. 60 61Pluggable interfaces typically include a **name** field in the vtable 62structure, which should be filled in with a pointer to a string 63literal containing the module name. 64 65Here is an example of what an initvt function might look like for a 66fictional pluggable interface named fences, for a module named 67"wicker":: 68 69 krb5_error_code 70 fences_wicker_initvt(krb5_context context, int maj_ver, 71 int min_ver, krb5_plugin_vtable vtable) 72 { 73 krb5_ccselect_vtable vt; 74 75 if (maj_ver == 1) { 76 krb5_fences_vtable vt = (krb5_fences_vtable)vtable; 77 vt->name = "wicker"; 78 vt->slats = wicker_slats; 79 vt->braces = wicker_braces; 80 } else if (maj_ver == 2) { 81 krb5_fences_vtable_v2 vt = (krb5_fences_vtable_v2)vtable; 82 vt->name = "wicker"; 83 vt->material = wicker_material; 84 vt->construction = wicker_construction; 85 if (min_ver < 2) 86 return 0; 87 vt->footing = wicker_footing; 88 if (min_ver < 3) 89 return 0; 90 vt->appearance = wicker_appearance; 91 } else { 92 return KRB5_PLUGIN_VER_NOTSUPP; 93 } 94 return 0; 95 } 96 97Logging from KDC and kadmind plugin modules 98------------------------------------------- 99 100Plugin modules for the KDC or kadmind daemons can write to the 101configured logging outputs (see :ref:`logging`) by calling the 102**com_err** function. The first argument (*whoami*) is ignored. If 103the second argument (*code*) is zero, the formatted message is logged 104at informational severity; otherwise, the formatted message is logged 105at error severity and includes the error message for the supplied 106code. Here are examples:: 107 108 com_err("", 0, "Client message contains %d items", nitems); 109 com_err("", retval, "while decoding client message"); 110 111(The behavior described above is new in release 1.17. In prior 112releases, the *whoami* argument is included for some logging output 113types, the logged message does not include the usual header for some 114output types, and the severity for syslog outputs is configured as 115part of the logging specification, defaulting to error severity.) 116 117.. _automake: https://www.gnu.org/software/automake/ 118.. _libtool: https://www.gnu.org/software/libtool/ 119