[thirdparty/openssl.git] / NOTES-NONSTOP.md

NOTES FOR THE HPE NONSTOP PLATFORM
==============================

Requirement details
-------------------

In addition to the requirements and instructions listed
in [INSTALL.md](INSTALL.md), the following are required as well:

 * The TNS/X platform supports hardware randomization.
   Specify the `--with-rand-seed=rdcpu` option to the `./Configure` script.
   This is recommended but not required. `egd` is supported at 3.0 but cannot
   be used if FIPS is selected.
 * The TNS/E platform does not support hardware randomization, so
   specify the `--with-rand-seed=egd` option to the `./Configure` script.

About c99 compiler
------------------

The c99 compiler is required for building OpenSSL from source. While c11
may work, it has not been broadly tested. c99 is the only compiler
prerequisite needed to build OpenSSL 3.0 on this platform. You should also
have the FLOSS package installed on your system. The ITUGLIB FLOSS package
is the only FLOSS variant that has been broadly tested.

Threading Models
----------------

OpenSSL can be built using unthreaded, POSIX User Threads (PUT), or Standard
POSIX Threads (SPT). Select the following build configuration for each on
the TNS/X (L-Series) platform:

 * `nonstop-nsx` or default will select an unthreaded build.
 * `nonstop-nsx_put` selects the PUT build.
 * `nonstop-nsx_64_put` selects the 64 bit file length PUT build.
 * `nonstop-nsx_spt_floss` selects the SPT build with FLOSS. FLOSS is
   required for SPT builds because of a known hang when using SPT on its own.

### TNS/E Considerations

The TNS/E platform is build using the same set of builds specifying `nse`
instead of `nsx` in the set above.

You cannot build for TNS/E for FIPS, so you must specify the `no-fips`
option to `./Configure`

About Prefix and OpenSSLDir
---------------------------

Because there are many potential builds that must co-exist on any given
NonStop node, managing the location of your build distribution is crucial.
Keep each destination separate and distinct. Mixing any mode described in
this document can cause application instability. The recommended approach
is to specify the OpenSSL version and threading model in your configuration
options, and keeping your memory and float options consistent, for example:

 * For 1.1 `--prefix=/usr/local-ssl1.1 --openssldir=/usr/local-ssl1.1/ssl`
 * For 1.1 PUT `--prefix=/usr/local-ssl1.1_put --openssldir=/usr/local-ssl1.1_put/ssl`
 * For 3.0 `--prefix=/usr/local-ssl3.0 --openssldir=/usr/local-ssl3.0/ssl`
 * For 3.0 PUT `--prefix=/usr/local-ssl3.0_put --openssldir=/usr/local-ssl3.0_put/ssl`

Use the `_RLD_LIB_PATH` environment variable in OSS to select the appropriate
directory containing `libcrypto.so` and `libssl.so`. In GUARDIAN, use the
`=_RLD_LIB_PATH` search define to locate the GUARDIAN subvolume where OpenSSL
is installed.

Float Considerations
--------------------

OpenSSL is built using IEEE Float mode by default. If you need a different
IEEE mode, create a new configuration specifying `tfloat-x86-64` (for Tandem
Float) or `nfloat-x86-64` (for Neutral Float).

Memory Models
-------------

The current OpenSSL default memory model uses the default platform address
model. If you need a different address model, you must specify the appropriate
c99 options for compile (`CFLAGS`) and linkers (`LDFLAGS`).

Cross Compiling with NSDEE
--------------------------

**Note:** None of these builds have been tested by the platform maintainer and are
supplied for historical value. Please submit a Pull Request to OpenSSL should
these need to be adjusted.

If you are attempting to build OpenSSL with NSDEE, you will need to specify
the following variables. The following set of compiler defines are required:

    # COMP_ROOT must be a full path for the build system (e.g. windows)
    COMP_ROOT=$(cygpath -w /path/to/comp_root)
    # CC must be executable by your shell
    CC=/path/to/c99

### Optional Build Variables

    DBGFLAG="--debug"
    CIPHENABLES="enable-ssl3 enable-ssl3-method enable-weak-ssl-ciphers enable-rc4"

### Internal Known TNS/X to TNS/E Cross Compile Variables

The following definition is required if you are building on TNS/X for TNS/E
and have access to a TNS/E machine on your EXPAND network - with an example
node named `\CS3`:

    SYSTEMLIBS="-L/E/cs3/usr/local/lib"

Version Procedure (VPROC) Considerations
----------------------------------------

If you require a VPROC entry for platform version identification, use the
following variables:

### For Itanium

    OPENSSL_VPROC_PREFIX=T0085H06

### For x86

    OPENSSL_VPROC_PREFIX=T0085L01

### Common Definition

    export OPENSSL_VPROC=${OPENSSL_VPROC_PREFIX}_$(
        . VERSION.dat
        if [ -n "$PRE_RELEASE_TAG" ]; then
            PRE_RELEASE_TAG="-$PRE_RELEASE_TAG"
        fi
        echo "$MAJOR.$MINOR.$PATCH$PRE_RELEASE_TAG$BUILD_METADATA" |\
            sed -e 's/[-.+]/_/g'
        )

Example Configure Targets
-------------------------

For OSS targets, the main DLL names will be `libssl.so` and `libcrypto.so`.
For GUARDIAN targets, DLL names will be `ssl` and `crypto`. The following
assumes that your PWD is set according to your installation standards.

    ./Configure nonstop-nsx           --prefix=${PWD} \
        --openssldir=${PWD}/ssl no-threads \
        --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nsx_g         --prefix=${PWD} \
        --openssldir=${PWD}/ssl no-threads \
        --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nsx_put       --prefix=${PWD} \
        --openssldir=${PWD}/ssl threads "-D_REENTRANT" \
        --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nsx_spt_floss --prefix=${PWD} \
        --openssldir=${PWD}/ssl threads "-D_REENTRANT" \
        --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nsx_64        --prefix=${PWD} \
        --openssldir=${PWD}/ssl no-threads \
        --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nsx_64_put    --prefix=${PWD} \
        --openssldir=${PWD}/ssl threads "-D_REENTRANT" \
        --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nsx_g_tandem  --prefix=${PWD} \
        --openssldir=${PWD}/ssl no-threads \
        --with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}

    ./Configure nonstop-nse           --prefix=${PWD} \
        --openssldir=${PWD}/ssl no-threads \
        --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nse_g         --prefix=${PWD} \
        --openssldir=${PWD}/ssl no-threads \
        --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nse_put       --prefix=${PWD} \
        --openssldir=${PWD}/ssl threads "-D_REENTRANT" \
        --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nse_spt_floss --prefix=${PWD} \
        --openssldir=${PWD}/ssl threads "-D_REENTRANT" \
        --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nse_64        --prefix=${PWD} \
        --openssldir=${PWD}/ssl no-threads \
        --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nse_64_put    --prefix=${PWD} \
        --openssldir=${PWD}/ssl threads "-D_REENTRANT"
        --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
    ./Configure nonstop-nse_g_tandem  --prefix=${PWD} \
        --openssldir=${PWD}/ssl no-threads \
        --with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
Commit	Line	Data
648cf924 RB	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	About Prefix and OpenSSLDir
	48	---------------------------
	49
	50	Because there are many potential builds that must co-exist on any given
	51	NonStop node, managing the location of your build distribution is crucial.
	52	Keep each destination separate and distinct. Mixing any mode described in
	53	this document can cause application instability. The recommended approach
	54	is to specify the OpenSSL version and threading model in your configuration
	55	options, and keeping your memory and float options consistent, for example:
	56
	57	* For 1.1 `--prefix=/usr/local-ssl1.1 --openssldir=/usr/local-ssl1.1/ssl`
	58	* For 1.1 PUT `--prefix=/usr/local-ssl1.1_put --openssldir=/usr/local-ssl1.1_put/ssl`
	59	* For 3.0 `--prefix=/usr/local-ssl3.0 --openssldir=/usr/local-ssl3.0/ssl`
	60	* For 3.0 PUT `--prefix=/usr/local-ssl3.0_put --openssldir=/usr/local-ssl3.0_put/ssl`
	61
	62	Use the `_RLD_LIB_PATH` environment variable in OSS to select the appropriate
	63	directory containing `libcrypto.so` and `libssl.so`. In GUARDIAN, use the
	64	`=_RLD_LIB_PATH` search define to locate the GUARDIAN subvolume where OpenSSL
65	is installed.
66
67	Float Considerations
68	--------------------
69
70	OpenSSL is built using IEEE Float mode by default. If you need a different
71	IEEE mode, create a new configuration specifying `tfloat-x86-64` (for Tandem
72	Float) or `nfloat-x86-64` (for Neutral Float).
73
74	Memory Models
75	-------------
76
77	The current OpenSSL default memory model uses the default platform address
78	model. If you need a different address model, you must specify the appropriate
79	c99 options for compile (`CFLAGS`) and linkers (`LDFLAGS`).
80
81	Cross Compiling with NSDEE
82	--------------------------
83
84	Note: None of these builds have been tested by the platform maintainer and are
85	supplied for historical value. Please submit a Pull Request to OpenSSL should
86	these need to be adjusted.
87
88	If you are attempting to build OpenSSL with NSDEE, you will need to specify
89	the following variables. The following set of compiler defines are required:
90
91	# COMP_ROOT must be a full path for the build system (e.g. windows)
92	COMP_ROOT=$(cygpath -w /path/to/comp_root)
93	# CC must be executable by your shell
94	CC=/path/to/c99
95
96	### Optional Build Variables
97
98	DBGFLAG="--debug"
99	CIPHENABLES="enable-ssl3 enable-ssl3-method enable-weak-ssl-ciphers enable-rc4"
100
101	### Internal Known TNS/X to TNS/E Cross Compile Variables
102
103	The following definition is required if you are building on TNS/X for TNS/E
104	and have access to a TNS/E machine on your EXPAND network - with an example
105	node named `\CS3`:
106
107	SYSTEMLIBS="-L/E/cs3/usr/local/lib"
108
109	Version Procedure (VPROC) Considerations
110	----------------------------------------
111
112	If you require a VPROC entry for platform version identification, use the
113	following variables:
114
115	### For Itanium
116
117	OPENSSL_VPROC_PREFIX=T0085H06
118
119	### For x86
120
121	OPENSSL_VPROC_PREFIX=T0085L01
122
123	### Common Definition
124
125	export OPENSSL_VPROC=${OPENSSL_VPROC_PREFIX}_$(
126	. VERSION.dat
127	if [ -n "$PRE_RELEASE_TAG" ]; then
128	PRE_RELEASE_TAG="-$PRE_RELEASE_TAG"
129	fi
130	echo "$MAJOR.$MINOR.$PATCH$PRE_RELEASE_TAG$BUILD_METADATA" \|\
131	sed -e 's/[-.+]/_/g'
132	)
133
134	Example Configure Targets
135	-------------------------
136
137	For OSS targets, the main DLL names will be `libssl.so` and `libcrypto.so`.
138	For GUARDIAN targets, DLL names will be `ssl` and `crypto`. The following
139	assumes that your PWD is set according to your installation standards.
140
141	./Configure nonstop-nsx --prefix=${PWD} \
142	--openssldir=${PWD}/ssl no-threads \
143	--with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
144	./Configure nonstop-nsx_g --prefix=${PWD} \
145	--openssldir=${PWD}/ssl no-threads \
146	--with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
147	./Configure nonstop-nsx_put --prefix=${PWD} \
148	--openssldir=${PWD}/ssl threads "-D_REENTRANT" \
149	--with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
150	./Configure nonstop-nsx_spt_floss --prefix=${PWD} \
151	--openssldir=${PWD}/ssl threads "-D_REENTRANT" \
152	--with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
153	./Configure nonstop-nsx_64 --prefix=${PWD} \
154	--openssldir=${PWD}/ssl no-threads \
155	--with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
156	./Configure nonstop-nsx_64_put --prefix=${PWD} \
157	--openssldir=${PWD}/ssl threads "-D_REENTRANT" \
158	--with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
159	./Configure nonstop-nsx_g_tandem --prefix=${PWD} \
160	--openssldir=${PWD}/ssl no-threads \
161	--with-rand-seed=rdcpu ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
162
163	./Configure nonstop-nse --prefix=${PWD} \
164	--openssldir=${PWD}/ssl no-threads \
165	--with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
166	./Configure nonstop-nse_g --prefix=${PWD} \
167	--openssldir=${PWD}/ssl no-threads \
168	--with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
169	./Configure nonstop-nse_put --prefix=${PWD} \
170	--openssldir=${PWD}/ssl threads "-D_REENTRANT" \
171	--with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
172	./Configure nonstop-nse_spt_floss --prefix=${PWD} \
173	--openssldir=${PWD}/ssl threads "-D_REENTRANT" \
174	--with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
175	./Configure nonstop-nse_64 --prefix=${PWD} \
176	--openssldir=${PWD}/ssl no-threads \
177	--with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
178	./Configure nonstop-nse_64_put --prefix=${PWD} \
179	--openssldir=${PWD}/ssl threads "-D_REENTRANT"
180	--with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}
181	./Configure nonstop-nse_g_tandem --prefix=${PWD} \
182	--openssldir=${PWD}/ssl no-threads \
183	--with-rand-seed=egd ${CIPHENABLES} ${DBGFLAG} ${SYSTEMLIBS}