.. include:: ../vars.rst .. _chapter-openssl-engines: *************************** Support for OpenSSL Engines *************************** |OpenSSL_TM| 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 |SP| 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 :property:`openssl_engine` property defines the OpenSSL engine to be used. The value of this property for the first |DP| of the application will be the value for all other |DPs| in the application. Setting this property to a different value for subsequent |DPs| will not be effective and will be silently ignored. .. admonition:: Disclaimer :class: attention |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. Properties for Configuring OpenSSL Engines ========================================== :numref:`Properties for Configuring OpenSSL Engines` lists the properties that you can set to configure OpenSSL engines. These properties are configured through the |DP|'s PROPERTY QosPolicy (see :ref:`p2_core/elements_dds_secure_system:QoS Properties`). .. list-table:: Properties for Configuring OpenSSL Engines :name: Properties for Configuring OpenSSL Engines :widths: 40 60 :header-rows: 1 :class: longtable * - Property Name (prefix with :property:`com.rti.serv.secure.`) [#fPrefix]_ - Property Value Description * - :property:`openssl_engine` - :required:`Optional` One or more dynamic libraries, each implementing an OpenSSL engine. If this property value is not set, the |SP| will use native OpenSSL code with its default engine. Otherwise, you must set this value to the filename, excluding the :file:`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 |DP|. 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 |DP| of the application will be the value for all other |DPs| in the application. Setting this property to a different value for subsequent |DPs| will not be effective and will be silently ignored. :type:`String`. Default: not set, meaning that the OpenSSL builtin engine will be used. * - :property:`authentication.keyform` - :required:`Optional` The format of the private key specified by :property:`dds.sec.auth.private_key` (see :numref:`DDS Security Properties for Configuring Authentication`). The value of this property can be one of the following: * :value:`pem`: The OpenSSL engine will use the |PrivateKey| loaded by the |SP| with the :property:`dds.sec.auth.private_key` property. In this case, the |PrivateKey| is in PEM format and will be loaded as a file or a string, depending on its :value:`file:` or :value:`data:,` prefix. * :value:`engine`: The OpenSSL engine will be responsible for loading and/or using the |PrivateKey|. 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()``. :type:`Enum`: :value:`pem`, :value:`engine` Default: :value:`pem` .. [#fPrefix] Assuming you used :value:`com.rti.serv.secure` as the alias to load the plugin. If not, change the prefix to match the string used with :property:`com.rti.serv.load_plugins`, followed by the :value:`.` character. Advanced Concepts ================= Support for Engine Control Commands ----------------------------------- You may use properties to invoke a sequence of ``ENGINE_ctrl_cmd_string()`` function calls (see :link_openssl_docs:`Issuing control commands to an ENGINE from OpenSSL Documentation `). These properties are configured through the |DP|'s PROPERTY QosPolicy (see :link_um:`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 :value:`com.rti.serv.secure` as the alias to load the |SP| (see :numref:`Properties for Enabling Security`): .. code-block:: xml com.rti.serv.secure.openssl_engine [engineName] com.rti.serv.secure.openssl_engine.[engineName].[cmdName1] [arg1] com.rti.serv.secure.openssl_engine.[engineName].[cmdName2] [arg2] ... The above properties will result in the following code being called by the |SP| upon loading the engine: .. code-block:: c ENGINE_ctrl_cmd_string(engineIdentifiedBy[engineName], [cmdName1], [arg1], 0); ENGINE_ctrl_cmd_string(engineIdentifiedBy[engineName], [cmdName2], [arg2], 0);