Skip to content

Latest commit

 

History

History
110 lines (95 loc) · 9.46 KB

crypto_plugin.rst

File metadata and controls

110 lines (95 loc) · 9.46 KB
Raw

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| |DomainParticipantQos::properties-api| dds.sec.crypto.plugin with the value builtin.AES-GCM-GMAC. Moreover, this plugin needs the activation of the :ref:`auth-pki-dh`. The DDS:Crypto:AES-GCM-GMAC plugin is configured using the :ref:`access-permissions`, i.e the cryptography plugin is configured through the properties and configuration files of the access control plugin. If the :ref:`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++ 
.. literalinclude:: /../code/DDSCodeTester.cpp
   :language: c++
   :start-after: // DDS_SECURITY_CRYPTO_PLUGIN_DOMAINPARTICIPANT
   :end-before: //!--
   :dedent: 8
XML 
.. literalinclude:: /../code/XMLTester.xml
   :language: xml
   :start-after: <!-->DDS_SECURITY_CRYPTO_PLUGIN_DOMAINPARTICIPANT<-->
   :end-before: <!--><-->

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 (|DataWriterQos::properties-api|) corresponding to the DataWriters in the |DataWriterQos|.

C++ 
.. literalinclude:: /../code/DDSCodeTester.cpp
   :language: c++
   :start-after: // DDS_SECURITY_CRYPTO_PLUGIN_DATAWRITER
   :end-before: //!--
   :dedent: 8
XML 
.. literalinclude:: /../code/XMLTester.xml
   :language: xml
   :start-after: <!-->DDS_SECURITY_CRYPTO_PLUGIN_DATAWRITER<-->
   :end-before: <!--><-->

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 (|DataReaderQos::properties-api|) corresponding to the DataReaders in the |DataReaderQos|.

C++ 
.. literalinclude:: /../code/DDSCodeTester.cpp
   :language: c++
   :start-after: // DDS_SECURITY_CRYPTO_PLUGIN_DATAREADER
   :end-before: //!--
   :dedent: 8
XML 
.. literalinclude:: /../code/XMLTester.xml
   :language: xml
   :start-after: <!-->DDS_SECURITY_CRYPTO_PLUGIN_DATAREADER<-->
   :end-before: <!--><-->