.. include:: ../vars.rst

.. _chapter-apis:

*********************
Relevant Connext APIs
*********************

Relevant functions
==================

The Core Libraries include some API functions that are relevant to the |RTI_SP_PRODUCT|.

:property:`banish_ignored_participants`
---------------------------------------

This method complements :property:`ignore_participant`, which prevents the
local |DP| from processing traffic from the remote |DP|. When security is
enabled, this method prevents already ignored remote |DPs| from processing
traffic from the local |DP| by implementing the key regeneration and
redistribution capabilities described in the section
:ref:`p2_core/cryptography:Limiting the Usage of Specific Key Material`.

.. note::

  For a demonstration of this method, see
  :file:`<path to examples>/connext_dds/c/hello_banish`.

:property:`discovered_participant_subject_name`
-----------------------------------------------

This method works almost as documented in the
:link_connext_dds_api_cpp2:`RTI Connext Modern C++ API DomainParticipant Class Reference <classdds_1_1domain_1_1DomainParticipant.html>`.
The main difference is that when security is enabled, this method retrieves the
|IdentityCert|'s subject name (see
:ref:`p2_core/elements_dds_secure_system:Identity Certificates`) instead of the
:property:`participant_name.name`. With this functionality, you can make a list
of currently discovered subject names and make decisions based on these names.

The format of the resulting subject name differs between OpenSSL and wolfSSL.
If you use OpenSSL, the subject name attributes will be separated by spaces and
commas. If you use wolfSSL, the subject name attributes will be separated only
by slashes. Here is an example:

.. tabs::

   .. group-tab:: OpenSSL

      .. code-block:: text

         C = US, ST = CA, L = Sunnyvale, O = ACME Inc., OU = CTO Of-fice, CN = DDS Shapes Demo, emailAddress = cto@acme.com

   .. group-tab:: wolfSSL

      .. code-block:: text

         /C=US/ST=CA/L=Sunnyvale/O=ACME Inc./OU=CTO Of-fice/CN=DDS Shapes Demo/emailAddress=cto@acme.com

If the discovered |DP| has not completed authentication and the value of the
:property:`authentication.enable_discovery_subject_name_propagation` property is
:value:`FALSE` (default), then DDS_RETCODE_NO_DATA is the result.

.. note::

  For a demonstration of this method, see
  :file:`<path to examples>/connext_dds/c/hello_banish`.

:property:`discovered_participants_from_subject_name`
-----------------------------------------------------

This method works almost as documented in the
:link_connext_dds_api_cpp2:`RTI Connext Modern C++ API DomainParticipant Class Reference <classdds_1_1domain_1_1DomainParticipant.html>`.
The main difference is that when security is enabled, this method takes as an
input the |IdentityCert|'s subject name (see
:ref:`p2_core/elements_dds_secure_system:Identity Certificates`) instead of the
:property:`participant_name.name`. As a consequence, the subject name input may
not be :property:`NULL` or malformed (e.g., with attributes that don't exist
according to `RFC 4514 <https://datatracker.ietf.org/doc/html/rfc4514>`_). With
this functionality, the |RTI_SP_PRODUCT| bridge the gap between `InstanceHandle_t` and subject
names. For example, if you know the subject name of a discovered |DP| that you
want to ignore, and you need to get the associated `InstanceHandle_t`, you can
call this method and then pass the result into :property:`ignore_participant`.

If a discovered |DP| has not completed authentication, then it is not included
in the resulting sequence of `InstanceHandle_t`.

If the subject name input is :property:`NULL` or malformed, this
method returns DDS_RETCODE_BAD_PARAMETER.

.. note::

  For a demonstration of this method, see
  :file:`<path to examples>/connext_dds/c/hello_banish`.

:property:`discovered_participant_data`
---------------------------------------
This method works as documented in the
:link_connext_dds_api_cpp2:`RTI Connext Modern C++ API DomainParticipant Class
Reference <classdds_1_1domain_1_1DomainParticipant.html>`. The returned
participant data contains security information about the remote |DP|.
This information is in the `trust_protection_info` and `trust_algorithm_info`
members of the :link_connext_dds_api_cpp2:`participant builtin topic data
<classdds_1_1topic_1_1ParticipantBuiltinTopicData.html>`, which have a type of
:link_connext_dds_api_cpp2:`ParticipantTrustProtectionInfo <classrti_1_1topic_1_1trust_1_1ParticipantTrustProtectionInfo.html>`
and :link_connext_dds_api_cpp2:`ParticipantTrustAlgorithmInfo <classrti_1_1topic_1_1trust_1_1ParticipantTrustAlgorithmInfo.html>`.

The equivalent APIs for the |EPs| (:link_connext_dds_api_cpp2:`matched_publication_data <classdds_1_1sub_1_1DataReader.html#a62195eaf0aa94ab4ada984966c3ac7eb>` and
:link_connext_dds_api_cpp2:`matched_subscription_data <classdds_1_1pub_1_1DataWriter.html#a8f94f174b39c2776c7eeb3e3d3995c9a>`)
also return data that has the `trust_protection_info` and `trust_algorithm_info` information
associated with them.

The contents of the `trust_protection_info` participant and endpoint data
structures are according to the descriptions in the `ParticipantSecurityInfo`
and `EndpointSecurityInfo` of the |SEC_SPEC_11|.
You can learn more about the contents of the `trust_algorithm_info` data structures
by reading about the security algorithms and the matching process for two
|SecDPs| (or |SecEPs|) in sections
:ref:`p2_core/cryptography:allowed_security_algorithms (domain_rule)` and
:ref:`p2_core/cryptography:Discovery of a Remote Secure Entity` of this User's
Manual.

:property:`on_invalid_local_identity_status_advance_notice`
-----------------------------------------------------------

This function is a
:link_connext_dds_api_cpp2:`DomainParticipantListener<classdds_1_1domain_1_1DomainParticipantListener.html>`
callback. It gets invoked when the local |DP|'s |IdentityCert| or Identity CA
has already expired or will expire within the duration specified by the
:property:`dds.participant.trust_plugins.certificate_expiration_advance_notice_duration.sec`
property. For more information, please see
:ref:`p2_core/authentication:Dynamic Certificate Expiration of the Local |DP|`.

Relevant types for the Governance Document
==========================================
The Core Libraries include some types that are relevant to the |RTI_SP_PRODUCT|
|GovernanceDoc|.

.. list-table:: Mappings between types in DDS and the |RTI_SP_PRODUCT|
   :name: DdsSpGovernanceTypeMapping
   :widths: 50 50
   :header-rows: 1
   :class: longtable

   * - DDS Type
     - |RTI_SP_PRODUCT_HEADING| Type
   * - :link_connext_dds_api_cpp2:`DDS_ParticipantTrustProtectionInfo <classrti_1_1topic_1_1trust_1_1ParticipantTrustProtectionInfo.html>`
     - `DDS_ParticipantSecurityProtectionInfo`
   * - `DDS_ParticipantTrustAttributesMask bitmask`
     - `DDS_ParticipantSecurityAttributesMask participant_attributes`
   * - `DDS_PluginParticipantTrustAttributesMask plugin_bitmask`
     - `DDS_PluginParticipantSecurityAttributesMask plugin_participant_attributes`
   * - `DDS_PluginParticipantTrustAttributesMask`
     - `DDS_PluginParticipantSecurityAttributesMask`
   * - :link_connext_dds_api_cpp2:`DDS_EndpointTrustProtectionInfo <classrti_1_1topic_1_1trust_1_1EndpointTrustProtectionInfo.html>`
     - `DDS_EndpointSecurityProtectionInfo`
   * - `DDS_EndpointTrustAttributesMask bitmask`
     - `DDS_EndpointSecurityAttributesMask endpoint_attributes`
   * - `DDS_PluginEndpointTrustAttributesMask plugin_bitmask`
     - `DDS_PluginEndpointSecurityAttributesMask plugin_endpoint_attributes`
   * - `DDS_EndpointTrustAttributesMask`
     - `DDS_EndpointSecurityAttributesMask`
   * - `DDS_PluginEndpointTrustAttributesMask`
     - `DDS_PluginEndpointSecurityAttributesMask`

.. list-table:: :link_connext_dds_api_cpp2:`DDS_ParticipantSecurityProtectionInfo <classrti_1_1topic_1_1trust_1_1ParticipantTrustProtectionInfo.html>`.bitmask bit values
   :name: ParticipantSecurityAttributes BitValues
   :widths: 10 40 50
   :header-rows: 1
   :class: longtable

   * - bitmask bit value
     - Definition in the |RTI_SP_PRODUCT| (prefix with ``PARTICIPANT_SECURITY_ATTRIBUTES_FLAG_``) and string name
     - Configuration
   * - ``0x1 << 0``
     - `IS_RTPS_PROTECTED`
     - |GovernanceDoc| :xmltag:`rtps_protection_kind` is not :xmlval:`NONE`
   * - ``0x1 << 1``
     - `IS_DISCOVERY_PROTECTED`
     - |GovernanceDoc| :xmltag:`discovery_protection_kind` is not :xmlval:`NONE`
   * - ``0x1 << 2``
     - `IS_LIVELINESS_PROTECTED`
     - |GovernanceDoc| :xmltag:`liveliness_protection_kind` is not :xmlval:`NONE`
   * - ``0x1 << 3``
     - `ARE_KEY_REVISIONS_ENABLED`
     - PropertyQosPolicy :property:`dds.participant.trust_plugins.key_revision_max_history_depth` is not :value:`0`
   * - ``0x1 << 4``
     - `IS_RTPS_PSK_PROTECTED`
     - |GovernanceDoc| :xmltag:`rtps_psk_protection_kind` is not :xmlval:`NONE`
   * - ``0x1 << 31``
     - `IS_VALID`
     - This bit indicates whether the rest of the ``bitmask`` is valid, so it
       should always be set as long as the |RTI_SP_PRODUCT| are enabled for the |DP| and
       the |RTI_SP_PRODUCT| version is 6.0.0 or above.

.. list-table:: :link_connext_dds_api_cpp2:`DDS_ParticipantSecurityProtectionInfo <classrti_1_1topic_1_1trust_1_1ParticipantTrustProtectionInfo.html>`.plugin_bitmask bit values
   :name: PluginParticipantSecurityAttributes BitValues
   :widths: 10 40 50
   :header-rows: 1
   :class: longtable

   * - plugin_bitmask bit value
     - Definition in the |RTI_SP_PRODUCT| (prefix with ``PLUGIN_PARTICIPANT_SECURITY_ATTRIBUTES_FLAG_``) and string name
     - Configuration in the |GovernanceDoc|
   * - ``0x1 << 0``
     - `IS_RTPS_ENCRYPTED`
     - :xmltag:`rtps_protection_kind` contains the substring :xmlval:`ENCRYPT`
   * - ``0x1 << 1``
     - `IS_DISCOVERY_ENCRYPTED`
     - :xmltag:`discovery_protection_kind` contains the substring :xmlval:`ENCRYPT`
   * - ``0x1 << 2``
     - `IS_LIVELINESS_ENCRYPTED`
     - :xmltag:`liveliness_protection_kind` contains the substring :xmlval:`ENCRYPT`
   * - ``0x1 << 3``
     - `IS_RTPS_ORIGIN_AUTHENTICATED`
     - :xmltag:`rtps_protection_kind` contains the substring :xmlval:`WITH_ORIGIN_AUTHENTICATION`
   * - ``0x1 << 4``
     - `IS_DISCOVERY_ORIGIN_AUTHENTICATED`
     - :xmltag:`discovery_protection_kind` contains the substring :xmlval:`WITH_ORIGIN_AUTHENTICATION`
   * - ``0x1 << 5``
     - `IS_LIVELINESS_ORIGIN_AUTHENTICATED`
     - :xmltag:`liveliness_protection_kind` contains the substring :xmlval:`WITH_ORIGIN_AUTHENTICATION`
   * - ``0x1 << 6``
     - `IS_RTPS_ENCRYPTED_WITH_PSK`
     - :xmltag:`rtps_psk_protection_kind` contains the substring :xmlval:`ENCRYPT`
   * - ``0x1 << 31``
     - `IS_VALID`
     - This bit indicates whether the rest of the ``bitmask`` is valid, so it
       should always be set as long as the |RTI_SP_PRODUCT| are enabled for the |DP| and
       the |RTI_SP_PRODUCT| version is 6.0.0 or above.

.. list-table:: :link_connext_dds_api_cpp2:`DDS_EndpointSecurityProtectionInfo <classrti_1_1topic_1_1trust_1_1EndpointTrustProtectionInfo.html>`.bitmask bit values
   :name: EndpointSecurityAttributes BitValues
   :widths: 10 40 50
   :header-rows: 1
   :class: longtable

   * - bitmask bit value
     - Definition in the |RTI_SP_PRODUCT| (prefix with ``ENDPOINT_SECURITY_ATTRIBUTES_FLAG_``) and string name
     - Configuration in the |GovernanceDoc|
   * - ``0x1 << 0``
     - `IS_READ_PROTECTED`
     - :xmltag:`enable_read_access_control` is :xmlval:`true`
   * - ``0x1 << 1``
     - `IS_WRITE_PROTECTED`
     - :xmltag:`enable_write_access_control` is :xmlval:`true`
   * - ``0x1 << 2``
     - `IS_DISCOVERY_PROTECTED`
     - :xmltag:`enable_discovery_protection` is :xmlval:`true`
   * - ``0x1 << 3``
     - `IS_SUBMESSAGE_PROTECTED`
     - :xmltag:`metadata_protection_kind` is not :xmlval:`NONE`
   * - ``0x1 << 4``
     - `IS_PAYLOAD_PROTECTED`
     - :xmltag:`data_protection_kind` is not :xmlval:`NONE`
   * - ``0x1 << 5``
     - `IS_KEY_PROTECTED`
     - :xmltag:`data_protection_kind` is :xmlval:`ENCRYPT`
   * - ``0x1 << 6``
     - `IS_LIVELINESS_PROTECTED`
     - :xmltag:`enable_liveliness_protection` is :xmlval:`true`
   * - ``0x1 << 31``
     - `IS_VALID`
     - This bit indicates whether the rest of the ``bitmask`` is valid, so it
       should always be set as long as |RTI_SP_PRODUCT| are enabled for the Endpoint's |DP|
       and the |RTI_SP_PRODUCT| version is 6.0.0 or above.

.. list-table:: :link_connext_dds_api_cpp2:`DDS_EndpointSecurityProtectionInfo <classrti_1_1topic_1_1trust_1_1EndpointTrustProtectionInfo.html>`.plugin_bitmask bit values
   :name: PluginEndpointSecurityAttributes BitValues
   :widths: 10 40 50
   :header-rows: 1
   :class: longtable

   * - plugin_bitmask bit value
     - Definition in the |RTI_SP_PRODUCT| (prefix with ``PLUGIN_ENDPOINT_SECURITY_ATTRIBUTES_FLAG_``) and string name
     - Configuration in the |GovernanceDoc|
   * - ``0x1 << 0``
     - `IS_SUBMESSAGE_ENCRYPTED`
     - :xmltag:`metadata_protection_kind` contains the substring :xmlval:`ENCRYPT`
   * - ``0x1 << 1``
     - `IS_PAYLOAD_ENCRYPTED`
     - :xmltag:`data_protection_kind` contains the substring :xmlval:`ENCRYPT`
   * - ``0x1 << 2``
     - `IS_SUBMESSAGE_ORIGIN_AUTHENTICATED`
     - :xmltag:`metadata_protection_kind` contains the substring :xmlval:`WITH_ORIGIN_AUTHENTICATION`
   * - ``0x1 << 31``
     - `IS_VALID`
     - This bit indicates whether the rest of the ``plugin_bitmask`` is valid,
       so it should always be set as long as |RTI_SP_PRODUCT| are enabled for the
       Endpoint's |DP| and the |RTI_SP_PRODUCT| version is 6.0.0 or above.

Relevant types for the Security Algorithms
==========================================

The Core Libraries include some types that are relevant to the algorithms used
in the |RTI_SP_PRODUCT|.

.. list-table:: Mappings between algorithm types in DDS and the |RTI_SP_PRODUCT|
   :name: DdsSpAlgorithmsTypeMapping
   :widths: 50 50
   :header-rows: 1
   :class: longtable

   * - DDS Type
     - |RTI_SP_PRODUCT_HEADING| Type
   * - `DDS_TrustAlgorithmSet`
     - `DDS_CryptoAlgorithmSet`
   * - `DDS_TrustAlgorithmRequirements`
     - `DDS_CryptoAlgorithmRequirements`
   * - :link_connext_dds_api_cpp2:`DDS_ParticipantTrustAlgorithmInfo <classrti_1_1topic_1_1trust_1_1ParticipantTrustAlgorithmInfo.html>`
     - `DDS_ParticipantSecurityAlgorithmInfo`
   * - :link_connext_dds_api_cpp2:`DDS_ParticipantTrustSignatureAlgorithmInfo <classrti_1_1topic_1_1trust_1_1ParticipantTrustSignatureAlgorithmInfo.html>`
     - `DDS_ParticipantSecurityDigitalSignatureAlgorithmInfo`
   * - `DDS_TrustAlgorithmRequirements trust_chain`

       `DDS_TrustAlgorithmRequirements message_auth`
     - `DDS_CryptoAlgorithmRequirements trust_chain`
       `DDS_CryptoAlgorithmRequirements message_auth`
   * - :link_connext_dds_api_cpp2:`DDS_ParticipantTrustKeyEstablishmentAlgorithmInfo <classrti_1_1topic_1_1trust_1_1ParticipantTrustKeyEstablishmentAlgorithmInfo.html>`
     - `DDS_ParticipantSecurityKeyEstablishmentAlgorithmInfo`
   * - `DDS_TrustAlgorithmRequirements shared_secret`
     - `DDS_CryptoAlgorithmRequirements shared_secret`
   * - :link_connext_dds_api_cpp2:`DDS_ParticipantTrustInterceptorAlgorithmInfo <classrti_1_1topic_1_1trust_1_1ParticipantTrustInterceptorAlgorithmInfo.html>`
     - `DDS_ParticipantSecuritySymmetricCipherAlgorithmInfo`
   * - `DDS_TrustAlgorithmSet supported_mask`

       `DDS_TrustAlgorithmSet builtin_endpoints_required_mask`

       `DDS_TrustAlgorithmSet builtin_kx_endpoints_required_mask`

       `DDS_TrustAlgorithmSet user_endpoints_default_required_mask`
     - `DDS_CryptoAlgorithmSet supported_mask`

       `DDS_CryptoAlgorithmSet builtin_endpoints_required_mask`

       `DDS_CryptoAlgorithmSet builtin_kx_endpoints_required_mask`

       `DDS_CryptoAlgorithmSet user_endpoints_default_required_mask`
   * - :link_connext_dds_api_cpp2:`DDS_EndpointTrustAlgorithmInfo <classrti_1_1topic_1_1trust_1_1EndpointTrustAlgorithmInfo.html>`
     - `DDS_EndpointSecurityAlgorithmInfo`
   * - :link_connext_dds_api_cpp2:`DDS_EndpointTrustInterceptorAlgorithmInfo <classrti_1_1topic_1_1trust_1_1EndpointTrustInterceptorAlgorithmInfo.html>`
     - `DDS_EndpointSecuritySymmetricCipherAlgorithmInfo`
   * - `DDS_TrustAlgorithmSet required_mask`
     - `DDS_CryptoAlgorithmSet required_mask`

Read section :ref:`p2_core/cryptography:Discovery of a remote Secure Entity` to
understand how the previous types are used and the consequences of having one
value or another. The following tables list the possible values and the
algorithms associated with each of them:

.. list-table:: Digital signature algorithms bit values
   :name: DigitalSignatureBitValues
   :widths: 10 40 50
   :header-rows: 1
   :class: longtable

   * - Bit value
     - Definition in the |RTI_SP_PRODUCT| (prefix with
       ``RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHM_INFO_BIT_``) and string name
     - Configuration
   * - ``0x1 << 0``
     - `RSASSA_PSS_MGF1SHA256_2048_SHA256`

       `RSASSA-PSS-MGF1SHA256+2048+SHA256`
     - + `message_auth`:

         + `supported_mask`: :xmltag:`digital_signature` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`RSASSA-PSS-MGF1SHA256+2048+SHA256`.

         + `required_mask`: The :property:`authentication.rsa_pss_pad` property
           has a value of `TRUE` or `AUTO`, and the key pair of the |DP| is RSA.

       + `trust_chain`:

         + `supported_mask`: :xmltag:`digital_signature_identity_trust_chain` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`RSASSA-PSS-MGF1SHA256+2048+SHA256`.

         + `required_mask`: The :property:`authentication.rsa_pss_pad` property
           has a value of `TRUE` or `AUTO`, and the signature of the the |DP|'s
           (or one of the authorities in the trust chain) |IdentityCert| is
           `RSASSA-PSS-MGF1SHA256+2048+SHA256`.

   * - ``0x1 << 1``
     - `RSASSA_PKCS1V15_2048_SHA256`

       `RSASSA-PKCS1-V1_5+2048+SHA256`
     - + `message_auth`:

         + `supported_mask`: :xmltag:`digital_signature` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`RSASSA-PKCS1-V1_5+2048+SHA256`.

         + `required_mask`: The :property:`authentication.rsa_pss_pad` property
           has a value of `FALSE` or `AUTO`, and the key pair of the |DP| is
           RSA.

       + `trust_chain`:

         + `supported_mask`: :xmltag:`digital_signature_identity_trust_chain` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`RSASSA-PKCS1-V1_5+2048+SHA256`.

         + `required_mask`: The :property:`authentication.rsa_pss_pad` property
           has a value of `FALSE` or `AUTO`, and the signature type of the
           |DP|'s |IdentityCert| (or the certificate of any of the authorities
           in the trust chain)  is `RSASSA-PKCS1-V1_5+2048+SHA256`.

   * - ``0x1 << 2``
     - `ECDSA_P256_SHA256`

       `ECDSA+P256+SHA256`
     - + `message_auth`:

         + `supported_mask`: :xmltag:`digital_signature` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`ECDSA+P256+SHA256`.

         + `required_mask`: The |DP| has a P-256 elliptic curve key pair.

       + `trust_chain`:

         + `supported_mask`: :xmltag:`digital_signature_identity_trust_chain` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`ECDSA+P256+SHA256`.

         + `required_mask`: The signature type of the |DP|'s |IdentityCert| (or
           the certificate of any of the authorities in the trust chain)  is
           `ECDSA+P256+SHA256`.

   * - ``0x1 << 3``
     - `ECDSA_P384_SHA384`

       `ECDSA+P384+SHA384`
     - + `message_auth`:

         + `supported_mask`: :xmltag:`digital_signature` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`ECDSA+P384+SHA384`.

         + `required_mask`: The |DP| has a P-384 elliptic curve key pair.

       + `trust_chain`:

         + `supported_mask`: :xmltag:`digital_signature_identity_trust_chain` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`ECDSA+P384+SHA384`.

         + `required_mask`: The signature type of the |DP|'s |IdentityCert| (or
           the certificate of any of the authorities in the trust chain)  is
           `ECDSA+P384+SHA384`.

   * - ``0x1 << 16``
     - `EDDSA_ED25519_SHA512`

       `EDDSA+ED25519+SHA512`
     - + `message_auth`:

         + `supported_mask`: :xmltag:`digital_signature` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`EDDSA+ED25519+SHA512`.


         + `required_mask`: The |DP| has a Ed25519 key pair type.

       + `trust_chain`:

         + `supported_mask`: :xmltag:`digital_signature_identity_trust_chain` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`EDDSA+ED25519+SHA512`.

         + `required_mask`: The signature type of the |DP|'s |IdentityCert| (or
           the certificate of any of the authorities in the trust chain) is
           `EDDSA+ED25519+SHA512`.

   * - ``0x1 << 17``
     - `EDDSA_ED448_SHAKE256`

       `EDDSA+ED448+SHAKE256`
     - + `message_auth`:

         + `supported_mask`: :xmltag:`digital_signature` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`EDDSA+ED448+SHAKE256`.


         + `required_mask`: The |DP| has a Ed448 key pair type.

       + `trust_chain`:

         + `supported_mask`: :xmltag:`digital_signature_identity_trust_chain` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`EDDSA+ED448+SHAKE256`.

         + `required_mask`: The signature type of the |DP|'s |IdentityCert| (or
           the certificate of any of the authorities in the trust chain) is
           `EDDSA+ED448+SHAKE256`.

.. list-table:: Key establishment algorithms bit values
   :name: KeyEstablishmentBitValues
   :widths: 10 40 50
   :header-rows: 1
   :class: longtable

   * - Bit value
     - Definition in the |RTI_SP_PRODUCT| (prefix with
       ``RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHM_INFO_BIT_``) and string name
     - Configuration
   * - ``0x1 << 0``
     - `DHE_MODP_2048_256`

       `DHE+MODP-2048-256`
     - + `shared_secret`:

         + `supported_mask`: :xmltag:`key_establishment` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`DHE+MODP-2048-256`.


         + `required_mask`: The
           :property:`authentication.key_establishment_algorithm` property has a
           value of `DHE+MODP-2048-256`.

   * - ``0x1 << 1``
     - `ECDHE_CEUM_P256`

       `ECDHE-CEUM+P256`
     - + `shared_secret`:

         + `supported_mask`: :xmltag:`key_establishment` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`ECDHE-CEUM+P256`.


         + `required_mask`: The
           :property:`authentication.key_establishment_algorithm` property has a
           value of `ECDHE-CEUM+P256` or `AUTO`, and the |DP| has a P-256
           elliptic curve key pair.

   * - ``0x1 << 2``
     - `ECDHE_CEUM_P384`

       `ECDHE-CEUM+P384`
     - + `shared_secret`:

         + `supported_mask`: :xmltag:`key_establishment` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`ECDHE-CEUM+P384`.


         + `required_mask`: The
           :property:`authentication.key_establishment_algorithm` property has a
           value of `ECDHE-CEUM+P384` or `AUTO`, and the |DP| has a
           P-384 elliptic curve key pair.

   * - ``0x1 << 16``
     - `ECDHE_CEUM_X25519`

       `ECDHE-CEUM+X25519`
     - + `shared_secret`:

         + `supported_mask`: :xmltag:`key_establishment` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`ECDHE_CEUM_X25519`.


         + `required_mask`: The
           :property:`authentication.key_establishment_algorithm` property has a
           value of `ECDHE-CEUM+X25519` or `AUTO`, and the |DP| has a Ed25519
           key pair type.

   * - ``0x1 << 17``
     - `ECDHE_CEUM_X448`

       `ECDHE-CEUM+X448`
     - + `shared_secret`:

         + `supported_mask`: :xmltag:`key_establishment` in
           :xmltag:`allowed_security_algorithms` contains
           :xmlval:`ECDHE_CEUM_X448`.


         + `required_mask`: The
           :property:`authentication.key_establishment_algorithm` property has a
           value of `ECDHE-CEUM+X448` or `AUTO`, and the |DP| has a Ed448 key
           pair type.

.. list-table:: Symmetric cipher algorithms bit values
   :name: SymmetricCipherBitValues
   :widths: 10 40 50
   :header-rows: 1
   :class: longtable

   * - Bit value
     - Definition in the |RTI_SP_PRODUCT| (prefix with
       ``RTI_SECURITY_SYMMETRIC_CIPHER_ALGORITHM_INFO_BIT_``) and string name
     - Configuration
   * - ``0x1 << 0``
     - `AES128_GCM`

       `AES128+GCM`
     - + |DP| and |EP| `supported_mask`: :xmltag:`symmetric_cipher` in
         :xmltag:`allowed_security_algorithms` contains
         :xmlval:`AES128+GCM`.

       + |DP| `builtin_endpoints_required_mask`,
         |DP| `builtin_kx_endpoints_required_mask`,
         |DP| `user_endpoints_default_required_mask`, and |EP|
         `required_mask`: The :property:`dds.sec.crypto.symmetric_cipher_algorithm`
         property has a value of :xmlval:`AES128+GCM`.

   * - ``0x1 << 1``
     - `AES256_GCM`

       `AES256+GCM`
     - + |DP| and |EP| `supported_mask`: :xmltag:`symmetric_cipher` in
         :xmltag:`allowed_security_algorithms` contains
         :xmlval:`AES256+GCM`.

       + |DP| `builtin_endpoints_required_mask`,
         |DP| `builtin_kx_endpoints_required_mask`,
         |DP| `user_endpoints_default_required_mask`, and |EP|
         `required_mask`: The :property:`dds.sec.crypto.symmetric_cipher_algorithm`
         property has a value of :xmlval:`AES256+GCM`.

   * - ``0x1 << 30``
     - `AES192_GCM`

       `AES192+GCM`
     - + |DP| and |EP| `supported_mask`: :xmltag:`symmetric_cipher` in
         :xmltag:`allowed_security_algorithms` contains
         :xmlval:`AES192+GCM`.

       + |DP| `builtin_endpoints_required_mask`,
         |DP| `builtin_kx_endpoints_required_mask`,
         |DP| `user_endpoints_default_required_mask`, and |EP|
         `required_mask`: The :property:`dds.sec.crypto.symmetric_cipher_algorithm`
         property has a value of :xmlval:`AES192+GCM`.

The highest bit
(`RTI_SECURITY_CRYPTO_ALGORITHM_INFO_BIT_COMPATIBILITY_MODE`: ``0x1 << 31``) is
always reserved and has a special meaning: it's used to simplify how to check if
two cryptographic algorithm masks are compatible. When the compatibility mode
bit is not set, all algorithms in the mask of required algorithms must be in the
supported mask as well. When the compatibility mode bit is set, the masks will
be compatible as long as one algorithm is both supported and required.
For more information read the note in section
:ref:`p2_core/cryptography:Discovery of a remote Secure Entity`.

.. list-table:: Compatibility mode bit
   :name: CompatibilityModeBitValue
   :widths: 40 10 50
   :header-rows: 1
   :class: longtable

   * - Bit value
     - Definition in the |RTI_SP_PRODUCT| (prefix with
       ``RTI_SECURITY_CRYPTO_ALGORITHM_INFO_BIT_``) and string name
     - Configuration
   * - ``0x1 << 31``
     - `COMPATIBILITY_MODE`

       `PARTIAL_MATCH_ALLOWED`
     - This bit is set only as part of the ``trust_chain.required_mask`` when
       more than one digital signature algorithm in the context of the identity
       trust chain is required. Therefore, it depends on the |IdentityCert|.

Half of the bit range is reserved for algorithms defined in the DDS Security
Specification and the other half (excluding the compatibility mode bit) is
reserved for vendor-specific algorithms. Therefore, if the compatibility mode
bit is not set, matching will fail between DomainParticipants from different
vendors if any of the symmetric cipher required masks has a vendor-specific
bit set (bits between ``0x1U << 16`` and ``0x1U << 30``). If the compatibility
mode bit is set, matching will succeed as long as one of the required symmetric
cipher algorithms is standard.

.. attention::

   The security algorithm masks are not transmitted (to minimize discovery
   overhead) if their contents match the default values for discovery. For more
   information, see
   :ref:`p2_core/cryptography:allowed_security_algorithms (domain_rule)`.