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