6.6. 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 TransportDescriptor. The following is an example of configuration of TLS on the TCP server.

C++

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);
tls_transport->set_WAN_address("80.80.99.45");

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

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
    <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>
            <wan_addr>80.80.99.45</wan_addr>
        </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.

C++

DomainParticipantQos qos;

// Set initial peers.
Locator_t initial_peer_locator;
initial_peer_locator.kind = LOCATOR_KIND_TCPv4;
IPLocator::setIPv4(initial_peer_locator, "80.80.99.45");
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);

// Link the Transport Layer to the Participant.
qos.transport().user_transports.push_back(tls_transport);

XML

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
    <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>
            </tls>
        </transport_descriptor>
    </transport_descriptors>

    <participant profile_name="TLSClientParticipant">
        <rtps>
            <userTransports>
                <transport_id>tls_transport_client</transport_id>
            </userTransports>
            <builtin>
                <initialPeersList>
                    <locator>
                        <tcpv4>
                            <address>80.80.99.45</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

string

empty

Password of the private_key_file or rsa_private_key_file.

private_key_file

string

empty

Path to the private key certificate file.

rsa_private_key_file

string

empty

Path to the private key RSA certificate file.

cert_chain_file

string

empty

Path to the public certificate chain file.

tmp_dh_file

string

empty

Path to the Diffie-Hellman parameters file.

verify_file

string

empty

Path to the CA (Certification- Authority) file.

verify_mode

TLSVerifyMode

empty

Establishes the verification mode mask. See TLS Verification Mode

options

TLSOptions

empty

Establishes the SSL Context options mask. See TLS Options

verify_paths

vector<string>

empty

Paths where the system will look for verification files.

verify_depth

int32_t

empty

Maximum allowed depth for verifying intermediate certificates.

default_verify_path

bool

empty

Look for verification files on the default paths.

handshake_role

TLSHandShakeRole

DEFAULT

Role that the transport will take on handshaking. See TLS Handshake Role

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.6.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 TransportDescriptor using the add_verify_mode() member function.

Value

Description

VERIFY_NONE

Perform no verification.

VERIFY_PEER

Perform verification of the peer.

VERIFY_FAIL_IF_NO_PEER_CERT

Fail verification if the peer has no certificate. Ignored unless VERIFY_PEER is also set.

VERIFY_CLIENT_ONCE

Do not request client certificate on renegotiation. Ignored unless VERIFY_PEER is also set.

Note

For a complete description of the different verification modes, please refer to the OpenSSL documentation.

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

DEFAULT_WORKAROUNDS

Implement various bug workarounds. See Boost.Asio context

NO_COMPRESSION

Disable compression.

NO_SSLV2

Disable SSL v2.

NO_SSLV3

Disable SSL v3.

NO_TLSV1

Disable TLS v1.

NO_TLSV1_1

Disable TLS v1.1.

NO_TLSV1_2

Disable TLS v1.2.

NO_TLSV1_3

Disable TLS v1.3.

SINGLE_DH_USE

Always create a new key when using Diffie-Hellman parameters.

6.6.3. TLS Handshake Role

The role can take the following values:

Value

Description

DEFAULT

Configured as client if connector, and as server if acceptor

CLIENT

Configured as client.

SERVER

Configured as server.