2.2.2.3. Security Plugins

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

Attention

For important information on new and deprecated features in 7.2.0, see What’s New in 7.2.0 in the RTI Security Plugins Release Notes.

2.2.2.3.1. Changes to building an application

2.2.2.3.1.2. OpenSSL 3.0 upgrade and 1.1.1 removal

Release 7.2.0 of the Security Plugins uses OpenSSL® 3.0.9. The Security Plugins 7.2.0 include only one set of target bundles: rti_security_plugins-7.2.0-target-openssl-3.0-<architecture>.rtipkg. These bundles are API-compatible with OpenSSL versions 3.0.0 through 3.0.9, not with versions earlier than OpenSSL 3.0.0. Note that Security Plugins 7.2.0 has only been tested by RTI using OpenSSL 3.0.9. If you need Security Plugins 7.2.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.1.3. wolfSSL upgrade

Starting in release 7.1.0, the Security Plugins for wolfSSL are now based on wolfSSL version 5.5.1. Starting with 7.1.0, 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.1.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.1.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.1.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.8 is slower than OpenSSL 1.1.1t, 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.3.2. API Compatibility

2.2.2.3.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.3. Updated shipped examples to support different cryptographic libraries

Release 7.1.0 (which release 7.2.0 subsumes) 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.3.4. Wire Compatibility

2.2.2.3.4.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.2.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.2.0 DataReader.

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

2.2.2.3.4.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.2.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.2.0 DataWriter using this combination.

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

2.2.2.3.4.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.3.4.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.

2.2.2.3.5. Configuration Changes

2.2.2.3.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.3.5.2. Enforcement of supported Digital Signature algorithms now supported in Connext

Release 7 adds 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.3.5.3. Deprecated properties in favor of pre-shared key (PSK) protection

In 7.2.0, the following properties are 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 in 7.2.0 (adding PSK protection to RTI Cloud Discovery Service and RTI Real-Time WAN Transport), release 7.2.0 offers a complete alternative to HMAC-Only protection. Starting in 7.2.0, you can now build your solution HMAC-free.

2.2.2.3.5.4. Secure BuiltinLoggingTopic renamed to BuiltinLoggingTypeV2

In the year 2038 support added in 7.2.0, 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.