crypto/openssl/NOTES-NONSTOP.md

   1 NOTES FOR THE HPE NONSTOP PLATFORM
   2 ==============================
   3
   4 Requirement details
   5 -------------------
   6
   7 In addition to the requirements and instructions listed
   8 in [INSTALL.md](INSTALL.md), the following are required as well:
   9
  10  * The TNS/X platform supports hardware randomization.
  11    Specify the `--with-rand-seed=rdcpu` option to the `./Configure` script.
  12    This is recommended but not required. `egd` is supported at 3.0 but cannot
  13    be used if FIPS is selected.
  14  * The TNS/E platform does not support hardware randomization, so
  15    specify the `--with-rand-seed=egd` option to the `./Configure` script.
  16
  17 About c99 compiler
  18 ------------------
  19
  20 The c99 compiler is required for building OpenSSL from source. While c11
  21 may work, it has not been broadly tested. c99 is the only compiler
  22 prerequisite needed to build OpenSSL 3.0 on this platform. You should also
  23 have the FLOSS package installed on your system. The ITUGLIB FLOSS package
  24 is the only FLOSS variant that has been broadly tested.
  25
  26 Threading Models
  27 ----------------
  28
  29 OpenSSL can be built using unthreaded, POSIX User Threads (PUT), or Standard
  30 POSIX Threads (SPT). Select the following build configuration for each on
  31 the TNS/X (L-Series) platform:
  32
  33  * `nonstop-nsx` or default will select an unthreaded build.
  34  * `nonstop-nsx_put` selects the PUT build.
  35  * `nonstop-nsx_64_put` selects the 64 bit file length PUT build.
  36  * `nonstop-nsx_spt_floss` selects the SPT build with FLOSS. FLOSS is
  37    required for SPT builds because of a known hang when using SPT on its own.
  38
  39 ### TNS/E Considerations
  40
  41 The TNS/E platform is build using the same set of builds specifying `nse`
  42 instead of `nsx` in the set above.
  43
  44 You cannot build for TNS/E for FIPS, so you must specify the `no-fips`
  45 option to `./Configure`.
  46
  47 Linking and Loading Considerations
  48 ----------------------------------
  49
  50 Because of how the NonStop Common Runtime Environment (CRE) works, there are
  51 restrictions on how programs can link and load with OpenSSL libraries.
  52 On current NonStop platforms, programs cannot both statically link OpenSSL
  53 libraries and dynamically load OpenSSL shared libraries concurrently. If this
  54 is done, there is a high probability of encountering a SIGSEGV condition
  55 relating to `atexit()` processing when a shared library is unloaded and when
  56 the program terminates. This limitation applies to all OpenSSL shared library
  57 components.
  58
  59 It is possible to configure the build with `no-atexit` to avoid the SIGSEGV.
  60 Preferably, you can explicitly call `OPENSSL_cleanup()` from your application.
  61 It is not mandatory as it just deallocates various global data structures
  62 OpenSSL allocated.
  63
  64 About Prefix and OpenSSLDir
  65 ---------------------------
  66
  67 Because there are many potential builds that must co-exist on any given
  68 NonStop node, managing the location of your build distribution is crucial.
  69 Keep each destination separate and distinct. Mixing any mode described in
  70 this document can cause application instability. The recommended approach
  71 is to specify the OpenSSL version and threading model in your configuration
  72 options, and keeping your memory and float options consistent, for example:
  73
  74  * For 1.1 `--prefix=/usr/local-ssl1.1 --openssldir=/usr/local-ssl1.1/ssl`
  75  * For 1.1 PUT `--prefix=/usr/local-ssl1.1_put --openssldir=/usr/local-ssl1.1_put/ssl`
  76
  77 As of 3.0, the NonStop configurations use the multilib attribute to distinguish
  78 between different models:
  79
  80  * For 3.0 `--prefix=/usr/local-ssl3.0 --openssldir=/usr/local-ssl3.0/ssl`
  81
  82 The PUT model is placed in `${prefix}/lib-put` for 32-bit models and
  83 `${prefix}/lib64-put` for 64-bit models.
  84
  85 Use the `_RLD_LIB_PATH` environment variable in OSS to select the appropriate
  86 directory containing `libcrypto.so` and `libssl.so`. In GUARDIAN, use the
  87 `=_RLD_LIB_PATH` search define to locate the GUARDIAN subvolume where OpenSSL
  88 is installed.
  89
  90 Float Considerations
  91 --------------------
  92
  93 OpenSSL is built using IEEE Float mode by default. If you need a different
  94 IEEE mode, create a new configuration specifying `tfloat-x86-64` (for Tandem
  95 Float) or `nfloat-x86-64` (for Neutral Float).
  96
  97 Memory Models
  98 -------------
  99
 100 The current OpenSSL default memory model uses the default platform address
 101 model. If you need a different address model, you must specify the appropriate
 102 c99 options for compile (`CFLAGS`) and linkers (`LDFLAGS`).
 103
 104 Cross Compiling on Windows
 105 --------------------------
 106
 107 To configure and compile OpenSSL, you will need to set up a Cygwin environment.
 108 The Cygwin tools should include bash, make, and any other normal tools required
 109 for building programs.
 110
 111 Your `PATH` must include the bin directory for the c99 cross-compiler, as in:
 112
 113     export PATH=/cygdrive/c/Program\ Files\ \(x86\)/HPE\ NonStop/L16.05/usr/bin:$PATH
 114
 115 This should be set before Configure is run. For the c99 cross-compiler to work
 116 correctly, you also need the `COMP_ROOT` set, as in:
 117
 118     export COMP_ROOT="C:\Program Files (x86)\HPE NonStop\L16.05"
 119
 120 `COMP_ROOT` needs to be in Windows form.
 121
 122 `Configure` must specify the `no-makedepend` option otherwise errors will
 123 result when running the build because the c99 cross-compiler does not support
 124 the `gcc -MT` option. An example of a `Configure` command to be run from the
 125 OpenSSL directory is:
 126
 127     ./Configure nonstop-nsx_64 no-makedepend --with-rand-seed=rdcpu
 128
 129 Do not forget to include any OpenSSL cross-compiling prefix and certificate
 130 options when creating your libraries.
 131
 132 The OpenSSL test suite will not run on your workstation. In order to verify the
 133 build, you will need to perform the build and test steps in OSS in your NonStop
 134 server. You can also build under gcc and run the test suite for Windows but that
 135 is not equivalent.
 136
 137 **Note:** In the event that you are attempting a FIPS-compliant cross-compile,
 138 be aware that signatures may not match between builds done under OSS and under
 139 cross-compiles as the compilers do not necessarily generate identical objects.
 140 Anything and everything to do with FIPS is outside the scope of this document.
 141 Refer to the FIPS security policy for more information.
 142
 143 The following build configurations have been successfully attempted at one
 144 point or another. If you are successful in your cross-compile efforts, please
 145 update this list:
 146
 147 - nonstop-nsx_64
 148 - nonstop-nsx_64_put
 149
 150 **Note:** Cross-compile builds for TNS/E have not been attempted, but should
 151 follow the same considerations as for TNS/X above. SPT builds generally require
 152 FLOSS, which is not available for workstation builds. As a result, SPT builds
 153 of OpenSSL cannot be cross-compiled.
 154
 155 Also see the NSDEE discussion below for more historical information.
 156
 157 Cross Compiling with NSDEE
 158 --------------------------
 159
 160 **Note:** None of these builds have been tested by the platform maintainer and
 161 are supplied for historical value. Please submit a Pull Request to OpenSSL
 162 should these need to be adjusted.
 163
 164 If you are attempting to build OpenSSL with NSDEE, you will need to specify
 165 the following variables. The following set of compiler defines are required:
 166
 167     # COMP_ROOT must be a full path for the build system (e.g. windows)
 168     COMP_ROOT=$(cygpath -w /path/to/comp_root)
 169     # CC must be executable by your shell
 170     CC=/path/to/c99
 171
 172 ### Optional Build Variables
 173
 174     DBGFLAG="--debug"
 175     CIPHENABLES="enable-ssl3 enable-ssl3-method enable-weak-ssl-ciphers enable-rc4"
 176
 177 ### Internal Known TNS/X to TNS/E Cross Compile Variables
 178
 179 The following definition is required if you are building on TNS/X for TNS/E
 180 and have access to a TNS/E machine on your EXPAND network - with an example
 181 node named `\CS3`:
 182
 183     SYSTEMLIBS="-L/E/cs3/usr/local/lib"
 184
 185 Version Procedure (VPROC) Considerations
 186 ----------------------------------------
 187
 188 If you require a VPROC entry for platform version identification, use the
 189 following variables:
 190
 191 ### For Itanium
 192
 193     OPENSSL_VPROC_PREFIX=T0085H06
 194
 195 ### For x86
 196
 197     OPENSSL_VPROC_PREFIX=T0085L01
 198
 199 ### Common Definition
 200
 201     export OPENSSL_VPROC=${OPENSSL_VPROC_PREFIX}_$(
 202         . VERSION.dat
 203         if [ -n "$PRE_RELEASE_TAG" ]; then
 204             PRE_RELEASE_TAG="-$PRE_RELEASE_TAG"
 205         fi
 206         if [ -n "$BUILD_METADATA" ]; then
 207             BUILD_METADATA="+$BUILD_METADATA"
 208         fi
 209         echo "$MAJOR.$MINOR.$PATCH$PRE_RELEASE_TAG$BUILD_METADATA" |\
 210             sed -e 's/[-.+]/_/g'
 211         )
 212
 213 Example Configure Targets
 214 -------------------------
 215
 216 For OSS targets, the main DLL names will be `libssl.so` and `libcrypto.so`.
 217 For GUARDIAN targets, DLL names will be `ssl` and `crypto`. The following
 218 assumes that your PWD is set according to your installation standards.
 219
 220     ./Configure nonstop-nsx           --prefix=${PWD} \
 221         --openssldir=${PWD}/ssl no-threads \
 222         --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 223     ./Configure nonstop-nsx_g         --prefix=${PWD} \
 224         --openssldir=${PWD}/ssl no-threads \
 225         --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 226     ./Configure nonstop-nsx_put       --prefix=${PWD} \
 227         --openssldir=${PWD}/ssl threads "-D_REENTRANT" \
 228         --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 229     ./Configure nonstop-nsx_spt_floss --prefix=${PWD} \
 230         --openssldir=${PWD}/ssl threads "-D_REENTRANT" \
 231         --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 232     ./Configure nonstop-nsx_64        --prefix=${PWD} \
 233         --openssldir=${PWD}/ssl no-threads \
 234         --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 235     ./Configure nonstop-nsx_64_put    --prefix=${PWD} \
 236         --openssldir=${PWD}/ssl threads "-D_REENTRANT" \
 237         --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 238     ./Configure nonstop-nsx_g_tandem  --prefix=${PWD} \
 239         --openssldir=${PWD}/ssl no-threads \
 240         --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 241
 242     ./Configure nonstop-nse           --prefix=${PWD} \
 243         --openssldir=${PWD}/ssl no-threads \
 244         --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 245     ./Configure nonstop-nse_g         --prefix=${PWD} \
 246         --openssldir=${PWD}/ssl no-threads \
 247         --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 248     ./Configure nonstop-nse_put       --prefix=${PWD} \
 249         --openssldir=${PWD}/ssl threads "-D_REENTRANT" \
 250         --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 251     ./Configure nonstop-nse_spt_floss --prefix=${PWD} \
 252         --openssldir=${PWD}/ssl threads "-D_REENTRANT" \
 253         --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 254     ./Configure nonstop-nse_64        --prefix=${PWD} \
 255         --openssldir=${PWD}/ssl no-threads \
 256         --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 257     ./Configure nonstop-nse_64_put    --prefix=${PWD} \
 258         --openssldir=${PWD}/ssl threads "-D_REENTRANT"
 259         --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
 260     ./Configure nonstop-nse_g_tandem  --prefix=${PWD} \
 261         --openssldir=${PWD}/ssl no-threads \
 262         --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}