diff options
author | Tom Yu <tlyu@mit.edu> | 2007-04-18 21:58:06 +0000 |
---|---|---|
committer | Tom Yu <tlyu@mit.edu> | 2007-04-18 21:58:06 +0000 |
commit | a06998f6afb36bef2a4e7b1ea93cb6de5c4138e9 (patch) | |
tree | 61566b00573a00cdf50d8b75915512fd4e88afc0 /src | |
parent | c1640b0d6e7f04807121d283faaf47e2b2b561af (diff) | |
download | krb5-a06998f6afb36bef2a4e7b1ea93cb6de5c4138e9.zip krb5-a06998f6afb36bef2a4e7b1ea93cb6de5c4138e9.tar.gz krb5-a06998f6afb36bef2a4e7b1ea93cb6de5c4138e9.tar.bz2 |
pull up r19490 from trunk
r19490@cathode-dark-space: jaltman | 2007-04-18 17:45:22 -0400
ticket: new
subject: 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: 5535
version_fixed: 1.6.1
git-svn-id: svn://anonsvn.mit.edu/krb5/branches/krb5-1-6@19492 dc483132-0cff-0310-8789-dd5450dbe970
Diffstat (limited to 'src')
-rw-r--r-- | src/windows/identity/doc/Makefile | 3 | ||||
-rw-r--r-- | src/windows/identity/doc/images/modules_plugins_krb5.png | bin | 0 -> 22193 bytes | |||
-rw-r--r-- | src/windows/identity/doc/plugin_framework.h | 132 | ||||
-rw-r--r-- | src/windows/identity/doc/plugin_main.h | 59 | ||||
-rw-r--r-- | src/windows/identity/doc/plugin_structure.h | 10 |
5 files changed, 124 insertions, 80 deletions
diff --git a/src/windows/identity/doc/Makefile b/src/windows/identity/doc/Makefile index 39b20a5..89380af 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 Binary files differnew file mode 100644 index 0000000..127e89e --- /dev/null +++ b/src/windows/identity/doc/images/modules_plugins_krb5.png diff --git a/src/windows/identity/doc/plugin_framework.h b/src/windows/identity/doc/plugin_framework.h index 39d6ac1..a10af2a 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 feb4a25..70040b2 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 c82af7b..452029e 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
|