
  Network Identity Manager

        Credentials Provider Plug-in Template

------------------------------------------------------------------

        CONTENTS

        1.  INTRODUCTION
        2.  COPYRIGHT AND LICENSE
        3.  ROADMAP OF THE TEMPLATE
        4.  BUILD REQUIREMENTS
        5.  BUILDING
        6.  RUNNING THE PLUG-IN
        7.  KNOWN ISSUES
        8.  SUPPORT / BUG REPORTS

------------------------------------------------------------------

1.      INTRODUCTION

    This directory and subdirectories contain a plug-in template for
    creating a credentials provider plug-in for Network Identity
    Manager.  A credentials manager plug-in provides knowledge of a
    specifc credentials type to the NetIDMgr application and manages
    those credentials on behalf of NetIDMgr.

    This version of the template adheres to the following version
    constraints:

        Network Identity Manager API version : 5

    (This API version corresponds to the MIT Kerberos for Windows
    version 3.1).

    The source files in this template can be used to build the plug-in
    DLL and the US English resource DLL for the plug-in.  In its
    current form, the plug-in doesn't do any credentials management.
    However, it implements a number of stub functions that can be
    filled in to perform the necessary credentials management
    operations.

------------------------------------------------------------------

2.      COPYRIGHT AND LICENSE

    Copyright (c) 2006 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.

------------------------------------------------------------------

3.      ROADMAP OF THE TEMPLATE

    The template consists of the following files and directories:

    .\README

        This file.

    .\Makefile

        The primary (and only) Makefile used by 'nmake' to build the
        plug-in.  In addition to providing build directives, it also
        contains a set of macros which defines the names and version
        information that is used throughout the plug-in code.

        Look for the 'Configuration Settings' section of the Makefile
        for the macros.  If you are basing a plug-in on this template,
        you will want to change these macros.  These macros will be
        used to generate 'credacq_config.h', a header file included by
        'credprov.h' so that the values of the macros can be used in C
        code.

    .\credprov.h

        The main header file for all the C source files in the
        plug-in.

    .\main.c

        Provides the entry points for the module.

    .\plugin.c

        Provides the message processing functions and support routines
        for implementing the plug-in.  Note that some of the message
        processing routines have been moved to other sources files
        based on their use.

    .\credtype.c

        Functions for handling our credentials type.

    .\credacq.c

        Handlers for the credentials acquisition messages including
        handling the user interface for the new credentials dialogs.

    .\proppage.c

        Dialog procedures and support code for displaying property
        sheets for credentials that belong to our credentials type.

    .\config_main.c

        Dialog procedures and support code for providing the general
        configuration panel for this plug-in.

    .\config_id.c

        Dialog procedures and support code for providing per-identity
        configuration for this plug-in.

    .\config_ids.c

        Dialog procedures and support code for providing configuration
        for defaults across all identities.

    .\version.rc

        Version information for the plug-in as well as all the
        language resource DLLs.

    .\langres.h

        Declarations for the language resources (see below).  In its
        current form, it was generated via Visual Studio while editing
        the language resouces file.

    .\images\plugin.ico

        A generic plug-in icon.

    .\lang\en_us\langres.rc

        US-English language resources.  This will be used to create
        the language resource DLL.

------------------------------------------------------------------

4.      BUILD REQUIREMENTS

    Microsoft(R) Platform SDK (Windows Server 2003 or later)

        (http://www.microsoft.com/msdownload/platformsdk/sdkupdate/)

    Microsoft(R) Visual C++ (Visual Studio 2003 or later)

        Although not tested, the template should build using the
        Microsoft Visual C++ toolkit.

    MIT Kerberos for Windows (version 3.1 or later) SDK

        At the current time, version 3.1 is still in beta.  However,
        the template will not work with the 3.0 SDK due to a number of
        changes that were made to the NetIDMgr API between 3.0 and
        3.1.

------------------------------------------------------------------

5.      BUILDING

    The build process is fairly starightforward.  The source is set up
    to build using 'nmake', a build tool distributed with the Platform
    SDK as well as with Visual Studio.

    1.  Open a command prompt with a suitable build environment.

        From a plain command prompt, you can set up a debug build
        environment targetting Windows XP (32-bit) with:

        > "%PROGRAMFILES%\Microsoft Platform SDK\SetEnv.Cmd" /XP32 /DEBUG

    2.  Set the environment variable KFWSDKDIR to point to the root of
        the Kerberos for Windows 3.1 SDK.  (i.e. %KFWSDKDIR%\inc
        should be the include directory of the SDK)

        > SET KFWSDKDIR=%PROGRAMFILES%\MIT\Kerberos

    3.  Start the build:

        > NMAKE all

        The build target 'all' builds the plug-in and the language
        resources.  There is an additional build target 'clean' which
        removes the temporary files and the binaries generated during
        the build.

        Assuming everything goes well, the plug-in binaries should be
        created under a subdirectory under 'dest'.  The name of the
        subdirectory reflects the target architecture and the build
        type ('debug' or 'release').

------------------------------------------------------------------

6.      RUNNING THE PLUG-IN

    Once the binaries for the plug-in have been built, you need to
    register the plug-in with NetIDMgr by adding a registry value as
    follows:

    [HKEY_CURRENT_USER\Software\MIT\NetIDMgr\PluginManager\Modules\<Module name>]
       "ImagePath"="<path>"

    The <path> should be the full path to the plug-in DLL.

    <Module name> is the name of the module that you built.  The
    default value specified in the template is 'MyModule'.  This is
    the value of the macro 'MODULENAME' defined in the 'Makefile'.

    Once this is done, you need to restart NetIDMgr so that it will
    pick up the new plug-in.

------------------------------------------------------------------

7.      KNOWN ISSUES

    1.  With the current MIT Kerberos for Windows 3.1 beta, NetIDMgr
        will fail to load the plug-in when tries to load the plug-in
        for the first time.  Restarting NetIDMgr will fix the problem.
        This will be fixed in a future beta and the final release of
        KfW 3.1

------------------------------------------------------------------

8.      SUPPORT / BUG REPORTS

    Problems should be sent to netidmgr@secure-endpoints.com

------------------------------------------------------------------
