User:TomYu/Plugin support improvements
Contents
Priorities
- Allow third parties to implement multiple plugin modules for each pluggable interface
- Allow a plugin module to build as dynamic or built-in from the same source code
- Allow third parties to more easily create new plugin modules
- Provide a uniform method for configuring discovery of plugin modules
- Improve readability of code that calls pluggable interfaces
- Allow easier creation of new pluggable interfaces
Deliverables for release 1.9
Create a plugin framework and pluggable interfaces that can support password strength and password synchronization plugin modules. These should support the capabilities of two existing extensions written by Russ Allbery -- krb5-strength and krb5-sync. The framework is subject to change in the future, so it doesn't have to accommmodate all eventualities, but we will have a goal of not painting ourselves into a corner with respect to reasonably plausible future requirements.
Requirements
- minimal configuration required
- no explicit configuration for using built-in modules in their default modes
- no explicit configuration for using loadable modules if the files containing them are located in the default directory for that kind of module
Definitions
- pluggable interface
- an (internal) interface that can be implemented by a third party. These can be one-to-one, or one-to-many. An example of one-to-one is the DAL, and an example of one-to-many is preauth.
- module
- a unit of code that implements a pluggable interface. It can be built in, or it can be dynamically loadable.
- built-in
- a module whose executable code is located within the library shared object or executable program file, or behaves as if it were. (Dependent library shared objects of the calling library can contain "built-in" modules for the calling library, but this can cause problems with cyclic references.) The distinguishing characteristic of a built-in module is that, as part of program startup, the operating system automatically maps the executable code of the module into the address space of the process that calls it, without any explicit action by the library or program.
- dynamically loaded
- a module whose executable code is located within a file that is distinct from the library or program that calls it. The plugin support framework uses the runtime linker (or equivalent) to explicitly map the executable code of the module into the process address space.
- discovery
- process of enumerating what modules are available for a pluggable interface. Includes possible filtering of the raw discovered set.
- compiled-in
- directory scan
- explicit inclusion by configuration
- explicit exclusion by configuration
- loading
- the process of making modules available for calling. This can involve dynamically loading a module using the runtime linker, or it can involve registering a vtable provided by an application.
- built-in
- dynamic loading
- application-registered
- selection
- the process of a caller invoking one specific module from the set of loaded modules that implement an interface.
- consumer interface
- the interface that a caller uses to access the services of a pluggable interface. Typically, but not always, the krb5 library implements the consumer interface.
- provider interface
- the interface that a module author implements
Components
- plugin manager (PLM)
- plugin loader (PLL)
- pluggable interface (PLIF)
- caller (consumer) interface
- provider interface
Plugin manager
The plugin manager (PLM) provides a set of generic support capabilities that are independent of individual pluggable interfaces. It centralizes the discovery process for plugin modules. Typically, consumers of pluggable interfaces do not call it directly, but instead call a loader function of the pluggable interface.
/** opaque handle for plugin manager context */
typedef struct k5_plm_ctx_ *k5_plm_ctx;
/** opaque handle for a single plugin module */
typedef struct k5_pmod_ *k5_pmod;
/** opaque handle for a set of plugin modules */
typedef struct k5_pmod_set_ *k5_pmod_set;
/** numeric ID designating a pluggable interface */
typedef int k5_plif;
#define K5_PLIF_CCACHE 1
#define K5_PLIF_RCACHE 2
#define K5_PLIF_PWQUAL 3
/** Initialize the plugin manager. */
krb5_error_code k5_plm_init(k5_plm_ctx *ctx);
/** Shut down the plugin manager. */
void k5_plm_fini(k5_plm_ctx ctx);
/** Retrieve a module handle for the named module of the specified type. */
krb5_error_code k5_plm_get_pmod(k5_plm_ctx ctx, k5_plif plif,
const char *name, k5_pmod *pmod);
/** Free a plugin module handle. */
void k5_plm_free_pmod(k5_plm_ctx ctx, k5_pmod pmod);
/** Retrieve a handle for a set of modules
of the specified pluggable interface. */
krb5_error_code k5_plm_get_pmod_set(k5_plm_ctx ctx, k5_plif plif,
k5_pmod_set *pmset);
/** Free a module set. */
void k5_plm_free_pmod_set(k5_plm_ctx ctx, k5_pmod_set pmset);
/** Get a data symbol from a module. */
krb5_error_code k5_plm_get_data(k5_plm_ctx ctx, k5_pmod pmod, const char *name,
void **data);
/** Get a function symbol from a module. */
krb5_error_code k5_plm_get_func(k5_plm_ctx ctx, k5_pmod pmod, const char *name,
void (**func)());
/** Get a set of function symbols from a module set. */
krb5_error_code k5_plm_get_data_set(k5_plm_ctx ctx, k5_pmod pmod,
const char *name,
void ***data, size_t *count);
/** Get a set of function symbols from a module set. */
krb5_error_code k5_plm_get_func_set(k5_plm_ctx ctx, k5_pmod pmod,
const char *name,
void (***func)(), size_t *count);
- given the identifier of a pluggable interface, return an opaque handle representing the entire collection of available plugin modules that implements that pluggable interface.
- given the identifier of a pluggable interface and a module name, return an opaque generic handle for that module. For loadable modules, this can contain the handle from
dlopen(). For built-in modules, this can contain a pointer to a vtable.
Plugin loader
The plugin loader (PLL) provides generic utility functions for loading plugin modules.
Caller (consumer) interface
A caller (consumer) of a pluggable interface uses an opaque handle to call the methods of a plugin module. Each method of the consumer interface is an ordinary C function that takes the opaque handle either explicitly as its first argument or implicitly by some means such as a module name. Conceptually, these pluggable interface functions are wrapper functions that call through function pointers contained in the opaque handle object. (though this is not the only possible implementation)
One rationale for doing this instead of having the caller invoke methods through a function pointer is that it makes it easier for debuggers and analysis tools to recognize when a particular interface method is being called. (Function pointers might have identifier names that look nothing like the actual name of the function they point to, in addition to enabling confusing aliasing.)
A handle can represent:
- the plugin module itself
- a resource to which the plugin module provides access (e.g., a ccache handle)
- a set of plugin modules (e.g., the set of all available preauth mechanisms)
The caller does not generally need to know about whether a given module is built-in or dynamically loaded. The caller might explicitly register a new module that it implements.
Provider interface
The provider interface for a built-in module will generally take the form of a structure of function pointers, each of which points to a method implementation within the module.
The initial loadable module provider interface will support operating systems with POSIX-style dlopen() capabilities.
Does each loadable plugin module implementing a pluggable interface need to prepend a prefix to the name of each method? e.g., if the method is "f1", does module "foo" name its implementation of "f1" "foo_f1"? If not, how would builtin modules work?
Loadable module provider interface
A loadable module exports a single function symbol. The function takes as arguments an interface version number, a pointer to a caller-allocated vtable structure for the interface, and the size of the structure (as an added precaution against version mismatches).
Although the caller (actually the plugin support code) allocates the vtable structure in the above description, one alternative is to have the module perform the allocation of the structure itself. This can cause problems if the module uses a different memory allocator than the caller.
Should the single function symbol have a prefix that depends on the name of the plugin module?
- Yes
- allows identical module source code to be used for the built-in and loadable module versions of a module
- No
- adding a prefix to the symbol adds complexity to the code that looks up the symbol
Built-in module provider interface
A built-in module provides the same interface as a loadable module. In the alternative where we use same exported function symbol for each loadable module implementing a pluggable interface, the built-in modules will still need distinct prefixes are required for each vtable retrieval function.
One-symbol-per-method alternative loadable module provider interface
Exporting one symbol per method in a loadable module is an alternative that might require less effort from a module author, as it does not require that a vtable be part of the provider interface. Built-in modules would probably still require a vtable (though that could be provided by the implementation of the consumer interface).
Loader with fixed module set
This approach uses a slightly different definition for "loader". A loader knows about a fixed set of plugin modules, which may implement different pluggable interfaces. Typically, a built-in loader knows about all of the built-in modules, regardless of what interface each module implements. A collection of dynamically loaded modules (possibly implementing different pluggable interfaces) can be combined in a single shared object that only exports the loader interface.
Current plugins
We currently have the following plugin frameworks:
- Preauth: All shared objects from profile-specified or installation directory are loaded. Two vtables are read from the shared objects, one for libkrb5 and one for the KDC. The preauth framework iterates over the module list invoking functions to generate or handle preauth data. Preauth vtable functions receive a callback function and data object which allow it to request information such as the expected enctype or FAST armor key for the request.
- Authdata: Very similar to the preauth framework.
- KDB: The profile specifies a database library name for each realm. Shared objects matching the library name are loaded from a profile-specified and installation directory; the first matching object with an appropriately-named vtable data object is used, and the rest are ignored. libkdb5 contains wrappers which invoke functions in the library's vtable, or (for some optional functions) default implementations if the vtable left the function pointer as NULL.
- KDC location: All shared objects from an installation directory are located. A vtable is read from the shared objects. The KDC location framework iterates over each vtable and invokes a lookup function; modules can return success with a location, an error (which halts the location process), or a distinguished error code which passes control along to the next module or the built-in location mechanisms.
- GSSAPI: The file /etc/gss/mechs can specify a list of mechanism OIDs and shared object filenames; filenames are taken as relative to an installation directory. Shared objects implementing mechanisms can export either a function returning a vtable, or can export each GSSAPI interface individually.
The following areas of functionality are virtualized but have no exposed plugin framework:
- Serialization: Serialization table entries can be registered with krb5_register_serializer. Data objects are matched to table entries by magic number. The registration function is exported by libkrb5 and is named with the krb5_ prefix, but it and its associated structure are declared in k5-int.h rather than krb5.h. It is not used outside of libkrb5.
- ccache: Very similar to serialization, except that ccache implementations are selected using a URL-style prefix in the ccache name.
- keytab: Very similar to ccache, except that the keytab registration function is used outside of libkrb5 to register a "KDB keytab", which is used by kadmind to serve GSSRPC without requiring a keytab file containing the kadmin keys.
- Replay cache: Very similar to ccache, except that the replay cache registration function is not used anywhere (even inside libkrb5).
Plugin frameworks which are "not exposed" may still be productively used by vendor forks of the krb5 tree.
Future plugins
The following areas are candidates for future plugin support:
- PRNG
- profile / configuration
- DNS / host-realm mapping
- password quality policy
- lockout
- audit
- password synchronization
Current support infrastructure
In libkrb5support, we have functions to facilitate loading plugins from shared objects. There is a set of functions to load individual plugins from named files and mechglue; these are currently used by the HDB bridge and GSS mechglue:
- krb5int_open_plugin - Create a plugin handle from a filename
- krb5int_close_plugin - Close a plugin handle
- krb5int_get_plugin_data - Retrieve a data object from a plugin handle by symbol name
- krb5int_get_plugin_func - Retrieve a function object from a plugin handle by symbol name
There is another set of functions to scan a list of directories for plugins:
- krb5int_open_plugin_dirs - Create a plugin dir handle from a list of directories and (optionally) filebases
- krb5int_close_plugin_dirs - Close a plugin dir handle
- krb5int_get_plugin_dir_data - Retrieve a list of data objects from a plugin dir handle by symbol name
- krb5int_get_plugin_dir_func - Retrieve a list of function objects from a plugin dir handle by symbol name
- krb5int_free_plugin_dir_data - Free a list of data objects returned by krb5int_get_plugin_dir_data
- krb5int_free_plugin_dir_func - Free a list of function objects returned by krb5int_get_plugin_dir_func
Problem areas
- Every caller of krb5int_open_plugin_dirs specifies either no filebases (e.g. preauth plugins) or a single filebase (KDB plugins). Accepting and processing a list of filebases is probably needless complexity.
- Callers of krb5int_open_plugin_dirs have to know what directories to supply, which means they need to know the krb5 install root as well as the magic plugin area for OS X, and they need logic for reading a profile variable to determine the alternate plugin directory for the test suite (currently only implemented for KDB and preauth plugins).
- In most uses of plugins, we read a data object containing a list of function pointers. This makes it mostly impossible to supply a plugin which works with multiple versions of krb5. If we instead read a function object which we invoked with a version number to retrieve the vtable, it would be possible (though perhaps awkward) to create a shared object which works with multiple versions.
- We are somewhat schizophrenic about how plugins can access krb5 library functionality, and in particular internal symbols. Sometimes we call functions directly, sometimes we make use of a vtable passed into the plugin (e.g. the preauth_get_client_data_proc function), sometimes we use the accessor to invoke internal functions, and sometimes we call APIs or internal functions directly. Ideally we should have a consistent policy with a sound justification.
- When measuring code coverage with gcov, we cannot use shared libraries; this means we need to link in-tree plugins statically into the libraries or programs which load them. We have an ad-hoc method to do this with KDB plugins, but not with other plugin types.
- Administrators have an easier time writing scripts than creating linkable shared objects. In some cases it might yield a better administrator experience to create plugin interfaces via subprocesses than loading shared objects, although in many cases this might not be feasible.
- In some scenarios such as embedded environments, it may be more useful to allow applications to supply plugin vtables via an API (as we do for keytabs and ccaches, though those APIs are not public) than to load them from shared objects in the filesystem.
Links
Some possibly useful ideas at Dr Dobb's. It's rather biased toward C++, and we may disagree with some of the details. Among other things, it advocates separating the domain-specific interface of a plugin module from its domain-independent interface: plugin modules get passed a handle for the "registry services" of the plugin manager, and the modules must call those services to register their objects or methods.
