2.2.2. Security Plugins

The following issues affect backward compatibility in the Security Plugins when migrating from release 6.1.1/6.1.2 to release 7.3.0.

Attention

For important information on new and deprecated features in 7.3.0, see the Security Plugins Release Notes.

2.2.2.1. Deprecations or Removals

Deprecated means that an item is still supported, but will be removed in a future release. Removed means that an item is discontinued or no longer supported. For complete information about deprecations and removals in the Security Plugins, see the Security Plugins Release Notes.

2.2.2.1.1. HMAC-Only Mode Deprecation

Starting in release 7.1.0, Builtin Security Plugins’s HMAC-Only mode is deprecated, and Lightweight Builtin Security Plugins should be used instead (see The Lightweight Builtin Security Plugins, in the RTI Security Plugins User’s Manual for details).

HMAC-Only mode remains functional in release 7.3.0 for integration with legacy systems only and should not be used in new deployments. For detailed information on Builtin Security Plugins’s HMAC-Only mode and its configuration, see RTPS-HMAC-Only Mode in the Security Plugins 6.1.2 documentation.

2.2.2.2. API Compatibility

2.2.2.2.1. Removed check_remote_topic

The DDS Security specification describes the Access Control plugin operation check_remote_topic. This function was implemented and invoked during endpoint discovery starting from Security Plugins 6.0.0. However, due to the absence of TopicBuiltinTopicData propagation, this invocation was ineffective. Starting in 7.2.0, the Security Plugins no longer call check_remote_topic. If you have a custom Access Control plugin that was relying on check_remote_topic to enforce access control rules, you should move your implementation of this function to both check_remote_datawriter and check_remote_datareader.

2.2.2.3. Changes to Building an Application

2.2.2.3.1. Link against both libssl and libcrypto

When building an application, you must now link against both libssl and libcrypto instead of only libcrypto. libssl has been added to the hello_security example makefiles and project files.

2.2.2.3.2. OpenSSL 3.0 upgrade and 1.1.1 removal

Release 7.3.0 of the Security Plugins uses OpenSSL® 3.0.12. The Security Plugins 7.3.0 include only one set of target bundles: rti_security_plugins-7.3.0-target-openssl-3.0-<architecture>.rtipkg. These bundles are API-compatible with OpenSSL versions 3.0.0 through 3.0.12, not with versions earlier than OpenSSL 3.0.0. Note that Security Plugins 7.3.0 has only been tested by RTI using OpenSSL 3.0.12. If you need Security Plugins 7.3.0 to run against older versions of OpenSSL, please contact support@rti.com.

The support of OpenSSL 1.1.1 has been removed, because it is end-of-life in September, 2023 (https://www.openssl.org/policies/releasestrat.html).

OpenSSL 3.0 has replaced the Engine API with the Provider API (see https://www.openssl.org/docs/man3.0/man7/migration_guide.html and search for the ‘Engines and “METHOD” APIs’ section). If you are using OpenSSL Engines, please note that the Security Plugins do not support providers (see https://www.openssl.org/docs/man3.0/man7/provider.html).

2.2.2.3.3. wolfSSL upgrade

Starting in release 7.1.0, the Security Plugins for wolfSSL are now based on wolfSSL version 5.5.1. The Security Plugins are API-compatible with wolfSSL version 5.5.1, not with versions earlier than wolfSSL 5.5.1. Note that the Security Plugins have only been tested by RTI using wolfSSL 5.5.1.

See the RTI Security Plugins Installation Guide.

2.2.2.3.4. wolfSSL build flags

You must build wolfSSL with two additional flags: --enable-certext and --enable-aesgcm-stream. RTI has added these two new options to the list of flags that you must build wolfSSL with. For more information, see Building wolfSSL, in the RTI Security Plugins Installation Guide.

2.2.2.3.5. Security Plugins SDK no longer uses cmocka

The tests included in the Security Plugins SDK no longer depend on the cmocka third-party library. Starting in 7.2.0, the SDK uses a test library shipped with Connext. There is no need to install the cmocka bundle.

2.2.2.3.6. Degradation of Security Plugins performance when switching from OpenSSL 1.1.1 to OpenSSL 3.0

The throughput of the Security Plugins for OpenSSL 3.0 is worse than that of the Security Plugins for OpenSSL 1.1.1. This degradation is not due to the Security Plugins; it is due to the OpenSSL cryptographic library. OpenSSL 3.0.12 is slower than OpenSSL 1.1.1n, at least for most algorithms that the Security Plugins support. The root cause is this OpenSSL issue: https://github.com/openssl/openssl/issues/20171. See Cryptographic Libraries, in the RTI Connext Performance Benchmarks, for more information.

2.2.2.4. Changes to Shipped Examples

2.2.2.4.1. Updated shipped examples to support different cryptographic libraries

Release 7.1.0 added support for compiling the security shipped examples (the C, C++ and Java hello_security examples, and the hello_banish C example) using any of the available cryptographic libraries (OpenSSL 3.0 or wolfSSL 5.5). Use the cryptographic library matching your installation of the Security Plugins. When linking statically, the default cryptographic library is now OpenSSL 3.0. (Release 6.1.2’s default was OpenSSL 1.1.1.)

The examples for Windows systems now include new build modes, so you can choose the cryptographic library. On Linux and macOS systems, you can indicate the cryptographic library as a parameter of the make command when compiling the example.

Please see the hello_security READ_ME.txt files for more details.

2.2.2.5. Configuration Changes

2.2.2.5.1. Removed support for DSA

After release 6.1.2, the support for Digital Signature Algorithm (DSA) was removed, following its deprecation in earlier releases.

The DSA is no longer accepted in the configuration and must be replaced with a different, supported algorithm. For the list of supported algorithms, see Cryptographic Algorithms Used for Digital Signatures in the RTI Security Plugins User’s Manual. For example, if you try to configure a DSA private key, you will get errors similar to the following:

RTI_Security_AuthenticationData_create:[...]"unknown private key type"}}

2.2.2.5.2. Enforcement of supported Digital Signature algorithms now supported in Connext

Release 7.0.0 added the ability to enforce restrictions on the cryptographic algorithms that are allowed in your system. As part of this feature, the Security Plugins check that DomainParticipants only use supported Digital Signature algorithms. You can find the list of supported algorithms in Cryptographic Algorithms Used for Digital Signatures in the RTI Security Plugins User’s Manual.

For example, the verification of the Identity Certificate Authority fails if the combination of signature algorithm and digest type is not compatible. The failure will happen when authenticating a remote DomainParticipant or when creating the local DomainParticipant. For example, the Security Plugins will log the following error when trying to load an Identity Certificate signed using ECDSA P256 with SHA-1 (because this combination is not supported):

RTI_Security_CertHelper_logIncompatibleDigest:!Found unknown digest type when sha256 digest type was expected: The Certificate Authority's public key is of type id-ecPublicKey and curve prime256v1
RTI_Security_CertHelper_verifyCert_errorIfCrlMissing:!invalid digest type
[...]
RTI_Security_Authentication_getCertificate:[..] "Identity verification failed. Make sure it was signed by the right authority."

In the following example, the remote DomainParticipant is using a Digital Signature algorithm the local DomainParticipant does not support:

RTI_Security_CertHelper_isDigestTypeAllowed:!unexpected key type. Valid key types are ECDSA (NIST P-256 or NIST P-384) and RSA
RTI_Security_CertHelper_verifyCert_errorIfCrlMissing:!invalid digest type
RTI_Security_CertHelper_verifyCert:[...]"X509_verify_cert returned -1 with error 0: ok

Valid configurations are RSA with SHA-256, ECDSA secp256r1 with SHA-256, and ECDSA secp384r1 with SHA-384. For more information, read Cryptographic Algorithms Used for Digital Signatures in the RTI Security Plugins User’s Manual.

Previous releases of the Security Plugins applied no restrictions with respect to the allowed Digital Signature algorithms, as long as the underlying cryptographic library (e.g., OpenSSL) supported them. As a result, applications using the Security Plugins relying on an unsupported configuration need to update the affected configuration artifacts (Identity Certificates, CA Certificates, Governance Document, and or Permissions Document).

2.2.2.5.3. Deprecated properties in favor of pre-shared key (PSK) protection

In 7.2.0, the following properties were deprecated:

com.rti.serv.secure.cryptography.rtps_protection_key
com.rti.serv.secure.authentication.participant_discovery_protection_key

Although the properties are still available for use, you should use pre-shared key (PSK) protection instead, specifically the com.rti.serv.secure.cryptography.rtps_protection_preshared_key property. The deprecated properties will be removed in a future release.

Note that the deprecation of these properties follows the deprecation of the HMAC-Only mode in the previous release. (See RTPS-HMAC-Only Mode, in the RTI Security Plugins User’s Manual.) These properties were based on the HMAC-Only mode. With enhancements to PSK made in 7.2.0 (adding PSK protection to RTI Cloud Discovery Service and RTI Real-Time WAN Transport), release 7.3.0 (which includes 7.2.0) offers a complete alternative to HMAC-Only protection. In 7.3.0, you can now build your solution HMAC-free.

2.2.2.5.4. Secure BuiltinLoggingTopic renamed to BuiltinLoggingTypeV2

Starting in 7.2.0, which added year 2038 support, the secure BuiltinLoggingType type has been renamed BuiltinLoggingTypeV2, the DDS:Security:LogTopic Topic has been renamed DDS:Security:LogTopicV2, and the type’s IDL has changed. To receive both the old (from applications running ealier versions of the Security Plugins) and new Topics, you will need to create two DataReaders: one subscribed to DDS:Security:LogTopic and one subcribed to DDS:Security:LogTopicV2.

Related to 2038 support, the type that is used to represent seconds in DDS_Time_t (C and C++ API), Time_t (Java API), and Time (Modern C++, C#, and Python API) has changed from a 32-bit integer to a 64-bit integer.

2.2.2.5.5. Deprecation of the dds.data_writer.history.use_530_encoding_alignment property

This release of the Security Plugins deprecates the plugin-agnostic dds.data_writer.history.use_530_encoding_alignment property. This property no longer has any effect. A warning message will be logged if this property is set to TRUE. You never needed to set this property in order to interoperate with Security Plugins 5.3.0 or 5.3.1, so this deprecation does not break backward interoperability.

2.2.2.5.6. Deprecation of the cryptography.encryption_algorithm property

This release of the Security Plugins deprecates the plugin-specific cryptography.encryption_algorithm property. Instead, you should set the dds.sec.crypto.symmetric_cipher_algorithm property defined in the OMG ‘DDS Security’ specification, version 1.2. The behavior of the deprecated and the standard property is the same: they are both optional properties that configure the algorithm used for protecting data and metadata.

2.2.2.6. Logging Changes

2.2.2.6.1. Changed fields in Security Events log messages

The following fields in Security Events log messages have changed in this release:

msgid ("k" when the Security Event is printed in JSON format):
Before 7.3.0, this field always contained the string literal "security". Now, it will have a numeric identifier. This change aligns with the message IDs published by RTI Monitoring Library 2.0 for Connext messages, which are also numeric identifiers.
guid name-value pair in structured_data ("x" when the Security Event is printed in JSON format):
The GUID format changed. Starting in release 7.3.0, the hexadecimal letters are shown in upper case, and each component of the GUID (separated by dots) is always 8 characters in length, filling in with leading zeros when necessary. For example, the GUID dfcd91e1.6868b395.a84df008.1c1 now looks like DFCD91E1.6868B395.A84DF008.000001C1.
plugin_class name-value pair in structured_data ("x" when the Security Event is printed in JSON format):
All the plugin class names changed in release 7.3.0 to align with the plugin class names of the OMG ‘DDS Security’ specification, version 1.2. See the following table for the new values:

Table 2.3 Plugin class names comparison
Before Release 7.3.0	Release 7.3.0
`Authentication`	`DDS:Auth:PKI-DH`
`Access Control`	`DDS:Access:Permissions`
`Cryptography`	`DDS:Crypto:AES-GCM-GMAC`
`Logging`	`DDS:Logging:DDS_LogTopic`
`Common`	`RTI:Common`

RTI also added new plugin class names in this release:

DDS:Auth:PSK: Authentication plugin class name for the Lightweight Builtin Security Plugins.
DDS:Access:PSK: Access Control plugin class name for the Lightweight Builtin Security Plugins.
DDS:Crypto:PSK: Cryptography plugin class name for the Lightweight Builtin Security Plugins.
RTI:Auth, RTI:Access, RTI:Crypto, and RTI:Logging: plugin class names used for Security Events logged outside the Security Plugins.

These changes affect both Security Events logged in JSON format through the Connext Builtin Logging System and Security Events distributed over DDS. Keep these changes in mind if your application parses the Security Events log messages or if it subscribes to the Logging topic.

2.2.2.7. Performance and Scalability

2.2.2.7.1. Scalability is slightly affected in systems with more than 900 matching DomainParticipants

DomainParticipant discovery is slightly degraded in terms of scalability. This issue is only noticeable in scenarios with more than 900 DomainParticipants that belong to the same domain. This issue was introduced by the fix for RTI Issue ID SEC-2220 (Non-random initial session ID for entities other than the Secure Key Exchange Channel).

2.2.2.8. Wire Compatibility

2.2.2.8.1. Batching of protected data is not backwards compatible

When enabling batching and serialized data protection, the serialized data protection is now applied to the entire batch instead of to the individual samples within the batch. While this change improves throughput, it also affects backwards compatibility with 6.1.2 releases and earlier. A Connext 7.3.0 DataWriter using this combination will not communicate with a DataReader of an earlier release, and a DataWriter of an earlier release using this combination will not communicate with a Connext 7.3.0 DataReader.

For more information, see Serialized Data Protection in the RTI Security Plugins User’s Manual.

2.2.2.8.2. Data protection kind did not protect serialized keys sent with dispose samples

In releases 6.1.2 and earlier, if you set serialize_key_with_dispose in the DATA_WRITER_PROTOCOL QoS Policy to TRUE (and the Governance document tag data_protection_kind was not NONE), then the key that was serialized with a dispose sample was (incorrectly) not protected. In order to protect this key, you had to set the Governance document tag metadata_protection_kind or rtps_protection_kind to a value other than NONE. This problem has been fixed in release 7.1.0.

While this change fixes a security weakness, it also affects backwards compatibility with releases 6.1.2 and earlier. A Connext 7.3.0 DataReader will fail to process dispose samples from a DataWriter of an earlier release that is setting serialize_key_with_dispose to TRUE and data_protection_kind to a value other than NONE, and a DataReader of an earlier release will fail to process dispose samples from a Connext 7.3.0 DataWriter using this combination.

For more information, see Serialized Data Protection in the RTI Security Plugins User’s Manual.

2.2.2.8.3. AES-192 is not supported when communicating with earlier releases

This issue affects you if you currently configure AES-192 as the cryptography.encryption_algorithm in combination with a Governance document that enables any protection kind other than NONE.

Releases after 6.1.2 do not communicate with 6.1.2 and earlier versions or with other vendors using AES-192, unless the remote DomainParticipant supports discovery changes related to propagation of cryptographic algorithms, discussed in detail in Discovery of a Remote Secure Entity in the RTI Security Plugins User’s Manual.

After 6.1.2, supported and used cryptographic algorithms are propagated in order to determine matching and to improve debuggability. To maintain backward compatibility, and to save bandwidth, the default values are not propagated. The defaults are set to match values recommended in previous releases and allowed by the OMG DDS Security 1.1 specification. In the case of Endpoint Symmetric Cipher Algorithms and Participant Symmetric Cipher Algorithms, the default ‘used algorithm’ is AES-256, while the default ‘supported algorithms’ are AES-128 and AES-256.

As a result, AES-192 is not supported when communicating with releases 6.1.2 and earlier and with vendors not propagating their cryptographic algorithms during discovery. If the local DomainParticipant tries to configure AES-192 as the cryptography.encryption_algorithm (see Properties for Configuring Cryptography in the RTI Security Plugins User’s Manual) while communicating with a DomainParticipant not supporting algorithms during discovery propagation, you will see the following error message:

PRESParticipant_getRemoteParticipantInitialSecurityState:[...]security info for authenticated remote participant [...] does not match the one for local participant [...]. Dropping participant announcement..."}}

Additionally, AES-192 is now deprecated. Please reconfigure your system to use other, supported algorithms. For details about cryptographic algorithms and their default values, see: Cryptographic Algorithms and Authentication Cryptographic Algorithms in the RTI Security Plugins User’s Manual.

2.2.2.8.4. Deprecated property values for configuring the symmetric cipher algorithm

After release 6.1.2, the aes-128-gcm and aes-256-gcm values of the the property that configures the symmetric cipher algorithm are deprecated (see Properties for Configuring Cryptography in the RTI Security Plugins User’s Manual). These values can still be used, but may be removed in a future release. Instead, configure the symmetric cipher algorithm with either AES128+GCM or AES256+GCM. Note that the cryptography.encryption_algorithm property has also been deprecated in 7.3.0.