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

Figure 6.1 Parts of the Message Protected by Each Protection Kind

The Cryptography Plugin uses AES-GCM to protect the traffic. 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. 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.2.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.

Figure 6.2 Architecture Overview of Two Matching Secure Entities

6.2.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.2.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 File, see Governance File).

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.2.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 and is identified by the Sender Key ID.

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

Figure 6.3 Derivation of the Session Key and Receiver-Specific Session Keys

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

Figure 6.4 Key Derivation in the Sender. The Key Material is stored in the Secure Entity.

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.2.2. Lifecycle of Secure Entities

6.2.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.2.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 this Governance compatibility checks, when you enable security, Connext DDS sends additional properties as part of the discovery information. These properties support making matching decisions. For further details, see Governance Compatibility Validation.

6.2.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.2.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.

Figure 6.6 Reception of a Secure Message

6.2.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-, 192-, 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_EFFORTS kind), Lifespan, and TimeBasedFilter, among others, can result in a DataReader receiving a subset of the samples written by a DataWriter.

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

Note that Security Plugins 6.1.0 does NOT support key renewal. However, the Session ID changes when a certain number of blocks have been encrypted with the same Session Key. This results in using a different Session Key for the following messages without the need of generating and exchanging new Key Material. Since the original Key Material stays the same, this mechanism is not useful for kicking off participants from the system.

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

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. Securing DDS Messages on The Wire

When sending a protected message, some cryptographic information is added to let the Receiver know how the message was protected (Transformation Kind) and what keys were used (identified by the Sender Key ID). This information goes in the Crypto Header. Then the Crypto Content submessage element is used to wrap a Serialized Payload, an RTPS submessage, or a complete RTPS message. The Crypto Content is the result of applying one of the cryptographic transformations to the protected message. Also, a Crypto Footer is appended to the (potentially encrypted) message. The Crypto Footer contains the authentication tag that protects the message integrity (aka Common MAC). If Origin Authentication Protection is enabled, the Crypto Footer will also contain the Receiver-Specific MACs.

Depending on where you apply the protection, the message that is sent on the wire will be secured in different ways. This has further implications that we analyze next.

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

Figure 6.7 General Structure of an RTPS Message

6.4.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. The DataWriter protects the sample payload right after the serialization. The protected sample (including the MAC and potentially being encrypted) is stored in the DataWriter’s queue until sent (it may be sent in a batch). 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.

Figure 6.8 RTPS Message Transformation with Serialized Data Protection

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

Figure 6.9 RTPS Message Transformation with Submessage Protection

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

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

\[\lbrace A\rbrace\cup\lbrace B\rbrace\cup\lbrace A,B,C,D\rbrace=\lbrace A,B,C,D\rbrace\]

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.

Figure 6.12 Location of the Different Kinds of Protection

6.4.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.4.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 the Transformation Kind and the 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.

• 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.4.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.4.2.3. Crypto Footer

The Crypto Footer consists of the Common MAC (and the Receiver-Specific MACs, when Origin Authentication Protection is used).

• Common MAC: The Common MAC in the Crypto Footer is the authentication tag generated by the AES-GMAC transformation using the Session Key and the Initialization Vector. This transformation operates on the message being protected in plaintext when the SIGN protection kind is used, or on the encrypted message when the protection kind is ENCRYPT. The result is a 128-bit (16-byte) MAC that protects the message integrity.

• Receiver-Specific MACs: (only when Origin Authentication Protection is used) The Receiver-Specific MACs in the Crypto Footer are the AES-GMAC tags computed on the Common MAC using each of the Receiver-Specific Session Keys and the same Initialization Vector. Each of the Receiver-Specific MACs is 128-bit (16-byte).

The Receiver-Specific MACs are computed with a secret key that the Sender shares only with a set of Receivers (ideally one). The Receiver-Specific MACs provide origin authentication to the Receiver even when the Sender is communicating with multiple Receivers via multicast and shares the same encryption key with all of them. For more information, see Origin Authentication Protection Implications.

6.5. 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 File, you are actually defining the Entities and Secure Entities that are used to transmit the information related to that Topic. This includes:

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

2. Whether the Endpoint Discovery traffic will be exchanged through the secure version of the Builtin Discovery Endpoints.

3. Whether the liveliness assertions will be exchanged through the secure version of the Builtin Participant Message Endpoints (if the LIVELINESS QosPolicy is AUTOMATIC or MANUAL_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.5.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 or cryptography.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.

Table 6.1 Protection Levels Applied by Secure DomainParticipants During RTPS Protection

Governance Rule	ProtectionKind	Level of Protection
rtps_protection_kind	NONE	No protection
	SIGN	Integrity
	ENCRYPT	Integrity and confidentiality
	SIGN_WITH_ORIGIN_AUTHENTICATION	Integrity and origin authentication
	ENCRYPT_WITH_ORIGIN_AUTHENTICATION	Integrity, confidentiality, and origin authentication

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

Table 6.2 Protection Levels Applied by user-defined Endpoints for Serialized Data Protection

Governance Rule	ProtectionKind	Level of Protection
data_protection_kind	NONE	No protection
	SIGN	Integrity
	ENCRYPT	Integrity and confidentiality

Table 6.3 Protection Levels Applied by user-defined Endpoints for Submessage Protection

Governance Rule	ProtectionKind	Level of Protection
metadata_protection_kind	NONE	No protection
	SIGN	Integrity
	ENCRYPT	Integrity and confidentiality
	SIGN_WITH_ORIGIN_AUTHENTICATION	Integrity and origin authentication
	ENCRYPT_WITH_ORIGIN_AUTHENTICATION	Integrity, confidentiality, and origin authentication

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

Table 6.4 Protection Levels Applied by Builtin Secure Discovery Endpoints and Builtin Secure ServiceRequest Endpoints in the Submessage Protection Stage

Governance Rule	ProtectionKind	Level of Protection
discovery_protection_kind	NONE	No protection
	SIGN	Integrity
	ENCRYPT	Integrity and confidentiality
	SIGN_WITH_ORIGIN_AUTHENTICATION	Integrity and origin authentication
	ENCRYPT_WITH_ORIGIN_AUTHENTICATION	Integrity, confidentiality, and origin authentication

6.5.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.5.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.

Table 6.5 Protection Levels Applied by Builtin Secure Liveliness Endpoints at the Submessage Protection Stage

Governance Rule	ProtectionKind	Level of Protection
liveliness_protection_kind	NONE	No protection
	SIGN	Integrity
	ENCRYPT	Integrity and confidentiality
	SIGN_WITH_ORIGIN_AUTHENTICATION	Integrity and origin authentication
	ENCRYPT_WITH_ORIGIN_AUTHENTICATION	Integrity, confidentiality, and origin authentication

6.6. Related Governance Rules

You can control what protection kind you apply to different parts of your communication. You can do this by setting some Cryptography rules in your Governance Document. For information on what Secure Entity is responsible for protecting each part of the message, see Security Protections Applied by DDS Entities.

6.6.1. Understanding ProtectionKinds

Attributes whose names end with _protection_kind share a type called ProtectionKind. The DDS Security specification lists five possible values of ProtectionKind, all of which are supported by the Security Plugins.

• NONE indicates that no cryptographic transformation is applied.

• SIGN indicates that the cryptographic transformation is purely a Galois message authentication code (GMAC, referred to as MAC), which protects the integrity of the message the protection applies to. No encryption is performed. The MAC is placed after the content (in the Crypto Footer). If the Receiver finds a missing or incorrect MAC, the Receiver will reject the content.

• ENCRYPT indicates that the cryptographic transformation is AES encrypted followed by a MAC computed on the ciphertext, also known as Galois/Counter Mode (GCM), protecting both the integrity and confidentiality of the messages. The MAC is placed after the content (in the Crypto Footer). If the Receiver finds a missing or incorrect MAC, the Receiver will reject the content.

• ProtectionKinds ending in _WITH_ORIGIN_AUTHENTICATION indicate that in addition to using the Sender’s key to generate a Common MAC, the Sender generates Receiver-Specific MACs using keys that are only shared with a subset of Receivers (ideally, only one). The additional MACs are placed after the Common MAC (also in the Crypto Footer). They prove to the Receiver that the Sender originated the message, preventing other Receivers from impersonating the Sender. If the Receiver finds a missing or incorrect Common MAC, the Receiver will reject the content. If the Receiver finds a missing or incorrect Receiver-Specific MAC that was computed using its own Receiver-Specific Key, the Receiver will reject the content. For further details, see Origin Authentication Protection).

  Note

  The ProtectionKinds ending in _WITH_ORIGIN_AUTHENTICATION are allowed only if the value of the property cryptography.max_receiver_specific_macs is greater than 1 (see Table 6.8).

The ProtectionKinds ending in _WITH_ORIGIN_AUTHENTICATION are as follows:

• SIGN_WITH_ORIGIN_AUTHENTICATION indicates that a Common MAC is performed on the content, and Receiver-Specific MACs are performed on the Common MAC. This provides integrity and origin authentication protections.

• ENCRYPT_WITH_ORIGIN_AUTHENTICATION indicates that a GCM is performed on the content, and Receiver-Specific MACs are performed on the Common MAC. This provides integrity, confidentiality, and origin authentication protections.

6.6.2. Domain-Level Rules

The following attributes belong inside a domain_rule.

6.6.2.1. rtps_protection_kind (domain_rule)

This ProtectionKind specifies how to protect a DomainParticipant’s outgoing messages and what kind of protection is required of incoming messages. A message consists of an RTPS header and submessages, so a message is an envelope around submessages. If allow_unauthenticated_participants = TRUE, rtps_protection_kind must be set to NONE. Setting rtps_protection_kind to NONE will cause the DomainParticipant to accept both protected and unprotected incoming RTPS messages. Setting rtps_protection_kind to something other than NONE will cause the DomainParticipant to reject incoming RTPS messages that have a missing or incorrect MAC.

6.6.2.2. discovery_protection_kind (domain_rule)

This ProtectionKind specifies the metadata_protection_kind used for the secure builtin DataWriter and DataReader entities used for discovery, Topic Queries, and Locator Reachability Responses.

The discovery_protection_kind will protect Endpoint Discovery for the Topics that set enable_discovery_protection. This includes information exchanged for discovering new Endpoint and for updating existing ones, as described in enable_discovery_protection (topic_rule). The discovery_protection_kind will also protect messages that contain updates to the existing DomainParticipants. Note that new DomainParticipant discovery announcements are never protected (but updates to existing DomainParticipants are protected).

6.6.2.3. liveliness_protection_kind (domain_rule)

This ProtectionKind specifies the metadata_protection_kind used for the secure builtin DataWriter and DataReader entities used for liveliness.

The liveliness_protection_kind will protect liveliness information from Topics that set enable_liveliness_protection (only if the DataWriter’s LIVELINESS QosPolicy is AUTOMATIC or MANUAL_BY_PARTICIPANT, as described in enable_liveliness_protection (topic_rule)).

6.6.3. Topic-Level Rules

The following attributes belong inside a topic_rule.

6.6.3.1. metadata_protection_kind (topic_rule)

This ProtectionKind specifies how to protect a DataWriter’s or DataReader’s outgoing RTPS submessages. These submessages include, but are not limited to, DATA, HEARTBEAT, ACKNACK, APP_ACK, and GAP. (For the full list of affected RTPS submessages, refer to Submessage Protection.) Note that DATA submessage is an envelope around a serialized payload, so metadata_protection_kind affects data as well as metadata.

6.6.3.2. data_protection_kind (topic_rule)

This attribute may be NONE, SIGN, or ENCRYPT. It specifies how to protect a DataWriter’s serialized payload, as described in Serialized Data Protection.

The DataWriter applies this protection upon adding the serialized payload to the DataWriter’s queue (the DataWriter’s queue stores the protected payload). In that sense, one difference between metadata_protection_kind and data_protection_kind is that for metadata_protection_kind, the submessage protection takes effect immediately before sending out the content, so if a given serialized payload needs to be resent multiple times, the submessage protection will be re-computed every time the serialized payload is (re)sent; on the other hand, the serialized data protection is applied only when the sample is added to the writer queue and, therefore, this protection does not need to be re-computed every time the serialized payload is sent.

Receiver-Specific MACs are never included in this protection, so the ProtectionKinds ending in _WITH_ORIGIN_AUTHENTICATION are not allowed for this attribute.

6.6.3.3. enable_discovery_protection (topic_rule)

This attribute may be TRUE or FALSE. It specifies whether to use the secure or unsecure builtin Endpoint for certain outgoing traffic related to this Topic. Such traffic includes Endpoint Discovery messages and TopicQuery messages. enable_discovery_protection also specifies whether or not to reject unsecure incoming Endpoint Discovery messages related to this Topic. For further details, see Builtin Secure Discovery Endpoints.

6.6.3.4. enable_liveliness_protection (topic_rule)

This attribute may be TRUE or FALSE. The value of this attribute matters only if the DataWriter’s LIVELINESS QosPolicy is AUTOMATIC or MANUAL_BY_PARTICIPANT (see LIVELINESS QosPolicy in the Core Libraries User’s Manual). In either of these cases, enable_liveliness_protection specifies whether or not to use the secure builtin Endpoint for exchanging liveliness messages for DataWriters of this Topic. Otherwise, when LIVELINESS QosPolicy is MANUAL_BY_TOPIC, this attribute does not take effect and it is the user-defined Secure Endpoints that take care of liveliness assertions, which are protected with metadata_protection_kind. For further details, see Builtin Secure Discovery Endpoints.

6.7. Advanced Cryptography Concepts

6.7.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 or rtps_protection_kind is a value other than NONE, 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 than NONE, the sample will be rejected by the DataReader queue (or lost, in the case of best effort communication).

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

Table 6.6 DDS_DiscoveryConfigQosPolicy Fields Affecting the Secure Key Exchange Builtin Topic

Type	Field Name	Description
PUBLISH_MODE QosPolicy (DDS Extension)	secure_volatile_writer_publish_mode	Determines whether the Key Exchange builtin subscription DataWriter publishes data synchronously or asynchronously, and how.

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

Table 6.7 DDS_DiscoveryConfigQosPolicy Fields Affecting the RTPS Protocol-Related Configuration of the Secure Key Exchange Builtin Topic

Type	Field Name	Description
RtpsReliableWriterProtocol_t	secure_volatile_writer	RTPS protocol-related configuration settings for the builtin Secure Key Exchange writer
DDS_RtpsReliableReaderProtocol_t	secure_volatile_reader	RTPS protocol-related configuration settings for the builtin Secure Key Exchange reader

6.7.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.7.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, with cryptography.max_receiver_specific_macs set to 5, 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:

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

2. 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.7.6. 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 re-encodes 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 16.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.

When Persistence Service restarts, it loads each PRSTDataWriter’s Sender Key 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.7.7. 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.7.8. Pre-Shared Key RTPS Protection

To avoid the discovery-time overhead of mutual authentication and key exchange, you may use the RTPS-HMAC-Only Plugins described in RTPS-HMAC-Only Mode and provide a pre-shared key with the hmac_only.cryptography.key property (see Table 14.1). If you are using the UDP WAN transport and you do not want to use the RTPS-HMAC-Only Plugins, you may provide a pre-shared key via the cryptography.rtps_protection_key property to protect the binding pings (see Table 6.8).

6.8. Properties for Configuring Cryptography

The QoS Properties listed in Table 6.8 configure Cryptography:

Table 6.8 RTI Security Plugins Properties for Configuring Cryptography

Property Name (prefix with com.rti.serv.secure.) 3	Property Value Description
cryptography.max_blocks_per_session	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: [1 - MAX_UINT64] Default: MAX_UINT64
cryptography.encryption_algorithm	Optional The algorithm that the Sender uses for the encryption transformation. The value of this property determines the Transformation Kind sent in the protected messages (and through the Secure Key Exchange Channel) to inform the Receiver about the transformation used to protect the data. The options are aes-128-gcm, aes-192-gcm, and aes-256-gcm (“gcm” is Galois/Counter Mode (GCM) authenticated encryption). The number indicates the number of bits in the key. DomainParticipants are not required to set this property to the same value in order to communicate with each other. In the Governance Document, a protection_kind set to ENCRYPT will use GCM, and a protection_kind set to SIGN will use the GMAC variant of this algorithm. Enum: aes-128-gcm, aes-192-gcm, aes-256-gcm Default: aes-128-gcm
cryptography.max_receiver_specific_macs	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 encode_datawriter_submessage, and there could be another 32 Receiver-Specific MACs in the result of encode_rtps_message. If there are more than 32 Receivers, the Receivers will be assigned one of the 32 possible MACs in a round-robin fashion. Note that in the case of encode_datawriter_submessage, all the readers belonging to the same DomainParticipant will always be assigned the same Receiver-Specific MAC. Setting this value to 0 will completely disable Receiver-Specific MACs. For further details see Origin Authentication Protection Implications. Integer: [2, 3275], or 0 to completely disable Receiver-Specific MACs. Default: 0 (WITH_ORIGIN_AUTHENTICATION protection kinds not allowed)
cryptography.share_key_for_metadata_and_data_protection	Optional Indicator of whether the metadata and data encoding operations share the same Key Material or use different keys. By default, DataWriters with both metadata_protection_kind and data_protection_kind set to a value other than NONE use the same Key Material for protecting both RTPS submessages and serialized data. To change this behavior, set this property to FALSE. Boolean. Default: TRUE (they share Key Material)
cryptography.rtps_protection_key	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 hmac_only.cryptography.key. See that property’s description in Table 14.1 for the details. 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 with com.rti.serv.load_plugins, followed by the . character.

6.8.1. Configuration Properties Affecting Connext DDS Core Libraries Behavior

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.

Table 6.9 Properties for Configuring Cryptography Common to Any Cryptography Plugin

Property Name

Property Value Description

dds.data_writer.history.use_530_encoding_alignment

Optional Determines whether or not to align a serialized payload to a 4-byte boundary before encoding it. If TRUE, this alignment does not occur; this is consistent with Connext DDS 5.3.0 behavior. If FALSE, then this alignment does occur; this is the only way to make the builtin Cryptography Plugin work with data_protection_kind = SIGN. This property applies to the DataWriterQos. Boolean. Default: FALSE