Preparing the environment

The SSX tools described in this chapter require the SSX and OpenSSL libraries. Therefore, you have to prepare the environment accordingly using the following scripts:

• ssxenv.bat on Windows
• ssxenv.sh on UNIX; just source the script

Both scripts appropriately set up the command and library search paths for the SSX tools. With a default installation, enter the following commands:

• Windows command prompt (specify the appropriate drive and product installation directory if you do not use the default settings):

  C:\SoftwareAG\common\security\ssx\bin\ssxenv.bat

  Note:

  If the backwards compatible 32-bit SSX tools are to be used, you have to use ssxenv.bat from the ssx_32\bin directory instead.

• UNIX shell (specify the appropriate product installation directory if you do not use the default settings):

  . /opt/softwareag/common/security/ssx/bin/ssxenv.sh

  Note:

  As this script is to be sourced, make sure that there is a space character between the leading dot (.) and the script.

Both scripts load yet another script (tlsenv.bat/tlsenv.sh) to ensure that the necessary OpenSSL libraries are found. With a default installation, this script is available at the following location:

• Windows:

  C:\SoftwareAG\common\security\openssl\extras\tlsenv.bat

• UNIX:

  /opt/softwareag/common/security/openssl/extras/tlsenv.sh

Under certain circumstances, the environment setup previously described might be ignored by the operating system, for example, when using elevated privileges. In this case, follow the example:

Sometimes it is necessary to create a symlink from the expected default directory to the actual installation directory of the libraries (root privileges might be needed to do that):

mkdir -p /opt/softwareag/common/security/ssx
ln -s /actual/path/to/ssx/lib /opt/softwareag/common/security/ssx/lib
mkdir -p /opt/softwareag/common/security/openssl
ln -s /actual/path/to/openssl/lib64 /opt/softwareag/common/security/openssl/lib64

Avoid listing of /actual/path/to/common/security/openssl/lib, /opt/softwareag/common/security/openssl/lib, /usr/lib and /lib or the respective lib64 directories on a Linux system. It is especially not necessary to list the system directories /usr/lib, /usr/lib64, /lib or /lib64 as the system is looking for libraries in these directories anyway.

The environment script prints a warning if it detects a situation when either the system's or the product's OpenSSL libraries would be hidden and hence either the system tools or the webMethods products might not be able to load the correct libraries. A similar warning is produced when the environment variable OPENSSL_MODULES is set. This environment variable can be used to locate additional OpenSSL providers and is not set by default.

The scripts also create the environment variables SSXDIR and TLSDIR, which contain the full qualified paths to the ssx and openssl base directories. Further environment variables with derived values are also set: SSX_CONFIG, OPENSSL_CONF and SSL_CERT_FILE (see Environment variables affecting behavior and configuration for brief explanations).

Using OpenSSL's FIPS 140-2 certified provider

After a long time, OpenSSL 3.0.0 was the first version to distribute a FIPS 140-2 certified module. IBM® webMethods builds this module according to the instructions published in the OpenSSL FIPS 140-2 Security Policy of Certificate #4282. At the time of writing, the last version validated was OpenSSL 3.0.9. The module from that version will continue to be packaged with newer versions of OpenSSL until a newer version of the OpenSSL 3.0 FIPS 140-2 provider is validated. At that time, the newer validated version of the module will be packaged.

Note:

IBM webMethods does not provide newer OpenSSL versions with a FIPS 140-3 provider. So far the announced end of maintenance for all newer versions of OpenSSL will be reached before the end of maintenance for OpenSSL 3.0.

To use the FIPS provider, you must complete the installation with a manual step. When you install SSX, the SSL package is installed along with SSX. The SSL package consists of OpenSSL. To complete the installation, you must run the provided script:

• Windows:

  C:\SoftwareAG\common\security\openssl\extras\prepareFIPS.bat

• UNIX:

  /opt/softwareag/common/security/openssl/extras/prepareFIPS.sh

Review the script and follow the instructions that are printed when the scripts run.

SSX does not load a specific OpenSSL configuration. Instead, it uses the configuration provided by the OPENSSL_CONF environment variable. The minimalist configuration shipped as openssl/extras/openssl-fips.cnf within the SSL package ensures that only the FIPS and the base provider of OpenSSL are used, thus operating the software in an approved manner.

Note:

Simply sourcing the tlsenv script does not make the FIPS provider operational. Instead, you must set the variables that are mentioned by the script before the tlsenv script is run.

For more information, see the OpenSSL FIPS 140-2 Security Policy of Certificate #4282. At the time of writing, this certificate can be viewed at https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4282.

The OpenSSL project publishes detailed information about their implementation and how to use it compliantly with the manual page fips_module. The OpenSSL 3.0 version of this page can be found at https://docs.openssl.org/3.0/man7/fips_module/.