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

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

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

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

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

2.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, [email protected]
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, [email protected]</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, [email protected]"</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.

2.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 DDS 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.

2.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 DDS builtin logging system, the Builtin Secure Logging Topic as defined in the DDS Security specification, or both.

Before release 6.1.0 of Connext DDS, enabling the logging distribution was done by setting the logging.distribute.enable property to TRUE. In Connext DDS 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 DDS builtin logging system to use a log file or an output device (see Controlling Messages from Connext DDS, in the RTI Connext DDS Core Libraries User’s Manual).

Note that for better performance when log messages are generated frequently, the Connext DDS 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.

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

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

2.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 DomainParticipantsremove_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.

2.2.4.11. Improvements in Discovery Performance

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