15. Relevant Connext APIs

15.1. Relevant functions

The Core Libraries include some API functions that are relevant to the Security Plugins.

15.1.1. banish_ignored_participants

This method complements ignore_participant, which prevents the local DomainParticipant from processing traffic from the remote DomainParticipant. When security is enabled, this method prevents already ignored remote DomainParticipants from processing traffic from the local DomainParticipant by implementing the key regeneration and redistribution capabilities described in the section Limiting the Usage of Specific Key Material.

15.1.2. discovered_participant_subject_name

This method works almost as documented in the RTI Connext Modern C++ API DomainParticipant Class Reference. The main difference is that when security is enabled, this method retrieves the Identity Certificate’s subject name (see Identity Certificates) instead of the 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:

OpenSSL

wolfSSL

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

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

If the discovered DomainParticipant has not completed authentication, then DDS_RETCODE_NO_DATA is the result.

15.1.3. discovered_participants_from_subject_name

This method works almost as documented in the RTI Connext Modern C++ API DomainParticipant Class Reference. The main difference is that when security is enabled, this method takes as an input the Identity Certificate’s subject name (see Identity Certificates) instead of the participant_name.name. As a consequence, the subject name input may not be NULL or malformed (e.g., with attributes that don’t exist according to RFC 4514). With this functionality, Security Plugins bridges the gap between InstanceHandle_t and subject names. For example, if you know the subject name of a discovered DomainParticipant 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 ignore_participant.

If a discovered DomainParticipant 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 NULL or malformed, this method returns DDS_RETCODE_BAD_PARAMETER.

15.1.4. discovered_participant_data

This method works as documented in the RTI Connext Modern C++ API DomainParticipant Class Reference. The returned participant data contains security information about the remote DomainParticipant. This information is in the trust_info and trust_algorithms members of the participant builtin topic data, which have a type of ParticipantTrustInfo and ParticipantTrustAlgorithms.

The equivalent APIs for the Endpoints (matched_publication_data and 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 OMG DDS Security specification. 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 Secure DomainParticipants (or Secure Endpoints) in sections allowed_security_algorithms (domain_rule) and Discovery of a Remote Secure Entity of this User’s Manual.

15.2. Relevant types

The Core Libraries include some types that are relevant to the Security Plugins.

Table 15.1 Mappings between Types in DDS and in the Security Plugins

DDS Type

Security Plugins Type

ParticipantTrustInfo::plugin_bitmask

DDS_PluginParticipantSecurityAttributesMask plugin_participant_attributes

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
Table 15.2 Digital signature algorithms bit values

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
Table 15.3 Key establishment algorithms bit values

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
Table 15.4 Symmetric cipher algorithms bit values

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.