17. Relevant Connext APIs

17.1. Relevant functions

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

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

Note

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

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

OpenSSLwolfSSL

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.

Note

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

17.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, the Security Plugins bridge 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.

Note

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

17.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_protection_info and trust_algorithm_info members of the participant builtin topic data, which have a type of ParticipantTrustProtectionInfo and ParticipantTrustAlgorithmInfo.

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

17.1.5. on_invalid_local_identity_status_advance_notice

This function is a DomainParticipantListener callback. It gets invoked when the local DomainParticipant’s Identity Certificate or Identity CA has already expired or will expire within the duration specified by the dds.participant.trust_plugins.certificate_expiration_advance_notice_duration.sec property. For more information, please see Dynamic Certificate Expiration of the Local DomainParticipant.

17.2. Relevant types for the Governance Document

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

Table 17.1 Mappings between types in DDS and the Security Plugins

DDS Type	Security Plugins Type
DDS_ParticipantTrustProtectionInfo	DDS_ParticipantSecurityProtectionInfo
DDS_ParticipantTrustAttributesMask bitmask	DDS_ParticipantSecurityAttributesMask participant_attributes
DDS_PluginParticipantTrustAttributesMask plugin_bitmask	DDS_PluginParticipantSecurityAttributesMask plugin_participant_attributes
DDS_PluginParticipantTrustAttributesMask	DDS_PluginParticipantSecurityAttributesMask
DDS_EndpointTrustProtectionInfo	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

Table 17.2 DDS_ParticipantSecurityProtectionInfo.bitmask bit values

bitmask bit value	Definition in the Security Plugins (prefix with PARTICIPANT_SECURITY_ATTRIBUTES_FLAG_) and string name	Configuration
0x1 << 0	IS_RTPS_PROTECTED	Governance Document rtps_protection_kind is not NONE
0x1 << 1	IS_DISCOVERY_PROTECTED	Governance Document discovery_protection_kind is not NONE
0x1 << 2	IS_LIVELINESS_PROTECTED	Governance Document liveliness_protection_kind is not NONE
0x1 << 3	ARE_KEY_REVISIONS_ENABLED	PropertyQosPolicy dds.participant.trust_plugins.key_revision_max_history_depth is not 0
0x1 << 4	IS_RTPS_PROTECTED_WITH_PRESHARED_KEY	Governance Document rtps_preshared_secret_protection_kind is not 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 Security Plugins are enabled for the DomainParticipant and the Security Plugins version is 6.0.0 or above.

Table 17.3 DDS_ParticipantSecurityProtectionInfo.plugin_bitmask bit values

plugin_bitmask bit value	Definition in the Security Plugins (prefix with PLUGIN_PARTICIPANT_SECURITY_ATTRIBUTES_FLAG_) and string name	Configuration in the Governance Document
0x1 << 0	IS_RTPS_ENCRYPTED	rtps_protection_kind contains the substring ENCRYPT
0x1 << 1	IS_DISCOVERY_ENCRYPTED	discovery_protection_kind contains the substring ENCRYPT
0x1 << 2	IS_LIVELINESS_ENCRYPTED	liveliness_protection_kind contains the substring ENCRYPT
0x1 << 3	IS_RTPS_ORIGIN_AUTHENTICATED	rtps_protection_kind contains the substring WITH_ORIGIN_AUTHENTICATION
0x1 << 4	IS_DISCOVERY_ORIGIN_AUTHENTICATED	discovery_protection_kind contains the substring WITH_ORIGIN_AUTHENTICATION
0x1 << 5	IS_LIVELINESS_ORIGIN_AUTHENTICATED	liveliness_protection_kind contains the substring WITH_ORIGIN_AUTHENTICATION
0x1 << 6	IS_RTPS_ENCRYPTED_WITH_PRESHARED_KEY	rtps_preshared_secret_protection_kind contains the substring 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 Security Plugins are enabled for the DomainParticipant and the Security Plugins version is 6.0.0 or above.

Table 17.4 DDS_EndpointSecurityProtectionInfo.bitmask bit values

bitmask bit value	Definition in the Security Plugins (prefix with ENDPOINT_SECURITY_ATTRIBUTES_FLAG_) and string name	Configuration in the Governance Document
0x1 << 0	IS_READ_PROTECTED	enable_read_access_control is true
0x1 << 1	IS_WRITE_PROTECTED	enable_write_access_control is true
0x1 << 2	IS_DISCOVERY_PROTECTED	enable_discovery_protection is true
0x1 << 3	IS_SUBMESSAGE_PROTECTED	metadata_protection_kind is not NONE
0x1 << 4	IS_PAYLOAD_PROTECTED	data_protection_kind is not NONE
0x1 << 5	IS_KEY_PROTECTED	data_protection_kind is ENCRYPT
0x1 << 6	IS_LIVELINESS_PROTECTED	enable_liveliness_protection is 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 Security Plugins are enabled for the Endpoint’s DomainParticipant and the Security Plugins version is 6.0.0 or above.

Table 17.5 DDS_EndpointSecurityProtectionInfo.plugin_bitmask bit values

plugin_bitmask bit value	Definition in the Security Plugins (prefix with PLUGIN_ENDPOINT_SECURITY_ATTRIBUTES_FLAG_) and string name	Configuration in the Governance Document
0x1 << 0	IS_SUBMESSAGE_ENCRYPTED	metadata_protection_kind contains the substring ENCRYPT
0x1 << 1	IS_PAYLOAD_ENCRYPTED	data_protection_kind contains the substring ENCRYPT
0x1 << 2	IS_SUBMESSAGE_ORIGIN_AUTHENTICATED	metadata_protection_kind contains the substring 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 Security Plugins are enabled for the Endpoint’s DomainParticipant and the Security Plugins version is 6.0.0 or above.

17.3. Relevant types for the Security Algorithms

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

Table 17.6 Mappings between algorithm types in DDS and the Security Plugins

DDS Type	Security Plugins Type
DDS_TrustAlgorithmSet	DDS_CryptoAlgorithmSet
DDS_TrustAlgorithmRequirements	DDS_CryptoAlgorithmRequirements
DDS_ParticipantTrustAlgorithmInfo	DDS_ParticipantSecurityAlgorithmInfo
DDS_ParticipantTrustSignatureAlgorithmInfo	DDS_ParticipantSecurityDigitalSignatureAlgorithmInfo
DDS_TrustAlgorithmRequirements trust_chain DDS_TrustAlgorithmRequirements message_auth	DDS_CryptoAlgorithmRequirements trust_chain DDS_CryptoAlgorithmRequirements message_auth
DDS_ParticipantTrustKeyEstablishmentAlgorithmInfo	DDS_ParticipantSecurityKeyEstablishmentAlgorithmInfo
DDS_TrustAlgorithmRequirements shared_secret	DDS_CryptoAlgorithmRequirements shared_secret
DDS_ParticipantTrustInterceptorAlgorithmInfo	DDS_ParticipantSecuritySymmetricCipherAlgorithmInfo
DDS_TrustAlgorithmSet supported_mask DDS_TrustAlgorithmSet builtin_endpoints_required_mask DDS_TrustAlgorithmSet builtin_kx_endpoints_required_mask	DDS_CryptoAlgorithmSet supported_mask DDS_CryptoAlgorithmSet builtin_endpoints_required_mask DDS_CryptoAlgorithmSet builtin_kx_endpoints_required_mask
DDS_EndpointTrustAlgorithmInfo	DDS_EndpointSecurityAlgorithmInfo
DDS_EndpointTrustInterceptorAlgorithmInfo	DDS_EndpointSecuritySymmetricCipherAlgorithmInfo
DDS_TrustAlgorithmSet required_mask	DDS_CryptoAlgorithmSet required_mask

Read section 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:

Table 17.7 Digital signature algorithms bit values

Bit value	Definition in the Security Plugins (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: digital_signature in allowed_security_algorithms contains RSASSA-PSS-MGF1SHA256+2048+SHA256. required_mask: The authentication.rsa_pss_pad property has a value of TRUE, or AUTO and the key pair of the DomainParticipant is RSA. trust_chain: supported_mask: digital_signature_identity_trust_chain in allowed_security_algorithms contains RSASSA-PSS-MGF1SHA256+2048+SHA256. required_mask: The authentication.rsa_pss_pad property has a value of TRUE, or AUTO and the signature of the the DomainParticipant’s (or one of the authorities in the trust chain) Identity Certificate is RSASSA-PSS-MGF1SHA256+2048+SHA256.
0x1 << 1	RSASSA_PKCS1V15_2048_SHA256 RSASSA-PKCS1-V1_5+2048+SHA256	message_auth: supported_mask: digital_signature in allowed_security_algorithms contains RSASSA-PKCS1-V1_5+2048+SHA256. required_mask: The authentication.rsa_pss_pad property has a value of FALSE, or AUTO and the key pair of the DomainParticipant is RSA. trust_chain: supported_mask: digital_signature_identity_trust_chain in allowed_security_algorithms contains RSASSA-PKCS1-V1_5+2048+SHA256. required_mask: The authentication.rsa_pss_pad property has a value of FALSE, or AUTO and the signature type of the DomainParticipant’s Identity Certificate (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: digital_signature in allowed_security_algorithms contains ECDSA+P256+SHA256. required_mask: The DomainParticipant has a P-256 elliptic curve key pair. trust_chain: supported_mask: digital_signature_identity_trust_chain in allowed_security_algorithms contains ECDSA+P256+SHA256. required_mask: The signature type of the DomainParticipant’s Identity Certificate (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: digital_signature in allowed_security_algorithms contains ECDSA+P384+SHA384. required_mask: The DomainParticipant has a P-384 elliptic curve key pair. trust_chain: supported_mask: digital_signature_identity_trust_chain in allowed_security_algorithms contains ECDSA+P384+SHA384. required_mask: The signature type of the DomainParticipant’s Identity Certificate (or the certificate of any of the authorities in the trust chain) is ECDSA+P384+SHA384.
0x1 << 30	CUSTOM CUSTOM	message_auth: supported_mask: digital_signature in allowed_security_algorithms contains a value not included in the DDS Security Specification: EDDSA_ED25519_SHA512 or EDDSA_ED448_SHAKE256. required_mask: The DomainParticipant has a key pair type not included in the DDS Security Specification (Ed25519 or Ed448 key pairs). trust_chain: supported_mask: digital_signature_identity_trust_chain in allowed_security_algorithms contains a value not included in the DDS Security Specification: EDDSA_ED25519_SHA512 or EDDSA_ED448_SHAKE256 required_mask: The signature type of the DomainParticipant’s Identity Certificate (or the certificate of any of the authorities in the trust chain) is not included in the DDS Security Specification (EDDSA+ED25519+SHA512 or EDDSA+ED448+SHAKE256).

Table 17.8 Key establishment algorithms bit values

Bit value	Definition in the Security Plugins (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: key_establishment in allowed_security_algorithms contains DHE+MODP-2048-256. required_mask: The 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: key_establishment in allowed_security_algorithms contains ECDHE-CEUM+P256. required_mask: The authentication.key_establishment_algorithm property has a value of ECDHE-CEUM+P256, or a value of AUTO and the DomainParticipant has a P-256 elliptic curve key pair.
0x1 << 2	ECDHE_CEUM_P384 ECDHE-CEUM+P384	shared_secret: supported_mask: key_establishment in allowed_security_algorithms contains ECDHE-CEUM+P384. required_mask: The authentication.key_establishment_algorithm property has a value of ECDHE-CEUM+P384, or a value of AUTO and the DomainParticipant has a P-384 elliptic curve key pair.
0x1 << 30	CUSTOM CUSTOM	shared_secret: supported_mask: key_establishment in allowed_security_algorithms contains a value not included in the DDS Security Specification: ECDHE_CEUM_X25519 or ECDHE_CEUM_X448. required_mask: The authentication.key_establishment_algorithm property has a value of ECDHE-CEUM+X25519, or a value of ECDHE-CEUM+X448, or a value of AUTO and the DomainParticipant has a key pair type not included in the DDS Security Specification (Ed25519 or Ed448 key pairs).

Table 17.9 Symmetric cipher algorithms bit values

Bit value	Definition in the Security Plugins (prefix with RTI_SECURITY_SYMMETRIC_CIPHER_ALGORITHM_INFO_BIT_) and string name	Configuration
0x1 << 0	AES128_GCM AES128+GCM	DomainParticipant and Endpoint supported_mask: symmetric_cipher in allowed_security_algorithms contains AES128+GCM. DomainParticipant builtin_endpoints_required_mask, DomainParticipant builtin_kx_endpoints_required_mask, and Endpoint required_mask: The cryptography.encryption_algorithm property has a value of AES128+GCM.
0x1 << 1	AES256_GCM AES256+GCM	DomainParticipant and Endpoint supported_mask: symmetric_cipher in allowed_security_algorithms contains AES256+GCM. DomainParticipant builtin_endpoints_required_mask, DomainParticipant builtin_kx_endpoints_required_mask, and Endpoint required_mask: The cryptography.encryption_algorithm property has a value of AES256+GCM.
0x1 << 30	CUSTOM CUSTOM	DomainParticipant and Endpoint supported_mask: symmetric_cipher in allowed_security_algorithms contains AES192+GCM. DomainParticipant builtin_endpoints_required_mask, DomainParticipant builtin_kx_endpoints_required_mask, and Endpoint required_mask: The cryptography.encryption_algorithm property has a value of 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 Discovery of a Remote Secure Entity.

Table 17.10 Compatibility mode bit

Bit value	Definition in the Security Plugins (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 Identity Certificate.

Note

We use the custom bit to represent any custom security algorithm in a category. The RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHM_INFO_BIT_EDDSA_ED25519_SHA512, and RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHM_INFO_BIT_EDDSA_ED448_SHAKE256 definitions map to RTI_SECURITY_DIGITAL_SIGNATURE_ALGORITHM_INFO_BIT_CUSTOM. The RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHM_INFO_BIT_ECDHE_CEUM_X25519, and RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHM_INFO_BIT_ECDHE_CEUM_X448 definitions map to RTI_SECURITY_KEY_ESTABLISHMENT_ALGORITHM_INFO_BIT_CUSTOM. RTI_SECURITY_SYMMETRIC_CIPHER_ALGORITHM_INFO_BIT_AES192_GCM maps to RTI_SECURITY_SYMMETRIC_CIPHER_ALGORITHM_INFO_BIT_CUSTOM.

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 allowed_security_algorithms (domain_rule).