]>
Commit | Line | Data |
---|---|---|
4d8743f4 RL |
1 | |
2 | INSTALLATION ON THE NETWARE PLATFORM | |
3 | ------------------------------------ | |
4 | ||
5 | Notes about building OpenSSL for NetWare. | |
6 | ||
7 | ||
8 | BUILD PLATFORM: | |
9 | --------------- | |
10 | The build scripts (batch files, perl scripts, etc) have been developed and | |
11 | tested on W2K. The scripts should run fine on other Windows | |
12 | platforms (NT, Win9x, WinXP) but they haven't been tested. They may require | |
13 | some modifications. | |
14 | ||
15 | ||
16 | Supported NetWare Platforms - NetWare 5.x, NetWare 6.x: | |
17 | ------------------------------------------ | |
18 | OpenSSL uses the WinSock interfaces introduced in NetWare 5. Therefore, | |
19 | previous versions of NetWare, 4.x and 3.x, are not supported. | |
20 | ||
21 | On NetWare there are two c-runtime libraries. There is the legacy CLIB | |
22 | interfaces and the newer LibC interfaces. Being ANSI-C libraries, the | |
23 | functionality in CLIB and LibC is similar but the LibC interfaces are built | |
24 | using Novell Kernal Services (NKS) which is designed to leverage | |
25 | multi-processor environments. | |
26 | ||
27 | The NetWare port of OpenSSL can configured to build using CLIB or LibC. The | |
28 | CLIB build was developed and tested using NetWare 5.0 sp6.0a. The LibC | |
29 | build was developed and tested using the NetWare 6.0 FCS. | |
30 | ||
31 | The necessary LibC functionality ships with NetWare 6. However, earlier | |
32 | NetWare 5.x versions will require updates in order to run the OpenSSL LibC | |
33 | build. | |
34 | ||
35 | ||
36 | REQUIRED TOOLS: | |
37 | --------------- | |
38 | Based upon the configuration and build options used, some or all of the | |
39 | following tools may be required: | |
40 | ||
41 | ||
42 | * Perl for Win32 - required (http://www.activestate.com/ActivePerl) | |
43 | Used to run the various perl scripts on the build platform. | |
44 | ||
45 | ||
46 | * Perl 5.8.0 for NetWare v3.20 (or later) - required | |
47 | (http://developer.novell.com) Used to run the test script on NetWare | |
48 | after building. | |
49 | ||
50 | ||
51 | * Metrowerks CodeWarrior PDK 2.1 (or later) for NetWare - required: | |
52 | Provides command line tools used for building. | |
53 | ||
54 | Tools: | |
55 | mwccnlm.exe - C/C++ Compiler for NetWare | |
56 | mwldnlm.exe - Linker for NetWare | |
57 | mwasmnlm.exe - x86 assembler for NetWare (if using assembly option) | |
58 | ||
59 | ||
60 | * Assemblers - optional: | |
61 | If you intend to build using the assembly options you will need an | |
62 | assembler. Work has been completed to support two assemblers, Metrowerks | |
63 | and NASM. However, during development, a bug was found in the Metrowerks | |
64 | assembler which generates incorrect code. Until this problem is fixed, | |
65 | the Metrowerks assembler cannot be used. | |
66 | ||
67 | mwasmnlm.exe - Metrowerks x86 assembler - part of CodeWarrior tools. | |
68 | (version 2.2 Built Aug 23, 1999 - not useable due to code | |
69 | generation bug) | |
70 | ||
71 | nasmw.exe - Netwide Assembler NASM | |
72 | version 0.98 was used in development and testing | |
73 | ||
74 | * Make Tool - required: | |
75 | In order to build you will need a make tool. Two make tools are | |
76 | supported, GNU make (gmake.exe) or Microsoft nmake.exe. | |
77 | ||
78 | gmake.exe - GNU make for Windows (version 3.75 used for development) | |
79 | http://www.gnu.org/software/make/make.html | |
80 | ||
81 | nmake.exe - Microsoft make (Version 6.00.8168.0 used for development) | |
82 | ||
83 | ||
84 | * Novell Developer Kit (NDK) - required: (http://developer.novell.com) | |
85 | ||
86 | CLIB - BUILDS: | |
87 | ||
88 | WinSock2 Developer Components for NetWare: | |
89 | For initial development, the October 27, 2000 version was used. | |
90 | However, future versions should also work. | |
91 | ||
92 | NOTE: The WinSock2 components include headers & import files for | |
93 | NetWare, but you will also need the winsock2.h and supporting | |
94 | headers (pshpack4.h, poppack.h, qos.h) delivered in the | |
95 | Microsoft SDK. Note: The winsock2.h support headers may change | |
96 | with various versions of winsock2.h. Check the dependencies | |
97 | section on the NDK WinSock2 download page for the latest | |
98 | information on dependencies. | |
99 | ||
100 | ||
101 | NLM and NetWare libraries for C (including CLIB and XPlat): | |
47c1735a RL |
102 | If you are going to build a CLIB version of OpenSSL, you will |
103 | need the CLIB headers and imports. The March, 2001 NDK release or | |
104 | later is recommended. | |
4d8743f4 RL |
105 | |
106 | Earlier versions should work but haven't been tested. In recent | |
107 | versions the import files have been consolidated and function | |
108 | names moved. This means you may run into link problems | |
109 | (undefined symbols) when using earlier versions. The functions | |
110 | are available in earlier versions, but you will have to modifiy | |
111 | the make files to include additional import files (see | |
112 | openssl\util\pl\netware.pl). | |
113 | ||
114 | ||
115 | LIBC - BUILDS: | |
116 | ||
117 | Libraries for C (LibC) - LibC headers and import files | |
47c1735a RL |
118 | If you are going to build a LibC version of OpenSSL, you will |
119 | need the LibC headers and imports. The March 14, 2002 NDK release or | |
120 | later is required. | |
4d8743f4 RL |
121 | |
122 | NOTE: The LibC SDK includes the necessary WinSock2 support. It | |
123 | It is not necessary to download the WinSock2 Developer when building | |
124 | for LibC. | |
125 | ||
126 | ||
127 | BUILDING: | |
128 | --------- | |
129 | Before building, you will need to set a few environment variables. You can | |
130 | set them manually or you can modify the "netware\set_env.bat" file. | |
131 | ||
132 | The set_env.bat file is a template you can use to set up the path | |
133 | and environment variables you will need to build. Modify the | |
134 | various lines to point to YOUR tools and run set_env.bat. | |
135 | ||
47c1735a RL |
136 | netware\set_env.bat [target] |
137 | ||
4d8743f4 RL |
138 | target - "netware-clib" - CLib NetWare build |
139 | - "netware-libc" - LibC NetWare build | |
140 | ||
141 | If you don't use set_env.bat, you will need to set up the following | |
142 | environment variables: | |
143 | ||
144 | path - Set path to point to the tools you will use. | |
145 | ||
146 | MWCIncludes - The location of the NDK include files. | |
147 | ||
47c1735a RL |
148 | CLIB ex: set MWCIncludes=c:\ndk\nwsdk\include\nlm |
149 | LibC ex: set MWCIncludes=c:\ndk\libc\include | |
4d8743f4 RL |
150 | |
151 | PRELUDE - The absolute path of the prelude object to link with. For | |
47c1735a RL |
152 | a CLIB build it is recommended you use the "clibpre.o" files shipped |
153 | with the Metrowerks PDK for NetWare. For a LibC build you should | |
154 | use the "libcpre.o" file delivered with the LibC NDK components. | |
155 | ||
156 | CLIB ex: set PRELUDE=c:\ndk\nwsdk\imports\clibpre.o | |
157 | LibC ex: set PRELUDE=c:\ndk\libc\imports\libcpre.o | |
4d8743f4 RL |
158 | |
159 | IMPORTS - The locaton of the NDK import files. | |
47c1735a RL |
160 | |
161 | CLIB ex: set IMPORTS=c:\ndk\nwsdk\imports | |
162 | LibC ex: set IMPORTS=c:\ndk\libc\imports | |
4d8743f4 RL |
163 | |
164 | ||
165 | In order to build, you need to run the Perl scripts to configure the build | |
166 | process and generate a make file. There is a batch file, | |
167 | "netware\build.bat", to automate the process. | |
168 | ||
169 | Build.bat runs the build configuration scripts and generates a make file. | |
170 | If an assembly option is specified, it also runs the scripts to generate | |
171 | the assembly code. Always run build.bat from the "openssl" directory. | |
172 | ||
173 | netware\build [target] [debug opts] [assembly opts] [configure opts] | |
47c1735a | 174 | |
4d8743f4 RL |
175 | target - "netware-clib" - CLib NetWare build |
176 | - "netware-libc" - LibC NetWare build | |
177 | ||
178 | debug opts - "debug" - build debug | |
179 | ||
180 | assembly opts - "nw-mwasm" - use Metrowerks assembler | |
181 | "nw-nasm" - use NASM assembler | |
182 | "no-asm" - don't use assembly | |
183 | ||
184 | configure opts- all unrecognized arguments are passed to the | |
47c1735a | 185 | perl configure script |
4d8743f4 RL |
186 | |
187 | examples: | |
47c1735a RL |
188 | |
189 | CLIB build, debug, without assembly: | |
190 | netware\build.bat netware-clib debug no-asm | |
191 | ||
192 | LibC build, non-debug, using NASM assembly: | |
193 | netware\build.bat netware-libc nw-nasm | |
194 | ||
4d8743f4 RL |
195 | Running build.bat generates a make file to be processed by your make |
196 | tool (gmake or nmake): | |
197 | ||
198 | CLIB ex: gmake -f netware\nlm_clib.mak | |
199 | LibC ex: gmake -f netware\nlm_libc.mak | |
200 | ||
201 | ||
202 | You can also run the build scripts manually if you do not want to use the | |
203 | build.bat file. Run the following scripts in the "\openssl" | |
204 | subdirectory (in the order listed below): | |
205 | ||
206 | perl configure no-asm [other config opts] [netware-clib|netware-libc] | |
207 | configures no assembly build for specified netware environment | |
47c1735a | 208 | (CLIB or LibC). |
4d8743f4 RL |
209 | |
210 | perl util\mkfiles.pl >MINFO | |
211 | generates a listing of source files (used by mk1mf) | |
212 | ||
213 | perl util\mk1mf.pl no-asm [other config opts] [netware-clib|netware-libc >netware\nlm.mak | |
214 | generates the makefile for NetWare | |
215 | ||
216 | gmake -f netware\nlm.mak | |
217 | build with the make tool (nmake.exe also works) | |
218 | ||
219 | NOTE: If you are building using the assembly option, you must also run the | |
220 | various Perl scripts to generate the assembly files. See build.bat | |
221 | for an example of running the various assembly scripts. You must use the | |
222 | "no-asm" option to build without assembly. The configure and mk1mf scripts | |
223 | also have various other options. See the scripts for more information. | |
224 | ||
225 | ||
226 | The output from the build is placed in the following directories: | |
227 | ||
228 | CLIB Debug build: | |
229 | out_nw_clib.dbg - static libs & test nlm(s) | |
230 | tmp_nw_clib.dbg - temporary build files | |
231 | outinc_nw_clib - necessary include files | |
232 | ||
233 | CLIB Non-debug build: | |
234 | out_nw_clib - static libs & test nlm(s) | |
235 | tmp_nw_clib - temporary build files | |
236 | outinc_nw_clib - necesary include files | |
237 | ||
238 | LibC Debug build: | |
239 | out_nw_libc.dbg - static libs & test nlm(s) | |
240 | tmp_nw_libc.dbg - temporary build files | |
241 | outinc_nw_libc - necessary include files | |
242 | ||
243 | LibC Non-debug build: | |
244 | out_nw_libc - static libs & test nlm(s) | |
245 | tmp_nw_libc - temporary build files | |
246 | outinc_nw_libc - necesary include files | |
247 | ||
248 | ||
249 | TESTING: | |
250 | -------- | |
251 | The build process creates the OpenSSL static libs ( crypto.lib, ssl.lib, | |
252 | rsaglue.lib ) and several test programs. You should copy the test programs | |
253 | to your NetWare server and run the tests. | |
254 | ||
255 | The batch file "netware\cpy_tests.bat" will copy all the necessary files | |
256 | to your server for testing. In order to run the batch file, you need a | |
257 | drive mapped to your target server. It will create an "OpenSSL" directory | |
258 | on the drive and copy the test files to it. CAUTION: If a directory with the | |
259 | name of "OpenSSL" already exists, it will be deleted. | |
260 | ||
261 | To run cpy_tests.bat: | |
262 | ||
263 | netware\cpy_tests [output directory] [NetWare drive] | |
264 | ||
265 | output directory - "out_nw_clib.dbg", "out_nw_libc", etc. | |
266 | NetWare drive - drive letter of mapped drive | |
267 | ||
268 | CLIB ex: netware\cpy_tests out_nw_clib m: | |
269 | LibC ex: netware\cpy_tests out_nw_libc m: | |
270 | ||
271 | ||
272 | The Perl script, "do_tests.pl", in the "OpenSSL" directory on the server | |
273 | should be used to execute the tests. Before running the script, make sure | |
274 | your SEARCH PATH includes the "OpenSSL" directory. For example, if you | |
275 | copied the files to the "sys:" volume you use the command: | |
276 | ||
277 | SEARCH ADD SYS:\OPENSSL | |
278 | ||
279 | ||
280 | To run do_tests.pl type (at the console prompt): | |
281 | ||
282 | perl \openssl\do_tests.pl [options] | |
283 | ||
284 | options: | |
285 | -p - pause after executing each test | |
286 | ||
287 | The do_tests.pl script generates a log file "\openssl\test_out\tests.log" | |
288 | which should be reviewed for errors. Any errors will be denoted by the word | |
289 | "ERROR" in the log. | |
290 | ||
291 | NOTE: Currently (11/2002), the LibC test nlms report an error while loading | |
292 | when launched from the perl script (do_tests.pl). The problems are | |
293 | being addressed by the LibC development team and should be fixed in the | |
294 | next release. Until the problems are corrected, the LibC test nlms | |
295 | will have to be executed manually. | |
296 | ||
297 | ||
298 | DEVELOPING WITH THE OPENSSL SDK: | |
299 | -------------------------------- | |
300 | Now that everything is built and tested, you are ready to use the OpenSSL | |
301 | libraries in your development. | |
302 | ||
303 | There is no real installation procedure, just copy the static libs and | |
304 | headers to your build location. The libs (crypto.lib & ssl.lib) are | |
305 | located in the appropriate "out_nw_XXXX" directory | |
306 | (out_nw_clib, out_nw_libc, etc). | |
307 | ||
308 | The headers are located in the appropriate "outinc_nw_XXX" directory | |
309 | (outinc_nw_clib, outinc_nw_libc). | |
310 | ||
311 | One suggestion is to create the following directory | |
312 | structure for the OpenSSL SDK: | |
313 | ||
314 | \openssl | |
315 | |- bin | |
316 | | |- openssl.nlm | |
317 | | |- (other tests you want) | |
318 | | | |
319 | |- lib | |
320 | | | - crypto.lib | |
321 | | | - ssl.lib | |
322 | | | |
323 | |- include | |
324 | | | - openssl | |
325 | | | | - (all the headers in "outinc_nw\openssl") | |
326 | ||
327 | ||
328 | The program "openssl.nlm" can be very useful. It has dozens of | |
329 | options and you may want to keep it handy for debugging, testing, etc. | |
330 | ||
331 | When building your apps using OpenSSL, define "NETWARE". It is needed by | |
332 | some of the OpenSSL headers. One way to do this is with a compile option, | |
333 | for example "-DNETWARE". | |
334 | ||
335 | ||
336 | ||
337 | NOTES: | |
338 | ------ | |
339 | ||
340 | Resource leaks in Tests | |
341 | ------------------------ | |
342 | Some OpenSSL tests do not clean up resources and NetWare reports | |
343 | the resource leaks when the tests unload. If this really bugs you, | |
344 | you can stop the messages by setting the developer option off at the console | |
345 | prompt (set developer option = off). Or better yet, fix the tests to | |
346 | clean up the resources! | |
347 | ||
348 | ||
349 | Multi-threaded Development | |
350 | --------------------------- | |
351 | The NetWare version of OpenSSL is thread-safe however, multi-threaded | |
352 | applications must provide the necessary locking function callbacks. This | |
353 | is described in doc\threads.doc. The file "openssl\crypto\threads\mttest.c" | |
354 | is a multi-threaded test program and demonstrates the locking functions. | |
355 | ||
356 | ||
357 | What is openssl2.nlm? | |
358 | --------------------- | |
359 | The openssl program has numerous options and can be used for many different | |
360 | things. Many of the options operate in an interactive mode requiring the | |
361 | user to enter data. Because of this, a default screen is created for the | |
362 | program. However, when running the test script it is not desirable to | |
363 | have a seperate screen. Therefore, the build also creates openssl2.nlm. | |
364 | Openssl2.nlm is functionally identical but uses the console screen. | |
365 | Openssl2 can be used when a non-interactive mode is desired. | |
366 | ||
367 | NOTE: There are may other possibilities (command line options, etc) | |
368 | which could have been used to address the screen issue. The openssl2.nlm | |
369 | option was chosen because it impacted only the build not the code. | |
370 | ||
371 | ||
372 | Why only static libraries? | |
373 | -------------------------- | |
374 | Globals, globals, and more globals. The OpenSSL code uses many global | |
375 | variables that are allocated and initialized when used for the first time. | |
376 | ||
377 | On NetWare, most applications (at least historically) run in the kernel. | |
378 | When running in the kernel, there is one instance of global variables. | |
379 | For regular application type NLM(s) this isn't a problem because they are | |
380 | the only ones using the globals. However, for a library NLM (an NLM which | |
381 | exposes functions and has no threads of execution), the globals cause | |
382 | problems. Applications could inadvertently step on each other if they | |
383 | change some globals. Even worse, the first application that triggers a | |
384 | global to be allocated and initialized has the allocated memory charged to | |
385 | itself. Now when that application unloads, NetWare will clean up all the | |
386 | applicaton's memory. The global pointer variables inside OpenSSL now | |
387 | point to freed memory. An abend waiting to happen! | |
388 | ||
389 | To work correctly in the kernel, library NLM(s) that use globals need to | |
390 | provide a set of globals (instance data) for each application. Another | |
391 | option is to require the library only be loaded in a protected address | |
392 | space along with the application using it. | |
393 | ||
394 | Modifying the OpenSSL code to provide a set of globals (instance data) for | |
395 | each application isn't technically difficult, but due to the large number | |
396 | globals it would require substantial code changes and it wasn't done. Hence, | |
397 | the build currently only builds static libraries which are then linked | |
398 | into each application. | |
399 | ||
400 | NOTE: If you are building a library NLM that uses the OpenSSL static | |
401 | libraries, you will still have to deal with the global variable issue. | |
402 | This is because when you link in the OpenSSL code you bring in all the | |
403 | globals. One possible solution for the global pointer variables is to | |
404 | register memory functions with OpenSSL which allocate memory and charge it | |
405 | to your library NLM (see the function CRYPTO_set_mem_functions). However, | |
406 | be aware that now all memory allocated by OpenSSL is charged to your NLM. | |
407 | ||
408 | ||
409 | CodeWarrior Tools and W2K | |
410 | --------------------------- | |
411 | There have been problems reported with the CodeWarrior Linker | |
412 | (mwldnlm.exe) in the PDK 2.1 for NetWare when running on Windows 2000. The | |
413 | problems cause the link step to fail. The only work around is to obtain an | |
414 | updated linker from Metrowerks. It is expected Metrowerks will release | |
415 | PDK 3.0 (in beta testing at this time - May, 2001) in the near future which | |
416 | will fix these problems. | |
417 | ||
418 | ||
419 | Makefile "vclean" | |
420 | ------------------ | |
421 | The generated makefile has a "vclean" target which cleans up the build | |
422 | directories. If you have been building successfully and suddenly | |
423 | experience problems, use "vclean" (gmake -f netware\nlm.mak vclean) and retry. | |
424 | ||
425 | ||
426 | "Undefined Symbol" Linker errors | |
427 | -------------------------------- | |
428 | There have been linker errors reported when doing a CLIB build. The problems | |
429 | occur because some versions of the CLIB SDK import files inadvertently | |
430 | left out some symbols. One symbol in particular is "_lrotl". The missing | |
431 | functions are actually delivered in the binaries, but they were left out of | |
432 | the import files. The issues should be fixed in the September 2001 release | |
433 | of the NDK. If you experience the problems you can temporarily | |
434 | work around it by manually adding the missing symbols to your version of | |
47c1735a RL |
435 | "clib.imp". |
436 |