From: Jeffrey Altman Date: Wed, 18 Apr 2007 21:45:22 +0000 (+0000) Subject: More NIM Developer documentation updates X-Git-Tag: krb5-1.7-alpha1~1131 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=3690f6c10df5a2d4c4087b73dba606548a3c51fd;p=krb5.git More NIM Developer documentation updates Revisions to the plug-in architecture documentation. Adds a graphic showing the plug-in architecture Defines "ALIASES" in the Makefile so that the current NIM API Version number will be used within the docs at build time. ticket: new git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@19490 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/src/windows/identity/doc/Makefile b/src/windows/identity/doc/Makefile index 39b20a5aa..89380aff3 100644 --- a/src/windows/identity/doc/Makefile +++ b/src/windows/identity/doc/Makefile @@ -1,5 +1,6 @@ # # Copyright (c) 2004 Massachusetts Institute of Technology +# Copyright (c) 2007 Secure Endpoints Inc. # # Permission is hereby granted, free of charge, to any person # obtaining a copy of this software and associated documentation files @@ -53,6 +54,8 @@ INPUT += "$(SRC)\kmm" INPUT += "$(SRC)\kherr" !ifdef BUILD_AFS INPUT += "$(SRC)\plugins\afs" + +ALIASES = "apiversion=$(NETIDMGR_VERSION_API)" !endif IMAGE_PATH = "$(SRC)\doc\images" diff --git a/src/windows/identity/doc/images/modules_plugins_krb5.png b/src/windows/identity/doc/images/modules_plugins_krb5.png new file mode 100644 index 000000000..127e89e8d Binary files /dev/null and b/src/windows/identity/doc/images/modules_plugins_krb5.png differ diff --git a/src/windows/identity/doc/plugin_framework.h b/src/windows/identity/doc/plugin_framework.h index 39d6ac18f..a10af2a6f 100644 --- a/src/windows/identity/doc/plugin_framework.h +++ b/src/windows/identity/doc/plugin_framework.h @@ -28,75 +28,119 @@ /*! \page pi_framework Plug-in Framework -\section pi_fw_pnm Plug-ins and Modules +\section pi_fw_pnm Introduction to Plug-ins, Modules and Messages \subsection pi_fw_pnm_p Plug-ins -A Network Identity Manager plug-in is a package that implements a defined API that will -perform credentials management or related tasks on behalf of Network Identity Manager. -The core Network Identity Manager codebase does not interact directly with Kerberos v5 or -AFS or any other external entity directly. Instead, plug-ins are used. +A plug-in is a package that implements a defined API that will perform +credentials management or related tasks on behalf of Network Identity +Manager. -Each plug-in has a name. The name should be unique among the loaded -plug-ins, or the plug-in will fail to load. +The Network Identity Manager architecture is message based. The core +of each plug-in is a message handler. The plug-in integrates with the +application by subscribing to, and handling specific types of +messages. -The method in which Network Identity Manager communicates with a plug-in depends on the -plug-in type. For more information on each plug-in type, please refer -to \ref pi_pt. - -Most plug-in types rely on a message processor for communication. -During plug-in registration, the module specifies the message processor -for the plug-in, which acts as the only point of contact between the -Network Identity Manager core and the plug-in. Some other plug-ins require exporting -specific functions. +The plug-in message handler runs in its own thread and receive +asynchronous messages. There are exceptions, such as when one plug-in +requires another plug-in to handle a specific message before it can +handle the message. In addition, during certain operations that +require user interaction, each plug-in can delegate code that will run +in the main application thread (the user interface thread) to process +window messages. \subsection pi_fw_pnw_m Modules One or more plug-ins can be bundled together into a module. A module -is a dynamically loadable library which exports a specific -set of callbacks. Currently, the only two required callbacks for a -module are : +is a dynamically loadable library which exports a specific set of +callbacks. Currently, the only two required callbacks for a module +are : - init_module(), and - exit_module() -\section pi_fw_pm Plug-in/Module Manager +For more information about how a module is structured, see \ref +pi_structure . + +\subsection pi_fw_pnm_msg Messages and Message Queues + +An integral part of this framework is the messaging system. Most of +the communication between the Network Identity Manager application and +plug-ins is conducted through passing messages. + +A message has a type and subtype and is denoted in this documentation +as \< \e message_type, \e message_subtype\>. For example, when a +plug-in is loaded, the first message it receives is \< ::KMSG_SYSTEM, +::KMSG_SYSTEM_INIT \>. + +Each thread in the application, specially threads that were created +for individual plug-in messages handlers, has an associated message +queue that stores and manages all the messages that have been sent to +subscribers in that thread. + +The most common recipient of a message is a message callback function +(see ::kmq_callback_t ). The message handler for a plug-in is one such +example. A message callback function receives the message type, +subtype and two optional parameters for the message. + +Any acceptable recipient can subscribe to broadcast messages of any +type. Once subscribed, whenever a message of that type is broadcast, +the message will get queued on the corresponding message queue. Then, +one of the dispatch functions can dispatch the message to the correct +callback function. (see ::kmq_dispatch). + +Next \subpage pi_fw_pm ... -The plug-in manager maintains a separate thread for loading and -registering modules. When a module is successfully loaded and it +*/ + +/*! + +\page pi_fw_pm Module Manager + +The module manager is tasked with loading, unloading and managing the +plug-in message processing. It maintains a separate thread for loading +and registering modules. When a module is successfully loaded and it registers one or more plug-ins, a new thread is created for each plug-in. Plug-in specific initialization and other callback functions -are called from within this new thread. This is to prevent one plug-in -from "hanging" other plug-ins and the main Network Identity Manager -user interface threads. +are called from within this new thread. This is to prevent one +plug-in from "hanging" other plug-ins and the main Network Identity +Manager user interface threads. Read more : - \ref pi_structure \subsection pi_fw_pm_load Load sequence -When kmm_load_module() is called, the following sequence of events -occur: +When kmm_load_module() is called to load a specific module, the +following sequence of events occur: -- The standard system search path is used to locate the binary. +- The registration information for the module is located on the + registry key \c + \Software\MIT\NetIDMgr\PluginManager\Modules\[ModuleName]. -- The binary is loaded into the address space of Network Identity Manager along with - any dependencies not already loaded. +- The \c ImagePath value from the registration information is used to + locate the module binary. If it is not an absolute path, then the + binary is located using the standard system search path starting + from the directory in which Network Identity Manager binaries are + located. -- If the Network Identity Manager core binary is signed, then the signature is checked - against the system and user certificate stores. If this fails, the - module is unloaded. See \ref pi_fw_pm_unload. +- The binary is loaded into the address space of Network Identity + Manager along with any dependencies not already loaded. -- init_module() for the loaded module is called. If this function - returns an error or if no plug-ins are registered, then the module is - unloaded. See \ref pi_fw_pm_unload. +- If the Network Identity Manager core binary is signed, then the + signature is checked against the system and user certificate stores. + If this fails, the module is unloaded. See \ref pi_fw_pm_unload. + +- The init_module() entry point for the loaded module is called. If + this function returns an error or if no plug-ins are registered, + then the module is immediately unloaded. See \ref pi_fw_pm_unload. - During processing of init_module(), if any localized resource libraries are specified using kmm_set_locale_info(), then one of the localized libraries will be loaded. See \ref pi_localization - During processing of init_module(), the module registers all the - plug-ins that it is implementing by calling kmm_register_plug-in() for + plug-ins that it is implementing by calling kmm_register_plugin() for each. - Once init_module() returns, each plug-in is initialized. The method @@ -111,23 +155,29 @@ occur: - During normal operation, any registered plug-ins for a module can be unloaded explicitly, or the plug-in itself may signal that it should be unloaded. If at anytime, all the plug-ins for the module are - unloaded, then the module itself is also unloaded unless the NoUnload - registry value is set in the module key. + unloaded, then the module itself is also unloaded unless the \c + NoUnload registry value is set in the module key. \subsection pi_fw_pm_unload Unload sequence - For each of the plug-ins that are registered for a module, the exit code is invoked. The method by which this happens depends on the - plug-in type. The plug-in is not given a chance to object to the + plug-in type. The plug-in is not given a chance to veto the decision to unload. Each plug-in is responsible for performing cleanup tasks, freeing resources and unsubscribing from any message classes that it has subscribed to. -- exit_module() is called for the module. +- The exit_module() entry point is called for the module. - If any localized resource libraries were loaded for the module, they are unloaded. - The module is unloaded. +The following diagram illustrates the relationship between modules and +plug-ins as implemented in the Kerberos 5 plug-in distributed with +Network Identity Manager. + +\image html modules_plugins_krb5.png + */ diff --git a/src/windows/identity/doc/plugin_main.h b/src/windows/identity/doc/plugin_main.h index feb4a25d3..70040b285 100644 --- a/src/windows/identity/doc/plugin_main.h +++ b/src/windows/identity/doc/plugin_main.h @@ -29,38 +29,42 @@ \page plug-ins Network Identity Manager Modules and Plug-ins -Plug-ins and localization are handled by the Network Identity Manager Module Manager -API. Each plug-in consists of a dynamically loadable library and zero -or more associated resource libraries. + The Network Identity Manager application does not include any + ability to manage any specific type of credential. Instead it + exposes a framework on which plug-ins can be implemented to manage + credentials. -For more information about Network Identity Manager Plug-ins, see the following -sections: + Plug-ins and localization are handled by the Network Identity + Manager Module Manager API. -- \subpage pi_framework -- \subpage pi_pt -- \subpage pi_structure -- \subpage pi_localization + The following sections describe plug-ins in detail: + + - \subpage pi_framework + - \subpage pi_pt + - \subpage pi_structure + - \subpage pi_localization */ /*! \page pi_pt Plug-in Types -The types of plug-ins that are currently supported by Network Identity Manager are : +The types of plug-ins that are currently supported by Network Identity +Manager are : \section pi_pt_cred Credential Provider A credential provider plug-in essentially acts as an interface between -Network Identity Manager and some entity which defines the credentials for the purpose -of managing those credentials. +Network Identity Manager and some entity which defines the credentials +for the purpose of managing those credentials. There can be more than one credential provider in a module. \subsection pi_pt_cred_comm Communication -Communication between Network Identity Manager and a credential provider occurs -through a message processor. When registering a credential provider, -the module initialization code in init_module() specifies -::KHM_PITYPE_CRED as the \a type member and sets \a msg_proc member to -a valid message processor in the ::khm_plug-in record. +Communication between Network Identity Manager and a credential +provider occurs through a message processor. When registering a +credential provider, the module initialization code in init_module() +specifies ::KHM_PITYPE_CRED as the \a type member and sets \a msg_proc +member to a valid message processor in the ::khm_plugin record. \subsection pi_pt_cred_init Initialization @@ -72,8 +76,8 @@ guaranteed to be the first message it receives. The callback function should return KHM_ERROR_SUCCESS if it initializes properly or some other value otherwise. If the return -value signals an error, then the plug-in is assume to not be loaded and -immediately unregistered. +value signals an error, then the plug-in is assumed to have failed +initialization and is immediately unloaded. The message processor is automatically subscribed to the following message types: @@ -86,7 +90,6 @@ obtain new credentials. This is because other plug-ins that may depend on the new credential messages may not be loaded at this time. See the section on \ref cred_msgs for more information. - \subsection pi_pt_cred_exit Uninitialization When the plug-in is to be removed, the module manager sends a @@ -107,22 +110,6 @@ unsubscribed from as they are automatically removed. Since credential managers may receive privileged information, the signature requirements for credential managers are specially strict. -\section pi_pt_conf Configuration Provider - -Provides configuration information. -[TODO: fill in] - -\subsection pi_pt_conf_comm Communication -[TODO: fill in] - -\subsection pi_pt_conf_init Initialization -[TODO: fill in] - -\subsection pi_pt_conf_exit Uninitialization -[TODO: fill in] - -\subsection pi_pt_conf_other Other Notes - */ diff --git a/src/windows/identity/doc/plugin_structure.h b/src/windows/identity/doc/plugin_structure.h index c82af7b69..452029e4f 100644 --- a/src/windows/identity/doc/plugin_structure.h +++ b/src/windows/identity/doc/plugin_structure.h @@ -29,9 +29,13 @@ \page pi_structure Structure of a module -A Network Identity Manager module is a dynamically loadable library with a -specific set of exported symbols. Each export symbol and general -notes about writing a plug-in module are documented below. +A Network Identity Manager module is a dynamically loadable library +with a specific set of exported symbols. Each export symbol and +general notes about writing a plug-in module are documented below. + +\section pi_str_reg Registration and Version Information + +[TODO] \section pi_str_init Initialization