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