/*
 * Copyright (c) 2005 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 (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use, copy,
 * modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/* $Id$ */

/*!

\page plug-ins Network Identity Manager Modules and Plug-ins

  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.

  Plug-ins and localization are handled by the Network Identity
  Manager Module Manager API.

  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 :

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

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_plugin record.

\subsection pi_pt_cred_init Initialization

Once init_module() has completed, the module manager sends a
<::KMSG_SYSTEM,::KMSG_SYSTEM_INIT> message to the message processor.

For credential provider plug-ins, <::KMSG_SYSTEM,::KMSG_SYSTEM_INIT> is
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 assumed to have failed
initialization and is immediately unloaded.

The message processor is automatically subscribed to the following
message types:
- ::KMSG_SYSTEM
- ::KMSG_KCDB

Although a plug-in can use the <::KMSG_SYSTEM,::KMSG_SYSTEM_INIT>
message enumerate existing credentials in the system, it should not
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
<::KMSG_SYSTEM,::KMSG_SYSTEM_EXIT> to the message processor.  The
plug-in must perform any necessary shutdown operations, free up
resources and unsubscribe from any messages that it has subscribed to.

This message is guaranteed to be the last message received by a
credentials manager plug-in if the plug-in unsubsribes from all
additional message classes that it subsribed to.

The message types that the message processor is automatically
subscribed to (See \ref pi_pt_cred_init) do not have to be
unsubscribed from as they are automatically removed.

\subsection pi_pt_cred_other Other Notes

Since credential managers may receive privileged information, the
signature requirements for credential managers are specially strict.

*/


