3.2.3. RTI Security Plugins

3.2.3.1. Wire Compatibility

3.2.3.1.1. Permissions expiration enforcement

In 7.7.0, the Security Plugins enforce Permissions expiration at the time marked by the <notAfter> tag in the DomainParticipant’s Permissions Grant, for the entire DomainParticipant lifecycle. Therefore, DomainParticipants in 7.7.0 will stop communicating with remote DomainParticipants that have expired permissions. This release also introduces a way to renew the expiring permissions at runtime, allowing DomainParticipants to continue their operation in the system. Support for permissions renewal requires an additional, user-supplied mechanism for periodically supplying and renewing DomainParticipants Permissions Documents.

Pre-7.7.0 DomainParticipants verify Permissions validity only during local DomainParticipant creation and during remote DomainParticipant authentication. They do not offer a way to renew their Permissions and will be removed from the system once their permissions expire. If you require 7.7.0 DomainParticipants to interoperate with older Security Plugins versions, there are two workarounds for pre-7.7.0 DomainParticipants available:

• Restart the DomainParticipant with a new Permissions Document. With this option, your system must be tolerant to intrinsic, periodic DomainParticipant downtimes.

• Configure the Permissions Document with a <notAfter> tag value sufficiently in the future, so that it doesn’t expire during DomainParticipant runtime. This option incurs a security risk. The risk can be mitigated with short-lived identity certificates (available since release 7.2.0) or with OCSP (available since release 7.5.0).

Refer to Permissions Expiration in the RTI Security Plugins User’s Manual for more details.

3.2.3.1.2. GUID consistency enforcement

Release 7.7.0 of the Security Plugins introduces an Access Control mechanism to enforce consistency between SampleInfo::publication_handle, SampleInfo::original_publication_virtual_guid, SampleInfo::source_guid, DDS_PublicationBuiltinTopicData::virtual_guid, and DDS_SubscriptionBuiltinTopicData::virtual_guid. If your Permissions Document grant has <default>DENY</default>, then this mechanism is enabled by default. If you are using Collaborative DataWriters, Persistence Service, Routing Service, or other Infrastructure Services built on top of Routing Service, or write_w_params with WriteParams::identity.writer_guid or WriteParams::source_guid, then you may experience communication failure along with this error:

does not match DDS_SampleInfo::publication_handle

In that case, you may need to adjust the proxy permissions in your Permissions Document. Alternatively, you may set <enforce_proxy_permissions>false</enforce_proxy_permissions> in your Governance Document <domain_rule>, but this option is generally discouraged and should only be used when integrating with legacy systems where domain insider integrity and availability threats are not a concern.

Refer to DataWriters Acting as a Proxy for other DataWriters in the RTI Security Plugins User’s Manual for more details.

3.2.3.1.3. Interoperability with DomainParticipants that have a domain tag or partitions

In 7.7.0, the Builtin Security Plugins consider the DomainParticipant’s domain tag and partitions when deciding whether an allow or deny rule matches. If an allow rule doesn’t specify partitions, it will only match against the default empty string partition (“”). If a deny rule doesn’t specify partitions, it will match against any partition (including the default empty string partition). The same behavior applies to domain tags. Your Permissions Document must be explicit when allowing partitions and domain tags; the implicit behavior is to deny access as much as possible.

For example, consider the following rule in a Permissions Document:

<allow_rule>
    <domains>
        <id>0</id>
    </domains>
</allow_rule>
<default>DENY</default>

In previous releases, a DomainParticipant with a subject name matching the grant of this rule would be allowed to publish or subscribe in domain 0, regardless of its domain tag or partitions. Starting in this release, the same DomainParticipant will be denied if it has a domain tag or partition different from the empty string.

As a result, if your system has a combination of both pre-7.3.1 and post-7.3.1 DomainParticipants, you must update your Permissions Document for all of them. Your system should account for the new behavior and include the <partitions> and <tag> or <tag_expression> elements as necessary. These tags must include the must_interpret="false" attribute and value so versions of the Builtin Security Plugins that do not support them don’t fail to parse the Permissions Document.

For example, this change in the previous rule will allow the DomainParticipant with a Migration Guide tag and Permissions Document update partition.

<allow_rule>
    <domains>
        <id>0</id>
        <tag must_interpret="false">Migration Guide</tag>
    </domains>
    <partitions must_interpret="false">
        <partition>Permissions Document update</partition>
    </partitions>
</allow_rule>
<default>DENY</default>

Note that this workaround only works for releases of the Builtin Security Plugins that support the must_interpret attribute (7.0.0 or later). Connext added support for DomainParticipant partitions in the 7.0.0 release and for domain tags in the 6.0.0 release. Communication with secure 6.x DomainParticipants is not possible if they are configured with a domain tag.

3.2.3.2. Changes to Building an Application

3.2.3.2.1. OpenSSL 3 upgrade

Between release 7.3.0 and 7.3.1, the OpenSSL® version changed from 3.0.12 to 3.5.1. See OpenSSL 3 upgrade for user actions related to that upgrade. Release 7.7.0 uses version 3.5.5. (That upgrade, from 3.5.1 to 3.5.5, occurred between 7.6.0 and 7.7.0.) No user action is required for the upgrade from 3.5.1 to 3.5.5. Just note that Security Plugins 7.7.0 has only been tested by RTI using OpenSSL 3.5.5. If you need Security Plugins 7.7.0 to run against older versions of OpenSSL, please contact support@rti.com.

3.2.3.2.2. wolfSSL 5 upgrade

Release 7.7.0 of the Security Plugins upgrades the version of wolfSSL® from 5.5.1 to 5.8.2. The Security Plugins bundles have been renamed from 5.5 (e.g., rti_security_plugins-7.6.0-target-wolfssl-5.5-<architecture>.rtipkg) to 5.8 (e.g., rti_security_plugins-7.7.0-target-wolfssl-5.8-<architecture>.rtipkg). These bundles are API-compatible with wolfSSL version 5.8.2, not with versions earlier than wolfSSL version 5.8.2. Note that Security Plugins 7.7.0 has only been tested by RTI using wolfSSL version 5.8.2. If you need Security Plugins 7.7.0 to run against older versions of wolfSSL, please contact support@rti.com.

Note

The rti_security_plugins-<version>-host-wolfssl-<version>-<host platform>.rtipkg packages are available on demand only. If you do not see them in the Customer Portal, contact support@rti.com.

wolfSSL 5.8.2 requires your X.509 Identity CA certificate (root and intermediates) to have the basicConstraints = CA:true extension. Refer to The basicConstraints X.509 v3 extension in the RTI Security Plugins User’s Manual for more details. If you are migrating from wolfSSL 5.5.1 to 5.8.2, make sure your Identity CA certificates have this extension. In the .cnf configuration file, verify that the x509_extensions = v3_ca line is not commented out.

3.2.3.2.3. Linking against the Security Plugins for wolfSSL

Release 7.7.0 of the Security Plugins no longer ships the Security Plugins for wolfSSL libraries in the <NDDSHOME>/lib/<architecture>/ directory (where <NDDSHOME> refers to the root directory of your RTI Connext installation). The libraries (both Lightweight Builtin Security Plugins and Builtin Security Plugins) are now located in the <NDDSHOME>/lib/<architecture>/wolfssl-5.8/ directory.

As a consequence, if you are linking dynamically against the Security Plugins for wolfSSL, you need to run your applications with the updated library path that includes <NDDSHOME>/lib/<architecture>/wolfssl-5.8/. For example, on Linux, you can set the LD_LIBRARY_PATH environment variable to:

export LD_LIBRARY_PATH=\
$NDDSHOME/lib/x64Linux4gcc8.5.0/wolfssl-5.8:\
$NDDSHOME/lib/x64Linux4gcc8.5.0:\
$NDDSHOME/third_party/wolfssl-5.8.2/x64Linux4gcc8.5.0/debug/lib

Make sure to add the path to the Security Plugins for wolfSSL before the path to the general libraries. Otherwise, your application may attempt to load the default Security Plugins for OpenSSL library.

If you are linking statically against the Security Plugins for wolfSSL, you need to indicate the new library path to the linker in your build system. You can find an example makefile in the example secure hello world applications provided in the rti_workspace directory.

3.2.3.3. Configuration Changes

3.2.3.3.1. Changes to the default cryptographic algorithms

In this release, the Security Plugins changed the list of default supported algorithms to be used if you don’t specify an algorithm rule in the <allowed_security_algorithms> tag of the Governance Document. The default supported algorithms include only the algorithms listed in the OMG DDS Security 1.2 specification. RTI-specific and experimental algorithms are no longer included in the supported algorithm list by default and need to be explicitly listed in the Governance Document. If your system uses such algorithms, you must update your Governance Document to continue using them. See Supported Cryptographic Algorithms in the Security Plugins User’s Manual for more information.

3.2.3.3.2. Plugin-specific access_control.permissions_file property no longer available

This release of the Security Plugins removes the plugin-specific access_control.permissions_file property. You must now use the dds.sec.access.permissions property according to the DDS Security specification. See Properties for Configuring Access Control in the Security Plugins User’s Manual for more information.

3.2.3.3.3. Renaming of the advance notice properties

This release of the Security Plugins renames the dds.participant.trust_plugins.certificate_expiration_advance_notice_duration.sec property to dds.participant.trust_plugins.expiration_advance_notice_duration.sec and the dds.participant.trust_plugins.certificate_expiration_advance_notice_reminder_period.sec property to dds.participant.trust_plugins.expiration_advance_notice_reminder_period.sec. The old names are not supported any more. In this release, these properties affect not only the Identity Certificate, but also the Permissions Document. For more information, see the Security Plugins User’s Manual.

3.2.3.3.4. Removal of cryptography.max_receiver_specific_macs as a requirement for RTPS origin authentication

This release of the Security Plugins removes the cryptography.max_receiver_specific_macs property as a requirement for setting the Governance tag <rtps_protection_kind> to a value that ends in _WITH_ORIGIN_AUTHENTICATION. If you are setting max_receiver_specific_macs only because it was a requirement and not because you are trying to reduce the performance impact of origin authentication, then you are encouraged to remove this setting in favor of the new default value of AUTO.

3.2.3.4. Key Revision Changes

3.2.3.4.1. Key Revisions are enabled by default

This release introduces the enable_key_revision rule of the Governance Document to control whether key revisions are enabled. This release also enables key revisions by default, meaning the default value of the enable_key_revision Governance Rule is true.

This change affects interoperability with previous releases. If you want to interoperate with older Connext applications that are not using Key Revisions, then you must explicitly disable Key Revisions in your Governance Document, by setting the enable_key_revision Domain Rule to false. Here is an example:

<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>
        <enable_key_revision>false</enable_key_revision> <!-- Add this line here. -->
        <discovery_protection_kind>ENCRYPT</discovery_protection_kind>

Then, you must re-sign the Governance Document with the Permissions Certificate Authority.

If you need to use the same Governance Document in both 7.7.0 and a release older than 7.5.0, then you may add must_interpret="false" as described in Keeping Governance and Permissions Compatibility Across Different Security Plugins Versions in the RTI Security Plugins User’s Manual:

<enable_key_revision must_interpret="false">false</enable_key_revision>

3.2.3.4.2. Key Revision Max History Depth must be at least 8

If you are currently setting the dds.participant.trust_plugins.key_revision_max_history_depth property value to 7, then starting in this release you must now increase this value to at least 8, since 8 is the new minimum value if you are not setting the property value to 0.

Note that this release introduces the enable_key_revision rule of the Governance Document. This rule must be consistent with the value of the dds.participant.trust_plugins.key_revision_max_history_depth property. If the property has a non-zero value, then the enable_key_revision rule of the Governance Document must be set to true. If the property has a value of 0, then enable_key_revision must be set to false.

3.2.3.5. API Changes

3.2.3.5.1. Changes related to the advance notice status APIs

The on_invalid_local_identity_status_advance_notice DomainParticipant callback has been renamed to on_invalid_local_status_advance_notice. In addition to Identity Certificates, this callback can now handle Permissions Documents as well.

As part of these changes, the callback type and signature have changed. The type is now InvalidLocalAdvanceNoticeStatusCallback. The signature changes because the InvalidLocalIdentityAdvanceNoticeStatus output data structure has been renamed to InvalidLocalAdvanceNoticeStatus. Two additional fields have been added to this structure: an expiration_code and an expiration_message. They both convey the reason for the security artifact to become invalid. The expiration_message is a descriptive string message and the expiration_code is an integer that can be used programmatically. For more information about the existing expiration codes, see the section about the on_invalid_local_status_advance_notice API in the Security Plugins User Manual.

The status kind that you need to pass as the status mask when setting the DomainParticipant listener has also been renamed. Instead of DDS_INVALID_LOCAL_IDENTITY_ADVANCE_NOTICE_STATUS, you must now use DDS_INVALID_LOCAL_ADVANCE_NOTICE_STATUS.

3.2.3.6. Logging Changes

3.2.3.6.1. New logging topic for the Lightweight Security Plugins library

Release 7.7.0 of the Lightweight Builtin Security Plugins introduces a new logging topic, DDS:Security:PSK:LogTopic. Previously, the Lightweight Builtin Security Plugins logged messages to the same topic as the Builtin Security Plugins, DDS:Security:LogTopicV2. However, according to the DDS Security Specification, this topic must enable metadata and data protection. Therefore, the Lightweight Builtin Security Plugins should not log to it.

Applications using the Lightweight Builtin Security Plugins and subscribing to the DDS:Security:LogTopicV2 topic will no longer receive log messages from the Lightweight Builtin Security Plugins. Instead, they should subscribe to the new DDS:Security:PSK:LogTopic.

3.2.3.7. Deprecation and Removal Changes

3.2.3.7.1. HMAC-Only mode removed from the Builtin Security Plugins

HMAC-Only mode and the features based upon it are removed from the Builtin Security Plugins in 7.7.0. Use the Lightweight Builtin Security Plugins instead. Legacy HMAC-Only mode systems can communicate with modern Pre-Shared Key protected systems by using a 7.3.0 or 7.3.1 Routing Service instance (because these releases support both modes).

As a result of the removal, the plugin-specific properties for configuring HMAC-Only mode are also removed: hmac_only.enabled, hmac_only.cryptography.key, and hmac_only.cryptography.max_blocks_per_session are no longer available. This release also removes the authentication.participant_discovery_protection_key and cryptography.rtps_protection_key properties for setting static HMAC keys to compute signatures with.

3.2.3.7.2. Use new property in place of authentication.key_establishment_algorithm

Release 7.7.0 of the Security Plugins contains the new dds.sec.auth.key_establishment_algorithm property, as defined in the OMG DDS Security 1.2 specification. This new property deprecates the authentication.key_establishment_algorithm plugin-specific one. Both properties configure the algorithm used to establish a shared secret during authentication. Their behavior and accepted values are the same. You should use the new standard property instead of the deprecated plugin-specific one, because the deprecated one may be removed in a future release.

3.2.3.7.3. Deprecation of authentication.crl and removal of authentication.crl_file

This release of the Security Plugins deprecates the plugin-specific authentication.crl property, and removes the plugin-specific authentication.crl_file property. Instead, you should set the dds.sec.auth.crl property defined in the OMG ‘DDS Security’ specification. The behavior and configuration of the deprecated and the new property is the same: they are both optional properties that configure the Certificate Revocation List (CRL) used by the Builtin Security Plugins.

3.2.3.7.4. Removal of the deprecated SecurityPluginSuite_create entry point

Release 7.7.0 of the Security Plugins removes the SecurityPluginSuite_create entry point. If you had set the com.rti.serv.secure.create_function or com.rti.serv.secure.create_function_ptr property with the deprecated entry point, you must update it to use RTI_Security_PluginSuite_create (function name or address, depending on property and linking mode). Refer to Building and Running Security Plugins-Based Applications in the RTI Security Plugins User’s Manual for more details.

3.2.3.7.5. Removal of the AES-192-GCM symmetric cipher algorithm

Following the deprecation of AES-192-GCM in release 7.3.0, release 7.7.0 now completely removes this cryptographic algorithm from the list of available symmetric cipher algorithms. If you are still using AES-192-GCM in your system, please transition to AES-256-GCM or AES-128-GCM.

For more information about symmetric cipher algorithms, see Algorithms Involved in Protecting Secure Entities Traffic in the RTI Security Plugins User’s Manual.

3.2.3.7.6. Deprecation of authentication.alternative_ca_files and access_control.alternative_permissions_authority_files

This release of the Security Plugins deprecates the plugin-specific authentication.alternative_ca_files and authentication.alternative_permissions_authority_files properties. Instead, you should set the (plugin-specific) authentication.alternative_identity_cas and access_control.alternative_permissions_cas properties. The new properties allow you to specify the alternative CA certificates in PEM format, in a way similar to how you can already configure the Identity Certificate and CRL documents. The property value should be either a file name (file: prefix) or some data contents (data: prefix). The file prefix is assumed if no prefix is specified. You can indicate multiple alternative CA certificates by separating them with newline characters. Refer to “Note regarding document format” in the RTI Security Plugins User’s Manual for more details.

3.2.3.7.7. Renaming of the property that enables experimental algorithms

This release of the Security Plugins renames the com.rti.serv.secure.authentication.enable_custom_algorithms property to com.rti.serv.secure.authentication.enable_experimental_algorithms. The Security Plugins no longer support the old name. The new name is clearer, conveying the property’s purpose more effectively. This property enables algorithms that the Security Plugins considers experimental and not fully supported, such as EdDSA. It is not related to custom algorithms (those algorithms that are implementation-specific and not defined by the OMG ‘DDS Security’ specification), such as AES-192.

3.2.3.8. SDK Changes

This release of the Security Plugins introduces changes in the Service Plugin Interface (SPI). If you have implemented custom plugins, you may need to update them for compatibility. See the Service Plugin Interface (SPI) Notes section of the Security Plugins SDK documentation for more information. In your Connext installation, find the documentation inside the security-buildsrc/doc folder.