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