src/WINNT/netidmgr_plugin/extensions/sample/README

   1
   2   OpenAFS Network Identity Provider Plug-in
   3
   4         OpenAFS Plug-in Extension Template
   5
   6 ------------------------------------------------------------------
   7
   8         CONTENTS
   9
  10         1.  INTRODUCTION
  11         2.  COPYRIGHT AND LICENSE
  12         3.  ROADMAP OF THE TEMPLATE
  13         4.  BUILD REQUIREMENTS
  14         5.  BUILDING
  15         6.  RUNNING THE PLUG-IN
  16         7.  KNOWN ISSUES
  17         8.  SUPPORT / BUG REPORTS
  18
  19 ------------------------------------------------------------------
  20
  21 1.      INTRODUCTION
  22
  23     This directory and subdirectories contain a plug-in template for
  24     creating an extension for the OpenAFS Network Identity Manager
  25     plug-in.  Currently, such extensions are limited to providing
  26     additional authentication methods.
  27
  28     This version of the template adheres to the following version
  29     constraints:
  30
  31         Network Identity Manager API version : 10 or later
  32         OpenAFS Plug-in Version              :  1 or later
  33
  34     The source files in this template can be used to build the plug-in
  35     DLL and the US English resource DLL for the plug-in.  In its
  36     current form, the plug-in doesn't do much.  However, the source
  37     code contains a number of stub functions that can be used to
  38     implement your extension.
  39
  40     Note that this template is based on the credentials provider
  41     template in the Network Identity Manager SDK, and has numerous
  42     references to credentials providers that are not applicable to
  43     this particular type of plug-in.
  44
  45 ------------------------------------------------------------------
  46
  47 2.      COPYRIGHT AND LICENSE
  48
  49     Copyright (c) 2008 Secure Endpoints Inc.
  50
  51     Permission is hereby granted, free of charge, to any person
  52     obtaining a copy of this software and associated documentation
  53     files (the "Software"), to deal in the Software without
  54     restriction, including without limitation the rights to use, copy,
  55     modify, merge, publish, distribute, sublicense, and/or sell copies
  56     of the Software, and to permit persons to whom the Software is
  57     furnished to do so, subject to the following conditions:
  58
  59     The above copyright notice and this permission notice shall be
  60     included in all copies or substantial portions of the Software.
  61
  62     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  63     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  64     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  65     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  66     HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  67     WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  68     OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  69     DEALINGS IN THE SOFTWARE.
  70
  71 ------------------------------------------------------------------
  72
  73 3.      ROADMAP OF THE TEMPLATE
  74
  75     The files and directories included in the template are described
  76     below.  The files that you most likely want to change are
  77     Makefile, afspext.c, version.rc and lang\en_us\langres.rc.
  78
  79     .\README
  80
  81         This file.
  82
  83     .\Makefile
  84
  85         The primary (and only) Makefile used by 'nmake' to build the
  86         plug-in.  In addition to providing build directives, it also
  87         contains a set of macros which defines the names and version
  88         information that is used throughout the plug-in code.
  89
  90         Look for the 'Configuration Settings' section of the Makefile
  91         for the macros.  If you are basing a plug-in on this template,
  92         you will want to change these macros.  These macros will be
  93         used to generate 'credacq_config.h', a header file included by
  94         'credprov.h' so that the values of the macros can be used in C
  95         code.
  96
  97     .\credprov.h
  98
  99         The main header file for all the C source files in the
 100         plug-in.
 101
 102     .\main.c
 103
 104         Provides the entry points for the module.
 105
 106     .\plugin.c
 107
 108         Provides the message processing functions and support routines
 109         for implementing the plug-in.  Note that some of the message
 110         processing routines have been moved to other sources files
 111         based on their use.
 112
 113     .\afspext.c
 114
 115         The message handler for AFS_MSG messages. The OpenAFS plug-in
 116         uses these messages to communicate with its extensions.  This
 117         is probably the only C source file you would want to modify
 118         when implementing an extension plug-in for the OpenAFS
 119         plug-in.
 120
 121     .\config_main.c
 122
 123         Dialog procedures and support code for providing the general
 124         configuration panel for this plug-in.  Providing a
 125         configuration panel isn't required for an extension plug-in.
 126
 127     .\version.rc
 128
 129         Version information for the plug-in as well as all the
 130         language resource DLLs.
 131
 132     .\langres.h
 133
 134         Declarations for the language resources (see below).  In its
 135         current form, it was generated via Visual Studio while editing
 136         the language resouces file.
 137
 138     .\images\plugin.ico
 139
 140         A generic plug-in icon.
 141
 142     .\lang\en_us\langres.rc
 143
 144         US-English language resources.  This will be used to create
 145         the language resource DLL.
 146
 147 ------------------------------------------------------------------
 148
 149 4.      BUILD REQUIREMENTS
 150
 151     Microsoft(R) Platform SDK (Windows Server 2003 or later)
 152
 153         (http://www.microsoft.com/msdownload/platformsdk/sdkupdate/)
 154
 155     Microsoft(R) Visual C++ (Visual Studio 2003 or later)
 156
 157         Although not tested, the template should build using the
 158         Microsoft Visual C++ toolkit.
 159
 160     MIT Kerberos for Windows (version 3.2 or later) SDK
 161
 162     OpenAFS for Windows 1.5.x SDK or source
 163
 164         The only file that is needed for building an extension plug-in
 165         is afspext.h.
 166
 167 ------------------------------------------------------------------
 168
 169 5.      BUILDING
 170
 171     The build process is fairly straightforward.  The source is set up
 172     to build using 'nmake', a build tool distributed with the Platform
 173     SDK as well as with Visual Studio.
 174
 175     1.  Open a command prompt with a suitable build environment.
 176
 177         From a plain command prompt, you can set up a debug build
 178         environment targeting Windows XP (32-bit) with:
 179
 180         > "%PROGRAMFILES%\Microsoft Platform SDK\SetEnv.Cmd" /XP32 /DEBUG
 181
 182     2.  Set the environment variable KFWSDKDIR to point to the root of
 183         the Kerberos for Windows 3.1 SDK.  (i.e. %KFWSDKDIR%\inc
 184         should be the include directory of the SDK)
 185
 186         > SET KFWSDKDIR=%PROGRAMFILES%\MIT\Kerberos
 187
 188     3.  Set the environment variable AFSPLUGINDIR to the directory
 189         that contains afspext.h.  This could either be in the OpenAFS
 190         SDK include directory or in the source tree at
 191         src\WINNT\netidmgr_plugin.
 192
 193         > SET AFSPLUGINDIR=...
 194
 195     4.  Start the build:
 196
 197         > NMAKE all
 198
 199         The build target 'all' builds the plug-in and the language
 200         resources.  There is an additional build target 'clean' which
 201         removes the temporary files and the binaries generated during
 202         the build.
 203
 204         Assuming everything goes well, the plug-in binaries should be
 205         created under a subdirectory under 'dest'.  The name of the
 206         subdirectory reflects the target architecture and the build
 207         type ('debug' or 'release').
 208
 209 ------------------------------------------------------------------
 210
 211 6.      RUNNING THE PLUG-IN
 212
 213     Once the binaries for the plug-in have been built, you need to
 214     register the plug-in with NetIDMgr by adding a registry value as
 215     follows:
 216
 217     [HKEY_CURRENT_USER\Software\MIT\NetIDMgr\PluginManager\Modules\<Module name>]
 218        "ImagePath"="<path>"
 219
 220     The <path> should be the full path to the plug-in DLL.
 221
 222     <Module name> is the name of the module that you built.  The
 223     default value specified in the template is 'MyAFSExtModule'.  This
 224     is the value of the macro 'MODULENAME' defined in the 'Makefile'.
 225
 226     Once this is done, you need to restart NetIDMgr so that it will
 227     pick up the new plug-in.
 228
 229 ------------------------------------------------------------------
 230
 231 7.      KNOWN ISSUES
 232
 233 ------------------------------------------------------------------
 234
 235 8.      SUPPORT / BUG REPORTS
 236
 237     Problems should be sent to openafs@secure-endpoints.com
 238
 239 ------------------------------------------------------------------