• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
OMG DDS Security Specification - 4th revised submission document
 

OMG DDS Security Specification - 4th revised submission document

on

  • 1,489 views

NOTE: This document has been obsoleted by the Adopted DDS Specification ...

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

Statistics

Views

Total Views
1,489
Views on SlideShare
1,489
Embed Views
0

Actions

Likes
0
Downloads
11
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    OMG DDS Security Specification - 4th revised submission document OMG DDS Security Specification - 4th revised submission document Document Transcript

    • Date: March 2013 revised submissionDDS SecurityJoint Revised Submission____________________________________________________OMG Document: dds/2013-02-15(March 2013 revised submission)________________________________________________Submission Contacts:Gerardo Pardo-Castellote, Ph.D. (lead)CTO, Real-Time Innovations, Inc.gerardo@rti.comJaime Martin-LosaCTO, eProsima.jaime.martin@eprosima.comAngelo Corsaro, Ph.D.CTO, PrimsTech.angelo.corsaro@prismtech.com
    • Copyright © 2011, Object Management Group, Inc. (OMG)Copyright © 2010, Real-Time Innovations, Inc. (RTI) USE OF SPECIFICATION - TERMS, CONDITIONS & NOTICESThe material in this document details an Object Management Group specification in accordancewith the terms, conditions and notices set forth below. This document does not represent acommitment to implement any portion of this specification in any companys products. Theinformation contained in this document is subject to change without notice. LICENSESThe company listed above have granted to the Object Management Group, Inc. (OMG) anonexclusive, royalty-free, paid up, worldwide license to copy and distribute this document andto modify this document and distribute copies of the modified version. Each of the copyrightholders listed above has agreed that no person shall be deemed to have infringed the copyright inthe included material of any such copyright holder by reason of having used the specification setforth herein or having conformed any computer software to the specification.Subject to all of the terms and conditions below, the owners of the copyright in this specificationhereby grant you a fully-paid up, non-exclusive, nontransferable, perpetual, worldwide license(without the right to sublicense), to use this specification to create and distribute software andspecial purpose specifications that are based upon this specification, and to use, copy, anddistribute this specification as provided under the Copyright Act; provided that: (1) both thecopyright notice identified above and this permission notice appear on any copies of thisspecification; (2) the use of the specifications is for informational purposes and will not becopied or posted on any network computer or broadcast in any media and will not be otherwiseresold or transferred for commercial purposes; and (3) no modifications are made to thisspecification. This limited permission automatically terminates without notice if you breach anyof these terms or conditions. Upon termination, you will destroy immediately any copies of thespecifications in your possession or control. PATENTSThe attention of adopters is directed to the possibility that compliance with or adoption of OMGspecifications may require use of an invention covered by patent rights. OMG shall not beresponsible for identifying patents for which a license may be required by any OMGspecification, or for conducting legal inquiries into the legal validity or scope of those patentsthat are brought to its attention. OMG specifications are prospective and advisory only.Prospective users are responsible for protecting themselves against liability for infringement ofpatents.
    • GENERAL USE RESTRICTIONSAny unauthorized use of this specification may violate copyright laws, trademark laws, andcommunications regulations and statutes. This document contains information, which isprotected by copyright. All Rights Reserved. No part of this work covered by copyright hereinmay 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--withoutpermission of the copyright owner. DISCLAIMER OF WARRANTYWHILE THIS PUBLICATION IS BELIEVED TO BE ACCURATE, IT IS PROVIDED "ASIS" AND MAY CONTAIN ERRORS OR MISPRINTS. THE OBJECT MANAGEMENTGROUP AND THE COMPANIES LISTED ABOVE MAKE NO WARRANTY OF ANYKIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS PUBLICATION, INCLUDINGBUT NOT LIMITED TO ANY WARRANTY OF TITLE OR OWNERSHIP, IMPLIEDWARRANTY OF MERCHANTABILITY OR WARRANTY OF FITNESS FOR APARTICULAR PURPOSE OR USE. IN NO EVENT SHALL THE OBJECT MANAGEMENTGROUP OR ANY OF THE COMPANIES LISTED ABOVE BE LIABLE FOR ERRORSCONTAINED HEREIN OR FOR DIRECT, INDIRECT, INCIDENTAL, SPECIAL,CONSEQUENTIAL, RELIANCE OR COVER DAMAGES, INCLUDING LOSS OFPROFITS, REVENUE, DATA OR USE, INCURRED BY ANY USER OR ANY THIRDPARTY IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THISMATERIAL, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.The entire risk as to the quality and performance of software developed using this specification isborne by you. This disclaimer of warranty constitutes an essential part of the license granted toyou to use this specification. RESTRICTED RIGHTS LEGENDUse, duplication or disclosure by the U.S. Government is subject to the restrictions set forth insubparagraph (c) (1) (ii) of The Rights in Technical Data and Computer Software Clause atDFARS 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 theDoD F.A.R. Supplement and its successors, or as specified in 48 C.F.R. 12.212 of the FederalAcquisition Regulations and its successors, as applicable. The specification copyright owners areas indicated above and may be contacted through the Object Management Group, 140 KendrickStreet, Needham, MA 02494, U.S.A. TRADEMARKSMDA®, Model Driven Architecture®, UML®, UML Cube logo®, OMG Logo®, CORBA® andXMI® are registered trademarks of the Object Management Group, Inc., and Object
    • Management Group™, OMG™ , Unified Modeling Language™, Model Driven ArchitectureLogo™, Model Driven Architecture Diagram™, CORBA logos™, XMI Logo™, CWM™,CWM Logo™, IIOP™ , MOF™ , OMG Interface Definition Language (IDL)™ , and OMGSysML™ are trademarks of the Object Management Group. All other products or companynames mentioned are used for identification purposes only, and may be trademarks of theirrespective owners. COMPLIANCEThe copyright holders listed above acknowledge that the Object Management Group (actingitself or through its designees) is and shall at all times be the sole entity that may authorizedevelopers, suppliers and sellers of computer software to use certification marks, trademarks orother special designations to indicate compliance with these materials.Software developed under the terms of this license may claim compliance or conformance withthis specification if and only if the software compliance is of a nature fully matching theapplicable compliance points as stated in the specification. Software developed only partiallymatching the applicable compliance points may claim only that the software was based on thisspecification, but may not claim compliance or conformance with this specification. In the eventthat testing suites are implemented or approved by Object Management Group, Inc., softwaredeveloped using this specification may claim compliance or conformance with the specificationonly if the software satisfactorily completes the testing suites.
    • OMG’s Issue Reporting ProcedureAll 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 mayfind 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.)
    • Table of Contents1   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.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
    • 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
    • 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
    • PrefaceOMGFounded in 1989, the Object Management Group, Inc. (OMG) is an open membership, not-for-profitcomputer industry standards consortium that produces and maintains computer industry specifica-tions for interoperable, portable, and reusable enterprise applications in distributed, heterogeneousenvironments. Membership includes Information Technology vendors, end users, government agen-cies, and academia.OMG member companies write, adopt, and maintain its specifications following a mature, openprocess. OMG’s specifications implement the Model Driven Architecture® (MDA®), maximizingROI 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 SpecificationsAs noted, OMG specifications address middleware, modeling and vertical domain frameworks. ASpecifications Catalog is available from the OMG website at:http://www.omg.org/technology/documents/spec_catalog.htmSpecifications within the Catalog are organized by the following categories:OMG Modeling Specifications• UML• MOF• XMI• CWM• Profile specificationsOMG Middleware Specifications• CORBA/IIOP• Data-Distribution Service (DDS) Specifications• IDL/Language MappingsDDS Security, Revised Submission v
    • • Specialized CORBA specifications• CORBA Component Model (CCM)Platform Specific Model and Interface Specifications• CORBAservices• CORBAfacilities• OMG Domain specifications• OMG Embedded Intelligence specifications• OMG Security specificationsAll of OMG’s formal specifications may be downloaded without charge from our website. (Productsimplementing OMG specifications are available from individual suppliers.) Copies of specifications,available in PostScript and PDF format, may be obtained from the Specifications Catalog cited aboveor by contacting the Object Management Group, Inc. at:OMG Headquarters140 Kendrick StreetBuilding A, Suite 300Needham, MA 02494USATel: +1-781-444-0404Fax: +1-781-444-0320Email: pubs@omg.orgCertain OMG specifications are also available as ISO standards. Please consult http://www.iso.org.Typographical ConventionsThe type styles shown below are used in this document to distinguish programming statements fromordinary English. However, these conventions are not used in tables or section headings where nodistinction is necessary.Times/Times New Roman - 10 pt.: Standard body textHelvetica/Arial - 10 pt. Bold: OMG Interface Definition Language (OMG IDL) and syntaxelements.Courier - 10 pt. Bold: Programming language elements.Helvetica/Arial - 10 pt: ExceptionsNOTE: Terms that appear in italics are defined in the glossary. Italic text also represents the nameof a document, specification, or other publication.vi DDS Security, Revised Submission
    • 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
    • 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 evento 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 informationand 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) toprovide simple access to standard, interoperable, pre-defined security policies out-of-the box. At thesame 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, AuthorizationPolicy repositories, or cryptographic libraries, which might be program or project specific.1.5 Overview of this SpecificationThis specification defines the Security Model and Service Plugin Interface (SPI) architecture forcompliant DDS implementations. The DDS Security Model is enforced by the invocation of theseSPIs by the DDS implementation. This specification also defines a set of built-in implementations ofthese 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
    • 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
    • 1.6 Design Rationale1.7 Statement of Proof of Concept1.8 Resolution of RFP Requirements and RequestsThe specification resolves the following mandatory requirements:Table 1. Mandatory RFP RequirementsRequirement Description Reference Remarks6.5.16.5.16.5.36.5.46.5.5The proposed specification addresses the following optional requirements:Table 2. Optional RFP RequirementsRequirement Description Reference Remarks6.6.16.6.26.6.36.6.46.6.56.6.66.6.76.6.81.9 Responses to RFP Issues to be discussedThe specification discusses the following issues:4 DDS Security, Revised Submission
    • Table 3. RFP Issues to be DiscussedIssue Description Reference Remarks6.7.16.7.26.7.36.7.46.7.5DDS Security, Revised Submission 5
    • PART II – PIM and Language PSMsfor 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
    • 4 Normative ReferencesRFC 20145 Terms and DefinitionsFor 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 bespecified for data timeliness and reliability. It is independent of implementation languages.Information AssuranceThe 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.AuthenticationSecurity measure designed to establish the identity of a transmission, message, or originator.Access ControlMechanism that enables an authority to control access to areas and resources in a given physical fa-cility or computer-based information system.ConfidentialityAssurance that information is not disclosed to unauthorized individuals, processes, or devices.IntegrityProtection against unauthorized modification or destruction of information.Non-RepudiationAssurance the sender of data is provided with proof of delivery and the recipient is provided withproof of the senders identity, so neither can later deny having processed the data.6 SymbolsPKIHMACDDS Security, Revised Submission 7
    • This specification does not define any symbols or abbreviations.7 DDS Security7.1 Security ModelThe Security Model for DDS must define the security principals (users of the system), the objectsthat are being secured, and the operations on the objects that are to be restricted. DDS applicationsshare 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 thoseTopics.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 theDDS 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 dataTo provide secure access to the DDS Global Data Space applications that use DDS must first beauthenticated, 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 controldecisions that determine whether the application is allowed to perform specific actions. Examples ofactions 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 inthe data). Enforcement of the access control shall be supported by cryptographic techniques such thatinformation confidentiality and integrity can be maintained, which in turn requires an infrastructureto manage and distribute the necessary cryptographic keys.8 DDS Security, Revised Submission
    • 7.1.1 ThreatsIn order to understand the decisions made in the design of the plugins it is important to understandsome 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 dataThese threats are described in the context of a hypothetical communication scenario with 6 actors allattached 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
    • 7.1.1.1 Unauthorized SubscriptionThe DomainParticipant Eve is connected to the same network infrastructure and is able to observethe 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 communicationchannels. Or in situations where Alice and Bob are communicating over multicast Eve could simplysubscribe to the same multicast address.Protecting against Eve is reasonably simple. All that is required is for Alice to encrypt the data itwrites using a secret key that is only shared with authorized receivers such as Bob, Trent, and Mal-lory.7.1.1.2 Unauthorized PublicationThe DomainParticipant Trudy is connected to the same network infrastructure and is able to injectnetwork packets with any data contents, headers and destination it wishes (e.g Alice). The networkinfrastructure 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 senddata 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 requirethat 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
    • • 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 insubsequent sections. Suffice it to say that in many situations the use of HMAC is preferred as theperformance to compute and verify them is about 1000 faster than the performance of comput-ing/verifying digital signatures.7.1.1.3 Tampering and ReplayMallory is authorized to subscribe to Topic T, Therefore Alice has shared with Mallory the secretkey 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 hasof 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 necessaryRTPS identifiers (e.g. Alice’s RTPS DomainParticipant and DataWriter GUIDs). Mallory has thesecret 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 forthe new message. Bob and the others will have no way to see that message came from Mallory andwill 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 whensending the message to Mallory cannot be the same it uses when sending messages to Bob. In otherwords Alice must share a different secret key for HMAC with each recipient. That way Mallory willnot have the HMAC key that Bob expects from Alice and the messages from Mallory to Bob will notbe 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 makesthe use of multicast simpler. However the performance penalty of using digital signatures is so highthat 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 servicesInfrastructure 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 theoriginal application.DDS Security, Revised Submission 11
    • These services can be trusted to not be malicious, however often it is not desirable to grant them theprivileges 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 necessarythat the security model supports the concept of having a participant, such as Trent, that is allowed toreceive, process, and relay RTPS messages, but is not allowed to see the contents of the data withinthe message. In other words it can see the headers and sample information (writer GUID, sequencenumbers, 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, butnot the secret key used to encrypt the data itself. In addition Bob, Mallory and others need to acceptTrent as someone that is able to write on topic T, and moreover relay messages from Alice. Thismeans two things, (1) accept and interpret messages encrypted with Alice’s secret key and (2) allowTrent to include in its sample information the information it got from Alice (writer GUID, sequencenumber 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 lackingthe secret key used for encryption it will be unable to see the data. When it relays the message toBob, it will include the information that indicates the message originated in Alice and produce anHMAC with its own secret HMAC key that it shared with Bob. Bob will receive the message, verifythe HMAC and then see it is a relayed message from Alice. Bob recognizes Trent is authorized torelay messages so it will accept the sample information that relates to Alice and process the messageas 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 onlythe data and the sample information it needs to relay from Alice it could then just relay the digitalsignature 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 MessagesOMG 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 requiredensuring 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 todefine exactly what needs to be secured. Some applications may require only the data payload to beconfidential 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
    • To help clarify these requirements, this section explains the structure of the RTPS Message and thedifferent Submessages it may contain.An RTPS Message is composed of a leading RTPS Header followed by a variable number of RTPSSubmessages. Each RTPS Submessage itself composed of a Sub-message Header fol-lowed by a variable number of SubmessagElements. There are various kinds ofSubmessageElements to communicate thngs like sequence numbers, unique identifiers forDataReaders and DataWriters, SerializedKeys or KeyHash of the application data, source time-stamps, QoS, etc. There is one kind of SubmessageElement called SerializedData that isused to carry the data sent by DDS Applications.For the purpses of securing comminications we may distinguish three types of RTPSSubmessages: 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
    • 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 theSerializedData 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 differentDataWriter 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 differentDDS DomainParticipant entities this is done by preceding the set of RTPS Submessages thatoriginate from a common DomainParticipant with an InfoSource RTPS submessage.7.2.2 Secure RTPS MessagesSection 7.1.1 identified the Threats addressed by the DDS Security Specification. Ito protect againstthe “Authorized Subscription” threat it is necessary use encryption to protect the sensitive parts ofthe 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 informationon on other RTPS SubmessageElements (e.g. sequence numbers, KeyHash, and unique writer/readeridentifiers) 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 DataWriterit 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 theRTPS Message need to be encrypted and/or signed.The Message Transformation performed by the Security Plugins transforms an RTPS Message intoanother RTPS Message. The RTPS Header is preserved, however the remaining content in the14 DDS Security, Revised Submission
    • 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 ANDINCOMPLETE>7.2.3.1 RTPS Secure Submessage Elements7.2.3.1.1 CryptoTransformIdentifier7.2.3.1.2 SecuredData7.2.3.1.3 EncodedPayload7.2.3.2 RTPS Secure SubmessagesThis specification introduces a new RTPS Submessages that will be used to wrap other submessagessecuring 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 RTPSsubmessage elements.DDS Security, Revised Submission 15
    • 7.2.3.2.1 RTPS SecureSubMsg7.2.3.2.1.1 PurposeThis submessage is used to wrap one or more regular RTPS submessages in such a way that theircontents are secured via encryption, message authentication, and/or digital signatures.The Submessage conforms to the general structure of RTPS submessages and therefore can appearinside a well-formed RTPS message.7.2.3.2.1.2 ContentThe 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
    • multisubmsgFlag   SubmessageFlag   Indicates  the  submessage  contains  potentially  multi-­‐ ple  submessages  withincryptoTransformId   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  messagepayload   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  signatures7.2.3.2.1.3 ValidityThe Submessage is invalid if the submessageLength in the Submessage header is too small.7.2.3.2.1.4 Logical InterpretationThe 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 ANDINCOMPLETE>7.2.4.1 RTPS Secure Submessage Elements7.2.4.1.1 CryptoTransformIdentifier7.2.4.1.2 EncodedPayload7.2.4.1.3 SecuredData7.2.4.2 RTPS Secure Submessages7.2.4.2.1 SecureSubMsg7.2.4.2.1.1 Wire representation7.2.4.2.1.2 Submessage IdThe SecureSubMsg shall have the submesageId set to the value 0x30.DDS Security, Revised Submission 17
    • 7.2.4.2.1.3 Flags in the Submessage Header8 Plug-in ArchitectureThere are five plugin SPIs- Authentication, Access-Control, Cryptographic, Logging, and Data Tag-ging.18 DDS Security, Revised Submission
    • 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 InteractionsAuthentication Authenticate the principal that is The principal may be an applica-DDS Security, Revised Submission 19
    • 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 eventsData Tagging Add  a  data  tag  for  each  data  sample  8.1 Security ExceptionSecurityExceptionAttributescode SecurityExceptionCodemessage StringOperationsinit void exception SecurityExceptionget_message String exception SecurityExceptionget_code SecurityExceptionCode exception SecurityExceptionget_minor_code long exception SecurityException20 DDS Security, Revised Submission
    • SecurityException objects are potentially returned from many of the calls in the plugins. They areused 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: initThe 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_messageThe  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_codeThe  operation  returns  the  code  associated  with  the  exception.  8.1.4 Operation: get_minor_codeThe  operation  returns  a  plugin-­‐dependent  code  associated  with  the  exception.8.2 PropertyProperty is a data-type that holds a pair of strings. One is considered the property “name” and theother the property “value” associated that name. Property Sequences are used as a generic data-typeto 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 thevalue of the “name” attribute implementers shall use property names that start with a prefix to anICANN domain name they own, in reverse order. For example the prefix would be “com.acme.” forplugins 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.PropertyAttributesname Stringvalue StringDDS Security, Revised Submission 21
    • 8.3 CredentialCredentials provide a generic mechanism to pass information from DDS to the Security Plugins. Thisinformation is used to identify that application that is running and its permissions. The Credentialsdata-type provides a generic container for security credentials and certificates. The actual format andinterpretation of the credentials and how they are configured is specific to each implementation ofthe Security Plugins and shall be specified by each Security Plugin.Typical use of credentials would be signed certificates or signed permissions documents. Credentialsare only exchanged locally between the DDS implementation and the plugins linked to it and runningin 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.CredentialAttributescredential_classid Stringproperties Property[]value OctetSeqThere are several specializations of the Credential class. They all share the same format but are usedfor different purposes this is modeled by defining specialized classes.22 DDS Security, Revised Submission
    • 8.3.1 Attribute: credential_classidIdentifies 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 toidentify non-standard Credentials. In order to avoid collisions the credential_class_id they use shallstart with a prefix to an ICANN domain name they own, using the same rules specified in Section 8.2for property names.8.3.2 Attribute: propertiesTis attribute is a container for meta-data to be held in the Credential. The contents are specific toeach plugin implementation.8.3.3 Attribute: valueThis attribute is used to hold the data stored in the Credential. The contents are specific to eachplugin implementation.8.4 TokenTokens provide a generic mechanism to pass information between Security Plugins using DDS as thetransport. Token objects are meant for transmission over the network using DDS either embeddedwithin the BuiltinTopicData sent via discovery or alternatively via special Topics defines by thisspecification.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.TokenAttributestoken_classid Stringwrapper_classid Stringproperties Property[]value OctetSeqwrapped_value OctetSeqThere are multiple specializations of the Token class. They all share the same format but are used fordifferent purposes this is modeled by defining specialized classes.DDS Security, Revised Submission 23
    • 8.4.1 Attribute: token_classidIdentifies 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 prefixto an ICANN domain name they own, using the same rules specified in Section 8.2 for propertynames.8.4.2 Attribute: wrapper_classidIdentifies 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_classidthey use shall start with a prefix to an ICANN domain name they own, using the same rules specifiedin Section 8.2 for property names.8.4.3 Attribute: propertiesThis attribute provides a container for meta-data to be held in the Token. The contents are specific toeach plugin implementation.24 DDS Security, Revised Submission
    • 8.4.4 Attribute: valueThis attribute is used to hold the data stored in the token. The contents are specific to each pluginimplementation. The value attribute is intended to store data in ‘cleartext’. To store encrypted orsigned data the plugin implementation should use the wrapped_value attribute instead.8.4.5 Attribute: wrapped_valueThis attribute is used to hold the data stored in the token. The contents are specific to each pluginimplementation. The value attribute is intended to store ‘cryptographically protected’ data. The kindof protection (e.g. encryption and/or signature) is indicated by the value of the wrapper_classidattribute.8.5 DDS support for plugin message exchangeIn order to perform mutual authentication and key exchange between DDS Participants the securityplugins associated with those participants need to exchange messages.DDS already has a mechanism for message exchange between the Participants. Exposing some ofthese 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 DDSInteroperability Protocol).These endpoints were designed to be extensible and support the kind of message-exchanged neededby 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 originatingparticipant.The ‘kind’ attribute is used to identify of different types of messages. The actual data is carried onthe ‘value’ octet sequence. Its content and format is specified for each value of the ‘kind’ attribute.DDS Security, Revised Submission 25
    • 8.5.1 Reserved values of ParticipantMessageDataKindThis 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 ParticipantMessageDataEach value for the kind in ParticipantMessageData uses different schema to store data within thedata (octet sequence) attribute in the ParticipantMessageData.8.5.2.1 Data for message kind KIND_SECURITY_AUTH_HANDSHAKEIf ParticipantMessageData kind is KIND_SECURITY_AUTH_HANDSHAKE the data attributecontains 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_TOKENSIf ParticipantMessageData kind is KIND_SECURITY_PARTICIPANT_CRYPTO_TOKENS the data attribute contains the CDR big-endian serialization of thestructure ParticipantCryptoTokenSMsg defined by the IDL below:struct ParcicipantCryptoTokensMsg {26 DDS Security, Revised Submission
    • 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_TOKENSIf ParticipantMessageData kind is KIND_SECURITY_DATAWRITER_CRYPTO_TOKENS the data attribute contains the CDR big-endian serialization of thestructure 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_TOKENSIf ParticipantMessageData kind is KIND_SECURITY_DATAWRITER_CRYPTO_TOKENS the data attribute contains the CDR big-endian serialization of thestructure DatareaderCryptoTokensMsg defined by the IDL below:struct DatareaderCryptoTokensMsg { octet readerwriter_guid[16]; octet datawriter_guid[16]; sequence<CryptoToken> crypto_tokens;};8.6 Authentication Plug-inThe 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 DDSDomain 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 anauthentication protocol. A participant that enables the authentication plug-in will only communicateto another participant that has the authentication plug-in enabled.The plugin SPI is designed to support multiple implementations which may require varying numbersof message exchanges, which may be used to challenge the other side so it can determine it knowsthe secrets, associated with its credential, and potentially establish shared secrets, which can then beused to exchange session keys.DDS Security, Revised Submission 27
    • 8.6.2 Authentication Plug-in ModelThe Authentication Plug-in model is presented in the figure below.8.6.2.1 IdentityCredentialThis is a native type that represents the information that is passed from the DDS middleware to theplugin in order to prove identity of the application that contains the DomainParticipant. Thestructure and interpretation of the contents as well as the mechanism used to pass it to theAuthenticationPlugin shall be specified by each plugin implementation.28 DDS Security, Revised Submission
    • 8.6.2.2 IdentityTokenAn IdentityToken encodes the identity information for a DomainParticipant, in a mannerthat can be externalized and propagated via discovery.8.6.2.3 IdentityHandleAn IdentityHandle is an opaque local reference to internal state within theAuthenticationPlugin, 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 theidentity of a DomainParticipant and is used whenever a client of theAuthenticationPlugin needs to refer to the identity of a previously identifiedDomainParticipant.8.6.2.4 HandshakeHandleA HandshakeHandle is an opaque local reference used to refer to the internal state of a possiblemutual authentication or handshake protocol.8.6.2.5 MessageTokenA MessageToken encodes plugin-specific information that the Authentication plugins associatedwith two DomainParticipant entities exchange as part of the mutual authentication handshake. TheMessageToken are understood only by the AuthenticationPlugin implementations on ei-ther side of the handshake. The MessageToken are sent and received by the DDS implementationunder the direction of the AuthenticationPlugins.8.6.2.6 SharedSecretHandleA SharedSecretHandle is an opaque local reference to internal state within theAuthenticationPlugin containing a secret that is shared between theAuthenticationPlugin implementation and the peer AuthenticationPlugin implemen-tation associated with a remote DomainParticipant. It is understood only by the twoAuthenticationPlugin 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 twoDomainParticipants in a secure manner.8.6.2.7 AuthenticationThis interface is the starting point for all the security mechanisms. When a DomainParticipantis either locally created or discovered, it needs to be authenticated in order to be able to communicatein a DDS Domain.The interaction between the DDS implementation and the Authentication plugins has been designedin a flexible manner so it is possible to support various authentication mechanisms, including thoseDDS Security, Revised Submission 29
    • that require a handshake and/or perform mutual authentication between participants and establishes ashared secret. This interaction is described in the state machine illustrated in the figure below.AuthenticationNo AttributesOperationsvalidate_local_ident ValidationResult_tity out: IdentityHandle30 DDS Security, Revised Submission
    • local_identity_handle credential IdentityCredential participant_key Octet[16] exception SecurityExceptionget_identity_token IdentityToken handle IdentityHandle exception SecurityExceptionvalidate_remote_iden ValidationResult_ttity out: IdentityHandle remote_identity_handle local_identity_handle IdentityHandle remote_identity_token IdentityToken remote_participant_key Octet[16] exception SecurityExceptionbegin_handshake_requ ValidationResult_test out: handshake_handle HandshakeHandle out: handshake_message MessageToken initiator_identity_handl IdentityHandle e replier_identity_handle IdentityHandle exception SecurityExceptionbegin_handshake_repl ValidationResult_ty out: handshake_handle HandshakeHandle out: MessageToken handshake_message_out handshake_message_in MessageToken initiator_identity_handl IdentityHandle e replier_identity_handle IdentityHandle exception SecurityExceptionprocess_handshake ValidationResult_tDDS Security, Revised Submission 31
    • out: MessageToken handshake_message_out handshake_message_in MessageToken handshake_handle HandshakeHandle exception SecurityExceptionget_shared_secret SharedSecretHandle handshake_handle HandshakeHandle exception SecurityExceptionset_listener Boolean listener AuthenticationListen er exception SecurityExceptionreturn_token Boolean token IdentityToken exception SecurityExceptionreturn_handshake_han Booleandle handshake_handle HandshakeHandle exception SecurityExceptionreturn_identity_hand Booleanle identity_handle IdentityHandle exception SecurityExceptionreturn_sharedsecret_ Booleanhandle sharedsecret_handle SharedSecretßHandle exception SecurityException8.6.2.7.1 Type: ValidationResult_tEnumerates the possible return values of the validate_local_identity and validate_remote_identityoperations.ValidationResult_tVALIDATION_OK Indicates the validation has succeeded32 DDS Security, Revised Submission
    • VALIDATION_FAILED Indicates the validation has failedVALIDATION_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_identityValidates the identity of the local DomainParticipant, provided by anIdentityCredential. 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 aconfigurable delay to check the status of verification. This shall continue until the operation returnsDDS Security, Revised Submission 33
    • either VALIDATION_OK if the validation succeeds, or VALIDATION_FAILED. This approachallows 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 AuthenticatedParticipant 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 credentialis 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_identityInitiates the process of validating the identity of the discovered remote DomainParticipant,represented as an IdentityToken object. The operation returns the ValidationResult_tindicating 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 remoteDomainParticipant to the AuthenticationPlugin.If the validation can be performed solely with the information passed and it succeeds the operationshall return VALIDATION_OK. If it can be performed with the information passed and it fails itshall 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 validationprocess.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 identifiedby the remote_participant_key. This message is received on the BuiltinParticipantMessageReaderand 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 interpretthe bytes inside the ParticipantMessageData data sequence as the CDR serialization of aMessageToken and shall call the operation begin_handshake_reply passing the received34 DDS Security, Revised Submission
    • MessageToken and shall call the operation begin_handshake_reply passing the receivedMessageToken as the handshake_message_in.If an error occurs, this method shall throw an exception.Parameter remote_identity_token : A token received as part ofParticipantBuiltinTopicData representing the identity of the remoteDomainParticipant.Parameter local_identity_handle: A handle to the local DomainParticipant that is requestingthe remote participant to be validated. The local handle must have been obtained by an earlier call tovalidate_local_identity.Parameter (out) remote_identity_handle: A handle that can be used to locally refer to the remoteAuthenticated 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_requestThis operation is used to initiate a handshake when the first handshake message must be generated. Itshall 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 thestate of the handshake. It is passed to other operations in the PluginDDS Security, Revised Submission 35
    • 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_replyThis operation is used to initiate a handshake when an initial handshake message has been receivedfrom 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 matchingKIND_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 shallsend the handshake_message_out using the BuiltinParticipantMessageWrite to the participantidentified 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 thestate of the handshake. It is passed to other operations in the PluginParameter (out) handshake_message_out: A Token containing a message to be sent using theBuiltinParticipantMessageWriter. The contents shall be specified by each plugin implementation.36 DDS Security, Revised Submission
    • 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 handshakeresponse.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_handshakeThis operation is used to continue a handshake. It shall be called by the DDS middleware solely as aresult of having a previous call to begin_handshake_request returns or begin_handshake_reply thatreturned VALIDATION_PENDING_HANDSHAKE_MESSAGE and having also received a mes-sage on the BuiltinParticipantMessageReader with the participantGuidPrefix matching the GUIDprefix of the participant associated with the initiator_identity_handle and a kind matchingKIND_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 shallsend the handshake_message_out using the BuiltinParticipantMessageWriter to the participantidentified 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 theBuiltinParticipantMessageWriter. 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
    • Parameter handshake_handle: Handle returned by a corresponding previous call to be-gin_handshake_request or begin_handshake_reply.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 BuiltinParticipantMessageWriter and then wait for a reply message on the BuiltinPartici- pantMessageReader 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.7 Operation: get_shared_secretRetrieves the SharedSecretHandle resulting with a successfully completed handshake.This operation shall be called by the DDS middleware after on each HandshakeHandle after thehandshake that uses that handle completes successfully, that is the last ‘handshake’ operation calledon that handle (begin_handshake_request, begin_handshake_reply, orprocess_handshake) returns VALIDATION_OK or VALIDATION_OK_FINAL_MESSAGE.The retrieved SharedSecretHandle shall be used by the DDS middleware in conjunction withthe CryptoKeyExchange interface of the Cryptographic Plugin to exchange cryptographic keymaterial with other DomainParticipant entities.If an error occurs, this method shall return nil and/or throw and exception.Parameter handshake_handle: Handle returned by a corresponding previous call to be-gin_handshake_request or begin_handshake_reply, which has successfully completed the hand-shake operations.Parameter exception: A SecurityException object.8.6.2.7.8 Operation: get_identity_tokenRetrieves an IdentityToken used to represent on the network the identity of the Participantidentified by the specified IdentityHandle.Parameter handle: The handle used to locally identify the Participant for which an IdentityTo-ken is desired. The handle must have been returned by a successful call to validate_local_identity,otherwise the operation shall throw a SecurityException.Parameter exception: A SecurityException object.38 DDS Security, Revised Submission
    • Return: If an error occurs, this method shall return nil, otherwise it shall return theIdentityToken.8.6.2.7.9 Operation: set_listenerSets the AuthenticationListener that the AuthenticationPlugin will use to notify theDDS middleware infrastructure of events relevant to the Authentication of DDS Participants.If an error occurs, this method shall return false.Parameter listener: An AuthenticationListener object to be attached to theAuthentication object. If this argument is nil it indicates that there shall be no listener.Parameter exception: A SecurityException object, which provides details, in the case theoperation returns false.8.6.2.7.10 Operation: return_tokenReturns the IdentityToken object to the plugin so it can be disposed of.Parameter token: An IdentityToken issued by the plugin on a prior call to get_identity_token.Parameter exception: A SecurityException object, which provides details in the case thisoperation returns false.8.6.2.7.11 Operation: return_handshake_handleReturns the HandshakeHandle object to the plugin so it can be disposed of.Parameter handshake_handle: A HandshakeHandle issued by the plugin on a prior call to be-gin_hadshake_requst or begin_handshake_reply.Parameter exception: A SecurityException object, which provides details in the case thisoperation returns false.8.6.2.7.12 Operation: return_identity_handleReturns the IdentityHandle object to the plugin so it can be disposed of.Parameter identity_handle: An IdentityHandle issued by the plugin on a prior call to vali-date_local_identity or validate_remote_identity.Parameter exception: A SecurityException object, which provides details in the case thisoperation returns false.8.6.2.7.13 Operation: return_sharedsecret_handleReturns the SharedSecretHandle object to the plugin so it can be disposed of.Parameter sharedsecret_handle: An IdentityHandle issued by the plugin on a prior call toget_shared_secret.DDS Security, Revised Submission 39
    • Parameter exception: A SecurityException object, which provides details in the case thisoperation returns false.8.6.2.8 AuthenticationListenerThe AuthenticationListener provides the means for notifying the DDS middleware infra-structure of events relevant to the Authentication of DDS Participants. For example, identity certifi-cates can expire; hence, the AuthenticationListener is notified when a certificate has ex-pired and revokes the identity.AuthenticationListenerNo AttributesOperationson_revoke_identity Boolean plugin Authentication handle IdentityHandle exception SecurityException8.6.2.8.1 Operation: on_revoke_identityRevokes the identity of the participant identified by the IdentityHandle. The correspondingIdentity becomes invalid. As a result of this the DDS middleware shall terminate any communica-tions whose Authorization depends on that handle.If an error occurs, this method shall return false.Parameter plugin: An Authentication plugin object that has this listener allocated.Parameter handle: An IdentityHandle object that corresponds to the Identity of a DDS Par-ticipant whose identity is being revoked.8.7 Access Control Plug-InThe Access Control Plug-in API defines the types and operations necessary to support an access con-trol mechanism for DDS DomainParticipants.8.7.1 Background (Non-Normative)Once a DomainParticipantis authenticated, its access rights need to be validated and enforced.Often access rights are described using an access control matrix where the rows are subjects (i.e.,users) and the columns are objects (i.e. resources), and a cell defines the access right that a givensubject has over a resource. Typical implementations provide either a column centric view (i.e. ac-cess control lists) or a row centric view (i.e. set of capabilities stored with each subject). A row cen-40 DDS Security, Revised Submission
    • tric approach is provided by the use of certificates, for authorization in this case. With the proposedAccess Control Plug-in SPI both approaches can be supported.Before we can describe the access control plug-in SPI, we first need to define the access rights thatcan be attached to a DomainParticipant. Every DDS application uses aDomainParticipant to access or produce information on a Domain; hence theDomainParticipant has to be allowed to run in a certain Domain. Moreover, aDomainParticipant is responsible for creating DataReaders and DataWriters thatcommunicate over a certain Topic. Hence, a DomainParticipant has to have the right to cre-ate a Topic, to publish through its DataWriters certain Topics and to subscribe through itsDataReaders to certain Topics. There is a very strong relationship between the access controlplug-in and the Cryptographic plug-in because encryption keys need to be generated forDataWriters based on the DomainParticipant’s access rights.8.7.2 Access Control Plug-in ModelThe Access Control Plug-in model is presented in the figure below.DDS Security, Revised Submission 41
    • 8.7.2.1 PermissionsCredentialThis is a native type that represents the information that is passed from the DDS middleware to theplugin in order to prove the permissions the participant has. The structure and interpretation of the42 DDS Security, Revised Submission
    • contents as well as the mechanism used to pass it to the AccessControlPlugin shall be speci-fied by each plugin implementation.8.7.2.2 PermissionsTokenA PermissionsToken encodes the permissions information for a DomainParticipant, in amanner that can be externalized and propagated via discovery. Moreover, it optionally contains theDataTag label that the DomainParticipant is allowed to attach to the data.8.7.2.3 PermissionsHandleA PermissionsHandle is an opaque local reference to internal state within theAccessControlPlugin. It is understood only by the AccessControlPlugin and charac-terizes the permissions associated with a specific DomainParticipant. This object is returnedby the AccessControlPlugin as part of the validation of the permissions of aDomainParticipant and is used whenever a client of the AccessControlPlugin needs torefer to the permissions of a previously validated DomainParticipant.DDS Security, Revised Submission 43
    • 8.7.2.4 AccessControl interfaceAccessControlNo AttributesOperationscheck_create_partici Booleanpant permissions_hand PermissionsHandle le domain_id DomainId_t property PropertyQoSPolicy qos DomainParticipantQoS exception SecurityExceptioncheck_create_datawri Booleanter permissions_hand PermissionsHandle le domain_id DomainId_t topic_name String property PropertyQoSPolicy qos DataWriterQoS data_tag DataTag exception SecurityExceptioncheck_create_datarea Booleander permissions_hand PermissionsHandle le domain_id DomainId_t topic_name String property PropertyQoSPolicy qos DataReaderQoS data_tag DataTag exception SecurityExceptioncheck_create_topic Boolean permissions_hand PermissionsHandle44 DDS Security, Revised Submission
    • permissions_hand PermissionsHandle le domain_id DomainId_t topic_name String property PropertyQoSPolicy qos TopicQoS exception SecurityExceptioncheck_local_datawrit Booleaner_register_instance permissions_hand PermissionsHandle le writer DataWriter key DynamicData exception SecurityExceptioncheck_local_datawrit Booleaner_dispose_instance permissions_hand PermissionsHandle le writer DataWriter key DynamicData exception SecurityExceptioncheck_remote_partici Booleanpant permissions_hand PermissionsHandle le domain_id DomainId_t participant_data ParticipantBuiltinTopicDa ta exception SecurityExceptioncheck_remote_datawri Booleanter permissions_hand PermissionsHandle le publication_data PublicationBuiltinTopicDa ta data_tag DataTag exception SecurityExceptionDDS Security, Revised Submission 45
    • check_remote_datarea Booleander permissions_hand PermissionsHandle le subscription_dat SubscriptionBuiltinTopicD a ata data_tag DataTag exception SecurityExceptioncheck_remote_topic Boolean permissions_hand PermissionsHandle le topic_data TopicBuiltinTopicData exception SecurityExceptioncheck_remote_datawri Booleanter_register_instance permissions_hand PermissionsHandle le reader DataReader publication_hand InstanceHandle_t le key DynamicData instance_handle InstanceHandle_t exception SecurityExceptioncheck_remote_datawri Booleanter_dispose_instance permissions_hand PermissionsHandle le reader DataReader publication_hand InstanceHandle_t le key DynamicData exception SecurityExceptionget_permissions_toke PermissionsTokenn handle PermissionsHandle exception SecurityException46 DDS Security, Revised Submission
    • set_listener Boolean listener AccessControlListener exception SecurityExceptionreturn_permissions_t Booleanoken token PermissionsTokenvalidate_local_permi PermissionsHandlessions auth_plugin AuthenticationPlugin identity IdentityHandle credential PermissionsCredential exception SecurityExceptionvalidate_remote_perm PermissionsHandleissions auth_plugin AuthenticationPlugin local_identity_h IdentityHandle andle remote_identity_ IdentityHandle handle remote_permissio PermissionsToken ns_token exception SecurityException8.7.2.4.1 Operation: validate_local_permissionsValidates the permissions of the local DomainParticipant, provided the PermissionsCre-dential. The operation returns a PermissionsHandle object, if successful. The Permis-sionsHandle can be used to locally identify the permissions of the local DomainParticipantto the AccessControlPlugin.If an error occurs, this method shall return nil.Parameter auth_plugin: The Authentication plug-in, which validated the identity of the localDomainParticipant. If this argument is nil, the operation shall return nil.Parameter identity: The IdentityHandle returned by the authentication plug-in from a suc-cessful call to validate_local_identity.Parameter credential: A credential that can be used to validate the permissions of the localDomainParticipant. The nature of the credential is specific to each AccessControl pluginimplementation.DDS Security, Revised Submission 47
    • Parameter exception: A SecurityException object, which provides details, in case this operationreturns nil.8.7.2.4.2 Operation: validate_remote_permissionsValidates the permissions of the remote DomainParticipant, propagated as aPermissionsToken object. The operation returns a PermissionsHandle object, if success-ful.If an error occurs, this method shall return nil.Parameter auth_plugin: The Authentication plug-in, which validated the identity of theremote DomainParticipant. If this argument is nil, the operation shall return nil.Parameter local_identity_handle: The IdentityHandle returned by the authentication plug-in.Parameter remote_identity_handle: The IdentityHandle returned by a successful call to thevalidate_remote_identity operation on the AuthenticationPlugin.Parameter remote_permissions_token: The permissions of the remote DomainParticipant. Ifthis argument is nil, the operation shall return nil.Parameter exception: A SecurityException object, which provides details, in case this opera-tion returns nil.8.7.2.4.3 Operation: check_create_participantEnforces the permissions of the local DomainParticipant. When the localDomainParticipant is created, its permissions must allow it to join the DDS Domain specifiedby the domain_id. Optionally the use of the specified value for the DomainParticipantQoS also hasto be allowed by its permissions. The operation returns a Boolean value.If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the localDomainParticipant. If this argument is nil, the operation shall return false.Parameter domain_id: The domain id where the local DomainParticipant is about to becreated. If this argument is nil, the operation shall return false.Parameter property: The QoS properties of the local DomainParticipant (name/values pairsthat can be used to configure certain parameters and are not exposed through formal QoS policies). Ifthis argument is nil, the operation shall return false.Parameter qos: The QoS policies of the local DomainParticipant. If this argument is nil, theoperation shall return false.Parameter exception: A SecurityException object, which provides details, in case this opera-tion returns false.48 DDS Security, Revised Submission
    • 8.7.2.4.4 Operation: check_create_datawriterEnforces the permissions of the local DomainParticipant. When the localDomainParticipant creates a DataWriter for topic_name with the specifiedDataWriterQos associated with the data_tag, its permissions have to allow this. The opera-tion returns a Boolean object.If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the localDomainParticipant. If this argument is nil, the operation shall return false.Parameter topic_name: The topic name that the DataWriter is supposed to write. If this argu-ment is nil, the operation shall return false.Parameter property: The QoS properties of the local DataWriter (name/values pairs that canbe used to configure certain parameters and are not exposed through formal QoS policies). If this ar-gument is nil, the operation shall return false.Parameter qos: The QoS policies of the local DataWriter. If this argument is nil, the operationshall return false.Parameter data_tag: The data tag that the local DataWriter is about to associate with its data.This argument can be nil if it is not considered for access control.Parameter exception: A SecurityException object, which provides details, in case this operationreturns false.8.7.2.4.5 Operation: check_create_datareaderEnforces the permissions of the local DomainParticipant. When the localDomainParticipant creates a DataReader for a Topic for topic_name with the specifiedDataReaderQos qos associated with the data_tag, its permissions have to allow this. The op-eration returns a Boolean value.If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the localDomainParticipant. If this argument is nil, the operation shall return false.Parameter topic_name: The topic name that the DataReader is supposed to read. If this argu-ment is nil, the operation shall return false.Parameter property: The QoS properties of the local DataReader (name/values pairs that canbe used to configure certain parameters and are not exposed through formal QoS policies). If this ar-gument is nil, the operation shall return false.Parameter qos: The QoS policies of the local DataReader. If this argument is nil, the operationshall return false.DDS Security, Revised Submission 49
    • Parameter data_tag: The data tag that the local DataReader is about to read. This argumentcan be nil if it is not considered for access control.Parameter exception: A SecurityException object, which provides details, in case this opera-tion returns false.8.7.2.4.6 Operation: check_create_topicEnforces the permissions of the local DomainParticipant. When an entity of the localDomainParticipant creates a Topic with topic_name, with the specified TopicQos qosassociated its permissions have to allow this. The operation returns a Boolean value.If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the localDomainParticipant. If this argument is nil, the operation shall return false.Parameter topic_name: The topic name to be created. If this argument is nil, the operation shallreturn false.Parameter property: The QoS properties of the Topic (name/values pairs that can be used to con-figure certain parameters and are not exposed through formal QoS policies). If this argument is nil,the operation shall return false.Parameter qos: The QoS policies of the local Topic. If this argument is nil, the operation shallreturn false.Parameter exception: A SecurityException object, which provides details, in case this opera-tion returns false.8.7.2.4.7 Operation: check_local_datawriter_register_instanceEnforces the permissions of the local DomainParticipant. In case the access control requires afiner granularity at the instance level, this operation enforces the permissions of the localDataWriter. The key identifies the instance being registered and the permissions are checked todetermine if registration of the specified instance is allowed. The operation returns a Booleanvalue.If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the localDomainParticipant. If this argument is nil, the operation shall return false.Parameter writer: DataWriter object that registers the instance. If this argument is nil, the op-eration shall return false.Parameter key: The key of the instance that for which the registration permissions are beingchecked. If this argument is nil, the operation shall return false.Parameter exception: A SecurityException object, which provides details, in case this op-eration returns false.50 DDS Security, Revised Submission
    • 8.7.2.4.8 Operation: check_local_datawriter_dispose_instanceEnforces the permissions of the local DomainParticipant. In case the access control requires afiner granularity at the instance level, this operation enforces the permissions of the localDataWriter. The key has to match the permissions for disposing an instance. The operation re-turns a Boolean object.If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the localDomainParticipant. If this argument is nil, the operation shall return false.Parameter writer: DataWriter object that registers the instance. If this argument is nil, the op-eration shall return false.Parameter key: The key identifies the instance being registered and the permissions are checked todetermine if disposal of the specified instance is allowed. If this argument is nil, the operation shallreturn false.Parameter exception: A SecurityException object, which provides details, in case this op-eration returns nil.8.7.2.4.9 Operation: check_remote_participantEnforces the permissions of the remote DomainParticipant. When the remoteDomainParticipant is discovered, the domain_id and optionally the DomainParticipantQoS arechecked to verify that joining that DDS Domain and using that QoS is allowed by its permissions.The operation returns a Boolean result.If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the remoteDomainParticipant. If this argument is nil, the operation shall return false.Parameter domain_id: The domain id where the remote DomainParticipant is about to becreated. If this argument is nil, the operation shall return false.Parameter participant_data: The ParticipantBuiltInTopicData object associated to theremote DomainParticipant. If this argument is nil, the operation shall return false.Parameter exception: A SecurityException object, which provides details, in case this opera-tion returns nil.8.7.2.4.10 Operation: check_remote_datawriterEnforces the permissions of the remote DomainParticipant. When the remoteDomainParticipant publishes data on a certain topic, the topic_name and optionally theDataWriterQoS extracted from the publication_data are verified to ensure that the remoteDataWriter’s permissions allow it to publish the DDS Topic using the specified Qos. The operationreturns a Boolean value.DDS Security, Revised Submission 51
    • If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the remoteDomainParticipant. If this argument is nil, the operation shall return false.Parameter publication_data: The PublicationBuiltInTopicData object associated with the remoteDataWriter. If this argument is nil, the operation shall return false.Parameter data_tag: The data tag that the remote DataWriter associates with its data. This ar-gument can be nil if it is not considered for access control.Parameter exception: A SecurityException object, which provides details, in case this opera-tion returns false.8.7.2.4.11 Operation: check_remote_datareaderEnforces the permissions of the remote DomainParticipant. When the remoteDomainParticipant subscribes to a certain DDS Topic, the topic_name and optionally theDataReaderQoS extracted from the subscription_data are verified to ensure that the remoteDataReader’s permissions allow it to subscribe to the DDS Topic using the specifiedDataReaderQos. The operation returns a Boolean value.If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the localDomainParticipant. If this argument is nil, the operation shall return false.Parameter subscription_data: The SubscriptionBuiltInTopicData object associated with the remoteDataReader. If this argument is nil, the operation shall return false.Parameter data_tag: The data tag that the remote DataReader is about to read. This argumentcan be nil if it is not considered for access control.Parameter exception: A SecurityException object, which provides details, in case this operationreturns false.8.7.2.4.12 Operation: check_remote_topicEnforces the permissions of the remote DomainParticipant. When the remoteDomainParticipant creates a certain topic, the topic_name and optionally the TopicQoS ex-tracted from the topic_data are verified to ensure the remote DomainParticipant permissionsallow it to create the DDS Topic with the specified QoS. The operation returns a Boolean value.If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the remoteDomainParticipant. If this argument is nil, the operation shall return false.Parameter topic_data: The TopicBuiltInTopicData object associated with the Topic. If this ar-gument is nil, the operation shall return false.52 DDS Security, Revised Submission
    • Parameter exception: A SecurityException object, which provides details, in case this opera-tion returns false.8.7.2.4.13 Operation: check_remote_datawriter_register_instanceEnforces the permissions of the remote DomainParticipant. In case the access control requiresa finer granularity at the instance level, this operation enforces the permissions of the remoteDataWriter. The key has to match the permissions for registering an instance. The operation re-turns a Boolean value.If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the remoteDomainParticipant. If this argument is nil, the operation shall return false.Parameter reader: The local DataReader object that is matched to the remote Publicationthat registered an instance.Parameter publication handle: Handle that identifies the remote Publication.Parameter key: The key of the instance that needs to match the permissions for registering an in-stance. If this argument is nil, the operation shall return false.Parameter exception: A SecurityException object, which provides details, in case this op-eration returns false.8.7.2.4.14 Operation: check_remote_datawriter_dispose_instanceEnforces the permissions of the remote DomainParticipant. In case the access control requiresa finer granularity at the instance level, this operation enforces the permissions of the remoteDataWriter. The key has to match the permissions for disposing an instance. The operation re-turns a Boolean value.If an error occurs, this method shall return false.Parameter permissions_handle: The PermissionsHandle object associated with the remoteDomainParticipant. If this argument is nil, the operation shall return false.Parameter reader: The local DataReader object that is matched to the Publication that disposedan instance.Parameter publication handle: Handle that identifies the remote Publication.Parameter key: The key of the instance that needs to match the permissions for disposing an in-stance. If this argument is nil, the operation shall return false.Parameter exception: A SecurityException object, which provides details, in case this op-eration returns false.DDS Security, Revised Submission 53
    • 8.7.2.4.15 Operation: get_permissions_tokenRetrieves a PermissionsToken object that can be used to represent on the network theDomainParticipant’s permissions, which are identified by the specified PermissionsHandle.If an error occurs, this method shall return nil.Parameter handle: The handle used to locally identify the permissions of the DomainParticipant forwhich a PermissionsToken is desired. If this argument is nil, the operation shall return nil.Parameter exception: A SecurityException object, which provides details, in case this op-eration returns nil.8.7.2.4.16 Operation: set_listenerSets the listener for the AccessControl object.If an error occurs, this method shall return false.Parameter listener: An AccessControlListener object to be attached to theAccessControl object. If this argument is nil, the operation returns false.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.7.2.4.17 Operation: return_permissions_tokenReturns the PermissionsToken to the plugin for disposal.Parameter token: A PermissionsToken to be disposed of.8.7.2.5 AccessControlListener interfaceThe purpose of the AccessControlListener is to be notified of all status changes for differentidentities. For example, permissions can change; hence, the AccessControlListener is noti-fied and enforces the new permissions.AccessControlListenerNo AttributesOperationson_revoke_permissions Boolean plugin AccessControl handle PermissionsHandle54 DDS Security, Revised Submission
    • 8.7.2.5.1 Operation: on_revoke_permissionsDomainParticipants’ Permissions can be revoked/changed. This listener provides a callbackfor permission revocation/changes.If an error occurs, this method shall return false.Parameter plugin: The correspondent AccessControl object.Parameter handle: A PermissionsHandle object that corresponds to the Permissions of a DDSParticipant whose permissions are being revoked.DDS Security, Revised Submission 55
    • 8.8 Cryptographic Plug-inThe Cryptographic Operations Plug-in API defines the types and operations necessary to support en-cryption, digest, message authentication codes, authentication, and key exchange for DDSDataWriters and DDS DataReaders.Users of DDS may have specific cryptographic libraries they use for encryption as well as specificrequirements regarding the algorithms for digests, message authentication, and signing. In additionapplications may require having only some of those functions performed, or performed only for cer-tain Topics and not for others. Therefore the plug-in API has to be general enough to allow flexibleconfiguration and deployment scenarios.8.8.1 Cryptographic Plug-in ModelThe Cryptographic Plug-in model is presented in the figure below. It combines related cryptographicinterfaces for key creation, key exchange, encryption, message authentication, hashing and signature.56 DDS Security, Revised Submission
    • 8.8.1.1 CryptoTokenThis class represents a generic holder for key material. A CryptoToken object contains all theinformation necessary to construct a set of keys to be used to encrypt and/or sign plain text trans-forming it into cipher-text.The format and interpretation of the CryptoToken depends on the implementation of the plugin.Each plugin implementation shall fully define it such that applications are able to interoperate. Ingeneral the CryptoToken will contain one or more keys and any other necessary material to per-form the crypto-transformation and/or verification, such as, initialization vectors (IVs), salts, etc.8.8.1.2 ParticipantCryptoHandleThe ParticipantCryptoHandle object is an opaque local reference that represents the KeyMaterial that is used to encrypt and sign whole RTPS Messages. It is used by the operationsencode_rtps_message and decode_rtps_message.8.8.1.3 DatawriterCryptoHandleThe DatawriterCryptoHandle object is an opaque local reference that represents the Key Ma-terial that is used to encrypt and sign RTPS Subsessage submessages sent from a DataWriter.This includes the RTPS submessages Data, DataFrag, Gap, Heatbeat, and HearbeatFrag,as well as the SerializedData submessage element that appears in the Data and DataFragsubmessages.It is used by the operations encode_datawriter_submessage,decode_datawriter_submessage, encode_serialized_data, anddecode_serialized_data.8.8.1.4 DatareaderCryptoHandleThe DatareaderCryptoHandle object is an opaque local reference that represents the Key Ma-terial that is used to encrypt and sign RTPS Submessages sent from a DataReader. This in-cludes the RTPS Submessages AckNack and NackFrag.It is used by the operations encode_datareader_submessage,decode_datareader_submessage.8.8.1.5 CryptoTransformIdentifierThe CryptoTranformIdentifier object used to uniquely identify the transformation appliedon the sending side (encoding) so that the receiver can locate the necessary key material to performthe inverse transformation (decoding). The generation of CryptoTranformIdentifier is per-formed by the Cryptographic plugin.To enable interoperability and avoid mis-interpretation of the key material the structure of theCryptoTranformIdentifier is defined for all Cryptographic plugin implementations.DDS Security, Revised Submission 57
    • CryptoTransformIdentifierAttributestransformation_kind_id octet[4]transformation_key_id octet[8]8.8.2 Attribute: transformation_kind_idUniquely identifies the type of transformation.  Values of transformation_kind_id having the first two octets set to zero are reserved by thisspecification, including future versions of this specification.Implementers can use the transformation_kind_id attribute to identify non-standard Trans-formation Kinds. In order to avoid collisions the first two octets in thetransformation_kind_id shall be set to a registered RTPS VendorId [28]. The RTPSVendorId used shall either be one reserved to the implementer of the Cryptographic Plugin, or elsethe implementer of the Cryptographic Plugin shall secure permission from the registered owner ofthe RTPS VendorId to use it.8.8.3 Attribute: transformation_key_idUniquely identifies the key material used to perform a cryptographic transformation within the scopeof all transformations that could be performed by transformations belonging to thattransformation_kind_id.In combination with the transformation_kind_id the transformation_key_id attrib-ute allows the receiver to select the proper key material to decrypt/verify a message that has beenencrypted and/or signed. The use of this attribute allows a receiver to be robust to dynamic changesin keys and key material in the sense that it can identify the correct key or at least detect that it doesnot have the necessary keys and key material.The values of the transformation_key_id are defined by the Cryptographic plugin imple-mentation and only understood by it.8.8.3.1 CryptoKeyFactory interfaceThis interface groups the operations related to the creation of keys used for encryption and digitalsigning of both the data written by DDS applications and the RTPS submessage and message headersused to do discovery and distribute the DDS data.CryptoKeyFactoryNo AttributesOperations58 DDS Security, Revised Submission
    • register_local_parti ParticipantCryptoHandlecipant participant_iden IdentityHandle tity participant_perm PermissionsHandle issions participant_prop PropertyQos erties exception SecurityExceptionregister_matched_rem ParticipantCryptoHandleote_participant local_participan ParticipantCryptoHandle t_crypto_handle remote_participa IdentityHandle nt_identity remote_participa PermissionsHandle nt_permissions shared_secret SharedSecretHandle exception SecurityExceptionregister_local_dataw DatawriterCryptoHandleriter participant_iden IdentityHandle tity participant_perm PermissionsHandle issions datawriter_prope PropertyQos rties exception SecurityExceptionregister_matched_rem DatareaderCryptoHandleote_datareader local_datawriter DatawriterCryptoHandle t_crypto_handle remote_participa IdentityHandle nt_identity remote_participa PermissionsHandle nt_permissions shared_secret SharedSecretHandle exception SecurityExceptionDDS Security, Revised Submission 59
    • register_local_datar DatareaderCryptoHandleeader participant_iden IdentityHandle tity participant_perm PermissionsHandle issions datareader_prope PropertyQos rties exception SecurityExceptionregister_matched_rem DatawriterCryptoHandleote_datawriter local_datareader DatareaderCryptoHandle _crypto_handle remote_participa IdentityHandle nt_identity remote_participa PermissionsHandle nt_permissions shared_secret SharedSecretHandle exception SecurityExceptionunregister_participa Booleannt participant_cryp ParticipantCryptoHandle to_handle exception SecurityExceptionunregister_datawrite Booleanr datawriter_crypt DatawriterCryptoHandle o_handle exception SecurityExceptionunregister_datareade Booleanr datareader_crypt DatareaderCryptoHandle o_handle exception SecurityException8.8.3.1.1 . Operation: register_local_participant60 DDS Security, Revised Submission
    • Registers a local DomainParticipant with the Cryptographic Plugin. The DomainParticipant musthave been already Authenticated and granted Access to the DDS Domain. The operation shall createany necessary key material that is needed to Encrypt and Sign secure messages that are directed toother DDS DomainParticipant entities on the DDS Domain.Parameter participant_identity: An IdentityHandle returned by a prior call tovalidate_local_identity. If this argument is nil, the operation returns nil.Parameter participant_permissions: A PermissionsHandle returned by a prior call tovalidate_local_permissions. If this argument is nil, the operation returns nilParameter participant_property: The QoS properties of the local DomainParticipant(name/values pairs that can be used to configure certain parameters and are not exposed throughformal QoS policies).Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns nil.8.8.3.1.2 Operation: register_matched_remote_participantRegisters a remote DomainParticipant with the Cryptographic Plugin. The remote DomainParticipantmust have been already Authenticated and granted Access to the DDS Domain. The operation per-forms two functions: a) It shall create any necessary key material needed to Decrypt and verify the signatures of mes- sages received from that remote DomainParticipant that are directed to the local DomainPar- ticipant. b) It shall create any necessary key material that will be used by the local DomainParticipant when encrypting or signing messages that are indented only for that remote DomainPartici- pant.Parameter local_participant_crypto_handle: A ParticipantCryptoHandle returned by aprior call to register_local_participant. If this argument is nil, the operation returnsnil.Parameter remote_participant_identity: An IdentityHandle returned by a prior call tovalidate_remote_identity. If this argument is nil, the operation returns nil.Parameter participant_permissions: A PermissionsHandle returned by a prior call tovalidate_remote_permissions. If this argument is nil, the operation returns nilParameter shared_secret: The SharedSecretHandle returned by a prior call toget_shared_secret as a result of the successful completion of the Authentication handshakebetween the local and remote DomainParticipant entities.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns nil.DDS Security, Revised Submission 61
    • 8.8.3.1.3 Operation: register_local_datawriterRegisters a local DataWriter with the Cryptographic Plugin. The fact that the DataWriterwas successfully created indicates that the DomainParticipant to which it belongs was authenticated,granted access to the DDS Domain, and granted permission to create the DataWriter on itsTopic.This operation shall create the cryptographic material necessary to encrypt and/or sign the data writ-ten by the DataWriter and returns a DatawriterCryptoHandle to be used for any crypto-graphic operations affecting messages sent or received by the DataWriter.If an error occurs, this method shall return nil. If it succeeds the operation shall return an opaquehandle that can be used to refer to that key material.Parameter local_participant_identity: An IdentityHandle returned by a prior call tovalidate_local_identity. It shall correspond to the DomainParticipant to which theDataWriter belongs. If this argument is nil, the operation returns nil.Parameter local_participant_permissions: A PermissionsHandle returned by a prior call tovalidate_local_permissions. It shall correspond to the DomainParticipant to whichthe DataWriter belongs. If this argument is nil, the operation returns nilParameter local_datawriter_properties: The PropertyQoS policy of the local DataWriter(name/values pairs that can be used to configure certain parameters and are not exposed throughformal QoS policies). This parameter shall contain all the properties in the DataWriter whosename has the prefix “dds.security.crypto.” The purpose of this parameter is to allow configuration ofthe Cryptographic Plugin by the DataWriter, for example selection of the cryptographic algo-rithm, key size, or even setting of the key. The use of this parameter depends on the particular im-plementation of the plugin and shall be specified for each implementation.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns nil.8.8.3.1.4 Operation: register_matched_remote_datareaderRegisters a remote DataReader with the Cryptographic Plugin. The remote DataReader shallcorrespond to one that has been granted permissions to match with the local DataWriter.This operation shall create the cryptographic material necessary to encrypt and/or sign the RTPSsubmessages (Data, DataFrag, Gap, Heartbeat, HeartbeatFrag) sent from the localDataWriter to that DataReader. It shall also create the cryptographic material necessary toprocess the RTPS Submessages (AckNack, NackFrag) sent from the remote DataReader to theDataWriter.Parameter local_datawriter_crypto_handle: A DatawriterCryptoHandle returned by aprior call to register_local_datawriter. If this argument is nil, the operation returnsnil.62 DDS Security, Revised Submission
    • Parameter remote_participant_identity: An IdentityHandle returned by a prior call tovalidate_remote_identity. It shall correspond to the DomainParticipant to which theremote DataReader belongs. If this argument is nil, the operation returns nil.Parameter remote_participant_permissions: A PermissionsHandle returned by a prior callto validate_remote_permissions. It shall correspond to the DomainParticipant towhich the DataReader belongs. If this argument is nil, the operation returns nilParameter shared_secret: The SharedSecretHandle returned by a prior call toget_shared_secret as a result of the successful completion of the Authentication handshakebetween the local and remote DomainParticipant entities.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns nil.8.8.3.1.5 Operation: register_local_datareaderRegisters a local DataReader with the Cryptographic Plugin. The fact that the DataReaderwas successfully created indicates that the DomainParticipant to which it belongs was authenticated,granted access to the DDS Domain, and granted permission to create the DataReader on itsTopic.This operation shall create the cryptographic material necessary to encrypt and/or sign the messagessent by the DataReader when the encryption/signature is independent of the targeted DataWriter.If successful the operation returns a DatareaderCryptoHandle to be used for any crypto-graphic operations affecting messages sent or received by the DataWriter.Parameter local_participant_identity: An IdentityHandle returned by a prior call tovalidate_local_identity. It shall correspond to the DomainParticipant to which theDataReader belongs. If this argument is nil, the operation returns nil.Parameter local_participant_permissions: A PermissionsHandle returned by a prior call tovalidate_local_permissions. It shall correspond to the DomainParticipant to whichthe DataReader belongs. If this argument is nil, the operation returns nilParameter local_datareader_properties: The PropertyQoS policy of the local DataReader(name/values pairs that can be used to configure certain parameters and are not exposed throughformal QoS policies).Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns nil.8.8.3.1.6 Operation: register_matched_remote_datawriterRegisters a remote DataWriter with the Cryptographic Plugin. The remote DataWritershall correspond to one that has been granted permissions to match with the local DataReader.This operation shall create the cryptographic material necessary to decrypt and/or verify the signa-tures of the RTPS submessages (Data, DataFrag, Heartbeat, HeartbeatFrag, Gap) sentDDS Security, Revised Submission 63
    • from the remote DataWriter to the DataReader. The operation shall also create the crypto-graphic material necessary to encrypt and/or sign the RTPS submessages (AckNack, NackFrag)sent from the local DataReader to the remote DataWriter.Parameter local_datawriter_crypto_handle: A DatawriterCryptoHandle returned by aprior call to register_local_datawriter. If this argument is nil, the operation returnsnil.Parameter remote_participant_identity: An IdentityHandle returned by a prior call tovalidate_remote_identity. It shall correspond to the DomainParticipant to which theremote DataWriter belongs. If this argument is nil, the operation returns nil.Parameter remote_participant_permissions: A PermissionsHandle returned by a prior callto validate_remote_permissions. It shall correspond to the DomainParticipant towhich the DataWriter belongs. If this argument is nil, the operation returns nilParameter shared_secret: The SharedSecretHandle returned by a prior call toget_shared_secret as a result of the successful completion of the Authentication handshakebetween the local and remote DomainParticipant entities.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns nil.8.8.3.1.7 Operation: unregister_participantReleases the resources that the Cryptographic plugin maintains associated with a DomainParticipant.After calling this function the DDS Implementation shall not use theparticipant_crypto_handle anymore.The DDS Implementation shall call this function when it determines that there will be no furthercommunication with the DDS DomainParticipant associated with theparticipant_crypto_handle. Specifically it shall be called when the application deletes alocal DomainParticipant and also when the DDS Discovery mechanism detects that a matched Do-mainParticipant is no longer in the system.Parameter participant_crypto_handle: A ParticipantCryptoHandle returned by a priorcall to register_local_participant, orregister_matched_remote_participant if this argument is nil, the operation returnsfalse.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.1.8 Operation: unregister_datawriterReleases the resources that the Cryptographic plugin maintains associated with a DataWriter. Aftercalling this function the DDS Implementation shall not use the datawriter_crypto_handleanymore.64 DDS Security, Revised Submission
    • The DDS Implementation shall call this function when it determines that there will be no furthercommunication with the DDS DataWriter associated with the datawriter_crypto_handle.Specifically it shall be called when the application deletes a local DataWriter and also when the DDSDiscovery mechanism detects that a matched DataWriter is no longer in the system.Parameter datawriter_crypto_handle: A ParticipantCryptoHandle returned by a prior callto register_local_datawriter, or register_matched_remote_datawriter if thisargument is nil, the operation returns false.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.1.9 Operation: unregister_datareaderReleases the resources that the Cryptographic plugin maintains associated with a DataReader. Aftercalling this function the DDS Implementation shall not use the datareader_crypto_handleanymore.The DDS Implementation shall call this function when it determines that there will be no furthercommunication with the DDS DataReader associated with the datareader_crypto_handle.Specifically it shall be called when the application deletes a local DataReader and also when theDDS Discovery mechanism detects that a matched DataReader is no longer in the system.Parameter datareader_crypto_handle: A ParticipantCryptoHandle returned by a priorcall to register_local_datareader, or register_matched_remote_datareader ifthis argument is nil, the operation returns false.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.2 CryptoKeyExchange InterfaceThe key exchange interface manages the creation of keys and assist in the secure distribution of keysand key material.CryptoKeyExchangeNo AttributesOperationscreate_local_partici CryptoToken[]pant_crypto_tokens local_participan ParticipantCryptoHandle t_crypto remote_participa ParticipantCryptoHandle nt_crypto exception SecurityExceptionset_remote_participa Booleannt_crypto_tokensDDS Security, Revised Submission 65
    • set_remote_participa Booleannt_crypto_tokens local_participan ParticipantCryptoHandle t_crypto remote_participa ParticipantCryptoHandle nt_crypto remote_participa CryptoToken[] nt_tokens exception SecurityExceptioncreate_local_datawri CryptoToken[]ter_crypto_tokens local_datawriter DatawriterCryptoHandle _crypto remote_datareade DatareaderCryptoHandle r_crypto exception SecurityExceptionset_remote_datawrite Booleanr_crypto_tokens local_datareader DatareaderCryptoHandle _crypto remote_datawrite DatawriterCryptoHandle r_crypto remote_datawrite CryptoToken[] r_tokens exception SecurityExceptioncreate_local_datarea CryptoToken[]der_crypto_tokens local_datareader DatareaderCryptoHandle _crypto remote_datawrite DatawriterCryptoHandle r_crypto exception SecurityExceptionset_remote_datareade Booleanr_crypto_tokens local_datawriter DatawriterCryptoHandle _crypto remote_datareade DatareaderCryptoHandle r_crypto remote_datawrite CryptoToken[] r_tokens66 DDS Security, Revised Submission
    • exception SecurityExceptionreturn_crypto_tokens Boolean crypto_tokens CryptoToken[] exception SecurityException8.8.3.2.1 Operation: create_local_participant_crypto_tokensThis operation creates a sequence of CryptoToken tokens containing the information needed tocorrectly interpret cipher text encoded using the local_participant_crypto. That is, theCryptoToken sequence contains the information needed to decrypt any data encrypted using thelocal_participant_crypto as well as verify any signatures produced using thelocal_participant_crypto.The returned CryptoToken sequence contains opaque data, which only the plugins understand.The returned CryptoToken is intended for transmission in “clear text” to the remote Domain-Participant associated with the remote_participant_crypto so that the remote Do-mainParticipant has access to the necessary key material. For this reason the CryptoKeyEx-change plugin implementation may encrypt the sensitive information inside the CryptoToken usingshared secrets and keys obtained from the remote_participant_crypto. The specific waysin which this is done depend on the plugin implementation.The DDS middleware implementation shall call this operation for each remote DomainPartici-pant that matches a local DomainParticipant. The returned CryptoToken sequence shallbe sent inside by the DDS middleware to the remote DomainParticipant using the Partici-pantMessageWriter with kind set to KIND_SECURITY_PARTICIPANT_CRYPTO_TOKENS(see section 8.5).Parameter local_participant_crypto: A ParticipantCryptoHandle returned by a previouscall to register_local_participant that corresponds to the DomainParticipant thatwill be encrypting and signing messages.Parameter remote_participant_crypto: A ParticipantCryptoHandle returned by a previ-ous call to register_matched_remote_participant that corresponds to the Domain-Participant that will be receiving the messages from the local DomainParticipant andwill be decrypting them and verifying their signature.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns nil.8.8.3.2.2 Operation: set_remote_participant_crypto_tokensThis operation shall be called by the DDS implementation upon reception of a message on the Par-ticipantMessageReader with kind set toKIND_SECURITY_PARTICIPANT_CRYPTO_TOKEN (see section 8.5).DDS Security, Revised Submission 67
    • The operation configures the Cryptographic plugin with the key material necessary to interpretmessages encoded by the remote DomainParticipant associated with the re-mote_participant_crypto and destined to the local DomainParticipant associated withthe local_participant_crypto. The interpretation of the CryptoToken sequence is spe-cific to each Cryptographic plugin implementation. The CryptoToken sequence may containinformation that is encrypted and/or signed. Typical implementations of the Cryptographicplugin will use the previously configured shared secret associated with the local and remote Par-ticipantCryptoHandle to decode the CryptoToken sequence and retrieve the key materialwithin.Parameter remote_participant_crypto: A ParticipantCryptoHandle returned by a previ-ous call to register_matched_remote_participant that corresponds to the Domain-Participant that will be sending the messages from the local DomainParticipant and willbe encrypting/signing them with the key material encoded in the CryptoToken sequence.Parameter local_participant_crypto: A ParticipantCryptoHandle returned by a previouscall to register_local_participant that corresponds to the DomainParticipant thatwill be receiving messages from the remote DomainParticipant and will need to decrypt and/orverify their signature.Parameter remote_participant_tokens: A CryptoToken sequence received via the Partici-pantMessageReader. The CryptoToken shall correspond to the one returned by a call tocreate_local_participant_crypto_tokens performed by the remote DomainPar-ticipant on the remote side.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.2.3 Operation: create_local_datawriter_crypto_tokensThis operation creates a CryptoToken sequence containing the information needed to correctlyinterpret cipher text encoded using the local_datawriter_crypto. That is, the CryptoTo-ken sequence contains that information needed to decrypt any data encrypted using thelocal_datawriter_crypto as well as verify any signatures produced using thelocal_datawriter_crypto.The returned CryptoToken sequence contains opaque data, which only the plugins understand.The returned CryptoToken sequence shall be sent to the remote DataReader associated withthe remote_datareader_crypto so that the remote DataReader has access to the necessarykey material. For this reason the CryptoKeyExchange plugin implementation may encrypt thesensitive information inside the CryptoToken sequence using shared secrets and keys obtainedfrom the remote_datareader_crypto. The specific ways in which this is done depend on theplugin implementation.The DDS middleware implementation shall call this operation for each remote DataReader thatmatches a local DataWriter. The returned CryptoToken sequence shall be sent by the DDSmiddleware to the remote DataReader using the ParticipantMessageWriter with kind set68 DDS Security, Revised Submission
    • to KIND_SECURITY_DATAWRITER_CRYPTO_TOKENS (see section 8.5). The returned Cryp-toToken shall appear in the crypto_tokens attribute of the DatawriterCryptoTo-kensMsg (see section 8.5.2.3). The datawriter_guid attribute shall be set to the RTPS GUIDof the local DataWriter and the datareader_guid attribute shall be set to the RTPS GUIDof the remote DataReader.Parameter local_datawriter_crypto: A DatawriterCryptoHandle returned by a previouscall to register_local_datawriter that corresponds to the DataWriter that will be en-crypting and signing messages.Parameter remote_datareader_crypto: A DatareaderCryptoHandle returned by a previ-ous call to register_matched_remote_datareader that corresponds to the DataReaderthat will be receiving the messages from the local DataWriter and will be decrypting them andverifying their signature.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns nil.8.8.3.2.4 Operation: set_remote_datawriter_crypto_tokensThis operation shall be called by the DDS implementation upon reception of a message on the Par-ticipantMessageReader with kind set toKIND_SECURITY_DATAWRITER_CRYPTO_TOKENS (see section 8.5).The operation configures the Cryptographic plugin with the key material necessary to interpretmessages encoded by the remote DataWriter associated with the re-mote_datawriter_crypto and destined to the local DataReader associated with the lo-cal_datareader_crypto. The interpretation of the CryptoToken sequence is specific toeach Cryptographic plugin implementation. The CryptoToken sequence may contain infor-mation that is encrypted and/or signed. Typical implementations of the Cryptographic pluginwill use the previously configured shared secret associated with the remote DatawriterCrypto-Handle and local DatareaderCryptoHandle to decode the CryptoToken sequence andretrieve the key material within.Parameter remote_datawriter_crypto: A DatawriterCryptoHandle returned by a previouscall to register_matched_remote_datawriter that corresponds to the DataWriter thatwill be sending the messages to the local DataReader and will be encrypting/signing them withthe key material encoded in the CryptoToken.Parameter local_datareader_crypto: A DatareaderCryptoHandle returned by a previouscall to register_local_datareader that corresponds to the DataReader that will be re-ceiving messages from the remote DataWriter and will need to decrypt and/or verify their signa-ture.Parameter remote_datawriter_tokens: A CryptoToken sequence received via the Partici-pantMessageReader. The CryptoToken shall correspond to the one returned by a call tocreate_local_datawriter_crypto_tokens performed by the remote DataWriter onthe remote side.DDS Security, Revised Submission 69
    • Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.2.5 Operation: create_local_datareader_crypto_tokensThis operation creates a CryptoToken sequence containing the information needed to correctlyinterpret cipher text encoded using the local_datareader_crypto. That is, the CryptoTo-ken sequence contains that information needed to decrypt any data encrypted using thelocal_datareader_crypto as well as verify any signatures produced using thelocal_datareader_crypto.The returned CryptoToken sequence contains opaque data, which only the plugins understand.The returned CryptoToken sequence shall be sent to the remote DataWriter associated withthe remote_datawriter_crypto so that the remote DataWriter has access to the necessarykey material. For this reason the CryptoKeyExchange plugin implementation may encrypt thesensitive information inside the CryptoToken sequence using shared secrets and keys obtainedfrom the remote_datawriter_crypto. The specific ways in which this is done depend on theplugin implementation.The DDS middleware implementation shall call this operation for each remote DataWriter thatmatches a local DataReader. The returned CryptoToken sequence shall be sent by the DDSmiddleware to the remote DataWriter using the ParticipantMessageWriter with kind setto KIND_SECURITY_DATAREADER_CRYPTO_TOKENS (see section 8.5). The returned Cryp-toToken shall appear in the crypto_tokens attribute of the DatareaderCryptoTo-kensMsg (see section 8.5.2.4). The datareader_guid attribute shall be set to the RTPS GUIDof the local DataReader and the datawriter_guid attribute shall be set to the RTPS GUIDof the remote DataWriter.Parameter local_datareader_crypto: A DatareaderCryptoHandle returned by a previouscall to register_local_datareader that corresponds to the DataReader that will be en-crypting and signing messages.Parameter remote_datawriter_crypto: A DatawriterCryptoHandle returned by a previouscall to register_matched_remote_datawriter that corresponds to the DataWriter thatwill be receiving the messages from the local DataReader and will be decrypting them and verify-ing their signature.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns nil.8.8.3.2.6 Operation: set_remote_datareader_crypto_tokensThis operation shall be called by the DDS implementation upon reception of a message on the Par-ticipantMessageReader with kind set toKIND_SECURITY_DATAREADER_CRYPTO_TOKENS (see section 8.5).The operation configures the Cryptographic plugin with the key material necessary to interpretmessages encoded by the remote DataReader associated with the re-70 DDS Security, Revised Submission
    • mote_datareader_crypto and destined to the local DataWriter associated with the lo-cal_datawriter_crypto. The interpretation of the CryptoToken sequence is specific toeach Cryptographic plugin implementation. The CryptoToken sequence may contain infor-mation that is encrypted and/or signed. Typical implementations of the Cryptographic pluginwill use the previously configured shared secret associated with the remote DatareaderCrypto-Handle and local DatawriterCryptoHandle to decode the CryptoToken sequence andretrieve the key material within.Parameter remote_datareader_crypto: A DatareaderCryptoHandle returned by a previouscall to register_matched_remote_datareader that corresponds to the DataReader thatwill be sending the messages to the local DataWriter and will be encrypting/signing them withthe key material encoded in the CryptoToken sequence.Parameter local_datawriter_crypto: A DatawriterCryptoHandle returned by a previouscall to register_local_datawriter that corresponds to the DataWriter that will be re-ceiving messages from the remote DataReader and will need to decrypt and/or verify their signa-ture.Parameter remote_datareader_tokens: A CryptoToken sequence received via the Partici-pantMessageReader. The CryptoToken shall correspond to the one returned by a call tocreate_local_datareader_crypto_tokens performed by the remote DataReader onthe remote side.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.2.7 Operation: return_crypto_tokensReturns the tokens in the CryptoToken sequence to the plugin so the plugin can release any in-formation associated with it.Parameter crypto_tokens: Contains CryptoToken objects issued by the plugin on a prior call toone of the following operations: • create_local_participant_crypto_tokens • create_local_datawriter_crypto_tokens • create_local_datareader_crypto_tokensParameter exception: A SecurityException object, which provides details in the case thisoperation returns false.8.8.3.3 CryptoTransform interfaceThis interface groups the operations related to encrypting/decrypting as well as computing and veri-fying both message digests (hashes) and Message Authentication Codes (MAC).MACs may be used to verify both the data integrity and the authenticity of a message. The computa-tion of a MAC (also known as a keyed cryptographic hash function), takes as input a secret key andan arbitrary-length message to be authenticated, and outputs a MAC. The MAC value protects both aDDS Security, Revised Submission 71
    • messages data integrity as well as its authenticity by allowing verifiers (who also possess the secretkey) to detect any changes to the message content.A Hash-based Message Authentication Code (HMAC) is a specialized way to compute MACs.While an implementation of the plugin is not forced to use HMAC, and could use other MAC algo-rithms, the API is chosen such that plugins have the possibility to implement HMAC if they sochoose.The operations in the CryptoTransform Plugin are defined to be quite generic, taking an inputbyte array to transform and producing the transformed array of bytes as an output. The DDS imple-mentation is only responsible for calling the operations in the CryptoTransform plugin at the appro-priate times as it generates and processes the RTPS messages, substitute the input bytes with thetransformed bytes produced by the CryptoTransform operations, and proceed to generate/sendor process the RTPS message, with the replaced bytes, as it would have with the original one. Thedecision of the kind of transformation to perform (encrypt and/or produce a digest and/or a MACand/or signature) is left to the plugin implementation.CryptoTransformNo AttributesOperationsencode_serialized_da Booleanta Out: octet[] encoded_buffer plain_buffer octet[] sending_datawrit DatawriterCryptoHandle er_crypto Out: exception SecurityExceptionencode_datawriter_su Booleanbmessage Out: octet[] encoded_rtps_sub message plain_rtps_subme octet[] ssage sending_datawrit DatawriterCryptoHandle er_crypto receiving_datare DatareaderCryptoHandle[] ader_crypto_list exception SecurityException72 DDS Security, Revised Submission
    • encode_datareader_su Booleanbmessage Out: octet[] encoded_rtps_sub message plain_rtps_subme octet[] ssage sending_dataread DatareaderCryptoHandle er_crypto receiving_datawr DatawriterCryptoHandle[] iter_crypto_list exception SecurityExceptionencode_rtps_message Boolean Out: octet[] encoded_rtps_mes sage plain_rtps_messa octet[] ge sending_crypto ParticipantCryptoHandle receiving_crypto ParticipantCryptoHandle[] _list exception SecurityExceptionpreprocess_secure_su Booleanbmsg Out: DatawriterCryptoHandle datawriter_crypt o Out: DatareaderCryptoHandle datareader_crypt o Out: DDS_SecureSumessageCatego secure_submessag ry_t e_category In: octet[] encoded_rtps_sub message receiving_crypto ParticipantCryptoHandleDDS Security, Revised Submission 73
    • sending_crypto ParticipantCryptoHandle exception SecurityExceptiondecode_serialized_da Out: octet[]ta encoded_rtps_sub message plain_rtps_subme octet[] ssage sending_datawrit DatawriterCryptoHandle er_crypto receiving_datare DatareaderCryptoHandle[] ader_crypto_list exception SecurityException exception SecurityExceptiondecode_datawriter_su Booleanbmessage Out: octet[] plain_rtps_subme ssage encoded_rtps_sub octet[] message receiving_partic ParticipantCryptoHandle ipant_crypto sending_particip ParticipantCryptoHandle ant_crypto exception SecurityExceptiondecode_datareader_su Booleanbmessage Out: octet[] plain_rtps_messa ge encoded_rtps_mes octet[] sage receiving_partic ParticipantCryptoHandle ipant_crypto sending_particip ParticipantCryptoHandle ant_crypto exception SecurityException74 DDS Security, Revised Submission
    • decode_rtps_message Boolean Out: octet[] plain_buffer encoded_buffer octet[] receiving_crypto ParticipantCryptoHandle sending_crypto ParticipantCryptoHandle exception SecurityException8.8.3.3.1 Operation: encode_serialized_dataThis operation shall be called by the DDS implementation as a result of the application calling thewrite operation on the DataWriter that is associated with the DatawriterCryptoHandle specified inthe sending_datawriter_crypto parameter.The operation receives the data written by the DataWriter in serialized form wrapped inside theRTPS SerializedData submessage element and shall output a RTPS SecuredData submes-sage.The DDS implementation shall call this operation for all outgoing RTPS Submessages with submes-sage kind Data and DataFrag. The DDS implementation shall substitute the SerializedDatasubmessage element within the aforementioned RTPS submessages with the SecuredData pro-duced by this operation.The implementation of encode_serialized_data can perform any desired cryptographictransformation of the SerializedData using the key material in thesending_datawriter_crypto, including encryption, addition of a MAC, and/or signature.The SecuredData shall include within the CryptoTransformIdentifier any additionalinformation beyond the one shared via the CryptoToken that would be needed to identify the keyused and decode the SecuredData submessage element.DDS Security, Revised Submission 75
    • If an error occurs, this method shall return false.Parameter encoded_buffer: The output containing the SecuredData RTPS submessage element,which shall be used to replace the input plain_buffer.Parameter plain_buffer: The input containing the SerializedData RTPS submessage element.Parameter sending_datawriter_crypto: The DatawriterCryptoHandle returned by a previous call toregister_local_datawriter for the DataWriter that wrote the SerializedData.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.3.2 Operation: encode_datawriter_submessageThis operation shall be called by the DDS implementation whenever it has constructed a RTPS sub-message of kind Data, DataFrag, Gap, Heartbeat, or HeartbeatFrag.The operation receives the DatawriterCryptoHandle of the DataWriter that is sending thesubmessage as well a list of DatareaderCryptoHandle corresponding to all the DataReaderentities to which the submessage is being sent.The operation receives the complete RTPS submessage as it would normally go onto the wire in theparameter rtps_submessage and shall output a RTPS SecureSubMsg in the output parameterencoded_rtps_submessage. The DDS implementation shall substitute the original RTPSsubmessage that was passed in the rtps_submessage with the SecureSubMsg returned in theencoded_rtps_submessage output parameter and use the SecureSubMsg in the construc-tion of the RTPS message that is eventually sent to the intended recipients.The implementation of encode_datawriter_submessage can perform any desired crypto-graphic transformation of the RTPS Submessage using the key material in thesending_datawriter_crypto, it can also add one or more MACs, and/or signatures. Thefact that the cryptographic material associated with the list of intended DataReader entities is passed76 DDS Security, Revised Submission
    • in the parameter receiving_datareader_crypto_list allows the plugin implementationto include one of MAC that may be computed differently for each DataReader.The implementation of encode_datawriter_submessage shall include within the Secure-SubMsg the CryptoTransformIdentifier containing any additional information necessaryfor the receiving plugin to identify the DatawriterCryptoHandle associated with theDataWriter that sent the message as well as the DatareaderCryptoHandle associated with theDataReader that is meant to process the submessage. How this is done depends on the plugin imple-mentation.The CryptoTransformIdentifier should also contain any additional information beyond theone shared via the CryptoToken that would be needed to identify the key used and decode theSecureSubMsg submessage back into the original RTPS submessage.If an error occurs, this method shall return false.Parameter encoded_rtps_submessage: The output containing the RTPS SecureSubMsg submes-sage, which shall be used to replace the input rtps_submessage.Parameter plain_rtps_submessage: The input containing the RTPS submessage created by aDataWriter. This submessage will be one of following kinds: Data, DataFrag, Gap, Heart-beat, and HeartbeatFrag.Parameter sending_datawriter_crypto: The DatawriterCryptoHandle returned by a previ-ous call to register_local_datawriter for the DataWriter whose GUID is inside thertps_submessage.Parameter receiving_datareader_crypto_list: The list of DatareaderCryptoHandle returnedby previous calls to register_matched_remote_datareader for the DataReader entities towhich the submessage will be sent.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.3.3 Operation: encode_datareader_submessageThis operation shall be called by the DDS implementation whenever it has constructed a RTPS sub-message of kind AckNack or NackFrag.DDS Security, Revised Submission 77
    • The operation receives the DatareaderCryptoHandle of the DataReader that is sending thesubmessage as well a list of DatawriterCryptoHandle corresponding to all the DataWriterentities to which the submessage is being sent.The operation receives the complete RTPS submessage as it would normally go onto the wire in theparameter rtps_submessage and shall output a RTPS SecureSubMsg in the output parameterencoded_rtps_submessage. The DDS implementation shall substitute the original RTPSsubmessage that was passed in the rtps_submessage with the SecureSubMsg returned in theencoded_rtps_submessage output parameter and use the SecureSubMsg in the construc-tion of the RTPS message that is eventually sent to the intended recipients.The implementation of encode_datareader_submessage can perform any desired crypto-graphic transformation of the RTPS Submessage using the key material in thesending_datareader_crypto, it can also add one or more MACs, and/or signatures. Thefact that the cryptographic material associated with the list of intended DataWriter entities is passedin the parameter receiving_datawriter_crypto_list allows the plugin implementationto include one of MAC that may be computed differently for each DataWriter.The implementation of encode_datareader_submessage shall include within the Secure-SubMsg the CryptoTransformIdentifier containing any additional information necessaryfor the receiving plugin to identify the DatareaderCryptoHandle associated with theDataReader that sent the message as well as the DatawriterCryptoHandle associated with theDataWriter that is meant to process the submessage. How this is done depends on the plugin imple-mentation.The CryptoTransformIdentifier should also contain any additional information beyond theone shared via the CryptoToken that would be needed to identify the key used and decode theSecureSubMsg submessage back into the original RTPS submessage.If an error occurs, this method shall return false.Parameter encoded_rtps_submessage: The output containing the RTPS SecureSubMsg submes-sage, which shall be used to replace the input rtps_submessage.Parameter plain_rtps_submessage: The input containing the RTPS submessage created by aDataReader. This submessage will be one of following kinds: AckNack, NackFrag.78 DDS Security, Revised Submission
    • Parameter sending_datareader_crypto: The DatareaderCryptoHandle returned by a previ-ous call to register_local_datareader for the DataReader whose GUID is inside thertps_submessage.Parameter receiving_datawriter_crypto_list: The list of DatawriterCryptoHandle returnedby previous calls to register_matched_remote_datawriter for the DataWriter entities towhich the submessage will be sent.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.3.4 Operation: encode_rtps_messageThis operation shall be called by the DDS implementation whenever it has constructed a RTPS mes-sage prior to sending it on the wire.The operation receives the ParticipantCryptoHandle of the DomainParticipant that is send-ing the submessage as well a list of ParticipantCryptoHandle corresponding to all the Do-mainParticipant entities to which the submessage is being sent.The operation receives the complete RTPS message as it would normally go onto the wire in the pa-rameter rtps_message and shall output also an RTPS message containing a single Secure-SubMsg in the output parameter encoded_rtps_message. The DDS implementation shall sub-stitute the original RTPS message that was passed in the rtps_message with the en-coded_rtps_message returned by this operation and proceed to send it to the intended recipi-ents.This operation may optionally not perform any transformation of the input RTPS message. In thiscase the operation shall return false but not set the exception object. In this situation the DDS im-plementation shall send the original RTPS message. If this operation performs any transformation of the original RTPS message it shall output an RTPSHeader followed by a single SecureSubMsg with the MultiSubmsgFlag (see section 7.2.3.2.1)set to true.The implementation of encode_rtps_message may perform any desired cryptographic trans-formation of the RTPS Message using the key material in thesending_participant_crypto, it can also add one or more MACs, and/or signatures. Thefact that the cryptographic material associated with the list of intended DataWriter entities is passedin the parameter receiving_participant_crypto_list allows the plugin implementationto include one of MAC that may be computed differently for each destination DomainParticipant.The implementation of encode_ rtps_message shall include within the SecureSubMsg theCryptoTransformIdentifier containing any additional information beyond the one sharedvia the CryptoToken that would be needed to identify the key used and decode the Secure-SubMsg submessage back into the original RTPS message.DDS Security, Revised Submission 79
    • If an error occurs, this method shall return false and set the exception object.Parameter encoded_rtps_message: The output containing the encoded RTPS message. The outputmessage shall contain the original RTPS Header followed by a single SecureSubMsg submessagewith the MultiSubmsgFlag set to true.Parameter plain_rtps_message: The input containing the RTPS messages the DDS implementationintended to send.Parameter sending_participant_crypto: The ParticipantCryptoHandle returned by a previ-ous call to register_local_participant for the DomainParticipant whose GUID is inside the RTPSHeader.Parameter receiving_participant_crypto_list: The list of ParticipantCryptoHandle re-turned by previous calls to register_matched_remote_participant for the DomainPar-ticipant entities to which the message will be sent.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.3.5 Operation: decode_rtps_messageThis operation shall be called by the DDS implementation whenever it receives an RTPS messageprior to parsing it.This operation shall reverse the transformation performed by the encode_rtps_message opera-tion, decrypting the content if appropriate and verifying any MACs or digital signatures that wereproduced by the encode_rtps_message operation.This operation expects the RTPS Header to be followed by a single SecureSubMsg with the Mul-tiSubmsgFlag (see section 7.2.3.2.1) set to true. If this is not the case the operation shall per-form no transformation, return false, but not set the exception object. This situation is not considered80 DDS Security, Revised Submission
    • an error. It simply indicates that the encode_rtps_message operation did not transform theoriginal RTPS message.If an error occurs, this method shall return and exception.Parameter plain_rtps_message: The output containing the decoded RTPS message. The output mes-sage shall contain the original RTPS Header followed by a single SecureSubMsg submessage.Parameter encoded_rtps_message: The input containing the encoded RTPS message the DDS im-plementation received.Parameter receiving_participant_crypto: The ParticipantCryptoHandle returned by previ-ous calls to register_local_participant for the DomainParticipant entity that received theRTPS message.Parameter sending_participant_crypto: The ParticipantCryptoHandle returned by a previ-ous call to register_matched_remote_participant for the DomainParticipant that sentthe RTPS message whose GUID is inside the RTPS Header.Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.3.6 Operation: preprocess_secure_submsgThis operation shall be called by the DDS implementation as a result a DomainParticipant receivinga RTPS SecureSubMsg with the MultiSubmsgFlag (see section 7.2.3.2.1) set to false.The purpose of the operation is to determine whether the secure submessage was produced as a resultof a call to encode_datawriter_submessage or a call to en-code_datareader_submessage, and retrieve the appropriate DatawriterCryptoHandleand DatareaderCryptoHandle needed to decode the submessage.DDS Security, Revised Submission 81
    • If the operation returns successfully the DDS implementation shall call the appropriate decode opera-tion based on the returned SecureSubmessageCategory: • If the returned SecureSubmessageCategory equals WRITERSUBMESSAGE, then the DDS Implementation shall call decode_datawriter_submessage. • If the returned SecureSubmessageCategory equals READERSUBMESSAGE, then the DDS Implementation shall call decode_datareader_submessage.Parameter secure_submessage_category: Output SecureSubmessageCategory_t. It shall beset to WRITERSUBMESSAGE if the SecureSubMsg was created by a call to en-code_datawriter_submessage or set to READERSUBMESSAGE if the SecureSubMsg wascreated by a call to encode_datareader_submessage. If none of these conditions apply theoperation shall return false.Parameter datawriter_crypto: Output DatawriterCryptoHandle. The setting depends on theretuned value of secure_submessage_category: • If secure_submessage_category is WRITERSUBMESSAGE the datawriter_crypto shall be the DatawriterCryptoHandle returned by a previous call to register_matched_remote_datawriter for the DataWriter that wrote the RTPS Submessage. • If secure_submessage_category is READERSUBMESSAGE the datawriter_crypto shall be the DatawriterCryptoHandle returned by a previous call to register_local_datawriter for the DataWriter that is the destination of the RTPS Submessage.Parameter datareader_crypto: Output DatareaderCryptoHandle. The setting depends on theretuned value of secure_submessage_category: • If secure_submessage_category is WRITERSUBMESSAGE the datareader_crypto shall be the DatareaderCryptoHandle returned by a previous call to register_local_datareader for the DataReader that is the destination of the RTPS Submessage. • If secure_submessage_category is READERSUBMESSAGE the datareader_crypto shall be the DatareaderCryptoHandle returned by a previous call to register_matched_remote_datareader for the DataReader that wrote the RTPS Submessage.Parameter encoded_rtps_message: The input containing the received RTPS message.Parameter receiving_participant_crypto: The ParticipantCryptoHandle returned by previ-ous calls to register_local_participant for the DomainParticipant that received the RTPSmessage.Parameter sending_participant_crypto: The ParticipantCryptoHandle returned by a previ-ous call to register_matched_remote_participant for the DomainParticipant whoseGUID is inside the RTPS Header.82 DDS Security, Revised Submission
    • Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.3.7 Operation: decode_datawriter_submessageThis operation shall be called by the DDS implementation as a result of receiving a Secure-SubMsg with the MultiSubmsgFlag set to false whenever the preceding call to prepre-cess_secure_submessage identified the SecureSubmessageCategory as WRIT-ERSUBMESSAGE.This operation shall reverse the transformation performed by the en-code_datawriter_submessage operation, decrypting the content if appropriate and verifyingany MACs or digital signatures that were produced by the encode_datawriter_submessageoperation.The DDS implementation shall substitute the RTPS SecureSubMsg submessage within the re-ceived submessages with the RTPS Submessage produced by this operation.If an error occurs, this method shall return false.Parameter plain_rtps_submessage: The output containing the RTPS submessage created by aDataWriter. This submessage will be one of following kinds: Data, DataFrag, Gap, Heart-beat, and HeartbeatFrag.Parameter encoded_rtps_submessage: The input containing the RTPS SecureSubMsg submes-sage, which was created by a call to encode_datawriter_submessage.Parameter receiving_datareader_crypto: The DatareaderCryptoHandle returned by the pre-ceding call to prepreprocess_secure_submsg performed on the received SecureSubMsg.It shall contain the DatareaderCryptoHandle corresponding to the DataReader that is receiv-ing the RTPS Submessage.Parameter sending_datawriter_crypto: The DatawriterCryptoHandle returned by the pre-ceding call to prepreprocess_secure_submsg performed on the received SecureSubMsg.It shall contain the DatawriterCryptoHandle corresponding to the DataWriter that is sendingthe RTPS Submessage.DDS Security, Revised Submission 83
    • Parameter exception: A SecurityException object, which provides details, in the case thisoperation returns false.8.8.3.3.8 Operation: decode_datareader_submessageThis operation shall be called by the DDS implementation as a result of receiving a Secure-SubMsg with the MultiSubmsgFlag set to false whenever the preceding call to prepre-cess_secure_submessage identified the SecureSubmessageCategory as READER-SUBMESSAGE.This operation shall reverse the transformation performed by the en-code_datareader_submessage operation, decrypting the content if appropriate and verifyingany MACs or digital signatures that were produced by the encode_datareader_submessageoperation.The DDS implementation shall substitute the RTPS SecureSubMsg submessage within the re-ceived submessages with the RTPS Submessage produced by this operation.If an error occurs, this method shall return false.Parameter plain_rtps_submessage: The output containing the RTPS submessage created by aDataReader. This submessage will be one of following kinds: AckNack, NackFrag.Parameter encoded_rtps_submessage: The input containing the RTPS SecureSubMsg submes-sage, which was created by a call to encode_datareader_submessage.Parameter receiving_datareader_crypto: The DatareaderCryptoHandle returned by the pre-ceding call to prepreprocess_secure_submsg performed on the received SecureSubMsg.It shall contain the DatareaderCryptoHandle corresponding to the DataReader that is receiv-ing the RTPS Submessage.Parameter sending_datawriter_crypto: The DatawriterCryptoHandle returned by the pre-ceding call to prepreprocess_secure_submsg performed on the received SecureSubMsg.It shall contain the DatawriterCryptoHandle corresponding to the DataWriter that is sendingthe RTPS Submessage.84 DDS Security, Revised Submission
    • 8.8.3.3.9 Operation: decode_serialized_dataThis operation shall be called by the DDS implementation as a result a DataReader receiving a Dataor DataFrag submessage containing a SecuredData RTPS submessage element (instead of thenormal SerializedData).The DDS implementation shall substitute the SecuredData submessage element within the re-ceived submessages with the SerializedData produced by this operation.The implementation of decode_serialized_data shall undo the cryptographic transformationof the SerializedData that was performed by the corresponding call to en-code_serialized_data on the DataWriter side. The DDS implementation shall use the avail-able information on the remote DataWriter that wrote the message and the receiving DataReader tolocate the corresponding DatawriterCryptoHandle and DatareaderCryptoHandle andpass them as parameters to the operation. In addition it shall use the CryptoTransformIdenti-fier present in the SecuredData to verify that the correct key us available and obtain any addi-tional data needed to decode the SecuredData.If an error occurs, this method shall return false.Parameter plain_buffer: The output containing the SerializedData RTPS submessage element,which shall be used to replace the input plain_buffer.Parameter encoded_buffer: The input containing the SecuredData RTPS submessage element.Parameter receving_reader_crypto: The DatareaderCryptoHandle returned by a previouscall to register_local_datareader for the DataReader that received the Submessagecontaining the SecuredData.Parameter sending_datawriter_crypto: The DatawriterCryptoHandle returned by a previ-ous call to register_matched_remote_datawriter for the DataWriter that wrote theSecuredData.DDS Security, Revised Submission 85
    • Parameter exception: A SecurityException object, which provides details, in the case this op-eration returns false.8.9 The Logging PluginThe Logging Control Plug-in API defines the types and operations necessary to support logging ofsecurity events for a DDS DomainParticipant.8.9.1 Background (Non-Normative)The logging plug-in provides the capability to log all security events, both expected behavior andsecurity violations or errors. The goal is to create security logs that can be used in the case of anaudit of behavior. Each of the other security plug-ins will log events using the logging API.The logger will add an ID to the log message that uniquely specifies the DomainParticipant. It alsoadds a time-stamp to each log message.The logging API has two options for collecting log data. The first is to log all events to a local file.The second is to distribute log events securely over DDS.8.9.2 Logging Plug-in ModelThe logging model is shown in the figure below.8.9.2.1 LogOptionsThe LogOptions let the user control which level to log and where to log. The options must be setbefore logging starts and may not be changed. This is to ensure that an attacker cannot temporarilysuspend logging while they violate security rules, and then start it up again. By default the log_levelis set to TRACE_LEVEL so that all log messages are recorded. The options specify if the messagesshould be logged to a file, and if so the file name. The LogOptions also specify whether the mes-sages should be distributed over DDS.LogOptionsAttributeslog_level Long86 DDS Security, Revised Submission
    • log_file Stringdistribute Boolean8.9.2.1.1 Attribute: log_levelSpecifies what level of log messages will be logged. Messages at or above the log_level are logged.The levels are as follows, from high to low: • FATAL_LEVEL – security error causing a shutdown or failure of the Domain Participant • SEVERE_LEVEL – major security error or fault • ERROR_LEVEL – minor security error or fault • WARNING_LEVEL – undesirable or unexpected behavior • NOTICE_LEVEL – important security event • INFO_LEVEL – interesting security event • DEBUG_LEVEL – detailed information on the flow of the security events • TRACE_LEVEL – even more detailed information8.9.2.1.2 Attribute: log_fileSpecifies the full path to a local file for logging events. If the file already exists, the logger will ap-pend log messages to the file. If it is NULL, then the logger will not log messages to a file.8.9.2.1.3 Attribute: distributeSpecifies whether the log events should be distributed over DDS. If it is TRUE, then each log mes-sage at or above the log_level is published as a DDS Topic.8.9.2.2 LoggerLoggerNo AttributesOperationsset_log_options Boolean options LogOptions exception SecurityExceptionlog void log_level long message StringDDS Security, Revised Submission 87
    • category String exception SecurityExceptionenable_logging void exception SecurityException8.9.2.2.1 Operation: set_log_optionsSets the options for the logger. This must be called before enable_logging; it is an error to set theoptions after logging has been enabled.If the options are not successfully set, then the method shall return false.Parameter options: the LogOptions object with the required optionsParameter exception: A SecurityException object, which provides details, in the case thisoperation returns false8.9.2.2.2 Operation: logLog a message. The logger will log the message if its log_level is at or above the level set in theLogOptions. The Logger will add a unique Domain Participant ID consisting of the RTPSapp id and RTPS host id to the message. If it is sent out over DDS, then DDS will add a timestamp.If it is logged locally, a timestamp will be added when it is logged.Parameter log_level: The level of the log message. It must correspond to one of the levels definedin 8.9.2.1.1.Parameter message: The log messageParameter category: A category for the log message. This can be used to specify which securityplugin generated the message.Parameter exception: A SecurityException object that will return an exception if there is anerror with logging8.9.2.2.3 Operation: enable_loggingEnables logging. After this method is called, any call to log shall log the messages according to theoptions. After this method is called, the options may not be modified. This is to ensure that the log-ger cannot be temporarily suspended to cover up an attack.If the options are not successfully set, then the method shall return false.Parameter options: the LogOptions object with the required optionsParameter exception: A SecurityException object, which provides details, in the case thisoperation returns false88 DDS Security, Revised Submission
    • 8.10 Data TaggingData tagging is the ability to add a security label or tag to data. This is often used to specify a classi-fication level of the data including information about its releasbility. In a DDS context, it could haveseveral uses: • It can be used for access control – access control would be granted based on the tag • It could be used for message prioritization • It could not be used by the middleware, and instead used by the application or other service8.10.1 Background (Non-Normative)There are four different approaches to data tagging: • DataWriter tagging: data received from a certain DataWriter has the tag of the DataWriter. This solution does not require the tag to be added to each individual sample. • Data instance tagging: each instance of the data has a tag. This solution does not require the tag to be added to each individual sample. • Individual sample tagging: every DDS sample has its own tag attached. • Per-field sample tagging: very complex management of the tags.This specification supports DataWriter tagging. This was considered the best choice as it meetsthe majority of uses cases. It fits into the DDS paradigm, as the meta-data for all samples from aDataWriter is the same. It is also the highest performance, as the tag only needs to be exchangedonce when the DataWriter is discovered, not sent with each sample.This approach directly supports typical use cases where each application or DomainParticipant writesdata on a Topic with a common set of tags (e.g. all at the same specified security level). For usecases where an application creates data at different classifications, that application can create multi-ple DataWriters with different tags.8.10.2 ApproachThe DataWriter tag will be associated with every sample written by the DataWriter. Insteadof a plug-in, an API will be added to the DataWriter to add a tag, and to a DataReader to re-trieve the tag. The tag itself will be a string. The description of the contents of a tag is outside thescope of this specification.The data tag will map to a specified property of the DataWriter. This means that the tag will becommunicated during DDS discovery as part of the meta-data. To ensure secure delivery of the tag,the discovery data should be secured by securing the built-in DataWriter and DataReader.8.10.3 DataTagging ModelThe data tag will be added as a property QoS on the DataWriter with a name of “Secure_DDS_Tag”.The property will be propagated over discovery.DDS Security, Revised Submission 89
    • 8.10.3.1 DataTagThe DataTag contains the tag for the data.DataTagAttributesvalue <string>Attribute: valueSpecifies the contents of a tag. The description of the tag is open to the user. For example, it couldcontain the classification, classification caveats, and releasability information. The tag could beXML.8.10.3.2 DataWriter ExtensionAn additional method would be added to the DataWriter to add a tag.DataWriterNo AttributesOperationsadd_data_tag ReturnCode_t data_tag DataTag8.10.3.2.1 Operation: add_data_tagAdds a data tag to a DataWriter. Only one data tag may be added. If the function is called a sec-ond time with a new tag, it shall return error.If the tag is not successfully set, then the method shall return error.Parameter data_tag: the DataTag object with the tag.8.10.3.3 DataReader ExtensionAn additional method would be added to the DataReader to retrieve a tag.DataReaderNo AttributesOperationsget_data_tag ReturnCode_t90 DDS Security, Revised Submission
    • out: data_tag DataTag publication_handle InstanceHandle_t8.10.3.3.1 Operation: get_data_tagGets the data tag for a sample. If there is no tag associated with the sample, it will return nil.Parameter data_tag: the data_tag is an output of the method containing the tag.Parameter publication_handle: this is the handle to the DataWriter that wrote the sample.This handle can be found in the SampleInfo that is returned with the data as the result of a reador take call.8.11 Security Plug-ins’ BehaviorIn the previous sections, the functionality and APIs of each plug-in have been described. This sectionprovides additional information on how the plug-ins are integrated with the middleware.8.11.1 Authentication and AccessControl behavior with local DomainParticipantThe figure above illustrates the functionality of the security plug-ins with regards to a localDomainParticipant.DDS Security, Revised Submission 91
    • 1. The DDS application initiates the creation of a local DomainParticpant. 2. Given the identity information that the application provides, the middleware validates the identity of the local DomainParticipant by calling Authentication::validate_local_identity() operation. The Authentica- tion plug-in validates the identity of the local DomainParticipant and issues an IdentityHandle for the holder of the identity (DomainParticipant), which will be necessary for interacting with the access control plug-in. If the identity is not validated, the DomainParticipant is not created. 3. The middleware validates the permissions of the local DomainParticipant by call- ing AccessControl::validate_local_permissions() operation. The Ac- cess Control plug-in validates the permissions of the local DomainParticipant, and issues a signed PermissionsHandle for the holder of the identity (DomainParticipant). If the permissions are not validated, the DomainParticipant object is not created. 4. The middleware needs to first verify that the DomainParticpant is allowed on Do- main domainId. Operation AccessControl::check_create_participant() is called for this verifica- tion. 5. The middleware calls get_identity_token() operation, which returns the IdentityToken object corresponding to the received IdentityHandle. The IdentityToken object is necessary for later for discovery propagation. 6. The DomainParticipant’s identity information is propagated via discovery using the IdentityToken object returned at step 5. 7. The middleware calls get_permissions_token() operation, which returns the PermissionsToken object corresponding to the received PermissionsHandle. 8. The DomainParticipant’s permissions information is propagated via discovery us- ing the PermissionsToken object returned at step 7.8.11.2 Authentication behavior with remote DomainParticipantThe figure below illustrates the functionality of the security plug-ins with regards to a remoteDomainParticipant.92 DDS Security, Revised Submission
    • 1. A remote DomainParticipant is discovered via the discovery protocol. The BuiltinParticipantTopicData contains the IdentityToken of the remote DomainParticipant. 2. Given the identity information that the remote DomainParticipant propagated via discovery, the middleware validates the identity of the remote DomainParticipant by calling Authentication::validate_remote_identity() operation. The Authentication plug-in validates the identity of the remote DomainParticipant, which may involve additional handshakes on the network, and issues an IdentityHandle for the remote DomainParticipant with is needed for further operations that involve that DomainParticipant. If the identity is not validated or no identity information is propagated, the remote DomainParticipant is ignored. The operation returns PENDING_HANDSHAKE_REQUEST indicating further hand- shaking is necessary to complete the validation. 3. The middleware calls Authentication::begin_handshake_request() to begin the requested handshake. The operation outputs a HandshakeHandle and a MessageToken (messageToken1) that the middleware must send to the remote Do- mainParticipant. The operation returns PENDING_HANDSHAKE_MESSAGE indicat- ing Authentication is not complete and an additional message is expected.DDS Security, Revised Submission 93
    • 4. The middleware sends the MessageToken (messageToken1) to the remote participant using the BuiltinParticipantMessageWriter. 5. The middleware on the Participant2 DomainParticipant receives the MessageToken (messageToken1) on the BuiltinParticipantMessageReader. The mid- dleware determines this is message originated from a remote DomainParticipant for which it had already called Authentication::validate_remote_identity() where the function had re- turned PENDING_HANDSHAKE_REPLY. 6. The middleware calls Authentication::begin_handshake_reply() passing the received MessageToken (messageToken1). The Authentication plugin processes the MessageToken messageToken1 and outputs a MessageToken messageToken2 in re- sponse and a HandshakeHandle. The begin_handshake_reply returns PEND- ING_HANDSHAKE_MESSAGE, indicating Authentication is not complete and an addi- tional message is expected. 7. The middleware sends the MessageToken (messageToken2) back to Participant1 using the BuiltinParticipantMessageWriter. 8. The middleware on the Participant1 DomainParticipant receives the MessageToken (messageToken2) on the BuiltinParticipantMessageReader. The mid- dleware determines this is message originated from a remote DomainParticipant for which it had already called Authentication::validate_remote_identity() where the function had re- turned PENDING_HANDSHAKE_REQUEST. 9. The middleware calls Authentication::process_handshake() passing the re- ceived MessageToken (messageToken2). The Authentication plugin processes the messageToken2, validates it is a valid reply to the messageToken1 it had sent and outputs the MessageToken messageToken3 in response. The process_handshake() re- turns OK_WITH_FINAL_MESSAGE, indicating Authentication is complete but mes- sageToken3 shall be sent Participant2. 10. The middleware sends the MessageToken (messageToken3) to the remote participant using the BuiltinParticipantMessageWriter. 11. The middleware on the Participant2 DomainParticipant receives the MessageToken (messageToken3) on the BuiltinParticipantMessageReader. The mid- dleware determines this is message originated from a remote DomainParticipant for which it had already called Authentication::begin_handshake_reply() where the function had returned PENDING_HANDSHAKE_MESSAGE. 12. The middleware calls Authentication::process_handshake() passing the re- ceived MessageToken (messageToken3). The Authentication plugin processes the messageToken2, validates it is a valid reply to the messageToken2 it had sent and returns OK, indicating Authentication is complete and no more messages need to be sent or re- ceived.94 DDS Security, Revised Submission
    • 13. The middleware on Participant1, having completed the Authentication of Participant2, calls Authentication::get_shared_secret() to retrieve the SharedSecret, which is used with the other Plugins to create Tokens to exchange with Participant2. 14. The middleware on Participant2, having completed the Authentication of Participant1, calls Authentication::get_shared_secret() to retrieve the SharedSecret, which is used with the other Plugins to create Tokens to exchange with Participant1.8.11.3 AccessControl behavior with local domain entity creationThe figure below illustrates the functionality of the security plug-ins with regards to the creation oflocal DDS domain entities: Topic, DataWriter and DataReader entities. 1. The DDS application initiates the creation of a new Topic for the DomainParticpant. 2. The middleware verifies the DomainParticpant is allowed to create a Topic with name topicName. Operation AccessControl::check_create_topic() is called for this verification. If the verification fails, the Topic object is not created. 3. The DDS application initiates the creation of a local DataWriter. 4. The middleware verifies that the DataWriter has the right permissions to publish on Topic topicName. OperationDDS Security, Revised Submission 95
    • AccessControl::check_create_datawriter() is called for this verification. As an optional behavior, check_create_datawriter () can also verify if the DataWriter is allowed to tag data with dataTag. If the verification doesn’t succeed, the DataWriter is not created. As an optional behavior check_create_datawriter() can also check the QoS associated with the DataWriter and grant permissions taking that into consideration. 5. The DDS application initiates the creation of a local DataReader. 6. The middleware verifies that the DataReader has the right permissions to subscribe on Topic topicName. Operation AccessControl::check_create_datareader() is called for this verification. As an optional behavior, check_create_datareader() can also verify if the DataReader is allowed to receive data tagged with dataTag. If the verification doesn’t succeed, the DataReader is not created. As an optional behavior check_create_datareader() can also check the QoS associated with the DataReader and grant permissions taking that into consideration. 7. The DDS application initiates the registration of an instance of the DataWriter. 8. The middleware verifies that the DataWriter has the right permissions to register the instance. Operation AccessControl::check_local_datawriter_register_instance() is called for this verification. If the verification doesn’t succeed, the instance is not regis- tered. 9. The DDS application initiates the disposal of an instance of the DataWriter. 10. The middleware verifies that the DataWriter has the right permissions to dispose the instance. Operation AccessControl::check_local_datawriter_dispose_instance() is called for this verification. If the verification doesn’t succeed, the instance is not dis- posed.8.11.4 AccessControl behavior with remote entity discoveryThe figure below illustrates the functionality of the security plug-ins with regards to the discovery ofremote Topic, DataWriter and DataReader entities.96 DDS Security, Revised Submission
    • 1. A remote DomainParticipant (Participant2) is discovered via the discovery proto- col. The BuiltinParticipantTopicData contains the PermissionsToken of the remote DomainParticipant. 2. The DDS implementation calls AccessControl::validate_remote_permissions() to validate the permis- sions of the remote DomainParticipant, passing the PermissionsToken ob- tained via discovery from the remote participant. This function returns a PermissionsHandle, which the middleware will then use whenever an access con- trol decision must be made for the remote DomainParticipant. 3. The DDS implementation calls the operation AccessControl::check_remote_participant() to verify the remote DomainParticipant is allowed on Domain domainId, passing the PermissionsHandle. If the verification fails, the remote DomainParticipant is ignored. 4. A new Topic created by the remote DomainParticipant (Participant2) is discovered. 5. The middleware verifies that the remote DomainParticpant is allowed to create a Topic with name topicName. The operation AccessControl::check_remote_topic() is called for this verification. If the verification fails, the Topic is ignored.DDS Security, Revised Submission 97
    • 6. A remote DataWriter is discovered via the discovery protocol. 7. The middleware verifies that the remote DataWriter has the right permissions to pub- lish on Topic topicName. Operation AccessControl::check_remote_datawriter() is called for this verification. As an optional behavior, the same operation can also verify if the DataWriter is al- lowed to tag data with dataTag. If the verification doesn’t succeed, the DataWriter is ignored. 8. A remote DataReader is discovered via the discovery protocol. 9. The middleware verifies that the remote DataReader has the right permissions to sub- scribe on Topic topicName. Operation AccessControl::check_remote_datareader() is called for this verification. As an optional behavior, the same operation can also verify if the DataReader is al- lowed to receive tag data with dataTag. If the verification doesn’t succeed, the DataReader is ignored. 10. The middleware receives a sample from a matched remote DataWriter with DDS In- stance NEW, indicating this is the first sample for that instance received by the DataReader. 11. The middleware verifies that the remote DataWriter has the right permissions to regis- ter the instance. Operation AccessControl::check_remote_datawriter_register_instance() is called for this verification. If the verification doesn’t succeed, the sample is ignored. 12. The middleware receives a sample from a matched remote DataWriter with DDS In- stance NOT_ALIVE_DISPOSED, indicating the remote DataWriter disposed an in- stance. 13. The middleware verifies that the remote DataWriter has the right permissions to dis- pose the instance. The operation AccessControl::check_remote_datawriter_dispose_instance() is called for this verification. If the verification doesn’t succeed, the instance disposal is ig- nored.8.11.5 Security Plugins behavior for key propagationThe figure below illustrates the functionality of the security plug-ins with regards to the discovery ofremote DomainParticipant, DataWriter and DataReader entities with the purpose ofpropagating key material.98 DDS Security, Revised Submission
    • 8.11.5.1 Participant to Key Exchange with discovered Participant 1. A remote DomainParticipant (Participant2) is discovered via the discovery proto- col. The remote DomainParticipant is authenticated and its permissions are checked as described in sections 8.11.2 and 8.11.4. This is not shown here. This resulted in the creation of an IdentityHandle, a PermissionsHandle, and a SharedSecretHandle for that remote DomainParticipant. 2. The DDS implementation calls CryptoKeyFactory::register_matched_remote_participant() to store the association of the remote identity and the shared secret. 3. The DDS implementation calls the operation CryptoKeyExchange::get_local_participant_crypto_token() to ob- tain a CriptoToken (cryptoTokenParticipant1ForParticipant2) to send to the remote DomainParticipant (Participant2). Depending on the implementation theCriptoToken returned by the CryptoKeyExchange might be secured with ma- terial derived from the SharedSecret to it can be sent without further protection by the DDS Implementation. 4. The DDS inplementation sends the CryptoToken (cryptoTokenPartici- pant1ForParticipant2) to Participant2 using the BuiltinParticipantMessageWriter. 5. The DDS implementation on Participant2 receives the CryptoToken and calls the op- eration CryptoKeyExchange::set_remote_participant_crypto_token() Token to register the CryptoToken with the remote DomainParticipant. This will enable the Cryptographic plugin on Participant2 to decode the data sent from Partici- pant1.DDS Security, Revised Submission 99
    • 8.11.5.2 DataWriter key exchange with discovered DataReader 1. A remote DataReader (Reader2) is discovered via the discovery protocol by Partici- pant1. The permissions for the remote DomainParticipant (Participant2) to which Reader2 belongs are checked to ensure it is allowed to write the Topic as described in section 8.11.4. This part is not shown here. 2. The DDS implementation retrieves the cryptographic handles related to the remote par- ticipant (IdentityHandle, a PermissionsHandle, and SharedSecretHandle) and calls CryptoKeyFactory::register_matched_remote_datareader() to store the association of the remote DataReader (Reader2), the remote DomainParticipant (Participant2) identity, and the shared secret. 3. The DDS implementation calls the operation CryptoKeyExchange::get_local_datawriter_crypto_token() to ob- tain a CriptoToken (cryptoTokenWriter1ForReader2) to send to the remote DomainParticipant (Participant2). Depending on the implementation the CriptoToken returned by the CryptoKeyExchange might be secured with material derived from the SharedSecret so it can be sent without further protection by the DDS Implementation. 4. The DDS implementation sends the CryptoToken (cryptoTokenWriter1ForReader2) to Participant2 using the BuiltinParticipantMessageWriter. 5. The DDS implementation on Participant2 receives the CryptoToken and calls the op- eration CryptoKeyExchange::set_remote_datawriter_crypto_token() to register the CryptoToken with the remote DataWriter. This will enable the Cryptographic plugin on Participant2 to decode the data sent from Writer1.100 DDS Security, Revised Submission
    • 8.11.5.3 DataReader key exchange with discovered DataWriter 1. A remote DataWriter (Writer1) is discovered via the discovery protocol by Partici- pant2. The permissions for the remote DomainParticipant (Participant1) to which Writer1 belongs are checked to ensure it is allowed to write the Topic as described in sec- tion 8.11.4. This part is not shown here. 2. The DDS implementation retrieves the cryptographic handles related to the remote par- ticipant (IdentityHandle, a PermissionsHandle, and SharedSecretHandle) and calls CryptoKeyFactory::register_matched_remote_datawriter() to store the association of the remote DataWriter (Writer1), the remote DomainParticipant (Participant1) identity, and the shared secret. 3. The DDS implementation calls the operation CryptoKeyExchange::get_local_datareader_crypto_token() to ob- tain a CriptoToken (cryptoTokenReader2ForWriter1) to send to the remote DomainParticipant (Participant1). Depending on the implementation the CriptoToken returned by the CryptoKeyExchange might be secured with material derived from the SharedSecret so it can be sent without further protection by the DDS Implementation. 4. The DDS implementation sends the CryptoToken (cryptoTokenReader2ForWriter1) to Participant1 using the BuiltinParticipantMessageWriter. 5. The DDS implementation on Participant1 receives the CryptoToken and calls the op- eration CryptoKeyExchange::set_remote_datareader_crypto_token() to register the CryptoToken with the remote DataReader. This will enable the Cryptographic plugin on Participant1 to decode the data sent from Reader2.DDS Security, Revised Submission 101
    • 8.11.6 Security Plugins behavior for encoding/decodingThis section describes the behavior of the DDS implementation related to the CryptoTransform inter-face.This specification does not mandate a specific DDS implementation in terms of the internal logic ortiming when the different operations in the CryptoTransform plugin are invoked. The sequencecharts below just express the requirements in terms of the operations that need to be called and theirinterleaving. This specification only requires that by the time the RTPS message appears on the wirethe proper encoding operations have been executed first on each SerializedData submessageelement, then on the enclosing RTPS Submessage, and finally on the RTPS Message. Similarlyby the time a received RTPS Message is interpreted the proper decoding operations are executed onthe reverse order. First on the encoded RTPS Message, then on each SecureSubMsg, and finallyon each SecuredData submessage element.8.11.6.1 Encoding/decoding of a single writer message on an RTPS messageThe figure below illustrates the functionality of the security plug-ins with regards to encoding thedata, Submessages and RTPS messages in the situation where the intended RTPS Message containsa single writer RTPS Submessage. 1. The application writes data using a DataWriter belonging to Participant1. The DDS implementation serializes the data.102 DDS Security, Revised Submission
    • 2. The DDS implementation constructs the SerializedData RTPS submessage element and calls the operation CryptoTransform::encode_serialized_data(). This operation creates a RTPS SecuredData that protects the SerializedData poten- tially encrypting it, adding a MAC and/or digital signature. 3. This step is notional; the specific mechanism depends on the DDS Implementation. The DDS Implementation realizes it is time to send the data written by the DataWriter to a remote DataReader. 4. The DDS implementation constructs the RTPS Data Submessage that it will send to the DataReader and calls CryptoTransform::encode_datawriter_submessage() to transform the original Data submessage to a SecureSubMsg. This same transformation would be applied to any DataWriter submessage (Data, Gap, Heartbeat, DataFrag, HeartbeatFrag). The encode_datawriter_submessage() receives as pa- rameters the DatawriterCryptoHandle of the DataWriter and a list of DatareaderCryptoHandle for all the DataReader entities to which the message will be sent. Using a list allows the same SecureSubMsg to be sent to all those DataReader entities. 5. The DDS implementation constructs the RTPS Message it intends to send to the DataReader (or readers). It then calls CryptoTransform::encode_rtps_message() to transform the original RTPS Message into a new “encoded” RTPS Message with the same RTPS header and a single SecureSubMsg protecting the contents of the original RTPS Message. The encode_rtps_message() receives as parameters the ParticipantCryptoHandle of the sending DomainParticipant (Participant1) and a list of ParticipantCryptoHandle for all the DomainParticipant entities to which the message will be sent (Participant2). Using a list enables the DomainParticipant to send the same message (potentially over multicast) to all those DomainParticipant entities. 6. The DDS implementation sends the new “encoded” RTPS Message obtained as a result of the previous step to Participant2. 7. The DDS implementation on Participant2 receives the “encoded” RTPS Message. The DDS implementation parses the message and detects a RTPS SecureSubMsg with the MultiSubmsgFlag (see section 7.2.3.2.1) set to true. This indicates it shall call the CryptoTransform::decode_rtps_message() to transform the “encoded” RTPS Message into an RTPS Message that decodes the RTPS SecureSubMsg and proceed to parse that instead. 8. The DDS implementation on Participant2 encounters parses the RTPS Message resulting from the previous step and encounters a RTPS SecureSubMsg with the Multi- SubmsgFlag (see section 7.2.3.2.1) set to false. This indicates it shall call CryptoTransform::prepare_rtps_submessage() to determine whether this is a Writer submessage or a Reader submessage and obtain theDDS Security, Revised Submission 103
    • DatawriterCryptoHandle and DatareaderCryptoHandle handles it needs to decode the message. This function determines it is a Writer submessage. 9. The DDS implementation calls CryptoTransform::decode_datawriter_submessage() passing in the RTPS SecureSubMsg and obtains the original Data submessage that was the input to the encode_datawriter_submessage() on the DataWriter side. From the Data submessage the DDS implementation extracts the SecuredData submessage element. This operation takes as arguments the DatawriterCryptoHandle and DatareaderCryptoHandle obtained in the previous step. 10. This step is notional; the specific mechanism depends on the DDS Implementation. The DDS Implementation realizes it is time to notify the DataReader and retrieve the actual data sent by the DataWriter. 11. The DDS implementation calls CryptoTransform::decode_serialized_data() passing in the RTPS Se- curedData and obtains the original SerializedData submessage element was the input to the encode_serialized_data() on the DataWriter side. This operation takes as arguments the DatawriterCryptoHandle and DatareaderCryptoHandle obtained in the step 8.8.11.6.2 Encoding/decoding of multiple writer messages on an RTPS messageThe figure below illustrates the functionality of the security plug-ins in the situation where the in-tended RTPS message contains a multiple DataWriter RTPS Submessages, which can repre-sent multiple samples, from the same DataWriter or from multiple DataWriter entities as well asa mix of Data, Heartbeat, Gap, and any other DataWriter RTPS Submessage as definedin section 7.2.1.104 DDS Security, Revised Submission
    • The steps followed to encode and decode multiple Writer Submessages within the same RTPS mes-sage are very similar to the ones used for a single Writer message. The only difference is that on thewriter side can create multiple RTPS Submessages. In this case two Data Submessages and a Heart-beat Submessage, transform each separately using theCryptoTransform::encode_datawriter_submessage(), place them in the sameRTPS message and then transform the RTPS message containing all the resulting SecureSubMsgsubmessages using CryptoTransform::encode_rtps_message().The steps followed to decode the message would then be the inverse ones.Note that the DataWriter entities that are sending the submessages and/or the DataReader entitiesthat are the destination of the different Submessages may be different. In this situation each call toCryptoTransform::encode_serialized_data(),CryptoTransform::encode_datawriter_submessage(),CryptoTransform::decode_datawriter_submessagDDS Security, Revised Submission 105
    • e(), and CryptoTransform::encode_serialized_data(), shall receive the properDatawriterCryptoHandle and DatareaderCryptoHandle handles.8.11.6.3 Encoding/decoding of multiple reader messages on an RTPS messageThe figure below illustrates the functionality of the security plug-ins in the situation where the in-tended RTPS message contains multiple DataReader RTPS submessages from the sameDataReader or from multiple DataReader entities. These include AckNack and NackFragRTPS Submessages as defined in section 7.2.1. 1. This step is notional; the specific mechanism depends on the DDS Implementation. The DDS Implementation on Participant2 realizes it is time to send an AckNack or NackFrag submessage from DataReader to a remote DataWriter. 2. The DDS implementation constructs the AckNack (or any other DataReader RTPS Submessage) and calls the operation CryptoTransform::encode_datareader_submessage(). This operation creates a RTPS SecureSubMsg that protects the original Submessage potentially en- crypting it, adding a MAC and/or digital signature. This operation shall receive as pa- rameter the DatareaderCryptoHandle of the DataReader that sends the submes- sage and a list of DatawriterCryptoHandle handles of all the DataWriter enti- ties to which the Submessage will be sent.106 DDS Security, Revised Submission
    • 3. Step 2 may be repeated multiple times constructing various SecureSubMsg submes- sages from different DataReader RTPS Submessages. Different submessages may originate on different DataReader entities and/or be destined for different DataWriter entities. On each case the encode_datareader_submessage() operation shall re- ceive the DatareaderCryptoHandle and list of DatawriterCryptoHandle that correspond to the source and destinations of that particular Submessage. 4. The DDS Implementation constructs the RTPS Message that contains the SecureSubMsg submessages obtained as a result of the previous steps. It shall then call CryptoTransform::encode_rtps_message(). To transform the “original” RTPS Message into another “encoded” RTPS Message containing a single SecureSubMsg with the MultiSubmsgFlag (see section 7.2.3.2.1) set to true. 5. The DDS implementation sends the “encoded” RTPS Message to Participant1 (and any other destination DomainParticipant). 6. The DDS implementation on Participant1 receives the “encoded” RTPS Message. The DDS implementation parses the message and detects a RTPS SecureSubMsg with the MultiSubmsgFlag (see section 7.2.3.2.1) set to true. This indicates it shall call the CryptoTransform::decode_rtps_message() to transform the “encoded” RTPS Message into an RTPS Message that decodes the RTPS SecureSubMsg and proceed to parse that instead. 7. The DDS implementation on Participant1 encounters parses the RTPS Message resulting from the previous step and encounters a RTPS SecureSubMsg with the Multi- SubmsgFlag (see section 7.2.3.2.1) set to false. This indicates it shall call CryptoTransform::prepare_rtps_submessage() to determine whether this is a DataWriter submessage or a DataReader submessage and obtain the DatawriterCryptoHandle and DatareaderCryptoHandle handles it needs to decode the message. This function determines it is a DataReader submessage. 8. The DDS implementation on Participant1 calls CryptoTransform::decode_datareader_submessage() passing in the RTPS SecureSubMsg and obtains the original AckNack (or proper DataReader Submessage) submessage that was the input to the encode_datareader_submessage() on the DataReader side (Participant2). This operation takes as arguments the DatawriterCryptoHandle and DatareaderCryptoHandle obtained in the previous step. 9. This step is notional; the specific mechanism depends on the DDS Implementation. The DDS Implementation realizes it is time to notify the DataReader of the Acknowledgment, negative acknowledgment or whatever the DataReader Submessage indicated. 10. Each SecureSubMsg encountered within the RTPS Message having the Multi- SubmsgFlag (see section 7.2.3.2.1) set to false is processed in this same way. The operation CryptoTransform::prepare_rtps_submessage() is first invoked and it this indicates it is a DataReader submessage the DDS Implementation shall callDDS Security, Revised Submission 107
    • CryptoTransform::decode_datareader_submessage() on the submes- sage.8.11.6.4 Encoding/decoding of reader and writer messages on an RTPS messageThe figure below illustrates the functionality of the security plug-ins with regards to encoding thedata, Submessages and RTPS messages in the situation where the intended RTPS message containsmultiple RTPS Submessages which can represent a mix of different kinds of DataWriter andDataReader submessages such as Data, Heartbeat, Gap, AckNack, NackFrag and anyother RTPS Submessage as defined in section 7.2.1. 1. The application writes data using a DataWriter belonging to Participant1. The DDS implementation serializes the data. 2. The DDS implementation constructs the SerializedData RTPS submessage element and calls the operation CryptoTransform::encode_serialized_data(). This operation creates a RTPS SecuredData that protects the SerializedData poten- tially encrypting it, adding a MAC and/or digital signature. 3. This step is notional; the specific mechanism depends on the DDS Implementation. The DDS Implementation realizes it is time to send the data written by the DataWriter to a remote DataReader. 4. The DDS implementation constructs the RTPS Data Submessage that it will send to the DataReader and calls108 DDS Security, Revised Submission
    • CryptoTransform::encode_datawriter_submessage() to transform the original Data submessage to a SecureSubMsg. 5. This step is notional. The specifics will depend on the DDS Implementation. The DDS implementation decides it needs to send a Heartbeat submessage along with the Data submessage. It constructs the RTPS Heartbeat submessage and calls CryptoTransform::encode_datawriter_submessage() to transform the original Heartbeat submessage to a SecureSubMsg. 6. This step is notional; the specific mechanism depends on the DDS Implementation. The DDS Implementation on Participant1 decides it also want to include an RTPS AckNack submessage from a DataReader that also belongs to Participant1 into the same RTPS Message because it is destined to the same Participant2. 7. The DDS Implementation constructs the RTPS AckNack submessage and calls CryptoTransform::encode_datareader_submessage() to transform the original AckNack submessage to a SecureSubMsg. 8. The DDS Implementation constructs the RTPS Message that contains the SecureSubMsg submessages obtained as a result of the previous steps. It shall then call CryptoTransform::encode_rtps_message(). To transform the “original” RTPS Message into another “encoded” RTPS Message containing a single SecureSubMsg with the MultiSubmsgFlag (see section 7.2.3.2.1) set to true. 9. The DDS implementation sends the “encoded” RTPS Message to Participant2 (and any other destination DomainParticipant). 10. The DDS implementation on Participant2 receives the “encoded” RTPS Message. The DDS implementation parses the message and detects a RTPS SecureSubMsg with the MultiSubmsgFlag (see section 7.2.3.2.1) set to true. This indicates it shall call the CryptoTransform::decode_rtps_message() to transform the “encoded” RTPS Message into an RTPS Message that decodes the RTPS SecureSubMsg and proceed to parse that instead. 11. The DDS implementation on Participant2 encounters parses the RTPS Message resulting from the previous step and encounters a RTPS SecureSubMsg with the Multi- SubmsgFlag (see section 7.2.3.2.1) set to false. This indicates it shall call CryptoTransform::prepare_rtps_submessage() to determine whether this is a DataWriter submessage or a DataReader submessage and obtain the DatawriterCryptoHandle and DatareaderCryptoHandle handles it needs to decode the message. This function determines it is a DataWriter submessage. 12. The DDS implementation on Participant1 calls CryptoTransform::decode_datawriter_submessage() passing in the RTPS SecureSubMsg and obtains the original Data submessage that was the input to the encode_datarwriter_submessage() on Participant1. This operation takes as arguments the DatawriterCryptoHandle and DatareaderCryptoHandle obtained in the previous step.DDS Security, Revised Submission 109
    • 13. This step is notional; the specific mechanism depends on the DDS Implementation. The DDS Implementation realizes it is time to notify the DataReader of the arrival of data. 14. The DDS implementation calls CryptoTransform::decode_serialized_data() passing in the RTPS Se- curedData and obtains the original SerializedData submessage element was the input to the encode_serialized_data() on the Participant1 side. This operation takes as arguments the DatawriterCryptoHandle and DatareaderCryptoHandle obtained in the step 11. 15. Step 11 is repeated. It is again determined that the next SecureSubMsg is a DataWriter submessage and the proper DatawriterCryptoHandle and DatareaderCryptoHandle handles are retrieved. 16. Step 12 is repeated, CryptoTransform::decode_datawriter_submessage() passing in the RTPS SecureSubMsg and it transforms it into the original Heartbeat submessage. 17. This step is notional; the specific mechanism depends on the DDS Implementation. The DDS Implementation notifies DataReader of the Heartbeat. 18. Step 11 is repeated. It is determined that the next SecureSubMsg is a DataReader submessage and the proper DatawriterCryptoHandle and DatareaderCryptoHandle handles are retrieved. 19. The DDS implementation on Participant1 calls CryptoTransform::decode_datareader_submessage() passing in the RTPS SecureSubMsg and obtains the original AckNack submessage that was the in- put to the encode_datarwreader_submessage() on the Participant1. This opera- tion takes as arguments the DatawriterCryptoHandle and DatareaderCryptoHandle obtained in the previous step. 20. This step is notional; the specific mechanism depends on the DDS Implementation. The DDS Implementation notifies DataWriter of the AckNack.110 DDS Security, Revised Submission
    • 9 Built-in PluginsThis specification defines the behavior and implementation of at least one built-in plugin of eachplugin kind. The built-in plugins provide out-of-the-box interoperability between implementations ofthis specification.The built-in plugins are summarized in the table below: SPI   Plugin Name   Description  Authentication   DDS:Auth:PKI-­‐RSA/DSA-­‐DH   Uses  PKI  with  a  pre-­‐configured  shared  Cer-­‐ tificate  Authority.   RSA  or  DSA  and  Diffie-­‐Hellman  for  authenti-­‐ cation  and  key  exchange.    AccessControl   10 DDS:Access:PKI-­‐Signed-­‐XML-­‐ Permissions document signed by shared Permissions   Certificate Authority  Cryptography   11 DDS:Crypto:AES-­‐CTR-­‐HMAC-­‐ AES128 for encryption (in counter mode)   RSA/DSA-­‐DH   SHA1 and SHA256 for digest   HMAC-SHA1 and HMAC-256 for MAC  DataTagging   DDS:Tagging:DDS_Discovery   Send Tags via Endpoint Discovery  Logging   DDS:Loging:DDS_LogTopic   Logs  security  events  to  a  dedicated  DDS  Log   Topic  11.1 Requirements and prioritiesThe selection of the built-in plugins was driven by several functional as well as non-functional re-quirements.Most DDS users surveyed consider the following functional requirements as essential to be providedby the secure DDS middleware: • Authentication of applications (DDS Domain Participants) joining a DDS Domain • Access control of subscribing applications to specific data, at the Domain and Topic level • Message integrity and authentication • Encryption of the data sample using different encryption keys for different TopicsDDS Security, Revised Submission 111
    • In addition to these essential needs, many users also required the secure DDS middleware shouldprovide for: • Sending digitally signed data samples • Sending data securely over multicast • Tagging data • Integration with open standard security plug-insOther functional requirements are considered useful but less common: • Access control to certain samples within a Topic but not others, the access rights being granted according to the data-sample contents or the data-sample key • Access control to certain attributes within a data sample but not others such that certain DataReader entities can only observe a subset of the attributes, which depends on their per- missions. • Permissions that control which QoS might be used by a specific DDS Entity: DomainPartici- pant, Publisher, DataWriter, Subscriber, or DataReader.The main non-functional requirements that informed the selection of the built-in plugins are • Performance and Scalability • Robustness and Availability • Fit to the DDS Data-Centric Information Model • Leverage and reuse of existing security infrastructure and technologies • Ease of use while supporting common application requirements11.1.1 Performance and ScalabilityDDS is commonly deployed in systems that demand high-performance and need to scale to largenumbers of processes and computers. Different applications vary greatly in the number of processes,Topics, and or data-objects belonging to each Topic.The policy enforcement/decision points as well as the transformations (cipher, decipher, hash) per-formed by the plugins should not adversely degrade system performance and scalability beyond whatis tolerable and strictly needed. In practice this means several things for the built-in plugins: • The use of Asymmetric Key Cryptography shall be limited to the discovery and session- establishment phase (i.e. when a Participant discovers another Participant, a DataReader and matching DataWriter, and so on). • The use of ciphers, HMACs, or digital signatures shall be selectable on a per stream (Topic) basis. In case of encryption, symmetric ciphers should be used for the application data. • It shall be possible to provide integrity via HMAC techniques without also requiring the data to be ciphered.112 DDS Security, Revised Submission
    • • Multicast shall be supported even for ciphered data.11.1.2 Robustness and AvailabilityDDS is deployed in mission critical systems, which must continue to operate 24/7 despite partial sys-tem malfunction. It also operates in fielded environments where specific components or systems maybe subject to accidental failure or active attack. DDS itself provides a highly robust infrastructurethanks to the way the communication model and protocols are defined as they can be (and commonlyare) implemented in a peer-to-peer fashion without any centralized services. For this reason manyDDS implementations have no single points of failure.The built-in plugins should not negate these desirable properties present in the underlying DDS mid-dleware infrastructure.In practice this means that: • Centralized policy decision points or services should be avoided. • The individual DDS DomainParticipant components should be self-contained and have what they need to operate securely even in the presence of system partitions. • Multi-party key agreement protocols shall be avoided as they become easily disrupted by dis- rupting one party. • Security tokens and keys should be compartmentalized as much as possible such that com- promise of an application component is contained to that component itself. For example se- lection of a system-wide secret key for the whole Domain or even for a Topic should be avoided.11.1.3 Fitness to the DDS Data-Centric ModelApplication developers that use DDS think in terms of the data-centric elements that DDS provides.That is, they think first and foremost about the Domains (global data spaces) the application mustjoin and the Topics that it needs to read and write. Therefore the built-in plugins should offer thepossibility to control access with this level of granularity.Users of DDS also think about the data-objects (keyed instances) they read and write, the ability todispose instances, filter by content, set QoS, and so forth. While it may be useful to offer ways toprovide access controls to this as well, it was considered of lesser priority and potentially conflictingwith the goal of ease of configurability and maintainability.The semantics of DDS communications require that individual samples can be consumed independ-ently of each other. Depending on the QoS policy settings samples written by a single DataWritermay be received and processed out of order relative to the order sent, or may be received with inter-mediate gaps resulting from best-effort communication (if selected), or may be filtered by content,time, or history, etc. For this reason any encryption and/or digital signature applied to a sampleshould be able to be processed in isolation, without requiring the receiver to maintain a specific con-text reconstructed from previous samples.DDS Security, Revised Submission 113
    • 11.1.4 Leverage and reuse of existing security infrastructure and technologiesTo the extent possible it is desirable that the built-in plugins leverage and reuse existing IA technol-ogy and tools. This not only reduces the barrier of entry for implementers of the specification, butalso more importantly enhances the quality of the result by allowing the use of proven, peer-reviewed, and/or already certified approaches. The built-in plugins leverage existing standards andtools for PKI, ciphers, hashing and digital signing. To the extent possible, ideas and approaches fromexisting protocols for key management and secure multicast are also leveraged, although where ap-propriate they have been adapted to the data-centric communications model of DDS and the DDS-RTPS wire protocol.11.1.5 Ease of use while supporting common application requirementsIt is anticipated that specialized applications may need to develop their own security plugins to eitherintegrate existing security infrastructure or meet specialized requirements. Therefore the primaryconsumers of the built-in plugins will be users that want to secure their systems but not have com-plex needs or significant legacy components. Under these conditions ease of use is essential. A secu-rity infrastructure that is too hard to configure or complex to understand or maintain is less likely tobe used, or may be used wrongly, resulting in systems that are less secure overall.The built-in plugins balance rich functionality and ease of use, providing for the most common usecases, in a manner that is easy to understand and use correctly.11.2 Built-in Authentication: DDS:Auth:PKI-RSA/DSA-DHThis built-in authentication plugin is referred to as the “DDS:Auth:PKI-RSA/DSA-DH”.The DDS:Auth:PKI-RSA/DSA-DH plugin implements authentication using a trustedCertificate Authority (CA), it performs mutual authentication between discovered partici-pants using the Digital Signature Algorithm (DSA) [4] and establishes a shared secret using Diffie-Hellman (D-H) Key Agreement Method [5].The CA could be an existing one. Or a new one could be created for the purpose of deploying appli-cations on a DDS Domain. The nature or manner in which the CA is selected is not important be-cause the way it is used enforces a shared recognition by all participating applications.Prior to being enabled the DDS: Auth: PKI-RSA/DSA-DH plugin that is associated with each Do-mainParticipant must be configured with three things: 1. The X.509 Certificate that defines the Shared CA. This certificate contains the Public Key of the CA. 2. The RSA Private Key of the DomainParticipant. 3. An X.509 Certificate that chains up to the CA, that binds the RSA Public Key of the DomainParticipant to the distinguished name (subject name) for the DomainParticipant and any intermediate CA certificates required to build the chain114 DDS Security, Revised Submission
    • 11.2.1 ConfigurationThe specific format of the root CA certificate, the private key of the DomainParticipant, and the cer-tificate for the DomainParticipant is not dictated by this specification. Implementations may usestandard formats for certificates and keys and configure them using an API, an extended QoS Policy,or use a specially named domain participant property that is read by the DDS: Auth:PKI-RSA/DSA-DH plugin.Leaving unspecified the details of the DDS:Auth:PKI-RSA/DSA-DH plugin configuration does notaffect interoperability and might be required to accommodate different security concerns and plat-forms (e.g. some platforms may provide specialized secure storage for holding private keys, othersmay not support a file system, etc.).Domain Participants should use Certificate Revocation Lists (CRLs) and/or OCSP to check for re-voked certificates.11.2.2 DDS:Auth:PKI-RSA/DSA-DH Types<NOTE: THIS SECTION IS STILL PRELIMINARY ANDINCOMPLETE>This section specifies the content and format of the Credentials and Tokens used by theDDS:Auth:PKI-RSA/DSA-DH plugin.The content of the Handle objects is not specified as it represents references to internal state that isonly understood by the plugin itself. The DDS Implementation only needs to hold a reference to theretuned value from the plugin and pass it to the appropriate calls.11.2.2.1 DDS:Auth:PKI-RSA/DSA-DH IdentityCredentialThe DDS:Auth:PKI-RSA/DSA-DH plugin shall set the attributes of the IdentityCredential objects asspecified in the table below: Attribute name   Attribute value  credential_classid   “DDS:Auth:X.509-­‐PEM”  properties   This  specification  does  not  define  any  required  values  for  the  proper-­‐ ties.  However  it  reserves  all  properties  with  names  starting  with  the   prefix  “dds.”  For  future  versions  of  the  specification.   Specific  implementations  of  the  plugin  may  use  the  contents  of  this   attribute  to  configure  internal  behavior  as  long  as  the  externally  ob-­‐ servable  behavior  complies  with  this  specification.value   Octet  sequence  containing  the  characters  in  the  PEM-­‐encoded  X.509   certificate  for  the  DomainParticipant  signed  by  the  shared  Certificate   Authority.  private_value   Octet  sequence  containing  the  characters  in  the  PEM-­‐encoded  RSA  DDS Security, Revised Submission 115
    • Private  Key  associated  with  the  Public  Key,  which  was  signed  in  the   certificate  contained  in  the  value  attribute.  11.2.2.2 DDS:Auth:PKI-RSA/DSA-DH IdentityTokenThe DDS:Auth:PKI-RSA/DSA-DH plugin shall set the attributes of the IdentityToken object asspecified in the table below: Attribute  name   Attribute  value  token_classid   “DDS:Auth:X.509-­‐PEM”  wrapper_classid   The  empty  string  properties   This  specification  does  not  define  any  required  values  for  the  proper-­‐ ties.  However  it  reserves  all  properties  with  names  starting  with  the   prefix  “dds.”  For  future  versions  of  the  specification.   Specific  implementations  of  the  plugin  may  use  the  contents  of  this   attribute  to  configure  internal  behavior  as  long  as  the  externally  ob-­‐ servable  behavior  complies  with  this  specification.  value   Octet  sequence  containing  the  characters  in  the  PEM-­‐encoded  X.509   certificate  for  the  DomainParticipant  signed  by  the  shared  Certificate   Authority.  wrapped_value   The  empty  sequence.  11.2.2.3 DDS:Auth:PKI-RSA/DSA-DH MessageTokenThe DDS:Auth:PKI-RSA/DSA-DH plugin uses several MessageToken object formats:• HandshakeRequestMessageToken objects• HandshakeReplyMessgeToken objects• HandshakeFinalMessageToken objects11.2.2.3.1 HandshakeRequestMessageToken objectsThe attributes in HandshakeRequestMessageToken objects are set as specified in the table below: Attribute  name   Attribute  value  token_classid   The  string  can  be  set  to  either  “DDS:Auth:ChallengeReq:PKI-­‐DH”  or   “DDS:Auth:ChallengeReq:PKI-­‐RSA”.    Both  values  shall  be  supported.  wrapper_classid   The  empty  string  properties   This  specification  does  not  define  any  required  values  for  the  proper-­‐ ties.  However  it  reserves  all  properties  with  names  starting  with  the   prefix  “dds.”  For  future  versions  of  the  specification.116 DDS Security, Revised Submission
    • value   The  value  of  this  octet  Sequence  shall  be  set  to  a  NONCE  whose  first   10  octets  are  set  to  match  those  in  the  string:  “CHALLENGE:”  wrapped_value   The  empty  sequence.  11.2.2.3.2 HandshakeReplyMessageTokenThe attributes in the HandshakeReplyMessageToken objects are set as specified in the tablebelow: Attribute  name   Attribute  value  token_classid   The  string  can  be  set  to  either  “DDS:Auth:ChallengeRep:PKI-­‐DH”  or   “DDS:Auth:ChallengeRep:PKI-­‐RSA”.    Both  values  shall  be  supported.  wrapper_classid   The  string  can  be  set  to  either  “DDS:Auth:Challenge:PKI-­‐DH”  or   “DDS:Auth:Challenge:PKI-­‐RSA”.    Both  values  shall  be  supported.  properties   This  specification  does  not  define  any  required  values  for  the  proper-­‐ ties.  However  it  reserves  all  properties  with  names  starting  with  the   prefix  “dds.”  For  future  versions  of  the  specification.value   The  value  of  this  octet  sequence  shall  be  set  to  a  NONCE  whose  first   16  octets  are  set  to  match  those  in  the  string:  “CHALLENGE-­‐REPLY:”    wrapped_value   The  value  of  this  octet  sequence  shall  be  set  to  the  result  of  signing   the  SHA-­‐256  hash  of  the  value  attribute  of  a  previously-­‐received   HandshakeRequestMessageToken    object    with  the  private  key  asso-­‐ ciated  with  the  DomainParticipant  that  creates  the  HandshakeRe-­‐ plyMessageToken  object.11.2.2.3.3 HandshakeFinalMessageTokenHandshakeFinalMessageToken objects are used to finish an authentication handshake andcommunicate a SharedSecret. The SharedSecret shall be a 256-bit random number gener-ated using a cryptographycally-strong random number generator. Each createdHandshakeFinalMessageToken shall have associated a unique SharedSecret.The attributes in the HandshakeFinalMessageToken objects are set as specified in the table below. Attribute  name   Attribute  value  token_classid   The  string  can  be  set  to  either  “DDS:Auth:ChallengeFin:PKI-­‐DH”  or   “DDS:Auth:ChallengeFin:PKI-­‐RSA”.    Both  values  shall  be  supported.  wrapper_classid   The  string  can  be  set  to  either  “DDS:Auth:Challenge:DSA-­‐SHA256”  or   “DDS:Auth:Challenge:RSA-­‐SHA256”.    Both  values  shall  be  supported.properties   This  specification  does  not  define  any  required  values  for  the  proper-­‐ ties.  However  it  reserves  all  properties  with  names  starting  with  the   prefix  “dds.”  For  future  versions  of  the  specification.value   Set  to  the  result  of  encrypting  the  SharedSecret  associated  with   the  HandshakeFinalMessageToken  with  the  Public  Key  of  the  remote  DDS Security, Revised Submission 117
    • DomainParticipant  that  is  the  destination  of  the  HandshakeFinalM-­‐ essageToken.wrapped_value   The  bytes  in  this  octet  sequence  shall  be  set  to  the  result  of  signing   the  SHA-­‐256  hash  of  the  value  attribute  of  a  previously-­‐received   HandshakeReplyMessageToken    object    with  the  private  key  associ-­‐ ated  with  the  DomainParticipant  that  creates  the  HandshakeFinalM-­‐ essageToken  object.11.2.3 Behavior of the DDS:Auth:PKI-RSA/DSA-DH pluginThe table below describes the actions that the DDS:Auth:PKI-RSA/DSA-DH plugin performs wheneach of the plugin operations is invoked.validate_local_ide This operation shall receive thentity participant_key associated with the local participant whose identity is being validated. This operation shall receive the identity_credential containing an the IdentityCredential object with the contents described in Section 11.2.2.1. The operation shall verify the validity of the certificate using the configured CA. The operation shall check a CRL and/or an OCSP (RFC 2560) responder. This includes checking the expiration date of the certificate. If the above check fails the operation shall return VALIDATION_FAILED. The operation shall fill the handle with an implementation-dependent reference that allows the implementation to retrieve at least the following information: 1. The private key associated with the identity_credential 2. The public key associated with the identity_credential. 3. The participant_key. If successful the operation shall return VALIDATION_OK.118 DDS Security, Revised Submission
    • get_identity_token The operation shall receive the handle corresponding to the one returned by a successful previous call to validate_local_identity. If the above condition is not met the operation shall return the exception DDS_SecurityException_PreconditionError. This operation shall return an IdentityToken object with the content specified in section 11.2.2.2.validate_remote_id The operation shall receive theentity IdentityToken of the remote participant in the argument remote_identity_token. The contents of the IdentityToken shall identical to what would be returned by a call to get_identity_token on the AuthenticationPlugin of the remote participant associated with the remote_participant_key. The operation shall verify the validity of the certificate contained in the remote_identity_token value attribute using the locally configured CA in the same manner as the validate_local_identity operation. If the remote_identity_token does not have the correct format or the verification fails then the operation shall fail und return ValidationResult_Fail. If the verification succeeds the operation shall compare lexicographically the remote_participant_key with the participant key obtained from the local_identity_handle. If the remote_participant_key > local participant_key the operation shall return VALIDATION_PENDING_HANDSHAKE_REQUEST If the remote_participant_key < local participant_key the operation shall return VALIDATION_PENDING_HANDSHAKE_MESSAGE. In both scenarios the remote_identity_handle shall be filled with a referece to internal plugin information that identifies theDDS Security, Revised Submission 119
    • remote participant and associates it to the remote_identity_token and any additional information requied for the challenge protocol.begin_handshake_re The operation shall receive thequest initiator_identity_handle corresponding to the local_identity_handle of a previous invocation to the validate_remote_identity operation that returned VALIDATION_PENDING_HANDSHAKE_REQUEST. The operation shall also receive the replier_identity_handle corresponding to the remote_identity_handle returned by that same invocation to the validate_remote_identity operation. The operation shall return the handshake_message containing a HandshakeRequestMessageToken object with contents as defined in section 11.2.2.3.1. The operation shall fill the handshake_handle with an implementation- dependent reference that allows the implementation to retrieve at least the following information: 1. The local_identity_handle 2. The remote_identity_handle 3. The value attribute of the handshake_message returned. The operation shall return VALIDATION_PENDING_HANDSHAKE_MESSAGEbegin_handshake_re The operation shall receive theply replier_identity_handle corresponding to local_identity_handle of a previous invocation to the validate_remote_identity operation that returned VALIDATION_PENDING_CHALLENGE_MESSAGE. The operation shall also receive the initiator_identity_handle corresponding to120 DDS Security, Revised Submission
    • the remote_identity_handle returned by that same invocation to the validate_remote_identity operation. If any of the above conditons is not met the operation shall return the exception DDS_SecurityException_PreconditionError. The operation shall fill the handshake_message_out with a HandnshakeReplyMessage object with the content specified in section 11.2.2.3.2. Specifically the wrapped_value attribute shall be set to the result of signing the SHA-256 hash of the received handshake_message_in value attribute with the private key associated with the replier_identity_handle. The operation shall fill the handshake_handle with an implementation- dependent reference that allows the implementation to retrieve at least the following information: 1. The replier_identity_handle 2. The initiator_identity_handle 3. The value attribute of the challenge_message returned. The operation shall return VALIDATION_PENDING_CHALLENGE_MESSAGEproceess_handshake The operation shall be called with the handshake_handle returned by a previous callon a to begin_handshake_request that retunedhandshake_handle VALIDATION_PENDING_CHALLENGE_MESSAGEcreated by The handshake_message_in shall correspond tobegin_handshake_re a HandshakeReplyMessageToken object receivedquest() as a reply to the handshake_message HandshakeRequestmessageToken object associated with the handshake_handle. If any of the above conditons is not met the operation shall return the exception DDS_SecurityException_PreconditionError. The operation shall verify that the contents of the handshake_message_in correspond to a HandshakeReplyMessageToken as described inDDS Security, Revised Submission 121
    • section 11.2.2.3.2. The operation shall verify that the contents of the wrapped_value correspond the digital signature of the value in the handshake message associated with the handshake_handle. This signature shall be verified with the public key of the remote participant associated with the handshake_handle. If the specified verification on the wrapped_value does not succeed the operation shall return VALIDATION_FAILED If the specified verification on the wrapped_value succeeds, then the operation shall generate a 256-bit random number to be used as a shared_secret using a cryptographycally-strong random number generator. The operation shall create a HandshakeFinalMessageToken object with an associated SharedSecret as described in section 11.2.2.3.3. The operation shall fill the handshake_message_out with the created HandshakeFinalMessageToken object. Specifically: • The handshake_message_out value attribute shall contain the result of encrypting the SharedSecret with the public key of the remote participant associated with the handshake_handle. • The handshake_message_out wrapped_value shall contain the result of signing the SHA-256 hash of the handshake_message_in value attribute concatenated with the contents of the handshake_message_out value attribute. This signature shall use the private key of the local participant associated with handshake_handle. The operation shall save the SharedSecret in the hansdhake_handle and return VALIDATION_OK_WITH_FINAL_MESSAGE.122 DDS Security, Revised Submission
    • process_handshake The operation shall be called with the handshake_handle returned by a previous callon a to begin_handshake_reply that retunedhandshake_handle VALIDATION_PENDING_HANDSHAKE_MESSAGEcreated by The handshake_message_in shall correspond tobegin_handshake_re the one received as a reply to theply() handshake_message_out associated with the handshake_handle. If any of the above conditons is not met the operation shall return the exception DDS_SecurityException_PreconditionError. The operation shall verify that the contents of the handshake_message_in correspond to a HandshakeFinalMessageToken object as described in section 11.2.2.3.3. The contents of the handshake_message_in value wrapped_value attribute shall be verified with the public key of the remote participant. The contents of the handshake_message_in value attribute shall be decrypted with the private key of the local participant associated with the handshake_handle. The result shall be saved as the SharedSecret and be associated with the hansdhake_handle. If the specified verification on the wrapped_value does not succeed the operation shall return VALIDATION_FAIL If specified verification on the wrapped_value succeeds, then the operation shall return VALIDATION_OK.get_shared_secret This operation shall be called with the handshake_handle that was previously used to call either process_handshake and for which the aforementioned operation returned VALIDATION_OK_WITH_FINAL_MESSAGE or VALIDATION_OK. If the above conditon is not met the operation shall return the exception DDS_SecurityException_PreconditionError. The operation shall return aDDS Security, Revised Submission 123
    • SharedSecretHandle that is ineternalli associated with the SharedSecret stablished as part of the handshake. On failure the operation shall return nil.return_handshake_h This operation shall be called with aandle handshake_handle returned by a previous call to either begin_handshake_request or begin_handshake_reply If the above conditon is not met the operation shall return the exception DDS_SecurityException_PreconditionError. The operation shall release all resources associated with the handshake_handle. The operation shall return True.get_identity_token This operation shall return an IdentityToken. The IdentityToken classid field shall contain the string “x509-PEM” The IdentityToken value field shall contain the PEM-encoded X.509 certificate for the DomainParticipant. This is the same sequence that was either passed as a IdentityCredential to the validate_local_identity operation or inside the IdentityToken passed to the validate_remote_identity operation.set_listener This operation shall save a reference to the listener object and associate it with the specified IdentityHandle124 DDS Security, Revised Submission
    • 11.2.4 Wire protocol implemented by the DDS:Auth:PKI-RSA/DSA- DH pluginThe operations the Secure DDS implementation executes on the AuthenticationPlugin combinedwith the behavior of the DDS:Auth:PKI-RSA/DSA-DH result on a efficient 3-message protocol thatperforms mutual authentication and establishes a shared secret.The rest of this section describes the resulting protocol.The authentication protocol is symmetric, that is there are no client and server roles. But only oneDomainParticipant should initiate the protocol. To determine which of the twoDomainParticipant entities shall initiate the protocol, each DomainParticipant comparesits own GUID with that of the other DomainParticipant. The DomainParticipant with thelower GUID (using lexicographical order) initiates the protocol.11.2.4.1 Terms and notationThe table below summarizes the terms used in the description of the protocol term   meaning  Participant_A   The  DomainParticipant  that  initiates  the  protocol.  Participant_B   The  DomainParticipant  that  does  not  initiate  the  protocol.  PubK_A   The  Public  Key  of  Participant_A  PubK_B   The  Public  Key  of  Participant_B  PrivK_A   The  Private  Key  of  Participant_A  PrivK_B   The  Private  Key  of  Participant_B  Cert_A   The    Certificate  (signed  by  the  shared  CA)  of  Participant  A.  It  contains  PubK_A  Cert_B   The    Certificate  (signed  by  the  shared  CA)  of  Participant  B.  It  contains  PubK_B  Challenge_A   The  challenge  created  by  Participant_A  by  calling  begin_handshake_request()   on  the  Authentication  Plugin.  Essentially  the  String  “CHALLENGE:”  concate-­‐ nated  with  a  NONCE  Challenge_B   The  challenge  created  by  Participant_B  by  calling  begin_handshake_reply()  on   the  Authentication  Plugin.  Essentially  the  String  “CHALLENGE-­‐REPLY:”  con-­‐ catenated  with  a  NONCE.  SharedSecret   A  cryptographically  strong  random  number  generated  with  the  purpose  of   establishing  a  shared  secret  between  Participant_A  and  Participant_B  The table below summarizes the notation and transformation functions used in the description of theprotocol: Function  /  notation   meaning  Sign(data)   Signs  the  ‘data’  argument  using  the  Private  Key.  DDS Security, Revised Submission 125
    • Encrypt(PubK,  data).   Encrypts  the  data  using  the  public  key  PubK  Hash(data)   Hashes  the  ‘data’  argument    using  SHA-­‐256.  data1  #  data2   The  symbol  ‘#’  is  used  to  indicate  byte  concatenation  11.2.4.2 Protocol descriptionThe table below describes the resulting 3-way protocol that establishes authentication and a sharedsecret between Participant_A and Participant_B. Participant  A   Participant  B  Is  configured  with  PrivK_A  ,  Cert_A  (and  thus   Is  configured  with  PrivK_B,  Cert_B    (and  thus  PubK_A  )   PubK_B)  Receives  Cert_B  (and  thus  PubK_B)  via  Partici-­‐ Receives  Cert_A  (and  thus  PubK_A  )  via  Partici-­‐pant  Discovery.     pant  Discovery.    Verifies  Cert_B  when  it  discovers  Participant_B   Verifies  Cert_A  when  it  discovers  Participant_A      Generates  a  random  challenge_A  and  sends:  MessageToken: (challenge_A)   Generates  a  random  challenge_B  and  sends:   MessageToken: ( Sign(challenge_A), challenge_B)  Verifies  Sign(challenge_A)against  PubK_B    Generates  SharedSecret  and  encrypts  it  using  PubK_B,  resulting  on:            Encrypt(PubK_B, SharedSecret)Hashes  challenge_B  concatenated  with  the  previ-­‐ous  encrypted  shared  secret  Signs  the  hash.  Sends:  MessageToken: ( Encrypt(PubK_B, SharedSecret),126 DDS Security, Revised Submission
    • Sign( Hash( challenge_B # Encrypt(PubK_B, SharedSecret))))   Verifies  the  signature  over  the  hash  and  de-­‐ crypts  the  SharedSecret.11.3 Built-in Access Control Plugin: DDS:Access:PKI-Signed- XML-PermissionsThis built-in Access Control plugin is referred to as the “DDS:Access:PKI-Signed-XML-Permissions” plugin.The DDS:Access:PKI-Signed-XML-Permissions implements the AccessControl Plugin API using apermissions document signed by a shared Certificate Authority (CA).The shared CA could be an existing one (including the same CA used for the Authentication Plugin),or a new one could be created for the purpose of assigning permissions to the applications on a DDSDomain. The nature or manner in which the CA is selected is not important because the way it isused enforces a shared recognition by all participating applications.Each DomainParticipant has associated an instance of the DDS:Access:PKI-Signed-XML-Permissions plugin. Prior to being enabled the DDS:Access:PKI-Signed-XML-Permissions must beconfigured with three things: 1. The x.509 certificate that identifies the CA to be used for signing the Permissions Tokens. This certificate contains the Public Key of the shared CA. 2. The DomainParticipant permissions document formatted as described in subsequent sections. 3. The PermissionsToken, which contains the digital signature of the permissions document signed by the shared permissions CA.11.3.1 ConfigurationThe way the DDS:Access:PKI-Signed-XML-Permissions is configured with self-signed x.509 cer-tificate of the permissions CA is not specified. It can be done in an implementation dependent way.The fact that this is not specified does not affect interoperability.11.3.1.1 DomainParticipant permissions documentThe permissions document is an XML document containing the permissions of the domain partici-pant and binding them to the distinguished name of the DomainParticipant as defined in theDDS:Auth:PKI-RSA/DSA-DH authentication plugin.The format of this document defined using the following XSD.DDS Security, Revised Submission 127
    • <?xml  version="1.0"  encoding="utf-­‐16"?>  <xs:schema  elementFormDefault="qualified"  attributeFormDefault="unqualified"  xmlns:xs="http://www.w3.org/2001/XMLSchema">          </xs:element  name="permissions"  type="Permissions">          <xs:complexType  name="Permissions">                  <xs:sequence  minOccurs="1"  maxOccurs="1">                          <xs:element  name="validity"  type="Validity"  />                          <xs:element  name="subject_name"  type="xs:string"  />                          <xs:choice  minOccurs="1"  maxOccurs="1">                                  </xs:element  name="allow_with_exceptions"  minOccurs="0"  type="AllowedPermissions">                                  </xs:element  name="deny_with_exceptions"  minOccurs="0"  type="DeniedPermissions">                          </xs:choice>                          </xs:element  name="extra_tags"  type="Tags"  minOccurs="0"  maxOccurs="1">                  </xs:sequence>          </xs:complexType>          <xs:complexType  name="Validity">                  <xs:sequence  minOccurs="1"  maxOccurs="1">                          <xs:element  name="not_before"  type="xs:string"  />                          <xs:element  name="not_after"  type="xs:string"  />                  </xs:sequence>          </xs:complexType>          <xs:complexType  name="AllowedPermissions">                  <xs:sequence  minOccurs="1"  maxOccurs="1">                          <xs:element  name="domain_id"  type="xs:string"  />                          <xs:sequence  minOccurs="1"  maxOccurs="unbounded">                                  <xs:element  name="allow"  type="PermissionExpression"  />                                  <xs:element  name="exception"  type="PermissionExpression"  />                          </xs:sequence>                  </xs:sequence>          </xs:complexType>          <xs:complexType  name="DeniedPermissions">                  <xs:sequence  minOccurs="1"  maxOccurs="1">                          <xs:element  name="domain_id"  type="xs:string"  />                          <xs:sequence  minOccurs="1"  maxOccurs="unbounded">                                  <xs:element  name="deny"  type="PermissionExpression"  />                                  <xs:element  name="exception"  type="PermissionExpression"  />                          </xs:sequence>                  </xs:sequence>          </xs:complexType>          <xs:complexType  name="PermissionExpression">                  <xs:choice  minOccurs="0"  maxOccurs="unbounded">                          </xs:element  name="publish"  minOccurs="0"  type="TopicExpression">                          </xs:element  name="subscribe"  minOccurs="0"  type="TopicExpression">                  </xs:choice>          </xs:complexType>          <xs:simpleType  name="TopicExpression">                  </xs:restriction  base="xs:string">  128 DDS Security, Revised Submission
    •        </xs:simpleType>          <xs:complexType  name="Tags">                  <xs:sequence  minOccurs="1"  maxOccurs="unbounded">                          </xs:element  name="tag"  type="TagValue">                  </xs:sequence>          </xs:complexType>          <xs:complexType  name="TagValue">                  <xs:sequence  minOccurs="1"  maxOccurs="unbounded">                          </xs:element  name="name"  type="xs:string">                          </xs:element  name="value"  type="xs:string">                  </xs:sequence>          </xs:complexType>  </xs:schema>The following is an example permissions document that complies with this format:<?xml  version="1.0"  encoding="utf-­‐16"?>  <permisions  xsi:noNamespaceSchemaLocation="omg_shared_ca_permissions.xsd"      xmlns:xsi="http://www.w3.org/2001/XMLSchema-­‐instance">          <validity>                  <!-­‐-­‐  Format  is  YYYYMMDDHH  in  GMT-­‐-­‐>                  <not_before>2012060113</not_before>                  <not_after>2013060113</not_after>          </validity>          <subject_name>/C=US/ST=CA/L=Sunnyvale/O=ACME  Inc./OU=CTO  Office/CN=DDS  Shapes  Demo/emailAddress=cto@acme.com</subject_name>          <allow_with_exceptions>                  <domain_id>0</domain_id>                  <allow>                          <publish>Sq*</publish>                          <subscribe>Circle</subscribe>                  </allow>                  <exception>                          <publish>SquareExtra</publish>                  </exception>          </allow_with_exceptions>          <extra_tags>                  <tag>                          <name>aTagName</name>                          <value>aTagValue</value>                  </tag>          </extra_tags>  </permissions>The XML permissions document consists of four sections: 1. Validity Section (validity element)DDS Security, Revised Submission 129
    • 2. Subject name Section (subject_name element) 3. Permissions Section (allow_with_exception or deny_with_exception elements) 4. Extra Tags Section (extra_tags element)The contents and delimiters of each section are described below.11.3.1.1.1 Validity SectionThis section is delimited by the XML element <validity>. The contents of this element reflect thevalid dates for the certificate. It contains both the starting date and the end date in GMT formatted asYYYYMMDDHH.11.3.1.1.2 Subject name SectionThis section is delimited by the XML element <subject_name>. The contents of this element shallbe the x.509 subject name for the DomainParticipant as is given in its Authorization Certificate. Thex.509 name is a set of name-value pairs. In order for implementations of this specification to inter-operate correctly the format of this name within the XML document must be uniquely defined. Therepresentation chosen is the same used by openssl to print subject names. That is each. The succes-sive names-values appear in a single string, separated by the forward slash character ‘/’. Each nameseparated from its assigned value by the character ‘=’.For example:/C=US/ST=CA/L=Sunnyvale/O=ACME Inc./OU=CTO Office/CN=DDS ShapesDemo/emailAddress=cto@acme.com11.3.1.1.3 Permissions SectionThis section contains the permissions assigned to the DomainParticipant. It appears either as a set ofallowed permissions with exceptions inside the <allow_with_exceptions> element or as a set of de-nied permissions with exceptions inside the <deny_with_exceptions> element.Both allowed and denied permissions specify the DDS domain IDs to which they apply.The allowed permissions are given in terms of a list of topic name expressions the participant is al-lowed to publish as well as the list of topic name expressions it is allowed to subscribe to. In additionto the allowed lists an exception list is also provided. A participant is allowed to publish a topic if thetopic name matches one of the expressions in the allowed publication list and does not match any ofthe topic-name expressions in the exception publication list. Parallel logic applies to the determina-tion of whether a participant is allowed to subscribe to a topic.The denied permissions are given in terms of a list of topic name expressions the participant is notallowed to publish as well as a list of topic name expressions it is not allowed to subscribe to. In ad-dition to the denied lists an exception list is also provided. A participant is allowed to publish a topicif the topic name either does not match one of the expressions in the denied publication list or if is amatch, then it also matches one of topic-name expressions in the exception list. The same logic ap-plies to the determination of whether a participant is allowed to subscribe to a topic.130 DDS Security, Revised Submission
    • 11.3.1.1.4 Extra Tags SectionThis section contains additional text matter that is signed in the certificate. It provides an extensibil-ity mechanism where additional information that should be signed can appear.11.3.2 DDS:Access:PKI-Signed-XML-Permissions Types<NOTE: THIS SECTION IS STILL PRELIMINARY ANDINCOMPLETE>This section specifies the content and format of the Credentials and Tokens used by theDDS:Access:PKI-Signed-XML-Permissions plugin.11.3.2.1 DDS:Access:PKI-Signed-XML-Permissions PermissionsCredentialThe DDS:Access:PKI-Signed-XML-Permissions plugin shall set the attributes of the Permission-sCredential objects as specified in the table below: Attribute  name   Attribute  value  credential_classid   “DDS:Access:PKI-­‐Signed-­‐XML-­‐Permissions”  properties   This  specification  does  not  define  any  required  values  for  the  proper-­‐ ties.  However  it  reserves  all  properties  with  names  starting  with  the   prefix  “dds.”  For  future  versions  of  the  specification.   Specific  implementations  of  the  plugin  may  use  the  contents  of  this   attribute  to  configure  internal  behavior  as  long  as  the  externally  ob-­‐ servable  behavior  complies  with  this  specification.  value   Octet  sequence  containing  the  characters  in  the  PEM-­‐encoded  X.509   certificate  for  the  DomainParticipant  signed  by  the  shared  Certificate   Authority.  private_value   Octet  sequence  containing  the  characters  in  the  PEM-­‐encoded  RSA   Private  Key  associated  with  the  Public  Key  that  was  signed  in  the   certificate  contained  in  the  value  attribute.  11.3.2.2 DDS:Access:PKI-Signed-XML-Permissions PermissionsTokenThe DDS:Access:PKI-Signed-XML-Permissions plugin shall set the attributes of the Permission-sToken object as specified in the table below: Attribute  name   Attribute  value  token_classid   “DDS:Access:PKI-­‐Signed-­‐XML-­‐Permissions”wrapper_classid   The  empty  string  DDS Security, Revised Submission 131
    • properties   This  specification  does  not  define  any  required  values  for  the  proper-­‐ ties.  However  it  reserves  all  properties  with  names  starting  with  the   prefix  “dds.”  For  future  versions  of  the  specification.   Specific  implementations  of  the  plugin  may  use  the  contents  of  this   attribute  to  configure  internal  behavior  as  long  as  the  externally  ob-­‐ servable  behavior  complies  with  this  specification.  value   Octet  sequence  containing  the  characters  in  the  PEM-­‐encoded  PKCS7   digital  signature  of  the  permissions  document.    The  digital  signature   is  performed  by  the  permissions  CA  using  its  private  Key.  wrapped_value   The  empty  sequence.  11.3.3 Behavior of the built-in Access Control PluginThe DDS:Access:PKI-Signed-XML-Permissions shall be initialized to have access to the Permis-sions CA 2048-bit RSA public key. As this is a built-in plugin the mechanism for initialization is im-plementation dependent.The table below describes the actions that the DDS:Access:PKI-Signed-XML-Permissions pluginperforms when each of the plugin operations is invoked.check_create_participant This operation will use the permissions_handle to retrieve the cached Permissions Section. The operation will verify that the Permissions Section allows creating a participant in the specified domain_id.check_create_datawriter This operation will use the permissions_handle to retrieve the cached Permissions Section. The operation will verify that the Permissions Section allows publishing the specified topic_name on the specified domain_id.check_create_datareader This operation will use the permissions_handle to retrieve the cached Permissions Section. The operation will verify that the Permissions Section allows subscribing to the specified topic_name on the specified domain_id.check_create_topic This operation will use the132 DDS Security, Revised Submission
    • permissions_handle to retrieve the cached Permissions Section. The operation will verify that the Permissions Section allows publishing or subscribing to the specified topic_name on the specified domain_id.check_local_datawriter_re This operation returns TRUE.gister_instancecheck_local_datawriter_di This operation returns TRUE.spose_instancecheck_remote_participant This operation will use the permissions_handle to retrieve the cached Permissions Section. The operation will verify that the Permissions Section allows creating a participant in the specified domain_id.check_remote_datawriter This operation will use the permissions_handle to retrieve the cached Permissions Section. The operation will verify that the Permissions Section allows publishing a the specified topic_name on the specified domain_id.check_remote_datareader This operation will use the permissions_handle to retrieve the cached Permissions Section. The operation will verify that the Permissions Section allows subscribing to the specified topic_name on the specified domain_id.check_remote_topic This operation will use the permissions_handle to retrieve the cached Permissions Section. The operation will verify that the Permissions Section allows publishing or subscribing to the specified topic_name on the specified domain_id.check_remote_datawriter_r This operation returns TRUE.egister_instanceDDS Security, Revised Submission 133
    • check_remote_datawriter_d This operation returns TRUE.ispose_instanceget_permissions_token This operation shall return the PermissionsToken formatted as described in section 11.3.2.2.set_listener This operation shall save a reference to the listener object and associate it with the specified PermissionsHandle.validate_local_permission This operation will invoke the operations get_identity_token on the auth_plugin that is passed as a parameter to obtain the IdentityCredential associated with the IdentityHandle and get the subject name of the certificate given to the domain participant. The operation shall receive the PermissionsCredential formatted as described in section 11.3.2.1. The operation shall check the subject name in the PKCS7 documents and determine that it matches the one from the IdentityCredential. The operation shall verify the digital signature of the PKCS7 document by the configured Permissions CA. If all of these succeed the operation shall cache the Permission Section from the certificate and return an opaque handle that the plugin can use to refer to the saved information. Otherwise the operation shall return an error.validate_remote_permissio This operation will invoke the operationns get_identity_token on the auth_plugin passing the remote_identity_handle to retrieve the IdentityToken for the remote DomainParticipant. The operation shall receive the PermissionsToken which shall contain the PKCS7 digitally-signed permissions document.134 DDS Security, Revised Submission
    • The operation shall check the subject name in the PKCS7 documents and determine that it matches the one from the IdentityToken of the remote DomainParticipant. The operation shall verify the digital signature of the PKCS7 document by the configured Permissions CA. If all of these succeed the operation shall cache the Permission Section from the PermissionsToken and return an opaque handle that the plugin can use to refer to the saved information. Otherwise the operation shall return an error.11.4 Built-in Cryptographic PluginThe built-in cryptographic plugin is referred to as “DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH”plugin.DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH provides data encryption services using AdvancedEncryption Standard (AES) in counter (CTR) mode. It supports two AES key size: 128 bits and 256bits. It also provides hash-based message authentication (HMAC) services with two different hash-ing functions: SHA256 and SHA1.The approach followed is conceptually similar to that used for SRTP. However it has been enhancedto be able to support additional scenarios, such as the presence of services like a DDS persistenceservice or a data relay service, which are present in DDS-RTPS systems and not supported by RTP.The algorithm used for data confidentiality is AES in CTR mode. While AES is a block cipher, theuse of counter mode effectively turns it into a stream cipher. It generates key-stream blocks that areXORed with the plaintext blocks to get the ciphertext. Since the XOR operation is symmetric thedecryption operation is exactly the same. It is called counter mode because the key-stream blocks aregenerated encrypting successive values of a "counter" with the key. This mode of operation requiresthe SessionKey to be kept secret, however the counter does not need to be protected and can be anyfunction that creates a sequence that does not repeat in a long time, in particular it can be a simpleincrementing integer.DDS Security, Revised Submission 135
    • The use of counter mode allows decryption of blocks in arbitrary order. All that is needed to decrypta block are the SessionKey and the counter. This is very important for DDS because a DataReadermay not receive all the samples written by a matched DataWriter. The use of ContentFilteredTopicsas well as QoS policies such as History (with KEEP_LAST kind), Reliability (withBEST_EFFORTS kind), Lifespan, and TimeBasedFilter, among others, can result in a DataReaderreceiving a subset of the samples written by a DataWriter.The DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH plugin is also used to compute a Hash-basedMessage Authentication Code (HMAC). The plugin supports two hashing algorithms to use withHMAC-SHA256 and HMAC-SHA1. HMAC is defined by IETF RFC 2014 [19]. HMAC keys mustbe at least as long as the block size of the underlying hash algorithm. The MAC may be computedover the entire RTPS message, which can include multiple submessages, encrypted using differentAES keys or may be over particular submessages.11.4.1 ConfigurationThe configuration of the DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH plugin not dictated by thisspecification and therefore is implementation specific. Implementations may provide, for example,an API, an extended QoS Policy, or use a specially named domain participant property. The require-ment is that the different modes of operation should all be supported and configurable.11.4.2 DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH Types<NOTE: THIS SECTION IS STILL PRELIMINARY ANDINCOMPLETE>The Cryptographic Plugin defines a set of generic data-types to be used to initialize the plugin and toexternalize the properties and material that must be shared with the applications that need to decodethe cipher material, verify signatures, etc.Each plugin implementation defines the contents of these types in a manner appropriate for the algo-rithms it uses. All “Handle” types are local opaque handles that are only understood by the localplugin object that creates them. The remaining types shall be fully specified so that independent im-plementations of DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH can interoperate.136 DDS Security, Revised Submission
    • 11.4.2.1 DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH CryptoTokenThe DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH plugin shall set the attributes of the CryptoTo-ken object as specified in the table below: Attribute  name   Attribute  value  token_classid   “DDS:Crypto:AES-­‐CTR-­‐HMAC”wrapper_classid   The  string  DDS:Crypto:AES256-­‐SHA256properties   This  specification  does  not  define  any  required  values  for  the  proper-­‐ ties.  However  it  reserves  all  properties  with  names  starting  with  the   prefix  “dds.”  For  future  versions  of  the  specification.   Specific  implementations  of  the  plugin  may  use  the  contents  of  this   attribute  to  configure  internal  behavior  as  long  as  the  externally  ob-­‐ servable  behavior  complies  with  this  specification.  value   A  sequence  of  octets  containing  the  result  of  encrypting  the  Extended   CDR  encapsulation  of  the  KeyMaterial_AES_CTR_HMAC  structure   whose  IDL  is  defined  below.  The  encryption  is  performed  using  the   key  KxKey  derived  from  the  SharedSecret  as  described  in  section   11.4.2.1.2.wrapped_value   A  sequence  of  octets  containing  the  HMAC  of  the  value  attribute.   The  HMAC  uses  the  MAC  key  KxMacKey  derived  from  the  SharedSe-­‐ cret  as  described  in  section  11.4.2.1.2.11.4.2.1.1 KeyMaterial_AES_CTR_HMAC structureThe contents and serialization of the KeyMaterial_AES_CTR_HMAC structure are described by theExtended IDL below:enum CipherKind { NONE = 0, AES128 = 1, AES256 = 2};enum HashKind { NONE = 0, SHA1 = 1, SHA256 = 2};@extensiblestruct KeyMaterial_AES_CTR_HMAC { CipherKind cipher_kind; HashKind hash_kind; long master_key_id;DDS Security, Revised Submission 137
    • sequence<octet, 32> master_key; sequence<octet, 32> initilization_vector; sequence<octet, 32> hmac_key_id;};11.4.2.1.2 Derivation of KxKey and KxMacKey from SharedSecretThe KxKey and KxMacKey are derived from the SharedKey using the formulas:KxKey := HMACsha256(SharedSecret, challenge_A # challenge_B # KxCookie)KxMacKey := HMACsha256(SharedSecret, challenge_A # challenge_B # KxMacCookie)In the above formula the terms used shall have the meaning described in the table below: term   meaning  Challenge_A   The  challenge  that  was  sent  in  the  value  attribute  of  the  HandshakeRe-­‐ questMessageToken  as  part  of  the  Authentication  protocolChallenge_B   The  challenge  that  was  sent  in  the  value  attribute  of  the  HandshakeRe-­‐ plyMessageToken  as  part  of  the  Authentication  protocolSharedSecret   The  shared  secret  that  was  sent  in  the  value  attribute  of  the  HandshakeFi-­‐ nalMessageToken  as  part  of  the  Authentication  protocol.  Note  that  the   value  attribute  contained  the  SharedSecret  encrypted  with  the  Public  Key   of  the  remote  DomainParticipant  that  was  the  destination  of  the  Hand-­‐ shakeFinalMessageToken.  The  SharedSecret  term  refers  to  the  un-­‐ encrypted  value.KxKeyCookie   The  16  bytes  in  the  string  “key  exchange  key”KxMacKeyCookie   The  16  bytes  in  the  string  “key  exchange  mac”data1  #  data2  #  data3   The  symbol  ‘#’  is  used  to  indicate  byte  concatenation  HMACsha256(key,  data) Computes  the  hash-­‐based  message  authentication  code  on  ‘data’  using  the   key  specified  as  first  argument  and  a  SHA256  hash  as  defined  in  [19].11.4.2.2 DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH CryptoTransformIdentifierThe DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH shall set the CryptoTransformIdentifier attrib-utes as specified in the table below: attribute   value  138 DDS Security, Revised Submission
    • transformation_kind_id   Set  to  one  of  the  following  values:   #define  HMAC_SHA1                                                {  0x00,  0x00,  0x01,  0x00}     #define  HMAC_SHA256                                      {  0x00,  0x00,  0x01,  0x01}     #define    AES128_HMAC_SHA1            {  0x00,  0x00,  0x02,  0x00}   #define    AES256_HMAC_SHA256  {  0x00,  0x00,  0x02,  0x01}     The  value  HMAC_SHA1  indicates  the  transformation  performed   leaves  the  plaintext  unencrypted  and  appends  an  HMAC  using   SHA1.     The  value  HMAC_SHA256  indicates  the  transformation  performed   leaves  the  plaintext  unencrypted  and  appends  an  HMAC  using   SHA256.     The  value  AES-­‐128_HMAC_SHA1  indicates  the  transformation  per-­‐ formed  first  encrypts  the  cleartext  using  AES  with  128-­‐bit  key  and   the  resulting  cipher  text  is  appended  with  the  HMAC  computed   over  the  ciphertext  using  SHA1.     The  value  AES-­‐256_HMAC_SHA256  indicates  the  transformation   performed  first  encrypts  the  cleartext  using  AES  with  256-­‐bit  key   and  the  resulting  cipher  text  is  appended  with  the  HMAC  computed   over  the  ciphertext  using  SHA256.  transformation_key_id   This  is  set  to  a  different  value  each  time  the  key  used  for  encryption   or  HMAC  changes.  The  algorithm  used  should  avoid  repeating  the   values  for  the  CryptoHandle  that  performs  the  encryption.11.4.2.3 DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH SecureDataHeaderThe DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH CryptoKeyTransform interface has several op-erations that transform clear text into cipher text. The cipher-text created by these “encode” opera-tions contains a SecureDataHeader that is used by the corresponding “decode” operations onthe receiving size. The SecureDataHeader structure is described by the Extended IDL below:@finalstruct SecureDataHeader_AES_CTR_HMAC { CryptoTranformIdentifier transform_id; long session_id; long sesson_counter;};DDS Security, Revised Submission 139
    • 11.4.3 Behavior of the DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH Plugin<NOTE: THIS SECTION IS STILL PRELIMINARY ANDINCOMPLETE>This plugin implements three interfaces: CryptoKeyFactory, CryptoKeyExchange, and CryptoTrans-form. Each is described separately.11.4.3.1 CryptoKeyFactory for DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DHThe table below describes the actions that the DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH wheneach of the CryptoKeyFactory plugin operations is invoked.register_local_pa This  operation  shall  create  a  new  KeyMaterial_AES_CTR_HMACrticipant object and return a handle that can the plugin can use to access the cre- ated object. We will refer to this object by the name: ParticipantKeyMaterial. The CipherKind and HashKind for the ParticipantKeyMaterial object shall be configurable but the configuration mechanism is not specified.  register_matched_ This  operation  shall  associate  the  SharedSecret  received  as  an  ar-­‐remote_participan gument  with  the  local  and  remote  t ParticipantCryptoHandle. This  operation  shall  create  a  new  KeyMaterial_AES_CTR_HMAC object and associate it with the local and remote ParticipantCryptoHandle pair. We will refer to this object by the name: Participant2ParticipantKeyMaterial. The CipherKind for the ParticipantKeyMaterial object shall be NONE. The HashKind shall be configurable but the configuration mechanism is not specified. The Participant2ParticipantKeyMaterial shall be used when the local participant needs to produce a MAC that can only be verified by that one matched remote participant. This operation also creates the KxKey and the KxMacKey that derive from the SharedSecret passed as a parameter and associate them with the local and remote ParticipantCryptoHandle pair. We will refer to these keys as Participant2ParticipantKxKey and Participant2ParticipantKxMacKey, respectively.register_local_da This  operation  shall  create  a  new  KeyMaterial_AES_CTR_HMACtawriter object and returns a handle that can the plugin can use to access the cre- ated object. We will refer to this object by the name:140 DDS Security, Revised Submission
    • WriterKeyMaterial. The CipherKind and HashKind for the WriterKeyMaterial object shall be configurable but the configuration mechanism is not specified. It is possible for the configuration to result in both CipherKind and HashKind having the value NONE.register_matched_ This  operation  shall  create  a  new  KeyMaterial_AES_CTR_HMACremote_datareader object and associate it with the local DatawriterCryptoHandle and remote DatareaderCryptoHandle pair. We will refer to this object by the name: Writer2ReaderKeyMaterial. The CipherKind and HashKind for the Writer2ReaderKeyMaterial object shall be NONE. The Hash- Kind shall be configurable but the configuration mechanism is not specified. The Writer2ReaderKeyMaterial shall be used when the local DataWriter needs to produce a MAC that can only be verified by that one matched remote DataReader.  register_local_da This  operation  shall  create  a  new  KeyMaterial_AES_CTR_HMACtareader object and return a handle that can the plugin can use to access the cre- ated object. We will refer to this object by the name: ReaderKeyMaterial. The CipherKind and HashKind for the ReaderKeyMaterial object shall be configurable but the configuration mechanism is not specified. It is possible for the configuration to result in both CipherKind and HashKind having the value NONE.  register_matched_ This  operation  shall  create  a  new  KeyMaterial_AES_CTR_HMACremote_datawriter object and associate it with the local DatareaderCryptoHandle and remote DatawriterCryptoHandle pair. We will refer to this object by the name: Reader2WriterKeyMaterial. The CipherKind and HashKind for the Reader2WriterKeyMaterial object shall be NONE. The Hash- Kind shall be configurable but the configuration mechanism is not specified. The Reader2WriterKeyMaterial shall be used when the local DataReader needs to produce a MAC that can only be verified by that one matched remote DataWriter.  unregister_partic Releases  any  resources  allocated  on  the  corresponding  call  to  regis-­‐ipant ter_local_participant,  or  register_matched_remote_participant  unregister_datawr Releases  any  resources  allocated  on  the  corresponding  call  to  regis-­‐iter ter_local_datawriter,  or  register_matched_remote_datawriter  DDS Security, Revised Submission 141
    • unregister_datare Releases  any  resources  allocated  on  the  corresponding  call  to  regis-­‐ader ter_local_datareader,  or  register_matched_remote_datareader  11.4.3.2 CryptoKeyExchange for DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DHThe table below describes the actions that the DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH wheneach of the CryptoKeyExchange plugin operations is invokedcreate_local_partic Creates  two  DDS:Crypto:AES-­‐CTR-­‐HMAC-­‐RSA/DSA-­‐DH  CryptoToken  ob-­‐ipant_crypto_tokens   jects  and  returns  both  in  the  output  sequence.   The  first  CryptoToken  contains  the  ParticipantKeyMaterial cre-­‐ ated  on  the  call  to  register_local_participant.   The  second  CryptoToken  contains  the   Participant2ParticipantKeyMaterial  created  on  the  call  to   register_matched_remote_participant  for  the   remote_participant_crypto. Both  CryptoToken  objects  use  the  Participant2ParticipantKxKey and  Participant2ParticipantKxMacKey.set_remote_particip Shall  receive  the  sequence  of  two  CryptoToken  objects  that  was  created  ant_crypto_tokens   by  the  corresponding  call  to   create_local_participant_crypto_tokens  on  the  remote  side.   The  operation  uses  the  Participant2ParticipantKxKey and   Participant2ParticipantKxMacKey associated  with  the  local  and   remote  ParticipantCryptoHandle  pair  to  verify  and  decode  the  two   tokens  and  associates  the  obtained  keys  with  the  CryptoHandle  pair.  The   decoded  keys  shall  be  referred  as  RemoteParticipantKeyMaterial and  RemoteParticipant2ParticipantKeyMaterial,  respec-­‐ tively.create_local_datawr Creates  two  DDS:Crypto:AES-­‐CTR-­‐HMAC-­‐RSA/DSA-­‐DH  CryptoToken  ob-­‐iter_crypto_tokens   jects  and  returns  both  in  the  output  sequence.   The  first  CryptoToken  contains  the  DatawriterKeyMaterial created   on  the  call  to  register_local_datawriter.   The  second  CryptoToken  contains  the  Writer2ReaderKeyMaterial   created  on  the  call  to  register_matched_remote_datareader  for   the  remote_datareader_crypto. Both  CryptoToken  objects  use  the  Participant2ParticipantKxKey and  Participant2ParticipantKxMacKey.  set_remote_datawrit Shall  receive  the  sequence  of  two  CryptoToken  objects  that  was  created  er_crypto_tokens   by  the  corresponding  call  to   create_local_datawriter_crypto_tokens  on  the  remote  side.   The  operation  uses  the  Participant2ParticipantKxKey and  142 DDS Security, Revised Submission
    • Participant2ParticipantKxMacKey associated  with  the  local  and   remote  ParticipantCryptoHandle  pair  to  verify  and  decode  the  two   tokens  and  associates  the  obtained  keys  with  the  CryptoHandle  pair.  The   decoded  keys  shall  be  referred  as  RemoteDatawriterKeyMaterial and  RemoteWriter2ReaderKeyMaterial,  respectively.create_local_datare Creates  two  DDS:Crypto:AES-­‐CTR-­‐HMAC-­‐RSA/DSA-­‐DH  CryptoToken  ob-­‐ader_crypto_tokens   jects  and  returns  both  in  the  output  sequence.   The  first  CryptoToken  contains  the  DatareaderKeyMaterial created   on  the  call  to  register_local_datareader.   The  second  CryptoToken  contains  the  Reader2WriterKeyMaterial   created  on  the  call  to  register_matched_remote_datawriter  for   the  remote_datawriter_crypto. Both  CryptoToken  objects  use  the  Participant2ParticipantKxKey and  Participant2ParticipantKxMacKey.  set_remote_dataread Shall  receive  the  sequence  of  two  CryptoToken  objects  that  was  created  er_crypto_tokens by  the  corresponding  call  to   create_local_datareader_crypto_tokens  on  the  remote  side.   The  operation  uses  the  Participant2ParticipantKxKey and   Participant2ParticipantKxMacKey associated  with  the  local  and   remote  ParticipantCryptoHandle  pair  to  verify  and  decode  the  two   tokens  and  associates  the  obtained  keys  with  the  CryptoHandle  pair.  The   decoded  keys  shall  be  referred  as  RemoteDatareaderKeyMaterial and  RemoteReader2WriterKeyMaterial,  respectively.return_crypto_token Releases  the  resources  associated  with  the  CryptoToken  objects  in  the  s sequence.11.4.3.3 CryptoKeyTransform for DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH11.4.3.3.1 OverviewThe table below describes the actions that the DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DHwheneach of the CryptoKeyTransform plugin operations is invokedencode_serialized_d Uses  the  WriterKeyMaterial associated  with  the  ata   sending_datawriter_crypto  to  encrypt  and  sign  the  input  Serial-­‐ izedData  RTPS  SubmessageElement  transforming  into  a  RTPS  SecureData   SubmessageElement  containing  the  EncodeOperationOutputData  that  is   the  result  of  the  encrypting  and  signing  operations.   This  operation  shall  always  set  additional_digests  attribute  in  the  En-­‐ codeOperationOutputData  to  the  empty  sequence.encode_datawriter_s Uses  the  WriterKeyMaterial associated  with  the  ubmessage   sending_datawriter_crypto  and  theDDS Security, Revised Submission 143
    • Writer2ReaderKeyMaterial  associated  with  the   sending_datawriter_crypto  and  each  of  the   receiving_datareader_crypto  handles  to  transform  the  input   RTPS  Submessage  into  a  RTPS  SecureSubMessage  containing  the  En-­‐ codeOperationOutputData  that  is  the  result  of  the  encrypting  and  signing   operations.   The  ciphertext  shall  be  computed  using  the  WriterKeyMaterial  asso-­‐ ciated  with  the  sending_datawriter_crypto.   Depending  on  the  configuration  the  operation  may  compute  and  set  the   common_digest  or  the  additional_digests.     If  computed,  the  common_digest  shall  be  computed  using  the   WriterKeyMaterial  associated  with  the   sending_datawriter_crypto.   If  computed,  the  additional_digests  shall  be  computed  using  the   Writer2ReaderKeyMaterial  associated  with  the  pair  composed  of   the  sending_datawriter_crypto  and  each  of  the  corresponding   receiving_datareader_crypto.    encode_datareader_s Uses  the  ReaderKeyMaterial associated  with  the  ubmessage   sending_datareader_crypto  and  the Reader2WriterKeyMaterial  associated  with  the   sending_datareader_crypto  and  each  of  the   receiving_datareader_crypto  handles  to  transform  the  input   RTPS  Submessage  into  a  RTPS  SecureSubMessage  containing  the  En-­‐ codeOperationOutputData  that  is  the  result  of  the  encrypting  and  signing   operations.   The  ciphertext  shall  be  computed  using  the  ReaderKeyMaterial as-­‐ sociated  with  the  sending_datareader_crypto.   Depending  on  the  configuration  the  operation  may  compute  and  set  the   common_digest  or  the  additional_digests.     If  computed,  the  common_digest  shall  be  computed  using  the   ReaderKeyMaterial associated  with  the   sending_datareader_crypto.   If  computed,  the  additional_digests  shall  be  computed  using  the   Reader2WriterKeyMaterial  associated  with  the  pair  composed  of   the  sending_datareader_crypto  and  each  of  the  corresponding   receiving_datawriter_crypto.144 DDS Security, Revised Submission
    • 11.4.3.3.1.1 enc Uses  the  ParticipantKeyMaterial associated  with  the   ode_rtps_m sending_participant_crypto  and  the essage Participant2ParticipantKeyMaterial  associated  with  the   sending_participant_crypto  and  each  of  the  receiving_ articipant_crypto  handles  to  transform  the  input  RTPS  Message   into  a  RTPS  Message  that  contains  a  single  RTPS  SecureSubMessage.  The   SecureSubMessage  contains  the  EncodeOperationOutputData  that  is  the   result  of  the  encrypting  and  signing  operations.   The  ciphertext  shall  be  computed  using  the   ParticipantKeyMaterial associated  with  the   sending_participant_crypto.   Depending  on  the  configuration  the  operation  may  compute  and  set  the   common_digest  or  the  additional_digests.     If  computed,  the  common_digest  shall  be  computed  using  the   ParticipantKeyMaterial associated  with  the   sending_participant_crypto.   If  computed,  the  additional_digests  shall  be  computed  using  the   Participant2ParticipantKeyMaterial  associated  with  the  pair   composed  of  the  sending_participant_crypto  and  each  of  the  cor-­‐ responding  receiving_participant_crypto.decode_rtps_message   Examines  the  CryptoTranformIdentifier to  determine  the  trans-­‐ form_kind_id  is  one  of  the  recognized  kinds.  If  the  kind  is  not  recognized   the  operation  shall  fail  with  and  exception.   Uses  source  and  destination  DomainParticipantGUIDs  in  the  RTPS  Header   to  locate  the  sending_participant_crypto  and  receiving_participant_crypto.   Then  looks  whether  the  transform_key_id  attribute  in  the   CryptoTranformIdentifier is  associated  with  those  Partcipant-­‐ CryptoHandles.  If  the  association  is  not  found  the  operation  shall  fail  with   and  exception.   Uses  the  RemoteParticipantKeyMaterial and  the   RemoteParticipant2ParticopantKeyMaterial associated  with   the  retrieved  PartcipantCryptoHandles  to  verify  and  decrypt  the  RTPS   SubMessage  that  follows  the  RTPS  Header.  If  the  verification  or  decryp-­‐ tion  fails  the  operation  shall  fail  with  and  exception.   If  the  RemoteParticipantKeyMaterial specified  a  hash_kind  dif-­‐ ferent  from  NONE,  then  the  operation  shall  check  that  the  received  Se-­‐ cureSubMessage  contains  a  common_digest  and  use  it  to  verify  the  Se-­‐ cureSubMessage.  If  the  common_digest  is  missing  or  the  verification  fails   the  operation  shall  fail  with  an  exception.   If  the  RemoteParticopant2ParticipantKeyMaterial specified   a  hash_kind  different  from  NONE,  then  the  operation  shall  check  that  the   received  SecureSubMessage  contains  an  additional_digest  element  with  a   transformation_id  it  that  is  associated  with  local  and  remote  Partcipant-­‐DDS Security, Revised Submission 145
    • CryptoHandles.  If  the  additional_digest  is  missing  or  the  verification  fails   the  operation  shall  fail  with  an  exception.   Upon  success  the  returned  RTPS  Message  shall  match  the  input  to  the  en-­‐ code_rtps_message  operation  on  the  DomainParticipant  that  sent  the   message.preprocess_secure_s Examines  the  RTPS  SecureSubmessage  to:  ubmsg Determine  whether  the  CryptoTranformIdentifier the  trans-­‐ form_kind_id  matches  one  of  the  recognized  kinds   Classify  the  RTPS  Submessage  as  a  Writer  or  Reader  Submessage.   Retrieve  the  DatawriterCryptoHandle  and  DataReaderCryptoHandle  han-­‐ dles  associated  with  the  CryptoTranformIdentifier the  trans-­‐ form_key_id.11.4.4 decode_d Uses  the  RemoteDatawriterKeyMaterial and  the   atawriter_subm RemoteDatawriter2DatareaderKeyMaterial associated  with   essage the  CryptoHandles  returned  by  the  preprocess_secure_submessage  to   verify  and  decrypt  the  RTPS  SubMessage  If  the  verification  or  decryption   fails  the  operation  shall  fail  with  and  exception.   If  the  RemoteDatawriterKeyMaterial specified  a  hash_kind  differ-­‐ ent  from  NONE,  then  the  operation  shall  check  that  the  received  Secure-­‐ SubMessage  contains  a  common_digest  and  use  it  to  verify  the  Secure-­‐ SubMessage.  If  the  common_digest    is  missing  or  the  verification  fails  the   operation  shall  fail  with  an  exception.   If  the  RemoteDatawriter2DatareaderKeyMaterial specified  a   hash_kind  different  from  NONE,  then  the  operation  shall  check  that  the   received  SecureSubMessage  contains  an  additional_digest  element  with  a   transformation_id  it  that  is  associated  with  local  and  remote  CryptoHan-­‐ dles.  If  the  additional_digest  is  missing  or  the  verification  fails  the  opera-­‐ tion  shall  fail  with  an  exception.   Upon  success  the  returned  RTPS  SubMessage  shall  match  the  input  to  the   encode_datawriter_message  operation  on  the  DomainParticipant  that   sent  the  message.decode_datareader_s Uses  the  RemoteDatareaderKeyMaterial and  the  ubmessage RemoteDatareader2DatawriterKeyMaterial associated  with   the  CryptoHandles  returned  by  the  preprocess_secure_submessage  to   verify  and  decrypt  the  RTPS  SubMessage  If  the  verification  or  decryption   fails  the  operation  shall  fail  with  and  exception.   If  the  RemoteDatareaderKeyMaterial specified  a  hash_kind  differ-­‐ ent  from  NONE,  then  the  operation  shall  check  that  the  received  Secure-­‐ SubMessage  contains  a  common_digest  and  use  it  to  verify  the  Secure-­‐ SubMessage.  If  the  common_digest    is  missing  or  the  verification  fails  the   operation  shall  fail  with  an  exception.   If  the  RemoteDatareader2DatawriterKeyMaterial specified  a  146 DDS Security, Revised Submission
    • hash_kind  different  from  NONE,  then  the  operation  shall  check  that  the   received  SecureSubMessage  contains  an  additional_digest  element  with  a   transformation_id  it  that  is  associated  with  local  and  remote  CryptoHan-­‐ dles.  If  the  additional_digest  is  missing  or  the  verification  fails  the  opera-­‐ tion  shall  fail  with  an  exception.   Upon  success  the  returned  RTPS  SubMessage  shall  match  the  input  to  the   encode_datareader_message  operation  on  the  DomainParticipant  that   sent  the  message.decode_serialized_d Uses  writerGUID  and  the  readerGUID  in  the  RTPS  SubMessage  to  locate  ata the  sending_datawriter_crypto  and  receiving_datareader_crypto.  Then   looks  whether  the  transform_key_id  attribute  in  the   CryptoTranformIdentifier in  the  SecureData  SubmessageElement   is  associated  with  those  CryptoHandles.  If  the  association  is  not  found  the   operation  shall  fail  with  and  exception.   Uses  the  RemoteDatawriterKeyMaterial associated  with  the  re-­‐ trieved  CryptoHandles  to  verify  and  decrypt  the  RTPS  SecureData  Sub-­‐ messageElement.  If  the  verification  or  decryption  fails  the  operation  shall   fail  with  and  exception.   If  the  RemoteDatawriterKeyMaterial specified  a  hash_kind  differ-­‐ ent  from  NONE,  then  the  operation  shall  check  that  the  received  Secure-­‐ Data  SubmessageElement  contains  a  common_digest  and  use  it  to  verify   the  SecureSubMessage.  If  the  common_digest  is  missing  or  the  verifica-­‐ tion  fails  the  operation  shall  fail  with  an  exception.  11.4.4.1.1 Encode/decode operation virtual machineThe logical operation of the Crypto-AES-CTR-HMAC-RSA/DSA-DH is described in terms of a vir-tual machine as it performs the encrypt message digest operations. This is not intended to mandateimplementations should follow this approach literally, simply that the observable results for anyplaintext are the same as the virtual machine described here.For any given cryptographic session the operation of the Crypto-AES-CTR-HMAC-RSA/DSA-DHas it transforms plaintext into ciphertext can be described in terms of a virtual machine that maintainsthe following state:State  variable   Type   Meaning  MasterKey   128  bit  array  for  AES128   The  master  key  from  which  ses-­‐ sion  salts,  session  keys  and  ses-­‐ 256  bit  array  for  AES256   sion  hash  keys  are  derived  MasterSalt   128  bit  array  for  AES128   A  random  vector  used  in  connec-­‐ tion  with  the  MasterKey  to  cre-­‐ 256  bit  array  for  AES256   ate  the  SessionKey    MasterHMACSalt   128  bit  array  for  AES128   A  random  vector  used  in  connec-­‐DDS Security, Revised Submission 147
    • tion  with  the  MasterKey  to  cre-­‐ 256  bit  array  for  AES256   ate  the  SessionHashKey  MasterSessionSalt   128  bit  array  for  AES128   A  random  vector  used  to  salt  the   derivation  of  the  SessionSalt   from  the  MasterKey  and  the  Ses-­‐ sionId.  MasterKeyId   32  bit  integer   A  random  number  associated   with  the  master  key  when  it  is   first  created  used  to  tag  the  ci-­‐ phertext  to  ensure  the  correct   key  is  being  used  during  decryp-­‐ tion.  It  may  be  used  also  for  the   purposes  of  re-­‐keying.    SessionId   32  bit  array   An  incrementing  counter  used  to   create  the  current  SessionKey,   SessionSalt,  and  Ses-­‐ sionHMACKey  from  the  Mas-­‐ terKey  and  Master  salts.   The  SessionId  is  changed  each   time  a  new  SessionKey  is  needed   and  then  used  to  derive  the  new   SessionKey  and  SessionSalt  from   the  MasterKey.   Knowledge  of  the  MasterKey  ,   MasterSalt,  MasterHMACSalt,   and  the  SessionId  is  sufficient  to   create  the  SessionKey,  Session-­‐ Salt,  and  SessionHMACKey.  SessionSalt   128  bit  array     A  vector  constructed  from  the   MasterKey,  MasterSessionSalt     and  SessionId  used  in  connec-­‐ tion  with  the  session  counter  to   construct  the  input  to  the  Block   Cipher.  SessionKey   128  bit  array  for  AES128   The  current  key  used  for  creat-­‐ ing  the  ciphertext.   256  bit  array  for  AES256   It  is  constructed  from  the  Mas-­‐ terKey,  MasterSalt,  and  Ses-­‐ sionId  SessionHMACKey   128  bit  array  for  AES128   The  current  key  used  to  compute   the  HMAC  performed  by  the   256  bit  array  for  AES256   compute_digest  operation  session_block_counter   64  bit  integer   A  counter  that  counts  the  num-­‐ ber  of  blocks  that  have  been  ci-­‐148 DDS Security, Revised Submission
    • phered  with  the  current  Ses-­‐ sionKey.  max_blocks_per_session   64  bit  integer   A  configurable  property  that  lim-­‐ its  the  number  of  blocks  that  can   be  ciphered  with  the  same  Ses-­‐ sionKey.  If  the  ses-­‐ sion_block_counter  exceeds  this   value  a  new  SessionKey,  Ses-­‐ sionSalt,  and  SessionHMACKey     are  computed  and  the  ses-­‐ sion_block_counter  is  reset  to   zero.    All the key material with a name that starts with “Master” corresponds to theKeyMaterial_AES_CTR_HMAC objects that were created by the CryptoKeyFactory opera-tions. This key material is not used directly to encrypt or compute MAC of the plaintext. Rather it isused to create “Session” Key material by means of the algorithms described below. This has thebenefit that the ‘session’ keys used to secure the date stream data can be modified as needed to main-tain the security if the stream without having to perform explicit rekey and key-exchange operations.Note that by deriving the SessionHMACKey from the same MasterKey as the SessionKey we arelimiting the potential deployment scenarios in that if an application needs to receive data and validatethe digest to ensure it has not been tampered with, it has to also be given the key necessary to under-stand the data. This may be too strong a requirement for applications such as the Persistence Service,or a logging or forwarding service that need to simply forward data but may not have the right privi-leges to understand its contents. To avoid this situation it would be necessary to separate the digest ofthe data from the digest of the RTPS Submessage so that it becomes possible to give access to thekeys necessary to verify complete submessage integrity to a service without simultaneously givingaccess to the keys necessary to verify data integrity and understand the data itself.11.4.4.1.2 Computation of Session Keys and SaltsThe SessionKey, SessionSalt, and SessionHMACKey are computed from the MasterKey, MasterSaltand the SessionId:SessionSalt := HMAC(MasterKey,"SessionSalt" + MasterSessionSalt + SessionId)Truncated to 128 bitsSessionKey := HMAC(MasterKey,"SessionKey" + MasterSalt + SessionId)SessionHMACKey := HMAC(MasterKey,"SessionHMACKey" + MasterHMACSalt + SessionId)In the above expressions the symbol ‘+’ indicates concatenation.11.4.4.1.3 Computation of ciphertext from plaintextThe ciphertext is computed from the plain text the SessionSalt as the NONCE for CTR mode.The encryption Transforms the plaintext input into ciphertext by performing an encryption operationusing the AES algorithm in counter mode using the SessionKeys associated with the specified Key-Handle. The encryption transformation is described in detail in the sections that follow.DDS Security, Revised Submission 149
    • The encryption operation increments the session counter associated with the KeyHandle by one foreach encrypted blockThis operation may change the session key. This decision should be taken at the beginning as all ci-phertext returned by an invocation of the operation must be encrypted with the same session key. If anew session key is changed the SessionId must be changed in correspondence and session counter isreset accordingly.The resulting ciphertext is wrapped by a SecureDataHeader that indicates the sessionId and stat-ing value for the counter.The resulting block of bytes from the “encode” operations (encode_serialized_data, en-code_datawriter_submessage, encode_datareader_submessage, and encode_rtps_message) is the Ex-tended CDR encoding of the IDL for the EncodeOperationOutputData below:@finalstruct DigestResult { SecureDataHeader_AES_CTR_HMAC digest_header; sequence<octet> digest;};@finalstruct EncodeOperationOutputData { SecureDataHeader_AES_CTR_HMAC secure_data_header; sequence<octet> ciphertext; sequence<octet> common_digest; sequence<Digest> additional_digests;};11.4.4.1.4 Computation of plaintext from ciphertextThe decrypt operation first checks that the CryptoTransformIdentifier attribute in theSecureDataHeader_AES_CTR_HMAC has the proper transformation_kind_id and alsouses the CryptoTransformIdentifier transformation_key_id to locate MasterKeyand MasterSalt. In case of a re-key the CryptographicSessionHandle may be associatedwith multiple MasterKeyId and this parameter allows selection of the correct one. If theMasterKeyId is not found associated with the CryptographicSessionHandle the opera-tion shall fail.The session_id attribute within the SecureDataHeader_AES_CTR_HMAC is used to obtain theproper SessionSalt and SessionKey. Note that this only requires a re-computation if it haschanged from the previously received SessionId for that CryptographicSessionHandle.Given the SessionSalt and SessionKey the transformation performed to recover the plaintextfrom the ciphertext is identical to the one performed to go plaintext to ciphertext11.4.4.1.5 Computation of the message digestThe message digest is computed on the secure_data_header and the ciphertext.150 DDS Security, Revised Submission
    • There are two types of digests that may appear.• The first stored in the common_digest uses the KeyMaterial described in the secure_data_header. This digest may be verified by all the receivers of the EncodeOperationOutputData.• The second type, stored in the additional_digests contains digests that use different SecureData- Header_AES_CTR_HMAC which appear explicitly in the DigestResult digest_header. These di- gests use keys that are only shared with some of the receivers of the EncodeOperationOutput- Data. In general each receiver will only have the keys necessary to verify one of these addi- tional_digests. The key material for these digest is derived from the RemoteParticipant2ParticipantKeyMaterial, the RemoteWriter2ReaderKeyMaterial, or the Re- moteReader2WriterKeyMaterial.Depending on the selected algorithm the digest is computed as an HMAC-SHA256 or HMAC-SHA1.11.5 Built-in Logging PluginBuilt-in Logging Plugin<NOTE: THIS SECTION IS MISSING>References[1] DDS-RTPS: Data-Distribution Service Interoperability Wire Protocol version 1.0, http://www.omg.org/cgi-bin/doc?ptc/2006-08-02[2] Transport Layer Security, http://en.wikipedia.org/wiki/Transport_Layer_Security[3] IPSec, http://en.wikipedia.org/wiki/IPsec[4] DSA, FIPS PUB 186-3 Digital Signature Standard (DSS). http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf[5] Diffie-Hellman (D-H) Key Agreement Method. IETF RFC 2631. http://tools.ietf.org/html/rfc2631[6] J. H. Catch et. al., “A Security Analysis of the CLIQUES Protocol Suite”, http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.2.8964[7] Erramilli, S.; Gadgil, S.; Natarajan, N., “Efficient assignment of multicast groups to pub- lish-subscribe information topics in tactical networks”, MILCOM 2008[8] “RFC 2094 - Group Key Management Protocol (GKMP) Architecture”, http://www.faqs.org/rfcs/rfc2094.html[9] Raghav Bhaskar, Daniel Augot, Cedric Adjih, Paul Muhlethaler and Saadi Boudjit, “AGDH (Asymmetric Group Diffie Hellman): An Efficient and Dynamic Group Key Agreement Pro- tocol for Ad hoc Networks”, Proceedings of New Technologies, Mobility and Security (NTMS) conference, Paris, France, May 2007[10] Qianhong Wu, Yi Mu, Willy Susilo, Bo Qin and Josep Domingo-Ferrer “Asymmetric Group Key Agreement”, EUROCRYPT 2009DDS Security, Revised Submission 151
    • [11] “Secure IP Multicast”, http://www.cisco.com/en/US/prod/collateral/iosswrel/ps6537/ps6552/prod_presentation0900a ecd80473105.pdf[12] Gerardo Pardo-Castellote. “Secure DDS: A Security Model suitable for NetCentric, Publish- Subscribe, and Data Distribution Systems”, RTESS, Washington DC, July 2007. http://www.omg.org/news/meetings/workshops/RT-2007/05-2_Pardo-Castellote-revised.pdf[13] Baugher, M., Weis, B., Hardjono, T. and H. Harney, "The Group Domain of Interpretation, RFC 3547, http://tools.ietf.org/html/rfc3547, July 2003.[14] P. Zimmerman, A. Johnston, and J. Callas, “ZRTP: Media Path Key Agreement for Secure RTP”, Internet-Draft, March 2009[15] F. Andreason, M. Baugher, and D. Wing, “Session description protocol (SDP) security de- scription for media streams,” RFC 4568, July 2006[16] D. Ignjatic, L. Dondeti, F. Audet, P. Lin, “MIKEY-RSA-R: An Additional Mode of Key Dis- tribution in Multimedia Internet KEYing (MIKEY)”, RFC 4738, November 2006.[17] M. Baugher, A. Rueegsegger, and S. Rowles, “GDOI Key Establishment for the STRP Data Security Protocol”, http://tools.ietf.org/id/draft-ietf-msec-gdoi-srtp-01.txt, June 2008.[18] Bruce Schneier (August 2005). "SHA-1 Broken". Retrieved 2009-01-09. "[19] H. Krawczyk, M. Bellare, and R.Canetti, “HMAC: Keyed-Hashing for Message Authentica- tion” IETF RFC 2104, http://tools.ietf.org/html/rfc2104[20] Bellare, Mihir (June 2006). "New Proofs for NMAC and HMAC: Security without Collision- Resistance". In Dwork, Cynthia. Advances in Cryptology – Crypto 2006 Proceedings. Lec- ture Notes in Computer Science 4117. Springer-Verlag.[21] S. Turner and L. Chen, “Updated Security Considerations for the MD5 Message-Digest and the HMAC-MD5 Algorithms” IETF RFC 6151, http://tools.ietf.org/html/rfc6151[22] Cisco, “Implementing Group Domain of Interpretation in a Dynamic Multipoint VPN”, http://www.cisco.com/en/US/prod/collateral/iosswrel/ps6537/ps6586/ps6660/ps6811/prod_w hite_paper0900aecd804c363f.html[23] CiscoIOS Secure Multicast, http://www.cisco.com/en/US/prod/collateral/iosswrel/ps6537/ps6552/prod_white_paper0900 aecd8047191e.html[24] A. Mason. IPSec Overview Part Two: Modes and Transforms. http://www.ciscopress.com/articles/article.asp?p=25477[25] R. Canetti, P. Cheng, F. Giraud, D. Pendararkis, J. Rao, P. Rohatgi, and D. Saha, “An IPSec- based Host Architecture for Secure Internet Multicast”, Proceedings of the 7th Annual Net- work and Distributed Systems Security Symposium, San Diego, CA, 2000[26] T. Aurisch, and C. Karg, “Using the IPSec architecture for secure multicast communica- tions,” 8th International Command and Control Research and Technology Symposium (ICCRTS), Washington D.C., 2003[27] J. Zhang and C. Gunter. Application-aware secure multicast for power grid communications, International Journal of Security and Networks, Vol 6, No 1, 2011[28] List of reserved RTPS Vendor Ids. http://portals.omg.org/dds/content/page/dds-rtps-vendor- and-product-ids152 DDS Security, Revised Submission