Certificate Lifecycle Management with RTI Security Extensions

This example shows how to configure Security Extensions to banish and ignore participants that have been compromised, while keeping the system as a whole from shutting down. We will show how to remove participants from a live system after their certificate has expired or been revoked. And, how to go through the process of connecting or reconnecting elements after the problem has been resolved.

This Case + Code consists of the following elements:

• Configuration scripts for the generation of certificates and using those certificates to sign Security Extension configuration files.
• An example Shapes-publishing application that can banish participants with revoked or expired certificates
• Instructions for running the demo

This Case + Code shows how applications can banish and ignore participants who are no longer trusted and discusses the RTI Connext configuration decisions made when developing the example.

Download the Example

Make sure that you have the newest versions of RTI Connext with Security Extensions installed and configured. The example has been tested on Windows 10 64-bit and Ubuntu 20.04 64-bit, but should be able to run on any system that can use RTI Connext.

For Windows, you will need to have a bash shell installed, such as Git for Windows.

The example can be found on the RTI Community GitHub Repository. To run the example you need cmake and openssl installed.

Configuration

The first step in running the example is to run the configuration script. The configuration script uses openssl to do the following:

• Generate an Identity CA Certificate
• Generate a Permissions CA Certificate
• Generate Identity Certificates for all participants
• Sign the Governance file
• Sign all Permissions files

The script can be found at CertificateRevocation/demo/. Run SetupSecurityFiles.sh.

Build

The next step is to build the ShapePublisher application. Full instructions for building the example can be found in the RTI Community GitHub Repository.

Configuring Shapes Demo

For the demo you will need to configure two instances of the Shapes demo to act as ShapesDemoA and ShapesDemoB.

Open two instances of the ShapesDemo from the same directory as your ShapePublisher application. If your path variables are set up correctly you should just be able to run rtiShapesDemo.sh or rtiShapesDemo.bat

Once the demos are open, you will need to add the Quality of Service (QOS) file and select the appropriate profiles for both demo instances. You can do this by:

1. Go to Controls»Configuration…
2. Click Stop.
3. Deselect Enable Distributed Logger.
4. In the Choose the profile pull-down, choose
• pmiLibrary::ShapeDemoA
• pmiLibrary::ShapeDemoB
5. Then click Start.

Shape Demo A allows for Publish and Subscribe, while Shape Demo B can only Subscribe.

Run the Custom Publisher

Full instructions for running the custom publisher can be found in the RTI Community GitHub Repository.

There are 3 types of configuration files used in Security Extensions application. The QOS (Quality of Service) file, the Governance file and Permissions files. Here we will discuss QOS settings necessary for Security Extensions operation and specifically new settings necessary for lifecycle management. Discussion of Governance and Permissions files are found in the next section.

Domain Participant Configuration

Security configuration within the QOS file begins and ends with Domain Participant configuration. Security settings for topics datareaders and datawriters are handled in the configuration files detailed in the next section.

Below is an overview of the elements needed to configure an application using Security Extensions. The QOS file described below can be found within the GitHub repository for this example here.

Note that even though many of these configurations are pointing at files, this is not strictly necessary. It is possible to include the information as text within the configuration file itself. Instead of specifying a file, specify data like this:

"data:,-----BEGIN CERTIFICATE-----\nabcdef\n-----END CERTIFICATE-----"

Although this isn’t recommended for most applications, it is an option.

Basic Structure

Within applications using Security Extensions, it is best to use a nested structure, with a base profile that handles root configuration, and inherited profiles that handle endpoint-specific details. This helps to create a cohesive configuration for the system, reducing QOS mismatch and making things work correctly the first time.

For the root configuration, we have this:

<qos_profile name="pmiRootSecure" base_name="BuiltinQosLib::Generic.StrictReliable">
  <base_name>
    <element>BuiltinQosSnippetLib::Optimization.Discovery.Endpoint.Fast</element>
    <element>BuiltinQosSnippetLib::Feature.Security.Enable</element>
  </base_name>

Note that we are starting with the Generic.StrictReliable profile and adding two QOS snippets. We could have just as easily started with Best Effort, or some other base profile. The first QOS snippet, Optimization.Discovery.Endpoint.Fast, was chosen to help speed up discovery and is recommended for applications using Security Extensions. The second snippet handles some basic configuration of the Domain Participant to enable our default Security Extension libraries.

Root Domain Participant Configuration

key_revision_max_history_depth

<element>
  <name>dds.participant.trust_plugins.key_revision_max_history_depth</name>
    <value>7</value>
  </element>

This setting is what enables key revisions – the mechanism that Security Extensions use to banish participants from an active system. The value of 7 is somewhat arbitrary, with the important point being that it is not the value of 0. Note that setting this property to a non-zero value will make connecting to participants that do not have key revisions enabled impossible, breaking compatibility with applications running older versions of Connext.

More information on this property can be found in Section 6.3.3.2 of the RTI Security Plugins User’s Manual.

Identify CA and Permission CA

<element>
  <name>dds.sec.auth.identity_ca</name>
  <value>file:../../cert/pmi/ca/pmiIdentityCaCert.pem</value>
</element>
<element>
  <name>dds.sec.access.permissions_ca</name>
  <value>file:../../cert/pmi/ca/pmiPermissionsCaCert.pem</value>
</element>

This configures the location of the Public Certificates for certifying identity and permissions. Since these are different security considerations, configuration allows for different certificates for each, although many times the same certificate is used for both.

More information on these properties can be found in Section 3.2.1 of the RTI Security Plugins User’s Manual, including information on identity certificate chaining.

Governance

<element>
  <name>dds.sec.access.governance</name>
  <value>file:../security/signed/pmiSigned_pmiGovernance.p7s</value>
</element>

This configures the location of the governance file signed by the Permissions CA. Details about this file are found below.

Individual Participant Configuration

For individual participants, some settings should be unique for each participant.

Names

<datawriter_qos>
  <publication_name>
    <name>ShapesDemoAWriter</name>
  </publication_name>
</datawriter_qos>
<datareader_qos>
  <subscription_name>
    <name>ShapesDemoAReader</name>
  </subscription_name>
</datareader_qos>
<domain_participant_qos>
  <participant_name>
    <name>ShapesDemoAParticipant</name>
  </participant_name>

By giving each datawriter, datareader and participant a unique name, we can make debugging easier and help differentiate each participant. Each of these settings can also be specified in code, and is in many cases. It is done in the configuration here because these names should match up with names within the configured Permissions files.

Identity Certificate

<element>
  <name>dds.sec.auth.identity_certificate</name>
  <value>file:../../cert/pmi/identities/ShapeDemoA/pmiShapesDemoACert.pem</value>
</element>

This setting points to an identity certificate, which should be unique for each device, if not for each participant. It must be derived from the Identity CA (or an intermediate CA), specified above. During discovery this certificate is sent over the wire in order to prove identity to other participants.

More information about this property can be found in Section 3.2.1  of the RTI Security Plugins User’s Manual, including information on identity certificate chaining.

Private Key

<element>
 <name>dds.sec.auth.private_key</name>
 <value>file:../../cert/pmi/identities/ShapeDemoA/private/pmiShapesDemoAKey.pem</value>
</element>

The private identity key is used by Connext for PKI communication. This should be the private key to the identity certificate configured above. It is this reason that identity certificates should be device- and/or participant-exclusive. Using common identity certificates across your system allows potentially compromised endpoints to pretend to be a different participant. It also makes certificate lifecycle management more difficult.

For options and different ways this property can be configured, refer toTable 4.1 of the RTI Security Plugins User’s Manual.

Permissions

<element>
  <name>dds.sec.access.permissions</name>
  <value>file:../security/signed/signed_ShapesDemoA.p7s</value>
</element>

Signed permissions files, in addition to signed identity files, are sent over the wire during discovery to allow for proper connections between participants. This file must be signed by the Permissions CA, just like the governance file. Detailed information about this file can be found below.

Configuring a Security Extensions application begins with the QOS file detailed above. But is continued with the correct configuration of the Governance and Permissions files. These define security configuration for the system as a whole,  where each participant fits into the system, respectively.

This is the basic structure of the security elements within each participant and the system as a whole.

Governance File

The governance file used in this application can be found on GitHub here. For detailed information on all of the configuration of a governance file in Connext see Section 3.3  of the RTI Security Plugins User’s Manual. It is highly recommended that you read this section of the User’s Manual before configuring your system.

For this example we are using the settings described in detail in the user manual.

The governance file is signed by the Permissions CA.

Permissions File

The permissions files used in this application can be found on GitHub here. For detailed information on all of the configuration of a governance file in Connext see Section 3.4  of the RTI Security Plugins User’s Manual. Please read this section of the User’s Manual before continuing.

<default>DENY</default>

You should note that each of the permissions files uses this rule. This tag means that any action not explicitly allowed is prohibited, making this a white list based system, which although safer, is much more restrictive (which is what makes it safer). Depending on your system, you may configure your permissions with Allow Rules, Deny Rules, or a mixture of both. Please be aware of the security considerations for these decisions.

Each Permissions File is signed by the Permissions CA. 

ShapeDemoA

<publish>
  <topics>
    <topic>Triangle</topic>
    <topic>Circle</topic>
    <topic>Square</topic>
  </topics>
</publish>
<subscribe>
  <topics>
    <topic>Triangle</topic>
    <topic>Circle</topic>
    <topic>Square</topic>
  </topics>
</subscribe>

Note that Shape Demo A is configured to publish and subscribe to all topics. Also note that we are explicit in defining what is meant by all topics. If an additional shape and topic (such as Hexagon) was added to the system, this application would not be able to publish or subscribe to it.

ShapeDemoB

<subscribe>
  <topics>
    <topic>Triangle</topic>
    <topic>Circle</topic>
    <topic>Square</topic>
  </topics>
</subscribe>

Although similar to Shape Demo A, this application will only be able to subscribe to the shapes topics. Publishing to these topics by this application will be ignored by other participants.

ShapePublisher

<publish>
  <topics>
    <topic>Triangle</topic>
  </topics>
</publish>

Each Shape Publisher is restricted to publishing a single topic. This is about as restrictive as you can get within a Permissions configuration.

A great deal more information is available in the RTI Security Plugins User’s Manual. This resource goes into detail on all of the configuration elements described in this use case. It is highly recommended that you become familiar with the manual and use it when designing and configuring your system and applications.

Join the Community

Post questions on the RTI Community Forum.

Contribute to our Case + Code examples on RTI Community GitHub using these instructions.

Explore More with Connext

Check out more of the RTI Connext product suite and learn how Connext products can help you build your distributed systems. If you haven't already, download the free trial.