diff options
Diffstat (limited to 'crypto/krb5/doc/html/_sources/plugindev/general.rst.txt')
-rw-r--r-- | crypto/krb5/doc/html/_sources/plugindev/general.rst.txt | 118 |
1 files changed, 0 insertions, 118 deletions
diff --git a/crypto/krb5/doc/html/_sources/plugindev/general.rst.txt b/crypto/krb5/doc/html/_sources/plugindev/general.rst.txt deleted file mode 100644 index fba9bf6eaba4..000000000000 --- a/crypto/krb5/doc/html/_sources/plugindev/general.rst.txt +++ /dev/null @@ -1,118 +0,0 @@ -General plugin concepts -======================= - -A krb5 dynamic plugin module is a Unix shared object or Windows DLL. -Typically, the source code for a dynamic plugin module should live in -its own project with a build system using automake_ and libtool_, or -tools with similar functionality. - -A plugin module must define a specific symbol name, which depends on -the pluggable interface and module name. For most pluggable -interfaces, the exported symbol is a function named -``INTERFACE_MODULE_initvt``, where *INTERFACE* is the name of the -pluggable interface and *MODULE* is the name of the module. For these -interfaces, it is possible for one shared object or DLL to implement -multiple plugin modules, either for the same pluggable interface or -for different ones. For example, a shared object could implement both -KDC and client preauthentication mechanisms, by exporting functions -named ``kdcpreauth_mymech_initvt`` and ``clpreauth_mymech_initvt``. - -.. note: The profile, locate, and GSSAPI mechglue pluggable interfaces - follow different conventions. See the documentation for - those interfaces for details. The remainder of this section - applies to pluggable interfaces which use the standard - conventions. - -A plugin module implementation should include the header file -``<krb5/INTERFACE_plugin.h>``, where *INTERFACE* is the name of the -pluggable interface. For instance, a ccselect plugin module -implementation should use ``#include <krb5/ccselect_plugin.h>``. - -.. note: clpreauth and kdcpreauth module implementations should - include <krb5/preauth_plugin.h>. - -initvt functions have the following prototype:: - - krb5_error_code interface_modname_initvt(krb5_context context, - int maj_ver, int min_ver, - krb5_plugin_vtable vtable); - -and should do the following: - -1. Check that the supplied maj_ver argument is supported by the - module. If it is not supported, the function should return - KRB5_PLUGIN_VER_NOTSUPP. - -2. Cast the supplied vtable pointer to the structure type - corresponding to the major version, as documented in the pluggable - interface header file. - -3. Fill in the structure fields with pointers to method functions and - static data, stopping at the field indicated by the supplied minor - version. Fields for unimplemented optional methods can be left - alone; it is not necessary to initialize them to NULL. - -In most cases, the context argument will not be used. The initvt -function should not allocate memory; think of it as a glorified -structure initializer. Each pluggable interface defines methods for -allocating and freeing module state if doing so is necessary for the -interface. - -Pluggable interfaces typically include a **name** field in the vtable -structure, which should be filled in with a pointer to a string -literal containing the module name. - -Here is an example of what an initvt function might look like for a -fictional pluggable interface named fences, for a module named -"wicker":: - - krb5_error_code - fences_wicker_initvt(krb5_context context, int maj_ver, - int min_ver, krb5_plugin_vtable vtable) - { - krb5_ccselect_vtable vt; - - if (maj_ver == 1) { - krb5_fences_vtable vt = (krb5_fences_vtable)vtable; - vt->name = "wicker"; - vt->slats = wicker_slats; - vt->braces = wicker_braces; - } else if (maj_ver == 2) { - krb5_fences_vtable_v2 vt = (krb5_fences_vtable_v2)vtable; - vt->name = "wicker"; - vt->material = wicker_material; - vt->construction = wicker_construction; - if (min_ver < 2) - return 0; - vt->footing = wicker_footing; - if (min_ver < 3) - return 0; - vt->appearance = wicker_appearance; - } else { - return KRB5_PLUGIN_VER_NOTSUPP; - } - return 0; - } - -Logging from KDC and kadmind plugin modules -------------------------------------------- - -Plugin modules for the KDC or kadmind daemons can write to the -configured logging outputs (see :ref:`logging`) by calling the -**com_err** function. The first argument (*whoami*) is ignored. If -the second argument (*code*) is zero, the formatted message is logged -at informational severity; otherwise, the formatted message is logged -at error severity and includes the error message for the supplied -code. Here are examples:: - - com_err("", 0, "Client message contains %d items", nitems); - com_err("", retval, "while decoding client message"); - -(The behavior described above is new in release 1.17. In prior -releases, the *whoami* argument is included for some logging output -types, the logged message does not include the usual header for some -output types, and the severity for syslog outputs is configured as -part of the logging specification, defaulting to error severity.) - -.. _automake: https://www.gnu.org/software/automake/ -.. _libtool: https://www.gnu.org/software/libtool/ |