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