64afcdaa5e04fe9589629cd82530eef8a567d7d9
[openafs.git] / 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 starightforward.  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 targetting 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 ------------------------------------------------------------------