4. Authentication
Authentication is the process of making sure a DomainParticipant is who it claims to be. Loading any 1 security plugins will configure the DomainParticipant to request the plugins to authenticate a newly discovered remote participant before initiating Endpoint Discovery with that participant. Authentication is done via a series of inter-participant challenge and response messages, which are exchanged during a 3-way handshake. These messages perform mutual authentication, so the end result is that this DomainParticipant authenticates the remote DomainParticipant and vice-versa.
Before a DomainParticipant is enabled, the Authentication Plugin associated with the DomainParticipant must be configured with three artifacts:
The Identity CA Certificate, which contains the public key of the Identity CA.
The Private Key of the DomainParticipant.
An Identity Certificate that chains up to the Identity CA. This certificate binds the public key of the DomainParticipant to its subject name.
If the Authentication Plugin fails to verify any of these prerequisites, participant creation fails.
To successfully authenticate a remote participant, that remote participant must present a valid Identity Certificate (this is known as Identity Certificate Validation, which we describe in Identity Certificate Validation) and prove to have access to the private key associated with the Identity Certificate’s public key (by signing challenges during the handshake).
Authentication of the remote participant takes place right after the Participant Discovery phase (see Discovery in the Core Libraries User’s Manual). Secure Endpoint Discovery will only happen between mutually authenticated participants. In other words, if a participant (let’s call it P1) fails to authenticate a different participant (P2), P1 ignores Endpoint Discovery traffic from P2. Otherwise, P1 initiates Endpoint Discovery with P2 after mutual authentication. If a participant fails to authenticate, Connext will try again by initiating a new handshake through the Authentication Plugin.
Each DomainParticipant can optionally specify a certificate revocation list (CRL) to the Authentication Plugin. The CRL is checked for revoked certificates as part of the Identity Certificate Validation (see Identity Certificate Validation). Remote participants presenting a revoked certificate will not be authenticated. This way, you can prevent a compromised DomainParticipant from joining your secure domain by revoking its Identity Certificate and adding it to the CRL.
- 1
Either RTI Security Plugins or custom security plugins. Setting
.load_pluginwill tell the Connext core to call the Authentication Plugin.
4.1. Handshake
To perform mutual authentication, DomainParticipants exchange a series of challenge and response messages in a 3-way handshake. This handshake is the mechanism by which participants verify each other’s identity and establish a Shared Secret. After mutual authentication over an unsecure channel, a Shared Key is derived using the Shared Secret.
Handshake messages are sent over the Authentication Builtin Topic, which allows the messages to be directed to a specific recipient (see Authentication Builtin Topic (ParticipantStatelessMessage)).
The handshake establishes mutual authentication between discovered participants using the RSA or ECDSA digital signature algorithms, and determines a Shared Secret using Diffie-Hellman (DH) or Elliptic Curve Diffie-Hellman (ECDH) key establishment methods.
4.1.1. Message Exchange
Let’s analyze the handshake by examining the messages that two participants (P1 and P2) exchange as part of the authentication:
4.1.1.1. Handshake Request
To initiate the handshake, P1 sends a Handshake Request to P2 that includes:
P1’s Identity Certificate (Cert1), which includes P1’s public key (PubK1)
P1’s Participant data (Pdata1), which includes P1’s DomainParticipantQos and P1’s security attributes
P1’s Permissions Document (Perm1)
A challenge (Challenge1) and a Diffie-Hellman public key (DH1), which P1 randomly generates right before initiating the handshake
4.1.1.2. Handshake Reply
When P2 receives the Handshake Request, it verifies Cert1 and Perm1’s signature. At this point, P2 knows whether P1 has presented a valid Identity Certificate (that chains up to the shared Identity CA) and Permissions Document (signed by the shared Permissions CA). If it did, the handshake continues and P2 sends a Handshake Reply to P1 that includes:
P2’s Identity Certificate (Cert2), which includes P2’s public key (PubK2)
P2’s Participant data (Pdata2), which includes P2’s DomainParticipantQos and P2’s security attributes
P2’s Permissions Document (Perm2)
A challenge (Challenge2) and a Diffie-Hellman public key (DH2), which P2 randomly generates upon reception of a Handshake Request
A signature (Sign2), which P2 generates by signing some of the message contents, including Challenge1 and DH2, with its private key (PrivK2)
4.1.1.3. Handshake Final
When P1 receives the Handshake Reply, it verifies Cert2 and Perm1’s signature, thus verifying whether P2 has presented a valid Identity Certificate (that chains up to the shared Identity CA) and Permissions Document (signed by the shared Permissions CA). P1 also verifies Sign2 against PubK2. Hence, P1 can verify whether Sign2 was generated with PrivK2. At this point, P1 knows whether P2 is the legitimate holder of the private key associated with Cert2. If the verification succeeds, P2 is authenticated and P1 computes the Shared Secret from DH2 and the Diffie-Hellman private key used for DH1. At this point, P1 sends a Handshake Final to P2 that includes:
A signature (Sign1), which P1 generates by signing some of the message contents, including Challenge2 and DH1, with its private key (PrivK1)
When P2 receives this message it verifies Sign1 against PubK1. Now, P2 knows whether P1 is the legitimate holder of the private key associated with Cert1. P1 is now authenticated and P2 computes the Shared Secret from DH1 and the Diffie-Hellman private key used for DH2. At this point, the handshake concludes: P1 and P2 are mutually authenticated and have a Shared Secret they can use to derive the Shared Key they need to communicate securely.
4.1.2. General Considerations
The authentication process is secure, even if the channel where the authentication happens is not secure. As we mentioned earlier, the Handshake Request and Handshake Reply messages include a random challenge. In both cases, the purpose of this challenge is to verify that the remote participant currently holds the private key corresponding to the exchanged certificate. For clarity, let’s analyze how we achieve this using the Handshake Request.
In the Handshake Request, P1 is the challenger participant, and P2 is the challenged participant. (Note that the mechanism used in the Handshake Reply is the same, but P1 and P2 swap roles.) In this first case, P1 sends a random challenge that P2 needs to sign (along with other information) with its private key, sending the result back to P1. Then P1 verifies that the signature corresponds to the public key in P2’s certificate. Since the challenge is a random piece of information unique to the current authentication session, P1 can verify that P2 currently holds the private key corresponding to the public key claimed in the certificate. With this mechanism, it is not possible to capture a valid handshake from a previous authentication session and replay it later without it becoming invalid. Therefore, we can be sure that P2 is the legitimate holder of the exchanged certificate. In other words, this verifies that P2 is who it claims to be.
During the authentication process, things can go wrong. For example, an unauthorized participant may present an invalid certificate, an attacker trying to impersonate one of your participants will be unable to give a valid response to the challenges, or an attacker may try to break the authentication between two legitimate participants by sending invalid responses to challenges in lieu of an authorized participant halfway through the authentication process. An invalid certificate or response to a challenge will result in a VALIDATION_FAILURE for that particular handshake message, but authentication will not fail until it times out. This is to avoid denial-of-service (DoS) attacks where a third party injects messages during an authentication.
If the authentication process fails (because it times out), the participants can fall into one of the following states:
4.1.2.1. Symmetric Authentication Failure
If the authentication process is not completed and fails for both participants (P1 does not authenticate P2, and P2 does not authenticate P1), P1 cleans up all the authentication state of P2 and P2 cleans up all the authentication state of P1, so the authentication can start from scratch.
4.1.2.2. Asymmetric Authentication Failure
Let’s analyze the case where P1 successfully authenticates P2, but P2 did not authenticate P1. This can happen if P1 received the Handshake Reply that was correct, but it couldn’t deliver the Handshake Final (because of a network failure, for example). In this case, P2 cannot start authenticating from scratch because from P1’s perspective, P2 has already authenticated (in other words, P1 has not cleaned up P2’s authentication state).
Asymmetric authentication failure can also happen if authentication succeeds for both participants, then liveliness expires for just one of them.
To solve this problem, by default, P2 periodically sends Authentication Request messages to P1 after a timeout. With an Authentication Request, P2 asks P1 to open a secondary authentication process so it has the opportunity to reauthenticate. If that succeeds, P1 will replace P2’s old authentication state with the new one. At this point, P1 and P2 are mutually authenticated.
For more details, see Re-Authentication.
4.1.3. Identity Certificate Validation
Identity Certificates are signed by a CA trusted by both DomainParticipants. Therefore, DomainParticipants can verify that the received certificate is legitimate. As per the DDS Security Specification, Identity Certificates are in PEM format and may contain a human-readable section above the mandatory section delimited by:
---BEGIN CERTIFICATE---
---END CERTIFICATE---
The human-readable section adds no functionality and is NOT used for validating the certificate. Removing it from the Identity Certificate before the authentication process reduces the size of the messages on the network.
By default beginning in Connext DDS version 6.0.1, the human-readable part of Identity Certificates is stripped when the certificate is loaded. This behavior avoids additional overhead and can be controlled with the boolean property authentication.propagate_simplified_identity_certificate (see Table 4.2).
Identity Certificate Validation is done when this participant receives the first handshake message from a remote participant, and implies multiple checks:
4.1.3.1. Step 1. Verifying the certificate validity on the current date and time
The Security Plugins will check the certificate’s X.509 Validity fields (Not Before and Not After). If the certificate is received outside this time frame (before it becomes valid, or after it has expired), validation fails immediately. Otherwise, the certificate is considered currently valid.
4.1.3.2. Step 2. Verifying that the certificate is not revoked
You can specify a CRL by setting the authentication.crl property (see Table 4.2). By doing this, your DomainParticipant will check the certificate against the revocation list. If the certificate is found to be revoked, validation fails immediately. Note that the revocation list is immutable (it is not exchanged during discovery or handshaking) and changes in the CRL are not enforced until the DomainParticipant using it is deleted and recreated. For further details, refer to Multiple Certificate Revocation Lists.
4.1.3.3. Step 3. Verifying that the Identity CA issued the remote’s Identity Certificate
The local DomainParticipant validates the certificate against the Identity CA specified in the dds.sec.auth.identity_ca property (see Table 4.1). If the issuer of the Identity Certificate is an intermediate CA, you should specify the full certificate chain in the dds.sec.auth.identity_certificate property. In this case, the Identity Certificate will be verified to chain up to the Identity CA, as specified in Identity Certificate Chaining.
If the Identity CA is not currently valid or cannot validate an Identity Certificate,
then the validation will be retried with the alternative certificates specified
in the authentication.alternative_ca_files property (see
Table 4.2). If
none of the alternative CAs are currently valid and can validate the file (or
if you did not set this property), the validation process will fail.
4.2. Authentication Builtin Topic (ParticipantStatelessMessage)
To perform the handshake, DomainParticipants need to exchange directed messages through a unsecure communication channel. For this purpose, the DDS Security specification introduces a new Authentication Builtin Topic, also known as the ParticipantStatelessMessage builtin Topic. This best-effort stateless Topic prevents the sequence-number prediction vulnerability that is present in unsecure reliable protocols.
The Authentication Builtin Topic implements the channel that DomainParticipants need to perform authentication. Data samples exchanged for this Topic include both the handshake messages (see Handshake) and the re-authentication messages (see Re-Authentication).
4.2.1. Fragmentation Support for the Authentication Topic
The Security Plugins support fragmenting Authentication Builtin Topic samples. This is useful in scenarios with a hard limit on the transport maximum message size.
This feature is enabled by default: fragmentation of Authentication Builtin Topic samples will be triggered when sending samples that exceed the message_size_max configured in the transports used by Connext (see Setting Builtin Transport Properties with the PropertyQosPolicy in the Core Libraries User’s Manual).
4.4. Cryptographic Algorithms
The Security Plugins use different cryptographic algorithms for different purposes. Starting with version 7.0.0, the user can modify and select algorithms supported and used by Secure Entity. This section describes the relationship between the digital signature and key establishment algorithms that can be configured in the Authentication Plugin.
In this section, we also describe the relationship between the algorithms that can be configured in the Authentication Plugin and the ParticipantTrustAlgorithmInfo::signature and ParticipantTrustAlgorithmInfo::key_establishment fields, which are used to propagate the used and supported algorithms for a DomainParticipant. A complete list of values can be found in Table 17.7 and Table 17.8.
Note that a Secure Entity may not propagate through discovery the exact list of algorithms listed in the Governance Document. The reason is that the final value for a supported mask is an intersection of the algorithms allowed by the Governance Document and the list of algorithms supported by the DomainParticipant. Remember that the Governance Document is about system-wide security requirements. Even if the Governance Document allows an algorithm, the implementation of the Security Plugins for a DomainParticipant may not support it. For example, the Security Plugins for wolfSSL may support different algorithms than the Security Plugins for OpenSSL.
Finally, this section also defines discovery defaults for every field of the ParticipantBuiltinTopicData::trust_algorithm_info. Discovery defaults are the values that are assumed when no value is propagated through discovery see Discovery of a Remote Secure Entity for more details about discovery.
4.4.1. Digital Signature Algorithms
Digital Signature Algorithms collect algorithms used in the DomainParticipant trust chain as well as for authentication. The following algorithms are supported:
RSASSA-PSS-MGF1SHA256+2048+SHA256
RSASSA-PKCS1-V1_5+2048+SHA256
ECDSA-P256+SHA256
ECDSA-P384+SHA384
EDDSA+ED25519+SHA512 (<< experimental >>)
EDDSA+ED448+SHAKE256 (<< experimental >>)
Digital Signature Algorithms specify four algorithm definitions:
trust_chain.supported_mask: A list of supported trust chain algorithms. The default value is: RSASSA-PSS-MGF1SHA256+2048+SHA256 and ECDSA-P256+SHA256.trust_chain.required_mask: A list of algorithms used in the DomainParticipant’s identity trust chain. Identity Certificate determines which algorithm is used. The default value is: ECDSA-P256+SHA256.message_auth.supported_mask: A list of supported authentication digital signature algorithms. The default value is: RSASSA-PSS-MGF1SHA256+2048+SHA256 and ECDSA-P256+SHA256.message_auth.required_mask: The authentication digital signature algorithm used by a DomainParticipant. Identity Certificate determines which algorithm is used. The default value is: ECDSA-P256+SHA256.
Note
The trust_chain.supported_mask are the list of digital signature
algorithms supported by the DomainParticipant in the context of creating a chain of trust.
This means that they are the algorithms used for verifying the Identity Certificate
against the Identity Certificate Authority. The Security Plugins enforce during
validation of the remote Identity Certificate chain that the actual used digital
signature algorithms are supported.
The message_auth.supported_mask are the list of digital signature algorithms
supported by the DomainParticipant for checking that the remote DomainParticipant is authentic.
These are the algorithms that a DomainParticipant supports for challenging a remote DomainParticipant
to prove that it has the Private Key corresponding to its Identity Certificate.
4.4.2. Key Establishment Algorithms
Key Establishment Algorithms collect algorithms used in key establishment during DomainParticipant authentications. The following algorithms are supported:
DHE-MODP+2048+256
ECDHE-CEUM+P256
ECDHE-CEUM+P384
ECDHE-CEUM+X25519 (<< experimental >>)
ECDHE-CEUM+X448 (<< experimental >>)
Key Establishment Algorithms specify two algorithm definitions:
supported_mask: A list of supported key establishment algorithms. The default value is: DHE-MODP+2048+256 and ECDHE-CEUM+P256.required_mask: Indicates the algorithm the DomainParticipant will use as the key establishment algorithm if the DomainParticipant is the authentication initiator (if not, the algorithm of the other DomainParticipant will be used). It is determined by authentication.key_establishment_algorithm property (see Table 6.8). The default value is: ECDHE-CEUM+P256.
See allowed_security_algorithms (domain_rule) to learn how to configure which of these algorithms are supported.
4.5. Advanced Authentication Concepts
4.5.1. Protecting Participant Discovery
Participant Discovery is sent through an unsecure channel. Consequently, additional mechanisms need to be put in place to make sure the received information comes from a legitimate participant. In the Security Plugins, the mechanism for protecting the Participant Discovery information is known as TrustedState.
Security Plugins TrustedState is an RTI extension to the DDS Security Authentication specification that covers two limitations in the DDS Security specification:
The lack of a standardized mechanism for validating that the Participant Discovery information received by DDS actually matches the information of the authenticated remote DomainParticipant.
Participant Discovery data is immutable after authentication. This prevents functionality such as updating IP addresses. (Only a limitation in DDS Security 1.0, resolved in 1.1.).
Security Plugins TrustedState is a digest of the Participant Discovery data, plus information that unambiguously identifies the current local participant state and the current authentication session. TrustedState is exchanged as part of the authentication process as a vendor extension. More specifically, TrustedState is included as a binary property in the Handshake Reply and Handshake Final messages. Once the authentication completes, involved participants will validate received Participant Discovery information against the received TrustedState. This way, participants can be sure that the received Participant Discovery comes from the authenticated participant.
The Participant Discovery channel is also used to propagate changes in the DomainParticipant’s QoS or in the locators. In order to securely propagate Participant Discovery changes after authenticating the remote participant, the Security Plugins use the participant’s identity private key to sign the Participant Discovery data plus some additional information identifying the local participant state (and which is consistent with the one serialized in the TrustedState). This signature is then serialized as a property in the Participant Discovery data. This way, other participants can validate that the update is legitimate by verifying the received Participant Discovery against the participant’s public key.
Please note that in DDS Security 1.0 (which Connext 5.3.x implements), the DomainParticipantQos for remote DomainParticipants is immutable. To overcome this limitation, 5.3.x uses the TrustedState extension. Non-RTI participants do not implement TrustedState; therefore, they cannot update DomainParticipantQos Discovery information after authentication. This limitation is solved by DDS Security 1.1, which is adopted in Connext 6.0.0+.
To increase compatibility with other vendors, Secure DomainParticipants that use the RTI Security Plugins will successfully authenticate remote participants that do not provide TrustedState. Non-RTI participants should ignore the TrustedState property in the Handshake since it is a vendor extension.
Caution
When the authentication.participant_discovery_protection_key
(<< deprecated >>) property is set (see Table 4.2), the TrustedState mechanism is
disabled. Instead, symmetric cryptography based on the pre-shared key
specified by this property is used to protect the participant announcements’
integrity. Note that, in this scenario, DomainParticipants cannot validate that the
Participant Discovery information received by Connext matches the authenticated remote
DomainParticipants.
Note that the authentication.participant_discovery_protection_key
property is required to use Cloud Discovery Service and the Security Plugins together.
4.5.2. Identity Certificate Chaining
This section assumes you are familiar with the concept of a Certificate Chain, as described in Public Key Infrastructure (PKI).
You may specify a certificate chain in the dds.sec.auth.identity_certificate property (see Table 4.1). You can create the certificate chain by concatenating individual certificates and specifying the concatenated result as a single file or string. The local Identity Certificate will be verified before creating the local DomainParticipant. It will also be sent on the network as part of the handshake. If a certificate chain is specified, then the whole chain will be sent on the network, which may cause significant overhead.
To avoid additional overhead, beginning in Connext version 6.1.0, the human-readable part of Identity Certificates is stripped by default when the certificate is loaded. You can control this behavior with the authentication.propagate_simplified_identity_certificate property (see Table 4.2).
The CRLs specified in the authentication.crl property will be used throughout the verification process (see Table 4.2). This property may contain any number of CRLs, each one signed by either the Identity CA (dds.sec.auth.identity_ca), one of the alternative CAs (authentication.alternative_ca_files), or one of the intermediate CAs in the Identity Certificate chain.
The Identity Certificate will be verified against the Identity CA using the following procedure:
The current certificate is the first certificate in the Identity Certificate chain.
Check that the current certificate is valid for the current date. Otherwise, the verification fails immediately.
If the current certificate is signed and unrevoked by the Identity CA (
dds.sec.auth.identity_ca) or any of the alternative CAs listed inauthentication.alternative_ca_files, then the verification succeeds immediately. Otherwise:If a next certificate exists in the chain and the current certificate is signed and unrevoked by that next certificate, then the next certificate becomes the current certificate.
If none of the certificates in the Identity Certificate chain lead to the Identity CA (or any of the alternative Identity CAs), then the verification fails. For details on certificate validation, see Identity Certificate Validation.
4.5.3. Re-Authentication
The Security Plugins support securely re-authenticating remote participants as described in the DDS Security specification. This is needed in scenarios where there is an asymmetric liveliness loss.
As depicted in Figure 4.1, asymmetric liveliness loss occurs between two participants, P1 and P2, when P1 loses liveliness with P2. When this happens, P1 cleans up all the associated state, while P2 still keeps the authenticated state. Because P2 keeps an authenticated state from P1, it will not accept new authentication messages from P1. Without the ability to re-authenticate, asymmetric liveliness loss will lead to communication not recovering. The same occurs in the case of an asymmetric authentication failure. The Security Plugins address this problem by including a re-authentication capability as described in the DDS Security specification.
If P1 has not completed an ongoing authentication with P2 after a specific period, it will send an Authentication Request (dds.sec.auth_request) message that includes a nonce to P2. This message will give a hint to P2 that P1 is pending authentication with P2. This specific period is configured by the property dds.participant.trust_plugins.authentication_request_delay.sec, see Table 4.3.
When P2 receives an Authentication Request message, it will check if it already has a valid completed authentication with P1. If so, that could mean that an asymmetric liveliness loss has occurred. To verify that the Authentication Request is legitimate, the two participants will now conduct a whole authentication process that includes the nonce received as part of the triggering dds.sec.auth_request message. Only if this secondary authentication succeeds, the old state will be removed in P2 and replaced with the new one, allowing discovery to complete again and communication to recover. If this secondary authentication fails, no change will be made in P1 and the old authenticated session will be kept.
Because the old authenticated state is kept until the new authentication has successfully completed, the Security Plugins re-authentication is robust against attackers trying to bring down an existing authentication.
Figure 4.1 Messages Exchanged During the Re-Authentication Process
4.5.4. Dynamic Certificate Revalidation
A valid Identity Certificate or Identity CA may not stay valid forever. When one of them becomes invalid, the Security Plugins should take appropriate action on the corresponding DomainParticipant. Currently, the Security Plugins support taking actions based on a certificate’s expiration time (the Not After X.509 Validity field), and the actions differ between remote DomainParticipants and the local DomainParticipant.
4.5.4.1. Dynamic Certificate Expiration of Remote DomainParticipants
If the Identity Certificate of a remote DomainParticipant is successfully validated during
handshaking (see
Identity Certificate Validation), the Security Plugins note
the earliest expiration time among the chain of certificates that were involved
in the validation. At that time, the Security Plugins performs the
Identity Certificate Validation steps again. If
this revalidation fails, then the Security Plugins will remove the remote DomainParticipant. Note
that the remote DomainParticipant is only removed, not ignored, so it will be allowed to
rejoin the system if it can be recreated with the same GUID and with a valid
Identity Certificate. If the property
dds.participant.trust_plugins.key_revision_max_history_depth is set
to a value other than 0, then the Security Plugins will also create a new
Key Revision (see
Limiting the Usage of Specific Key Material) in
order to render the remote DomainParticipant’s Key Material outdated. If this property is
unset or set to 0, then the Security Plugins will generate this log message at the
ENTITIES category and the ERROR verbosity:
Precondition not met because the participant has not enabled key regeneration using the "dds.participant.trust_plugins.key_revision_max_history_depth" property. You must enable this property to prevent removed or ignored participants from reading your encrypted data or writing data that looks like it came from you!!!
4.5.4.2. Dynamic Certificate Expiration of the Local DomainParticipant
If the Identity Certificate of the local DomainParticipant is successfully validated during DomainParticipant
creation, and the local DomainParticipant is configured with a DomainParticipantListener
and a StatusMask that includes
INVALID_LOCAL_IDENTITY_ADVANCE_NOTICE_STATUS, then
the Security Plugins note the earliest expiration time among the chain of certificates that
were involved in the validation. The Security Plugins subtract the value of the
dds.participant.trust_plugins.certificate_expiration_advance_notice_duration.sec
property from that earliest expiration time. At that notification time,
the Security Plugins perform the Identity Certificate Validation
steps again for the local DomainParticipant. If this revalidation determines that a
certificate has already expired or will expire within the advance notice
duration, then the Security Plugins will notify the user by invoking the
on_invalid_local_identity_status_advance_notice
callback function. After the first notification, the Security Plugins will continue
notifying the user every second until the certificate chain has finally
expired.
Currently, the Security Plugins do not support updating the local DomainParticipant’s Identity Certificate or Identity CA without deleting and recreating the local DomainParticipant.
4.6. Properties for Configuring Authentication
Table 4.1 and Table 4.2 list the properties that you can set for authentication. These properties are configured through the DomainParticipant’s PROPERTY QosPolicy (see QoS Properties).
Property Name |
Property Value Description |
|---|---|
|
Required Identity CA certificate. This certificate is used for verifying the Identity Certificates of local and remote DomainParticipants (see Public Key Infrastructure (PKI)). Two participants that want to securely communicate with each other must use the same Identity CA. You may specify either the file name or the document contents. See the note below for details. String. Default: |
|
Required The private key associated with the first certificate that appears in
You may specify either the file name or the document contents. See the note below for details. String. Default: |
|
Required Identity Certificate signed by the Identity CA. Other participants will request this certificate to verify the identity of the local participant. This is an X.509 certificate in PEM format. You may put a chain of certificates in the Identity Certificate by concatenating individual certificates and specifying the concatenated result as a single file or string. See Identity Certificate Chaining and Public Key Infrastructure (PKI).
String. Default: |
|
Only required if The password used to decrypt the $ openssl req -new -newkey ec:ecdsaparam2 \
-config example2ECdsa.cnf -keyout peer2keyECdsa.pem \
-passout pass:MyPassword -out peer2reqECdsa.pem
you should specify the Base64 encoding of MyPassword, therefore the value of the password property should be If the String. Default: |
Note regarding document format
The Identity CA, Private Key, and Identity Certificate documents in Table 4.1 must be in PEM format. You may specify either the file name or the document contents. If specifying the file name, the property value must have the fully qualified path and name of the file, and a prefix file: (no space after the colon) is optional. If specifying the contents of the document, the property value must have the prefix data:, (no space after the comma), followed by the contents inside the document.
Some examples:
"data:,-----BEGIN CERTIFICATE-----\nabcdef\n-----END CERTIFICATE-----"
"data:,-----BEGIN PRIVATE KEY-----\nabcdef\n-----END PRIVATE KEY-----"
"data:,-----BEGIN CERTIFICATE-----\nabcdef\n-----END CERTIFICATE-----"
Notice that the two \n characters are required.
"file:../../../dds_security/cert/ecdsa01/identities/ecdsa01Peer01Cert.pem"
"C:\Users\Name\dds_security\cert\ecdsa01\identities\ecdsa01Peer01Cert.pem"
Property Name (prefix with |
Property Value Description |
|---|---|
|
Optional The algorithm used to establish the Shared Secret during authentication.
The options are Diffie-Hellman Ephemeral with 2048-bit MODP Group
parameters ( If two participants, that specify different property values, discover each
other, they will use the algorithm that belongs to the participant with
the lower-valued Enum:
Default: |
|
Optional Same as
Enum:
|
|
Optional A comma-separated list of alternative Identity CA Certificates. If the verification of a file fails with the main certificate ( Each of the elements in the list must be the fully qualified path to the certificate file. This property value may optionally contain String. Default: |
|
Optional A Certificate Revocation List to keep track of untrusted X.509 certificates. If If If The document should be in PEM format. You may specify either the file name or the document contents. See the note above for details. This property is immutable: changes in the CRL will not be enforced until the DomainParticipant using the CRL is deleted and recreated. String. Default: |
|
Optional Same as
String. Default: |
|
Optional How to enforce the presence of the X.509 v3 extension This property has three possible values (case-insensitive):
Enum: Default: |
|
Optional If Identity Certificates in PEM format may contain a human-readable section above the mandatory section delimited by: ---BEGIN CERTIFICATE---
---END CERTIFICATE---
The human-readable section adds no functionality and is not protected in any way. Removing it from the Identity Certificate before the authentication process reduces the size of the messages on the network. Boolean. Default: |
|
Optional The format of the private key specified by The value of this property can be one of the following:
Enum: Default: |
|
Optional The kind of padding used when signing and verifying documents. This property has three possible values:
If the value of the property is either If the value of the property is Enum.
Default: |
|
Optional Attention HMAC-Only mode is deprecated and will be replaced in the future with Pre-Shared Key Protection (PSK), described in Pre-Shared Key Protection. PSK for RTI Cloud Discovery Service is currently not supported; it will be supported in the next release. Pre-shared key from which the Security Plugins derive the HMAC Key used to
compute message authentication codes over
ParticipantBuiltinTopicData messages. This key shares many of the
same details as If this property is set, then ParticipantBuiltinTopicData messages will be protected with an HMAC operation. DomainParticipants must set this property to the same value in order to communicate with each other. When this property is set, the DomainParticipants will not interoperate with non-Connext DDS Secure DomainParticipants. The purpose of this pre-shared key is to protect against certain DoS attacks against RTI Cloud Discovery Service. The value of this property is not used to protect any traffic other than ParticipantBuiltinTopicData messages. All other RTPS traffic still gets protected by the standard Cryptography Plugin, which uses dynamically-generated keys that are exchanged after authentication completes. This property takes effect regardless of the value of
If RTI Cloud Discovery Service is using the Security Plugins, then this property is required by all the DomainParticipants in the Domain. For more information, please refer to Security Considerations when Using Cloud Discovery Service. String. Since this key is provided as a String, it is recommended that you take the appropriate measures to protect any configuration XML file containing this key, or alternatively to securely retrieve and set up this property programmatically. Default: not set |
|
Optional << EXPERIMENTAL >> Configures whether to enable custom cryptographic algorithms for the Authentication plugin. When enabled, the Security Plugins will enable additional digital signature and key establishment algorithms that are not part of the DDS Security specification (EDDSA+ED25519+SHA512, EDDSA+ED448+SHAKE256, ECDHE-CEUM+X25519, ECDHE-CEUM+X448). Currently only supported in combination with OpenSSL: this property will have no effect when used in combination with wolfSSL. Two DomainParticipants with different configurations of this property will still interoperate as long as neither of them is using one of the custom algorithms. Default: |
|
Optional Configures whether to set custom crypto library (e.g., OpenSSL) allocators. When enabled (not the default), the Security Plugins will configure custom allocator functions (alloc, realloc, free) to the loaded crypto library with the goal of reducing memory fragmentation at the cost of a minimum performance impact. This is currently only supported in combination with OpenSSL. This property is only effective the first time a DomainParticipant loads the Security Plugins within the same process: subsequent DomainParticipant creations will ignore this property and leave the existing configuration unchanged. Moreover, this property is only effective if no allocation has been done with the crypto library builtin allocators before the Security Plugins have been loaded, otherwise a warning will be logged and no change will be made. For example, if you are using a dynamically linked VxWorks application and the kernel has the IPCRYPTO component, then the kernel will make some allocations at startup, and this property will not be effective. Important: Since the allocator functions live within the Security Plugins library, your application must not make any calls to the crypto library once the Security Plugins have been unloaded from memory. If your application uses heap monitoring: You should call
Default: |
- 2
Assuming you used
com.rti.serv.secureas the alias to load the plugin. If not, change the prefix to match the string used withcom.rti.serv.load_plugins, followed by the.character.
4.6.1. Configuration Properties Affecting Any Authentication Plugin
Table 4.3 lists a set of properties that are not exclusive to the shipped Security Plugins, but that will affect any Authentication Plugin.
Property Name (prefix with |
Property Value Description |
|---|---|
|
Optional Controls the maximum time (in seconds) that an ongoing authentication can remain without completing. After this timeout expires, the authentication process is cancelled, and associated resources are released. For more details, see General Considerations. A DomainParticipant should set its own Integer: Default: |
|
Optional Controls the delay (in seconds) before sending an Authentication Request to the remote participant. For more information, please see Re-Authentication. Integer: Default: |
|
Optional Controls the timeout (in seconds) for authentication negotiations started from an authentication request message. Integer: Default: |
|
Optional Controls how much time (in seconds) in advance the on_invalid_local_identity_status_advance_notice DomainParticipantListener callback function should notify the user when the local DomainParticipant’s Identity Certificate or Identity CA is about to expire. For more information, please see Dynamic Certificate Expiration of the Local DomainParticipant. Integer: Default: |
4.6.2. Configuration Properties Affecting Connext DDS Core Libraries Behavior
Table 4.4 lists other properties affecting the Connext Core Libraries’ behavior.
Property Name |
Property Value Description |
|---|---|
|
Optional If Boolean. Default: |