3. What's New in 7.0.0

3.1.1 Support for kicking Participants off a system

As described in Limiting the Usage of Specific Key Material, in the RTI Security Plugins User's Manual, the cryptography.max_blocks_per_session property is not useful for kicking participants off the system, because the original Key Material stays the same.

In this release, the Security Plugins now support a mechanism to regenerate and redistribute the Key Material without needing to recreate the involved DomainParticipants or losing liveliness. During a key regeneration and redistribution event, information to derive new Key Material is propagated over the Secure Key Exchange Channel to all currently legitimate remote DomainParticipants. When those DomainParticipants acknowledge this information, the old Key Material will no longer be used to encode new content, thus banishing formerly legitimate remote DomainParticipants, without negatively impacting communication with trusted DomainParticipants.

In this first release of this feature, key regeneration and redistribution can be triggered by calling the new DomainParticipant function, banish_ignored_participants() (see 3.1.2 New API for kicking Participants off a system). Future releases will add other ways to trigger key regeneration and redistribution.

This feature introduces new properties:

• dds.participant.trust_plugins.key_revision_max_history_depth
• dds.participant.trust_plugins.max_key_redistribution_delay.sec

To enable this feature, you must set the property dds.participant.trust_plugins.key_revision_max_history_depth to a non-zero value. A DomainParticipant that sets this property to a non-zero value will not communicate with a DomainParticipant that sets this property to 0, or with a DomainParticipant of a release older than Security Plugins 7.0.0.

See Limiting the Usage of Specific Key Material, in the RTI Security Plugins User's Manual for more information.

3.1.2 New API for kicking Participants off a system

This release adds a new API to kick DomainParticipants off a system, DomainParticipant::banish_ignored_participants(). This API complements DomainParticipant::ignore_participant(), which prevents the local DomainParticipant from processing traffic from the remote DomainParticipant. This new method prevents already ignored remote DomainParticipants from processing traffic from the local DomainParticipant.

You can use DomainParticipant::banish_ignored_participants() in combination with the key regeneration and redistribution capabilities of the Security Plugins. See Limiting the Usage of Specific Key Material, in the RTI Security Plugins User's Manual for more information.

3.2.1 Support for secp384r1 key-establishment and digital-signature algorithms

This release introduces support for new key-establishment and digital-signature algorithms. The supported key-establishment algorithms now include Elliptic Curve Diffie-Hellman in Ephemeral mode with secp384r1 as its curve (ECDHE-CEUM+P384). There is also support for digital signatures using ECDSA secp384r1 key-pairs with SHA-384 (ECDSA+P384+SHA384). Note that these algorithms are still not part of the DDS Security Specification.

3.2.2 Changes to property that configures key-establishment algorithm

The property authentication.shared_secret_algorithm has been renamed to authentication.key_establishment_algorithm. (The former name still works, but is now deprecated and may be removed in a future release). The previously supported values (dh and ecdh) are also deprecated. See below for replacement values.

The new property, authentication.key_establishment_algorithm, supports these values:

• DHE+MODP-2048-256: Replaces dh.
• ECDHE-CEUM+P256: Replaces ecdh.
• ECDHE-CEUM+P384: The key establishment algorithm is Elliptic Curve Diffie-Hellman in Ephemeral mode with secp384r1 as its curve.
• AUTO: The Security Plugins will detect the algorithm from the Identity’s private key. If the private key is Elliptic, with a NIST P-384 curve, the algorithm is set to ECDHE-CEUM+P384; otherwise, the algorithm is set to ECDHE-CEUM+P256.

3.2.3 Removed support for Digital Signature Algorithm (DSA)

In previous releases, Digital Signature Algorithm (DSA) support was deprecated. In this release, the DSA support is removed from the Security Plugins. As a result, the Security Plugins now require replacing DSA with one of the supported algorithms (see Cryptographic Algorithms Used for Digital Signatures for more information).

3.2.4 Added experimental support for ED25519, ED448, X25519, and X448

This release adds experimental support for two new digital signature algorithms (EDDSA+ED25519+SHA512, EDDSA+ED448+SHAKE256) and two key establishment algorithms (ECDHE-CEUM+X25519, ECDHE-CEUM+X448). Support for these new algorithms is disabled by default; it can be enabled through the following new property:

• com.rti.serv.secure.authentication.enable_custom_algorithms

This new property configures whether to enable custom cryptographic algorithms for the Authentication plugin. When enabled (not by default) the Security Plugins will enable additional digital signature and key establishment algorithms that are not part of the DDS Security specification (EDDSA+ED25519+SHA512, EDDSA+ED448+SHAKE256, ECDHE-CEUM+X25519, ECDHE-CEUM+X448).

This property is currently only supported in combination with OpenSSL; it will have no effect when used in combination with wolfSSL.

3.2.5 Changed default symmetric cipher algorithm to AES256+GCM

The AES symmetric keys used by the Cryptography Plugin to protect the confidentiality, integrity, and authenticity of messages are now, by default, 256-bits long (AES256+GCM). The previous default length for these keys was 128 bits. The change in the default behavior does not affect compatibility with previous releases: DomainParticipants using different size AES symmetric keys interoperate with no issues. You can modify the length of the keys to use 128 bits by setting the cryptography.encryption_algorithm property to AES128+GCM.

3.3.1 Information about supported and used cryptographic algorithms propagated in discovery

Secure DomainParticipants now propagate information about their supported and used cryptographic algorithms during discovery. This information is used to determine matching between different DomainParticipants, matching between different Endpoints, and for early detection of configuration issues.

DomainParticipants propagate the following information:

• PID_PARTICIPANT_SECURITY_DIGITAL_SIGNATURE_ALGO: Supported and used identity trust chain and authentication algorithms
• PID_PARTICIPANT_SECURITY_KEY_ESTABLISHMENT_ALGO: Supported and preferred key establishment algorithms
• PID_PARTICIPANT_SECURITY_SYMMETRIC_CIPHER_ALGO: Supported and used symmetric cipher algorithms for builtin endpoints traffic and key exchange
• PID_ENDPOINT_SECURITY_SYMMETRIC_CIPHER_ALGO: Symmetric cipher algorithm used by an endpoint to encode its traffic

If any of the PIDs values are set to defaults, or if security is disabled, they are not propagated. The defaults are compatible with previous Security Plugins releases: communication with earlier releases is not impacted.

Compatibility Rules

The following rules determine if two DomainParticipants, PA and PB, are compatible with respect to these cryptographic algorithms:

• Identity trust chain digital signature algorithms
  • PA’s supported algorithms intersect with any bit from PB’s used algorithm, and
  • PB’s supported algorithms intersect with any bit from PA’s used algorithm.
• Authentication digital signature algorithms
  • PA’s supported algorithms intersect with PB’s used algorithm, and
  • PB’s supported algorithms intersect with PA’s used algorithm.
• Key establishment algorithms
  • PA’s supported algorithms intersect with PB’s preferred algorithm, and
  • PB’s supported algorithms intersect with PA’s preferred algorithm.
• Symmetric cipher algorithms
  • PA’s supported algorithm intersects with PB’s used algorithm, and
  • PB’s supported algorithm intersects with PA’s used algorithm, and
  • PA’s builtin endpoint key exchange algorithm is equal to PB’s builtin endpoint key exchange algorithm.
• Two endpoints, EPA and EPB, are compatible if:
  • PA’s supported symmetric cipher algorithms intersect with EPB’s used algorithm, and
  • PB’s supported symmetric cipher algorithms intersect with EPA’s used algorithm.

• <key_establishment>

  Algorithms that DomainParticipants can use for key establishment.

  Possible values:

  • DHE+MODP-2048-256
  • ECDHE-CEUM+P256
  • ECDHE-CEUM+P384
    

Secure DomainParticipants propagate their list of supported+approved algorithms during discovery. Two DomainParticipants will match or not, depending on their supported+approved algorithms. They will try to authenticate each other only if they match.

To allow DomainParticipants in your system to use any supported security algorithm, do not add the <allowed_security_algorithms> XML element to the Governance Document. In that case, the only restriction comes from the implementation of the Security Plugins. For example, a particular crypto library may not support some algorithms. The Security Plugins will internally populate the supported algorithms and let other DomainParticipants know about them during discovery.

3.3.3 New XML attribute to improve version compatibility of Governance and Permissions Documents

This release introduces support for the must_interpret XML attribute. This attribute improves the backward and forward compatibility of the Governance and Permissions Documents.

XML elements that have the must_interpret attribute set to false will not trigger a validation failure of the XML parser. Add must_interpret="false" to the elements of your Governance or Permissions Document that are not supported in other Connext releases. Only the versions of the Security Plugins that understand these elements will interpret them. Others will ignore the elements when parsing the XML file.

If must_interpret is not specified, its default value is "true"—the XML parser validates the element as in previous releases.

Using must_interpret in your Governance of Permissions Document breaks compatibility with versions of the Security Plugins before 7.0.0. For more information, see: 
—The Migration Guide on the RTI Community Portal (https://community.rti.com/documentation),
—How the Governance File is Interpreted, in the RTI Security Plugins User's Manual, and
—How the XML is Validated, in the RTI Connext Core Libraries User's Manual.

3.4.1 Improved throughput when batching protected data

When enabling batching and data protection, the data protection is now applied to the entire batch instead of to the individual samples within the batch. This change introduces two improvements:

• The combination of compression, batching, and data protection is now supported. First the batch will be compressed, then the compressed batch will be protected.
• The throughput of batching and data protection has been improved because the overhead of data protection only appears once per batch.

3.4.2 Added optional custom allocator for Security Plugins for OpenSSL

This release adds the ability to set custom allocators for the Security Plugins loaded crypto library. In particular, this release adds a new custom allocator for Security Plugins for OpenSSL. This feature can be enabled through the new com.rti.serv.secure.authentication.enable_custom_allocators property.

com.rti.serv.secure.authentication.enable_custom_allocators configures whether to set custom crypto library (e.g., OpenSSL) allocators. When enabled (not by default), the Security Plugins will configure custom allocator functions (alloc, realloc, free) to the loaded crypto library with the goal of reducing memory fragmentation at the cost of a minimum performance impact. This is currently only supported in combination with OpenSSL.

This property is only effective the first time a DomainParticipant loads the Security Plugins within the same process: subsequent DomainParticipant creations will ignore this property and leave the existing configuration unchanged. Moreover, this property is only effective if no allocation has been done with the crypto library builtin allocators before the Security Plugins have been loaded, otherwise a warning will be logged and no change will be made.

Important: Since the allocator functions live within the Security Plugins library, your application must not make any calls to the crypto library once the Security Plugins have been unloaded from memory.

3.5.1 "file:" prefix is now optional when specifying filename properties

You may now specify a filename property value without using the prefix "file:". If there is no "data:," prefix and the openssl_engine property is not set, then the value is assumed to be a filename.

For example, "file:../../../dds_security/cert/ecdsa01/identities/ecdsa01Peer01Cert.pem" is now equivalent to "../../../dds_security/cert/ecdsa01/identities/ecdsa01Peer01Cert.pem".

3.5.2 Updated naming convention for email addresses, common names, and subject names of shipped example certificates

This release changes the naming convention used for the email addresses, common names, and subject names of the shipped example certificates. This change has an impact on the resulting subject name of these certificates and therefore this release also updates the shipped example Permission documents accordingly.

3.5.3 New APIs to identify DomainParticipants by subject name

But many of the current DomainParticipant APIs (such as DomainParticipant::ignore_participant()) identify DomainParticipants by their InstanceHandle_t. In this release, we bridge the gap between InstanceHandle_t and subject names. If you know the subject name of the DomainParticipant that you want to ignore, and you need to get the associated InstanceHandle_t, then you can use a new API, DomainParticipant::get_discovered_participants_from_subject_name(). You pass it a subject name string, and it outputs an InstanceHandleSeq of DomainParticipants that have this subject name.

In addition, if you know the InstanceHandle_t of a DomainParticipant for which you want to get the subject name, you can use another new API, DomainParticipant::get_discovered_participant_subject_name(). See the Relevant Connext APIs, in the RTI Security Plugins User's Manual.

3.5.4 Ability to dynamically load Monitoring Library and Security Plugins on VxWorks systems

Connext has the capability to enable the Monitoring Library and Security Plugins using QoS settings, without the need to recompile an application. This release adds support for these features on VxWorks systems.

See Method 1—Change the Participant QoS to Automatically Load the Dynamic Monitoring Library, in the RTI Connext Core Libraries User's Manual
and Dynamic Linking, in the RTI Security Plugins User's Manual
for details on the QoS properties used to enable these features.

3.6.1 Improved message content in case of permissions validation failure

Previously, if validation failed for a permission or governance document, only a high-level message was logged, suggesting that you check the configured permission authorities. This message has been improved. Now it includes a list of the permission authorities in the configuration that failed to sign the document.

3.6.2 Messages logged with Security Logging Plugin are now part of SECURITY category

All security events and messages logged with the Security Logging Plugin are now part of the SECURITY logging category (NDDS_CONFIG_LOG_CATEGORY_SECURITY). This has several implications for security-related messages, regardless of whether they come from the Security Plugins or Connext:

• The Logging Plugin will log a message if its log level is less than or equal to the verbosity of either the Security Plugins or the SECURITY category.
• Connext will log a security-related message if its log level is less than or equal to the SECURITY category verbosity.
• Setting the verbosity of the Security Plugins also configures the verbosity for the SECURITY category, which will affect any security-related message (including those logged from Connext) logged from any DomainParticipant within the same application.

For more on the interactions between Security Plugins and the SECURITY category verbosities, see Advanced Logging Concepts, in the RTI Security Plugins User's Manual.

3.6.3 Increased logging in case of identity validation failure

Previously, when identity validation failed, the user received only a high-level message informing about the fact and advising to check on configured identity authorities. Now, this message is followed by the list of all authorities listed in the configuration to sign the identity but failing to do so.

3.7.1 New functions in SDK test infrastructure

There are several new functions you can use for testing:

• RTITest_waitForEqualsIntExt(): Wait a certain time for a value to be equal to the expected one. Execute an action every 10ms (which can be useful for updating the value before checking if it matches the one we expect).
• DDSCTestContext_getMatchingPublicationsLength(): Get the number of matching publications associated with a DataReader.
• DDSCPubSubDataReaderListenerData_reset(): Reset the values in the DataReader Listener Data.
• DDSCTesterHelperLoggerDeviceData_initialize() and
  DDSCTesterHelperLoggerDeviceData_finalize(): Initialize and finalize a semaphore that protects the counter for found messages. The semaphore is required when multiple DomainParticipants are concurrently producing the expected log message.
• Functions for positioning a stream:
  • DDSCTestHelper_positionStreamToBinaryProperty()
  • DDSCTestHelper_positionStreamToPid()
  • DDSCTestHelper_positionStreamToNextPid()
• Functions associated with a DDSCPubSubTestContext:
  • DDSCPubSubTestContext_initializeListener()
  • DDSCPubSubTestContext_createPubParticipantWithTypeConfig()
  • DDSCPubSubTestContext_createSubParticipantWithTypeConfig()

3.7.2 New '-verbosity' argument for SDK testers

You can now change the verbosity for the access control and cryptography testers using the -verbosity <int> argument. It accepts a number between 0 (SILENT) and 6 (STATUS_ALL). The default value is 2: print fatal errors and exceptions. See the output of -help for more information about verbosity levels.

3.7.3 More meaningful return types for SDK tests

The access control and cryptography testers run a battery of tests. These tests previously returned only two values: RTI_FALSE (0) when a test failed and RTI_TRUE (1) when a test passed. A test can now return an RTITestReturnCode, which allows more possibilities:

• RTI_TEST_RETCODE_FAILED: The test failed. This value is equivalent to the previous RTI_FALSE.
• RTI_TEST_RETCODE_PASSED: The test passed. This value is equivalent to the previous RTI_TRUE.
• RTI_TEST_RETCODE_UNSUPPORTED: The test is not supported. A test won’t be supported when it depends on a feature unavailable for the current crypto library or architecture. The testing infrastructure doesn’t report unsupported tests as errors. Instead, unsupported tests pass when running.

More return types may be added in the future.

3.8.1 New Platforms

This release adds support for these platforms:

• macOS 12 on x64 and Arm v8 (SDK only supported on x64)
• Ubuntu 22.04 LTS on x64 and Arm v8 (SDK only supported on x64)
• VxWorks 21.11 on x64 (SDK not supported)
• Windows 11 on x64 with Visual Studio 2022

3.8.2 Removed Platforms

The following platforms were supported in Security Plugins 6.1.1, but are not supported in release 7.0.0.

• Android
• These Linux platforms:
  • CentOS 6.x
  • NI Linux 3
  • Red Hat Enterprise Linux 6.x
  • Ubuntu 18.04 LTS on Arm v7
• QNX Neutrino 6.x, 7.0.4
• VxWorks 7.x