Netware-specific changes,

PR: 780
Submitted by: Verdon Walker <VWalker@novell.com>
Reviewed by: Richard Levitte

1 files changed, 437 insertions, 0 deletions

diff --git a/INSTALL.NW b/INSTALL.NW
new file mode 100644
index 0000000000..22718f774b
--- /dev/null
+++ b/INSTALL.NW
@@ -0,0 +1,437 @@
+
+INSTALLATION ON THE NETWARE PLATFORM
+------------------------------------
+
+Notes about building OpenSSL for NetWare.
+
+
+BUILD PLATFORM:
+---------------
+The build scripts (batch files, perl scripts, etc) have been developed and
+tested on W2K.  The scripts should run fine on other Windows
+platforms (NT, Win9x, WinXP) but they haven't been tested.  They may require 
+some modifications.
+
+
+Supported NetWare Platforms - NetWare 5.x, NetWare 6.x:
+------------------------------------------
+OpenSSL uses the WinSock interfaces introduced in NetWare 5.  Therefore,
+previous versions of NetWare, 4.x and 3.x, are not supported.
+
+On NetWare there are two c-runtime libraries.  There is the legacy CLIB 
+interfaces and the newer LibC interfaces.  Being ANSI-C libraries, the 
+functionality in CLIB and LibC is similar but the LibC interfaces are built 
+using Novell Kernal Services (NKS) which is designed to leverage 
+multi-processor environments.
+
+The NetWare port of OpenSSL can configured to build using CLIB or LibC.  The 
+CLIB build was developed and tested using NetWare 5.0 sp6.0a.  The LibC 
+build was developed and tested using the NetWare 6.0 FCS.  
+
+The necessary LibC functionality ships with NetWare 6.  However, earlier 
+NetWare 5.x versions will require updates in order to run the OpenSSL LibC
+build.
+
+
+REQUIRED TOOLS:
+---------------
+Based upon the configuration and build options used, some or all of the
+following tools may be required:
+
+
+* Perl for Win32 - required (http://www.activestate.com/ActivePerl)
+   Used to run the various perl scripts on the build platform.
+
+
+* Perl 5.8.0 for NetWare v3.20 (or later) - required 
+   (http://developer.novell.com) Used to run the test script on NetWare 
+   after building.
+
+
+* Metrowerks CodeWarrior PDK 2.1 (or later) for NetWare - required:
+   Provides command line tools used for building.
+
+   Tools:
+   mwccnlm.exe  - C/C++ Compiler for NetWare
+   mwldnlm.exe  - Linker for NetWare
+   mwasmnlm.exe - x86 assembler for NetWare (if using assembly option)
+
+
+* Assemblers - optional:
+   If you intend to build using the assembly options you will need an
+   assembler.  Work has been completed to support two assemblers, Metrowerks
+   and NASM.  However, during development, a bug was found in the Metrowerks
+   assembler which generates incorrect code.  Until this problem is fixed,
+   the Metrowerks assembler cannot be used.
+
+   mwasmnlm.exe - Metrowerks x86 assembler - part of CodeWarrior tools.
+         (version 2.2 Built Aug 23, 1999 - not useable due to code
+          generation bug)
+
+   nasmw.exe - Netwide Assembler NASM
+         version 0.98 was used in development and testing
+
+* Make Tool - required:
+   In order to build you will need a make tool.  Two make tools are
+   supported, GNU make (gmake.exe) or Microsoft nmake.exe.
+
+   gmake.exe - GNU make for Windows (version 3.75 used for development)
+         http://www.gnu.org/software/make/make.html
+
+   nmake.exe - Microsoft make (Version 6.00.8168.0 used for development)
+
+
+* Novell Developer Kit (NDK) - required: (http://developer.novell.com)
+
+   CLIB - BUILDS:
+
+      WinSock2 Developer Components for NetWare:
+         For initial development, the October 27, 2000 version was used.
+         However, future versions should also work.
+
+         NOTE:  The WinSock2 components include headers & import files for
+         NetWare, but you will also need the winsock2.h and supporting
+         headers (pshpack4.h, poppack.h, qos.h) delivered in the
+         Microsoft SDK.  Note: The winsock2.h support headers may change
+         with various versions of winsock2.h.  Check the dependencies
+         section on the NDK WinSock2 download page for the latest
+         information on dependencies.
+
+
+      NLM and NetWare libraries for C (including CLIB and XPlat):
+			If you are going to build a CLIB version of OpenSSL, you will
+			need the CLIB headers and imports.  The March, 2001 NDK release or 
+			later is recommended.
+
+         Earlier versions should work but haven't been tested.  In recent
+         versions the import files have been consolidated and function
+         names moved.  This means you may run into link problems
+         (undefined symbols) when using earlier versions.   The functions
+         are available in earlier versions, but you will have to modifiy
+         the make files to include additional import files (see
+         openssl\util\pl\netware.pl).
+
+
+   LIBC - BUILDS:
+   
+      Libraries for C (LibC) - LibC headers and import files
+			If you are going to build a LibC version of OpenSSL, you will
+			need the LibC headers and imports.  The March 14, 2002 NDK release or
+			later is required.  
+         
+         NOTE: The LibC SDK includes the necessary WinSock2 support.  It
+         It is not necessary to download the WinSock2 Developer when building
+         for LibC.
+
+
+BUILDING:
+---------
+Before building, you will need to set a few environment variables.  You can
+set them manually or you can modify the "netware\set_env.bat" file.
+
+The set_env.bat file is a template you can use to set up the path
+and environment variables you will need to build.  Modify the
+various lines to point to YOUR tools and run set_env.bat.
+
+	netware\set_env.bat [target]
+	
+      target        - "netware-clib" - CLib NetWare build
+                    - "netware-libc" - LibC NetWare build
+
+If you don't use set_env.bat, you will need to set up the following
+environment variables:
+
+   path - Set path to point to the tools you will use.
+
+   MWCIncludes - The location of the NDK include files.
+         
+			CLIB ex: set MWCIncludes=c:\ndk\nwsdk\include\nlm
+			LibC ex: set MWCIncludes=c:\ndk\libc\include
+
+   PRELUDE - The absolute path of the prelude object to link with.  For
+			a CLIB build it is recommended you use the "nwpre.obj" file shipped
+			with the Metrowerks PDK for NetWare.  For a LibC build you should 
+			use the "libcpre.o" file delivered with the LibC NDK components.
+         
+			CLIB ex: set PRELUDE=c:\codewar\novell support\metrowerks support\
+                               libraries\runtime\nwpre.obj
+										 
+			LibC ex: set PRELUDE=c:\ndk\libc\imports\libcpre.o
+
+   IMPORTS - The locaton of the NDK import files.
+         
+			CLIB ex: set IMPORTS=c:\ndk\nwsdk\imports
+			LibC ex: set IMPORTS=c:\ndk\libc\imports
+
+
+In order to build, you need to run the Perl scripts to configure the build
+process and generate a make file.  There is a batch file,
+"netware\build.bat", to automate the process.
+
+Build.bat runs the build configuration scripts and generates a make file.
+If an assembly option is specified, it also runs the scripts to generate 
+the assembly code.  Always run build.bat from the "openssl" directory.
+
+   netware\build [target] [debug opts] [assembly opts] [configure opts]
+	
+      target        - "netware-clib" - CLib NetWare build
+                    - "netware-libc" - LibC NetWare build
+ 
+      debug opts    - "debug"  - build debug
+
+      assembly opts - "nw-mwasm" - use Metrowerks assembler
+                      "nw-nasm"  - use NASM assembler
+                      "no-asm"   - don't use assembly
+
+      configure opts- all unrecognized arguments are passed to the
+                       perl configure script
+
+   examples:
+	
+		CLIB build, debug, without assembly:
+			netware\build.bat netware-clib debug no-asm
+		
+		LibC build, non-debug, using NASM assembly:
+			netware\build.bat netware-libc nw-nasm
+		
+Running build.bat generates a make file to be processed by your make 
+tool (gmake or nmake):
+
+   CLIB ex: gmake -f netware\nlm_clib.mak 
+   LibC ex: gmake -f netware\nlm_libc.mak 
+
+
+You can also run the build scripts manually if you do not want to use the
+build.bat file.  Run the following scripts in the "\openssl"
+subdirectory (in the order listed below):
+
+   perl configure no-asm [other config opts] [netware-clib|netware-libc]
+      configures no assembly build for specified netware environment
+		(CLIB or LibC).
+
+   perl util\mkfiles.pl >MINFO
+      generates a listing of source files (used by mk1mf)
+
+   perl util\mk1mf.pl no-asm [other config opts] [netware-clib|netware-libc >netware\nlm.mak
+      generates the makefile for NetWare
+
+   gmake -f netware\nlm.mak
+      build with the make tool (nmake.exe also works)
+
+NOTE:  If you are building using the assembly option, you must also run the
+various Perl scripts to generate the assembly files.  See build.bat
+for an example of running the various assembly scripts.  You must use the
+"no-asm" option to build without assembly.  The configure and mk1mf scripts
+also have various other options.  See the scripts for more information.
+
+
+The output from the build is placed in the following directories:
+
+   CLIB Debug build:
+      out_nw_clib.dbg     - static libs & test nlm(s)
+      tmp_nw_clib.dbg     - temporary build files
+      outinc_nw_clib      - necessary include files
+
+   CLIB Non-debug build:
+      out_nw_clib         - static libs & test nlm(s)
+      tmp_nw_clib         - temporary build files
+      outinc_nw_clib      - necesary include files
+
+   LibC Debug build:
+      out_nw_libc.dbg     - static libs & test nlm(s)
+      tmp_nw_libc.dbg     - temporary build files
+      outinc_nw_libc      - necessary include files
+
+   LibC Non-debug build:
+      out_nw_libc         - static libs & test nlm(s)
+      tmp_nw_libc         - temporary build files
+      outinc_nw_libc      - necesary include files
+
+
+TESTING:
+--------
+The build process creates the OpenSSL static libs ( crypto.lib, ssl.lib,
+rsaglue.lib ) and several test programs.  You should copy the test programs
+to your NetWare server and run the tests.
+
+The batch file "netware\cpy_tests.bat" will copy all the necessary files
+to your server for testing.  In order to run the batch file, you need a
+drive mapped to your target server.  It will create an "OpenSSL" directory
+on the drive and copy the test files to it.  CAUTION: If a directory with the
+name of "OpenSSL" already exists, it will be deleted.
+
+To run cpy_tests.bat:
+
+   netware\cpy_tests [output directory] [NetWare drive]
+
+      output directory - "out_nw_clib.dbg", "out_nw_libc", etc.
+      NetWare drive    - drive letter of mapped drive
+
+      CLIB ex: netware\cpy_tests out_nw_clib m:
+      LibC ex: netware\cpy_tests out_nw_libc m:
+
+
+The Perl script, "do_tests.pl", in the "OpenSSL" directory on the server
+should be used to execute the tests.  Before running the script, make sure
+your SEARCH PATH includes the "OpenSSL" directory.  For example, if you
+copied the files to the "sys:" volume you use the command:
+
+   SEARCH ADD SYS:\OPENSSL
+
+
+To run do_tests.pl type (at the console prompt):
+
+   perl \openssl\do_tests.pl [options]
+
+      options:
+         -p    - pause after executing each test
+
+The do_tests.pl script generates a log file "\openssl\test_out\tests.log"
+which should be reviewed for errors.  Any errors will be denoted by the word
+"ERROR" in the log.
+
+NOTE:  Currently (11/2002), the LibC test nlms report an error while loading
+       when launched from the perl script (do_tests.pl).  The problems are 
+       being addressed by the LibC development team and should be fixed in the
+       next release.  Until the problems are corrected, the LibC test nlms 
+       will have to be executed manually.  
+
+
+DEVELOPING WITH THE OPENSSL SDK:
+--------------------------------
+Now that everything is built and tested, you are ready to use the OpenSSL
+libraries in your development.
+
+There is no real installation procedure, just copy the static libs and
+headers to your build location.  The libs (crypto.lib & ssl.lib) are
+located in the appropriate "out_nw_XXXX" directory 
+(out_nw_clib, out_nw_libc, etc).  
+
+The headers are located in the appropriate "outinc_nw_XXX" directory 
+(outinc_nw_clib, outinc_nw_libc).  
+
+One suggestion is to create the following directory 
+structure for the OpenSSL SDK:
+
+   \openssl
+      |- bin
+      |   |- openssl.nlm
+      |   |- (other tests you want)
+      |
+      |- lib
+      |   | - crypto.lib
+      |   | - ssl.lib
+      |
+      |- include
+      |   | - openssl
+      |   |    | - (all the headers in "outinc_nw\openssl")
+
+
+The program "openssl.nlm" can be very useful.  It has dozens of
+options and you may want to keep it handy for debugging, testing, etc.
+
+When building your apps using OpenSSL, define "NETWARE".  It is needed by
+some of the OpenSSL headers.  One way to do this is with a compile option,
+for example "-DNETWARE".
+
+
+
+NOTES:
+------
+
+Resource leaks in Tests
+------------------------
+Some OpenSSL tests do not clean up resources and NetWare reports
+the resource leaks when the tests unload.  If this really bugs you,
+you can stop the messages by setting the developer option off at the console
+prompt (set developer option = off).  Or better yet, fix the tests to
+clean up the resources!
+
+
+Multi-threaded Development
+---------------------------
+The NetWare version of OpenSSL is thread-safe however, multi-threaded
+applications must provide the necessary locking function callbacks.  This
+is described in doc\threads.doc.  The file "openssl\crypto\threads\mttest.c"
+is a multi-threaded test program and demonstrates the locking functions.
+
+
+What is openssl2.nlm?
+---------------------
+The openssl program has numerous options and can be used for many different
+things.  Many of the options operate in an interactive mode requiring the
+user to enter data.  Because of this, a default screen is created for the
+program.  However, when running the test script it is not desirable to
+have a seperate screen.  Therefore, the build also creates openssl2.nlm.
+Openssl2.nlm is functionally identical but uses the console screen.
+Openssl2 can be used when a non-interactive mode is desired.
+
+NOTE:  There are may other possibilities (command line options, etc)
+which could have been used to address the screen issue.  The openssl2.nlm
+option was chosen because it impacted only the build not the code.
+
+
+Why only static libraries?
+--------------------------
+Globals, globals, and more globals.  The OpenSSL code uses many global
+variables that are allocated and initialized when used for the first time.
+
+On NetWare, most applications (at least historically) run in the kernel.
+When running in the kernel, there is one instance of global variables.
+For regular application type NLM(s) this isn't a problem because they are
+the only ones using the globals.  However, for a library NLM (an NLM which
+exposes functions and has no threads of execution), the globals cause
+problems.  Applications could inadvertently step on each other if they
+change some globals.  Even worse, the first application that triggers a
+global to be allocated and initialized has the allocated memory charged to
+itself.  Now when that application unloads, NetWare will clean up all the
+applicaton's memory.  The global pointer variables inside OpenSSL now
+point to freed memory.  An abend waiting to happen!
+
+To work correctly in the kernel, library NLM(s) that use globals need to
+provide a set of globals (instance data) for each application.  Another
+option is to require the library only be loaded in a protected address
+space along with the application using it.
+
+Modifying the OpenSSL code to provide a set of globals (instance data) for
+each application isn't technically difficult, but due to the large number
+globals it would require substantial code changes and it wasn't done.  Hence,
+the build currently only builds static libraries which are then linked
+into each application.
+
+NOTE:  If you are building a library NLM that uses the OpenSSL static
+libraries, you will still have to deal with the global variable issue.
+This is because when you link in the OpenSSL code you bring in all the
+globals.  One possible solution for the global pointer variables is to
+register memory functions with OpenSSL which allocate memory and charge it
+to your library NLM (see the function CRYPTO_set_mem_functions).  However,
+be aware that now all memory allocated by OpenSSL is charged to your NLM.
+
+
+CodeWarrior Tools and W2K
+---------------------------
+There have been problems reported with the CodeWarrior Linker
+(mwldnlm.exe) in the PDK 2.1 for NetWare when running on Windows 2000.  The
+problems cause the link step to fail.  The only work around is to obtain an
+updated linker from Metrowerks.  It is expected Metrowerks will release
+PDK 3.0 (in beta testing at this time - May, 2001) in the near future which
+will fix these problems.
+
+
+Makefile "vclean"
+------------------
+The generated makefile has a "vclean" target which cleans up the build
+directories.  If you have been building successfully and suddenly
+experience problems, use "vclean" (gmake -f netware\nlm.mak vclean) and retry.
+
+
+"Undefined Symbol" Linker errors
+--------------------------------
+There have been linker errors reported when doing a CLIB build.  The problems
+occur because some versions of the CLIB SDK import files inadvertently 
+left out some symbols.  One symbol in particular is "_lrotl".  The missing
+functions are actually delivered in the binaries, but they were left out of
+the import files.  The issues should be fixed in the September 2001 release 
+of the NDK.  If you experience the problems you can temporarily
+work around it by manually adding the missing symbols to your version of 
+"clib.imp".