2.2.3. RTI Security Plugins

2.2.3.1. Wire Compatibility

2.2.3.1.1. Permissions expiration enforcement

Starting in release 7.6.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.6.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.6.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.6.0 DomainParticipants to interoperate with older Security Plugins versions, there are two workarounds for pre-7.6.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.

2.2.3.2. Changes to Building an Application

2.2.3.2.1. OpenSSL 3 upgrade

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

If you use OpenSSL 3.5.1 to generate a Identity CA certificate, you may get the following error when you attempt to create a DomainParticipant:

X509_verify_cert returned 0 with error 79: invalid CA certificate

You may be using an X.509 v3 Identity CA that does not have basicConstraints = CA:true. Refer to The basicConstraints X.509 v3 extension in the RTI Security Plugins User’s Manual for more details. In the .cnf configuration file, make sure the x509_extensions = v3_ca line is not commented out.

Note

When running openssl ca or openssl x509, OpenSSL version 3.2.0 and above generate X.509 v3 (as opposed to v1) certificates by default.

The certificates used by the shipped examples (i.e., the certificates in the rti_workspace/7.6.0/examples/dds_security/cert directory) have been updated with X.509 v3 certificates.

OpenSSL 3.4.0 and above no longer support the X25519 and X448 key establishment algorithms in the FIPS provider. This change affects you if you are setting authentication.enable_experimental_algorithms to TRUE and using the FIPS provider.

2.2.3.3. Configuration Changes

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

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

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

2.2.3.3.4. Key Revisions are enabled by default

This release of the Security Plugins changes the default value of the enable_key_revision Governance Rule to 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.6.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>

2.2.3.3.5. Changes to Additional Authenticated Data

This release of the Security Plugins changes the cryptography.enable_additional_authenticated_data property type to an enum and adds the AUTO value, which is also the new default. Using AUTO, the Builtin Security Plugins will auto-enable Additional Authenticated Data for messages protected with a pre-shared key and for messages containing an RTPS Header Extension submessage. We are also removing the Builtin Security Plugins support for 0, 1, yes, and no values of this property. If you use any of these values, please move to a value from the set of AUTO, TRUE and FALSE. Beyond the values, related functionality changes should be transparent to the user and no interoperability breaks are expected.

Note that from this release Additional Authenticated Data is the only RTPS protection method available in the Lightweight Builtin Security Plugins; other methods are not supported. Therefore, cryptography.enable_additional_authenticated_data is not read by the Lightweight Builtin Security Plugins.

See Properties for Configuring Cryptography in the Security Plugins User’s Manual for more information about the property.

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

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

2.2.3.4. API Changes

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

2.2.3.4.2. New API to get Lightweight Builtin Security Plugins library version

In 7.5.0 and previous releases, you could get the version of both the Builtin Security Plugins library and the Lightweight Builtin Security Plugins library by calling the RTI_Security_get_library_version API. This approach lead to potential problems when linking against both libraries of the Security Plugins.

Starting in release 7.6.0, you must use the RTI_Security_get_library_version API to get the version of the Builtin Security Plugins library and the new RTI_SecurityLightweight_get_library_version API to get the version of the Lightweight Builtin Security Plugins library.

2.2.3.5. Security Plugins SDK

If you use the Security Plugins SDK, read the Security Plugins Interface (SPI) Notes section of its documentation. This documentation lists the changes introduced in each release to the interface between the Core Libraries and the Security Plugins.