Difference between revisions of "Projects/Plugin support improvements"

Revision as of 13:17, 28 July 2010

Motivations, Priorities & Requirements

Motivations: there are a number of motivations behind the creation of the plugin architecture framework.

• Desire to separate pluggable interface from its implementation;
• Desire to provide simple and clear mechanism that facilitates additions of new pluggable interfaces and their implementations (modules);
• Handles both built-in and dynamic plugin modules;
• Allows multiple implementation of the same pluggable interface;
• Provides uniform way to supply parameters for plugin configuration;
• Allows one plugin implementation (module) to use services provided by the other plugin implementations.

Requirements: from these items we have developed a more formal set of requirements covering the design and the implementation of the framework to support the plugins. These are as follows:

1. Allow third parties to implement multiple plugin modules for each pluggable interface.
2. Allow a plugin module to build as dynamic or built-in from the same source code.
3. Allow third parties to more easily create new plugin modules.
4. Provide a uniform method for configuring discovery of plugin modules.
5. Improve readability of code that calls pluggable interfaces.
6. Allow easier creation of new pluggable interfaces.
7. Allow incremental transition of existing pluggable interfaces to the new framework.

Architecture Overview and Concepts

Introduction

The architecture for the plugin support is shown in the following figure. The participants and components are described in the section below.

Participants

The following is a summary of participants and components within the architecture. Further details are provided in the sections below.

Plugin Manager: The plugin manager provides a set of generic capabilities that are independent of individual plugin interfaces. The plugin manager implements operations that manage plugin configuration and plugin registry services.

Pluggable Interface: A pluggable interface is an interface that can be implemented by a third party in a modular manner. An implementation of a pluggable interface is referred to as a plugin module. Furthermore, a pluggable interface itself consist of a consumer interface and provider interface (see below).

Plugin Module: A plugin module is an implementation of a pluggable interface. For example, in the Figure Plugin_A is shown to have two implementations (modules).

Consumer: The consumer or caller is the entity that uses the plugin module.

Collaboration: Flows

As shown in the above Figure, the plugin architecture is designed based on the notion of pluggable interfaces, each of which are defined based on an abstract design.

When a third party wishes to develop a loadable plugin module (e.g. Plugin_Module_A1) that implements a specific task (e.g. implement password quality check), the developer of the module must conform to the pluggable interface (Pluggable Interface A) defined for that "family" of plugin modules.

The consumer (or caller) that later makes use of the plugin module, must invoke functions implemented in that module through a specific consumer interface (Consumer_Interface_A). Discovery (and filtering) is triggered by the first load operation (within a krb5_context).

Architecture Components

In this section we provide further details on the components of the architecture, describing its features and behaviors.

Plugin Manager

The plugin manager 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. Instead a consumer calls a loader function (of the specific pluggable interface) which in-turn calls the plugin manager.

In this architecture, the krb5_init_context() functions will create and configure a plugin manager context that will exist in the krb5_context.

The plugin manager locates plugin modules using both a numeric identifier (that designates a plugin interface) and a string (that names a module which implements that pluggable interface). The primary way to use the plugin manager is to query it for the vtable constructor for a specified module (or a set of vtable constructors for all modules of that interface).

The plugin manager keeps track of modules through its registries. These are discussed as follows.

Registry of built-in modules

This registry keeps track of built-in modules. Typically, libkrb5 will initialize this with locators for all of the built-in modules that are linked into it. Other code units can also register private built-in plugin modules using this registry.

Registry of loadable modules

This registry keeps track of a few additional items needed for loadable modules:

• Each interface's registry starts out empty.

• The consumer (typically) populates the registry by registering vtable constructors for built-in modules.

• When k5_plugin_load() is invoked on an interface for the first time, discovery is performed. This has two steps:

• • Dynamic module mappings are read from the profile. Each named dynamic module is dlopened and dlsym'd to obtain the vtable constructor, and that constructor is added to the interface registry.

• • Enable/disable information is read from the profile. The interface registry is pruned to contain only enabled modules.

• Thereafter, the interface's registry is unchanging.

Pluggable Interfaces

A pluggable interface is an interface (possibly internal to a library) that can be implemented by a third party in a modular, well-compartmentalized manner. These implementations of pluggable interfaces are called plugin modules. Pluggable interfaces allow a consumer to use the capabilities of the interface without needing to be aware of the implementation details. In particular, a pluggable interface prevents the consumer from needing to know whether the module is a built-in or a dynamically loadable module.

Pluggable interfaces 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.

A pluggable interface has two parts: a consumer interface and a provider interface. Typically, library code implements the consumer interface, and application code or other library code calls the functions of the consumer interface.

Consumer interface

The consumer interface isolates the consumer from implementation details of the pluggable interface. The consumer does not generally need to know about whether a given module is built-in or dynamically loaded. The implementation of a consumer interface is essentially a glue layer, and can make use of domain-independent (not specific to any pluggable interface) capabilities of the plugin framework. The consumer might explicitly register a new plugin module that it implements: this capability is part of the plugin manager.

A consumer of a pluggable interface uses an opaque handle (obtained from a loader function that is part of the pluggable interface) to call the methods of a plugin module. Each handle represents one plugin module, and perhaps associated resource information. For one-to-many pluggable interfaces, the loader function will return a list of handles.

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. In essence, these pluggable interface functions in the architecture are wrapper functions that call through function pointers contained in the opaque plugin module handle object.

One rationale for using wrapper functions instead of having the consumer directly invoke methods through a function pointer is to make 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.)

The loader function is specific to the pluggable interface. One reason is for type safety: there will be a distinct opaque handle type for each pluggable interface, allowing compile-time checking to catch some sorts of programming errors. Another reason is backward compatibility: it allows a pluggable interface to support plugin modules that implement an older provider interface.

Provider interface

A plugin module is a unit of code that implements (among others) the provider interface portion of a pluggable interface. Plugin modules can be built in or dynamically loaded. Several alternatives exist for the form of the provider interface, but some have significant advantages in allowing the plugin module to use identical source code for both built-in and loadable modules.

A built-in module is a module whose implementation is already available within the consumer's symbol namespace at the time of module discovery. This typically means a module whose implementation is part of the same code unit as the consumer, though it could also mean a module which was registered by some other code unit.

A dynamically loaded module is a module whose executable code is located within a file that is distinct from the library or program that calls it. The plugin framework uses the runtime linker (or equivalent) to explicitly map the executable code of the module into the process address space. (In POSIX systems, this is typically done using dlopen()).

Loadable module provider interface

The domain-independent part of the provider interface of a loadable module consists of a single exported function symbol, which denotes the vtable constructor function for that module. The signature of the constructor is specific to the plugin interface the module implements. The contents of the vtable are also specific to the plugin interface.

The constructor usually takes as arguments the following:

• an interface version number
• a pointer to a caller-allocated vtable structure for the interface,
• the size of the structure (as an added precaution against version mismatches).

The name of the function symbol is constructed from the name of the plugin interface and the name of the plugin module. This allows the caller to see just from the symbol name which interface and plugin it is calling.

Built-in-module provider interface

A built-in module provides the same interface as a loadable module. In this architecture we use an exported function symbol for each loadable module implementing a pluggable interface.

Plugin Registry

Domain Specific and Domain-Independent Modules

The architecture recognizes two "types" of plugin modules, namely domain-independent (not specific to a particular pluggable interface) modules and domain-specific modules. The intent here is to have a number of pluggable interfaces, each encapsulating a set of related capabilities in a way that allows third parties to implement the interfaces easily (both domain-specific and domain-independent).

domain-independent

plugin manager

generic plugin registry and support services

provider interface

the generic interface that a plugin module implements to interact with the plugin manager

domain-specific

this includes the pluggable interfaces

consumer interface

the interface that a user of a plugin accesses

provider interface

the interface that a plugin module implements to interact with the consumer

A consumer of a pluggable interface initializes the plugin manager (usually implicitly via krb5_init_context()) and uses the consumer interface to access the services of the plugin moudle. The bulk of the consumer interface is a set of ordinary C functions that takes an opaque plugin module handle as a parameter (which may be provided implicitly, depending on interface). Typically the consumer obtains an opaque plugin module handle by calling a domain-specific plugin loader, which is part of the consumer interface.

The provider interface has both a domain-independent part and a domain-specific part. The plugin manager interacts with the domain-independent part of a plugin module, while the consumer interface implementation interacts with the domain-specific part of a plugin module. The same plugin module source code can be built as either a built-in or dynamically loaded module.

Operational Flow

Startup

• The krb5_init_context() function initializes a plugin manager context that resides in the krb5_context.

• It registers libkrb5 built-in modules (from static tables), and reads location parameters of dynamically-loaded plugin modules (if any) from the krb5.conf (or other configuration profile).

• It calls the plugin manager methods to configure the locations of dynamically-loaded plugin modules.

Consumer

• The consumer calls the plugin loader function (for the desired pluggable interface).

• The loader function calls the plugin manager to retrieve the vtable constructor function for the appropriate module and builds an opaque module handle to give to the consumer.

• The plugin manager looks up the vtable constructor to give to the loader function of the pluggable interface.

• The consumer calls the wrapper functions (of the pluggable interface), passing the opaque module handle in order to access the capabilities of the pluggable interface.

Adding new modules at run time

An application can register its own plugin modules at run time by calling the plugin manager function to update the registry.

Backward compatibility

Older dynamically loadable modules that don't conform to the "vtable constructor function" provider model can be handled with specialized loader functions. If a pluggable interface needs to support a legacy loadable module of this sort, it can contain a more elaborate loader function that uses the lower-level capabilities of the plugin manager to:

• obtain an opaque locator handle for a module (or set of modules)
• look up data or function symbols from a module locator handle (or set of locator handles)

Interfaces and Functions

Consumer accessible functions

The following functions are meant to be used by a consumer of pluggable interfaces:

k5_plm_init

initialize a plugin manager context

k5_plm_fini

shut down a plugin manager context

k5_plm_add_vtfn

register a vtable constructor (e.g., for a built-in module)

k5_plm_set_basedir

set the base directory for dynamic plugin modules

k5_plm_set_plif_path

set the search path for dynamic plugin modules of a specific interface

Loader accessible function

The following functions are meant to be used by a loader function of a pluggable interface:

k5_plm_get_vtfn

get a vtable constructor

k5_plm_get_vtfn_set

get a set of vtable constructors

The following functions are meant to be used by a loader function that needs to do lower-level operations (particularly for backward compatibility with older loadable modules). They are typically not implemented by registries that only track built-in modules:

k5_plm_get_ploc

retrieve a module locator handle

k5_plm_get_ploc_set

retrieve a set of module locator handles

k5_ploc_get_vtfn

get a vtable constructor function from a module locator

k5_ploc_get_data

get a data symbol from a module locator

k5_ploc_get_func

get a function symbol from a module locator

k5_ploc_get_vtfn_set

get a set of vtable constructor functions from a module locator set

k5_ploc_get_data_set

get a set of data symbol from a module locator set

k5_ploc_get_func_set

get a set of function symbol from a module locator set

Configuration

Sample Code and Proof of Concept

Deliverables

For Release 1.9, the deliverables are (a) plugin framework/manager and pluggable interfaces that can support (b) password strength and (c) 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.

Existing Support

This section provides some background material on existing support for pluggable interfaces.

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 planned 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.

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. (While separate library shared objects that the calling library depends on can contain "built-in" modules for the calling library, 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. In POSIX systems, this is typically done using dlopen().

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