.. _section_installing-a-crypto-library:

Installing a Crypto Library
---------------------------

.. _section_crypto-installing-openssl:

Installing OpenSSL
~~~~~~~~~~~~~~~~~~~
.. note::

   If you have the free version of *Connext* (with "lm" in the
   package file name): OpenSSL |OPENSSLVERSION| 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.

Linux and macOS Systems
^^^^^^^^^^^^^^^^^^^^^^^

#. Make sure you've installed host and target *Security Plugins*
   packages as described in 
   :ref:`section_installing-a-commercial-version-for-OpenSSL`.

#. Install an OpenSSL *host* package from RTI:

   openssl-|OPENSSLVERSION|-|VERSION|-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-|OPENSSLVERSION|-|VERSION|-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):

   .. code-block:: shell

      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):

   .. code-block:: shell

      export LD_LIBRARY_PATH=
      <NDDSHOME>/third_party/openssl-3.5.5/<architecture>/release/lib:$LD_LIBRARY_PATH

#. To verify your OpenSSL installation, enter:

   .. code-block:: none

      openssl version

   You should see the version that you just installed:
   
   .. code-block:: none

      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:
   
   .. code-block:: none

      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):

   .. code-block:: none

      export OPENSSL_CONF=
      <NDDSHOME>/third_party/openssl-3.5.5/<architecture>/release/ssl/openssl.cnf


Windows Systems
^^^^^^^^^^^^^^^

#. Make sure you've installed host and target *Security Plugins*
   packages as described in 
   :ref:`section_installing-a-commercial-version-for-OpenSSL`.

#. Install an OpenSSL *host* package from RTI: 
   openssl-|OPENSSLVERSION|-|VERSION|-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-|OPENSSLVERSION|-|VERSION|-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:
  
   .. code-block:: none

      openssl version

   You should see this response:

   .. code-block:: none

      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.


.. _section_crypto-building-wolfssl:

Building wolfSSL
~~~~~~~~~~~~~~~~

wolfSSL is only for use with specific architectures.
See the `RTI Connext Core Libraries Platform Notes
<https://community.rti.com/static/documentation/connext-dds/7.7.0/doc/manuals/connext_dds_professional/platform_notes/index.htm>`__ 
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
<https://community.rti.com/static/documentation/connext-dds/7.7.0/doc/manuals/connext_dds_secure/release_notes/index.html>`__
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 <https://www.wolfssl.com/docs/wolfssl-manual/ch2/>`__.

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, :ref:`section_crypto-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.

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 <https://sourceware.org/bugzilla/show_bug.cgi?id=16139>`__ and
`#13379 <https://sourceware.org/bugzilla/show_bug.cgi?id=13379>`__ of
the **binutils** project.

.. _section_crypto-installing-wolfssl:

Installing wolfSSL
~~~~~~~~~~~~~~~~~~

After you've built wolfSSL for your target architecture 
(:ref:`section_crypto-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  
   :ref:`section_installing-a-commercial-version-for-wolfSSL`. 

#. In your **<NDDSHOME>/third_party** directory, create
   wolfssl-|WOLFSSLVERSION|/<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-|WOLFSSLVERSION|/<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 :ref:`section_crypto-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):

   .. code-block:: none

      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):

   .. code-block:: none

      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: 

   .. code-block:: none

      wolfssl-config --version      

   You should see this response:

   .. code-block:: none

      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.
