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: 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: 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 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/ 108: 109: 110: NLM and NetWare libraries for C (including CLIB and XPlat): 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. 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 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. 130: 131: NOTE: The LibC SDK includes the necessary WinSock2 support. It 132: It is not necessary to download the WinSock2 Developer when building 133: for LibC. The LibC SDK also includes the appropriate BSD socket support 134: if configuring to use BSD sockets. 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: 146: netware\set_env.bat [target] 147: 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: 158: CLIB ex: set MWCIncludes=c:\ndk\nwsdk\include\nlm 159: LibC ex: set MWCIncludes=c:\ndk\libc\include 160: 161: PRELUDE - The absolute path of the prelude object to link with. For 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 168: 169: IMPORTS - The locaton of the NDK import files. 170: 171: CLIB ex: set IMPORTS=c:\ndk\nwsdk\imports 172: LibC ex: set IMPORTS=c:\ndk\libc\imports 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] 184: 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) 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 196: perl configure script 197: 198: examples: 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: 206: LibC build, BSD sockets, non-debug, without assembly: 207: netware\build.bat netware-libc-bsdsock no-asm 208: 209: Running build.bat generates a make file to be processed by your make 210: tool (gmake or nmake): 211: 212: CLIB ex: gmake -f netware\nlm_clib_dbg.mak 213: LibC ex: gmake -f netware\nlm_libc.mak 214: LibC ex: gmake -f netware\nlm_libc_bsdsock.mak 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: 221: perl configure no-asm [other config opts] [netware-clib|netware-libc|netware-libc-bsdsock] 222: configures no assembly build for specified netware environment 223: (CLIB or LibC). 224: 225: perl util\mkfiles.pl >MINFO 226: generates a listing of source files (used by mk1mf) 227: 228: perl util\mk1mf.pl no-asm [other config opts] [netware-clib|netware-libc|netware-libc-bsdsock >netware\nlm.mak 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: 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 443: "clib.imp". 444: