.. include:: /../getting_started/vars.rst
RTI |RTI_SP_PRODUCT_HEADING|
****************************
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.
HMAC-Only Mode Deprecation
--------------------------
Starting in release 7.1.0, |SP_BUILTIN|'s *HMAC-Only mode* is deprecated,
and |LIGHT_SP_BUILTIN| should be used instead (see
:link_sec_um_730_lightweight:`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 |SP_BUILTIN|'s *HMAC-Only mode* and its configuration, see
:link_sec_um_hmaconly_612:`RTPS-HMAC-Only Mode <>` in the *Security Plugins* 6.1.2
documentation.
.. DOC-452
Logging Changes
===============
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):
|br|
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_MONITORINGLIBRARY2| 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):
|br|
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):
|br|
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:
.. list-table:: Plugin class names comparison
:widths: 50 50
:align: center
:header-rows: 1
* - Release 7.2.0 and earlier
- 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 |LIGHT_SP_BUILTIN|.
* ``DDS:Access:PSK``: Access Control plugin class name for the
|LIGHT_SP_BUILTIN|.
* ``DDS:Crypto:PSK``: Cryptography plugin
class name for the |LIGHT_SP_BUILTIN|.
* ``RTI:Auth``, ``RTI:Access``, ``RTI:Crypto``, and ``RTI:Logging``:
plugin class names used for Security Events logged outside the
|RTI_SP_PRODUCT|.
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.
.. DOC-364
Wire Compatibility
==================
Pre-Shared Key Protection is not backwards compatible due to OMG standard compliance changes
--------------------------------------------------------------------------------------------
|DPs| that have a Pre-Shared Key Protection enabled (by setting the
``dds.sec.crypto.rtps_psk_secret_passphrase`` property) will not communicate
with |DPs| from previous versions (7.1.0 or 7.2.0).
Compliance with OMG DDS Security 1.2 standard prompted a number of changes in
RTI's implementation of Pre-Shared Key Protection. Some of the changes break
interoperability with previous versions. This includes changes in the
pre-shared keys derivation algorithm (resulting in different cryptographic
keys) and lightweight plugins class ID.
The issue affects both the |SP_BUILTIN| when PSK is used and the |LIGHT_SP_BUILTIN|.
Backwards compatibility broken when configuring non-OMG-default cryptographic algorithms
-----------------------------------------------------------------------------------------
During discovery, |DPs| may propagate information about the cryptographic
algorithms that they require or support. The information is propagated when
|DPs| are configured with cryptographic algorithms that the |SEC_SPEC_12|
doesn't consider as default. You can find these default values in the
:link_sec_um_730_cryptography:`Cryptography chapter <#allowed-security-algorithms-domain-rule>`
of the |SP_UM| (the `"allowed_security_algorithms (domain_rule)"` section).
Note that the default behavior for the |RTI_SP_PRODUCT| is to support
all cryptographic algorithms (including some not considered default by the
specification) if your Governance Document doesn't indicate any. This means that
the |DPs| will propagate information about their cryptographic algorithms during
discovery if there is no ``allowed_security_algorithms`` tag in the Governance
Document.
In the previous 7.0.0, 7.1.0, and 7.2.0 releases, the |RTI_SP_PRODUCT|
serialized all related cryptographic algorithms as long as one of them had a
value not considered as default by the |SEC_SPEC_12|. Starting in this release,
the |RTI_SP_PRODUCT| may skip serialization of some algorithms. As a result,
compatibility between 7.3.0 and previous *Connext* 7 releases is broken when
configuring non-OMG-default cryptographic algorithms. Previous *Connext* 7
releases will attempt to deserialize all algorithms and fail when they are
missing.
This release of the |RTI_SP_PRODUCT| also changes the bits that are associated
with the experimental algorithms (`EDDSA+ED25519+SHA512`, `EDDSA+ED448+SHAKE256`,
`ECDHE-CEUM+X25519`, and `ECDHE-CEUM+X448`) in the propagated masks. Do not use
these experimental cryptographic algorithms if you expect compatibility between
7.3.0 and previous *Connext* 7 releases. Another non-OMG-default cryptographic
algorithm that you should not use when you expect backwards compatibility is
`AES192+GCM`. The value of its cryptographic algorithm identifier has changed in
7.3.0 to match the vendor-specific range that the |SEC_SPEC_12| mandates.
Performance and Scalability
===========================
Scalability is slightly affected in systems with more than 900 matching DomainParticipants
------------------------------------------------------------------------------------------
|DP| discovery is slightly degraded in terms of scalability. This
issue is only noticeable in scenarios with more than 900 |DPs| that
belong to the same |DP| partition. 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).
Changes to Properties
=====================
Deprecation of the dds.data_writer.history.use_530_encoding_alignment property
------------------------------------------------------------------------------
This release of the |RTI_SP_PRODUCT| 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 |RTI_SP_PRODUCT| 5.3.0 or 5.3.1, so this deprecation does not break
backward interoperability.
Deprecation of the cryptography.encryption_algorithm property
-------------------------------------------------------------
This release of the |RTI_SP_PRODUCT| 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.
Changes to the cryptography.rtps_protection_preshared_key property
------------------------------------------------------------------
This release of the |RTI_SP_PRODUCT| removes the plugin-specific
``cryptography.rtps_protection_preshared_key`` property. Instead, you should set
the ``dds.sec.crypto.rtps_psk_secret_passphrase`` property defined in the
`OMG 'DDS Security' specification, version 1.2 `__.
The behavior of the removed and the standard property is the
same: they are both properties that must be set when Pre-Shared Key Protection
is enabled, and they contain the seed used to derive the key for protecting
RTPS messages.
The acceptable formats for ``dds.sec.crypto.rtps_psk_secret_passphrase`` have
changed. The property supports two formats:
* ``data:,:`` allows you to provide the PSK seed explicitly in the
property value.
* ```` is an integer [0, 254] identifying the provided seed within the
system.
* ```` is a string used to derive (in combination with publicly
available data) the key used for encoding RTPS messages.
* ``file:`` allows you to provide the seed in a supplemental file.
The file can be optionally tracked by both |SP_BUILTIN| and
|LIGHT_SP_BUILTIN| (via the ``files_poll_interval`` property,
enabled by default) for changes that are automatically incorporated into
present operations.
* ```` is the path to a file containing the PSK seed. The content
of the file must use the ``:`` format.
Removal of the cryptography.rtps_protection_preshared_key_algorithm property
----------------------------------------------------------------------------
This release of the |RTI_SP_PRODUCT| removes the plugin-specific
``cryptography.rtps_protection_preshared_key_algorithm`` property. Instead, you
should set the ``dds.sec.crypto.rtps_psk_symmetric_cipher_algorithm`` property
defined in the `OMG 'DDS Security' specification, version 1.2 `__.
Just as the removed property, the new one controls the algorithm used for
protecting RTPS messages when Pre-Shared Key Protection is enabled. However, its
possible values are limited to: ``AUTO`` (same as ``AES256+GCM``),
``AES128+GCM``, and ``AES256+GCM``. The decision of whether to protect only
integrity, or to protect confidentiality as well, depends on the value of the
``rtps_psk_protection_kind`` XML tag in the Governance Document. In the case of
|LIGHT_SP_BUILTIN| (which does not support the Governance Document), it is configured
through the new ``dds.sec.access.rtps_psk_protection_kind`` property.
Removal of authentication.crl_file_poll_period.millisec and com.rti.serv.secure.authentication.identity_certificate_file_poll_period.millisec properties
--------------------------------------------------------------------------------------------------------------------------------------------------------
The ``authentication.crl_file_poll_period.millisec`` and
``authentication.identity_certificate_file_poll_period.millisec`` properties
have been replaced with a single property ``files_poll_interval``.
The new property controls the polling interval for all files tracked by the
|SP_BUILTIN|. File tracking is enabled when the ``files_poll_interval``
value is a non-zero, positive number. When enabled, the |SP_BUILTIN| will
create a dedicated thread and allocate memory for file-tracking purposes
regardless of whether there are any files to track. When ``files_poll_interval``
has a value of ``0``, all file tracking within |SP_BUILTIN| is disabled.
Note that this property specifies time in seconds (previously, milliseconds)
and acceptable values are in a narrower interval ``[0, 4294967]``. The default
value is now ``5`` (previously, ``0``), which means file tracking is enabled by
default.
Changes to the Governance Document
==================================
This release of the |RTI_SP_PRODUCT| removes the Governance Document
``rtps_preshared_secret_protection_kind`` XML tag in favor of the one defined in
the `OMG 'DDS Security' specification, version 1.2 `__:
``rtps_psk_protection_kind``. You must switch to the new
``rtps_psk_protection_kind`` XML tag. The new tag behaves exactly the same as
the old one. It configures the kind of protection (``ENCRYPT``, ``SIGN``, or
``NONE``) that the |SP_BUILTIN| apply to RTPS messages when using
Pre-Shared keys.