4.2.4. 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.

4.2.4.1. 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 RTI Security Plugins Installation Guide 6.1.0.

4.2.4.2. 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 <installation_folder>/third_party. For instructions, see the RTI Security Plugins Installation Guide 6.1.0.

4.2.4.3. 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:

gcc -o myApp myApp.o -L$RTI_OPENSSLHOME/$ARCH/release/lib -lsslz -lcryptoz

you should change it to this:

gcc -o myApp myApp.o $RTI_OPENSSLHOME/$ARCH/release/lib/libssl.a $RTI_OPENSSLHOME/$ARCH/release/lib/libcrypto.a

4.2.4.4. <allow_rule> pattern partitions from previous releases may no longer work

Imagine an <allow_rule> pattern partition that looked like this in 6.0.1:

         <allow_rule>
             ...
             <subscribe>
                 ...
                 <partitions>
                     <partition>P1*</partition>
                 </partitions>
             </subscribe>
         </allow_rule>

In 6.0.1 and earlier, you could successfully create a DataReader that subscribed to P12*. In 6.1.0, however, the DataReader 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 <allow_rule> 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 <allow_rule> (e.g., P12*).

The reason for requiring an exact match is that evaluating if a pattern partition is strictly contained within a pattern-based <allow_rule> is complicated and may result in unintuitive behavior.

The workaround is to change the <allow_rule>’s pattern partition to exactly match the pattern partition in the QoS. For example, change P1* to P12*:

         <allow_rule>
             ...
             <subscribe>
                 ...
                 <partitions>
                     <partition>P12*</partition>
                 </partitions>
             </subscribe>
         </allow_rule>

Note that a <deny_rule> is not affected by this limitation because the <deny_rule> is based on intersecting (not in containing) the evaluated partitions, and intersecting a pattern partition with a pattern-based <deny_rule> is not problematic.

4.2.4.5. No backward interoperability if Permissions Document subject name has commas in an attribute value

Imagine an identity certificate configuration file that contains this:

countryName=US
commonName=The Common Name, TwitterHandle=@guy
stateOrProvinceName=CA

For DomainParticipant creation to succeed in 6.0.1.21 and earlier, the <subject_name> in the Permissions Document had to look like this:

<subject_name>C=US, ST=CA, CN=The Common Name, TwitterHandle=@guy</subject_name>

For DomainParticipant creation to succeed in 6.0.1.22 and higher and in 6.1.0 and higher, the <subject_name> in the Permissions Document has to include quotes like this:

<subject_name>C=US, ST=CA, CN="The Common Name, TwitterHandle=@guy"</subject_name>

This behavior is the result of the fix related to RTI Issue ID SEC-1439. In summary, if a DomainParticipant has a <subject_name> attribute value that has commas, it will not communicate with both a 6.0.1 DomainParticipant and a 6.1.0 DomainParticipant simultaneously. The only recourse is to remove the commas from the identity certificate configuration file and regenerate the identity certificate and Permissions Document.

4.2.4.6. 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 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.

4.2.4.7. DomainParticipant 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 DomainParticipant 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 DomainParticipant 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 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.

4.2.4.8. 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 Section 4.2.4.7.) 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.

4.2.4.9. Old logging.distribute.queue threshold property names no longer work

The names for the properties that configure the logging thread thresholds have been updated.

Table 4.3 Logging Distribution Property Name Changes

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 Security Events and Logging, in the Security Plugins User’s Manual.

4.2.4.10. 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) DataWriter’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 DomainParticipant’s remove_peer() or ignore_peer() API. In particular, it could provoke an unbounded memory growth on the Key Exchange (Secure Volatile) DataWriter’s sample queue.

If you are enabling the Security Plugins and relying on DomainParticipants’ 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.

4.2.4.11. Improvements in Discovery Performance

The improvements described in Section 4.2.1.6 are even more pronounced in Security Plugins. The tests described in Section 4.2.1.6 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:

  <dds>
      <domain_access_rules>
        <domain_rule>
          <domains>
            <id_range>
              <min>0</min>
            </id_range>
          </domains>
          <allow_unauthenticated_participants>TRUE</allow_unauthenticated_participants>
          <enable_join_access_control>FALSE</enable_join_access_control>
          <discovery_protection_kind>NONE</discovery_protection_kind>
          <liveliness_protection_kind>NONE</liveliness_protection_kind>
          <rtps_protection_kind>NONE</rtps_protection_kind>
          <topic_access_rules>
            <topic_rule>
              <topic_expression>*</topic_expression>
              <enable_discovery_protection>FALSE</enable_discovery_protection>
              <enable_read_access_control>FALSE</enable_read_access_control>
              <enable_write_access_control>FALSE</enable_write_access_control>
              <metadata_protection_kind>NONE</metadata_protection_kind>
              <data_protection_kind>NONE</data_protection_kind>
            </topic_rule>
          </topic_access_rules>
        </domain_rule>
      </domain_access_rules>
  </dds>
  

The results are displayed in the following table:

Number of Endpoints	Discovery Time 6.0.1 (Seconds)	Discovery Time 6.1.0 (Seconds)	Diff (Seconds)
50	3.101	2.985	-0.12
75	3.766	3.518	-0.25
100	4.541	4.278	-0.26
125	10.544	8.262	-2.28
150	11.256	11.253	-0.00
175	14.872	13.509	-1.36
200	18.650	17.660	-0.99
225	21.932	19.420	-2.51
250	27.133	24.857	-2.28
275	35.549	28.274	-7.27
300	39.642	32.830	-6.81

• Secure Libraries, Secure Discovery: This scenario enables security restrictions for discovery. This is the governance file used:

  <dds>
      <domain_access_rules>
        <domain_rule>
          <domains>
            <id_range>
              <min>0</min>
            </id_range>
          </domains>
          <allow_unauthenticated_participants>FALSE</allow_unauthenticated_participants>
          <enable_join_access_control>TRUE</enable_join_access_control>
          <discovery_protection_kind>ENCRYPT</discovery_protection_kind>
          <liveliness_protection_kind>ENCRYPT</liveliness_protection_kind>
          <rtps_protection_kind>NONE</rtps_protection_kind>
          <topic_access_rules>
            <topic_rule>
              <topic_expression>*</topic_expression>
              <enable_discovery_protection>TRUE</enable_discovery_protection>
              <enable_read_access_control>TRUE</enable_read_access_control>
              <enable_write_access_control>TRUE</enable_write_access_control>
              <metadata_protection_kind>NONE</metadata_protection_kind>
              <data_protection_kind>NONE</data_protection_kind>
            </topic_rule>
          </topic_access_rules>
        </domain_rule>
      </domain_access_rules>
  </dds>
  

The results are displayed in the following table:

Number of Endpoints	Discovery Time 6.0.1 (Seconds)	Discovery Time 6.1.0 (Seconds)	Diff (Seconds)
50	5.071	3.116	-1.95
75	5.706	3.783	-1.92
100	9.122	6.617	-2.50
125	14.980	8.781	-6.20
150	23.689	10.644	-13.04
175	38.195	13.224	-24.97
200	56.997	17.201	-39.80
225	78.655	20.404	-58.25
250	102.576	26.537	-76.04
275	129.574	32.436	-97.14
300	160.880	37.668	-123.21

• 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:

  <dds>
      <domain_access_rules>
        <domain_rule>
          <domains>
            <id_range>
              <min>0</min>
            </id_range>
          </domains>
          <allow_unauthenticated_participants>FALSE</allow_unauthenticated_participants>
          <enable_join_access_control>TRUE</enable_join_access_control>
          <discovery_protection_kind>ENCRYPT</discovery_protection_kind>
          <liveliness_protection_kind>ENCRYPT</liveliness_protection_kind>
          <rtps_protection_kind>SIGN</rtps_protection_kind>
          <topic_access_rules>
            <topic_rule>
              <topic_expression>*</topic_expression>
              <enable_discovery_protection>TRUE</enable_discovery_protection>
              <enable_read_access_control>TRUE</enable_read_access_control>
              <enable_write_access_control>TRUE</enable_write_access_control>
              <metadata_protection_kind>NONE</metadata_protection_kind>
              <data_protection_kind>NONE</data_protection_kind>
            </topic_rule>
          </topic_access_rules>
        </domain_rule>
      </domain_access_rules>
  </dds>
  

The results are displayed in the following table:

Number of Endpoints	Discovery Time 6.0.1 (Seconds)	Discovery Time 6.1.0 (Seconds)	Diff (Seconds)
50	5.093	3.103	-1.99
75	7.085	3.830	-3.25
100	9.024	6.516	-2.51
125	15.788	8.587	-7.20
150	25.663	10.232	-15.43
175	39.401	13.281	-26.12
200	59.554	17.438	-42.12
225	80.577	21.887	-58.69
250	106.598	27.286	-79.31
275	135.227	33.087	-102.14
300	165.835	38.899	-126.94