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