Commit 4d8743f4 authored by Richard Levitte's avatar Richard Levitte
Browse files

Netware-specific changes, 

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

Configure

+12 −6
Original line number Diff line number Diff line
@@ -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;

INSTALL

+4 −2
Original line number Diff line number Diff line
@@ -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.]

INSTALL.NW

0 → 100644
+437 −0
Original line number Diff line number Diff line 


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".

Netware/build.bat

0 → 100644
+204 −0

File added.

Preview size limit exceeded, changes collapsed.

Netware/cpy_tests.bat

0 → 100644
+112 −0
Original line number Diff line number Diff line 
@echo off



rem   Batch file to copy OpenSSL stuff to a NetWare server for testing



rem   This batch file will create an "opensssl" directory at the root of the

rem   specified NetWare drive and copy the required files to run the tests.

rem   It should be run from inside the "openssl\netware" subdirectory.



rem   Usage:

rem      cpy_tests.bat <test subdirectory> <NetWare drive>

rem          <test subdirectory> - out_nw.dbg | out_nw

rem          <NetWare drive> - any mapped drive letter

rem

rem      example ( copy from debug build to m: dirve ):

rem              cpy_tests.bat out_nw.dbg m:

rem

rem      CAUTION:  If a directory named OpenSSL exists on the target drive

rem                it will be deleted first.





if "%1" == "" goto usage

if "%2" == "" goto usage



rem   Assume running in \openssl directory unless cpy_tests.bat exists then

rem   it must be the \openssl\netware directory

set loc=.

if exist cpy_tests.bat set loc=..



rem   make sure the local build subdirectory specified is valid

if not exist %loc%\%1\NUL goto invalid_dir



rem   make sure target drive is valid

if not exist %2\NUL goto invalid_drive



rem   If an OpenSSL directory exists on the target drive, remove it

if exist %2\openssl\NUL goto remove_openssl

goto do_copy



:remove_openssl

echo .

echo OpenSSL directory exists on %2 - it will be removed!

pause

rmdir %2\openssl /s /q



:do_copy

rem   make an "openssl" directory and others at the root of the NetWare drive

mkdir %2\openssl

mkdir %2\openssl\test_out

mkdir %2\openssl\apps

mkdir %2\openssl\certs

mkdir %2\openssl\test





rem   copy the test nlms

copy %loc%\%1\*.nlm %2\openssl\



rem   copy the test perl script

copy %loc%\netware\do_tests.pl %2\openssl\



rem   copy the certs directory stuff

xcopy %loc%\certs\*.*         %2\openssl\certs\ /s



rem   copy the test directory stuff

copy %loc%\test\CAss.cnf      %2\openssl\test\

copy %loc%\test\Uss.cnf       %2\openssl\test\

copy %loc%\test\pkcs7.pem     %2\openssl\test\

copy %loc%\test\pkcs7-1.pem   %2\openssl\test\

copy %loc%\test\testcrl.pem   %2\openssl\test\

copy %loc%\test\testp7.pem    %2\openssl\test\

copy %loc%\test\testreq2.pem  %2\openssl\test\

copy %loc%\test\testrsa.pem   %2\openssl\test\

copy %loc%\test\testsid.pem   %2\openssl\test\

copy %loc%\test\testx509.pem  %2\openssl\test\

copy %loc%\test\v3-cert1.pem  %2\openssl\test\

copy %loc%\test\v3-cert2.pem  %2\openssl\test\



rem   copy the apps directory stuff

copy %loc%\apps\client.pem    %2\openssl\apps\

copy %loc%\apps\server.pem    %2\openssl\apps\

copy %loc%\apps\openssl.cnf   %2\openssl\apps\



echo .

echo Tests copied

echo Run the test script at the console by typing:

echo     "Perl \openssl\do_tests.pl"

echo .

echo Make sure the Search path includes the OpenSSL subdirectory



goto end



:invalid_dir

echo.

echo Invalid build directory specified: %1

echo.

goto usage



:invalid_drive

echo.

echo Invalid drive: %2

echo.

goto usage



:usage

echo.

echo usage: cpy_tests.bat [test subdirectory] [NetWare drive]

echo     [test subdirectory] - out_nw_clib.dbg, out_nw_libc.dbg, etc. 

echo     [NetWare drive]     - any mapped drive letter

echo.

echo example: cpy_test out_nw_clib.dbg M:

echo  (copy from clib debug build area to M: drive)



:end