6. Cryptography¶
6.1. Introduction¶
Cryptography is the process of making sure no adversaries can manipulate or eavesdrop on communication. The Security Plugins cover this process by means of the Cryptography Plugin. To prevent adversaries from manipulating messages, the Cryptography Plugin appends a message authentication code (MAC) to the message being protected, therefore protecting its integrity. To prevent eavesdropping, the Cryptography Plugin can additionally encrypt the message, protecting its confidentiality.
Definitions
The Cryptography Plugin defines multiple protection levels that are applied to different parts of your communication. By “protect a message”, we refer to applying any of these protections to any particular part of your communication before sending it out. In other words, “to protect” implies “to perform the MAC cryptographic operations” – when data integrity is protected; or “to perform the encrypt and MAC cryptographic operations” – when both data integrity and data confidentiality are protected.
On the receiver side, we will “validate” a message to verify it was not manipulated – when data integrity is protected. We may also need to “decrypt” a message the sender protected against eavesdroppers – when data confidentiality is protected. Therefore, “validate (and potentially decrypt)” is equivalent to “verify the MAC (and decrypt, only if the message was encrypted)”.
With the Security Plugins, you can specify a different level of protection to each of your Topics (see Topic-Level Rules). For example, you can protect the data integrity of a particular Topic by setting the protection kind associated with that Topic to SIGN
in the Governance Document. If the data sent on that Topic should also be protected from potential eavesdropping, you can additionally protect its confidentiality by setting its protection kind to ENCRYPT
. This allows you to protect each of your Topics with the level of protection that it requires. You can also leave some of your Topics unprotected by setting its protection kind to NONE
, which could be useful to achieve compatibility with unsecure parts of your system or to save resources.
Secure DomainParticipants, Secure DataWriters, and Secure DataReaders use symmetric cryptography to protect the messages they send. Each of these Secure Entities is associated with different cryptographic material, preventing unauthorized Entities from participating in secure communication (see Secure Entities). For example, when you create a Secure DataWriter, some keys are associated with it. We call these keys Key Material, and the contents of Key Material are described in Local Sender’s Key Material. By only sharing its Key Material with authorized DataReaders, your Secure DataWriter makes sure that only these Secure DataReaders can read that information. This scheme, combined with the fact that you can define different protection levels for your DDS Entities based on DDS attributes (e.g., domain, topic name), provides granular security.
The Cryptography Plugin also puts in place a mechanism to prevent insiders from pretending to be a different entity. For instance, consider a DataReader that legitimately subscribes to a DataWriter for a particular Topic. Since symmetric encryption is used to protect data, the DataReader could potentially use the DataWriter’s key to send arbitrary samples, thus impersonating it. DataWriters can avoid this situation by protecting samples with Origin Authentication Protection (see Origin Authentication Protection).
6.1.1. Cryptography Plugin as an Enabler for Other Plugins¶
Protecting the confidentiality and integrity of data ensures that other security plugins can do their job correctly.
For example, the Access Control Plugin will prevent your secure DataWriters from sending samples to DataReaders that do not have permission to subscribe to a specific Topic. However, if the Cryptography Plugin does not enforce confidentiality by encrypting your samples, malicious DataReaders could listen to the traffic on your network, thus getting access to the data you wanted to protect and defeating the purpose of Access Control. In this sense, the Cryptography Plugin provides us with the building blocks that enable other Security Plugins to work properly. Access Control decides whether an entity has permission to do something; Cryptography enforces entities to meet this requirement.
The Authentication Plugin interacts in a similar way with the Cryptography Plugin. While the Authentication Plugin makes sure a participant is who it claims to be, it is the Cryptography Plugin that enforces that only authenticated participants have access to the domain. The Cryptography Plugin achieves this by protecting messages with encryption keys that have been only shared with successfully authenticated and authorized participants.
6.1.2. Overview of How Cryptography Works in DDS¶
To establish a DDS Secure communication, Secure Entities (i.e., Secure DomainParticipants, Secure DataWriters, and Secure DataReaders) perform some cryptographic transformations based on some security parameters and keys. Secure Entities use symmetric cryptography to MAC (and potentially encrypt) the information they protect. Therefore, a sender and its matching receivers will use the same cryptographic material to communicate securely. We will describe this in more detail in the section dedicated to Secure Entities.
In order to exchange the keys that Secure Entities need, mutually authenticated participants establish an end-to-end channel to exchange sensitive cryptographic material securely. This Secure Key Exchange Channel allows your Secure DomainParticipants to confidentially exchange the Key Material that Secure DataWriters and Secure DataReaders need to communicate. We will describe this channel in more detail in Secure Key Exchange Channel (ParticipantVolatileMessageSecure Topic).
Secure DataWriters and DataReaders are not only used to protect the user-defined Topics. New secure builtin Endpoint (DataWriters and DataReaders) will be created when you protect the discovery traffic or the liveliness assertions. More concretely, when you protect a Topic’s discovery information, your DomainParticipants will exchange the discovery information for that Topic through the Builtin Secure Discovery Topics. You can also protect liveliness messages exchanged for Topics that have AUTOMATIC
or MANUAL_BY_PARTICIPANT
(see enable_liveliness_protection (topic_rule)). Protecting liveliness will result in your DomainParticipants exchanging these messages through the Builtin Secure Liveliness Topic (see Builtin Secure Liveliness Topic). Note that these secure builtin Endpoints will coexist with their unsecure versions that will be used for Topics that aren’t using Discovery/Liveliness Protection.
Protecting different parts of your communication implies that your messages will have cryptographic transformations applied at different stages (see Security Protections Applied by DDS Entities). For example, Serialized Data Protection allows you to protect the samples published in a particular Topic. You could also decide to protect the RTPS submessages for that particular Topic. Submessage Protection covers both DATA submessages – which contain the (potentially already-protected) serialized payload – and submessages containing metadata, such as ACKNACK and HEARTBEAT submessages (see Overview of the Reliable Protocol in the Core Libraries User’s Manual). Finally, you could enable RTPS Protection to protect the complete RTPS messages that your DomainParticipants put on the network. Note that the protections at different stages are not mutually exclusive: the Cryptography Plugin gives you the flexibility to combine different levels of protection in the way that best fits your security requirements. Also, applying cryptographic transformations at different stages implies protecting different parts of the RTPS message, as depicted in Figure 6.1. For further details, see Securing DDS Messages on The Wire.
![../_images/protection-kinds.png](../_images/protection-kinds.png)
Figure 6.1 Parts of the Message Protected by Each Protection Kind¶
The Cryptography Plugin uses AES-GCM to protect the traffic (see Cryptographic Algorithms for details). The AES-GCM transformation produces both the ciphertext and a message authentication code (MAC) using the same secret key. This is sufficient to protect the plaintext and ensure integrity. However there are situations where multiple MACs are required. For example when a DataWriter shares the same key with multiple DataReaders and, in spite of this, the DataWriter needs to ensure origin authentication. In this situation the DataWriter should create a separate Receiver-Specific Key used only for authentication and append additional Receiver-Specific MACs, each computed with one of the Receiver-Specific Keys (see Origin Authentication Protection).
6.2. 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 Entities. This section describes the symmetric cipher algorithms that can be configured in the Cryptography Plugin.
In this section, we also describe the relationship between the algorithms that can be configured in the Cryptography Plugin and the ParticipantTrustAlgorithms and EndpointTrustAlgorithms fields, which are used to propagate the used and supported algorithms for a DomainParticipant. A complete list of values can be found in Table 15.4.
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_algorithms. Discovery defaults are the values are assumed when no value is propagated through discovery see :ref:p2_core/cryptography:Discovery of a remote Secure Entity for more details about discovery.
6.2.1. Participant Symmetric Cipher Algorithms¶
Participant Symmetric Cipher Algorithms collect algorithms used to encode DomainParticipant builtin endpoints’ traffic. The following algorithms are supported:
AES128-GCM
AES192-GCM (<< deprecated >>)
AES256-GCM
Participant Symmetric Cipher Algorithms specify three algorithm definitions:
supported_mask
: A list of symmetric cipher algorithms supported by a DomainParticipant. The default value is: AES128-GCM and AES256-GCM.builtin_endpoints_used_bit
: Indicates the algorithm the DomainParticipant will use as the symmetric cipher algorithm to encode protected builtin endpoint’s traffic. It is determined by cryptography.encryption_algorithm property (see Table 6.8). The default value is: AES256-GCM.builtin_endpoints_key_exchange_used_bit
: The algorithm used by DomainParticipant’s builtin endpoints to encode key exchange traffic. The default is not set.
6.2.2. Endpoint Symmetric Cipher Algorithms¶
Endpoint Symmetric Cipher Algorithms collect algorithms used to encode endpoints’ traffic. The following algorithms are supported:
AES128-GCM
AES192-GCM (<< deprecated >>)
AES256-GCM
Endpoint Symmetric Cipher Algorithms specify a single algorithm definition:
used_bit
: Indicates the algorithm the Endpoint will use as the symmetric cipher algorithm to encode its traffic. It must be an algorithm that is propagated in the DomainParticipant list of supported symmetric cipher algorithms. The default value is AES256-GCM. The symmetric cipher that an Endpoint uses is determined by thecryptography.encryption_algorithm
(see Table 6.8)
See allowed_security_algorithms (domain_rule) to learn how to configure which of these algorithms are supported.
6.3. Secure Entities¶
Definition
We will use the term Secure Entity to refer to one of the following three DDS Entities:
Secure DataWriter: can perform Serialized Data Protection and/or Submessage Protection.
Secure DataReader: can perform Submessage Protection.
Secure DomainParticipant: can perform RTPS Protection.
In other words, a Secure Entity is a DataWriter, a DataReader, or a DomainParticipant that has at least a protection kind different than NONE
in its associated Governance Rules.
When a Secure DataWriter sends a sample to its matching DataReaders, it will protect the sample by applying a cryptographic transformation (parametrized with a key). If, for example, this is a reliable Topic, the DataReaders also need to send ACKNACKs to the DataWriter, and these will be protected using the same cryptographic transformation, but using different keys. As you can see, both DataWriters and DataReaders need to send protected information to the other Endpoint. In this sense, we talk about Sender (the entity sending a secure message) and Receiver (the entity receiving a secure message). Note that every Secure Entity will have its own Sender and Receiver. The Sender will protect the messages; the Receiver will validate (and potentially decrypt) the messages.
To communicate with the other end, both the Sender and the Receiver will have a copy of the same Key Material, from which we derive the key that is used by the cryptographic transformations. Each Sender will generate its own key to protect the outgoing messages; Receivers for that Sender will need the same key to validate (and potentially decrypt) the incoming messages. This Key Material is securely exchanged between matching Secure Entities through the Secure Key Exchange Channel, as described in Secure Key Exchange Channel (ParticipantVolatileMessageSecure Topic).
6.3.1. Architecture of Secure Entities¶
Secure Entities have some attributes (configuration) and mechanisms (algorithms) that allow them to communicate securely. In addition, each Secure Entity has a Sender and a Receiver: the Sender handles the outgoing messages by protecting them; the Receiver handles the incoming messages by validating (and potentially decrypting) them. Secure Entities need to store and use keys as parameters for the cryptographic algorithms. Upon its creation, each Secure Entity generates the local Sender’s Key Material. Receivers in matching Secure Entities need a copy of this Key Material to validate (and potentially decrypt) the messages from this Sender, as depicted in Figure 6.2.
![../_images/secure-entity-architecture.png](../_images/secure-entity-architecture.png)
Figure 6.2 Architecture Overview of Two Matching Secure Entities¶
6.3.1.1. Security Mechanisms¶
To communicate securely, Secure Entities need to perform operations that involve the Cryptography Plugin. These operations include protecting the outgoing messages in the sender side and validating (and potentially decrypting) the incoming messages in the receiver side with the same symmetric key.
The key used by the cryptographic functions is a symmetric Session Key with a limited lifetime. The Session Key derives from cryptographic material generated by the Sender entity upon its creation, then sent to the Receiver upon discovery of the remote entity. The Session Key is a temporary key that will be valid for a particular session and derives from the Sender’s Key Material and Session ID. The Sender will periodically change the Session Key used to protect the messages by changing the Session ID. To let the Receiver know what Session Key it needs to use, the Sender includes the Session ID in every protected message.
6.3.1.2. Security Attributes¶
The security attributes define what part of the messages will be protected by the Sender and how, i.e., what transformation is applied and how it changes the transmitted packets. Security attributes come from the Governance Rules that apply to this Topic and need to be the same in every Endpoint for this Topic in the secure domain (see Discovery of a Remote Secure Entity). (Governance Rules are user-defined in the Governance Document, see Governance Document).
In the case of a Secure DataWriter, the security attributes define whether the Sender will protect the serialized data and/or the RTPS submessage. Secure DataReaders are limited to protecting the outgoing RTPS submessage, while Secure DomainParticipants can protect outgoing RTPS messages at the RTPS message level.
The security attributes also define whether the Sender will MAC the protected message or it will encrypt and MAC it. In either case, the Sender will use the Session Key to protect the outgoing messages; matching Receivers will use this same Session Key to validate (and potentially decrypt) the incoming messages.
6.3.1.3. Local Sender’s Key Material¶
Upon its creation, Secure Entities generate the local Sender’s Key Material. The local Sender uses this cryptographic material to communicate with the remote Receivers securely. The local Sender’s Key Material includes:
the Sender Key
the Sender Key ID, which identifies the Sender Key
the Transformation Kind, which is the algorithm that the Sender uses for protecting its contents.
Cryptographic algorithms do not use the Sender Key directly to protect communications. Instead, the Sender derives temporary Session Keys from its Sender Key (and other parameters from its Key Material). Cryptographic operations use these temporary keys to protect outgoing messages. These messages also include the Sender Key ID to allow the Receiver to identify, within all the Key Material received from a remote DomainParticipant, what Key Material was used to protect the message. Note that RTPS messages already contain the Secure Entity’s GUID that identifies the DomainParticipant from which the message originated. Additionally, the outgoing messages also include a Session ID, which allows the Receiver to derive the right Session Key by applying certain cryptographic operations over the selected Sender Key (see Figure 6.3).
When Origin Authentication Protection is enabled, one additional Receiver-Specific Key per Receiver (identified by the Receiver-Specific Key IDs) are stored in the Secure Entity along with the local Sender’s Key Material. This key is used to derive the Receiver-Specific Session Key, which in turn is used as input to the cryptographic operation that computes the Receiver-Specific MAC of the outgoing messages.
Note that while the Sender Key does not change in the whole lifecycle of the Secure Entity; the Session ID changes periodically (see Secure Communication).
![../_images/derivation-session-keys.png](../_images/derivation-session-keys.png)
Figure 6.3 Derivation of the Session Key and Receiver-Specific Session Keys¶
6.3.1.4. Remote Sender’s Key Material¶
The Receiver in the local Secure Entity needs the remote Sender’s Key Material to validate (and potentially decrypt) messages coming from that remote Sender. Note this is the same Key Material we introduced in Local Sender’s Key Material, but from the Receiver’s perspective. The local Secure Entity will receive the remote Sender’s Key Material through the Secure Key Exchange Channel after the two matching Secure Entities discover and validate each other. The local Receiver derives the Session Key from the remote Sender’s Key Material and the Session ID included in each message. Then, it uses the Session Key to validate (and potentially decrypt) incoming messages (see Secure Communication).
When the Receiver gets a message from the network, it takes the Sender Key ID and the remote Secure Entity’s GUID from the RTPS message. With this information, the Receiver can identify the Sender Key that the Sender used to protect the message from the list of its received keys. Then, it uses the Session ID, also included in the protected message, to compute the Session Key. Finally, the Receiver uses the Session Key to validate (and potentially decrypt) the message.
When Origin Authentication Protection is enabled, an additional Receiver-Specific Key is assigned to the local Receiver. This key is identified by the Receiver-Specific Key ID and is stored as part of the remote Sender’s Key Material. This key is used to derive the Receiver-Specific Session Key, which in turn is used to verify the Receiver-Specific MAC of the incoming messages.
![../_images/key-material-sender.png](../_images/key-material-sender.png)
Figure 6.4 Key Derivation in the Sender. The Key Material is stored in the Secure Entity.¶
![../_images/key-material-receiver.png](../_images/key-material-receiver.png)
Figure 6.5 Key Derivation in the Receiver. The Key Material stored in the Secure Entity is identified with the Sender Key ID, present in the incoming message.¶
6.3.2. Lifecycle of Secure Entities¶
6.3.2.1. Creation of the Secure Entity¶
Upon the creation of a Secure Entity, the local Sender Key is generated and stored locally. This is done after the checks from the Access Control Plugin, which verifies that the Entity has permission to do what it’s being created for. Refer to Local Sender’s Key Material for further details on the generated cryptographic material.
6.3.2.2. Discovery of a Remote Secure Entity¶
To successfully discover, DomainParticipants need to have a compatible configuration for the participant security attributes. A compatible configuration involves having the same RTPS Protection kind, the same Discovery Protection, and the same Liveliness Protection.
The same logic applies to Secure Endpoints and the endpoint security attributes. To communicate, two matching Secure Endpoints (a Secure DataWriter and a Secure DataReader) need to present the same Governance Rules for the Topic of these Secure Endpoints.
To support these Governance compatibility checks, when you enable security, Connext sends additional properties as part of the discovery information. These properties support making matching decisions. For further details, see Governance Compatibility Validation.
Secure DomainParticipants propagate information about their supported and used cryptographic algorithms during discovery. This information is used to determine matching between DomainParticipants, matching between Endpoints, and for early detection of configuration issues. The information that Secure DomainParticipant propagate during discovery about their cryptographic algorithms has the purpose of optimizing discovery traffic (do not match with DomainParticipants that do not support your local security algorithms) and improving debuggability. They are for improving system deployability and making it easier to detect configuration errors; they are not to enforce security.
DomainParticipant propagate information about cryptographic algorithms in following PIDs:
Digital Signature Algorithms:
PID_PARTICIPANT_SECURITY_DIGITAL_SIGNATURE_ALGO
.Key Establishment Algorithms:
PID_PARTICIPANT_SECURITY_KEY_ESTABLISHMENT_ALGO
.Symmetric Cipher Algorithms:
PID_PARTICIPANT_SECURITY_SYMMETRIC_CIPHER_ALGO
.Endpoint Symmetric Cipher Algorithms:
PID_ENDPOINT_SECURITY_SYMMETRIC_CIPHER_ALGO
.
If any of the PIDs values are set to defaults, or if security is disabled, they are not propagated. The defaults are compatible with previous Security Plugins releases: communication with earlier releases is not impacted. For detailed information about supported and the default cryptographic algorithms, see Cryptographic Algorithms in the “Authentication” chapter and Cryptographic Algorithms in the “Cryptography” chapter.
The following rules determine if two DomainParticipants, PA and PB, are compatible with respect to their cryptographic algorithms:
Identity trust chain digital signature algorithms: At least one digital signature algorithm from the remote Identity Certificate chain must be supported by the local DomainParticipant for a match to happen during discovery. Note that the local DomainParticipant doesn’t have to support all of the signature algorithms from the remote DomainParticipant. This is because the chain is not always validated completely, as any of the intermediate certificates in the Identity Certificate might be signed by the Identity CA. As a consequence, two DomainParticipants can match but still result in error during validation of the Identity Certificate.
PA’s trust_chain_supported_mask intersects with any bit from PB’s trust_chain_used_mask, and
PB’s trust_chain_supported_mask intersects with any bit from PA’s trust_chain_used_mask.
Authentication digital signature algorithms: The remote DomainParticipant computes a signature using the algorithm specified in its auth_used_bit. The local DomainParticipant must support it in order to verify the signature, and confirm its authenticity.
PA’s auth_supported_mask intersects with PB’s auth_used_bit, and
PB’s auth_supported_mask intersects with PA’s auth_used_bit.
Key establishment algorithms: Note that two DomainParticipants will use the preferred key establishment algorithm from the DomainParticipant that is the authentication initiator. In that sense, we could argue that it is enough to do the intersection of the initiator participant
preferred_bit
and the non-initiatorsupported_mask
to determine key establishment algorithm compatibility. The rationale for doing the matching for both DomainParticipants’preferred_bit
and thesupported_mask
is to make sure systems behave consistently independently of who is the initiator DomainParticipant (i.e., independently of the assigned DomainParticipant’s GUIDs): if communication would fail depending on who is the initiator, the key establishment algorithm configuration is determined to be incompatible.PA’s supported_mask intersects with PB’s preferred_bit, and
PB’s supported_mask intersects with PA’s preferred_bit.
Symmetric cipher algorithms:
PA’s supported_mask intersects with PB’s builtin_endpoints_used_bit, and
PB’s supported_mask intersects with PA’s builtin_endpoints_used_bit, and
PA’s builtin_endpoints_key_exchange_used_bit is equal to PB’s builtin_endpoints_key_exchange_used_bit.
For two Endpoint, EPA and EPB, to be compatible with respect to the configuration of their cryptographic algorithms:
PA’s supported_mask intersects with EPB’s used_bit, and
PB’s supported_mask intersects with EPA’s used_bit.
6.3.2.3. Key Material Exchange¶
Once the Secure Entities have fully matched (same Topic, same type, compatible QoS, same security attributes) and permissions are checked, they exchange the Key Material through the Secure Key Exchange Channel.
Each of the Secure Entities will register the local Sender’s Key Material and the remote Sender’s Key Material (that is received through the Secure Key Exchange Channel). As specified in Creation of the Secure Entity, the common part of the local Sender’s Key Material is generated upon the entity creation.
When Origin Authentication Protection is enabled, the Receiver-Specific Key Material is also exchanged. In this case, the local DomainParticipant maintains a list with the Receiver-Specific Keys that correspond to the discovered Secure Entities. Since Entities in the same DomainParticipant run in the same application memory space, a single Receiver-Specific Key is assigned to every Secure Entity in a remote DomainParticipant.
For further details on Key Material Exchange, see Secure Key Exchange.
6.3.2.4. Secure Communication¶
At this point, the Secure Entities can communicate securely.
The Sender will add additional information in the outgoing messages so the Receiver can validate (and potentially decrypt) them. This includes the Sender Key ID and the Session ID. The message will also contain the MAC (a.k.a. the Common MAC), and the Receiver-Specific MACs when Origin Authentication Protection is enabled.
Figure 6.6 depicts the process of receiving a secured incoming message. Details on how the communication is protected on the wire are covered in Cryptographic Information Added to RTPS Messages.
![../_images/reception-secure-msg.png](../_images/reception-secure-msg.png)
Figure 6.6 Reception of a Secure Message¶
6.3.3. Algorithms Involved in Protecting Secure Entities Traffic¶
Senders use AES-GCM to encrypt and MAC messages when the ENCRYPT
protection kind is in use. Alternatively, when the SIGN
protection
kind is configured, Senders use AES-GMAC to MAC-only data. On the counterpart
side, Receivers use the same algorithms to validate the MAC of (and potentially
decrypt) incoming data. Note that AES-GMAC transformation is a particular case
of AES-GCM, which produces only a MAC and leaves the input message unencrypted.
AES-GCM can operate with 128-bit, (deprecated) 192-bit, and 256-bit keys (see
cryptography.encryption_algorithm
in
Table 6.8).
Regardless of the key size, AES-GCM always operates in 128-bit (16-byte) blocks.
Hence, all the MACs are 128-bit (16-byte) long.
AES-GCM requires a symmetric key and an initialization vector to operate. In Security Plugins, the Session Key is used as the symmetric key, while the Initialization Vector is the concatenation of the Session ID and the so-called Initialization Vector Suffix.
The same Initialization Vector is associated with all the session keys of a specific Sender, including the common Session Key and all the Receiver-Specific Session Keys. The Initialization Vector Suffix is incremented each time any of these keys are used to encrypt and/or compute a MAC.
The Session ID and Initialization Vector Suffix are sent as part of the protected message, allowing the Receiver to derive the Session Key and the Receiver-Specific Key that it will use to validate (and potentially decrypt) the received messages.
As stated in the DDS Security specification, the use of (Galois) counter mode
allows authenticated decryption of blocks in an arbitrary order. All that is
needed to decrypt and validate the authentication tag are the Session Key and
the Initialization Vector. This is very important for DDS because a DataReader may not receive all the
samples written by a matched DataWriter. The use of DDS ContentFilteredTopics as well
as DDS QoS policies such as History (with KEEP_LAST
kind), Reliability
(with BEST_EFFORT
kind), Lifespan, and TimeBasedFilter, among others,
can result in a DataReader receiving a subset of the samples written by a DataWriter.
6.3.3.1. Limiting the Usage of a Specific Session Key¶
The Session Block Counter is an internal counter that keeps track of the number of blocks protected with the same Session Key. Note that GCM uses 128-bit blocks. The purpose of this counter is to ensure that a single Session Key is not used to protect more than the maximum blocks per session, as configured by the cryptography.max_blocks_per_session
property (see Table 6.8). The Session Block Counter and the size of the plaintext are used to ensure that cryptography.max_blocks_per_session
will not be exceeded during the encode operation. If the encode operation detects that the counter would exceed the maximum then it will modify the Session ID (and derive new session keys) prior to transforming any of the input plaintext.
The change in the Session ID triggers the creation of new session keys, randomizes the Initialization Vector Suffix, and resets the Session Block Counter.
Since the original Key Material (see Local Sender’s Key Material) stays the same even after creating new session keys, this mechanism is not useful for removing DomainParticipants from the system. The next section describes the mechanism that may be used for that purpose.
6.3.3.2. Limiting the Usage of Specific Key Material¶
In order to prevent removed remote DomainParticipants from processing encoded traffic from
the local DomainParticipant, the local DomainParticipant must ensure that the remote DomainParticipants do not have the
Key Material to decode that traffic. And in order to prevent removed malicious
remote DomainParticipants from impersonating trusted DomainParticipants by using previously received
Key Material to do message authentication, the local DomainParticipant must change its
Key Material and tell its peers to use the new Key Material in place of the
old one when authenticating messages. The Security Plugins add all of this functionality to
banish_ignored_participants
. When this method is called, the local DomainParticipant
creates a Key Revision. A Key Revision is a small piece of information, which
contains an identifier and a random number. The Key Revision can be combined
with an original Key Material in order to generate a new Key Material. After
sending the Key Revision to currently legitimate remote DomainParticipants via the
Secure Key Exchange Channel and receiving acknowledgments that the Key Revision was
received, the local DomainParticipant may activate the Key Revision. When a
Key Revision is activated, the new Key Material becomes the Key Material
that is used for encoding new content. Then, this new content will become
indecipherable by remote DomainParticipants that have been removed, while still being
decipherable by currently legitimate remote DomainParticipants. And this new Key Material
will be distinguishable from the old Key Material, which illegitimate remote
DomainParticipants may still possess, so a successful message authentication will actually
be trustworthy.
banish_ignored_participants
will still create a new Key Revision even if
there are no new removed DomainParticipants since the last time
banish_ignored_participants
was called.
Since Receiver-Specific Keys are only shared with a subset of trusted receivers and since they are always used in combination with the new Key Material, there is no need to regenerate Receiver-Specific Keys.
To enable Key Revisions, you must set the property
dds.participant.trust_plugins.key_revision_max_history_depth
to
a value other than 0
. A DomainParticipant that sets this property to a value other
than 0
will not communicate with a DomainParticipant that sets this property to
0
or with a DomainParticipant of a release older than Security Plugins 7.0.0.
This lack of interoperability is true even if the 7.0.0 DomainParticipant
never actually calls banish_ignored_participants
. The reason is that when
enabling Key Revisions, the contents of the Crypto Header (see
Cryptographic Information Added to RTPS Messages)
become different. The Core Libraries check the compatibility of
dds.participant.trust_plugins.key_revision_max_history_depth
at
DomainParticipant discovery time, at the same time that it checks for Governance
compatibility (see
Governance Compatibility Validation).
6.4. Secure Key Exchange Channel (ParticipantVolatileMessageSecure Topic)¶
In order to perform key exchange between Secure Entities, DomainParticipants need to send directed messages to each other using a reliable and secure channel. These messages are intended only for participants that are currently in the system and therefore use a DURABILITY QoS of kind VOLATILE
. The DDS Security specification introduces a new Secure Key Exchange Builtin Topic, also known as the ParticipantVolatileMessageSecure builtin Topic, to exchange these messages.
6.4.1. Secure Key Exchange Builtin Topic Characteristics And Security Attributes¶
The purpose of the Secure Key Exchange Builtin Topic is to reliably and securely transport the
Key Material between the Secure Entities. This Topic uses a RELIABILITY
QosPolicy of kind RELIABLE
and a HISTORY QosPolicy of kind
KEEP_ALL
to make sure that keys get to the remote Secure Entity. Also, a
DURABILITY QosPolicy of kind VOLATILE
is used to prevent sending data
to unauthorized late joiners. Finally, to protect the confidentiality of
messages sent on this channel, the Secure Key Exchange Builtin Endpoints use encryption as the
Submessage Protection.
The Secure Key Exchange Channel requires a Secure DataWriter and a Secure DataReader in both the local participant (P1) and the remote participant (P2). The Key Material that allows a DataWriter and its matching DataReaders to communicate securely is normally exchanged through this Secure Key Exchange Channel. The only exception is the Key Material used by this channel’s Secure Endpoints, a Shared Key that will derive from the information resulting from the authentication process. More concretely, the Shared Key is derived using HMAC operations on the Challenges exchanged in the Handshake and the Shared Secret that results from the authentication process. For more information on these parameters, see Handshake.
The Key Material derived for the Secure DataWriter and DataReader is identical. Nonetheless, since only P1 and P2 know the Shared Key, this cryptographic material is unique for P1 and P2. In other words, this is a direct channel between P1 and P2. That means that if there were a third participant (P3) in the system, there would be different keys for communicating between P1 and P3. So a Shared Key is particular to a single authentication session between a pair of DomainParticipants. Hence, if somehow P2 loses liveliness and P1 cleans the state associated with P2, and then P1 rediscovers P2, they will end up with a different Shared Key.
6.4.2. Secure Key Exchange¶
Once the Secure Key Exchange Channel is established, the Key Material for every other Secure Entity is exchanged through it. This Key Material includes the Transformation Kind, Sender Key and Sender Key ID, as well as the Receiver-Specific Key (see Architecture of Secure Entities).
If Key Revisions are enabled (see Limiting the Usage of Specific Key Material), then the most recent Key Revisions are also exchanged between the DomainParticipants. This exchange gives the receiving side the ability to decode historical data from the sending side. See Reencoding Protected Data when Regenerating Keys for more details.
DomainParticipants use this Topic to exchange the Key Material that will be used to protect outgoing RTPS messages (when RTPS Protection is enabled). After that, DomainParticipants exchange the Key Material for the builtin Secure Endpoints, including the Builtin Secure Publication DataWriter and DataReader used for Secure Endpoint Discovery (see Security Builtin Topics). Once your DomainParticipants have exchanged the keys for the builtin Secure Endpoints, they can perform secure discovery, and once they discover particular user-defined DataWriters and DataReaders, the participants will also use this channel to exchange the keys for those Endpoint.
More concretely, during Endpoint Discovery, two mutually authenticated participants (P1 and P2) will send publication and subscription DATA messages to inform their counterpart about their local DataWriters and DataReaders. When P1 discovers that P2 has a DataReader (DR2) matching a local DataWriter (DW1), P1 will register DR2 as a remote endpoint. If Origin Authentication Protection is enabled, P1 will assign DR2 Receiver-Specific Key Material. After this, P1 will send DW1’s local Sender Key Material through the Secure Key Exchange Channel. This message will include DR2’s Receiver-Specific Key Material. P2 will follow the same process: register DW1, assign it some Receiver-Specific Key Material (if Origin Authentication Protection is enabled), and send DR2’s local Sender Key Material to P1. At this point, DW1 and DR2 have all the cryptographic material that they need to communicate securely (see Local Sender’s Key Material).
6.4.3. Secure Key Redistribution¶
Suppose that while DW1 and DR2 are communicating, a third DomainParticipant
(P3) and its DataReader (DR3) join the system. DW1 communicates with DR3 for
a while, but then P1 decides that P3 is no longer trustworthy, so P1
calls ignore_participant
on P3 and then calls
banish_ignored_participants
(see Limiting the Usage of Specific Key Material).
This call creates a new Key Revision that is shared by both P1
and DW1, as well as by any of P1’s secure builtin endpoints. P1 sends
sends this Key Revision to P2 over the Secure Key Exchange Channel. While P1 waits
for P2 to acknowledge the Key Revision, P1 still uses its old
Key Material to protect outgoing RTPS messages, and DW1 still uses its old
Key Material to protect its outgoing RTPS submessages and data payloads. As
soon as P1 receives an acknowledgment for the Key Revision, P1 activates
the Key Revision, and P1 and DW1 both use the same Key Revision to derive
new Key Material from their respective old Key Material. Then, P1 and DW1
both start using their new Key Material.
If there is a fourth DomainParticipant (P4, which is still trusted) in the system, and
P4 takes too long to acknowledge the Key Revision, then P1 will remove
P4 from its list of legitimate remote participants. You can configure the
timeout for this removal using
dds.participant.trust_plugins.max_key_redistribution_delay.sec
.
After P1 removes P4, P1 will activate the Key Revision.
If P1 calls banish_ignored_participants
while still waiting to activate
the previous Key Revision, then banish_ignored_participants
will not
block. Instead, the Event thread (see
Event Thread in the Core Libraries User’s Manual)
will check every one second if the previous Key Revision has been activated.
When it is activated, the Event thread will create and send the new
Key Revision.
6.5. Securing DDS Messages on The Wire¶
When sending a protected message, some cryptographic information is added. The following sections describe the details of the cryptographic information (Cryptographic Information Added to RTPS Messages), as well as the effect of different protection kinds on what gets sent on the wire (RTPS Protocol Changes to Support Secure Entities Traffic).
6.5.1. RTPS Protocol Changes to Support Secure Entities Traffic¶
In the RTPS protocol, the main component is the RTPS message. RTPS messages have a header containing information about the sending entity, and have different units of information that are divided into submessages. In turn, each submessage has a header and its own elements. For example, a submessage can contain user data; it will have a data header and then contain your user data. Other submessages could contain metadata needed in DDS, such as HEARTBEATs, ACKNACKs, etc. To sum up, inside a single RTPS message you can have multiple submessages with different bits of information (see Figure 6.7).
Depending on the protection kind, different parts of the message will be protected.
![../_images/rtps-msg-structure.png](../_images/rtps-msg-structure.png)
Figure 6.7 General Structure of an RTPS Message¶
6.5.1.1. Serialized Data Protection¶
You can enable Serialized Data Protection by setting the data_protection_kind
Governance Rule to a value other than NONE
(see data_protection_kind (topic_rule)).
Serialized Data Protection only applies to the Sender in the DataWriter. If not batching, the DataWriter protects the sample payload right after the serialization. If batching, the DataWriter protects the entire batch right before the flush. The protected sample or batch (including the MAC and potentially being encrypted) is stored in the DataWriter’s queue until sent. When resending samples (for instance, for sending repairs), the sample is already in the DataWriter’s queue, so additional cryptographic operations are not needed (see Interaction Between the Security Plugins and Batching QoS).
Note
Secure DataWriters can only communicate with compatible Secure DataReaders, as described in Discovery of a Remote Secure Entity. In other words, secure and unsecure Endpoints cannot communicate.
From an RTPS point of view, the Serialized Data Protection only protects the payload inside the DATA submessages. Therefore, the Serialized Payload now becomes a Crypto Header, a Serialized Payload/Crypto Content element, and a Crypto Footer, as Figure 6.8 depicts. Note that the Serialized Payload element (unchanged from input) is used when only protecting data integrity (data_protection_kind
= SIGN
); the Crypto Content element (encrypted Serialized Payload) is used when also protecting data confidentiality (data_protection_kind
= ENCRYPT
). Also, note that the submessage structure (and number) is not modified.
![../_images/data-protection.png](../_images/data-protection.png)
Figure 6.8 RTPS Message Transformation with Serialized Data Protection¶
6.5.1.2. Instance Key Data Protection¶
If not batching, then Serialized Data Protection is also applied to instance key data. If
you set
DATA_WRITER_PROTOCOL QosPolicy’s serialize_key_with_dispose
to TRUE
, then instance key data will get sent with dispose samples, so
it has to be protected. The protection is applied when you register the
instance, and the protected instance key data is stored in the DataWriter’s queue.
Consequently, no additional cryptographic operations are needed when sending
dispose samples, and a decoding operation is needed if the DataWriter calls
get_key_value
.
If batching, then Serialized Data Protection is not applied to instance key data because
Serialized Data Protection is already applied to the entire batch, so there is no need
for further cryptographic operations on the instance key data. Consequently, no
additional cryptographic operations are needed if the DataWriter calls
get_key_value
.
6.5.1.3. Submessage Protection¶
You can enable Submessage Protection by setting the metadata_protection_kind
Governance Rule to a value other than NONE
(see metadata_protection_kind (topic_rule)).
Submessage Protection applies to messages sent both by the DataWriter and the DataReader. The Secure Endpoint will protect the following types of RTPS submessages right before putting them in the wire.
AckNack
AppAck
AppAckConf
Data
DataBatch
DataFrag
DataSession
Gap
Heartbeat
HeartbeatFrag
HeartbeatVirtual
NackFrag
Note
Secure DataWriters can only communicate with compatible Secure DataReaders, as described in Discovery of a Remote Secure Entity. In other words, secure and unsecure Endpoints cannot communicate.
From an RTPS point of view, Submessage Protection protects the submessages by prepending a Secure Prefix Submessage (SEC_PREFIX) – which contains the Crypto Header – to the Secure Body Submessage (SEC_BODY) – which contains the Crypto Content. It also appends a Secure Postfix Submessage (SEC_POSTFIX) – which contains the Crypto Footer. Therefore, the submessage becomes SEC_PREFIX + SEC_BODY + SEC_POSTFIX, as the following diagram depicts.
Note that the number of RTPS submessages increases, but the overall RTPS message structure is not modified.
![../_images/submsg-protection.png](../_images/submsg-protection.png)
Figure 6.9 RTPS Message Transformation with Submessage Protection¶
6.5.1.4. RTPS Protection¶
You can enable RTPS Protection by setting the rtps_protection_kind
Governance Rule to a value other than NONE
(see rtps_protection_kind (domain_rule)).
RTPS Protection affects the DomainParticipant and applies to every packet 1 that is sent by protecting the whole RTPS message right before putting it on the network.
Note
DomainParticipants with RTPS Protection can only communicate with DomainParticipants that have this same protection. In other words, when you enable RTPS Protection, secure and unsecure DomainParticipants cannot interoperate.
From an RTPS point of view, RTPS Protection protects the whole RTPS message by copying the RTPS header, then protecting the whole RTPS message (including its header). The resulting protected packet will consist of an SRTPS Prefix 2 – which contains the Crypto Header – followed by an SRTPS Body – which contains the Crypto Content – and an SRTPS Postfix – which contains the Crypto Footer.
Note that RTPS Protection modifies the structure of the whole RTPS message and, when encryption is used, the confidentiality of all the content (except the RTPS header) is protected.
![../_images/rtps-protection.png](../_images/rtps-protection.png)
Figure 6.10 RTPS Message Transformation with RTPS Protection¶
- 1
Exceptions of RTPS messages to which RTPS Protection applies are covered in DomainParticipants.
- 2
SRTPS stands for Secure RTPS.
6.5.1.5. Origin Authentication Protection¶
Origin Authentication Protection allows the Receiver to make sure that the Sender is who it claims to be (i.e., it can authenticate the origin), even when the Sender communicates with multiple Receivers via multicast and shares the same encryption key with all of them. For instance, consider a DataReader that legitimately subscribes to a DataWriter for a particular Topic. Since symmetric encryption is used to protect data, the DataReader could potentially use the DataWriter’s key to send arbitrary samples, thus impersonating it. DataWriters can avoid this situation by protecting samples with Origin Authentication Protection.
Hint
You can add Origin Authentication Protection to Submessage Protection by setting the metadata_protection_kind
Governance Rule to SIGN_WITH_ORIGIN_AUTHENTICATION
or ENCRYPT_WITH_ORIGIN_AUTHENTICATION
.
You can add Origin Authentication Protection to RTPS Protection by setting the rtps_protection_kind
Governance Rule to SIGN_WITH_ORIGIN_AUTHENTICATION
or ENCRYPT_WITH_ORIGIN_AUTHENTICATION
.
For further information, see Understanding ProtectionKinds.
This protection involves computing additional Receiver-Specific MACs with a secret key that the Sender shares only with a set of Receivers (ideally one). The additional MACs are computed by applying the AES-GMAC algorithm parameterized with the Receiver-Specific Key to the Common MAC, and appending the result to it in the Crypto Footer.
The number of Receiver-Specific MACs in an RTPS message is the union of the Receiver-Specific MACs each of its submessages would need. For example, assume that you have an RTPS message with three submessages. The first submessage is directed to a receiver A, the receiver of the second submessage is B, and the receiver of the third submessage is unknown. In this situation, if Submessage Protection were set to protect the origin authentication, the first submessage would have the Receiver-Specific MAC for A, the second submessage would have the Receiver-Specific MAC for B, and the third submessage would have the Receiver-Specific MAC for all the matching Endpoints, let’s say A, B, C, and D. Therefore, to satisfy the requirements of every submessage, the RTPS message will include the following Receiver-Specific MACs:
![../_images/rec-specific-macs-multiple-receivers.png](../_images/rec-specific-macs-multiple-receivers.png)
Figure 6.11 Receiver-Specific MACs included in an RTPS Message that uses RTPS Protection with Origin Authentication¶
Note that adding Origin Authentication Protection to Serialized Data Protection is not allowed (i.e., the DATA_WITH_ORIGIN_AUTHENTICATION
ProtectionKind does not exist). This is a consequence of the stage at which data is secured. On one hand, RTPS and Submessage Protections happen at wire-serialization time, right before handing the data to the transport. On the other hand, Serialized Data Protection happens right before the sample is saved in the DataWriter’s queue. The writer history stores the protected payload and this happens only once. While RTPS messages and submessages are re-protected when they are re-sent, user data is not. Once the sample is in the queue, the DataWriter has no information about the DataReaders interested in it. If a DataReader joins later and wants to receive historical data, the current sample in the queue would not be valid because it wouldn’t have the new Receiver-Specific MAC appended to it.
The diagram in Figure 6.12 summarizes the location of the protection.
![../_images/applying-protection.png](../_images/applying-protection.png)
Figure 6.12 Location of the Different Kinds of Protection¶
6.5.2. Cryptographic Information Added to RTPS Messages¶
When the Sender protects a message, it appends the MACs to the message and includes some information that the Receiver will need in order to derive the Session Key. More concretely, the secured message will contain these elements: a Crypto Header, Crypto Content (or Serialized Payload) and a Crypto Footer.
6.5.2.1. Crypto Header¶
The Crypto Header element indicates to the Receiver the cryptographic transformation that was used to protect the message. It also identifies the cryptographic material used to protect the message. It has three parts:
transformation_id: The transformation_id includes a four-byte Sender Key ID, and is used in combination with the identity of the sending DomainParticipant (already present in the RTPS header) to identify the Key Material used to derive the Session Key that protected the message. The transformation_id also includes four other bytes, whose contents depend on the setting of
dds.participant.trust_plugins.key_revision_max_history_depth
. If the value of this property is0
, then these bytes are the same Transformation Kind that was sent during the Secure Key Exchange. If the value of this property is not0
, then these bytes are the identifier of the Key Revision (see Limiting the Usage of Specific Key Material) that was used to protect the message.session_id: The session_id is used in combination with the Key Material to derive the cryptographic keys used for the encryption and MAC operations, including the Session Key and the Receiver-Specific Session Key.
initialization_vector_suffix: The initialization_vector_suffix is concatenated with the session_id to produce the Initialization Vector used as an input to the AES-GCM and AES-GMAC cryptographic operations/transformations.
6.5.2.2. Crypto Content / Serialized Payload¶
The Crypto Content is a sequence of octets that contain the encrypted version of the protected message when protecting both the integrity and confidentiality of the message (with ENCRYPT
protection kinds). Alternatively, the Serialized Payload is sent in plaintext when only the message’s integrity is protected (with SIGN
protection kinds).
6.6. Security Protections Applied by DDS Entities¶
Secure Entities are responsible for protecting the messages that they put on the wire. When you protect different parts of the communication related to a Topic in your Governance Document, you are actually defining the Entities and Secure Entities that are used to transmit the information related to that Topic. This includes:
Whether Secure DataWriters and DataReaders (or regular DataWriters and DataReaders) will be used to transmit the Topic’s payload (along with the Endpoint’s metadata such as HEARTBEATs, ACKNACKs and GAPs submessages).
Whether the Endpoint Discovery traffic will be exchanged through the secure version of the Builtin Discovery Endpoints.
Whether the liveliness assertions will be exchanged through the secure version of the Builtin Participant Message Endpoints (if the LIVELINESS QosPolicy is
AUTOMATIC
orMANUAL_BY_PARTICIPANT
, as described in enable_liveliness_protection (topic_rule)).
Also, when you enable RTPS Protection, your Secure DomainParticipants will additionally protect every RTPS message that is put on the network. (Of course, this includes the messages related to this Topic).
Keep in mind that to be able to communicate, the DomainParticipants in your secure domain need to protect the different parts of the communication related to your Topic the same way. For this reason, your DomainParticipants need to load compatible Governance documents (see Governance Compatibility Validation).
Let’s analyze what part of the communication (related to your Topic) each of these (potentially Secure) Entities can protect and what the valid levels of protection are.
6.6.1. DomainParticipants¶
In an unsecure scenario, Endpoints send packets directly to the network, without going through any DomainParticipant-level protection. This remains the same when you don’t use RTPS Protection. However, you can enable the RTPS Protection by setting the rtps_protection_kind
to a value other than NONE
. Then the DomainParticipant will intercept the RTPS message produced by your Endpoints (with a callback) and protect the whole message before putting it on the network.
Note that the DomainParticipant will apply RTPS Protection to every outgoing RTPS message except for the following:
DCPSParticipant builtin Topic messages (used in the Participant Discovery Phase)
Authentication (ParticipantStatelessMessage) builtin Topic messages
Secure Key Exchange (ParticipantVolatileMessageSecure) builtin Topic messages
UDP WAN transport binding ping messages (can be protected with either
hmac_only.cryptography.key
orcryptography.rtps_protection_key
)
The levels of protection that the Secure DomainParticipant can apply are listed in Table 6.1. Note that this protection will apply to every RTPS message sent by your DomainParticipants. Therefore if you have another type of protection enabled, multiple nested cryptographic operations will be performed on your data.
Governance Rule |
ProtectionKind |
Level of Protection |
---|---|---|
|
|
No protection |
|
Integrity |
|
|
Integrity and confidentiality |
|
|
Integrity and origin authentication |
|
|
Integrity, confidentiality, and origin authentication |
6.6.2. User-Defined Endpoints (DataWriters/DataReaders)¶
User-defined Endpoint are responsible for exchanging the Topic’s payload with the Security parameters that you define. You can configure user-defined Endpoints to protect either the Serialized Data, the RTPS submessages or both. Protecting the Serialized Data implies protecting the Topic’s payload, which is contained in DATA submessages. Protecting the RTPS submessages implies protecting both DATA submessages (which contain the payload) and other submessages that contain metadata (such as HEARTBEATs, ACKNACKs and GAPs submessages).
Serialized Data Protection and Submessage Protection are performed by the same Secure Entity, but at different stages:
Serialized Data Protection is applied to data in the DataWriter’s queue, before encapsulating it in an RTPS submessage.
Submessage Protection is applied right before putting the information on the network. Note that a batch of serialized data elements could be sent in the same submessage.
You can configure user-defined Endpoint to apply different levels of protection at each of these stages, as shown in Table 6.2 and Table Table 6.3.
You can configure the level of protection applied at each level independently. So if you want to protect the confidentiality of the payload and the integrity of the metadata sent by your user-defined Secure Endpoints you could set data_protection_kind
to ENCRYPT
and metadata_protection_kind
to SIGN
. Note that in this case, your DataWriter will perform an AES-GCM operation over the serialized data, storing the encrypted and MAC’d payload in its queue (with its corresponding format: Crypto Header | Crypto Content | Crypto Footer). Then right before putting the data on the network, it will perform an AES-GMAC operation to the DATA submessage, inserting the MAC’d submessage in an RTPS message (with its corresponding format: SEC Prefix | SEC Body | SEC Postfix).
Governance Rule |
ProtectionKind |
Level of Protection |
---|---|---|
|
|
No protection |
|
Integrity |
|
|
Integrity and confidentiality |
Governance Rule |
ProtectionKind |
Level of Protection |
---|---|---|
|
|
No protection |
|
Integrity |
|
|
Integrity and confidentiality |
|
|
Integrity and origin authentication |
|
|
Integrity, confidentiality, and origin authentication |
6.6.3. Builtin Secure Discovery Endpoints¶
Builtin Discovery Endpoint are responsible for exchanging the Endpoint Discovery information that allows the local DomainParticipant to discover remote Endpoint (and remote participants to discover the local DomainParticipant’s Endpoint). You can configure whether to use the secure version (or the regular unsecure version) of the Builtin Discovery Endpoints with the enable_discovery_protection
Governance Rule. If you set this Governance Rule to TRUE
, discovery information related to your Topic will be exchanged through the Builtin Secure Discovery Endpoints, and Topic Queries related to your Topic will be communicated through the Builtin Secure ServiceRequest Endpoints. These Endpoint will apply Submessage Protection to the level you configure with the discovery_protection_kind
Governance Rule.
The levels of protection that the Builtin Secure Discovery Endpoints can apply are listed in table Table 6.4. Note that this protection level will apply to the discovery and topic query information for every Topic that sets enable_discovery_protection
= TRUE
.
Governance Rule |
ProtectionKind |
Level of Protection |
---|---|---|
|
|
No protection |
|
Integrity |
|
|
Integrity and confidentiality |
|
|
Integrity and origin authentication |
|
|
Integrity, confidentiality, and origin authentication |
6.6.3.1. Secure Topic Query and Locator Reachability Support¶
Builtin Service Request Endpoint are responsible for exchanging Topic Queries and Locator Reachability responses. The Builtin Secure Service Request Endpoint will apply Submessage Protection to the level you configure with the discovery_protection_kind
Governance Rule. (See Builtin Secure ServiceRequest Topic).
The decision about which version of the Builtin Service Request endpoint (secure or not secure) the DataReader uses to send Topic Queries will depend on the value configured for the enable_discovery_protection
Governance Rule for that DataReader.
The decision about which version of the Builtin Service Request endpoint (secure or not secure) the Participant uses to send Locator Reachability responses to a remote Participant will be based on whether or not that remote Participant is using security.
6.6.4. Builtin Secure Liveliness Endpoints¶
Builtin Liveliness Endpoint are responsible for maintaining the liveliness of Topics that set the LIVELINESS QosPolicy to AUTOMATIC
or MANUAL_BY_PARTICIPANT
(see enable_liveliness_protection (topic_rule)). You can configure whether to use the secure version (or the regular unsecure version) of the Builtin Liveliness Endpoints with the enable_liveliness_protection
Governance Rule. If you set this Governance Rule to TRUE
, liveliness information related to your Topic will be exchanged through the Builtin Secure Liveliness Endpoints (only if the LIVELINESS QosPolicy is set to one of the values listed above). These Endpoint will apply Submessage Protection to the level you configure with the liveliness_protection_kind
Governance Rule.
The levels of protection that the Builtin Secure Liveliness Endpoints can apply are listed in table Table 6.5. Note that this protection level will only apply to Topics that set the LIVELINESS QosPolicy to one of the values listed above and set enable_liveliness_protection
= TRUE
.
Governance Rule |
ProtectionKind |
Level of Protection |
---|---|---|
|
|
No protection |
|
Integrity |
|
|
Integrity and confidentiality |
|
|
Integrity and origin authentication |
|
|
Integrity, confidentiality, and origin authentication |
6.8. Advanced Cryptography Concepts¶
6.8.1. Reliability Behavior When MAC Verification Fails¶
From a security point of view, message corruption due to random errors produced on the network cannot be distinguished from malicious tampering.
When setting data_protection_kind
, metadata_protection_kind
, or rtps_protection_kind
to a value other than NONE
, the DataReader may reject a sample due to MAC verification (for example, if the sample is tampered). When this happens, the DataReader does not deliver the sample to the application, and the sample is lost. If the RELIABILITY QosPolicy is set to RELIABLE
, however, the DataWriter will still repair the lost sample.
Note that depending on the level of protection, a tampered/replayed sample may be rejected at different levels:
If
metadata_protection_kind
orrtps_protection_kind
is a value other thanNONE
, the sample will be rejected before reaching the DataReader queue.If Submessage and RTPS Protection checks passed, and
data_protection_kind
is set to a value other thanNONE
, the sample will be rejected by the DataReader queue (or lost, in the case of best effort communication).
6.8.2. Enabling Asynchronous Publishing for the Secure Key Exchange Topic¶
The Security Plugins support fragmenting Secure Key Exchange (ParticipantVolatileMessageSecure) Builtin Topic samples. This is useful in scenarios with a hard limit on the transport maximum message size. Key Exchange is a reliable Topic; therefore, enabling fragmentation requires changing the publish mode to asynchronous publishing. For more information about how to configure the Secure Key Exchange Builtin Topic publish mode, see Table 6.6.
Type |
Field Name |
Description |
---|---|---|
|
Determines whether the Key Exchange builtin subscription DataWriter publishes data synchronously or asynchronously, and how. |
6.8.3. Configuring Reliability Protocol Settings of the Secure Key Exchange Topic¶
The Security Plugins support configuring the reliability protocol settings of the Secure Key Exchange (ParticipantVolatileMessageSecure) builtin topic, which is a reliable Topic. You can configure this by modifying the DDS_DiscoveryConfigQosPolicy (see DISCOVERY_CONFIG QosPolicy (DDS Extension) in the Core Libraries User’s Manual). For more information about how to configure the Key Exchange topic reliability protocol settings, see Table 6.7.
Type |
Field Name |
Description |
---|---|---|
|
RTPS protocol-related configuration settings for the builtin Secure Key Exchange writer |
|
|
RTPS protocol-related configuration settings for the builtin Secure Key Exchange reader |
6.8.4. Securing Application-Level Acknowledgments¶
As mentioned in Submessage Protection, the protection of AppAck submessages is determined by metadata_protection_kind
. Therefore, if an AppAck contains valid response data, that response data’s protection is determined by metadata_protection_kind
(not data_protection_kind
). Moreover, the Topic’s enable_read_access_control
(not enable_write_access_control
) determines whether the DataReader is allowed to match with a DataWriter and send such AppAcks. With that in mind, a DomainParticipant with permission to read but not write the Topic could create a DataReader (let’s call it DR1) whose response data always contains all of the sample’s contents being acknowledged. Even if no other DataReaders can interpret the AppAck response data as a data sample (because the response data would not be coming from a DATA submessage), DR1 could compromise the Topic’s payload confidentiality by putting samples in plaintext on the wire.
You can mitigate this threat by setting metadata_protection_kind
to ENCRYPT
. Doing so will force DR1 to set metadata_protection_kind
to ENCRYPT
to match with the DataWriter, ensuring that DR1 will encrypt its response data. Note that this is only true as long as the DataWriter’s DomainParticipant leaves the dds.participant.discovery_config.disable_endpoint_security_info_propagation
property set to FALSE
.
Warning
In Security Plugins 5.3.x or below, it’s still possible to misconfigure DR1 not to encrypt its response data – DR1 would still match with the DataWriter despite setting metadata_protection_kind
not equal to ENCRYPT
.
6.8.5. Origin Authentication Protection Implications¶
As described in Origin Authentication Protection, protecting the origin authentication of a message involves computing and sending a Receiver-Specific MAC to each of the message’s Receivers.
You can reduce the performance impact of ProtectionKinds ending in _WITH_ORIGIN_AUTHENTICATION
by limiting the number of Receiver-Specific MACs in your Secure Domain with the cryptography.max_receiver_specific_macs
property (see Table 6.8). Setting this resource limit will have security implications. For instance, assume that you set cryptography.max_receiver_specific_macs
to 10, and you have 20 DomainParticipants in your Secure Domain. In this case, you will have groups of 2 participants who share the same Receiver-Specific Key and could pretend to be the other participant. Note that, with this setup, all the participants would have a single peer that could be a potential attacker. If this resource limit is unchanged, as the number of participants grows, an increasing number of participants will share the same key. Hence, each participant could impersonate an increasing number of other participants.
For example, suppose you have 100 participants and set this limit to 5. Since the keys will rotate every 5 participants (like in a circular buffer), you will have five groups of 20 participants with the same Receiver-Specific Key. If they happen to have writers and readers for the same Topic, they could potentially attack the origin authentication.
To successfully perform this attack, a malicious participant needs two keys:
The Sender Key: generated by the Sender on the Secure Entity creation. It is only exchanged with Secure Entities matching that of the Sender – for instance, two DRs in different DomainParticipants matching the same DataWriter.
The Receiver-Specific Key: assigned by a DomainParticipant to the other DomainParticipants it discovers. The
cryptography.max_receiver_specific_macs
property limits the number of different Receiver-Specific Keys a DomainParticipant will assign. These keys are assigned in a round-robin fashion – for instance, withcryptography.max_receiver_specific_macs
set to5
, P6 and P1 will share the same Receiver-Specific Key.
Choosing a reasonable value for this property will depend on multiple factors, such as your system’s number of DomainParticipants and number of Topics.
Let’s consider the following scenarios, assuming that all the DPs in your system set cryptography.max_receiver_specific_macs to 5:
In a Secure Domain in which DomainParticipant P0 sends content to six other DomainParticipants, only P1 and P6 will share the Receiver-Specific Key. Therefore, P1 could potentially pretend to be P0 when sending content to P6 and vice versa. This impersonation can only happen if P1 and P6 have DataReaders for the same Topic and have matched the same DataWriter (otherwise, they won’t have the Sender Key to generate the Common MAC.
In a Secure Domain with 100 DomainParticipants, there will be five groups of 20 participants with the same Receiver-Specific Key. In this case, a malicious DomainParticipant could only impersonate the other 19 DomainParticipants with which it shares the Receiver-Specific Key.
As suggested by the second example, the cryptography.max_receiver_specific_macs allows you to divide DomainParticipants into groups, reducing the impact of a potential attack against the origin authentication. Which group a participant belongs in depends on the order of discovery, and therefore, is randomized. In this sense, the cryptography.max_receiver_specific_macs defines the size of a circular buffer with Receiver-Specific Keys. When P1 discovers P2, P1 assigns the next key in its buffer to P2. Suppose P2 loses liveliness with P1, and they discover again. In that case, P1 will assign P2 the next key in its circular buffer, which may differ from the previous one, potentially resulting in a group change with respect to P1.
6.8.6. Reencoding Protected Data when Regenerating Keys¶
As mentioned in Serialized Data Protection and Instance Key Data Protection, a DataWriter that protects its serialized data stores the protected serialized data and instance key data in its queue. And as described in Limiting the Usage of Specific Key Material, it is possible for a DataWriter to change its Key Material during its lifetime. In this section, we describe what happens to the stored protected data when new Key Revisions are introduced.
The property
dds.participant.trust_plugins.key_revision_max_history_depth
determines whether or not to enable Key Revisions. It also determines how many
Key Revisions to keep locally. When the DomainParticipant calls banish_ignored_participants
enough times for the number of Key Revisions to reach this limit, the DomainParticipant
must remove the oldest Key Revision in order to make space for the next
Key Revision. But what if there still exists a sample in the queue that was
protected using the oldest Key Revision?
Let’s consider that we have the following:
S0: A sample that was protected using the oldest Key Revision.
DW1: The sample S0 exists in this DataWriter’s queue.
P1: The local DomainParticipant that is calling
banish_ignored_participants
. DW1 belongs to this DomainParticipant.P2: A new DomainParticipant that joins the system.
DR2: A DataReader with DURABILITY QosPolicy of kind
TRANSIENT_LOCAL
that belongs to P2.
Then, the following could happen:
P1 removes the oldest Key Revision.
P2 joins the system.
P1 sends P2 its seven most recent Key Revisions (see Secure Key Exchange), which do not include the oldest Key Revision because it was just removed.
When DR2 receives S0 from DW1, DR2 is unable to decode S0 because it doesn’t have the necessary Key Revision.
To solve this problem, DW1 has to reencode S0 with the latest Key Revision before P1 removes the oldest Key Revision. The reencoding involves these steps, which are automatically done by Security Plugins:
Block the DataWriter’s Publisher. The DataWriter has to stop writing data during the reencoding.
Decode using the same Key Revision that was used to encode. The Key Revision identifier in the Crypto Header identifies which Key Revision was used to encode.
Encode using the latest Key Revision.
After this reencoding, DR2 will have the necessary Key Revision to decode S0.
Note that P1 sends P2 only its seven most recent Key Revisions. This
number is called the Key Revision Window Size. The number is seven instead
of key_revision_max_history_depth
in order to do the following:
Limit the amount of memory P2 needs for keeping track of the Key Revisions used by P1 and all of the other DomainParticipants communicating with P2.
Limit the amount of network traffic P1 needs for sending Key Revisions to late-joining DomainParticipants.
As a further optimization, the
Key Revision Window Size is reduced from seven to one if P1 never creates any
DataWriters with the RELIABILITY QosPolicy kind set to RELIABLE
and
the data_protection_kind
Governance Rule set to a value other than
NONE
.
Also note that key_revision_max_history_depth
is allowed to be greater than
seven. Consider this scenario:
P1 has
key_revision_max_history_depth
set to7
.A KEEP_LAST DataWriter from P1 encodes S0 using the original Key Material (revision
0
).When P1 has to make space for revision
7
, the DataWriter has to reencode S0.Before sending out S0 to any DataReaders, the DataWriter writes a sample that replaces S0 in the DataWriter’s queue.
That reencoding of S0 has become wasted effort.
To avoid this wasted effort, P1 can set key_revision_max_history_depth
to
a value greater than 7
. Then, the DataWriter will only reencode S0 if
it is actually requested by a DataReader through a NACK message. This is known as
lazy reencoding because it only happens when it’s required by a DataReader. This
configuration avoids wasted reencodings at the cost of additional memory. See
Configuration Properties Affecting Any Cryptography Plugin
for the memory footprint of Key Revisions.
Unlike non-lazy reencoding, lazy reencoding does not require blocking the DataWriter’s Publisher.
6.8.7. Interactions with Persistence Service¶
When you enable security, RTI Persistence Service will perform Serialized Data Protection before storing data into the database, at the level specified by data_protection_kind (topic_rule). To do so, Persistence Service creates Secure DataReaders to subscribe to Topics with TRANSIENT or PERSISTENT durability (see Introduction to RTI Persistence Service in the Core Libraries User’s Manual), and Secure DataWriters to write data to both the network and the database. Hence, after discovering a Topic, Persistence Service creates a PRSTDataReader and a PRSTDataWriter.
The PRSTDataReader receives data from the Connext Databus and verifies (and potentially decrypts) it. The PRSTDataWriter reencodes the data with its own key before inserting it into the database. The stored encoded data includes the payload and the metadata necessary to validate (and potentially decrypt) it, such as the Crypto Header and Crypto Footer (see Serialized Data Protection).
The first time Persistence Service creates a PRSTDataWriter, it
randomly generates a Sender Key that it stores encrypted in the database row
containing the information about the writer. The key used for this encryption
is the output of a derivation function whose input is the required
user-specified property dds.data_writer.history.key_material_key
(see Table 17.1). The
Cryptography Plugin uses PBKDF2 (Password-Based Key Derivation Function) with
SHA-512 (Secure Hash Algorithm with a 512-bit hash value) as the key derivation
function, which also takes a random salt as input; and AES-256-GCM as the
encryption algorithm. The key derivation function derives both the key and the
IV (Initialization Vector) used in the encryption. Persistence Service stores the random salt
along with the PRSTDataWriter’s encrypted Sender Key. If
Key Revisions are enabled (see
Limiting the Usage of Specific Key Material), then
Persistence Service also stores the key_revision_max_history_depth
most
recent Key Revisions, which will be necessary to decode the data upon
restarting Persistence Service (see
Reencoding Protected Data when Regenerating Keys.
Upon restarting Persistence Service, we use the original
PRSTDataWriter’s Key Revision to decode, and we use the new
PRSTDataWriter’s latest Key Revision to encode). The Key Revisions
are encrypted in the same way as the Sender Key.
When Persistence Service restarts, it loads each PRSTDataWriter’s Sender Key and Key Revisions from the database. To do so, Persistence Service needs the same configuration. If a different configuration is provided (e.g., wrong value for dds.data_writer.history.key_material_key
), Persistence Service creation will fail.
Note that when Persistence Service reads the data from the database, the PRSTDataWriter does NOT verify the MAC stored with the data before sending it out on the wire. It is up to the user DataReaders to verify the MAC. Consequently, if an attacker alters the database’s data, the PRSTDataWriter will resend the tampered data many times over the wire until the reliability protocol causes the data to be lost.
For further information, see Support for RTI Persistence Service.
6.8.8. Interactions with FlatData and Zero Copy¶
For more information about Security Plugins’s interactions with RTI FlatData™ language binding and Zero Copy transfer over shared memory, see the following sections in the RTI Connext DDS Core Libraries User’s Manual:
Using FlatData Language Binding in the Core Libraries User’s Manual (see “Interactions with RTI Security Plugins and Compression”)
Using Zero Copy Transfer Over Shared Memory in the Core Libraries User’s Manual (see “Interactions with RTI Security Plugins and Compression”)
6.9. Properties for Configuring Cryptography¶
The QoS Properties listed in Table 6.8 configure Cryptography:
Property Name (prefix with |
Property Value Description |
---|---|
|
Optional The number of message blocks that can be protected with the same Session Key. Whenever the number of blocks exceeds this value, a new Session Key is computed. The block size depends on the encryption algorithm. You can specify this value in decimal, octal, or hex. This value is an unsigned 64-bit integer. Unsigned integer: Default: |
|
Optional The algorithm that the Sender uses for the encryption transformation. The value of this property determines the Transformation Kind sent through the Secure Key Exchange Channel to inform the Receiver about the transformation used to protect the data. The options are DomainParticipants are not required to set this property to the same value in order to communicate with each other. In the Governance Document, a This property is set for DomainParticipants and affects both user and builtin Endpoint.
The exceptions are the Secure Key Exchange DataWriter and DataReader, which always
use Enum: Default: |
|
Optional The maximum number of Receiver-Specific Message Authentication Codes (MACs) that are appended to an encoded result. For example, if this value is 32, and the DomainParticipant is configured to protect both RTPS messages and submessages with Origin Authentication Protection, there could be 32 Receiver-Specific MACs in the result of Setting this value to Integer: Default: |
|
Optional Indicator of whether the metadata and data encoding operations share the same Key Material or use different keys. By default, DataWriters with both Boolean. Default: |
|
Optional Pre-shared key from which Security Plugins derive the HMAC Key used
to compute message authentication codes over UDP WAN binding pings.
This key shares many of the same details as
If this property is not set, then UDP WAN binding pings will not be protected with an HMAC operation. DomainParticipants must set this property to the same value in order to communicate with each other. The purpose of this pre-shared key is to protect against certain DoS attacks against the Real-Time WAN Transport. The value of this property is not used to protect any traffic other than UDP WAN binding pings. All other RTPS traffic still gets protected by the standard Cryptography Plugin, which uses dynamically-generated keys that are exchanged after authentication completes. For more information, please refer to Support for RTI Real-Time WAN Transport. 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 |
- 3
Assuming you used
com.rti.serv.secure
as 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.
6.9.1. Configuration Properties Affecting Any Cryptography Plugin¶
Table 6.9 lists a set of QoS Properties that are not exclusive to the shipped Security Plugins, but that will affect any Cryptography Plugin.
Property Name |
Property Value Description |
---|---|
|
Optional Controls the number of key revisions that are used to encode samples in the DataWriter queues. As the value increases, the reencoding of writer queue historical samples gets more delayed or even avoided, but the memory footprint of the DomainParticipant increases. The memory used for key revisions is preallocated, and it is roughly equal to 36 bytes (or 164 bytes if the DomainParticipant has at least one DataWriter using ODBC writer history) multiplied by the key_revision_max_history_depth. If there is at least one reliable DataWriter that is protecting its payload, then the DomainParticipant will send 7 key revisions instead of just 1 to each late joiner DomainParticipant. Each key revision adds about 128 bytes of network traffic, so that’s 128 * (7 - 1) = 768 more bytes per late joiner DomainParticipant. A DomainParticipant that sets this property to a value other than Integer: Default: |
|
Optional Controls the maximum time in seconds between generating and using a new key revision. After this time, remote DomainParticipants that have not yet acknowledged the new key revision will be completely removed. Integer: Default: |
|
Optional Determines whether or not to align a serialized payload to a 4-byte boundary before encoding it. If Boolean. Default: |
|
Optional Simulate tainted data. Connext DDS will modify one byte of encoded data after the GMAC is computed. This property applies to the DataWriterQos, and can be used for testing validation of the GMAC hash. Note that Connext DDS will only taint live data (repair data is not tainted). Also, tainting of encoded payloads requires running on a little-endian machine. If DecryptFinal failed. Possible GCM authentication failure
See Interface Between the Logging Plugin and the Connext DDS Builtin Logging System for more information about the Security Plugins log level values.
If Boolean. Default: |