==================================================
RTI Connext DDS Hello_security Example Application
==================================================

Welcome to Connext!


Compiling this Example
======================
You must set the environment variable NDDSHOME to your Connext
installation directory.

To build this example on a Windows platform, open the appropriate solution
file for your version of Microsoft Visual Studio in the win32 directory. Select
from the configuration pull-down menu: Debug, Release, Debug OpenSSL 1,
Release OpenSSL 1, Debug DLL, or Release DLL, where "DLL" is for dynamic
linking. By default, the OpenSSL version 3 crypto libraries are used. To use
the OpenSSL version 1 crypto libraries, select one of the "OpenSSL 1"
configurations.

To build this example for a QNX platform, you must set the environment variables
QNX_HOST and QNX_TARGET. For example:

setenv QNX_BASE /opt/qnx660
setenv QNX_HOST ${QNX_BASE}/host/linux/x86
setenv QNX_TARGET ${QNX_BASE}/target/qnx6

To build this example on a Linux or macOS system, type the following in a command
shell:

  > make -f make/makefile_HelloWorld_<architecture>

This example is not supported on Android architectures.

If using Certicom Security Builder Engine, you cannot use the ecdsa-ecdh shared
secret algorithm together with static linking. If you want to use ecdsa-ecdh,
you must use dynamic linking. Aside from that, all combinations of
static/dynamic libraries and release/debug libraries are supported. The dynamic
libraries use the QoS profile for specifying the security plugin, and the
static libraries use code for that. Static/release is the default.
To use dynamic libraries, run:

 > make -f make/makefile_HelloWorld_<architecture> SHAREDLIB=1

To use debug libraries, run:

 > make -f make/makefile_HelloWorld_<architecture> DEBUG=1

By default, the OpenSSL version 3 crypto libraries are used. To use the OpenSSL
version 1 crypto libraries (which is required for RedHawk architectures), run:

> make -f make/makefile_HelloWorld_<architecture> OPENSSL1=1

or

> make -f make/makefile_HelloWorld_<architecture> CRYPTO_LIB=OPENSSL1

To use the wolfSSL crypto library, run:

> make -f make/makefile_HelloWorld_<architecture> WOLFSSL=1

or

> make -f make/makefile_HelloWorld_<architecture> CRYPTO_LIB=WOLFSSL

You can use the wolfSSL crypto library if your Connext installation includes the
Security Plugins for wolfSSL.

Running this Example
====================

Linux and macOS systems
-----------------------
If you are using dynamic libraries, your LD_LIBRARY_PATH must include
$NDDSHOME/lib/<architecture>.

You must also include the path to your crypto libraries. If you are compiling
against the Security Plugins with OpenSSL, your LD_LIBRARY_PATH must include
$NDDSHOME/third_party/openssl-<version>/<architecture>/<release or debug>/lib
(location of libcrypto.so and libssl.so).
If you are compiling against the Security Plugins for use with wolfSSL, your
LD_LIBRARY_PATH must include $NDDSHOME/third_party/wolfssl-<version>/<architecture>/<release or debug>/lib
(location of libwolfssl.so).

If you are compiling for wolfSSL, your LD_LIBRARY_PATH must also include the
path to the Security Plugins for wolfSSL libraries (libnddssecurity.so). Add
$NDDSHOME/lib/<architecture>/wolfssl-<version>/ to your LD_LIBRARY_PATH. Make
sure to add this before the path to the general libraries
($NDDSHOME/lib/<architecture>). Otherwise, your application may attempt to load
the default Security Plugins for OpenSSL library.

If using Certicom Security Builder Engine for QNX, your LD_LIBRARY_PATH must include
$NDDSHOME/third_party/openssl-<version>/<architecture>/release/lib/:$CERTICOM_SBENGINEHOME/tools/sb/sb-$CERTICOMOS/lib/:$CERTICOM_SBENGINEHOME/lib/$CERTICOMOS.

To run this example, type the following commands in two different command shells (one command in each shell), either
on the same machine or on different machines:

  > objs/<architecture>/HelloWorld_subscriber
  > objs/<architecture>/HelloWorld_publisher

Windows systems
---------------
If using dynamic libraries, your PATH must include
%NDDSHOME%\lib\<architecture> and %NDDSHOME%\third_party\openssl-<version>\<architecture>\<release or debug>\bin
(location of the libcrypto and libssl DLLs).

To run this example, type the following commands in two different command shells (one command in each shell), either
on the same machine or on different machines:

  > objs\<architecture>\HelloWorld_subscriber.exe
  > objs\<architecture>\HelloWorld_publisher.exe

VxWorks Kernel Mode
-------------------
In case the application is linked dynamically (using SHAREDLIB=1 when compiling
the example with make), run these commands to load the Connext libraries:
  -> ld 1 < <NDDSHOME>/lib/<architecture>/libnddscore.so
  -> ld 1 < <NDDSHOME>/lib/<architecture>/libnddsc.so
  -> ld 1 < <NDDSHOME>/lib/<architecture>/libnddssecurity.so

Then load the publisher and subscriber modules:
  -> ld 1 < objs/<architecture>/HelloWorld_publisher.so
  -> ld 1 < objs/<architecture>/HelloWorld_subscriber.so

If you compiled the pubsub single DKM (using the "pubsub" argument when calling
make), load it instead:
  -> ld 1 < objs/<architecture>/HelloWorld_pubsub.so

Before running the publisher and subscriber, make sure that your current working
directory is in the hello_security folder. This directory must contain the
USER_QOS_PROFILES.xml. Otherwise, the publisher and subscriber won't be able to
read the example QoS profiles. Also, take into account that the
USER_QOS_PROFILES.xml relies on files under <rti_workspace>/examples/dds_security
being relative paths, so make sure the location is available in your target.
Spawn the corresponding kernel tasks with the following commands:
  -> taskSpawn "Publisher", 100, 0x01000000, <stack_size>, publisher_main, <domain_id>, <sample_count>, <profile>
  -> taskSpawn "Subscriber", 100, 0x01000000, <stack_size>, subscriber_main, <domain_id>, <sample_count>, <profile>

VxWorks RTP Mode
----------------
If the example was dynamically linked, the Connext libraries must be
available in the VxWorks target so LD_LIBRARY_PATH can point to it,
along with any system libraries from the VSB (such as libc.so.1). Before
running the example make sure you set the LD_LIBRARY_PATH:
  -> putenv "LD_LIBRARY_PATH=<path_to_ndds_libraries>;<path_to_system_libraries>"

Run the examples from the hello_security folder so the provided USER_QOS_PROFILES.xml
file is used. Also, take into account that the USER_QOS_PROFILES.xml relies on
files under <rti_workspace>/examples/dds_security being relative paths, so make
sure the location is available in your target.
  -> cmd rtp exec objs/<architecture>/HelloWorld_publisher.vxe -- <domain_id> <sample_count> <profile>
  -> cmd rtp exec objs/<architecture>/HelloWorld_subscriber.vxe -- <domain_id> <sample_count> <profile>

Accepted parameters
-------------------
This example is a modified version of an rtiddsgen generated HelloWorld
application.
It has been modified to use security profiles. The first two parameters are the
domain ID and sample count as in the hello_world example. The third parameter
changes the profile. Depending on the profile, you will run the example in one
of these three modes:

(1) Full security mode where DomainParticipants must authenticate to join the
system and their permissions are defined by the Permissions Documents. This is
the default mode, used when you don't specify a profile or you specify the "rsa"
profile or the "p384" profile. This example uses the "ecdsa"(*) algorithm suite
by default. The "rsa" profile uses the "rsa"(**) algorithm suite, and the "p384"
profile uses the "ecdsa secp384r1" algorithm suite.

(2) Pre-Shared mode where DomainParticipants use the Builtin Security Plugins
with Pre-Shared Key enabled and a Governance Document that enables
interoperability with the Lightweight Builtin Security Plugins. In this mode all
network traffic will be protected. Run this mode by setting the third parameter
(profile) to "preshared".

(3) OCSP mode, which enables DomainParticipants to validate their Identity
Certificates with an OCSP Responder. This mode uses the
"dds.sec.auth.ocsp_responder_uri" property to turn OCSP validation on. In this
mode, a compatible OCSP Responder is required to create and maintain the
DomainParticipant in the system. The OpenSSL-builtin OCSP Responder can
be invoked by running the included "run_ocsp_responder.py" Python script in
parallel to this example. Run this mode by setting the third parameter
(profile) to "ocsp".

* The "ecdsa" algorithm suite consists of ECDSA+P256+SHA256 (digital signature
  for identity trust chain and authentication) and ECDHE-CEUM+P256 (key establishment).
** The "rsa" algorithm suite consists of RSASSA-PKCS1-V1_5+2048+SHA256 (digital
   signature for identity trust chain), RSASSA-PSS-MGF1SHA256+2048+SHA256
   (digital signature for authentication) and ECDHE-CEUM+P256 (key
   establishment).
*** The "ecdsa secp384r1" algorithm suite consists of ECDSA+P384+SHA384 (digital
   signature for identity trust chain and authentication), and ECDHE-CEUM+P384
   (key establishment).

Troubleshooting this Example
============================
OpenSSL version:
  If you see the following error:

  Cryptography_encrypt:error:0607B083:lib(6):func(123):reason(131)

  you are likely linking against an older version of OpenSSL. You need version
  1.0.1c or later.

  For more information, please consult the "RTI Security Plugins Getting Started
  Guide".

OCSP:
  The OCSP responder is run accordingly to the configuration provided inside of
  "run_ocsp_responder.py" script. The value of the "dds.sec.auth.ocsp_responder_uri"
  in the profile must match the script configuration. If the configuration has to be
  changed or you want to run the responder on a different machine, you must update
  the address in all these places. Otherwise, creation of the DomainParticipant
  will fail with the "OCSP: the certificate is unknown" log message.

  By default the OCSP Responder works with the default (ecdsa01Peer01 and ecdsa01Peer02)
  identities. If you want to use different identities, you must add them to the OCSP
  Responder's index file - see the code in the script for details.
