3.3. Installing a Crypto Library

3.3.1. Installing OpenSSL

Note

If you have the free version of Connext (with “lm” in the package file name): OpenSSL 3.5.5 is installed automatically with the bundle. The following instructions are only for commercial installations.

RTI provides:

An OpenSSL host package, which enables OpenSSL for RTI’s applications such as RTI Admin Console, RTI Routing Service, rtiddsspy, etc.
An OpenSSL target package, which provides OpenSSL libraries that can be used to secure your applications.

3.3.1.1. Linux and macOS Systems

Make sure you’ve installed host and target Security Plugins packages as described in Security Plugins for OpenSSL.
Install an OpenSSL host package from RTI:

openssl-3.5.5-7.7.0-host-<host platform>.rtipkg

<host platform> is x64Linux for Linux systems, or darwin for macOS systems. Use the same process that you used for the .rtipkg files in the previous step.
Install an OpenSSL target package from RTI:

openssl-3.5.5-7.7.0-target-<target architecture>.rtipkg

Use the same process that you used for the .rtipkg files in the previous step.
Only on cross-compiled architectures:

The OpenSSL target package for cross-compiled architectures does not include the OpenSSL executable in the bin directory. If you require the OpenSSL executable (e.g., to generate identity certificates), you need to download and install the OpenSSL target package for an architecture that is not cross-compiled. Once the package is installed, add it to your PATH as described in the next step.
Include the resulting OpenSSL bin directory in your PATH. For example, assuming you want to use the “release” version of the OpenSSL 3.5.5 libraries (enter the command all on one line):
```
export PATH=
<NDDSHOME>/third_party/openssl-3.5.5/<architecture>/release/bin:${PATH}
```
If you will be using the dynamic libraries, include the resulting OpenSSL lib directory in your LD_LIBRARY_PATH (on Linux systems) or DYLD_LIBRARY_PATH (on macOS systems).

For example, assuming you want to use the release version of the OpenSSL 3.5.5 libraries (enter the command all on one line):
```
export LD_LIBRARY_PATH=
<NDDSHOME>/third_party/openssl-3.5.5/<architecture>/release/lib:$LD_LIBRARY_PATH
```
To verify your OpenSSL installation, enter:
```
openssl version
```
You should see the version that you just installed:
```
OpenSSL 3.5.5
```
If you see a version that you didn’t expect, your PATH may be pointing with a higher precedence to a different version of OpenSSL. You may need to place the version you just installed first or earlier in your PATH.

Note: When running the openssl version command, you may run into this OpenSSL warning:
```
WARNING: can't open config file: [default openssl built-in path]/openssl.cnf
```
To resolve this issue, set the environment variable OPENSSL_CONF to the path to the openssl.cnf file you are using. For example (enter this all on one line):
```
export OPENSSL_CONF=
<NDDSHOME>/third_party/openssl-3.5.5/<architecture>/release/ssl/openssl.cnf
```

3.3.1.2. Windows Systems

Make sure you’ve installed host and target Security Plugins packages as described in Security Plugins for OpenSSL.
Install an OpenSSL host package from RTI: openssl-3.5.5-7.7.0-host-x64Win64.rtipkg.

Use the same process that you used for the .rtipkg files in the previous step.
Install an OpenSSL target package from RTI: openssl-3.5.5-7.7.0-target-<target architecture>.rtipkg.
Add the resulting OpenSSL bin directory to your Path environment variable. For example (enter the command all on one line):
To verify your installation, enter:
```
openssl version
```
You should see this response:
```
OpenSSL 3.5.5
```

If you see an unexpected version, your PATH may be pointing with a higher precedence to a different version of OpenSSL. You may need to place the version you installed to be first or earlier in your PATH.

3.3.2. Building wolfSSL

wolfSSL is only for use with specific architectures. See the RTI Connext Core Libraries Platform Notes to determine compatibility with your target architecture.

RTI does not distribute wolfSSL. You should get a commercial version of wolfSSL. See the RTI Security Plugins Release Notes for compatible versions.

In a location of your choice, build wolfSSL for your target architecture. Read the chapter on “Building” in the wolfSSL User Manual.

You must build wolfSSL with the following flags:

–enable-smime
–enable-opensslall
–enable-opensslextra
–enable-crl
–enable-certgen
–enable-des3
–enable-reproducible-build
–enable-certext
–enable-aesgcm-stream
-DWOLFSSL_PSS_SALT_LEN_DISCOVER
–enable-static (if building statically)
–enable-harden

This flag is specific to non-ARM Linux systems:

–enable-aesni

These flags are specific to QNX systems:

–enable-smallstack
-DWOLFSSL_HAVE_MIN
-DWOLFSSL_HAVE_MAX

The flags that start with a double dash (–) are options that you must pass to the ./configure command. You must also pass to this command the options that start with the -D prefix. These options must be part of the CFLAGS space-separated list. For example:

CFLAGS="-DWOLFSSL_PSS_SALT_LEN_DISCOVER"

Alternatively, you can export CFLAGS as an environment variable.

Note

Compiling wolfSSL using different flags is not supported. You must build wolfSSL with the flags presented in this section. Otherwise, your application may not work correctly, or it may even crash.

You will need the resulting installation directory when installing wolfSSL in the next section, Installing wolfSSL.

We refer to the wolfSSL installation directory as the folder created after building wolfSSL. This folder should contain bin/, include/, lib/, and share/ directories. You can configure it when building wolfSSL by adding the –prefix and –exec-prefix flags during the make install step.

3.3.2.1. Troubleshooting wolfSSL Build Issues

There is a linking issue that happens if the build machine doesn’t have enough main memory. It can occur when you compile wolfSSL with debug information. You may see the following error messages:

/bin/ld: final link failed: Memory exhausted
collect2: error: ld returned 1 exit status

Or these:

/bin/ld: BFD version 2.23.52.0.1-16.el7 20130226 internal error, aborting at merge.c line 877 in _bfd_merged_section_offset
/bin/ld: Please report this bug.
collect2: error: ld returned 1 exit status

In both cases, try to build wolfSSL on another machine, update the version of ld, or modify the build flags to reduce the amount of memory required for the debug symbols.

A suggestion to reduce the memory footprint is to pass C_EXTRA_FLAGS=”-g1 -feliminate-unused-debug-symbols -fdebug-types-section” to the ./configure command. This flag will use the minimal debug information level, remove debug information for symbols that are not actually used, and attempt to be more efficient so that the linker can remove duplicates.

You can find more information on bugs #16139 and #13379 of the binutils project.

3.3.3. Installing wolfSSL

After you’ve built wolfSSL for your target architecture (Building wolfSSL), you need to install it so that the Security Plugins can use it. Follow these steps:

Make sure you’ve installed the host and target Security Plugins packages as described in Security Plugins for wolfSSL.
In your <NDDSHOME>/third_party directory, create wolfssl-5.8.2/<target architecture>/release/. Copy your wolfSSL installation directory under the release/ folder.

(This assumes that you want to use the release version of the wolfSSL libraries. If you want to use the debug version of the libraries, create wolfssl-5.8.2/<target architecture>/debug/ instead.)

You will end up with:

<NDDSHOME>/third_party/wolfssl-5.8.2/<target architecture>/[release|debug]/.
(This step isn’t necessary for a QNX target, because the tools and services are supported natively on QNX systems.)

If your target architecture is on a Linux, macOS, or Windows system and you want to use RTI Tools and Infrastructure Services: you also need to build the wolfSSL library compiled for your host architecture. To do so, repeat the steps in Building wolfSSL and create a new wolfSSL installation directory with the library compiled for your host architecture.

Once you have wolfSSL compiled for your host architecture, copy the dynamic library files (\*.so) to the <NDDSHOME>/resource/app/lib/<host architecture>/ directory. The dynamic library files are in the lib/ directory of your wolfSSL installation directory.

<host architecture> is one of these: darwin, x64Linux, x64Win64.

You must copy both the release and debug versions, including symbolic links.
Include the wolfSSL bin/ directory in your PATH.

For example, assuming you want to use the “release” version of the wolfSSL libraries (enter the command all on one line):
```
export PATH=
<NDDSHOME>/third_party/wolfssl-5.8.2/<architecture>/release/bin:${PATH}
```
If you will be using the dynamic libraries, include the wolfSSL lib/ directory in your library search path (LD_LIBRARY_PATH on Linux systems, DYLD_LIBRARY_PATH on macOS systems, or Path on Windows systems). For example, assuming you want to use the release version of the wolfSSL libraries (enter the command all on one line):
```
export LD_LIBRARY_PATH=
<NDDSHOME>/third_party/wolfssl-5.8.2/<architecture>/release/lib:$LD_LIBRARY_PATH
```
where <architecture> is your target architecture.
To verify your installation, enter:
```
wolfssl-config --version
```
You should see this response:
```
5.8.2
```
If you see an unexpected version, your PATH may be pointing with a higher precedence to a different version of wolfSSL. You may need to place the version you installed to be first or earlier in your PATH.