Back to home page

openssl Cross Reference

 
 

    


0001 
0002 INSTALLATION ON THE NETWARE PLATFORM
0003 ------------------------------------
0004 
0005 Notes about building OpenSSL for NetWare.
0006 
0007 
0008 BUILD PLATFORM:
0009 ---------------
0010 The build scripts (batch files, perl scripts, etc) have been developed and
0011 tested on W2K.  The scripts should run fine on other Windows platforms
0012 (NT, Win9x, WinXP) but they have not been tested.  They may require some
0013 modifications.
0014 
0015 
0016 Supported NetWare Platforms - NetWare 5.x, NetWare 6.x:
0017 -------------------------------------------------------
0018 OpenSSL can either use the WinSock interfaces introduced in NetWare 5,
0019 or the BSD socket interface.  Previous versions of NetWare, 4.x and 3.x,
0020 are only supported if OpenSSL is build for CLIB and BSD sockets;
0021 WinSock builds only support NetWare 5 and up.
0022 
0023 On NetWare there are two c-runtime libraries.  There is the legacy CLIB 
0024 interfaces and the newer LIBC interfaces.  Being ANSI-C libraries, the 
0025 functionality in CLIB and LIBC is similar but the LIBC interfaces are built 
0026 using Novell Kernal Services (NKS) which is designed to leverage 
0027 multi-processor environments.
0028 
0029 The NetWare port of OpenSSL can be configured to build using CLIB or LIBC.
0030 The CLIB build was developed and tested using NetWare 5.0 sp6.0a.  The LIBC 
0031 build was developed and tested using the NetWare 6.0 FCS.  
0032 
0033 The necessary LIBC functionality ships with NetWare 6.  However, earlier 
0034 NetWare 5.x versions will require updates in order to run the OpenSSL LIBC
0035 build (NetWare 5.1 SP8 is known to work).
0036 
0037 As of June 2005, the LIBC build can be configured to use BSD sockets instead
0038 of WinSock sockets. Call Configure (usually through netware\build.bat) using
0039 a target of "netware-libc-bsdsock" instead of "netware-libc".
0040 
0041 As of June 2007, support for CLIB and BSD sockets is also now available
0042 using a target of "netware-clib-bsdsock" instead of "netware-clib";
0043 also gcc builds are now supported on both Linux and Win32 (post 0.9.8e).
0044 
0045 REQUIRED TOOLS:
0046 ---------------
0047 Based upon the configuration and build options used, some or all of the
0048 following tools may be required:
0049 
0050 * Perl for Win32 - required (http://www.activestate.com/ActivePerl)
0051    Used to run the various perl scripts on the build platform.
0052 
0053 * Perl 5.8.0 for NetWare v3.20 (or later) - required 
0054    (http://developer.novell.com) Used to run the test script on NetWare 
0055    after building.
0056 
0057 * Compiler / Linker - required:
0058    Metrowerks CodeWarrior PDK 2.1 (or later) for NetWare (commercial):
0059       Provides command line tools used for building.
0060       Tools:
0061       mwccnlm.exe  - C/C++ Compiler for NetWare
0062       mwldnlm.exe  - Linker for NetWare
0063       mwasmnlm.exe - x86 assembler for NetWare (if using assembly option)
0064 
0065    gcc / nlmconv Cross-Compiler, available from Novell Forge (free):
0066          http://forge.novell.com/modules/xfmod/project/?aunixnw
0067 
0068 * Assemblers - optional:
0069    If you intend to build using the assembly options you will need an
0070    assembler.  Work has been completed to support two assemblers, Metrowerks
0071    and NASM.  However, during development, a bug was found in the Metrowerks
0072    assembler which generates incorrect code.  Until this problem is fixed,
0073    the Metrowerks assembler cannot be used.
0074 
0075    mwasmnlm.exe - Metrowerks x86 assembler - part of CodeWarrior tools.
0076          (version 2.2 Built Aug 23, 1999 - not useable due to code
0077           generation bug)
0078 
0079    nasmw.exe - Netwide Assembler NASM
0080          version 0.98 was used in development and testing
0081 
0082 * Make Tool - required:
0083    In order to build you will need a make tool.  Two make tools are
0084    supported, GNU make (gmake.exe) or Microsoft nmake.exe.
0085 
0086    make.exe - GNU make for Windows (version 3.75 used for development)
0087          http://gnuwin32.sourceforge.net/packages/make.htm
0088 
0089    nmake.exe - Microsoft make (Version 6.00.8168.0 used for development)
0090          http://support.microsoft.com/kb/132084/EN-US/
0091 
0092 * Novell Developer Kit (NDK) - required: (http://developer.novell.com)
0093 
0094    CLIB - BUILDS:
0095 
0096       WinSock2 Developer Components for NetWare:
0097          For initial development, the October 27, 2000 version was used.
0098          However, future versions should also work.
0099 
0100          NOTE:  The WinSock2 components include headers & import files for
0101          NetWare, but you will also need the winsock2.h and supporting
0102          headers (pshpack4.h, poppack.h, qos.h) delivered in the
0103          Microsoft SDK.  Note: The winsock2.h support headers may change
0104          with various versions of winsock2.h.  Check the dependencies
0105          section on the NDK WinSock2 download page for the latest
0106          information on dependencies. These components are unsupported by
0107          Novell. They are provided as a courtesy, but it is strongly
0108          suggested that all development be done using LIBC, not CLIB.
0109 
0110          As of June 2005, the WinSock2 components are available at:
0111          http://forgeftp.novell.com//ws2comp/
0112 
0113 
0114       NLM and NetWare libraries for C (including CLIB and XPlat):
0115          If you are going to build a CLIB version of OpenSSL, you will
0116          need the CLIB headers and imports.  The March, 2001 NDK release or 
0117          later is recommended.
0118 
0119          Earlier versions should work but haven't been tested.  In recent
0120          versions the import files have been consolidated and function
0121          names moved.  This means you may run into link problems
0122          (undefined symbols) when using earlier versions.   The functions
0123          are available in earlier versions, but you will have to modifiy
0124          the make files to include additional import files (see
0125          openssl\util\pl\netware.pl).
0126 
0127 
0128    LIBC - BUILDS:
0129    
0130       Libraries for C (LIBC) - LIBC headers and import files
0131          If you are going to build a LIBC version of OpenSSL, you will
0132          need the LIBC headers and imports.  The March 14, 2002 NDK release or
0133          later is required.  
0134          
0135          NOTE: The LIBC SDK includes the necessary WinSock2 support.
0136          It is not necessary to download the WinSock2 NDK when building for
0137          LIBC. The LIBC SDK also includes the appropriate BSD socket support
0138          if configuring to use BSD sockets.
0139 
0140 
0141 BUILDING:
0142 ---------
0143 Before building, you will need to set a few environment variables.  You can
0144 set them manually or you can modify the "netware\set_env.bat" file.
0145 
0146 The set_env.bat file is a template you can use to set up the path
0147 and environment variables you will need to build.  Modify the
0148 various lines to point to YOUR tools and run set_env.bat.
0149 
0150    netware\set_env.bat <target> [compiler]
0151 
0152       target        - "netware-clib" - CLIB NetWare build
0153                     - "netware-libc" - LIBC NetWare build
0154 
0155       compiler      - "gnuc"         - GNU GCC Compiler
0156                     - "codewarrior"  - MetroWerks CodeWarrior (default)
0157 
0158 If you don't use set_env.bat, you will need to set up the following
0159 environment variables:
0160 
0161    PATH - Set PATH to point to the tools you will use.
0162 
0163    INCLUDE - The location of the NDK include files.
0164          
0165             CLIB ex: set INCLUDE=c:\ndk\nwsdk\include\nlm
0166             LIBC ex: set INCLUDE=c:\ndk\libc\include
0167 
0168    PRELUDE - The absolute path of the prelude object to link with.  For
0169             a CLIB build it is recommended you use the "clibpre.o" files shipped
0170             with the Metrowerks PDK for NetWare.  For a LIBC build you should 
0171             use the "libcpre.o" file delivered with the LIBC NDK components.
0172 
0173             CLIB ex: set PRELUDE=c:\ndk\nwsdk\imports\clibpre.o
0174             LIBC ex: set PRELUDE=c:\ndk\libc\imports\libcpre.o
0175 
0176    IMPORTS - The locaton of the NDK import files.
0177 
0178             CLIB ex: set IMPORTS=c:\ndk\nwsdk\imports
0179             LIBC ex: set IMPORTS=c:\ndk\libc\imports
0180 
0181 
0182 In order to build, you need to run the Perl scripts to configure the build
0183 process and generate a make file.  There is a batch file,
0184 "netware\build.bat", to automate the process.
0185 
0186 Build.bat runs the build configuration scripts and generates a make file.
0187 If an assembly option is specified, it also runs the scripts to generate 
0188 the assembly code.  Always run build.bat from the "openssl" directory.
0189 
0190    netware\build [target] [debug opts] [assembly opts] [configure opts]
0191 
0192       target        - "netware-clib" - CLIB NetWare build (WinSock Sockets)
0193                     - "netware-clib-bsdsock" - CLIB NetWare build (BSD Sockets)
0194                     - "netware-libc" - LIBC NetWare build (WinSock Sockets)
0195                     - "netware-libc-bsdsock" - LIBC NetWare build (BSD Sockets)
0196  
0197       debug opts    - "debug"  - build debug
0198 
0199       assembly opts - "nw-mwasm" - use Metrowerks assembler
0200                       "nw-nasm"  - use NASM assembler
0201                       "no-asm"   - don't use assembly
0202 
0203       configure opts- all unrecognized arguments are passed to the
0204                       perl 'configure' script. See that script for
0205                       internal documentation regarding options that
0206                       are available.
0207 
0208    examples:
0209 
0210       CLIB build, debug, without assembly:
0211          netware\build.bat netware-clib debug no-asm
0212 
0213       LIBC build, non-debug, using NASM assembly, add mdc2 support:
0214          netware\build.bat netware-libc nw-nasm enable-mdc2
0215 
0216       LIBC build, BSD sockets, non-debug, without assembly:
0217          netware\build.bat netware-libc-bsdsock no-asm
0218 
0219 Running build.bat generates a make file to be processed by your make 
0220 tool (gmake or nmake):
0221 
0222    CLIB ex: gmake -f netware\nlm_clib_dbg.mak 
0223    LIBC ex: gmake -f netware\nlm_libc.mak 
0224    LIBC ex: gmake -f netware\nlm_libc_bsdsock.mak 
0225 
0226 
0227 You can also run the build scripts manually if you do not want to use the
0228 build.bat file.  Run the following scripts in the "\openssl"
0229 subdirectory (in the order listed below):
0230 
0231    perl configure no-asm [other config opts] [netware-clib|netware-libc|netware-libc-bsdsock]
0232       configures no assembly build for specified netware environment
0233       (CLIB or LIBC).
0234 
0235    perl util\mkfiles.pl >MINFO
0236       generates a listing of source files (used by mk1mf)
0237 
0238    perl util\mk1mf.pl no-asm [other config opts] [netware-clib|netware-libc|netware-libc-bsdsock >netware\nlm.mak
0239       generates the makefile for NetWare
0240 
0241    gmake -f netware\nlm.mak
0242       build with the make tool (nmake.exe also works)
0243 
0244 NOTE:  If you are building using the assembly option, you must also run the
0245 various Perl scripts to generate the assembly files.  See build.bat
0246 for an example of running the various assembly scripts.  You must use the
0247 "no-asm" option to build without assembly.  The configure and mk1mf scripts
0248 also have various other options.  See the scripts for more information.
0249 
0250 
0251 The output from the build is placed in the following directories:
0252 
0253    CLIB Debug build:
0254       out_nw_clib.dbg     - static libs & test nlm(s)
0255       tmp_nw_clib.dbg     - temporary build files
0256       outinc_nw_clib      - necessary include files
0257 
0258    CLIB Non-debug build:
0259       out_nw_clib         - static libs & test nlm(s)
0260       tmp_nw_clib         - temporary build files
0261       outinc_nw_clib      - necesary include files
0262 
0263    LIBC Debug build:
0264       out_nw_libc.dbg     - static libs & test nlm(s)
0265       tmp_nw_libc.dbg     - temporary build files
0266       outinc_nw_libc      - necessary include files
0267 
0268    LIBC Non-debug build:
0269       out_nw_libc         - static libs & test nlm(s)
0270       tmp_nw_libc         - temporary build files
0271       outinc_nw_libc      - necesary include files
0272 
0273 
0274 TESTING:
0275 --------
0276 The build process creates the OpenSSL static libs ( crypto.lib, ssl.lib,
0277 rsaglue.lib ) and several test programs.  You should copy the test programs
0278 to your NetWare server and run the tests.
0279 
0280 The batch file "netware\cpy_tests.bat" will copy all the necessary files
0281 to your server for testing.  In order to run the batch file, you need a
0282 drive mapped to your target server.  It will create an "OpenSSL" directory
0283 on the drive and copy the test files to it.  CAUTION: If a directory with the
0284 name of "OpenSSL" already exists, it will be deleted.
0285 
0286 To run cpy_tests.bat:
0287 
0288    netware\cpy_tests [output directory] [NetWare drive]
0289 
0290       output directory - "out_nw_clib.dbg", "out_nw_libc", etc.
0291       NetWare drive    - drive letter of mapped drive
0292 
0293       CLIB ex: netware\cpy_tests out_nw_clib m:
0294       LIBC ex: netware\cpy_tests out_nw_libc m:
0295 
0296 
0297 The Perl script, "do_tests.pl", in the "OpenSSL" directory on the server
0298 should be used to execute the tests.  Before running the script, make sure
0299 your SEARCH PATH includes the "OpenSSL" directory.  For example, if you
0300 copied the files to the "sys:" volume you use the command:
0301 
0302    SEARCH ADD SYS:\OPENSSL
0303 
0304 
0305 To run do_tests.pl type (at the console prompt):
0306 
0307    perl \openssl\do_tests.pl [options]
0308 
0309       options:
0310          -p    - pause after executing each test
0311 
0312 The do_tests.pl script generates a log file "\openssl\test_out\tests.log"
0313 which should be reviewed for errors.  Any errors will be denoted by the word
0314 "ERROR" in the log.
0315 
0316 DEVELOPING WITH THE OPENSSL SDK:
0317 --------------------------------
0318 Now that everything is built and tested, you are ready to use the OpenSSL
0319 libraries in your development.
0320 
0321 There is no real installation procedure, just copy the static libs and
0322 headers to your build location.  The libs (crypto.lib & ssl.lib) are
0323 located in the appropriate "out_nw_XXXX" directory 
0324 (out_nw_clib, out_nw_libc, etc).  
0325 
0326 The headers are located in the appropriate "outinc_nw_XXX" directory 
0327 (outinc_nw_clib, outinc_nw_libc).  
0328 
0329 One suggestion is to create the following directory 
0330 structure for the OpenSSL SDK:
0331 
0332    \openssl
0333       |- bin
0334       |   |- openssl.nlm
0335       |   |- (other tests you want)
0336       |
0337       |- lib
0338       |   | - crypto.lib
0339       |   | - ssl.lib
0340       |
0341       |- include
0342       |   | - openssl
0343       |   |    | - (all the headers in "outinc_nw\openssl")
0344 
0345 
0346 The program "openssl.nlm" can be very useful.  It has dozens of
0347 options and you may want to keep it handy for debugging, testing, etc.
0348 
0349 When building your apps using OpenSSL, define "NETWARE".  It is needed by
0350 some of the OpenSSL headers.  One way to do this is with a compile option,
0351 for example "-DNETWARE".
0352 
0353 
0354 
0355 NOTES:
0356 ------
0357 
0358 Resource leaks in Tests
0359 ------------------------
0360 Some OpenSSL tests do not clean up resources and NetWare reports
0361 the resource leaks when the tests unload.  If this really bugs you,
0362 you can stop the messages by setting the developer option off at the console
0363 prompt (set developer option = off).  Or better yet, fix the tests to
0364 clean up the resources!
0365 
0366 
0367 Multi-threaded Development
0368 ---------------------------
0369 The NetWare version of OpenSSL is thread-safe, however multi-threaded
0370 applications must provide the necessary locking function callbacks.  This
0371 is described in doc\threads.doc.  The file "openssl-x.x.x\crypto\threads\mttest.c"
0372 is a multi-threaded test program and demonstrates the locking functions.
0373 
0374 
0375 What is openssl2.nlm?
0376 ---------------------
0377 The openssl program has numerous options and can be used for many different
0378 things.  Many of the options operate in an interactive mode requiring the
0379 user to enter data.  Because of this, a default screen is created for the
0380 program.  However, when running the test script it is not desirable to
0381 have a seperate screen.  Therefore, the build also creates openssl2.nlm.
0382 Openssl2.nlm is functionally identical but uses the console screen.
0383 Openssl2 can be used when a non-interactive mode is desired.
0384 
0385 NOTE:  There are may other possibilities (command line options, etc)
0386 which could have been used to address the screen issue.  The openssl2.nlm
0387 option was chosen because it impacted only the build not the code.
0388 
0389 
0390 Why only static libraries?
0391 --------------------------
0392 Globals, globals, and more globals.  The OpenSSL code uses many global
0393 variables that are allocated and initialized when used for the first time.
0394 
0395 On NetWare, most applications (at least historically) run in the kernel.
0396 When running in the kernel, there is one instance of global variables.
0397 For regular application type NLM(s) this isn't a problem because they are
0398 the only ones using the globals.  However, for a library NLM (an NLM which
0399 exposes functions and has no threads of execution), the globals cause
0400 problems.  Applications could inadvertently step on each other if they
0401 change some globals.  Even worse, the first application that triggers a
0402 global to be allocated and initialized has the allocated memory charged to
0403 itself.  Now when that application unloads, NetWare will clean up all the
0404 applicaton's memory.  The global pointer variables inside OpenSSL now
0405 point to freed memory.  An abend waiting to happen!
0406 
0407 To work correctly in the kernel, library NLM(s) that use globals need to
0408 provide a set of globals (instance data) for each application.  Another
0409 option is to require the library only be loaded in a protected address
0410 space along with the application using it.
0411 
0412 Modifying the OpenSSL code to provide a set of globals (instance data) for
0413 each application isn't technically difficult, but due to the large number
0414 globals it would require substantial code changes and it wasn't done.  Hence,
0415 the build currently only builds static libraries which are then linked
0416 into each application.
0417 
0418 NOTE:  If you are building a library NLM that uses the OpenSSL static
0419 libraries, you will still have to deal with the global variable issue.
0420 This is because when you link in the OpenSSL code you bring in all the
0421 globals.  One possible solution for the global pointer variables is to
0422 register memory functions with OpenSSL which allocate memory and charge it
0423 to your library NLM (see the function CRYPTO_set_mem_functions).  However,
0424 be aware that now all memory allocated by OpenSSL is charged to your NLM.
0425 
0426 
0427 CodeWarrior Tools and W2K
0428 ---------------------------
0429 There have been problems reported with the CodeWarrior Linker
0430 (mwldnlm.exe) in the PDK 2.1 for NetWare when running on Windows 2000.  The
0431 problems cause the link step to fail.  The only work around is to obtain an
0432 updated linker from Metrowerks.  It is expected Metrowerks will release
0433 PDK 3.0 (in beta testing at this time - May, 2001) in the near future which
0434 will fix these problems.
0435 
0436 
0437 Makefile "vclean"
0438 ------------------
0439 The generated makefile has a "vclean" target which cleans up the build
0440 directories.  If you have been building successfully and suddenly
0441 experience problems, use "vclean" (gmake -f netware\nlm_xxxx.mak vclean) and retry.
0442 
0443 
0444 "Undefined Symbol" Linker errors
0445 --------------------------------
0446 There have been linker errors reported when doing a CLIB build.  The problems
0447 occur because some versions of the CLIB SDK import files inadvertently 
0448 left out some symbols.  One symbol in particular is "_lrotl".  The missing
0449 functions are actually delivered in the binaries, but they were left out of
0450 the import files.  The issues should be fixed in the September 2001 release 
0451 of the NDK.  If you experience the problems you can temporarily
0452 work around it by manually adding the missing symbols to your version of 
0453 "clib.imp".
0454