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:

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