NOTE: This document has been obsoleted by the Adopted DDS Specification
OMG DDS Security Draft Specification. This is the 4th Revised Submission to the DDS Security Specification.
Also accessible from the OMG at:
http://www.omg.org/members/cgi-bin/doc?mars/13-02-15.pdf
4. GENERAL USE RESTRICTIONS
Any unauthorized use of this specification may violate copyright laws, trademark laws, and
communications regulations and statutes. This document contains information, which is
protected by copyright. All Rights Reserved. No part of this work covered by copyright herein
may be reproduced or used in any form or by any means--graphic, electronic, or mechanical,
including photocopying, recording, taping, or information storage and retrieval systems--without
permission of the copyright owner.
DISCLAIMER OF WARRANTY
WHILE THIS PUBLICATION IS BELIEVED TO BE ACCURATE, IT IS PROVIDED "AS
IS" AND MAY CONTAIN ERRORS OR MISPRINTS. THE OBJECT MANAGEMENT
GROUP AND THE COMPANIES LISTED ABOVE MAKE NO WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS PUBLICATION, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY OF TITLE OR OWNERSHIP, IMPLIED
WARRANTY OF MERCHANTABILITY OR WARRANTY OF FITNESS FOR A
PARTICULAR PURPOSE OR USE. IN NO EVENT SHALL THE OBJECT MANAGEMENT
GROUP OR ANY OF THE COMPANIES LISTED ABOVE BE LIABLE FOR ERRORS
CONTAINED HEREIN OR FOR DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
CONSEQUENTIAL, RELIANCE OR COVER DAMAGES, INCLUDING LOSS OF
PROFITS, REVENUE, DATA OR USE, INCURRED BY ANY USER OR ANY THIRD
PARTY IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS
MATERIAL, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
The entire risk as to the quality and performance of software developed using this specification is
borne by you. This disclaimer of warranty constitutes an essential part of the license granted to
you to use this specification.
RESTRICTED RIGHTS LEGEND
Use, duplication or disclosure by the U.S. Government is subject to the restrictions set forth in
subparagraph (c) (1) (ii) of The Rights in Technical Data and Computer Software Clause at
DFARS 252.227-7013 or in subparagraph (c)(1) and (2) of the Commercial Computer Software -
Restricted Rights clauses at 48 C.F.R. 52.227-19 or as specified in 48 C.F.R. 227-7202-2 of the
DoD F.A.R. Supplement and its successors, or as specified in 48 C.F.R. 12.212 of the Federal
Acquisition Regulations and its successors, as applicable. The specification copyright owners are
as indicated above and may be contacted through the Object Management Group, 140 Kendrick
Street, Needham, MA 02494, U.S.A.
TRADEMARKS
MDA®, Model Driven Architecture®, UML®, UML Cube logo®, OMG Logo®, CORBA® and
XMI® are registered trademarks of the Object Management Group, Inc., and Object
5. Management Group™, OMG™ , Unified Modeling Language™, Model Driven Architecture
Logo™, Model Driven Architecture Diagram™, CORBA logos™, XMI Logo™, CWM™,
CWM Logo™, IIOP™ , MOF™ , OMG Interface Definition Language (IDL)™ , and OMG
SysML™ are trademarks of the Object Management Group. All other products or company
names mentioned are used for identification purposes only, and may be trademarks of their
respective owners.
COMPLIANCE
The copyright holders listed above acknowledge that the Object Management Group (acting
itself or through its designees) is and shall at all times be the sole entity that may authorize
developers, suppliers and sellers of computer software to use certification marks, trademarks or
other special designations to indicate compliance with these materials.
Software developed under the terms of this license may claim compliance or conformance with
this specification if and only if the software compliance is of a nature fully matching the
applicable compliance points as stated in the specification. Software developed only partially
matching the applicable compliance points may claim only that the software was based on this
specification, but may not claim compliance or conformance with this specification. In the event
that testing suites are implemented or approved by Object Management Group, Inc., software
developed using this specification may claim compliance or conformance with the specification
only if the software satisfactorily completes the testing suites.
6. OMG’s Issue Reporting Procedure
All OMG specifications are subject to continuous review and improvement. As part of this proc-
ess we encourage readers to report any ambiguities, inconsistencies, or inaccuracies they may
find by completing the Issue Reporting Form listed on the main web page http://www.omg.org,
under Documents, Report a Bug/Issue (http://www.omg.org/technology/agreement.)
7. Table of Contents
1
Response
Details .....................................................................................................................1
1.1
OMG
RFP
Response ....................................................................................................................... 1
1.2
Copyright
Waiver........................................................................................................................... 1
1.3
Contacts ........................................................................................................................................ 1
1.4
Problem
Statement ....................................................................................................................... 1
1.5
Overview
of
this
Specification ....................................................................................................... 2
1.6
Design
Rationale............................................................................................................................ 4
1.7
Statement
of
Proof
of
Concept ...................................................................................................... 4
1.8
Resolution
of
RFP
Requirements
and
Requests.............................................................................. 4
1.9
Responses
to
RFP
Issues
to
be
discussed........................................................................................ 4
2
Scope ......................................................................................................................................6
3
Conformance...........................................................................................................................6
3.1
Changes
to
Adopted
OMG
Specifications ....................................................................................... 6
3.2
Compliance
Levels ......................................................................................................................... 6
4
Normative
References .............................................................................................................7
5
Terms
and
Definitions .............................................................................................................7
6
Symbols...................................................................................................................................7
7
DDS
Security............................................................................................................................8
7.1
Security
Model .............................................................................................................................. 8
7.1.1
Threats ...........................................................................................................................................9
7.2
Securing
DDS
Messages ............................................................................................................... 12
7.2.1
RTPS
Background
(Non-‐Normative) .............................................................................................12
7.2.2
Secure
RTPS
Messages .................................................................................................................14
7.2.3
Platform
Independent
Description...............................................................................................15
7.2.4
Mapping
to
UDP/IP
PSM ..............................................................................................................17
8
Plug-‐in
Architecture............................................................................................................... 18
8.1
Security
Exception ....................................................................................................................... 20
DDS Security, Revised Submission i
8. 8.1.1
Operation:
init..........................................................................................................................21
8.1.2
Operation:
get_message .........................................................................................................21
8.1.3
Operation:
get_code ................................................................................................................21
8.1.4
Operation:
get_minor_code ..................................................................................................21
8.2
Property ...................................................................................................................................... 21
8.3
Credential.................................................................................................................................... 22
8.3.1
Attribute:
credential_classid ..........................................................................................23
8.3.2
Attribute:
properties .............................................................................................................23
8.3.3
Attribute:
value .........................................................................................................................23
8.4
Token .......................................................................................................................................... 23
8.4.1
Attribute:
token_classid ......................................................................................................24
8.4.2
Attribute:
wrapper_classid .................................................................................................24
8.4.3
Attribute:
properties .............................................................................................................24
8.4.4
Attribute:
value .........................................................................................................................25
8.4.5
Attribute:
wrapped_value ......................................................................................................25
8.5
DDS
support
for
plugin
message
exchange .................................................................................. 25
8.5.1
ParticipantMessageData
kinds
reserved
by
this
specification .....................................................26
8.5.2
Format
of
data
within
ParticipantMessageData ..........................................................................26
8.6
Authentication
Plug-‐in................................................................................................................. 27
8.6.1
Background
(Non-‐Normative) ......................................................................................................27
8.6.2
Authentication
Plug-‐in
Model ......................................................................................................28
8.7
Access
Control
Plug-‐In ................................................................................................................. 40
8.7.1
Background
(Non-‐Normative) ......................................................................................................40
8.7.2
Access
Control
Plug-‐in
Model.......................................................................................................41
8.8
Cryptographic
Plug-‐in .................................................................................................................. 56
8.8.1
Cryptographic
Plug-‐in
Model........................................................................................................56
8.8.2
Attribute:
transformation_kind_id.................................................................................58
8.8.3
Attribute:
transformation_key_id ...................................................................................58
8.9
The
Logging
Plugin....................................................................................................................... 86
8.9.1
Background
(Non-‐Normative) ......................................................................................................86
ii DDS Security, Revised Submission
9. 8.9.2
Logging
Plug-‐in
Model ..................................................................................................................86
8.10
Data
Tagging.............................................................................................................................. 89
8.10.1
Background
(Non-‐Normative) ....................................................................................................89
8.10.2
Approach ....................................................................................................................................89
8.10.3
DataTagging
Model ....................................................................................................................89
8.11
Security
Plug-‐ins’
Behavior ........................................................................................................ 91
8.11.1
Authentication
and
AccessControl
behavior
with
local
DomainParticipant ..............................91
8.11.2
Authentication
behavior
with
remote
DomainParticipant.........................................................92
8.11.3
AccessControl
behavior
with
local
domain
entity
creation........................................................95
8.11.4
AccessControl
behavior
with
remote
entity
discovery ..............................................................96
8.11.5
Security
Plugins
behavior
for
key
propagation...........................................................................98
8.11.6
Security
Plugins
behavior
for
encoding/decoding....................................................................102
9
Builtin
Plugins ..................................................................................................................... 111
9.1
Requirements
and
priorities ...................................................................................................... 111
9.1.1
Performance
and
Scalability.......................................................................................................112
9.1.2
Robustness
and
Availability........................................................................................................113
9.1.3
Fitness
to
the
DDS
Data-‐Centric
Model......................................................................................113
9.1.4
Leverage
and
reuse
of
existing
security
infrastructure
and
technologies..................................114
9.1.5
Ease
of
use
while
supporting
common
application
requirements .............................................114
9.2
Builtin
Authentication:
DDS:Auth:PKI-‐RSA/DSA-‐DH ................................................................... 114
9.2.1
Configuration..............................................................................................................................115
9.2.2
DDS:Auth:PKI-‐RSA/DSA-‐DH
Types ..............................................................................................115
9.2.3
Behavior
of
the
DDS:Auth:PKI-‐RSA/DSA-‐DH
plugin....................................................................118
9.2.4
Wire
protocol
implemented
by
the
DDS:Auth:PKI-‐RSA/DSA-‐DH
plugin.....................................125
9.3
Builtin
Access
Control
Plugin:
DDS:Access:PKI-‐Signed-‐XML-‐Permissions .................................... 127
9.3.1
Configuration..............................................................................................................................127
9.3.2
DDS:Access:PKI-‐Signed-‐XML-‐Permissions
Types ........................................................................131
9.3.3
Behavior
of
the
builtin
Access
Control
Plugin ............................................................................132
9.4
Builtin
Cryptographic
Plugin ...................................................................................................... 135
9.4.1
Configuration..............................................................................................................................136
DDS Security, Revised Submission iii
10. 9.4.2
DDS:Crypto:AES-‐CTR-‐HMAC-‐RSA/DSA-‐DH
Types .......................................................................136
9.4.3
Behavior
of
the
DDS:Crypto:AES-‐CTR-‐HMAC-‐RSA/DSA-‐DH
Plugin .............................................140
9.5
Builtin
Logging
Plugin ................................................................................................................ 151
References ................................................................................................................................ 151
iv DDS Security, Revised Submission
11. Preface
OMG
Founded in 1989, the Object Management Group, Inc. (OMG) is an open membership, not-for-profit
computer industry standards consortium that produces and maintains computer industry specifica-
tions for interoperable, portable, and reusable enterprise applications in distributed, heterogeneous
environments. Membership includes Information Technology vendors, end users, government agen-
cies, and academia.
OMG member companies write, adopt, and maintain its specifications following a mature, open
process. OMG’s specifications implement the Model Driven Architecture® (MDA®), maximizing
ROI through a full-lifecycle approach to enterprise integration that covers multiple operating sys-
tems, programming languages, middleware and networking infrastructures, and software develop-
ment environments. OMG’s specifications include: UML® (Unified Modeling Language™);
CORBA® (Common Object Request Broker Architecture); CWM™ (Common Warehouse Meta-
model); and industry-specific standards for dozens of vertical markets.
More information on the OMG is available at http://www.omg.org/.
OMG Specifications
As noted, OMG specifications address middleware, modeling and vertical domain frameworks. A
Specifications Catalog is available from the OMG website at:
http://www.omg.org/technology/documents/spec_catalog.htm
Specifications within the Catalog are organized by the following categories:
OMG Modeling Specifications
• UML
• MOF
• XMI
• CWM
• Profile specifications
OMG Middleware Specifications
• CORBA/IIOP
• Data-Distribution Service (DDS) Specifications
• IDL/Language Mappings
DDS Security, Revised Submission v
12. • Specialized CORBA specifications
• CORBA Component Model (CCM)
Platform Specific Model and Interface Specifications
• CORBAservices
• CORBAfacilities
• OMG Domain specifications
• OMG Embedded Intelligence specifications
• OMG Security specifications
All of OMG’s formal specifications may be downloaded without charge from our website. (Products
implementing OMG specifications are available from individual suppliers.) Copies of specifications,
available in PostScript and PDF format, may be obtained from the Specifications Catalog cited above
or by contacting the Object Management Group, Inc. at:
OMG Headquarters
140 Kendrick Street
Building A, Suite 300
Needham, MA 02494
USA
Tel: +1-781-444-0404
Fax: +1-781-444-0320
Email: pubs@omg.org
Certain OMG specifications are also available as ISO standards. Please consult http://www.iso.org.
Typographical Conventions
The type styles shown below are used in this document to distinguish programming statements from
ordinary English. However, these conventions are not used in tables or section headings where no
distinction is necessary.
Times/Times New Roman - 10 pt.: Standard body text
Helvetica/Arial - 10 pt. Bold: OMG Interface Definition Language (OMG IDL) and syntax
elements.
Courier - 10 pt. Bold: Programming language elements.
Helvetica/Arial - 10 pt: Exceptions
NOTE: Terms that appear in italics are defined in the glossary. Italic text also represents the name
of a document, specification, or other publication.
vi DDS Security, Revised Submission
13. PART I - Introduction
1 Response Details
1.1 OMG RFP Response
This specification is submitted in response to the DDS Security RFP issued in December 2010 with
OMG document number mars/ /2010-12-37.
1.2 Copyright Waiver
“Each of the entities listed above: (i) grants to the Object Management Group, Inc. (OMG) a nonex-
clusive, royalty-free, paid up, worldwide license to copy and distribute this document and to modify
this document and distribute copies of the modified version, and (ii) grants to each member of the
OMG a nonexclusive, royalty-free, paid up, worldwide license to make up to fifty (50) copies of this
document for internal review purposes only and not for distribution, and (iii) has agreed that no per-
son shall be deemed to have infringed the copyright in the included material of any such copyright
holder by reason of having used any OMG specification that may be based hereon or having con-
formed any computer software to such specification.”
1.3 Contacts
• Real-Time Innovations – Gerardo Pardo-Castellote, Ph.D. gerardo.pardo@rti.com
• eProsima – Jaime Martin-Losa Jaime.martin@eprosima.com
• PrimsTech – Angelo Corsaro, Ph.D. Angelo.Corsaro@prismtech.com
1.4 Problem Statement
Current DDS Systems meet Information Assurance requirements by isolating DDS applications into
a security enclave running at "system high". Inside the "protected domain" applications are author-
ized to publish and subscribe to any data in the DDS Global Data Space. Once inside the protected
domain applications are not authenticated; unless done at the application layer data and meta-data is
sent unencrypted and it is not protected against tampering, data is often sent using multicast. Stated
differently, the standard OMG DDS infrastructure provides no guarantees (other than those provided
by the physical protection of the system) on confidentiality, pedigree, or integrity of the information.
What is needed is a set of Information Assurance extensions to the DDS standard that provide the
necessary support for Authentication, Authorization and Access Control, Confidentiality, Integrity,
and Non-repudiation for all the data sent over DDS. Moreover, a Security Auditing capability is also
necessary to evaluate the state of the global data space.
One possible approach would be to enforce Mandatory Access Control (MAC) on all applications
that join a DDS Global Data-Space, requiring them to be authenticated and have the necessary cre-
DDS Security, Revised Submission 1
14. dentials. Beyond access to the DDS Global Data Space, the approach should provide finer-grain (e.g.
role-based or more generally, policy-based) access control to specific DDS Topics and perhaps even
to specific fields within DDS Topics. It should ensure confidentiality of the information, integrity,
pedigree, and non-repudiation. Finally, it should be able to handle the scalable publish-subscribe de-
ployment scenarios, specifically the one-to-many (multicast) distribution of encrypted information
and maintain the DDS real-time QoS in the distribution of information to multiple subscribers.
The required Security Architecture needs to be configurable (e.g. via newly added QoS polices) to
provide simple access to standard, interoperable, pre-defined security policies out-of-the box. At the
same time, the architecture should remain open and extensible (e.g. via “plug-in” SPIs) so that appli-
cation developers can integrate with pre-existing Identity Management Mechanisms, Authorization
Policy repositories, or cryptographic libraries, which might be program or project specific.
1.5 Overview of this Specification
This specification defines the Security Model and Service Plugin Interface (SPI) architecture for
compliant DDS implementations. The DDS Security Model is enforced by the invocation of these
SPIs by the DDS implementation. This specification also defines a set of built-in implementations of
these SPIs.
• The specified built-in SPI implementations enable both out-of-the box security and interoper-
ability between compliant DDS applications.
• The use of SPIs allows DDS users to customize the behavior and technologies that the DDS
implementations use for Information Assurance, specifically allowing customization of
Authentication, Access Control, Encryption, Message Authentication, Digital Signing, Log-
ging and Data Tagging.
2 DDS Security, Revised Submission
15. This specification defines five SPIs; combined they provide Information Assurance to DDS systems:
• Authentication Service Plug-in. Provides the means to verify the identity of the application
and/or user that invokes operations on DDS. Includes facilities to perform mutual authentica-
tion between participants and establish a shared secret.
• AccessControl Service Plug-in. Provides the means to enforce policy decisions on what DDS
related operations an authenticated user can perform. For example which domains it can join,
which Topics it can publish or subscribe, etc.
• Cryptographic Service Plug-in. Implements (or interfaces with libraries that implement) all
cryptographic operations, including encryption, decryption, hashing, digital signatures, etc.
Includes the means for key derivation from a shared secret.
• Logging Service Plug-in. Supports auditing of all DDS security-relevant events
• Data Tagging Service Plug-in. Provides a way to add tags to data samples.
DDS Security, Revised Submission 3
16. 1.6 Design Rationale
1.7 Statement of Proof of Concept
1.8 Resolution of RFP Requirements and Requests
The specification resolves the following mandatory requirements:
Table 1. Mandatory RFP Requirements
Requirement Description Reference Remarks
6.5.1
6.5.1
6.5.3
6.5.4
6.5.5
The proposed specification addresses the following optional requirements:
Table 2. Optional RFP Requirements
Requirement Description Reference Remarks
6.6.1
6.6.2
6.6.3
6.6.4
6.6.5
6.6.6
6.6.7
6.6.8
1.9 Responses to RFP Issues to be discussed
The specification discusses the following issues:
4 DDS Security, Revised Submission
18. PART II – PIM and Language PSMs
for DDS Security
2 Scope
This submission adds an additional “DDS Security Support” compliance point (“profile”) to the DDS
Specification with the following scope:
• Authentication Plug-in
• Access Control Plug-in
• Data Tagging API
• Cryptography Plug-in
• Key Management Plug-in
• Logging Plug-in
3 Conformance
3.1 Changes to Adopted OMG Specifications
This specification does not modify any existing adopted OMG specifications. It adds functionality on
top of the current OMG specifications.
• DDS: This specification does not modify or invalidate any existing DDS profiles or compli-
ance levels.
• RTPS: This specification depends on the definitions of CDR “parameter list” data structures
specified by RTPS. It does not require any modifications to RTPS, however it impacts
interoperability with existing DDS/RTPS implementations. In particular, DDS/RTPS imple-
mentations that do not implement this specification will not interoperate with implementa-
tions that do implement the mechanisms introduced by this proposal. The interoperability is
still achieved if the security mechanisms are disabled.
• IDL: This specification does not modify any existing IDL-related compliance levels.
3.2 Compliance Levels
There is a single compliance level to this specification. This compliance level shall be considered a
“DDS Security” Profile of the DDS Specification.
6 DDS Security, Revised Submission
19. 4 Normative References
RFC 2014
5 Terms and Definitions
For the purposes of this specification, the following terms and definitions apply.
Data-Centric Publish-Subscribe (DCPS)
The mandatory portion of the DDS specification used to provide the functionality required for an ap-
plication to publish and subscribe to the values of data objects.
Data Distribution Service (DDS)
An OMG distributed data communications specification that allows Quality of Service policies to be
specified for data timeliness and reliability. It is independent of implementation languages.
Information Assurance
The practice of managing risks related to the use, processing, storage, and transmission of informa-
tion or data and the systems and processes used for those purposes.
Authentication
Security measure designed to establish the identity of a transmission, message, or originator.
Access Control
Mechanism that enables an authority to control access to areas and resources in a given physical fa-
cility or computer-based information system.
Confidentiality
Assurance that information is not disclosed to unauthorized individuals, processes, or devices.
Integrity
Protection against unauthorized modification or destruction of information.
Non-Repudiation
Assurance the sender of data is provided with proof of delivery and the recipient is provided with
proof of the sender's identity, so neither can later deny having processed the data.
6 Symbols
PKI
HMAC
DDS Security, Revised Submission 7
20. This specification does not define any symbols or abbreviations.
7 DDS Security
7.1 Security Model
The Security Model for DDS must define the security principals (users of the system), the objects
that are being secured, and the operations on the objects that are to be restricted. DDS applications
share information on DDS Global Data Spaces (called DDS Domains) where the information is or-
ganized into Topics and accessed by means of read and write operations on data-instances of those
Topics.
Ultimately what is being secured is a specific DDS Global Data Space (domain) and within the do-
main the ability to access (read or write) information (specific Topic or even Topic-Instances) in the
DDS Global Data Space.
Securing DDS means providing
• Confidentiality of the data samples
• Integrity of data samples and the messages that contain them
• Authentication of DDS writers and readers
• Authorization of DDS writers and readers
• Non-repudiation of data
To provide secure access to the DDS Global Data Space applications that use DDS must first be
authenticated, such that the identity of the application (and potentially the user that interacts with it)
can be established. Once authentication has been obtained, the next step is to enforce access control
decisions that determine whether the application is allowed to perform specific actions. Examples of
actions are: joining a DDS Domain, defining a new Topic, reading, or writing a specific DDS Topic,
and even reading or writing specific Topic instances (as identified by the value of the key fields in
the data). Enforcement of the access control shall be supported by cryptographic techniques such that
information confidentiality and integrity can be maintained, which in turn requires an infrastructure
to manage and distribute the necessary cryptographic keys.
8 DDS Security, Revised Submission
21. 7.1.1 Threats
In order to understand the decisions made in the design of the plugins it is important to understand
some of the specific threats impacting applications that use DDS and DDS Interoperability Protocol
(RTPS).
Most relevant are four categories of threats:
1. Unauthorized subscription
2. Unauthorized publication
3. Tampering and replay
4. Unauthorized access to data
These threats are described in the context of a hypothetical communication scenario with 6 actors all
attached to the same network:
• Alice. A DDS DomainParticipant that is authorized to publish data on a Topic T.
• Bob. A DDS DomainParticipant that is authorized to subscribe to data on a Topic T.
• Eve. An eavesdropper. Someone that is not authorized to subscribe to data on Topic T.
However Eve uses the fact that it is connected to the same network to try to see the data.
• Trudy. An intruder. A DomainParticipant that is not authorized to publish on Topic T.
However Trudy uses the fact that it is connected to the same network to try to send data.
• Mallory. A Malicious DDS DomainParticipant. Mallory is authorized to subscribe to data on
topic T but it is not authorized to publish on Topic T. However Mallory will try to use in-
formation gained by subscribing to the data to publish in the network and try to convince Bob
that she is a legitimate publisher.
• Trent. A Trusted service that needs to receive information on Topic T and also send it. For
example, Trent can be a persistence service or a relay service. It is trusted to relay informa-
tion without having malicious intent. However it is not trusted to see the content of the in-
formation.
DDS Security, Revised Submission 9
22. 7.1.1.1 Unauthorized Subscription
The DomainParticipant Eve is connected to the same network infrastructure and is able to observe
the network packets despite the fact that the messages are not intended to be sent to Eve. Many sce-
narios can lead to this situation. Eve could tap into a network switch or observe the communication
channels. Or in situations where Alice and Bob are communicating over multicast Eve could simply
subscribe to the same multicast address.
Protecting against Eve is reasonably simple. All that is required is for Alice to encrypt the data it
writes using a secret key that is only shared with authorized receivers such as Bob, Trent, and Mal-
lory.
7.1.1.2 Unauthorized Publication
The DomainParticipant Trudy is connected to the same network infrastructure and is able to inject
network packets with any data contents, headers and destination it wishes (e.g Alice). The network
infrastructure will route those packets to the indicated destination.
In order to protect against Trudy, Bob, Trent and Mallory need to realize that the data is not originat-
ing with Alice. They need to realize that the data is coming from someone not authorized to send
data on topic T and therefore reject (i.e. not process) the packet.
Protecting against Trudy is also reasonably simple. All that is required is for the protocol to require
that the messages include either a hash-based message authentication code (HMAC) or digital signa-
ture.
• An HMAC creates a message authentication code using a secret key that is shared with the
intended recipients. Alice would only share the secret key with Bob, Mallory and Trent so
that they recognize messages that originate in Alice. Since Trudy is not authorized to publish
Topic T, Bob and the others will not recognize any HMACs that Trudy produces (i.e. they
will not recognize Trudy’s key).
10 DDS Security, Revised Submission
23. • A Digital Signature is based on public key cryptography. To create a Digital Signature Alice
encrypts a digest of the message using Alice’s private key. Everybody (including Bob, Mal-
lory and Trent) have access to Alice’s public key. Similar to the HMAC above, the recipients
can identify the messages from Alice, as they are the only ones whose digital signature can be
interpreted with Alice’s public key. Any digital signatures that Trudy may use will be re-
jected by the recipients as Trudy was not authorized to write topic T.
The use of HMAC versus Digital Signatures represents tradeoffs that will be discussed further in
subsequent sections. Suffice it to say that in many situations the use of HMAC is preferred as the
performance to compute and verify them is about 1000 faster than the performance of comput-
ing/verifying digital signatures.
7.1.1.3 Tampering and Replay
Mallory is authorized to subscribe to Topic T, Therefore Alice has shared with Mallory the secret
key to encrypt the topic and also, in the case HMAC is used, the secret key used for HMAC.
Assume Alice used HMAC instead of digital signatures. Then Mallory can use the knowledge it has
of the secret keys used for data-encryption and HMAC to create a message on the network and pre-
tend it came from Alice. Mallory can fake all the TCP/UDP/IP headers and also place any necessary
RTPS identifiers (e.g. Alice’s RTPS DomainParticipant and DataWriter GUIDs). Mallory has the
secret key that was used to encrypt the data so it can create encrypted data payloads with any con-
tents it wants. It has the secret key used to compute HMAC so it can also create a valid HMAC for
the new message. Bob and the others will have no way to see that message came from Mallory and
will accept it thinking it came from Alice.
So if Alice used HMAC the only solution to the problem is that the secret key used for HMAC when
sending the message to Mallory cannot be the same it uses when sending messages to Bob. In other
words Alice must share a different secret key for HMAC with each recipient. That way Mallory will
not have the HMAC key that Bob expects from Alice and the messages from Mallory to Bob will not
be misinterpreted as coming from Alice.
Recall that Alice needs to be able to use multicast to communicate efficiently with multiple receiv-
ers, Therefore if Alice wants to send an HMAC with a different key for every receiver, the only solu-
tion is to append multiple HMACs to the multicast message with some key-id that allows the recipi-
ent to select the correct HMAC to verify.
If Alice used digital signatures to protect the integrity of the message, then this ‘masquerading’ prob-
lem does not arise and Alice is able to send the same digital signature to all recipients. This makes
the use of multicast simpler. However the performance penalty of using digital signatures is so high
that in many situations it will be better to compute and send multiple HMACs as described earlier.
7.1.1.4 Unauthorized access to data by infrastructure services
Infrastructure services, such as the DDS Persistence Service or relay services need to be able to re-
ceive messages, verify their integrity, store them, and send them to other participants on behalf of the
original application.
DDS Security, Revised Submission 11
24. These services can be trusted to not be malicious, however often it is not desirable to grant them the
privileges they would need to understand the contents of the data. They are allowed to store and for-
ward the data, but not to see inside the data.
Trent is an example of such service. To support deployment of these types of services it is necessary
that the security model supports the concept of having a participant, such as Trent, that is allowed to
receive, process, and relay RTPS messages, but is not allowed to see the contents of the data within
the message. In other words it can see the headers and sample information (writer GUID, sequence
numbers, keyhash and such) but not the message contents.
In order to support services like Trent, Alice needs to accept Trent as a valid destination to its mes-
sages on topic T and share with Trent only the secret key used to compute the HMAC for Trent, but
not the secret key used to encrypt the data itself. In addition Bob, Mallory and others need to accept
Trent as someone that is able to write on topic T, and moreover relay messages from Alice. This
means two things, (1) accept and interpret messages encrypted with Alice’s secret key and (2) allow
Trent to include in its sample information the information it got from Alice (writer GUID, sequence
number and anything else needed to properly process the relayed message).
Assume Alice used HMAC in the message sent to Trent. Trent will have received from Alice the se-
cret key needed to properly verify the HMAC. Trent will be able to store the messages, but lacking
the secret key used for encryption it will be unable to see the data. When it relays the message to
Bob, it will include the information that indicates the message originated in Alice and produce an
HMAC with its own secret HMAC key that it shared with Bob. Bob will receive the message, verify
the HMAC and then see it is a relayed message from Alice. Bob recognizes Trent is authorized to
relay messages so it will accept the sample information that relates to Alice and process the message
as if it had originated with Alice. In particular it will use Alice’s secret key to decrypt the data.
If Alice had used digital signatures then Trent has two choices. If the digital signature covers only
the data and the sample information it needs to relay from Alice it could then just relay the digital
signature as well. Otherwise it can strip that and put its own HMAC. Similar to before, Bob recog-
nizes that Trent is allowed to relay messages from Alice and will be able to properly verify and proc-
ess the message.
7.2 Securing DDS Messages
OMG DDS uses the Real-Time Publish-Subscribe (RTPS) on-the-wire protocol (also an OMG stan-
dard) for communicating data. The RTPS protocol includes specifications of how discovery is per-
formed, the meta-data sent during discovery, and all the protocol messages and handshakes required
ensuring reliability. RTPS also specifies how messages are put together.
7.2.1 RTPS Background (Non-Normative)
In a secure system where efficiency and message latency is also a consideration, it is necessary to
define exactly what needs to be secured. Some applications may require only the data payload to be
confidential and it is acceptable for the discovery information as well as the reliability meta-traffic
(HEARTBEATs, ACKs, NACKs, etc.) to be visible as long as it is protected from modification.
Other applications may want to keep the meta-data (sequence numbers, in-line QoS) and/or the reli-
ability traffic (ACKs, NACKs, HEARTBEATs) also confidential. In some cases the discovery in-
formation (who is publishing what and the QoS) may need to be kept confidential as well.
12 DDS Security, Revised Submission
25. To help clarify these requirements, this section explains the structure of the RTPS Message and the
different Submessages it may contain.
An RTPS Message is composed of a leading RTPS Header followed by a variable number of RTPS
Submessages. Each RTPS Submessage itself composed of a Sub-message Header fol-
lowed by a variable number of SubmessagElements. There are various kinds of
SubmessageElements to communicate thngs like sequence numbers, unique identifiers for
DataReaders and DataWriters, SerializedKeys or KeyHash of the application data, source time-
stamps, QoS, etc. There is one kind of SubmessageElement called SerializedData that is
used to carry the data sent by DDS Applications.
For the purpses of securing comminications we may distinguish three types of RTPS
Submessages:
1. DataWriter Submesages. These are the RTPS submessages sent by a DataWriter to one or
more DataReaders. These include the Data, DataFrag, Gap, Heartbeat, and
HeartbeatFrag submessages.
2. DataReader Submesages. These are the RTPS submessages sent by a DataReader to one or
more DataWriters. These include the AckNack and the NackFrag submessages
3. Interpreter Submesages. These are the RTPS submessages that are destined to the Message
Interpereter and affect the interpretation of subsequents submessages. These include all the
“Info” messages.
DDS Security, Revised Submission 13
26. The only RTPS Submessages that contain application data are the Data and DataFrag. The appli-
cation data is contained within the SerializedData submessage element. In addition to the
SerializedData these submessages contain sequence numbers, inline QoS, the Key Hash, iden-
tifiers of the originating DataWriter and destination DataReader, etc.
The KeyHash submessage element may only appear in the Data and DataFrag submessages.
Depending on the data-type associated with the DataWriter that wrote the data the KeyHash sub-
message contains either:
• A serialized representation of the values of all the attributes that are declared as ‘key’ attributes
in the associated data-type
• Or else a MD5 hash computed over the aforementioned serialized key attributes.
Different RTPS Submessage within the same RTPS Message may originate on different
DataWriter or DataReader entities within the DomainParticipant that sent the RTPS Message.
It is also possible for a single RTPS Message to combine submessages that originated on different
DDS DomainParticipant entities this is done by preceding the set of RTPS Submessages that
originate from a common DomainParticipant with an InfoSource RTPS submessage.
7.2.2 Secure RTPS Messages
Section 7.1.1 identified the Threats addressed by the DDS Security Specification. Ito protect against
the “Authorized Subscription” threat it is necessary use encryption to protect the sensitive parts of
the RTPS message.
Depending on the application requirements it may be that the only thing that should be kept confi-
dential is the content of the application data, that is, the information contained in the “Serialized-
Data” RTPS submessage element. However, other applications may also consider the information
on on other RTPS SubmessageElements (e.g. sequence numbers, KeyHash, and unique writer/reader
identifiers) to be confidential. So the entire Data (or DataFrag) submessage may need to be en-
crypted. Similarly certain applications may consider other submessages such as Gap, AckNack,
Heartbeat, HeartbeatFrag, etc. to also be confidential.
For example, a Gap RTPS Submessage instructs a DataReader that a range of sequence num-
bers is no longer relevant. If an attacker can modify or forge a Gap message from a DataWriter
it can trick the DataReader into ignoring the data the DataWriter is sending.
To protect against the “Unauthorised Publication” and the “Tampering and Replay” threats it is nec-
essary that messages be signed using secure hashes or digital signatures. Depending on the applica-
tion it may be sufficient to sign only the application data (SerializedData submessage element),
the whole Submessage, and/or the whole RTPS Message.
To support different deployment scenarios this specification uses a “message transformation”
mechanism that gives the Security Plugin Implementations fine-grain control over which parts of the
RTPS Message need to be encrypted and/or signed.
The Message Transformation performed by the Security Plugins transforms an RTPS Message into
another RTPS Message. The RTPS Header is preserved, however the remaining content in the
14 DDS Security, Revised Submission
27. RTPS Message may be encrypted, protected by a Secure Message Authentication Code (MAC),
and/or signed. The MAC and/or signature can also include the RTPS Header to protect its integrity.
7.2.3 Platform Independent Description
<NOTE: THIS SECTION IS STILL PRELIMINARY AND
INCOMPLETE>
7.2.3.1 RTPS Secure Submessage Elements
7.2.3.1.1 CryptoTransformIdentifier
7.2.3.1.2 SecuredData
7.2.3.1.3 EncodedPayload
7.2.3.2 RTPS Secure Submessages
This specification introduces a new RTPS Submessages that will be used to wrap other submessages
securing their content. The format of the these additional RTPS submessages complies with the for-
mat of all RTPS submessages, consisting of an RTPS Submessage Header followed by a set of RTPS
submessage elements.
DDS Security, Revised Submission 15
28. 7.2.3.2.1 RTPS SecureSubMsg
7.2.3.2.1.1 Purpose
This submessage is used to wrap one or more regular RTPS submessages in such a way that their
contents are secured via encryption, message authentication, and/or digital signatures.
The Submessage conforms to the general structure of RTPS submessages and therefore can appear
inside a well-formed RTPS message.
7.2.3.2.1.2 Content
The elements that form the structure of the RTPS SecureSubMsg are described in the table below.
Element
Type
Meaning
EndianessFlag
SubmessageFlag
Appears
in
the
Submessage
header
flags.
Indicates
endianess.
16 DDS Security, Revised Submission
29. multisubmsgFlag
SubmessageFlag
Indicates
the
submessage
contains
potentially
multi-‐
ple
submessages
within
cryptoTransformId
CryptoTransformIdentifier
Identifies
the
kind
of
transformation
that
was
per-‐
formed
in
the
message
and
provides
additional
in-‐
formation
required
by
the
intended
recipients
to
de-‐
code
and
verify
the
message
payload
EncodedPayload
Contains
the
result
of
transforming
the
original
mes-‐
sage.
Depending
on
the
plugin
implementation
may
contain
encrypted
content,
message
access
codes
and/or
digital
signatures
7.2.3.2.1.3 Validity
The Submessage is invalid if the submessageLength in the Submessage header is too small.
7.2.3.2.1.4 Logical Interpretation
The SecureSubMsg provides a way to send secure content inside a legal RTPS submessage.
A SecureSubMsg may wrap a single RTPS Submessage, or a collection of RTPS submessages.
These two situations are distinguished by the value of the MultisubmsgFlag.
If the MultisubmsgFlag is false, then the SecureSubMsg contains a single RTPS submessage.
If the MultisubmsgFlag is true, then the SecureSubMsg may contain multiple RTPS submes-
sages. Whether it does or not will be determined by information inside the cryptoTransformId.
The specific mechanism depends on the encoding/transformation performed.
7.2.4 Mapping to UDP/IP PSM
<NOTE: THIS SECTION IS STILL PRELIMINARY AND
INCOMPLETE>
7.2.4.1 RTPS Secure Submessage Elements
7.2.4.1.1 CryptoTransformIdentifier
7.2.4.1.2 EncodedPayload
7.2.4.1.3 SecuredData
7.2.4.2 RTPS Secure Submessages
7.2.4.2.1 SecureSubMsg
7.2.4.2.1.1 Wire representation
7.2.4.2.1.2 Submessage Id
The SecureSubMsg shall have the submesageId set to the value 0x30.
DDS Security, Revised Submission 17
30. 7.2.4.2.1.3 Flags in the Submessage Header
8 Plug-in Architecture
There are five plugin SPIs- Authentication, Access-Control, Cryptographic, Logging, and Data Tag-
ging.
18 DDS Security, Revised Submission
31. The responsibilities and interactions between these Service Plugins are summarized in the table be-
low and detailed in the sections that follow.
Service Plugin Purpose Interactions
Authentication Authenticate the principal that is The principal may be an applica-
DDS Security, Revised Submission 19
32. joining a DDS Domain. tion/process or the user associated with
that application or process.
Support mutual authentication be-
tween participants and establishment
of a shared secret.
Access Control Decide whether a principal is al- Protected operations include joining a
lowed to perform a protected opera- specific DDS domain, creating a Topic,
tion. reading a Topic, writing a Topic, etc.
Cryptography Generate keys. Perform Key Ex- This plugin implements 4 complementary
change. Perform the encryption and interfaces: CryptoKeyFactory, Crypto-
decryption operations. Compute KeyExchange, and CryptoTransform.
digests, compute and verify Message
Authentication Codes. Sign and ver-
ify signatures of messages.
Logging Log all security relevant events
Data Tagging Add
a
data
tag
for
each
data
sample
8.1 Security Exception
SecurityException
Attributes
code SecurityExceptionCode
message String
Operations
init void
exception SecurityException
get_message String
exception SecurityException
get_code SecurityExceptionCode
exception SecurityException
get_minor_code long
exception SecurityException
20 DDS Security, Revised Submission
33. SecurityException objects are potentially returned from many of the calls in the plugins. They are
used to return an error code and message. Depending on the programming language used a Securi-
tyException may map to a programming-language exception or an output parameter to the function.
8.1.1 Operation: init
The operation
initializes
a
SecurityException.
Depending
on
the
programming
language
used,
this
function
may
be
automatically
provided
by
the
constructor,
or
it
may
need
to
be
ex-‐
plicitly
invoked.
8.1.2 Operation: get_message
The
operation
returns
a
textual
message
associated
with
the
SecurityException, the mes-‐
sage
provides
a
description
of
the
exception
in
human-‐readable
form.
8.1.3 Operation: get_code
The
operation
returns
the
code
associated
with
the
exception.
8.1.4 Operation: get_minor_code
The
operation
returns
a
plugin-‐dependent
code
associated
with
the
exception.
8.2 Property
Property is a data-type that holds a pair of strings. One is considered the property “name” and the
other the property “value” associated that name. Property Sequences are used as a generic data-type
to configure the plugins, pass meta-data and provide an extensible mechanism for vendors to config-
ure the behavior of their plugins without breaking portability or interoperability.
Properties with names that start with the prefix “dds.security.” are reserved by this specifica-
tion, including future versions of this specification. Plugin implementers can also use this mecha-
nism to pass meta-data and configure the behavior of their plugins. In order to avoid collisions on the
value of the “name” attribute implementers shall use property names that start with a prefix to an
ICANN domain name they own, in reverse order. For example the prefix would be “com.acme.” for
plugins developed by a hypothetical vendor that owns the domain “acme.com”.
The names and interpretation of the expected properties shall be specified by each Plugin implemen-
tation.
Property
Attributes
name String
value String
DDS Security, Revised Submission 21
34. 8.3 Credential
Credentials provide a generic mechanism to pass information from DDS to the Security Plugins. This
information is used to identify that application that is running and its permissions. The Credentials
data-type provides a generic container for security credentials and certificates. The actual format and
interpretation of the credentials and how they are configured is specific to each implementation of
the Security Plugins and shall be specified by each Security Plugin.
Typical use of credentials would be signed certificates or signed permissions documents. Credentials
are only exchanged locally between the DDS implementation and the plugins linked to it and running
in the same process space. They are never sent between processes over network.
The structure of Credentials is defined for all plugin implementations. However the contents and in-
terpretation of the Credentials attributes shall be specified by each Plugin implementation.
Credential
Attributes
credential_classid String
properties Property[]
value OctetSeq
There are several specializations of the Credential class. They all share the same format but are used
for different purposes this is modeled by defining specialized classes.
22 DDS Security, Revised Submission
35. 8.3.1 Attribute: credential_classid
Identifies the kind of credential.
Values of the credential_class_id with the prefix “dds.” are reserved for this specification, includ-
ing future versions of the specification. Implementers of this specification can use this attribute to
identify non-standard Credentials. In order to avoid collisions the credential_class_id they use shall
start with a prefix to an ICANN domain name they own, using the same rules specified in Section 8.2
for property names.
8.3.2 Attribute: properties
Tis attribute is a container for meta-data to be held in the Credential. The contents are specific to
each plugin implementation.
8.3.3 Attribute: value
This attribute is used to hold the data stored in the Credential. The contents are specific to each
plugin implementation.
8.4 Token
Tokens provide a generic mechanism to pass information between Security Plugins using DDS as the
transport. Token objects are meant for transmission over the network using DDS either embedded
within the BuiltinTopicData sent via discovery or alternatively via special Topics defines by this
specification.
The structure of Tokens is defined for all plugin implementations. However the contents and inter-
pretation of the Token attributes shall be specified by each Plugin implementation.
Token
Attributes
token_classid String
wrapper_classid String
properties Property[]
value OctetSeq
wrapped_value OctetSeq
There are multiple specializations of the Token class. They all share the same format but are used for
different purposes this is modeled by defining specialized classes.
DDS Security, Revised Submission 23
36. 8.4.1 Attribute: token_classid
Identifies the kind of token.
Strings with the prefix “dds.security.” are reserved for this specification, including future ver-
sions of the specification. Implementers of this specification can use this attribute to identify non-
standard tokens. In order to avoid collisions the token_classid they use shall start with a prefix
to an ICANN domain name they own, using the same rules specified in Section 8.2 for property
names.
8.4.2 Attribute: wrapper_classid
Identifies the kind of encryption used to protect the wrapped_value, if any.
Strings with the prefix “dds.security.” are reserved for this specification, including future ver-
sions of the specification. Implementers of this specification can use this attribute to identify non-
standard token wrappers. In order to avoid collisions on the chosen string the wrapped_classid
they use shall start with a prefix to an ICANN domain name they own, using the same rules specified
in Section 8.2 for property names.
8.4.3 Attribute: properties
This attribute provides a container for meta-data to be held in the Token. The contents are specific to
each plugin implementation.
24 DDS Security, Revised Submission
37. 8.4.4 Attribute: value
This attribute is used to hold the data stored in the token. The contents are specific to each plugin
implementation. The value attribute is intended to store data in ‘cleartext’. To store encrypted or
signed data the plugin implementation should use the wrapped_value attribute instead.
8.4.5 Attribute: wrapped_value
This attribute is used to hold the data stored in the token. The contents are specific to each plugin
implementation. The value attribute is intended to store ‘cryptographically protected’ data. The kind
of protection (e.g. encryption and/or signature) is indicated by the value of the wrapper_classid
attribute.
8.5 DDS support for plugin message exchange
In order to perform mutual authentication and key exchange between DDS Participants the security
plugins associated with those participants need to exchange messages.
DDS already has a mechanism for message exchange between the Participants. Exposing some of
these facilities to the Security Plugins would greatly simplify the implementation of the plugins,
which would be relieved from having to implement a separate messaging protocol.
The DDS interoperability wire protocol specifies the existence of two built-in end points BuiltinPar-
ticipantMessageWriter and BuiltinParticipantMessageReader (See section 9.6.2.1 of the DDS
Interoperability Protocol).
These endpoints were designed to be extensible and support the kind of message-exchanged needed
by the security plugins.
The messages exchanged by the BuiltinParticipantMessageWriter have the associated type Partici-
pantMessageData. This type is as defined by the DDS Interoperability Wire Protocol version 2.1)
and can be represented in IDL as:
typedef octet GuidPrefix_t[12];
typedef octet ParticipantMessageDataKind[4];
struct ParticipantMessageData {
GuidPrefix_t participantGuidPrefix; //@Key
ParticipantMessageDataKind kind; //@Key
sequence<octet> data;
};
The Interoperability Wire Protocol furthermore states that the messages sent by the BuiltinPartici-
pantMessageWriter shall always set the participantGuidPrefix to the GUID prefix of the originating
participant.
The ‘kind’ attribute is used to identify of different types of messages. The actual data is carried on
the ‘value’ octet sequence. Its content and format is specified for each value of the ‘kind’ attribute.
DDS Security, Revised Submission 25
38. 8.5.1 Reserved values of ParticipantMessageDataKind
This specification, including future versions of this specification reserves ParticipantMes-
sageDataKind values in the range 0x00010000 to 0x0001FFFF, both included.
Within the above range, the range 0x00018000 to 0x0001FFFF is reserved for vendor-specific exten-
sions and shall not be used by this specification, including future versions of this specification.
The specification defines the following values for the ParticipantMessageDataKind:
#define KIND_SECURITY_AUTH_HANDSHAKE {0x00, 0x01, 0x00, 0x01}
#define KIND_SECURITY_PARTICIPANT_CRYPTO_TOKENS {0x00, 0x01, 0x00, 0x02}
#define KIND_SECURITY_DATAWRITER_CRYPTO_TOKENS {0x00, 0x01, 0x00, 0x03}
#define KIND_SECURITY_DATAREADER_CRYPTO_TOKENS {0x00, 0x01, 0x00, 0x04}
Additional values of the ParticipantMessageDataKind may be defined with each plugin implemen-
tation.
8.5.2 Format of data within ParticipantMessageData
Each value for the kind in ParticipantMessageData uses different schema to store data within the
data (octet sequence) attribute in the ParticipantMessageData.
8.5.2.1 Data for message kind KIND_SECURITY_AUTH_HANDSHAKE
If ParticipantMessageData kind is KIND_SECURITY_AUTH_HANDSHAKE the data attribute
contains the CDR big-endian serialization of the structure MessageToken defined by the IDL below:
struct Property {
string<> name;
string<> value;
};
struct Token {
string<> token_classid;
string<> wrapper_classid;
sequence<Property> properties;
sequence<octet> value;
};
struct MessageToken : Token {
};
struct CryptoToken : Token {
};
8.5.2.2 Data for message kind KIND_SECURITY_PARTICIPANT_CRYPTO_TOKENS
If ParticipantMessageData kind is KIND_SECURITY_
PARTICIPANT_CRYPTO_TOKENS the data attribute contains the CDR big-endian serialization of the
structure ParticipantCryptoTokenSMsg defined by the IDL below:
struct ParcicipantCryptoTokensMsg {
26 DDS Security, Revised Submission
39. octet sending_participant_guid[16];
octet receiving_participant_guid[16];
sequence<CryptoToken> crypto_tokens;
};
8.5.2.3 Data for message kind KIND_SECURITY_DATAWRITER_CRYPTO_TOKENS
If ParticipantMessageData kind is KIND_SECURITY_
DATAWRITER_CRYPTO_TOKENS the data attribute contains the CDR big-endian serialization of the
structure DatawriterCryptoTokensMsg defined by the IDL below:
struct DatawriterCryptoTokensMsg {
octet datawriter_guid[16];
octet readerwriter_guid[16];
sequence<CryptoToken> crypto_tokens;
};
8.5.2.4 Data for message kind KIND_SECURITY_DATAREADER_CRYPTO_TOKENS
If ParticipantMessageData kind is KIND_SECURITY_
DATAWRITER_CRYPTO_TOKENS the data attribute contains the CDR big-endian serialization of the
structure DatareaderCryptoTokensMsg defined by the IDL below:
struct DatareaderCryptoTokensMsg {
octet readerwriter_guid[16];
octet datawriter_guid[16];
sequence<CryptoToken> crypto_tokens;
};
8.6 Authentication Plug-in
The Authentication Plug-in SPI defines the types and operations necessary to support the authentica-
tion of DDS DomainParticipants.
8.6.1 Background (Non-Normative)
Without the security enhancements, any DDS DomainParticipant is allowed to join a DDS
Domain without authenticating. However, in the case of a secure DDS system, every DDS partici-
pant will be required to authenticate to avoid data contamination from unauthenticated participants.
The DDS protocol detects when participants enter the network through its native discovery mecha-
nism.
The discovery mechanism that registers participants with the DDS middleware is enhanced with an
authentication protocol. A participant that enables the authentication plug-in will only communicate
to another participant that has the authentication plug-in enabled.
The plugin SPI is designed to support multiple implementations which may require varying numbers
of message exchanges, which may be used to challenge the other side so it can determine it knows
the secrets, associated with its credential, and potentially establish shared secrets, which can then be
used to exchange session keys.
DDS Security, Revised Submission 27
40. 8.6.2 Authentication Plug-in Model
The Authentication Plug-in model is presented in the figure below.
8.6.2.1 IdentityCredential
This is a native type that represents the information that is passed from the DDS middleware to the
plugin in order to prove identity of the application that contains the DomainParticipant. The
structure and interpretation of the contents as well as the mechanism used to pass it to the
AuthenticationPlugin shall be specified by each plugin implementation.
28 DDS Security, Revised Submission
41. 8.6.2.2 IdentityToken
An IdentityToken encodes the identity information for a DomainParticipant, in a manner
that can be externalized and propagated via discovery.
8.6.2.3 IdentityHandle
An IdentityHandle is an opaque local reference to internal state within the
AuthenticationPlugin, which uniquely identifies a DomainParticipant. It is under-
stood only by the AuthenticationPlugin and references the authentication state of the Partici-
pant. This object is returned by the AuthenticationPlugin as part of the validation of the
identity of a DomainParticipant and is used whenever a client of the
AuthenticationPlugin needs to refer to the identity of a previously identified
DomainParticipant.
8.6.2.4 HandshakeHandle
A HandshakeHandle is an opaque local reference used to refer to the internal state of a possible
mutual authentication or handshake protocol.
8.6.2.5 MessageToken
A MessageToken encodes plugin-specific information that the Authentication plugins associated
with two DomainParticipant entities exchange as part of the mutual authentication handshake. The
MessageToken are understood only by the AuthenticationPlugin implementations on ei-
ther side of the handshake. The MessageToken are sent and received by the DDS implementation
under the direction of the AuthenticationPlugins.
8.6.2.6 SharedSecretHandle
A SharedSecretHandle is an opaque local reference to internal state within the
AuthenticationPlugin containing a secret that is shared between the
AuthenticationPlugin implementation and the peer AuthenticationPlugin implemen-
tation associated with a remote DomainParticipant. It is understood only by the two
AuthenticationPlugin implementations that share the secret. The shared secret is used to en-
code Tokens, such as the CryptoToken, such that they can be exchanged between the two
DomainParticipants in a secure manner.
8.6.2.7 Authentication
This interface is the starting point for all the security mechanisms. When a DomainParticipant
is either locally created or discovered, it needs to be authenticated in order to be able to communicate
in a DDS Domain.
The interaction between the DDS implementation and the Authentication plugins has been designed
in a flexible manner so it is possible to support various authentication mechanisms, including those
DDS Security, Revised Submission 29
42. that require a handshake and/or perform mutual authentication between participants and establishes a
shared secret. This interaction is described in the state machine illustrated in the figure below.
Authentication
No Attributes
Operations
validate_local_ident ValidationResult_t
ity
out: IdentityHandle
30 DDS Security, Revised Submission
44. out: MessageToken
handshake_message_out
handshake_message_in MessageToken
handshake_handle HandshakeHandle
exception SecurityException
get_shared_secret SharedSecretHandle
handshake_handle HandshakeHandle
exception SecurityException
set_listener Boolean
listener AuthenticationListen
er
exception SecurityException
return_token Boolean
token IdentityToken
exception SecurityException
return_handshake_han Boolean
dle
handshake_handle HandshakeHandle
exception SecurityException
return_identity_hand Boolean
le
identity_handle IdentityHandle
exception SecurityException
return_sharedsecret_ Boolean
handle
sharedsecret_handle SharedSecretßHandle
exception SecurityException
8.6.2.7.1 Type: ValidationResult_t
Enumerates the possible return values of the validate_local_identity and validate_remote_identity
operations.
ValidationResult_t
VALIDATION_OK Indicates the validation has
succeeded
32 DDS Security, Revised Submission
45. VALIDATION_FAILED Indicates the validation has
failed
VALIDATION_PENDING_RETRY Indicates that validation is
still proceeding. The
operation shall be retried at
a later point in time.
VALIDATION_PENDING_HANDSHAKE_REQUEST Indicates that validation of
the submitted IdentityToken
requires sending a handshake
message. The DDS
Implementation shall call the
operation
begin_handshake_request and
send the MessageToken obtained
from this call using the
BuiltinParticipantMessageWriter.
VALIDATION_PENDING_HANDSHAKE_MESSAGE Indicates that validation is
still pending. The DDS
Implementation shall wait for
a message on the
BuiltinParticipantMessageReader and
once this is received call
process_handshake passing the
infrmation received in that
message.
VALIDATION_OK_FINAL_MESSAGE Indicates that validation has
succeeded but the DDS
Implementation shall send a
final message using the Builtin-
ParticipantMessageWriter.
8.6.2.7.2 Operation: validate_local_identity
Validates the identity of the local DomainParticipant, provided by an
IdentityCredential. The operation returns as an output parameter the IdentityHandle,
which can be used to locally identify the local Participant to the AuthenticationPlugin.
If an error occurs, this method shall return VALIDATION_FAILED.
The method shall return either VALIDATION_OK if the validation succeeds, or VALIDA-
TION_FAILED if it fails, or VALIDATION_PENDING_RETRY if the verification has not finished.
If VALIDATION_PENDING_RETRY is been returned, the operation shall be called again after a
configurable delay to check the status of verification. This shall continue until the operation returns
DDS Security, Revised Submission 33
46. either VALIDATION_OK if the validation succeeds, or VALIDATION_FAILED. This approach
allows non-blocking interactions with services whose verification may require invoking remote serv-
ices.
Parameter local_identity_handle: A handle that can be used to locally refer to the Authenticated
Participant in subsequent interactions with the AuthenticationPlugin. The nature of the han-
dle is specific to each AuthenticationPlugin implementation. The handle will only be mean-
ingful if the operation returns VALIDATION_OK.
Parameter credential: A credential that the AuthenticationPlugin implementation may use to vali-
date the identity of the local DomainParticipant. The nature and configuration of the credential
is specific to each AuthenticationPlugin implementation.
Parameter exception: A SecurityException object.
Return: The operation shall return
• VALIDATION_OK if the validation was successful
• VALIDATION_FAILED if it failed.
• VALIDATION_PENDING_RETRY if verification has not completed, and the operation
should be retried later.
8.6.2.7.3 Operation: validate_remote_identity
Initiates the process of validating the identity of the discovered remote DomainParticipant,
represented as an IdentityToken object. The operation returns the ValidationResult_t
indicating whether the validation succeeded, failed, or is pending a handshake. If the validation suc-
ceeds, an IdentityHandle object is returned which can be used to locally identify the remote
DomainParticipant to the AuthenticationPlugin.
If the validation can be performed solely with the information passed and it succeeds the operation
shall return VALIDATION_OK. If it can be performed with the information passed and it fails it
shall return VALIDATION_FAILED.
The validation of a remote participant might require the remote participant to perform a handshake.
In this situation the validate_remote_identity operation shall return VALIDA-
TION_PENDING_HANDSHAKE_REQUEST or VALIDA-
TION_PENDING_HANDSHAKE_MESSAGE.
If the operation returns VALIDATION_PENDING_HANDSHAKE_REQUEST, then the DDS im-
plementation shall call the operation begin_handshake_request to continue the validation
process.
If the operation returns VALIDATION_PENDING_HANDSHAKE_MESSAGE, then the DDS im-
plementation shall wait until it receives a handshake message from the remote participant identified
by the remote_participant_key. This message is received on the BuiltinParticipantMessageReader
and shall contain a participantGuidPrefix matching the remote_participant_key and a kind match-
ing KIND_SECURITY_AUTH_HANDSHAKE.
Upon receiving the above ParticipantMessageData message the DDS implementation shall interpret
the bytes inside the ParticipantMessageData data sequence as the CDR serialization of a
MessageToken and shall call the operation begin_handshake_reply passing the received
34 DDS Security, Revised Submission
47. MessageToken and shall call the operation begin_handshake_reply passing the received
MessageToken as the handshake_message_in.
If an error occurs, this method shall throw an exception.
Parameter remote_identity_token : A token received as part of
ParticipantBuiltinTopicData representing the identity of the remote
DomainParticipant.
Parameter local_identity_handle: A handle to the local DomainParticipant that is requesting
the remote participant to be validated. The local handle must have been obtained by an earlier call to
validate_local_identity.
Parameter (out) remote_identity_handle: A handle that can be used to locally refer to the remote
Authenticated Participant in subsequent interactions with the AuthenticationPlugin. The na-
ture of the remote_identity_handle is specific to each AuthenticationPlugin implementa-
tion. The handle will only be provided if the operation returns something other than VALIDA-
TION_FAILED.
Parameter exception: A SecurityException object.
Return: The operation shall return:
• VALIDATION_OK if the validation was successful,
• VALIDATION_FAILED if it failed,
• VALIDATION_PENDING_HANDSHAKE_REQUEST if validation has not completed and
the DDS implementation shall call begin_handshake_request, to continue the valida-
tion.
• VALIDATION_PENDING_HANDSHAKE_MESSAGE if validation has not completed and
the DDS implementation shall wait for a message on the BuiltinParticipantMessageReader
with the participantGuidPrefix matching the remote_participant_key and a kind matching
KIND_SECURITY_AUTH_HANDSHAKE and then call the operation
begin_handshake_reply, to continue the validation.
• VALIDATION_PENDING RETRY if the validation has not completed and the operation
should be called again at a later point in time to check the status of validation.
8.6.2.7.4 Operation: begin_handshake_request
This operation is used to initiate a handshake when the first handshake message must be generated. It
shall be called by the DDS middleware solely as a result of having a previous call to vali-
date_remote_identity returns VALIDATION_PENDING_HANDSHAKE_REQUEST.
This operation returns a MessageToken that shall be used to send a handshake to the remote partici-
pant identified by the replier_identity_handle.
The contents of the MessageToken are specified by the plugin implementation.
If an error occurs, this method shall throw an exception.
Parameter (out) handshake_handle: A handle returned by the Authentication Plugin used keep the
state of the handshake. It is passed to other operations in the Plugin
DDS Security, Revised Submission 35
48. Parameter (out) handshake_message: A Token containing a message to be sent using the Builtin-
ParticipantMessageWriter. The contents shall be specified by each plugin implementation.
Parameter initiator_identity_handle: Handle to the local participant that originated the handshake.
Parameter replier_identity_handle: Handle to the remote participant whose identity is being vali-
dated.
Parameter exception: A SecurityException object.
Return: The operation shall return:
• VALIDATION_OK if the validation was successful,
• VALIDATION_FAILED if it failed,
• VALIDATION_PENDING_HANDSHAKE_MESSAGE if validation has not completed and
the DDS implementation shall send the handshake_message_out using the BuiltinPartici-
pantMessageWriter and then wait for a message on the BuiltinParticipantMessageReader
with the participantGuidPrefix matching the remote_participant_key and a kind matching
KIND_SECURITY_AUTH_HANDSHAKE and then call the operation
begin_handshake_reply, to continue the validation.
• VALIDATION_OK_FINAL_MESSAGE if the validation succeeded but the DDS implemen-
tation shall send the returned handshake_message using the BuiltinParticipantMes-
sageReader.
• VALIDATION_PENDING RETRY if the validation has not completed and the operation
should be called again at a later point in time to check the status of validation.
8.6.2.7.5 Operation: begin_handshake_reply
This operation is used to initiate a handshake when an initial handshake message has been received
from another participant. It shall be called by the DDS middleware solely as a result of having a pre-
vious call to validate_remote_identity returns VALIDA-
TION_PENDING_HANDSHAKE_MESSAGE and having also received a message on the Builtin-
ParticipantMessageReader with the participantGuidPrefix matching the GUID prefix of the par-
ticipant associated with the initiator_identity_handle and a kind matching
KIND_SECURITY_AUTH_HANDSHAKE.
This operation generates a handshake_message_out in response to a received hand-
shake_message_in. Depending on the return value of the function the DDS implementation shall
send the handshake_message_out using the BuiltinParticipantMessageWrite to the participant
identified by the initiator_identity_handle.
The contents of the handshake_message_out MessageToken are specified by the plugin implemen-
tation.
If an error occurs, this method shall throw an exception.
Parameter (out) handshake_handle: A handle returned by the Authentication Plugin used keep the
state of the handshake. It is passed to other operations in the Plugin
Parameter (out) handshake_message_out: A Token containing a message to be sent using the
BuiltinParticipantMessageWriter. The contents shall be specified by each plugin implementation.
36 DDS Security, Revised Submission
49. Parameter handshake_message_in: A Token containing a message received from the BuiltinPar-
ticipantMessageReader. The contents shall be specified by each plugin implementation.
Parameter initiator_identity_handle: Handle to the remote participant that originated the hand-
shake.
Parameter replier_identity_handle: Handle to the local participant that is initiating the handshake
response.
Parameter exception: A SecurityException object.
Return: The operation shall return:
• VALIDATION_OK if the validation was successful,
• VALIDATION_FAILED if it failed,
• VALIDATION_PENDING_HANDSHAKE_MESSAGE if validation has not completed and
the DDS implementation shall send the handshake_message_out using the BuiltinPartici-
pantMessageWriter and then wait for a reply message on the BuiltinParticipantMes-
sageReader from that remote participant. The messages exchanges shall have kind matching
KIND_SECURITY_AUTH_HANDSHAKE
• VALIDATION_OK_FINAL_MESSAGE if the validation succeeded but the DDS implemen-
tation shall send the returned handshake_message_out using the BuiltinParticipantMes-
sageReader.
• VALIDATION_PENDING RETRY if the validation has not completed and the operation
should be called again at a later point in time to check the status of validation.
8.6.2.7.6 Operation: process_handshake
This operation is used to continue a handshake. It shall be called by the DDS middleware solely as a
result of having a previous call to begin_handshake_request returns or begin_handshake_reply that
returned VALIDATION_PENDING_HANDSHAKE_MESSAGE and having also received a mes-
sage on the BuiltinParticipantMessageReader with the participantGuidPrefix matching the GUID
prefix of the participant associated with the initiator_identity_handle and a kind matching
KIND_SECURITY_AUTH_HANDSHAKE.
This operation generates a handshake_message_out in response to a received hand-
shake_message_in. Depending on the return value of the function the DDS implementation shall
send the handshake_message_out using the BuiltinParticipantMessageWriter to the participant
identified by the initiator_identity_handle.
The contents of the handshake_message_out MessageToken are specified by the plugin implemen-
tation.
If an error occurs, this method shall throw an exception.
Parameter (out) handshake_message_out: A Token containing a message to be sent using the
BuiltinParticipantMessageWriter. The contents shall be specified by each plugin implementation.
Parameter handshake_message_in: A Token containing a message received from the BuiltinPar-
ticipantMessageReader. The contents shall be specified by each plugin implementation.
DDS Security, Revised Submission 37