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 DDS 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 DDS 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 a 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 performs mutual authentication between discovered participants using the RSA or ECDSA digital signature algorithms, and establishes a Shared Secret using Diffie-Hellman (DH) or Elliptic Curve Diffie-Hellman (ECDH) key agreement 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 File (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 File (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 File (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 File (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 every 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.
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 cannot validate an Identity Certificate, 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 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 DDS (see Setting Builtin Transport Properties with the PropertyQosPolicy in the Core Libraries User’s Manual).
4.4. Advanced Authentication Concepts¶
4.4.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 DDS 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 DDS 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 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 DDS 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.4.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 DDS 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.4.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. 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 prefix file: (no space after the colon), followed by the fully qualified path and name of the file. 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"
Property Name (prefix with |
Property Value Description |
|---|---|
|
Optional The algorithm used to establish the Shared Secret during authentication. The options are If two participants discover each other and they specify different values for this algorithm, the algorithm that is used is the one that belongs to the participant with the lower-valued Enum: Default: |
|
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. The value is a boolean that means:
This property takes effect only on certificate authorities that use RSA. All of the DomainParticipants in the system must set this property to the same value in order to communicate with each other. Boolean. Default: |
|
Optional Pre-shared key from which 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 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 |
- 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.5.1. Configuration Properties Affecting Connext DDS Core Libraries Behavior¶
Table 4.3 lists a set of properties that are not exclusive to the shipped Security Plugins, but that will affect any Authentication Plugin. Table 4.4 lists other properties affecting the Connext DDS Core Libraries’ behavior.
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: |
Property Name |
Property Value Description |
|---|---|
|
Optional If Boolean. Default: |