.. include:: /../getting_started/vars.rst .. _section-Product-Security-610: RTI Security Plugins ******************** The following issues affect backward compatibility in *RTI Security Plugins* when migrating from Release 6.0.1 to Release 6.1.0. OpenSSL upgrade =============== Release 6.1.0 of *Security Plugins* uses OpenSSL® 1.1.1k. (Release 6.0.0 used OpenSSL 1.0.2o, and Release 6.0.1 used 1.1.1d.) *Security Plugins* 6.1.0 is API-compatible with OpenSSL versions 1.1.0 through 1.1.1k, not with versions earlier than OpenSSL 1.1.0. If you need *Security Plugins* 6.1.0 to run against older versions of OpenSSL, please contact support@rti.com. For instructions on installing the latest version of OpenSSL, see the :link_connext_sec_ig_610:`RTI Security Plugins Installation Guide 6.1.0 <>`. .. BUILD-2667 Target OpenSSL bundles now distributed as .rtipkg files ======================================================= Target OpenSSL bundles are now distributed as ``.rtipkg`` files. (Previously, they were distributed as ``.zip`` files.) Once installed, the OpenSSL files are available in ``/third_party``. For instructions, see the :link_connext_sec_ig_610:`RTI Security Plugins Installation Guide 6.1.0 <>`. .. INSTALL-473 .. _section-OpenSSL-Namechange: Changed OpenSSL static library names ==================================== The OpenSSL static library names no longer have a "z" suffix. ``libcryptoz`` has been renamed to ``libcrypto``, and ``libsslz`` has been renamed to ``libssl``. When including the static libraries in a makefile, we recommend including the whole path to the OpenSSL static libraries in order to avoid confusion with the dynamic libraries. For example, if your makefile previously had this: .. code-block:: text gcc -o myApp myApp.o -L$RTI_OPENSSLHOME/$ARCH/release/lib -lsslz -lcryptoz you should change it to this: .. code-block:: text gcc -o myApp myApp.o $RTI_OPENSSLHOME/$ARCH/release/lib/libssl.a $RTI_OPENSSLHOME/$ARCH/release/lib/libcrypto.a .. BUILD-2848 pattern partitions from previous releases may no longer work ========================================================================= Imagine an ```` pattern partition that looked like this in 6.0.1: .. code-block:: xml :emphasize-lines: 6 ... ... P1* In 6.0.1 and earlier, you could successfully create a |DR| that subscribed to ``P12*``. In 6.1.0, however, the |DR| will not be created because a pattern partition in the QoS must have an exact match in an allow rule in order to be allowed. This behavior is the result of the fix related to RTI Issue ID SEC-1228. In other words, in the Permissions Document, an ```` that has a pattern partition other than ``*`` (e.g., ``P1*``) incorrectly does not allow creation of an entity whose PartitionQosPolicy contains a regular expression pattern that is a subset of that ```` (e.g., ``P12*``). The reason for requiring an exact match is that evaluating if a pattern partition is strictly contained within a pattern-based ```` is complicated and may result in unintuitive behavior. The workaround is to change the ````'s pattern partition to exactly match the pattern partition in the QoS. For example, change ``P1*`` to ``P12*``: .. code-block:: xml :emphasize-lines: 6 ... ... P12* Note that a ```` is not affected by this limitation because the ```` is based on intersecting (not in containing) the evaluated partitions, and intersecting a pattern partition with a pattern-based ```` is not problematic. .. SEC-1242 No backward interoperability if Permissions Document subject name has commas in an attribute value ================================================================================================== Imagine an identity certificate configuration file that contains this: .. code-block:: text countryName=US commonName=The Common Name, TwitterHandle=@guy stateOrProvinceName=CA For |DP| creation to succeed in 6.0.1.21 and earlier, the ```` in the Permissions Document had to look like this: .. code-block:: xml C=US, ST=CA, CN=The Common Name, TwitterHandle=@guy For |DP| creation to succeed in 6.0.1.22 and higher and in 6.1.0 and higher, the ```` in the Permissions Document has to include quotes like this: .. code-block:: xml C=US, ST=CA, CN="The Common Name, TwitterHandle=@guy" This behavior is the result of the fix related to RTI Issue ID SEC-1439. In summary, if a |DP| has a ```` attribute value that has commas, it will not communicate with both a 6.0.1 |DP| and a 6.1.0 |DP| simultaneously. The only recourse is to remove the commas from the identity certificate configuration file and regenerate the identity certificate and Permissions Document. .. SEC-1439 authentication.crl_file property has been deprecated and replaced by authentication.crl, which requires a "file:" or "data:," prefix ==================================================================================================================================== You may now specify the Certificate Revocation List as document contents instead of a file name. The ``authentication.crl_file`` property has been deprecated and replaced by ``authentication.crl``, which requires a ``file:`` or ``data:,`` prefix. For details, see :link_connext_sec_authentication_props_um_610:`Properties for Configuring Authentication, in the Security Plugins User's Manual <>`. While the ``authentication.crl_file`` property still works, we recommend using ``authentication.crl`` instead, since future versions of |CONNEXT| will completely remove support of ``authentication.crl_file``. Setting both properties at the same time is not supported and will result in a failure during the *Security Plugins* initialization. .. SEC-940 .. _section-SEC-1161: |DP| creation will fail if either logging.distribute.enable or logging.log_file logging property is set ======================================================================================================= This release changes the way to configure which logging methods to use, by using a bitmask. The property ``logging.mode_mask`` now configures whether to use the |CONNEXT| builtin logging system, the Builtin Secure Logging Topic as defined in the DDS Security specification, or both. Before release 6.1.0 of |CONNEXT|, enabling the logging distribution was done by setting the ``logging.distribute.enable`` property to TRUE. In |CONNEXT| 6.1.0, this property has been removed, and setting it will result in a |DP| creation failure. The ``logging.mode_mask`` property is now the only way to enable a logging method. Before release 6.1.0, you could choose to redirect the security messages to a file by setting the ``logging.log_file`` property. In 6.1.0, this property has been removed, and using it will result in a |DP| creation failure. You can still redirect the security log to a file by enabling the BUILTIN flag in the ``logging.mode_mask`` property (enabled by default) and configuring the |CONNEXT| builtin logging system to use a log file or an output device (see :link_connext_messages_usersman_610:`Configuring Connext Logging, in the RTI Connext Core Libraries User's Manual <>`). Note that for better performance when log messages are generated frequently, the |CONNEXT| builtin logging system does not flush the log messages into a file immediately after they are generated. When using ``logging.log_file`` in previous releases, *Security Plugins* did flush immediately. If your application needs to retain the immediate flushing behavior, you may configure a custom logging device. .. SEC-1161 Deprecated logging.distribute properties ======================================== In previous releases, properties for configuring security logging distributed over DDS had a name starting with ``logging.distribute``. This release renames these properties to start with ``logging.security_topic``. Properties starting with ``logging.distribute`` are now deprecated and will be removed in a future release. (There is one exception: the ``logging.distribute.enable`` property has been completely removed in this release, as documented in :numref:`section-SEC-1161`.) If you set the same property twice using the two alternative forms (i.e., ``logging.distribute`` and ``logging.security_topic`` forms), the property starting with ``logging.security_topic`` will take effect, and the property starting with ``logging.distribute`` will be ignored. .. SEC-1215 Old logging.distribute.queue threshold property names no longer work ==================================================================== The names for the properties that configure the logging thread thresholds have been updated. .. list-table:: Logging Distribution Property Name Changes :name: LogDistProp :widths: 60 60 :header-rows: 1 * - Old Property Name - New Property Name * - logging.distribute.queue.thread.message_threshold - logging.security_topic.thread.message_threshold * - logging.distribute.queue.thread.plugin_method_threshold - logging.security_topic.thread.plugin_method_threshold * - logging.distribute.queue.thread.plugin_class_threshold - logging.security_topic.thread.plugin_class_threshold You must update the logging thread thresholds property names if you were using the names including ``queue`` in their name. Attempting to use the ``queue`` properties will now fail during property validation. No code changes are required if you were using the ones without ``queue`` in their name. However, we still recommend updating your properties to use the new properties names, which include ``security_topic`` instead of ``distribute``, because a future release may stop supporting the ``distribute`` version of the properties. For more information on these properties, see :link_connext_sec_logging_um_610:`Security Events and Logging, in the Security Plugins User's Manual <>`. .. SEC-1162 Changed default value of max_heartbeat_retries for secure volatile channel to UNLIMITED ======================================================================================= This release changes the default value for the Key Exchange (Secure Volatile) |DW|'s ``max_heartbeat_retries`` to **UNLIMITED**. While this should not have a noticiable impact in most scenarios, it could have an impact when relying upon calls to a |DP|'s ``remove_peer()`` or ``ignore_peer()`` API. In particular, it could provoke an unbounded memory growth on the Key Exchange (Secure Volatile) |DW|'s sample queue. If you are enabling the *Security Plugins* and relying on |DPs|' ``remove_peer()`` or ``ignore_peer()`` APIs, we recommend setting **DiscoveryConfigQosPolicy::secure_volatile_writer's** ``max_heartbeat_retries`` to a finite value such that ``fast_heartbeat_period`` * ``max_heartbeat_retries`` is at least equal to your configured **DiscoveryConfigQosPolicy's** ``participant_liveliness_lease_duration``. .. SEC-1138 .. _section-security-disc-perf: Improvements in Discovery Performance ===================================== The improvements described in :numref:`section-core-disc-perf` are even more pronounced in *Security Plugins*. The tests described in :numref:`section-core-disc-perf` have been performed with three different levels of security to see the changes in time and the differences between 6.1.0 and 6.0.1. The three levels of security are the following: * **Secure Libraries, No restrictions:** This scenario uses *Security Plugins*, but the governance file allows free interaction between the entities (no authentication). This is the governance file used in this case: .. literalinclude:: performanceTables/governanceFiles/governance_.xml :language: XML The results are displayed in the following table: .. csv-table:: :file: performanceTables/discoverySecurityNoAuth.csv :header-rows: 1 * **Secure Libraries, Secure Discovery:** This scenario enables security restrictions for discovery. This is the governance file used: .. literalinclude:: performanceTables/governanceFiles/governance_Discovery.xml :language: XML The results are displayed in the following table: .. csv-table:: :file: performanceTables/discoverySecuritySecureDiscovery.csv :header-rows: 1 * **Secure Libraries, Secure Discovery + Sign:** This scenario is similar to **Secure Discovery**, except it adds the ``rtps_protection_kind`` sign. This is the governance file used: .. literalinclude:: performanceTables/governanceFiles/governance_DiscoverySign.xml :language: XML The results are displayed in the following table: .. csv-table:: :file: performanceTables/discoverySecuritySecureDiscoverySigned.csv :header-rows: 1