INSTALL.NW

   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):
 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.
 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
 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.
 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
 136         netware\set_env.bat [target]
 137
 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
 148                         CLIB ex: set MWCIncludes=c:\ndk\nwsdk\include\nlm
 149                         LibC ex: set MWCIncludes=c:\ndk\libc\include
 150
 151    PRELUDE - The absolute path of the prelude object to link with.  For
 152                         a CLIB build it is recommended you use the "nwpre.obj" file 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:\codewar\novell support\metrowerks support\
 157                                libraries\runtime\nwpre.obj
 158
 159                         LibC ex: set PRELUDE=c:\ndk\libc\imports\libcpre.o
 160
 161    IMPORTS - The locaton of the NDK import files.
 162
 163                         CLIB ex: set IMPORTS=c:\ndk\nwsdk\imports
 164                         LibC ex: set IMPORTS=c:\ndk\libc\imports
 165
 166
 167 In order to build, you need to run the Perl scripts to configure the build
 168 process and generate a make file.  There is a batch file,
 169 "netware\build.bat", to automate the process.
 170
 171 Build.bat runs the build configuration scripts and generates a make file.
 172 If an assembly option is specified, it also runs the scripts to generate
 173 the assembly code.  Always run build.bat from the "openssl" directory.
 174
 175    netware\build [target] [debug opts] [assembly opts] [configure opts]
 176
 177       target        - "netware-clib" - CLib NetWare build
 178                     - "netware-libc" - LibC NetWare build
 179
 180       debug opts    - "debug"  - build debug
 181
 182       assembly opts - "nw-mwasm" - use Metrowerks assembler
 183                       "nw-nasm"  - use NASM assembler
 184                       "no-asm"   - don't use assembly
 185
 186       configure opts- all unrecognized arguments are passed to the
 187                        perl configure script
 188
 189    examples:
 190
 191                 CLIB build, debug, without assembly:
 192                         netware\build.bat netware-clib debug no-asm
 193
 194                 LibC build, non-debug, using NASM assembly:
 195                         netware\build.bat netware-libc nw-nasm
 196
 197 Running build.bat generates a make file to be processed by your make
 198 tool (gmake or nmake):
 199
 200    CLIB ex: gmake -f netware\nlm_clib.mak
 201    LibC ex: gmake -f netware\nlm_libc.mak
 202
 203
 204 You can also run the build scripts manually if you do not want to use the
 205 build.bat file.  Run the following scripts in the "\openssl"
 206 subdirectory (in the order listed below):
 207
 208    perl configure no-asm [other config opts] [netware-clib|netware-libc]
 209       configures no assembly build for specified netware environment
 210                 (CLIB or LibC).
 211
 212    perl util\mkfiles.pl >MINFO
 213       generates a listing of source files (used by mk1mf)
 214
 215    perl util\mk1mf.pl no-asm [other config opts] [netware-clib|netware-libc >netware\nlm.mak
 216       generates the makefile for NetWare
 217
 218    gmake -f netware\nlm.mak
 219       build with the make tool (nmake.exe also works)
 220
 221 NOTE:  If you are building using the assembly option, you must also run the
 222 various Perl scripts to generate the assembly files.  See build.bat
 223 for an example of running the various assembly scripts.  You must use the
 224 "no-asm" option to build without assembly.  The configure and mk1mf scripts
 225 also have various other options.  See the scripts for more information.
 226
 227
 228 The output from the build is placed in the following directories:
 229
 230    CLIB Debug build:
 231       out_nw_clib.dbg     - static libs & test nlm(s)
 232       tmp_nw_clib.dbg     - temporary build files
 233       outinc_nw_clib      - necessary include files
 234
 235    CLIB Non-debug build:
 236       out_nw_clib         - static libs & test nlm(s)
 237       tmp_nw_clib         - temporary build files
 238       outinc_nw_clib      - necesary include files
 239
 240    LibC Debug build:
 241       out_nw_libc.dbg     - static libs & test nlm(s)
 242       tmp_nw_libc.dbg     - temporary build files
 243       outinc_nw_libc      - necessary include files
 244
 245    LibC Non-debug build:
 246       out_nw_libc         - static libs & test nlm(s)
 247       tmp_nw_libc         - temporary build files
 248       outinc_nw_libc      - necesary include files
 249
 250
 251 TESTING:
 252 --------
 253 The build process creates the OpenSSL static libs ( crypto.lib, ssl.lib,
 254 rsaglue.lib ) and several test programs.  You should copy the test programs
 255 to your NetWare server and run the tests.
 256
 257 The batch file "netware\cpy_tests.bat" will copy all the necessary files
 258 to your server for testing.  In order to run the batch file, you need a
 259 drive mapped to your target server.  It will create an "OpenSSL" directory
 260 on the drive and copy the test files to it.  CAUTION: If a directory with the
 261 name of "OpenSSL" already exists, it will be deleted.
 262
 263 To run cpy_tests.bat:
 264
 265    netware\cpy_tests [output directory] [NetWare drive]
 266
 267       output directory - "out_nw_clib.dbg", "out_nw_libc", etc.
 268       NetWare drive    - drive letter of mapped drive
 269
 270       CLIB ex: netware\cpy_tests out_nw_clib m:
 271       LibC ex: netware\cpy_tests out_nw_libc m:
 272
 273
 274 The Perl script, "do_tests.pl", in the "OpenSSL" directory on the server
 275 should be used to execute the tests.  Before running the script, make sure
 276 your SEARCH PATH includes the "OpenSSL" directory.  For example, if you
 277 copied the files to the "sys:" volume you use the command:
 278
 279    SEARCH ADD SYS:\OPENSSL
 280
 281
 282 To run do_tests.pl type (at the console prompt):
 283
 284    perl \openssl\do_tests.pl [options]
 285
 286       options:
 287          -p    - pause after executing each test
 288
 289 The do_tests.pl script generates a log file "\openssl\test_out\tests.log"
 290 which should be reviewed for errors.  Any errors will be denoted by the word
 291 "ERROR" in the log.
 292
 293 NOTE:  Currently (11/2002), the LibC test nlms report an error while loading
 294        when launched from the perl script (do_tests.pl).  The problems are
 295        being addressed by the LibC development team and should be fixed in the
 296        next release.  Until the problems are corrected, the LibC test nlms
 297        will have to be executed manually.
 298
 299
 300 DEVELOPING WITH THE OPENSSL SDK:
 301 --------------------------------
 302 Now that everything is built and tested, you are ready to use the OpenSSL
 303 libraries in your development.
 304
 305 There is no real installation procedure, just copy the static libs and
 306 headers to your build location.  The libs (crypto.lib & ssl.lib) are
 307 located in the appropriate "out_nw_XXXX" directory
 308 (out_nw_clib, out_nw_libc, etc).
 309
 310 The headers are located in the appropriate "outinc_nw_XXX" directory
 311 (outinc_nw_clib, outinc_nw_libc).
 312
 313 One suggestion is to create the following directory
 314 structure for the OpenSSL SDK:
 315
 316    \openssl
 317       |- bin
 318       |   |- openssl.nlm
 319       |   |- (other tests you want)
 320       |
 321       |- lib
 322       |   | - crypto.lib
 323       |   | - ssl.lib
 324       |
 325       |- include
 326       |   | - openssl
 327       |   |    | - (all the headers in "outinc_nw\openssl")
 328
 329
 330 The program "openssl.nlm" can be very useful.  It has dozens of
 331 options and you may want to keep it handy for debugging, testing, etc.
 332
 333 When building your apps using OpenSSL, define "NETWARE".  It is needed by
 334 some of the OpenSSL headers.  One way to do this is with a compile option,
 335 for example "-DNETWARE".
 336
 337
 338
 339 NOTES:
 340 ------
 341
 342 Resource leaks in Tests
 343 ------------------------
 344 Some OpenSSL tests do not clean up resources and NetWare reports
 345 the resource leaks when the tests unload.  If this really bugs you,
 346 you can stop the messages by setting the developer option off at the console
 347 prompt (set developer option = off).  Or better yet, fix the tests to
 348 clean up the resources!
 349
 350
 351 Multi-threaded Development
 352 ---------------------------
 353 The NetWare version of OpenSSL is thread-safe however, multi-threaded
 354 applications must provide the necessary locking function callbacks.  This
 355 is described in doc\threads.doc.  The file "openssl\crypto\threads\mttest.c"
 356 is a multi-threaded test program and demonstrates the locking functions.
 357
 358
 359 What is openssl2.nlm?
 360 ---------------------
 361 The openssl program has numerous options and can be used for many different
 362 things.  Many of the options operate in an interactive mode requiring the
 363 user to enter data.  Because of this, a default screen is created for the
 364 program.  However, when running the test script it is not desirable to
 365 have a seperate screen.  Therefore, the build also creates openssl2.nlm.
 366 Openssl2.nlm is functionally identical but uses the console screen.
 367 Openssl2 can be used when a non-interactive mode is desired.
 368
 369 NOTE:  There are may other possibilities (command line options, etc)
 370 which could have been used to address the screen issue.  The openssl2.nlm
 371 option was chosen because it impacted only the build not the code.
 372
 373
 374 Why only static libraries?
 375 --------------------------
 376 Globals, globals, and more globals.  The OpenSSL code uses many global
 377 variables that are allocated and initialized when used for the first time.
 378
 379 On NetWare, most applications (at least historically) run in the kernel.
 380 When running in the kernel, there is one instance of global variables.
 381 For regular application type NLM(s) this isn't a problem because they are
 382 the only ones using the globals.  However, for a library NLM (an NLM which
 383 exposes functions and has no threads of execution), the globals cause
 384 problems.  Applications could inadvertently step on each other if they
 385 change some globals.  Even worse, the first application that triggers a
 386 global to be allocated and initialized has the allocated memory charged to
 387 itself.  Now when that application unloads, NetWare will clean up all the
 388 applicaton's memory.  The global pointer variables inside OpenSSL now
 389 point to freed memory.  An abend waiting to happen!
 390
 391 To work correctly in the kernel, library NLM(s) that use globals need to
 392 provide a set of globals (instance data) for each application.  Another
 393 option is to require the library only be loaded in a protected address
 394 space along with the application using it.
 395
 396 Modifying the OpenSSL code to provide a set of globals (instance data) for
 397 each application isn't technically difficult, but due to the large number
 398 globals it would require substantial code changes and it wasn't done.  Hence,
 399 the build currently only builds static libraries which are then linked
 400 into each application.
 401
 402 NOTE:  If you are building a library NLM that uses the OpenSSL static
 403 libraries, you will still have to deal with the global variable issue.
 404 This is because when you link in the OpenSSL code you bring in all the
 405 globals.  One possible solution for the global pointer variables is to
 406 register memory functions with OpenSSL which allocate memory and charge it
 407 to your library NLM (see the function CRYPTO_set_mem_functions).  However,
 408 be aware that now all memory allocated by OpenSSL is charged to your NLM.
 409
 410
 411 CodeWarrior Tools and W2K
 412 ---------------------------
 413 There have been problems reported with the CodeWarrior Linker
 414 (mwldnlm.exe) in the PDK 2.1 for NetWare when running on Windows 2000.  The
 415 problems cause the link step to fail.  The only work around is to obtain an
 416 updated linker from Metrowerks.  It is expected Metrowerks will release
 417 PDK 3.0 (in beta testing at this time - May, 2001) in the near future which
 418 will fix these problems.
 419
 420
 421 Makefile "vclean"
 422 ------------------
 423 The generated makefile has a "vclean" target which cleans up the build
 424 directories.  If you have been building successfully and suddenly
 425 experience problems, use "vclean" (gmake -f netware\nlm.mak vclean) and retry.
 426
 427
 428 "Undefined Symbol" Linker errors
 429 --------------------------------
 430 There have been linker errors reported when doing a CLIB build.  The problems
 431 occur because some versions of the CLIB SDK import files inadvertently
 432 left out some symbols.  One symbol in particular is "_lrotl".  The missing
 433 functions are actually delivered in the binaries, but they were left out of
 434 the import files.  The issues should be fixed in the September 2001 release
 435 of the NDK.  If you experience the problems you can temporarily
 436 work around it by manually adding the missing symbols to your version of
 437 "clib.imp".