8.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
properties()
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.
The DDS:Crypto:AES-GCM-GMAC plugin is configured using the Access control plugin: DDS:Access:Permissions, 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 |
|
rtps.endpoint.submessage_protection_kind |
Encrypt RTPS submessages of a particular entity |
|
rtps.endpoint.payload_protection_kind |
Encrypt payload of a particular Writer |
|
The following is an example of how to set the properties of DomainParticipantQoS for the DDS:Crypto:AES-GCM-GMAC configuration.
C++ |
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 (properties()
) corresponding to the
DataWriters in the DataWriterQos.
C++ |
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 |
<data_writer 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>
</data_writer>
|
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 (properties()
) corresponding to the
DataReaders in the DataReaderQos.
C++ |
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 |
<data_reader 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>
</data_reader>
|