From ed0fe6c23007890333ef45886fd97b8775896d86 Mon Sep 17 00:00:00 2001 From: Jeffrey Altman Date: Tue, 17 Apr 2007 21:37:16 +0000 Subject: [PATCH] updates for NIM developer documentation Add the use of Tabs and Frames to the resulting output (doxyfile.cfg) Stylesheet changes to improve readability (stylesheet.css) Copyright updates (all files) Language Editing (all files) Version History (main_page.h) There are still a number of missing sections that need to be filled in as time permits: - Writing the dialog procedure for a cred type panel - Credential messages - configuration provider details - Actions - Menus ticket: new component: windows tags: pullup git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@19481 dc483132-0cff-0310-8789-dd5450dbe970 --- src/windows/identity/doc/cred_aquisition.h | 129 +++++++------- src/windows/identity/doc/cred_data_types.h | 82 +++++---- src/windows/identity/doc/cred_main.h | 1 + src/windows/identity/doc/cred_msgs.h | 5 +- src/windows/identity/doc/cred_prop_pages.h | 3 +- src/windows/identity/doc/doxyfile.cfg | 4 +- src/windows/identity/doc/footer.html | 4 +- src/windows/identity/doc/header.html | 3 +- src/windows/identity/doc/main_page.h | 92 ++++++++-- src/windows/identity/doc/plugin_framework.h | 86 +++++----- src/windows/identity/doc/plugin_locale.h | 6 +- src/windows/identity/doc/plugin_main.h | 36 ++-- src/windows/identity/doc/plugin_structure.h | 7 +- src/windows/identity/doc/stylesheet.css | 178 +++++++++++++++----- src/windows/identity/doc/ui_actions.h | 1 + src/windows/identity/doc/ui_context.h | 7 +- src/windows/identity/doc/ui_main.h | 1 + src/windows/identity/doc/ui_menus.h | 1 + 18 files changed, 417 insertions(+), 229 deletions(-) diff --git a/src/windows/identity/doc/cred_aquisition.h b/src/windows/identity/doc/cred_aquisition.h index 251b5b2c7..30f626f8e 100644 --- a/src/windows/identity/doc/cred_aquisition.h +++ b/src/windows/identity/doc/cred_aquisition.h @@ -1,5 +1,6 @@ /* * 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 @@ -26,36 +27,36 @@ /*! \page cred_acq Managed credential acquisition - Credential providers and the identity provider must participate in + Credential providers and identity providers must participate in managed credential acquisition in order to respond to the user's - requests to obtain new credentials for an identity or to obtain - new credentials for an existing identity. + requests to obtain new credentials for an identity or to renew + credentials for an existing identity. There are two major processes that result in managed credential - acuqisition. One is the acquisition of initial credentials, while - the other is the acquisition of new crednetials. Both processes - acquire new credentials (or replace existing credentials with new - ones). The difference between the two processes lie in the way the - new credentials are obtained. Initial credentials are obtained - using user supplied username and password while new credentials - are obtained using other existing credentials. + acuqisition. One is the acquisition of credentials, while the + other is credential renewal. During a renewal, existing + credentials are used to obtain new credentials which expire later + than the existing credential. Typically, the identity provider + performs the task of obtaining renewed initial credentials while + the other credential providers obtain new credentials based on + these initial credentials. - \section cred_acq_init Initial Credentials + \section cred_acq_new New Credentials When a user initiates the process of initial credential - acquisition, NetIDMgr broadcasts a - <::KMSG_CRED,::KMSG_CRED_INITIAL_CREDS> message. Credential - providers which need to participate in the initial credential - acquisition should respond to this message as detailed in - \ref cred_acq_handle. + acquisition, Network Identity Manager broadcasts a + <::KMSG_CRED,::KMSG_CRED_NEW_CREDS> message. Credential providers + which need to participate in the credential acquisition should + respond to this message as detailed in \ref cred_acq_handle. - \section cred_acq_new New Credentials + \section cred_acq_renew Renew Credentials - When a user initiates the process of obtaining new credentials - based on existing credentials, NetIDMgr broadcasts a - <::KMSG_CRED,::KMSG_CRED_NEW_CREDS> message. Credential providers - which need to participate in the initial credential acquisition - should respond to this message as detailed in \ref cred_acq_handle. + Network Identity Manager broadcasts a + <::KMSG_CRED,::KMSG_CRED_RENEW_CREDS> message to initiate the + process of renewing credentials. This may be triggered + automatically or by a user action. Credential providers which + need to participate in the renewal should respond to this message + as detailed in \ref cred_acq_handle. The following pages provide detailed information: @@ -65,13 +66,12 @@ /*! \page cred_acq_new_resp Handling new credentials acquisition - The process of acquiring new credentials whether they are initial - credentials or not, happen as follows : + The process of acquiring credentials happens as follows: - - NetIDMgr creates a ::khui_new_creds object and a credentials - acquisition window. + - Network Identity Manager creates a ::khui_new_creds object and a + credentials acquisition window. - - <::KMSG_CRED,::KMSG_CRED_INITIAL_CREDS> or + - <::KMSG_CRED,::KMSG_CRED_RENEW_CREDS> or <::KMSG_CRED,::KMSG_CRED_NEW_CREDS> is sent to all the credentials providers. @@ -79,7 +79,7 @@ for customizing their respective credential types. The type, panel and any dependency information is populated into a ::khui_new_creds_by_type structure and added to the - ::khui_new_creds structure. + ::khui_new_creds structure. (See khui_cw_add_type()). - <::KMSG_CRED, ::KMSG_CRED_DIALOG_PRESTART> is sent to all the credentials providers. Credentials providers should use this @@ -95,53 +95,58 @@ are done through ::KHUI_WM_NC_NOTIFY messages to the dialog procedures. - - Once the dialog completes, NetIDMgr sends - <::KMSG_CRED,::KMSG_CRED_DIALOG_END> message to all the - credentials providers. The UI portion ends here. The - individual dialog controls are destroyed as a result of the main - credentials acquisition window being destroyed. - - - NetIDMgr posts <::KMSG_CRED,::KMSG_CRED_DIALOG_PROCESS> message - to all the credentials providers. Each provider should check if - the user cancelled the dialog or indicated that the new - credentials should be obtained and act accordingly. The - credentials provider is responsible for removing the - ::khui_new_creds_by_type structre from the ::khui_new_creds - structure and freeing up any resources it allocated earlier in - preparation for obtaining new credentials. + - Once the dialog processing is done, a ::WMNC_DIALOG_PREPROCESS + message is sent to the dialog procedure. + + - Network Identity Manager posts + <::KMSG_CRED,::KMSG_CRED_DIALOG_PROCESS> message to all the + credentials providers. Each provider should check if the user + cancelled the dialog or indicated that the new credentials + should be obtained and act accordingly. The \a result field of + the ::khui_new_creds structure will be set to either + ::KHUI_NC_RESULT_PROCESS or ::KHUI_NC_RESULT_CANCEL to indicate + whether the user wishes to acquire credentials or cancel the + operation. + + - A <::KMSG_CRED, ::KMSG_CRED_END> message signals the end of the + credentials acquisition process. Each credentials provider is + responsible for removing the ::khui_new_creds_by_type structre + from the ::khui_new_creds structure and freeing up any resources + it allocated earlier in preparation for obtaining new + credentials. \section cred_acq_handle Responding to credential acquisition messages The credential acquisition messages are - <::KMSG_CRED,::KMSG_CRED_INITIAL_CREDS> and <::KMSG_CRED, - ::KMSG_CRED_NEW_CREDS>. They are structured as follows : + <::KMSG_CRED,::KMSG_CRED_NEW_CREDS> and <::KMSG_CRED, + ::KMSG_CRED_RENEW_CREDS>. They are structured as follows: - \b type : ::KMSG_CRED - - \b subtype: ::KMSG_CRED_INITIAL_CREDS or ::KMSG_CRED_NEW_CREDS + - \b subtype: ::KMSG_CRED_NEW_CREDS or ::KMSG_CRED_RENEW_CREDS - \b uparam : 0 (unused) - \b vparam : a pointer to a ::khui_new_creds structure. The \a vparam parameter of the message, as shown above, is a pointer to a ::khui_new_creds structure. You can use the \a - subtype field of this structure to determine whether this is an - initial credentials acquisition or a new credentials acquisition - at any point. + subtype field of this structure to determine whether this is a new + credentials acquisition or a renewal. In response to this message, a credentials provider is expected to provide a configuration panel which the user can use to customize how the credentials of this type are to be obtained. The panel is - described by the ::khui_new_cred_panel structure. + described by the ::khui_new_creds_by_type structure. \subsection cred_acq_panel_spec Specifying the credentials type panel The credentials type panel is used by the user to customize how credentials of the specified type are to be obtained. The - ::khui_new_cred_panel structure that describes the panel can be + ::khui_new_creds_by_type structure that describes the panel can be used to specify a number of parameters that guide how the panel is to be displayed in the new credentials acquisition dialog. The \a name field defines a localized string that will be - displayed in the tab control that houses the panel. Optionally, + displayed in the tab control that houses the panel. If it is \a + NULL, then the name of the credentials type is used. Optionally, an icon can be specified in the \a icon field which will appear alongside the name. A tooltip may be provided in the \a tooltip field which will be displayed when the user hovers the mouse over @@ -155,12 +160,13 @@ name). Then the panels without a positive ordianl are arranged behind these in increasing order of \a name. - The \a hwnd_panel field is used to specify the handle to the - dialog or window of the panel. The parent of this window should - be set to the \a hwnd parameter of the ::khui_new_creds structure - which is passed in to the message handler. + Currently, the credentials provider must specify a dialog template + that will be used to create the embedded dialog for configuring + new credentials for the type. This is done by setting the + khui_new_creds_by_type::h_module, khui_new_creds_by_type::dlg_proc + and khui_new_creds_by_type::dlg_template fields. - Following is a code snippet which suggests how this could be done: + Following is example code which suggests how this could be done: \code // Message handling code for KMSG_CRED_NEW_CREDS or @@ -181,11 +187,10 @@ t->icon = LoadIcon(my_hInstance, MAKEINTRESOURCE(IDI_PANEL_ICON)); t->tooltip = L"Configure credentials of my type"; - t->hwnd_panel = CreateDialog( - my_hInstance, - MAKEINTRESOURCE(IDD_MY_PANEL), - c->hwnd, - my_dialog_proc); + // specify the dialog template to use + t->h_module = my_hInstance; + t->dlg_proc = my_dialog_procedure; + t->dlg_template = MAKEINTRESOURCE(IDD_NEW_CREDS); if(KHM_FAILED(khui_cw_add_type(c,t))) { // handle error @@ -195,7 +200,7 @@ It is important to note that the ::khui_new_creds_by_type pointer that is passed into khui_cw_add_type() points to an allocated block of memory which should remain in memory until - <::KMSG_CRED,::KMSG_CRED_DIALOG_PROCESS> message is received. + <::KMSG_CRED,::KMSG_CRED_END> message is received. For information on how the dialog procedure should be written, see \ref cred_acq_dlgproc . diff --git a/src/windows/identity/doc/cred_data_types.h b/src/windows/identity/doc/cred_data_types.h index 8fa7b1f36..dcd115219 100644 --- a/src/windows/identity/doc/cred_data_types.h +++ b/src/windows/identity/doc/cred_data_types.h @@ -1,5 +1,6 @@ /* * 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 @@ -24,20 +25,21 @@ /* $Id$ */ -/*! \page cred_data_types Data types in NetIDMgr +/*! \page cred_data_types Data types in Network Identity Manager - NetIDMgr's Credentials Database supports several useful data types. In - addition, plug-ins can define custom data types. Only a few operations - are expected of these data types since the core KCDB delegates fine grained - operations to other entities that understand the underlying format. + Network Identity Manager's Credentials Database supports several + useful data types. In addition, plug-ins can define custom data + types. Only a few operations are expected of these data types + since the core KCDB delegates fine grained operations to other + entities that understand the underlying format. - A field in a credential can have any one of these data types, but it must - have some data type. Each value can be at most \a KCDB_TYPE_MAXCB bytes - in length regardless of the data type. + A field in a credential can have any one of these data types, but + it must have some data type. Each value can be at most \a + KCDB_TYPE_MAXCB bytes in length regardless of the data type. - Some data types have a fixed size (such as \a Int32), while others are - variable size. The required memory for each field in a credential is - allocated as needed. + Some data types have a fixed size (such as \a Int32), while others + are variable size. The required memory for each field in a + credential is allocated as needed. \section kcdb_pg_dt Data types @@ -47,13 +49,17 @@ \subsubsection kcdb_pg_idt_v Void - Pretty useless. This data type is used to indicate that the associated - object doesn't actually contain any data. + Type identifier : ::KCDB_TYPE_VOID + + The Void data type is used to indicate that the associated object + does not contain any data. \subsubsection kcdb_pg_idt_s String - A unicode string that is terminated with a unicode NULL (L'\\0'). By - default, the type has the following flags : + Type identifier : ::KCDB_TYPE_STRING + + A unicode string that is terminated with a unicode NULL (L'\\0'). + By default, the type has the following flags: \a KCDB_TYPE_FLAG_CB_AUTO @@ -63,18 +69,23 @@ \subsubsection kcdb_pg_idt_d Date - Dates and times in NetIDMgr are stored as \a FILETIME structures. Utility - functions are provided for converting from other formats such as \a time_t. + Type identifier : ::KCDB_TYPE_DATE + + Dates and times in Network Identity Manager are stored in \a + FILETIME structures. Utility functions are provided for + converting from other formats such as \a time_t. \subsubsection kcdb_pg_idt_i Interval - Stores an interval of time. Stored as a 64 bit signed integer. The + Type identifier : ::KCDB_TYPE_INTERVAL + + Stores an interval of time. Stored as a 64-bit signed integer. The string representation of this data type is different from the \a - Date data type and designate an interval of time. + Date data type and designates an interval of time. The special value _I64_MAX (which is defined in limits.h as - 0x7fffffffffffffff, or in otherwords, the largest positive value - that can be stored in a 64 bit signed integer) is used to + 0x7fffffffffffffff, or in other words, the largest positive value + that can be stored in a 64-bit signed integer) is used to represent an interval of unknown length. The string representations of a data value of Interval type are @@ -94,27 +105,34 @@ \subsubsection kcdb_pg_idt_i32 Int32 - A signed 32 bit integer. + Type identifier : ::KCDB_TYPE_INT32 + + A signed 32-bit integer. \subsubsection kcdb_pg_idt_i64 Int64 - A signed 64 bit integer. + Type identifier : ::KCDB_TYPE_INT64 + + A signed 64-bit integer. \subsubsection kcdb_pg_idt_da Data - Raw data. Can contain a byte stream. This data type can be used by - plug-ins to associate raw data with a credential. However, there is no - built in string representation for this data type. As such, this is not - meant to be used for storing anything that has to be displayed to the user - verbatim. + Type identifier : ::KCDB_TYPE_DATA + + Raw data. Can contain a byte stream. This data type can be used + by plug-ins to associate raw data with a credential. However, + there is no built-in string representation for this data type. As + such, this is not meant to be used for storing anything that has + to be displayed to the user verbatim. \section kcdb_pg_cust Custom data types \subsection kcdb_pg_cb Custom data type call backs - Custom data types in the NetIDMgr Credentials Database are defined using - \a kcdb_type structures which must include several callback functions. - The expected behavior of these callback functions is documented below. + Custom data types in the Network Identity Manager Credentials + Database are defined using \a kcdb_type structures that must + include several callback functions. The expected behavior of + these callback functions is documented below. \subsubsection kcdb_pg_cb_ts toString @@ -172,7 +190,7 @@ definition of what a relative ordering is. It is left up to each data type callback to interpret what 'ascending' and 'descending' mean. - The return value \a r should be as follows : + The return value \a r should be as follows: \a r < 0 : if \a data1 < \a data2 diff --git a/src/windows/identity/doc/cred_main.h b/src/windows/identity/doc/cred_main.h index b5be8ad5a..a9949aedb 100644 --- a/src/windows/identity/doc/cred_main.h +++ b/src/windows/identity/doc/cred_main.h @@ -1,5 +1,6 @@ /* * 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 diff --git a/src/windows/identity/doc/cred_msgs.h b/src/windows/identity/doc/cred_msgs.h index 49f644c91..6d7cd3d1b 100644 --- a/src/windows/identity/doc/cred_msgs.h +++ b/src/windows/identity/doc/cred_msgs.h @@ -1,5 +1,6 @@ /* * 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 @@ -26,7 +27,7 @@ /*! \page cred_msgs Handling credentials provider messages -A credentials provider plugin receives a number of messages during the +A credentials provider plug-in receives a number of messages during the course of execution. This section describes the appropriate ways of handling these messages. @@ -34,7 +35,7 @@ handling these messages. There are only two system messages that a credentials provider needs to handle. Both of these are explained elsewhere as they deal with -initialization and uninitialization of the plugin. See the following +initialization and uninitialization of the plug-in. See the following two sections for details on handling these messages. - <::KMSG_SYSTEM,::KMSG_SYSTEM_INIT> \ref pi_pt_cred_init diff --git a/src/windows/identity/doc/cred_prop_pages.h b/src/windows/identity/doc/cred_prop_pages.h index e4d41b106..fd1da5ad6 100644 --- a/src/windows/identity/doc/cred_prop_pages.h +++ b/src/windows/identity/doc/cred_prop_pages.h @@ -1,5 +1,6 @@ /* * 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 @@ -62,7 +63,7 @@ - The property sheet is created and made visible with a call to khui_ps_show_sheet(). - - The NetIDMgr message loop takes over. Further interaction + - The Network Identity Manager message loop takes over. Further interaction including notifications of 'Ok','Cancel','Apply' and other property sheet related actions are handled through WIN32 messages. diff --git a/src/windows/identity/doc/doxyfile.cfg b/src/windows/identity/doc/doxyfile.cfg index a9dcc5207..e26923566 100644 --- a/src/windows/identity/doc/doxyfile.cfg +++ b/src/windows/identity/doc/doxyfile.cfg @@ -25,7 +25,7 @@ DOXYFILE_ENCODING = UTF-8 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded # by quotes) that should identify the project. -PROJECT_NAME = NetIDMgr +PROJECT_NAME = "Network Identity Manager" # The PROJECT_NUMBER tag can be used to enter a project or revision number. # This could be handy for archiving the generated documentation or @@ -746,7 +746,7 @@ ENUM_VALUES_PER_LINE = 4 # Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are # probably better off using the HTML help feature. -GENERATE_TREEVIEW = NO +GENERATE_TREEVIEW = YES # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be # used to set the initial width (in pixels) of the frame in which the tree diff --git a/src/windows/identity/doc/footer.html b/src/windows/identity/doc/footer.html index fb3b621ce..c46b93960 100644 --- a/src/windows/identity/doc/footer.html +++ b/src/windows/identity/doc/footer.html @@ -5,7 +5,9 @@
Generated on $datetime for $projectname $projectnumber by Doxygen $doxygenversion
- © 2004-2007 Massachusetts Institute of Technology. Contact khimaira@mit.edu
+ © 2004-2007 Massachusetts Institute of Technology.
+ © 2005-2007 Secure Endpoints Inc.
+ Contact khimaira@mit.edu
diff --git a/src/windows/identity/doc/header.html b/src/windows/identity/doc/header.html index 4235468f3..d696ed5bb 100644 --- a/src/windows/identity/doc/header.html +++ b/src/windows/identity/doc/header.html @@ -1,5 +1,6 @@ - + $title + diff --git a/src/windows/identity/doc/main_page.h b/src/windows/identity/doc/main_page.h index 34b3d1d72..55ccb69dc 100644 --- a/src/windows/identity/doc/main_page.h +++ b/src/windows/identity/doc/main_page.h @@ -25,15 +25,17 @@ /* $Id$ */ -/*! \mainpage NetIDMgr +/*! \mainpage Network Identity Manager \image html khimaira_logo.png \section main_dev Documentation for Developers - NetIDMgr is a credentials manager, which currently manages - Kerberos IV, Kerberos V and AFS credentials. This document - describes the API that is implemented by the NetIDMgr system. + Network Identity Manager is a credentials manager, which is + capable of managing Kerberos v5, Kerberos v4, Andrew File System, + and Kerberized Certificate Authority credentials. This document + describes the API that is implemented by the Khimaira framework + upon which Network Identity Manager is based. See the following sections for more information : - \subpage license @@ -41,16 +43,20 @@ - \subpage releases © 2004-2007 Massachusetts Institute of Technology + + © 2005-2007 Secure Endpoints Inc. */ /*! \page license License agreement and credits - NetIDMgr is distributed under the MIT License. + Network Identity Manager is distributed under the MIT License. \section license_l MIT License Copyright © 2004,2005,2006,2007 Massachusetts Institute of Technology + + Copyright © 2005,2006,2007 Secure Endpoints Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation @@ -74,33 +80,87 @@ \section license_credits Credits - NetIDMgr was developed at the Massachusetts Institute of - Technology. + Network Identity Manager was developed at the Massachusetts Institute of + Technology in partnership with Secure Endpoints Inc. Information Services and Technology at Massachusetts Institute of Technology + + Secure Endpoints Inc. */ /*! \page bugs Reporting bugs - NetIDMgr bugs can be reported to - kfw-bugs@mit.edu for now. - - In the future, there will actually be a place to track NetIDMgr bugs. + Network Identity Manager bugs can be reported to + kfw-bugs@mit.edu or + netidmgr@secure-endpoints.com When reporting bugs, please include as much information as - possible to help diagnose the problem. More guidelines about - reporting bugs will appear here at some point in time. + possible to help reproduce the problem. \image html khimaira_logo_small.png */ /*! \page releases Prior releases + The following is a list of releases of Network Identity Manager. + Whenever there is an addition to the API or a significant change + in behavior, the API version is incremented. A plug-in that is + developed against a particular version of the API will be + compatible with any release of Network Identity Manager that + implements that version of the API. + + The Network Identity Manager version number is set as the file and + product version of nidmgr32.dll. + + - 1.2.0.2 Kerberos for Windows 3.2 Beta 2 Apr 11, 2007\n + API version : 8 + + - 1.2.0.1 Apr 06, 2007\n + API version : 8 + + - 1.2.0.0 Kerberos for Windows 3.2 Beta 1 Mar 29, 2007\n + API version : 8 + + - 1.1.11.0 Mar 20, 2007\n + API version : 8 + + - 1.1.10.0 Feb 28, 2007\n + API version : 8 + + - 1.1.9.0 Jan 20, 2007\n + API version : 7 + + - 1.1.8.0 Kerberos for Windows 3.1 Final Nov 22, 2006\n + API version : 6 + + - 1.1.6.0 Kerberos for Windows 3.1 Beta 4 Nov 17, 2006\n + API version : 6 + + - 1.1.4.0 Kerberos for Windows 3.1 Beta 3 Nov 08, 2006\n + API version : 6 + + - 1.1.2.0 Oct 09, 2006\n + API version : 6 + + - 1.1.0.2 Sep 21, 2006\n + API version : 6 + + - 1.1.0.1 Jul 19, 2006\n + API version : 5 + + - 1.1.0.0 Mar 08, 2006\n + API version : 5 + + - 1.0.0.0 Kerberos for Windows 3.0 Dec 05, 2005\n + API version : 4 + + - 0.1.2.0 Second Alpha release Nov 30, 2005\n + API version : 3\n + Released along with Kerberos for Windows 3.0 beta 2. + - 0.1.1 First Alpha release Nov 01, 2005\n - Released along with Kerberos for Windows 3.0.0 beta. + Released along with Kerberos for Windows 3.0 beta. - - 0.1.2 Second Alpha release Nov 30, 2005\n - Released along with Kerberos for Windows 3.0.0 beta 2. */ diff --git a/src/windows/identity/doc/plugin_framework.h b/src/windows/identity/doc/plugin_framework.h index c714284ec..39d6ac18f 100644 --- a/src/windows/identity/doc/plugin_framework.h +++ b/src/windows/identity/doc/plugin_framework.h @@ -1,5 +1,6 @@ /* * 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 @@ -25,49 +26,49 @@ /* $Id$ */ /*! -\page pi_framework Plugin Framework +\page pi_framework Plug-in Framework -\section pi_fw_pnm Plugins and Modules +\section pi_fw_pnm Plug-ins and Modules -\subsection pi_fw_pnm_p Plugins +\subsection pi_fw_pnm_p Plug-ins -A NetIDMgr plugin is a package that implements a defined API that will -perform credentials management or related tasks on behalf of NetIDMgr. -The core NetIDMgr codebase does not interact directly with Kerberos of -AFS or any other external entity directly. Instead, plugins are used -to abstract out this task. +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. -Each plugin has a name. The name should be unique among the loaded -plugins, or the plugin will fail to load. +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 method in which NetIDMgr communicates with a plugin depends on the -plugin type. For more information on each plugin type, please refer +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 plugin types rely on a message processor for communication. -During plugin registration, the module specifies the message processor -for the plugin, which acts as the only point of contact between the -NetIDMgr core and the plugin. Some other plugins require exporting +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. \subsection pi_fw_pnw_m Modules -One or more plugins can be bundled together into a module. A module -is essentially a dynamically loadable library which contain a specific +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 : - init_module(), and - exit_module() -\section pi_fw_pm Plugin/Module Manager +\section pi_fw_pm Plug-in/Module Manager -The plugin manager maintains a separate thread for loading and +The plug-in manager maintains a separate thread for loading and registering modules. When a module is successfully loaded and it -registers one or more plugins, a new thread is created for each -plugin. Plugin specific initialization and other callback functions -are called from within this new thread. This is to prevent one plugin -from "hanging" other plugins and the main NetIDMgr UI threads. +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. Read more : - \ref pi_structure @@ -75,19 +76,19 @@ Read more : \subsection pi_fw_pm_load Load sequence When kmm_load_module() is called, the following sequence of events -happen. +occur: - The standard system search path is used to locate the binary. -- The binary is loaded into the address space of NetIDMgr along with +- The binary is loaded into the address space of Network Identity Manager along with any dependencies not already loaded. -- If the NetIDMgr core binary is signed, then the signature is checked +- 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. - init_module() for the loaded module is called. If this function - returns an error or if no plugins are registered, then the module is + returns an error or if no plug-ins are registered, then the module is unloaded. See \ref pi_fw_pm_unload. - During processing of init_module(), if any localized resource @@ -95,29 +96,30 @@ happen. localized libraries will be loaded. See \ref pi_localization - During processing of init_module(), the module registers all the - plugins that it is implementing by calling kmm_register_plugin() for + plug-ins that it is implementing by calling kmm_register_plug-in() for each. -- Once init_module() returns, each plugin is initialized. The method - by which a plugin is initialized depends on the plugin type. The - initialization code for the plugin may indicate that it didn't - initialize properly, in which case the plugin is immediately - unregistered. No further calls are made to the plugin. +- Once init_module() returns, each plug-in is initialized. The method + by which a plug-in is initialized depends on the plug-in type. The + initialization code for the plug-in may indicate that it didn't + initialize properly, in which case the plug-in is immediately + unregistered. No further calls are made to the plug-in. -- If no plugin is successfully loaded, the module is unloaded. See +- If no plug-in is successfully loaded, the module is unloaded. See \ref pi_fw_pm_unload. -- During normal operation, any registered plugins for a module can be - unloaded explicitly, or the plugin itself may signal that it should - be unloaded. If at anytime, all the plugins for the module are - unloaded, then the module itself is also unloaded. +- 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. \subsection pi_fw_pm_unload Unload sequence -- For each of the plugins that are registered for a module, the exit +- 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 - plugin type. The plugin is not given a chance to object to the - decision to unload. Each plugin is responsible for performing + plug-in type. The plug-in is not given a chance to object to 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. diff --git a/src/windows/identity/doc/plugin_locale.h b/src/windows/identity/doc/plugin_locale.h index 6c3774fa5..646f89570 100644 --- a/src/windows/identity/doc/plugin_locale.h +++ b/src/windows/identity/doc/plugin_locale.h @@ -1,5 +1,6 @@ /* * 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 @@ -32,10 +33,10 @@ localized resource libraries with the module manager when it receives the init_module() callback. Note that you can only register localized resource libraries during init_module(). -The localized resource library is global to a module. Each plugin is +The localized resource library is global to a module. Each plug-in is not allowed to define its own localization library, although it is free to load and use any library as it sees fit. The module manager -does not manage these libraries for the plugin. +does not manage these libraries for the plug-in. \section pi_loc_spec Specification of localized resources @@ -105,3 +106,4 @@ the regular WIN32 API. */ + diff --git a/src/windows/identity/doc/plugin_main.h b/src/windows/identity/doc/plugin_main.h index ed06c6d08..feb4a25d3 100644 --- a/src/windows/identity/doc/plugin_main.h +++ b/src/windows/identity/doc/plugin_main.h @@ -1,5 +1,6 @@ /* * 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 @@ -26,13 +27,13 @@ /*! -\page plugins NetIDMgr Modules and Plugins +\page plug-ins Network Identity Manager Modules and Plug-ins -Plugins and localization are handled by the NetIDMgr Module Manager -API. Each plugin consists of a dynamically loadable library and zero +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. -For more information about NetIDMgr Plugins, see the following +For more information about Network Identity Manager Plug-ins, see the following sections: - \subpage pi_framework @@ -41,37 +42,37 @@ sections: - \subpage pi_localization */ -/*! \page pi_pt Plugin Types +/*! \page pi_pt Plug-in Types -The types of plugins that are currently supported by NetIDMgr are : +The types of plug-ins that are currently supported by Network Identity Manager are : \section pi_pt_cred Credential Provider -A credential provider plugin essentially acts as an interface between -NetIDMgr and some entity which defines the credentials for the purpose +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 NetIDMgr and a credential provider occurs +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. +a valid message processor in the ::khm_plug-in 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 plugins, <::KMSG_SYSTEM,::KMSG_SYSTEM_INIT> is +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 plugin is assume to not be loaded and +value signals an error, then the plug-in is assume to not be loaded and immediately unregistered. The message processor is automatically subscribed to the following @@ -79,22 +80,22 @@ message types: - ::KMSG_SYSTEM - ::KMSG_KCDB -Although a plugin can use the <::KMSG_SYSTEM,::KMSG_SYSTEM_INIT> +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 plugins that may depend +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 plugin is to be removed, the module manager sends a +When the plug-in is to be removed, the module manager sends a <::KMSG_SYSTEM,::KMSG_SYSTEM_EXIT> to the message processor. The -plugin must perform any necessary shutdown operations, free up +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 plugin if the plugin unsubsribes from all +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 @@ -124,3 +125,4 @@ Provides configuration information. */ + diff --git a/src/windows/identity/doc/plugin_structure.h b/src/windows/identity/doc/plugin_structure.h index b41ff3a07..c82af7b69 100644 --- a/src/windows/identity/doc/plugin_structure.h +++ b/src/windows/identity/doc/plugin_structure.h @@ -1,5 +1,6 @@ /* * 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 @@ -28,16 +29,16 @@ \page pi_structure Structure of a module -A NetIDMgr module is essentially a dynamically loadable library with a +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 plugin module are documented below. +notes about writing a plug-in module are documented below. \section pi_str_init Initialization Do not use DllMain or other system specific callback routines to perform intilization tasks other than creating mutexes, initializing thread local storage and other tasks that must be performed at that -stage. Specifically, do not call any NetIDMgr API functions from +stage. Specifically, do not call any Network Identity Manager API functions from within DllMain. \section pi_str_cb Callbacks diff --git a/src/windows/identity/doc/stylesheet.css b/src/windows/identity/doc/stylesheet.css index fc3e0624d..ddc3d1f54 100644 --- a/src/windows/identity/doc/stylesheet.css +++ b/src/windows/identity/doc/stylesheet.css @@ -1,62 +1,87 @@ BODY,H1,H2,H3,H4,H5,H6,P,CENTER,TD,TH,UL,DL,DIV { font-family: Geneva, Arial, Helvetica, sans-serif; } +BODY,TD { + font-size: 90%; +} H1 { text-align: center; + font-size: 160%; +} +H2 { + font-size: 120%; +} +H3 { + font-size: 100%; } CAPTION { font-weight: bold } DIV.qindex { width: 100%; - background-color: #000000; - border: 1px solid #000000; + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; margin: 2px; padding: 2px; - line-height: 100%; - color: #ffffff + line-height: 140%; } DIV.nav { width: 100%; - background-color: #000000; - border: 1px solid #000000; + background-color: #e8eef2; + border: 1px solid #84b0c7; text-align: center; margin: 2px; padding: 2px; - line-height: 100%; - color: #ffffff; + line-height: 140%; +} +DIV.navtab { + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + margin-right: 15px; + padding: 2px; +} +TD.navtab { + font-size: 70%; } A.qindex { text-decoration: none; - color: #ffffff; + font-weight: bold; + color: #1A419D; } A.qindex:visited { text-decoration: none; - color: #ffffff; + font-weight: bold; + color: #1A419D } A.qindex:hover { text-decoration: none; - background-color: #ffffff; - color: #000000 + background-color: #ddddff; } A.qindexHL { text-decoration: none; font-weight: bold; + background-color: #6666cc; + color: #ffffff; + border: 1px double #9295C2; } A.qindexHL:hover { text-decoration: none; - background-color: #333333; + background-color: #6666cc; color: #ffffff; } -A.qindexHL:visited { text-decoration: none; background-color: #333333; color: #ffffff } -A.el { text-decoration: none; } -A.elRef { } +A.qindexHL:visited { text-decoration: none; background-color: #6666cc; color: #ffffff } +A.el { text-decoration: none; font-weight: bold } +A.elRef { font-weight: bold } A.code:link { text-decoration: none; font-weight: normal; color: #0000FF} A.code:visited { text-decoration: none; font-weight: normal; color: #0000FF} A.codeRef:link { font-weight: normal; color: #0000FF} A.codeRef:visited { font-weight: normal; color: #0000FF} -A:hover { text-decoration: none; background-color: #cccccc } +A:hover { text-decoration: none; background-color: #f2f2ff } DL.el { margin-left: -1cm } .fragment { - font-family: monospace + font-family: monospace, fixed; + font-size: 95%; } PRE.fragment { border: 1px solid #CCCCCC; @@ -71,16 +96,14 @@ PRE.fragment { padding-bottom: 4px; } DIV.ah { background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px } -TD.md { background-color: #cccccc; font-weight: bold; } -TD.mdname1 { background-color: #cccccc; font-weight: bold; color: #000000; } -TD.mdname { background-color: #cccccc; font-weight: bold; color: #000000; width: 600px; } + DIV.groupHeader { margin-left: 16px; margin-top: 12px; margin-bottom: 6px; font-weight: bold; } -DIV.groupText { margin-left: 16px; font-style: italic; font-size: 14px } +DIV.groupText { margin-left: 16px; font-style: italic; font-size: 90% } BODY { background: white; color: black; @@ -88,7 +111,7 @@ BODY { margin-left: 20px; } TD.indexkey { - background-color: #cccccc; + background-color: #e8eef2; font-weight: bold; padding-right : 10px; padding-top : 2px; @@ -101,7 +124,7 @@ TD.indexkey { border: 1px solid #CCCCCC; } TD.indexvalue { - background-color: #cccccc; + background-color: #e8eef2; font-style: italic; padding-right : 10px; padding-top : 2px; @@ -114,7 +137,7 @@ TD.indexvalue { border: 1px solid #CCCCCC; } TR.memlist { - background-color: #f0f0f0; + background-color: #f0f0f0; } P.formulaDsp { text-align: center; } IMG.formulaDsp { } @@ -126,16 +149,9 @@ SPAN.comment { color: #800000 } SPAN.preprocessor { color: #806020 } SPAN.stringliteral { color: #002080 } SPAN.charliteral { color: #008080 } -.mdTable { - border: 1px solid #cccccc; - background-color: #cccccc; -} -.mdRow { - padding: 8px 10px; -} .mdescLeft { padding: 0px 8px 4px 8px; - font-size: 12px; + font-size: 80%; font-style: italic; background-color: #FAFAFA; border-top: 1px none #E0E0E0; @@ -146,7 +162,7 @@ SPAN.charliteral { color: #008080 } } .mdescRight { padding: 0px 8px 4px 8px; - font-size: 12px; + font-size: 80%; font-style: italic; background-color: #FAFAFA; border-top: 1px none #E0E0E0; @@ -171,7 +187,7 @@ SPAN.charliteral { color: #008080 } border-bottom-style: none; border-left-style: none; background-color: #FAFAFA; - font-size: 12px; + font-size: 80%; } .memItemRight { padding: 1px 8px 0px 8px; @@ -189,7 +205,7 @@ SPAN.charliteral { color: #008080 } border-bottom-style: none; border-left-style: none; background-color: #FAFAFA; - font-size: 13px; + font-size: 80%; } .memTemplItemLeft { padding: 1px 0px 0px 8px; @@ -207,7 +223,7 @@ SPAN.charliteral { color: #008080 } border-bottom-style: none; border-left-style: none; background-color: #FAFAFA; - font-size: 12px; + font-size: 80%; } .memTemplItemRight { padding: 1px 8px 0px 8px; @@ -225,7 +241,7 @@ SPAN.charliteral { color: #008080 } border-bottom-style: none; border-left-style: none; background-color: #FAFAFA; - font-size: 13px; + font-size: 80%; } .memTemplParams { padding: 1px 0px 0px 8px; @@ -244,7 +260,7 @@ SPAN.charliteral { color: #008080 } border-left-style: none; color: #606060; background-color: #FAFAFA; - font-size: 12px; + font-size: 80%; } .search { color: #003399; font-weight: bold; @@ -256,16 +272,88 @@ FORM.search { INPUT.search { font-size: 75%; color: #000080; font-weight: normal; - background-color: #ffcc99; + background-color: #e8eef2; } TD.tiny { font-size: 75%; } a { - color: #0000ff; + color: #1A41A8; } a:visited { - color: #0000ff; + color: #2A3798; +} +.dirtab { padding: 4px; + border-collapse: collapse; + border: 1px solid #84b0c7; +} +TH.dirtab { background: #e8eef2; + font-weight: bold; +} +HR { height: 1px; + border: none; + border-top: 1px solid black; + border-color: #88b7c8; +} + +/* Style for detailed member documentation */ +.memtemplate { + font-size: 80%; + color: #606060; + font-weight: normal; +} +.memnav { + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + margin-right: 15px; + padding: 2px; +} +.memitem { + padding: 4px; + background-color: #eef3f5; + border-width: 1px; + border-style: solid; + border-color: #dedeee; + -moz-border-radius: 8px 8px 8px 8px; +} +.memname { + white-space: nowrap; + font-weight: bold; +} +.memdoc{ + padding-left: 10px; +} +.memproto { + background-color: #d5e1e8; + width: 100%; + border-width: 1px; + border-style: solid; + border-color: #84b0c7; + font-weight: bold; + -moz-border-radius: 8px 8px 8px 8px; +} +.paramkey { + text-align: right; +} +.paramtype { + white-space: nowrap; +} +.paramname { + color: #602020; + font-style: italic; + white-space: nowrap; +} +/* End Styling for detailed member documentation */ + +/* for the tree view */ +.ftvtree { + font-family: sans-serif; + margin:0.5em; } -.anchor { - color: #000000; -} \ No newline at end of file +.directory { font-size: 9pt; font-weight: bold; } +.directory h3 { margin: 0px; margin-top: 1em; font-size: 11pt; } +.directory > h3 { margin-top: 0; } +.directory p { margin: 0px; white-space: nowrap; } +.directory div { display: none; margin: 0px; } +.directory img { vertical-align: -30%; } diff --git a/src/windows/identity/doc/ui_actions.h b/src/windows/identity/doc/ui_actions.h index de4e802e3..43bf3a94f 100644 --- a/src/windows/identity/doc/ui_actions.h +++ b/src/windows/identity/doc/ui_actions.h @@ -1,5 +1,6 @@ /* * 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 diff --git a/src/windows/identity/doc/ui_context.h b/src/windows/identity/doc/ui_context.h index b9bfadd6b..12843fb46 100644 --- a/src/windows/identity/doc/ui_context.h +++ b/src/windows/identity/doc/ui_context.h @@ -1,5 +1,6 @@ /* * 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 @@ -38,7 +39,7 @@ context functions and data structures provide access to this information. - The NetIDMgr user interface presents an outline view of all the + The Network Identity Manager user interface presents an outline view of all the credentials that were provided by credentials providers. This view consists of headers representing the outline levels and rows representing individual credentials. @@ -99,12 +100,12 @@ obtain and store the context in a location that is accessible to the handlers of the message. - If a plugin needs to obtain the UI context, it should do so by + If a plug-in needs to obtain the UI context, it should do so by calling khui_context_get() and passing in a pointer to a ::khui_action_context structure. Once obtained, the contents of the ::khui_action_context structure - should be considered read-only. When the plugin is done with the + should be considered read-only. When the plug-in is done with the structure, it should call ::khui_context_release(). This cleans up any additional memory allocated for storing the context as well as releasing all the objects that were referenced from the diff --git a/src/windows/identity/doc/ui_main.h b/src/windows/identity/doc/ui_main.h index 6e17980a9..d7bc6be00 100644 --- a/src/windows/identity/doc/ui_main.h +++ b/src/windows/identity/doc/ui_main.h @@ -1,5 +1,6 @@ /* * 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 diff --git a/src/windows/identity/doc/ui_menus.h b/src/windows/identity/doc/ui_menus.h index 09cc16e67..794aef6ca 100644 --- a/src/windows/identity/doc/ui_menus.h +++ b/src/windows/identity/doc/ui_menus.h @@ -1,5 +1,6 @@ /* * 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 -- 2.26.2