12. Support for OpenSSL Engines

Note

This chapter does NOT apply if you are using OpenSSL® version 3.0.0 or above. The Security Plugins do not support the OpenSSL Provider API (see https://www.openssl.org/docs/man3.0/man7/provider.html).

OpenSSL engines allow you to define custom implementations for cryptographic operations. When you load an engine, OpenSSL will call the cryptographic functions defined by the engine instead of its default builtin functions. The Security Plugins support the option of using an OpenSSL engine, enabling you to use optimized cryptographic libraries, add support for custom hardware acceleration, etc.

Note

When set, the openssl_engine property defines the OpenSSL engine to be used. The value of this property for the first DomainParticipant of the application will be the value for all other DomainParticipants in the application. Setting this property to a different value for subsequent DomainParticipants will not be effective and will be silently ignored.

Disclaimer

Connext is only tested with the OpenSSL builtin engine. Modifying or Configuring OpenSSL engines may result in deviations from tested scenarios. Support for custom OpenSSL configurations may require a support contract with RTI Professional Services.

12.1. Properties for Configuring OpenSSL Engines

Table 12.1 lists the properties that you can set to configure OpenSSL engines. These properties are configured through the DomainParticipant’s PROPERTY QosPolicy (see QoS Properties).

Table 12.1 Properties for Configuring OpenSSL Engines
Property Name (prefix with `com.rti.serv.secure.`) 1	Property Value Description
`openssl_engine`	Optional One or more dynamic libraries, each implementing an OpenSSL engine. If this property value is not set, the Security Plugins will use native OpenSSL code with its default engine. Otherwise, you must set this value to the filename, excluding the `lib` prefix and the file extension, of the dynamic libraries that implement the engines. These libraries and the dependent libraries must be in at least one of the following: Your library search path (pointed to by the environment variable `LD_LIBRARY_PATH` on Linux systems, `DYLD_LIBRARY_PATH` on macOS systems, or `PATH` on Windows systems). The path pointed to by the environment variable `OPENSSL_ENGINES`. The standard OpenSSL engines directory (only if `OPENSSL_ENGINES` is not set) When specifying multiple libraries, they must be separated by a semicolon (e.g., `engine1;engine2`). Failure to load any of the engines will result in failure to create the DomainParticipant. Each engine may implement a different set of security functions. For example, one engine may implement certificate management, while another engine may implement cryptographic operations such as encryption, HMAC, and Diffie-Hellman. For any security functions needed by the security plugins but not implemented by any of the engines, their builtin OpenSSL implementations will be invoked. Note: The value of this property for the first DomainParticipant of the application will be the value for all other DomainParticipants in the application. Setting this property to a different value for subsequent DomainParticipants will not be effective and will be silently ignored. String. Default: not set, meaning that the OpenSSL builtin engine will be used.
`authentication.keyform`	Optional The format of the private key specified by `dds.sec.auth.private_key` (see Table 4.1). The value of this property can be one of the following: `pem`: The OpenSSL engine will use the Private Key loaded by the Security Plugins with the `dds.sec.auth.private_key` property. In this case, the Private Key is in PEM format and will be loaded as a file or a string, depending on its `file:` or `data:,` prefix. `engine`: The OpenSSL engine will be responsible for loading and/or using the Private Key. This is useful to interface keys located in a trusted storage, such as a crypto chip, or when the key is an array of bytes that the engine loads using the function `ENGINE_load_private_key()`. Enum: `pem`, `engine` Default: `pem`

1: Assuming you used com.rti.serv.secure as the alias to load the plugin. If not, change the prefix to match the string used with com.rti.serv.load_plugins, followed by the . character.

12.2. Advanced Concepts

12.2.1. Support for Engine Control Commands

You may use properties to invoke a sequence of ENGINE_ctrl_cmd_string() function calls (see Issuing control commands to an ENGINE from OpenSSL Documentation). These properties are configured through the DomainParticipant’s PROPERTY QosPolicy (see PROPERTY QosPolicy (DDS Extension) in the Core Libraries User’s Manual). The XML format of the properties in the QoS Profile is as follows, assuming that you used com.rti.serv.secure as the alias to load the Security Plugins (see Table 9.1):

<domain_participant_qos>
  <property>
    <value>
      <element>
        <name>com.rti.serv.secure.openssl_engine</name>
        <value>[engineName]</value>
      </element>
      <element>
        <name>com.rti.serv.secure.openssl_engine.[engineName].[cmdName1]</name>
        <value>[arg1]</value>
      </element>
      <element>
        <name>com.rti.serv.secure.openssl_engine.[engineName].[cmdName2]</name>
        <value>[arg2]</value>
      </element>
    ...
    </value>
  </property>
</domain_participant_qos>

The above properties will result in the following code being called by the Security Plugins upon loading the engine:

ENGINE_ctrl_cmd_string(engineIdentifiedBy[engineName], [cmdName1], [arg1], 0);
ENGINE_ctrl_cmd_string(engineIdentifiedBy[engineName], [cmdName2], [arg2], 0);