diff options
author | Richard Levitte <levitte@openssl.org> | 2003-11-28 13:10:58 +0000 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2003-11-28 13:10:58 +0000 |
commit | 4d8743f490a5f96fa26d41985ee12cb6b9815a4c (patch) | |
tree | 9668a30c8c9bcc3347eddb5b553d8f1c6ccc8524 | |
parent | 4c8b4f9d03fb5db99fa22b235369b96039f60706 (diff) |
Netware-specific changes,
PR: 780
Submitted by: Verdon Walker <VWalker@novell.com>
Reviewed by: Richard Levitte
67 files changed, 3490 insertions, 43 deletions
@@ -519,6 +519,12 @@ my %table=( "Cygwin", "gcc:-DTERMIOS -DL_ENDIAN -fomit-frame-pointer -O3 -march=i486 -Wall:::CYGWIN32::BN_LLONG ${x86_gcc_des} ${x86_gcc_opts}:${x86_out_asm}:win32:cygwin-shared:::.dll", "debug-Cygwin", "gcc:-DTERMIOS -DL_ENDIAN -march=i486 -Wall -DBN_DEBUG -DREF_CHECK -DCONF_DEBUG -DBN_CTX_DEBUG -DCRYPTO_MDEBUG -DOPENSSL_NO_ASM -g -Wformat -Wshadow -Wmissing-prototypes -Wmissing-declarations -Werror:::CYGWIN32::::win32:cygwin-shared:::.dll", +# NetWare from David Ward (dsward@novell.com) - requires MetroWerks NLM development tools +# netware-clib => legacy CLib c-runtime support +"netware-clib", "mwccnlm:::::${x86_gcc_opts}:::", +# netware-libc => LibC/NKS support +"netware-libc", "mwccnlm:::::BN_LLONG ${x86_gcc_opts}:::", + # DJGPP "DJGPP", "gcc:-I/dev/env/WATT_ROOT/inc -DTERMIOS -DL_ENDIAN -fomit-frame-pointer -O2 -Wall:::MSDOS:-L/dev/env/WATT_ROOT/lib -lwatt:BN_LLONG ${x86_gcc_des} ${x86_gcc_opts}::::::::::", @@ -570,8 +576,8 @@ my %table=( ); -my @WinTargets=qw(VC-NT VC-CE VC-WIN32 VC-WIN16 VC-W31-16 VC-W31-32 VC-MSDOS - BC-32 BC-16 Mingw32 OS2-EMX); +my @MK1MF_Builds=qw(VC-NT VC-CE VC-WIN32 VC-WIN16 VC-W31-16 VC-W31-32 VC-MSDOS + BC-32 BC-16 Mingw32 OS2-EMX netware-clib netware-libc); my $idx = 0; my $idx_cc = $idx++; @@ -940,7 +946,7 @@ print "Configuring for $target\n"; &usage if (!defined($table{$target})); -my $IsWindows=scalar grep /^$target$/,@WinTargets; +my $IsMK1MF=scalar grep /^$target$/,@MK1MF_Builds; $exe_ext=".exe" if ($target eq "Cygwin"); $exe_ext=".exe" if ($target eq "DJGPP"); @@ -954,7 +960,7 @@ $openssldir=$prefix . "/ssl" if $openssldir eq ""; $openssldir=$prefix . "/" . $openssldir if $openssldir !~ /(^\/|^[a-zA-Z]:[\\\/])/; -print "IsWindows=$IsWindows\n"; +print "IsMK1MF=$IsMK1MF\n"; my @fields = split(/\s*:\s*/,$table{$target} . ":" x 30 , -1); my $cc = $fields[$idx_cc]; @@ -1502,7 +1508,7 @@ print "RC2 uses u$type[$rc2_int]\n" if $rc2_int != $def_int; print "BF_PTR used\n" if $bf_ptr == 1; print "BF_PTR2 used\n" if $bf_ptr == 2; -if($IsWindows) { +if($IsMK1MF) { open (OUT,">crypto/buildinf.h") || die "Can't open buildinf.h"; printf OUT <<EOF; #ifndef MK1MF_BUILD @@ -1544,7 +1550,7 @@ EOF } # create the ms/version32.rc file if needed -if ($IsWindows) { +if ($IsMK1MF) { my ($v1, $v2, $v3, $v4); if ($version_num =~ /(^[0-9a-f]{1})([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})/i) { $v1=hex $1; @@ -2,8 +2,10 @@ INSTALLATION ON THE UNIX PLATFORM --------------------------------- - [Installation on DOS (with djgpp), Windows, OpenVMS and MacOS (before MacOS X) - is described in INSTALL.DJGPP, INSTALL.W32, INSTALL.VMS and INSTALL.MacOS. + [Installation on DOS (with djgpp), Windows, OpenVMS, MacOS (before MacOS X) + and NetWare is described in INSTALL.DJGPP, INSTALL.W32, INSTALL.VMS, + INSTALL.MacOS and INSTALL.NW. + This document describes installation on operating systems in the Unix family.] 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 s |