Example DDS security configuration

This section shows an example Cyclone DDS configuration for DDS Security.

The steps for configuring DDS Security are:

  1. Create a permissions Certificate Authority (CA)

  2. Create an identity certificate

  3. Create a signed governance document

  4. Create a signed permissions document

  5. Either:

Create a permissions Certificate Authority (CA)

To generate the CA for identity management (authentication):

  1. Create the private key for the CA:

    openssl genrsa -out example_id_ca_priv_key.pem 2048

  2. Create the certificate for the identity CA (which is a self-signed certificate):

    openssl req -x509 -key example_id_ca_priv_key.pem -out example_id_ca_cert.pem -days 3650 -subj "/C=NL/ST=OV/L=Locality Name/OU=Example OU/O=Example ID CA Organization/CN=Example ID CA/emailAddress=authority@cycloneddssecurity.zettascale.com"

  3. Create the private key of the permissions CA (used for signing the AccessControl configuration files):

    openssl genrsa -out example_perm_ca_priv_key.pem 2048

  4. Create the self-signed certificate for the permissions CA:

    openssl req -x509 -key example_perm_ca_priv_key.pem -out example_perm_ca_cert.pem -days 3650 -subj "/C=NL/ST=OV/L=Locality Name/OU=Example OU/O=Example CA Organization/CN=Example Permissions CA/emailAddress=authority@cycloneddssecurity.zettascale.com"

Create an identity certificate

Create an identity certificate (signed by the CA), and the private key corresponding to an identity named Alice.

Note

These steps need to be repeated for each identity in the system.

To create a private key and an identity certificate for an identity named Alice:

  1. Create the private key for Alice’s identity:

    openssl genrsa -out example_alice_priv_key.pem 2048

  2. To request that the identity CA generates a certificate, create a Certificate Signing Request (CSR):

    openssl req -new -key example_alice_priv_key.pem -out example_alice.csr -subj "/C=NL/ST=OV/L=Locality Name/OU=Organizational Unit Name/O=Example Organization/CN=Alice Example/emailAddress=alice@cycloneddssecurity.zettascale.com"

  3. Create Alice’s identity certificate:

    openssl x509 -req -CA example_id_ca_cert.pem -CAkey example_id_ca_priv_key.pem -CAcreateserial -days 3650 -in example_alice.csr -out example_alice_cert.pem

  4. In the DDS Security authentication configuration:

    • Use Alice’s private key (example_alice_priv_key.pem) file for the PrivateKey setting.

    • Use Alice’s identity certificate (example_alice_cert.pem) file for the IdentityCertificate setting.

    • Use the certificate of the CA used for signing this identity (example_id_ca_cert.pem), for the IdentityCA setting.

Create a signed governance document

The following shows an example of a governance document that uses signing for submessage and an encrypted payload:

 1<?xml version="1.0" encoding=\"utf-8\"?>
 2<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://www.omg.org/spec/DDS-SECURITY/20170901/omg_shared_ca_governance.xsd">
 3  <domain_access_rules>
 4    <domain_rule>
 5      <domains>
 6        <id_range>
 7          <min>0</min>
 8          <max>230</max>
 9        </id_range>
10      </domains>
11      <allow_unauthenticated_participants>false</allow_unauthenticated_participants>
12      <enable_join_access_control>true</enable_join_access_control>
13      <discovery_protection_kind>NONE</discovery_protection_kind>
14      <liveliness_protection_kind>NONE</liveliness_protection_kind>
15      <rtps_protection_kind>NONE</rtps_protection_kind>
16      <topic_access_rules>
17        <topic_rule>
18          <topic_expression>*</topic_expression>
19          <enable_discovery_protection>true</enable_discovery_protection>
20          <enable_liveliness_protection>true</enable_liveliness_protection>
21          <enable_read_access_control>true</enable_read_access_control>
22          <enable_write_access_control>true</enable_write_access_control>
23          <metadata_protection_kind>SIGN</metadata_protection_kind>
24          <data_protection_kind>ENCRYPT</data_protection_kind>
25        </topic_rule>
26      </topic_access_rules>
27    </domain_rule>
28  </domain_access_rules>
29</dds>

The governance document must be signed by the permissions CA.

To sign the governance document:

openssl smime -sign -in example_governance.xml -text -out example_governance.p7s -signer example_perm_ca_cert.pem -inkey example_perm_ca_priv_key.pem

Create a signed permissions document

The permissions document is an XML document that contains the permissions of the participant and binds them to the subject name in the identity certificate (distinguished name) for the participant as defined in the DDS authentication plugin.

An example of a permissions document:

 1<?xml version="1.0" encoding="utf-8" ?>
 2<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 3     xsi:noNamespaceSchemaLocation="https://www.omg.org/spec/DDS-SECURITY/20170901/omg_shared_ca_permissions.xsd">
 4  <permissions>
 5    <grant name="default_permissions">
 6      <subject_name>emailAddress=alice@cycloneddssecurity.adlinktech.com,CN=Alice Example,O=Example Organization,OU=Organizational Unit Name,L=Locality Name,ST=OV,C=NL</subject_name>
 7      <validity>
 8        <!-- Format is CCYY-MM-DDThh:mm:ss[Z|(+|-)hh:mm] in GMT -->
 9        <not_before>2020-01-01T01:00:00</not_before>
10        <not_after>2120-01-01T01:00:00</not_after>
11      </validity>
12      <allow_rule>
13        <domains>
14          <id_range>
15            <min>0</min>
16            <max>230</max>
17          </id_range>
18        </domains>
19        <publish>
20          <topics>
21            <topic>*</topic>
22          </topics>
23          <partitions>
24            <partition>*</partition>
25          </partitions>
26        </publish>
27        <subscribe>
28          <topics>
29            <topic>*</topic>
30          </topics>
31          <partitions>
32            <partition>*</partition>
33          </partitions>
34        </subscribe>
35      </allow_rule>
36      <default>DENY</default>
37    </grant>
38  </permissions>
39</dds>

This document also needs to be signed by the permissions CA:

openssl smime -sign -in example_permissions.xml -text -out example_permissions.p7s -signer example_perm_ca_cert.pem -inkey example_perm_ca_priv_key.pem

Set the security properties in participant QoS

The following code fragment shows how to set the security properties to a QoS object, and use this QoS when creating a participant:

 1dds_qos_t * qos = dds_create_qos();
 2
 3dds_qset_prop(qos, "dds.sec.auth.library.path", "dds_security_auth");
 4dds_qset_prop(qos, "dds.sec.auth.library.init", "init_authentication");
 5dds_qset_prop(qos, "dds.sec.auth.library.finalize", "finalize_authentication");
 6dds_qset_prop(qos, "dds.sec.auth.identity_ca", "file:/path/to/example_id_ca_cert.pem");
 7dds_qset_prop(qos, "dds.sec.auth.private_key", "file:/path/to/example_alice_priv_key.pem");
 8dds_qset_prop(qos, "dds.sec.auth.identity_certificate", "file:/path/to/example_alice_cert.pem");
 9
10dds_qset_prop(qos, "dds.sec.crypto.library.path", "dds_security_crypto");
11dds_qset_prop(qos, "dds.sec.crypto.library.init", "init_crypto");
12dds_qset_prop(qos, "dds.sec.crypto.library.finalize", "finalize_crypto");
13
14dds_qset_prop(qos, "dds.sec.access.library.path", "dds_security_ac");
15dds_qset_prop(qos, "dds.sec.access.library.init", "init_access_control");
16dds_qset_prop(qos, "dds.sec.access.library.finalize", "finalize_access_control");
17dds_qset_prop(qos, "dds.sec.access.permissions_ca", "file:/path/to/example_perm_ca_cert.pem");
18dds_qset_prop(qos, "dds.sec.access.governance", "file:/path/to/example_governance.p7s");
19dds_qset_prop(qos, "dds.sec.access.permissions", "file:/path/to/example_permissions.p7s");
20
21dds_entity_t participant = dds_create_participant(0, qos, NULL);

Apply security settings

As an alternative for using the QoS, security settings can also be applied using the Cyclone DDS configuration XML. If both QoS and the configuration XML contain security settings, the values from the QoS is used and the security settings in the configuration XML are ignored.

The following XML fragment shows how to set security settings through configuration:

 1<Domain id="any">
 2  <DDSSecurity>
 3    <Authentication>
 4      <Library initFunction="init_authentication" finalizeFunction="finalize_authentication" path="dds_security_auth"/>
 5      <IdentityCA>file:/path/to/example_id_ca_cert.pem</IdentityCA>
 6      <IdentityCertificate>file:/path/to/example_alice_cert.pem</IdentityCertificate>
 7      <PrivateKey>file:/path/to/example_alice_priv_key.pem</PrivateKey>
 8    </Authentication>
 9    <Cryptographic>
10      <Library initFunction="init_crypto" finalizeFunction="finalize_crypto" path="dds_security_crypto"/>
11    </Cryptographic>
12    <AccessControl>
13      <Library initFunction="init_access_control" finalizeFunction="finalize_access_control" path="dds_security_ac"/>
14      <PermissionsCA>file:/path/to/example_perm_ca_cert.pem</PermissionsCA>
15      <Governance>file:/path/to/example_governance.p7s</Governance>
16      <Permissions>file:/path/to/example_permissions.p7s</Permissions>
17    </AccessControl>
18  </DDSSecurity>
19</Domain>

To use this configuration file for an application, set the CYCLONEDDS_URI environment variable to this config file:

export CYCLONEDDS_URI=/path/to/secure_config.xml

Note

This example configuration uses the attribute id=any for the domain element, any participant that is created (which implicitly creates a domain) in an application using this configuration gets these security settings.