Skip to content

README.md

Latest commit

 

History

History
133 lines (97 loc) · 7.92 KB

README.md

File metadata and controls

133 lines (97 loc) · 7.92 KB

DDS Security Artifacts

This directory contains the DDS Security PKI infrastructure, governance, permissions, and identity artifacts for the reference architecture. Security artifacts are generated by setup_security.py using OpenSSL.

Prerequisites

Generating Security Artifacts

From the repository root, run:

python3 system_arch/security/setup_security.py

This generates all private keys, certificates, and signed XML files needed for secure DDS communication from the committed configuration files (.cnf, governance .xml, and permissions .xml).

The script auto-detects the installed Connext version from the Python environment's rti.connextdds package. Use --connext-version X.Y.Z to override.

To re-generate all artifacts (overwriting existing ones):

python3 system_arch/security/setup_security.py --force

Checking Certificate Status

To inspect certificate expiry across all generated artifacts:

python3 system_arch/security/setup_security.py --status

Certificates expiring within 30 days are flagged as warnings. Use --warn-days N to adjust the threshold.

CLI Reference

Flag Description
(no flags) Generate artifacts (skip existing)
--force Re-generate all artifacts, overwriting existing ones
--strict Promote warnings to fatal errors
--status Report certificate expiry status and exit
--warn-days N Days-to-expiry warning threshold for --status (default: 30)
--connext-version X.Y.Z Override auto-detected Connext version

Directory Layout

system_arch/security/
├── ca/                                          # Certificate Authorities
│   ├── TrustedRootCa/                           #   Self-signed root CA
│   ├── TrustedIdentityCa/                       #   Intermediate CA for identity certs
│   └── TrustedPermissionsCa/                    #   Intermediate CA for permissions signing
├── domain_scope/                                # Per-domain governance & permissions
│   ├── OperationalDomain/
│   │   ├── governance/<name>/<name>.xml         #     Governance XML (committed)
│   │   │                └── signed/<issuer>/     #     Signed governance (.p7s)
│   │   └── permissions/<role>/<role>.xml         #     Permissions XML (committed)
│   │                        └── signed/<issuer>/ #     Signed permissions (.p7s)
│   └── TeleopWanDomain/
│       ├── TeleopWanDomain.psk                  #     PSK passphrase seed (generated)
│       └── ...
├── identity/                                    # Per-participant identity certs
│   └── <module>/<app>/<participant>/
│       ├── <participant>.cnf                    #   OpenSSL config (committed)
│       ├── private/<participant>.key            #   Private key (generated)
│       └── certs/<issuer>/
│           ├── <participant>.crt                #   Identity certificate (generated)
│           └── <participant>.chain.pem          #   Cert chain: leaf + issuer CA
├── dds_security.py                              # Low-level OpenSSL primitives
├── security_tree.py                             # Tree config, scaffolding, orchestration
└── setup_security.py                            # Project-specific tree definition + CLI

Key Concepts

  • CA hierarchy: A self-signed root CA (TrustedRootCa) issues two intermediate CAs — one for identity certificates (TrustedIdentityCa) and one for permissions/governance signing (TrustedPermissionsCa).
  • Chain files: Identity certificates include a .chain.pem containing both the leaf cert and its issuing CA cert, as required by the RTI Security Plugins.
  • Signed XML: Governance and permissions XML files are S/MIME-signed by the appropriate intermediate CA. The signed .p7s files are what Connext loads at runtime.
  • Per-participant permissions: Each participant has its own permissions document specifying the exact topics it may publish/subscribe to, with a default DENY rule.
  • PSK passphrases: Pre-Shared Key seed files (.psk) are generated per domain scope and stored alongside the governance/permissions artifacts (e.g. domain_scope/TeleopWanDomain/TeleopWanDomain.psk). The file format is <id>:<seed> where <id> is an integer in [0, 254] for Connext 7.3.x. Participants load the passphrase via the dds.sec.crypto.rtps_psk_secret_passphrase property.

Good Practices for DDS Security

  1. One governance document per domain.
  2. One permissions document and identity certificate per DomainParticipant.
  3. Permissions documents specify exactly which topics can be published/subscribed to, with a default rule of DENY.
  4. Use separate CAs for identity certificates vs. permissions/governance signing.
  5. Use intermediate CAs rather than signing directly with the root CA.

Considerations for This Reference Architecture

The security artifacts in this reference architecture demonstrate how applications can integrate RTI Security Plugins. This is not comprehensive cybersecurity advice for a production system.

  1. The three-tier CA hierarchy (root → intermediate identity CA + intermediate permissions CA) follows best practices. In production, the root CA private key should be kept offline.
  2. Per-participant topic rules enforce least-privilege access. Each participant can only publish/subscribe to the specific topics it requires.
  3. In a deployed system, you will need to manage the lifecycle of these certificates using a PKI or other security tools.
  4. You should implement safeguards for certificate revocation based on your threat model, and implement other cybersecurity best practices like security information and event management (SIEM).

See the RTI Security Plugins User's Manual for more detail on Design Considerations and Best Practices.

Scaffolding (Maintainer-Only)

The committed .cnf, governance .xml, and permissions .xml files are generated from Jinja2 templates located in system_arch/security/templates/. If you modify the tree definition in setup_security.py (e.g. add a new participant or domain scope), re-scaffold to update the committed files:

python3 system_arch/security/setup_security.py --scaffold

Then re-generate the artifacts:

python3 system_arch/security/setup_security.py --force

Use --strict with either command to promote warnings (e.g. overwriting hand-edited files, version mismatches, stale scaffold hashes) to fatal errors.

Validation

The generation pipeline includes several built-in validations that run automatically:

  • Subject name matching: Verifies the identity certificate DN matches the committed permissions XML.
  • Certificate validity: Warns if any cert is expired or if a leaf cert outlives its issuing CA.
  • Permissions validity: Warns if permissions expire before or after the identity certificate.
  • Domain range checks: Verifies permissions domain_id falls within the governance domain range.
  • Key file permissions: Warns if private key files have overly permissive file modes.
  • Stale scaffold detection: Warns if the tree definition has changed since the last --scaffold run.

Pass --strict to promote any of these warnings to fatal errors.