.. include:: /../getting_started/vars.rst
.. _section-Product-Security:
RTI Security Plugins
********************
Release 6.0.0 of *Security Plugins* uses OpenSSL 1.0.2o. (Release 5.3.1
used OpenSSL 1.0.2n.)
.. note::
OpenSSL 1.0.2o fixes moderate severity vulnerabilities (RTI Issue ID PLATFORMS-1642),
so it is recommended that you upgrade the version of OpenSSL that you are using to
OpenSSL 1.0.2o for release 6.0.0. For instructions on installing this version of OpenSSL,
see the :link_connext_sec_install_gsg_600:`RTI Security Plugins Getting Started Guide 6.0.0<>`.
The following issues affect backward compatibility in *Security Plugins*
starting in Release 6.0.0.
Configuration
=============
Changed Authentication and Access Control property names
--------------------------------------------------------
Starting with 6.0.0, you may use the property names that are in the
`DDS Security specification `_
for configuring some attributes of the builtin
Authentication and Access Control Plugins. See the section “Updated
configuration property names”
in the :link_connext_sec_new_other_release_notes:`RTI Security Plugins Release Notes <>`
for a list of properties.
Notes:
* The values of these properties require a prefix, which may be either
``file:`` or ``data:,``.
* If both the legacy and new properties are specified for a given
attribute, the new property is applied, and the legacy property is
ignored.
* The legacy ``com.rti.serv`` properties are not equivalent to the new
``dds.sec`` properties with respect to the inherit attribute of the
```` tag in a QoS profile. For example, if profile “Base”
specifies ``dds.sec.auth.identity_ca CaBase``
and profile “Derived” (which has ``base_name="Base"``) specifies
``com.rti.serv.secure.authentication.ca_file CaDerived``,
the CA will end up being “CaBase” because the two properties have
different names, and the new property takes precedence over the old one.
To avoid confusion, it is recommended to update your property names to match
those in the DDS Security specification and to add the ``file:`` prefix to
the corresponding property values. The ``com.rti.serv.secure`` prefix should
be used only for RTI-specific property names. See the
:link_connext_sec_authentication_gsg:`Authentication chapter of the Security Plugins Getting Started Guide <>`
for more information on these properties.
Changed default Persistence Service "dds.data_writer.history.key_material_key"
------------------------------------------------------------------------------
In 6.0.0, the undisclosed non-NULL default
``dds.data_writer.history.key_material_key`` has changed. As a result,
*Persistence Service* databases protected with the old default key will not
be accessible by the new *Persistence Service*. Note that using the default
key is discouraged, and you should set
``dds.data_writer.history.key_material_key`` to a value other than the default.
If you need to access a *Persistence Service* database encrypted with the
old default key using a new version of *Persistence Service*, please contact
RTI Support at support@rti.com.
.. note::
In 6.0.1, ``dds.data_writer.history.key_material_key`` becomes mandatory.
That is, not setting it will result in *Persistence Service* failing to start.
See :numref:`section-security-key`.
Changed Persistence Service encryption algorithm
------------------------------------------------
In 6.0.0, the algorithm used to encrypt a *Persistence
Service* database has changed to be more secure. As a result, databases
protected with the old *Persistence Service* will not be accessible by the
new *Persistence Service*.
.. _section-Security-changed-matching-behavior:
Changed matching behavior of allowed partitions condition
---------------------------------------------------------
The `DDS Security specification `_
describes the matching behavior of the ```` section within
an ```` of a Permissions file.
In order for a |DW| or |DR| to be matched with an
"allowed partitions" condition, the DDS entity’s partitions must be a
subset of the partitions in the condition. Release 6.0.0 enforces this
matching rule.
To change this enforcement, you may set the security plugin property
``access_control.use_530_partitions`` to TRUE. If TRUE, then a |DW| or |DR|
will be matched with an "allowed partitions" condition as long as at least
one of the DDS entity’s partitions matches one of the partitions in the
condition; this is consistent with |CONNEXT| 5.3.0 behavior. If FALSE,
then the entity’s partitions must be a subset of the condition’s partitions;
this is consistent with the behavior of the DDS Security specification.
The default value is FALSE.
Here’s an example:
.. list-table:: Allowed Partitions Condition Example
:name: TableAllowedPartitions
:widths: 25 50 50 25
:header-rows: 1
:class: longtable
* - |DW| Partitions
- Allowed Partitions Condition
- use_530_partitions
- allowed?
* - [A, B]
- [B, C]
- TRUE
- yes, because B is in [B, C]
* - [A, B]
- [B, C]
- FALSE
- no, because A is not in [B, C]
Change to mutability of Publisher PartitionQosPolicy
----------------------------------------------------
The Publisher PartitionQosPolicy always used to be mutable. Now in 6.0.0, it is
immutable if the Publisher contains any |DW| that meets both of the following
two criteria:
- The TopicSecurityAttributes for that |DW| have ``is_read_protected``
(which corresponds to ```` in the Governance
Document) set to TRUE.
- The |DW| has the DurabilityQosPolicy ``kind`` set to something
other than VOLATILE.
New protection for Builtin Logging Topic
----------------------------------------
Release 6.0.0 changes the Governance XML setting ``metadata_protection_kind``
from NONE to SIGN for the Builtin Logging Topic. This change was made to be
compliant with the
`DDS Security specification `_.
It breaks configuration compatibility between this and previous releases
when using a |DR| to subscribe to the Builtin Logging Topic. The |DR| must
now be configured to use ``metadata_protection_kind`` = SIGN.
To change this behavior, you may set the security plugin property
``access_control.use_530_logging_protection`` to TRUE. If TRUE, then the
``metadata_protection_kind`` will be NONE for the Builtin Logging Topic,
which is consistent with |CONNEXT| 5.3.0 behavior. The default value is FALSE.
Wire Compatibility
==================
Participants and endpoints using inconsistent security configuration do not communicate
---------------------------------------------------------------------------------------
Release 6.0.0 adds support for the new `DDS Security specification `_
participant/endpoint security matching, which allows for early detection of
incompatible security configurations. To support this feature, participants
will announce new parameters as part of the participant/endpoint discovery.
See :link_connext_sec_new_release_notes:`What's New in 6.0.0 in the Security Plugins Release Notes <>`.
The propagation of these parameters is enabled by default. Since their
propagation introduces additional restrictions for participant and endpoint
matching, participants and endpoints may stop communicating after upgrading
to 6.0.0 if they are using a configuration considered incompatible according
to the DDS Security specification.
To support scenarios relying on inconsistent security configurations, the
following new properties have been introduced (not used by default):
.. list-table:: New Properties to Enable/Disable Propagation of New Security Parameters During Discovery
:name: SecurityParameterProperties
:widths: 40 60
:header-rows: 1
:class: longtable
* - Property Name [#f1]_
- Property Value Description
* - ``dds.participant.discovery_config.``
``disable_endpoint_security_info_propagation``
- **Optional** |br|
|br|
If set to FALSE, the endpoint's ``security_info`` is propagated and
a |DW|/|DR| pair needs to use the same security configuration to match.
If set to TRUE in both participants, contained |DWs| and
|DRs| may communicate for some combinations of inconsistent
metadata/data protection kinds. |br|
|br|
Default: FALSE
* - ``dds.participant.discovery_config.``
``disable_participant_security_info_propagation``
- **Optional** |br|
|br|
If set to FALSE, the participant's ``security_info`` is propagated
and a pair of participants needs to use the same Governance's RTPS,
discovery, and liveliness configurations to match. If set to TRUE in
both participants, participants may communicate for some combinations
of inconsistent Governance's RTPS, discovery, and liveliness
configurations. |br|
|br|
Default: FALSE
APIs
====
Changes in DDS types and definitions
------------------------------------
The following changes were made in 6.0.0 to match the
`DDS Security specification `_:
* Added new ``TopicSecurityAttributes`` type.
* Moved the following from ``EndpointSecurityAttributes`` to
``TopicSecurityAttributes``:
* ``is_read_protected``
* ``is_write_protected``
* ``is_discovery_protected``
* ``is_liveliness_protected``
* Changed the ``RTI_Security_Exception`` (``DDS_TrustException``) definition
and removed the ``RTI_Security_ExceptionCode`` (``DDS_TrustExceptionCode``)
definition.
* Changed ``ReturnCode_t`` ``NOT_ALLOWED_BY_SEC`` (value 13) to
``NOT_ALLOWED_BY_SECURITY`` (value 1000).
Changes in APIs
---------------
The following changes were made in 6.0.0:
* Added the following APIs to the Access Control plugin interface to
match the `DDS Security specification `_:
* ``get_topic_security_attributes``
* ``get_datawriter_sec_attributes`` and ``get_datareader_sec_attributes``
(these replace ``get_endpoint_sec_attributes``)
* ``return_participant_sec_attributes``, ``return_datawriter_sec_attributes``,
and ``return_datareader_sec_attributes``
* Removed the ``get_endpoint_sec_attributes`` API from the Access Control
plugin interface.
* Updated ``validate_remote_identity`` to include AuthRequestMessageToken
parameters.
* Removed ``begin_auth_request`` and ``process_auth_request`` APIs from the
Authentication plugin interface.
* Updated ``check_remote_datareader`` to include the ``relay_only`` parameter.
* Updated ``check_local_datawriter_match`` and ``check_local_datareader_match``
to include publication/subscription data parameters and to remove the
tags parameter.
* Added “const” to non-primitive input parameters of APIs of Authentication,
Access Control, and Cryptography plugins.
get_datawriter_sec_attributes and get_datareader_sec_attributes must support receiving builtin topic names
----------------------------------------------------------------------------------------------------------
Previously, ``get_datawriter_sec_attributes`` and ``get_datareader_sec_attributes``
did not expect to receive builtin topic names, only user topic names.
In 6.0.0, to be compliant with `DDS Security specification `_,
the core libraries can call ``get_datawriter_sec_attributes`` and
``get_datareader_sec_attributes`` to retrieve the endpoint security attributes
for builtin (secure and non-secure) |DWs| and |DRs|. As such, custom security
plugins need to be updated to support receiving the following topic name
string definitions:
* DDS discovery topics:
* DDS_PARTICIPANT_TOPIC_NAME
* DDS_PUBLICATION_TOPIC_NAME
* DDS_SUBSCRIPTION_TOPIC_NAME
* DDS liveliness topic:
* DDS_PARTICIPANT_MESSAGE_TOPIC_NAME
* DDS Security secure discovery topics:
* DDS_PARTICIPANT_TRUSTED_TOPIC_NAME
* DDS_PUBLICATION_TRUSTED_TOPIC_NAME
* DDS_SUBSCRIPTION_TRUSTED_TOPIC_NAME
* DDS Security secure liveliness topic:
* DDS_PARTICIPANT_MESSAGE_TRUSTED_TOPIC_NAME
* Other DDS Security topics:
* DDS_PARTICIPANT_STATELESS_MESSAGE_TOPIC_NAME
* DDS_PARTICIPANT_TRUSTED_VOLATILE_MESSAGE_TOPIC_NAME
* RTI non-secure topics:
* DDS_PARTICIPANT_PROXY_TOPIC_NAME
* DDS_PARTICIPANT_STATE_TOPIC_NAME
* DDS_SERVICE_REQUEST_TOPIC_NAME
* RTI secure topics:
* DDS_SERVICE_REQUEST_TRUSTED_TOPIC_NAME
.. rubric:: Footnotes
.. [#f1] These new properties do not need to be prefixed with
‘com.rti.serv.secure.’