7.3. Cryptographic plugin: DDS:Crypto:AES-GCM-GMAC

The cryptographic plugin provides the tools and operations required to support encryption and decryption, digests computation, message authentication codes computation and verification, key generation, and key exchange for DomainParticipants, DataWriters and DataReaders. Encryption can be applied over three different levels of DDS protocol:

  • The whole RTPS messages.

  • The RTPS submessages of a specific DDS Entity (DataWriter or DataReader).

  • The payload (user data) of a particular DataWriter.

The authentication plugin implemented in Fast DDS is referred to as “DDS:Crypto:AES-GCM-GMAC”, in compliance with the DDS Security specification. This plugin is explained in detail below.

The DDS:Crypto:AES-GCM-GMAC plugin provides authentication encryption using Advanced Encryption Standard (AES) in Galois Counter Mode (AES-GCM). It supports 128 bits and 256 bits AES key sizes. It may also provide additional DataReader-specific Message Authentication Codes (MACs) using Galois MAC (AES-GMAC).

The DDS:Crypto:AES-GCM-GMAC authentication plugin, can be activated setting the DomainParticipantQos Property dds.sec.crypto.plugin with the value builtin.AES-GCM-GMAC. Moreover, this plugin needs the activation of the Authentication plugin: DDS:Auth:PKI-DH plugin. The DDS:Crypto:AES-GCM-GMAC plugin is configured using the Access control plugin: DDS:Access:Permissions plugin, i.e the cryptography plugin is configured through the properties and configuration files of the access control plugin. If the Access control plugin: DDS:Access:Permissions plugin will not be used, you can configure the DDS:Crypto:AES-GCM-GMAC plugin manually with the properties outlined in the following table.

Property name

Description

Property Value

rtps.participant.rtps_protection_kind

Encrypt whole RTPS messages

ENCRYPT

rtps.endpoint.submessage_protection_kind

Encrypt RTPS submessages of a particular entity

ENCRYPT

rtps.endpoint.payload_protection_kind

Encrypt payload of a particular Writer

ENCRYPT

The following is an example of how to set the properties of DomainParticipantQos for the DDS:Crypto:AES-GCM-GMAC configuration.

C++

eprosima::fastdds::dds::DomainParticipantQos pqos;

// Activate DDS:Crypto:AES-GCM-GMAC plugin
pqos.properties().properties().emplace_back("dds.sec.crypto.plugin",
    "builtin.AES-GCM-GMAC");

// Only if DDS:Access:Permissions plugin is not enabled
// Configure DDS:Crypto:AES-GCM-GMAC plugin
pqos.properties().properties().emplace_back(
    "rtps.participant.rtps_protection_kind",
    "ENCRYPT");

XML

<participant profile_name="secure_domainparticipant_conf_crypto_plugin_xml_profile">
    <rtps>
        <propertiesPolicy>
            <properties>
                <!-- Activate DDS:Crypto:AES-GCM-GMAC plugin -->
                <property>
                    <name>dds.sec.crypto.plugin</name>
                    <value>builtin.AES-GCM-GMAC</value>
                </property>
                <!-- Only if DDS:Access:Permissions plugin is not enabled -->
                <!-- Configure DDS:Crypto:AES-GCM-GMAC plugin -->
                <property>
                    <name>rtps.participant.rtps_protection_kind</name>
                    <value>ENCRYPT</value>
                </property>
            </properties>
        </propertiesPolicy>
    </rtps>
</participant>

Next example shows how to configure DataWriters to encrypt their RTPS submessages and the RTPS message payload, i.e. the user data. This is done by setting the DDS:Crypto:AES-GCM-GMAC properties corresponding to the DataWriters in the DataWriterQos.

C++

eprosima::fastdds::dds::DataWriterQos wqos;

// Only if DDS:Access:Permissions plugin is not enabled
// Configure DDS:Crypto:AES-GCM-GMAC plugin
wqos.properties().properties().emplace_back(
    "rtps.endpoint.submessage_protection_kind",
    "ENCRYPT");
wqos.properties().properties().emplace_back(
    "rtps.endpoint.payload_protection_kind",
    "ENCRYPT");

XML

<publisher profile_name="secure_datawriter_conf_crypto_plugin_xml_profile">
    <propertiesPolicy>
        <properties>
            <!-- Only if DDS:Access:Permissions plugin is not enabled -->
            <!-- Configure DDS:Crypto:AES-GCM-GMAC plugin -->
            <property>
                <name>rtps.endpoint.submessage_protection_kind</name>
                <value>ENCRYPT</value>
            </property>
            <property>
                <name>rtps.endpoint.payload_protection_kind</name>
                <value>ENCRYPT</value>
            </property>
        </properties>
    </propertiesPolicy>
</publisher>

The last example shows how to configure DataReader to encrypt their RTPS submessages. This is done by setting the DDS:Crypto:AES-GCM-GMAC properties corresponding to the DataReaders in the DataReaderQos.

C++

eprosima::fastdds::dds::DataWriterQos rqos;

// Only if DDS:Access:Permissions plugin is not enabled
// Configure DDS:Crypto:AES-GCM-GMAC plugin
rqos.properties().properties().emplace_back(
    "rtps.endpoint.submessage_protection_kind",
    "ENCRYPT");

XML

<subscriber profile_name="secure_datareader_conf_crypto_plugin_xml_profile">
    <propertiesPolicy>
        <properties>
            <!-- Only if DDS:Access:Permissions plugin is not enabled -->
            <!-- Configure DDS:Crypto:AES-GCM-GMAC plugin -->
            <property>
                <name>rtps.endpoint.submessage_protection_kind</name>
                <value>ENCRYPT</value>
            </property>
        </properties>
    </propertiesPolicy>
</subscriber>