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

Responding to credential acquisition messages

<::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:

• type : KMSG_CRED
• subtype: KMSG_CRED_NEW_CREDS or KMSG_CRED_RENEW_CREDS
• uparam : 0 (unused)
• vparam : a pointer to a khui_new_creds structure.

The vparam parameter of the message, as shown above, is a pointer to a khui_new_creds structure. You can use the 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.

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 name field defines a localized string that will be displayed in the tab control that houses the panel. If it is NULL, then the name of the credentials type is used. Optionally, an icon can be specified in the icon field which will appear alongside the name. A tooltip may be provided in the 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 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 name). Then the panels without a positive ordianl are arranged behind these in increasing order of 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:

       // 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
       }

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 Writing the dialog procedure for a cred type panel .

---