6.7. TLS over TCP
Warning
This documentation assumes the reader has basic knowledge of TLS concepts since terms like Certificate Authority (CA), Private Key, Rivest–Shamir–Adleman (RSA) cryptosystem, and Diffie-Hellman encryption protocol are not explained in detail.
Fast DDS allows configuring TCP Transports to use TLS (Transport Layer Security).
In order to set up TLS, the TCPTransportDescriptor must
have its apply_security
data member set to true
, and its
tls_config
data member filled with the desired configuration on the
TCPTransportDescriptor
.
The following is an example of configuration of TLS on the TCP server.
DomainParticipantQos qos;
// Create a descriptor for the new transport.
auto tls_transport = std::make_shared<TCPv4TransportDescriptor>();
tls_transport->sendBufferSize = 9216;
tls_transport->receiveBufferSize = 9216;
tls_transport->add_listener_port(5100);
// Create the TLS configuration
using TLSOptions = eprosima::fastdds::rtps::TCPTransportDescriptor::TLSConfig::TLSOptions;
tls_transport->apply_security = true;
tls_transport->tls_config.password = "test";
tls_transport->tls_config.cert_chain_file = "server.pem";
tls_transport->tls_config.private_key_file = "serverkey.pem";
tls_transport->tls_config.tmp_dh_file = "dh2048.pem";
tls_transport->tls_config.add_option(TLSOptions::DEFAULT_WORKAROUNDS);
tls_transport->tls_config.add_option(TLSOptions::SINGLE_DH_USE);
tls_transport->tls_config.add_option(TLSOptions::NO_SSLV2);
// Link the Transport Layer to the Participant.
qos.transport().user_transports.push_back(tls_transport);
<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com">
<transport_descriptors>
<transport_descriptor>
<transport_id>tls_transport_server</transport_id>
<type>TCPv4</type>
<tls>
<password>test</password>
<private_key_file>serverkey.pem</private_key_file>
<cert_chain_file>server.pem</cert_chain_file>
<tmp_dh_file>dh2048.pem</tmp_dh_file>
<options>
<option>DEFAULT_WORKAROUNDS</option>
<option>SINGLE_DH_USE</option>
<option>NO_SSLV2</option>
</options>
</tls>
<sendBufferSize>9216</sendBufferSize>
<receiveBufferSize>9216</receiveBufferSize>
<listening_ports>
<port>5100</port>
</listening_ports>
</transport_descriptor>
</transport_descriptors>
<participant profile_name="TLSServerParticipant">
<rtps>
<userTransports>
<transport_id>tls_transport_server</transport_id>
</userTransports>
</rtps>
</participant>
</profiles>
The corresponding configuration on the TCP client is shown in the following example.
DomainParticipantQos qos;
// Set initial peers.
Locator_t initial_peer_locator;
initial_peer_locator.kind = LOCATOR_KIND_TCPv4;
IPLocator::setIPv4(initial_peer_locator, "192.168.1.10");
initial_peer_locator.port = 5100;
qos.wire_protocol().builtin.initialPeersList.push_back(initial_peer_locator);
// Create a descriptor for the new transport.
auto tls_transport = std::make_shared<TCPv4TransportDescriptor>();
// Create the TLS configuration
using TLSOptions = eprosima::fastdds::rtps::TCPTransportDescriptor::TLSConfig::TLSOptions;
using TLSVerifyMode = eprosima::fastdds::rtps::TCPTransportDescriptor::TLSConfig::TLSVerifyMode;
tls_transport->apply_security = true;
tls_transport->tls_config.verify_file = "ca.pem";
tls_transport->tls_config.add_verify_mode(TLSVerifyMode::VERIFY_PEER);
tls_transport->tls_config.add_verify_mode(TLSVerifyMode::VERIFY_FAIL_IF_NO_PEER_CERT);
tls_transport->tls_config.add_option(TLSOptions::DEFAULT_WORKAROUNDS);
tls_transport->tls_config.add_option(TLSOptions::SINGLE_DH_USE);
tls_transport->tls_config.add_option(TLSOptions::NO_SSLV2);
tls_transport->tls_config.server_name = "my_server.com";
// Link the Transport Layer to the Participant.
qos.transport().user_transports.push_back(tls_transport);
<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com">
<transport_descriptors>
<transport_descriptor>
<transport_id>tls_transport_client</transport_id>
<type>TCPv4</type>
<tls>
<verify_file>ca.pem</verify_file>
<verify_mode>
<verify>VERIFY_PEER</verify>
<verify>VERIFY_FAIL_IF_NO_PEER_CERT</verify>
</verify_mode>
<options>
<option>DEFAULT_WORKAROUNDS</option>
<option>SINGLE_DH_USE</option>
<option>NO_SSLV2</option>
</options>
<server_name>my_server.com</server_name>
</tls>
</transport_descriptor>
</transport_descriptors>
<participant profile_name="TLSClientParticipant">
<rtps>
<userTransports>
<transport_id>tls_transport_client</transport_id>
</userTransports>
<builtin>
<initialPeersList>
<locator>
<tcpv4>
<address>192.168.1.10</address>
<physical_port>5100</physical_port>
</tcpv4>
</locator>
</initialPeersList>
</builtin>
</rtps>
</participant>
</profiles>
The following table describes the data members that are configurable on TLSConfig
.
Member |
Data type |
Default |
Description |
---|---|---|---|
|
|
Password of the |
|
|
|
Path to the private key certificate file. |
|
|
|
Path to the private key RSA certificate file. |
|
|
|
Path to the public certificate chain file. |
|
|
|
Path to the Diffie-Hellman parameters file. |
|
|
|
Path to the CA (Certification- Authority) file. |
|
Establishes the verification mode mask. |
|||
Establishes the SSL Context options mask. |
|||
|
Empty vector |
Paths where the system will look for verification files. |
|
|
-1 |
Maximum allowed depth for verifying intermediate |
|
|
|
Look for verification files on the default paths. |
|
Role that the transport will take on handshaking. |
|||
|
|
Server name or host name required in case |
Note
Fast DDS uses the Boost.Asio library to handle TLS secure connections. These data members are used to build the asio library context, and most of them are mapped directly into this context without further manipulation. You can find more information about the implications of each member on the Boost.Asio context documentation.
6.7.1. TLS Verification Mode
The verification mode defines how the peer node will be verified.
The following table describes the available verification options.
Several verification options can be combined in the same TCPTransportDescriptor
using the add_verify_mode()
member function.
Value |
Description |
---|---|
Perform no verification. |
|
Perform verification of the peer. |
|
Fail verification if the peer has no certificate.
Ignored unless |
|
Do not request client certificate on renegotiation.
Ignored unless |
Note
For a complete description of the different verification modes, please refer to the OpenSSL documentation.
6.7.2. TLS Options
These options define which TLS features are to be supported.
The following table describes the available options.
Several options can be combined in the same TransportDescriptor
using the add_option()
member function.
Value |
Description |
---|---|
Implement various bug workarounds. See Boost.Asio context. |
|
Disable compression. |
|
Disable SSL v2. |
|
Disable SSL v3. |
|
Disable TLS v1. |
|
Disable TLS v1.1. |
|
Disable TLS v1.2. |
|
Disable TLS v1.3. |
|
Always create a new key when using Diffie-Hellman parameters. |
6.7.3. TLS Handshake Role
The role can take the following values:
Value |
Description |
---|---|
Configured as client if connector, and as server if acceptor |
|
Configured as client. |
|
Configured as server. |