diff options
Diffstat (limited to 'src/windows/identity/doc/cred_aquisition.h')
| -rw-r--r-- | src/windows/identity/doc/cred_aquisition.h | 325 |
1 files changed, 0 insertions, 325 deletions
diff --git a/src/windows/identity/doc/cred_aquisition.h b/src/windows/identity/doc/cred_aquisition.h deleted file mode 100644 index 0161f74f1..000000000 --- a/src/windows/identity/doc/cred_aquisition.h +++ /dev/null @@ -1,325 +0,0 @@ -/* - * 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 cred_acq Managed credential acquisition - - 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 renew - credentials for an existing identity. - - There are two major processes that result in managed credential - 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_new New Credentials - - When a user initiates the process of initial credential - 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_renew Renew Credentials - - 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: - - - \subpage cred_acq_new_resp - - \subpage cred_acq_dlgproc - */ - -/*! \page cred_acq_new_resp Handling new credentials acquisition - - The process of acquiring credentials happens as follows: - - - Network Identity Manager creates a ::khui_new_creds object and a - credentials acquisition window. - - - <::KMSG_CRED,::KMSG_CRED_RENEW_CREDS> or - <::KMSG_CRED,::KMSG_CRED_NEW_CREDS> is sent to all the - credentials providers. - - - The credential providers create the panels (where appropriate) - 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. (See khui_cw_add_type()). - - - <::KMSG_CRED, ::KMSG_CRED_DIALOG_PRESTART> is sent to all the - credentials providers. - - - <::KMSG_CRED, ::KMSG_CRED_DIALOG_START> is sent to all the - credentials providers. - - - The dialog for obtaining credentials is displayed. - Notifications between the main dialog and the individual panels - are done through ::KHUI_WM_NC_NOTIFY messages to the dialog - procedures. - - - 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 \c 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. - - - Once all the plug-ins have processed the <::KMSG_CRED, - ::KMSG_CRED_DIALOG_PROCESS> message, the application checks - whether the new credentials dialog should continue processing, - or whether the dialog should be closed. If the dialog should - continue processing, then the dialog returns to the state it was - in prior to the ::WMNC_DIALOG_PREPROCESS message was sent. If - the dialog should be closed, then a <::KMSG_CRED, - ::KMSG_CRED_END> message is sent. - - - 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 - - \subsection cred_acq_handle_init <::KMSG_CRED,::KMSG_CRED_NEW_CREDS> and <::KMSG_CRED,::KMSG_CRED_RENEW_CREDS> Messages - - The credential acquisition messages are - <::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_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 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_creds_by_type structure. - - \subsubsection 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_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. 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 - the tab. - - In order to assert that the tab appears at a specific position in - the list of tabs, you can specify a positive number in the \a - ordinal field. Zero does not count as a valid ordinal. The - panels with positive ordinals are arranged first in increasing - order of ordinal (conflicts are resolved by sorting along the \a - name). Then the panels without a positive ordianl are arranged - behind these in increasing order of \a name. - - 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 example code which suggests how this could be done: - - \code - // Message handling code for KMSG_CRED_NEW_CREDS or - // KMSG_CRED_INIT_CREDS - ... - khui_new_creds * c; - khui_new_creds_by_type * t; - - c = (khui_new_creds *) vparam; - t = PMALLOC(sizeof(*t)); - ZeroMemory(t, sizeof(*t)); - - t->type = my_cred_type; - - // set look and feel params - t->ordinal = 3; // third in line - t->name = L"My panel name"; - t->icon = LoadIcon(my_hInstance, MAKEINTRESOURCE(IDI_PANEL_ICON)); - t->tooltip = L"Configure credentials of my type"; - - // 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 - } - \endcode - - 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_END> message is received. - - For information on how the dialog procedure should be written, see - \ref cred_acq_dlgproc . - -*/ - -/*! \page cred_acq_dlgproc Writing the dialog procedure for a cred type panel - - Once each credentials provider has had a chance to add a - credentials type panel for the new credentials dialog, the - application will attempt to create all the dialog panels. It will - use the dialog template and the dialog procedure specified in the - \c dlg_proc and \c dlg_template members of the - ::khui_new_creds_by_type structure. - - The credentials type panel will be an ordinary dialog that is - created as a child of the new credentials window. Therefore, the - dialog template should have the WS_CHILD style and the - WS_EX_CONTROLPARENT extended style set so that the main dialog - procedure can correctly navigate the child dialog. - - \section cred_acq_dlgmsg Handling Messages - - \subsection cred_acq_dlg_WM_INITDIALOG WM_INITDIALOG - - When the application creates a credentials type panel dialog, it - passes a pointer to the ::khui_new_creds structure as the \c - LPARAM parameter. This can be used to query for the credentials - type panel for the plug-in, as follows: - - \code - - // Handler for WM_INITDIALOG: - // HWND hwnd, WPARAM wParam and LPARAM lParam - - khui_new_creds * nc = NULL; - khui_new_creds_by_type * nct = NULL; - - // We can define and use a structure like the following to - // maintain the data that will be used to drive the dialog user - // interface and to store credentials type settings: - struct nc_dialog_data * d = NULL; - - nc = (khui_new_creds *) lParam; - - // Now we can use nc to query for our credentials type structure - khui_cw_find_type(nc, credtype_id, &nct); - - assert(nct); - - // The dialog data structure should live until we receive - // WM_DESTROY. - d = malloc(sizeof(*d)); - ZeroMemory(d, sizeof(*d)); - - d->nc = nc; - d->nct = nct; - - // Store it as our user data for the dialog. - SetWindowLongPtr(hwnd, DWLP_USER, (LPARAM) d); - - // The aux member of the khui_new_creds_by_type structure is - // reserved for use by the credentials provider. We can use it to - // store our dialog data. This way, the dialog procedure and the - // plug-in thread can both access it and use it to store - // credential options for use when obtaining credentials. The - // dialog and the dialog data exist until KMSG_CRED_END is sent. - nct->aux = (LPARAM) d; - - // We should return FALSE here to indicate that we don't want to - // set keyboard focus to this dialog yet. The application will - // attempt to create all the credentials type panels as well as - // the other child dialogs used for the new credentials opeartion. - return FALSE; - - \endcode - - \subsection cred_acq_dlg_WM_NC_NOTIFY WM_NC_NOTIFY - - ::WM_NC_NOTIFY is a special window message that Network Identity - Manager uses to communicate with credentials type panels. The - messages are listed in the ::khui_wm_nc_notifications enumeration. - The format of the message is as follows: - - - uMsg : KHUI_WM_NC_NOTIFY - - HIWORD(wParam) : one of ::khui_wm_nc_notifications - - LPARAM : pointer to the ::khui_new_creds structure (except where noted) - - The ::WM_NC_NOTIFY notifications that a credentials provider is - expected to handle are the following: - - - ::WMNC_IDENTITY_CHANGE - - \copydoc WMNC_IDENTITY_CHANGE - - - ::WMNC_DIALOG_MOVE - - \copydoc WMNC_DIALOG_MOVE - - - ::WMNC_UPDATE_CREDTEXT - - \copydoc WMNC_UPDATE_CREDTEXT - - - ::WMNC_CREDTEXT_LINK - - \copydoc WMNC_CREDTEXT_LINK - - - ::WMNC_DIALOG_PREPROCESS - - \copydoc WMNC_DIALOG_PREPROCESS - - \section cred_acq_other Other notes - -*/ |