.. include:: ../vars.rst .. _chapter-apis: ********************* Relevant Connext APIs ********************* Relevant functions ================== The Core Libraries include some API functions that are relevant to the |SP|. :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`. :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 `. 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, then DDS_RETCODE_NO_DATA is the result. :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 `. 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 `_). With this functionality, |SP| bridges 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 using "RTPS-HMAC-Only", this method returns DDS_RETCODE_UNSUPPORTED. Otherwise, if the subject name input is :property:`NULL` or malformed, this method returns DDS_RETCODE_BAD_PARAMETER. :property:`discovered_participant_data` --------------------------------------- This method works as documented in the :link_connext_dds_api_cpp2:`RTI Connext Modern C++ API DomainParticipant Class Reference `. The returned participant data contains security information about the remote |DP|. This information is in the `trust_info` and `trust_algorithms` members of the :link_connext_dds_api_cpp2:`participant builtin topic data `, which have a type of :link_connext_dds_api_cpp2:`ParticipantTrustInfo ` and :link_connext_dds_api_cpp2:`ParticipantTrustAlgorithms `. The equivalent APIs for the |EPs| (:link_connext_dds_api_cpp2:`matched_publication_data ` and :link_connext_dds_api_cpp2:`matched_subscription_data `) also return data that has the `trust_info` and `trust_algorithms` information associated with them. The contents of the `trust_info` participant and endpoint data structures are according to the descriptions in the `ParticipantSecurityInfo` and `EndpointSecurityInfo` of the :link_external_security_spec:`OMG DDS Security specification <1.1>`. You can learn more about the contents of the `trust_algorithms` 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. Relevant types ============== The Core Libraries include some types that are relevant to the |SP|. .. list-table:: Mappings between Types in DDS and in the Security Plugins :name: DdsSpTypeMapping :widths: 50 50 :header-rows: 1 :class: longtable * - DDS Type - Security Plugins Type * - :link_connext_dds_api_cpp2:`ParticipantTrustInfo::plugin_bitmask ` - `DDS_PluginParticipantSecurityAttributesMask plugin_participant_attributes` * - :link_connext_dds_api_cpp2:`ParticipantTrustAlgorithms ` - `DDS_ParticipantSecurityAlgorithms` * - `DDS_ParticipantTrustSignatureAlgorithms` - `DDS_ParticipantSignatureAlgorithms` * - `DDS_TrustSignatureMask trust_chain_supported_mask` `DDS_TrustSignatureMask trust_chain_used_mask` `DDS_TrustSignatureMask auth_supported_mask` `DDS_TrustSignatureBit auth_used_bit` - `DDS_DigitalSignatureMask trust_chain_supported_mask` `DDS_DigitalSignatureMask trust_chain_used_mask` `DDS_DigitalSignatureMask auth_supported_mask` `DDS_DigitalSignatureBit auth_used_bit` * - `DDS_TrustSignatureMask` - `DDS_DigitalSignatureMask` * - `DDS_TrustSignatureBit` - `DDS_DigitalSignatureBit` * - `DDS_ParticipantKeyEstablishmentAlgorithms` - `DDS_ParticipantTrustKeyEstablishmentAlgorithms` * - `DDS_TrustKeyEstablishmentMask supported_mask` `DDS_TrustKeyEstablishmentBit preferred_bit` - `DDS_KeyEstablishmentMask supported_mask` `DDS_KeyEstablishmentBit preferred_bit` * - `DDS_TrustKeyEstablishmentMask` - `DDS_KeyEstablishmentMask` * - `DDS_TrustKeyEstablishmentBit` - `DDS_KeyEstablishmentBit` * - `DDS_ParticipantTrustInterceptorAlgorithms` - `DDS_ParticipantSymmetricCipherAlgorithms` * - `DDS_TrustInterceptorMask supported_mask` `DDS_TrustInterceptorBit builtin_endpoints_used_bit` `DDS_TrustInterceptorBit builtin_endpoints_key_exchange_used_bit` - `DDS_SymmetricCipherMask supported_mask` `DDS_SymmetricCipherBit builtin_endpoints_used_bit` `DDS_SymmetricCipherBit builtin_endpoints_key_exchange_used_bit` * - `DDS_TrustInterceptorMask` - `DDS_SymmetricCipherMask` * - `DDS_TrustInterceptorBit` - `DDS_SymmetricCipherBit` .. list-table:: Digital signature algorithms bit values :name: DigitalSignatureBitValues :widths: 50 50 :header-rows: 1 :class: longtable * - Definition in the Security Plugins - Bit value * - `RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHMS_BIT_RSASSA_PSS_MGF1SHA256_2048_SHA256` - ``0x1 << 0`` * - `RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHMS_BIT_RSASSA_PKCS1V15_2048_SHA256` - ``0x1 << 1`` * - `RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHMS_BIT_ECDSA_P256_SHA256` - ``0x1 << 2`` * - `RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHMS_BIT_ECDSA_P384_SHA384` - ``0x1 << 3`` * - `RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHMS_BIT_CUSTOM` - ``0x1 << 31`` .. list-table:: Key establishment algorithms bit values :name: KeyEstablishmentBitValues :widths: 50 50 :header-rows: 1 :class: longtable * - Definition in the Security Plugins - Bit value * - `RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHMS_BIT_DHE_MODP_2048_256` - ``0x1 << 0`` * - `RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHMS_BIT_ECDHE_CEUM_P256` - ``0x1 << 1`` * - `RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHMS_BIT_ECDHE_CEUM_P384` - ``0x1 << 2`` * - `RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHMS_BIT_CUSTOM` - ``0x1 << 31`` .. list-table:: Symmetric cipher algorithms bit values :name: SymmetricCipherBitValues :widths: 50 50 :header-rows: 1 :class: longtable * - Definition in the Security Plugins - Bit value * - `RTI_SECURITY_SYMMETRIC_CIPHER_ALGORITHMS_BIT_AES128_GCM` - ``0x1 << 0`` * - `RTI_SECURITY_SYMMETRIC_CIPHER_ALGORITHMS_BIT_AES256_GCM` - ``0x1 << 1`` * - `RTI_SECURITY_SYMMETRIC_CIPHER_ALGORITHMS_BIT_CUSTOM` - ``0x1 << 31`` .. note:: We use the custom bit to represent any custom security algorithm in a category. The `RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHMS_BIT_EDDSA_ED25519_SHA512`, and `RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHMS_BIT_EDDSA_ED448_SHAKE256` definitions map to RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHMS_BIT_CUSTOM. The `RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHMS_BIT_ECDHE_CEUM_X25519`, and `RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHMS_BIT_ECDHE_CEUM_X448` definitions map to `RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHMS_BIT_CUSTOM`. `RTI_SECURITY_SYMMETRIC_CIPHER_ALGORITHMS_BIT_AES192_GCM` maps to `RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHMS_BIT_CUSTOM`.