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