DDS Security Specification (Adopted Beta1 June 2014)
1 like929 views
The document is an Object Management Group (OMG) specification for DDS Security, identified as version 1.0 beta 1, which outlines various security plugins, compliance requirements, and licensing terms for using the specification. It invites comments until October 15, 2014, and highlights the finalization phase, with the recommendation report expected to be published by April 3, 2015. The document also provides detailed information on conformance points, normative references, and guidelines for secure message exchange within DDS architecture.
![DDS Security v1.0 Beta 1 5
Cryptographic algorithm
A well-defined computational procedure that takes variable inputs, including a cryptographic key and
produces an output.
Cryptographic key
A parameter used in conjunction with a cryptographic algorithm that operates in such a way that
another agent with knowledge of the key can reproduce or reverse the operation, while an agent
without knowledge of the key cannot.
Examples include:
1. The transformation of plaintext data into ciphertext
2. The transformation of ciphertext data into plaintext
3. The computation of a digital signature from data
4. The verification of a digital signature
5. The computation of a message authentication code from data
6. The verification of a message authentication code from data and a received authentication
code
Data-Centric Publish-Subscribe (DCPS)
The mandatory portion of the DDS specification used to provide the functionality required for an
application to publish and subscribe to the values of data objects.
Data Distribution Service (DDS)
An OMG distributed data communications specification that allows Quality of Service policies to be
specified for data timeliness and reliability. It is independent of the implementation language.
Digital signature
The result of a cryptographic transformation of data that, when properly implemented with supporting
infrastructure and policy, provides the services of:
1. origin authentication
2. data integrity
3. signer non-repudiation
Extended IDL
Extended Interface Definition Language (IDL) used to describe data types in a way that can be
represented in a machine neutral format for network communications. This syntax was introduced as
part of the DDS-XTYPES specification [3].
Hashing algorithm
A one-way algorithm that maps an input byte buffer of arbitrary length to an output fixed-length byte
array in such a way that:
(a) Given the output it is computationally infeasible to determine the input.
(b) It is computationally infeasible to find any two distinct inputs that map to the same output.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-15-320.jpg)
![12 DDS Security v1.0 Beta1
7.2.1 Property
Property is a data type that holds a pair of strings. One string is considered the property “name” and
the other is the property “value” associated with that name. Property sequences are used as a
generic data type to configure the security plugins, pass metadata and provide an extensible
mechanism for vendors to configure the behavior of their plugins without breaking portability or
interoperability.
Property objects with names that start with the prefix “dds.sec.” are reserved by this
specification, including future versions of this specification. Plugin implementers can also use this
mechanism to pass metadata and configure the behavior of their plugins. In order to avoid collisions
with the value of the “name” attribute, implementers shall use property names that start with a prefix to
an ICANN domain name they own, in reverse order. For example,the prefix would be “com.acme.” for
plugins developed by a hypothetical vendor that owns the domain “acme.com”.
The names and interpretation of the expected properties shall be specified by each plugin
implementation.
Table 1 – Property class
Property
Attributes
name String
value String
7.2.1.1 IDL Representation for Property
The Property type may be used for information exchange over the network. When a Property is
sent over the network it shall be serialized using Extended CDR format according to the Extended IDL
representation [3] below.
@Extensibility (EXTENSIBLE_EXTENSIBILITY)
struct Property {
string key;
string value;
};
typedef sequence< Property > Properties;
7.2.2 BinaryProperty
BinaryProperty is a data type that holds a string and an octet sequence. The string is considered
the property “name” and the octet sequence the property “value” associated with that name. Sequences
of BinaryProperty are used as a generic data type to configure the plugins, pass metadata and
provide an extensible mechanism for vendors to configure the behavior of their plugins without
breaking portability or interoperability.
BinaryProperty objects with a “name” attribute that start with the prefix “dds.sec.” are
reserved by this specification, including future versions of this specification.
Plugin implementers may use this mechanism to pass metadata and configure the behavior of their
plugins. In order to avoid collisions with the value of the “name” attribute implementers, shall use](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-22-320.jpg)
![DDS Security v1.0 Beta 1 13
property names that start with a prefix to an ICANN domain name they own, in reverse order. For
example, the prefix would be “com.acme.” for plugins developed by a hypothetical vendor that owns
the domain “acme.com”.
The valid values of the “name” attribute and the interpretation of the associated “value” shall be
specified by each plugin implementation.
Table 2 – BinaryProperty class
BinaryProperty
Attributes
name String
value OctetSeq
7.2.2.1 IDL Representation for BinaryProperty
The BinaryProperty type may be used for information exchange over the network. When a
BinaryProperty is sent over the network, it shall be serialized using Extended CDR format
according to the Extended IDL representation [3] below.
@Extensibility (EXTENSIBLE_EXTENSIBILITY)
struct BinaryProperty {
string key;
OctetSeq value;
};
typedef sequence< BinaryProperty > BinaryProperties;
7.2.3 DataHolder
DataHolder is a data type used to hold generic data. It contains various attributes used to store data
of different types and formats. DataHolder appears as a building block for other types, such as
Token and GenericMessageData.
Table 3 – DataHolder class
DataHolder
Attributes
class_id String
string_properties PropertySeq
binary_properties BinaryPropertySeq
string_values StringSeq
binary_value1 OctetSeq
binary_value2 OctetSeq
longlongs_value LongLongSeq](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-23-320.jpg)
![14 DDS Security v1.0 Beta1
7.2.3.1 IDL representation for DataHolder
The DataHolder type may be used for information exchange over the network. When a
DataHolder is sent over the network, it shall be serialized using Extended CDR format according to
the Extended IDL representation [3] below.
typedef sequence<string> StringSeq;
typedef sequence<octet> OctetSeq;
typedef sequence<long long> LongLongSeq;
@Extensibility (EXTENSIBLE_EXTENSIBILITY)
struct DataHolder {
string class_id;
@Optional Properties string_properties;
@Optional BinaryProperties binary_properties;
@Optional StringSeq string_values;
@Optional OctetSeq binary_value1;
@Optional OctetSeq binary_value2;
@Optional LongLongSeq longlongs_value;
};
typedef sequence<DataHolder> DataHolderSeq;
7.2.4 Credential
Credential objects provide a generic mechanism to pass information from DDS to the security
plugins. This information is used to identify the application that is running and its permissions. The
Credential class provides a generic container for security credentials and certificates. The actual
interpretation of the credentials and how they are configured is specific to each implementation of the
security plugins and shall be specified by each security plugin.
The typical use of credentials would be signed certificates or signed permissions documents.
Credential objects are only exchanged locally between the DDS implementation and plugins
running in the same process space. They are never sent between processes or over a network.
The Credential class is structurally identical to the DataHolder class and therefore has the same
structure for all plugin implementations. However the contents and interpretation of the Credential
attributes shall be specified by each plugin implementation.
There are several specializations of the Credential class. They all share the same format but are
used for different purposes. This is modeled by defining specialized classes.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-24-320.jpg)
![DDS Security v1.0 Beta 1 15
class Credentials
Credential
IdentityCredential PermissionsCredential
DataHolder
- class_id :string
- string_properties :Property[]
- binary_properties :BinaryProperty[]
- string_values :string[]
- binary_value1 :byte[]
- binary_value2 :byte[]
- longlong_values :LongLong[]
Figure 3 – Credential Model
7.2.4.1 Attribute: class_id
When used as a Credential class, the class_id attribute in the DataHolder identifies the kind of
Credential
Values of the class_id with the prefix “dds.sec.” are reserved for this specification, including future
versions of the specification. Implementers of this specification can use this attribute to identify non-
standard credentials. In order to avoid collisions, the class_id they use shall start with a prefix to an
ICANN domain name they own, using the same rules specified in 7.2.1 for property names.
7.2.4.2 IDL Representation for Credential and Specialized Classes
The Credential class is used to hold information passed as parameters to the plugin operations. Its
structure can be defined in IDL such that the mapping to different programming languages is
unambiguously defined.
typedef DataHolder Credential;](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-25-320.jpg)
![16 DDS Security v1.0 Beta1
typedef Credential IdentityCredential;
typedef Credential PermissionsCredential;
7.2.5 Token
The Token class provides a generic mechanism to pass information between security plugins using
DDS as the transport. Token objects are meant for transmission over the network using DDS either
embedded within the builtin topics sent via DDS discovery or via special DDS Topic entities defined in
this specification.
The Token class is structurally identical to the DataHolder class and therefore has the same
structure for all plugin implementations. However, the contents and interpretation of the Token
objects shall be specified by each plugin implementation.
There are multiple specializations of the Token class. They all share the same format, but are used for
different purposes. This is modeled by defining specialized classes.
class Tokens
CryptoToken
Token
«discovery»
IdentityToken
«discovery»
PermissionsToken
MessageTokenPermissionsCredentialToken
DataHolder
- class_id :string
- string_properties :Property[]
- binary_properties :BinaryProperty[]
- string_values :string[]
- binary_value1 :byte[]
- binary_value2 :byte[]
- longlong_values :LongLong[]
Figure 4 – Token Model
7.2.5.1 Attribute: class_id
When used as a Token class, the class_id attribute in the DataHolder identifies the kind of Token
Strings with the prefix “dds.sec.” are reserved for this specification, including future versions of
the specification. Implementers of this specification can use this attribute to identify non-standard
tokens. In order to avoid collisions, the class_id they use shall start with a prefix to an ICANN domain
name they own, using the same rules specified in 7.2.1 for property names.
7.2.5.2 IDL Representation for Token and Specialized Classes
The Token class is used to hold information exchanged over the network. When a Token is sent over
the network, it shall be serialized using Extended CDR format according to the Extended IDL
representation below:](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-26-320.jpg)
![DDS Security v1.0 Beta 1 17
typedef DataHolder Token;
typedef Token HandshakeMessageToken;
typedef Token IdentityToken;
typedef Token PermissionsToken;
typedef Token IdentityCredentialToken;
typedef Token PermissionsCredentialToken;
typedef Token CryptoToken;
typedef Token ParticipantCryptoToken;
typedef Token DatawriterCryptoToken;
typedef Token DatareaderCryptoToken;
typedef sequence<HandshakeMessageToken> HandshakeMessageTokenSeq;
typedef sequence<CryptoToken> CryptoTokenSeq;
typedef CryptoTokenSeq ParticipantCryptoTokenSeq;
typedef CryptoTokenSeq DatawriterCryptoTokenSeq;
typedef CryptoTokenSeq DatareaderCryptoTokenSeq;
7.2.6 ParticipantGenericMessage
This specification introduces additional builtin DataWriter and DataReader entities used to send
generic messages between the participants. To support these entities, this specification uses a general-
purpose data type called ParticipantGenericMessage, which is defined by the following
extended IDL:
typedef octet[16] BuiltinTopicKey_t;
@Extensibility (EXTENSIBLE_EXTENSIBILITY)
struct MessageIdentity {
BuiltinTopicKey_t source_guid;
long long sequence_number;
};
typedef string<> GenericMessageClassId;
@Extensibility (EXTENSIBLE_EXTENSIBILITY)
struct ParticipantGenericMessage {
/* target for the request. Can be GUID_UNKNOWN */
MessageIdentity message_identity;
MessageIdentity related_message_identity;
BuiltinTopicKey_t destination_participant_key;
BuiltinTopicKey_t destination_endpoint_key;
BuiltinTopicKey_t source_endpoint_key;
GenericMessageClassId message_class_id;
DataHolderSeq message_data;
};](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-27-320.jpg)
![18 DDS Security v1.0 Beta1
7.2.7 Additional DDS Return Code: NOT_ALLOWED_BY_SEC
The DDS specification defines a set of return codes that may be returned by the operations on the DDS
API (see sub clause 7.1.1 of the DDS specification).
The DDS Security specification add an additional return code NOT_ALLOWED_BY_SEC, which
shall be returned by any operation on the DDS API that fails because the security plugins do not allow
it.
7.3 Securing DDS Messages on the Wire
OMG DDS uses the Real-Time Publish-Subscribe (RTPS) on-the-wire protocol [2] for communicating
data. The RTPS protocol includes specifications on how discovery is performed, the metadata sent
during discovery, and all the protocol messages and handshakes required to ensure reliability. RTPS
also specifies how messages are put together.
7.3.1 RTPS Background (Non-Normative)
In a secure system where efficiency and message latency are also considerations, it is necessary to
define exactly what needs to be secured. Some applications may require only the data payload to be
confidential and it is acceptable for the discovery information, as well as, the reliability meta-traffic
(HEARTBEATs, ACKs, NACKs, etc.) to be visible, as long as it is protected from modification. Other
applications may also want to keep the metadata (sequence numbers, in-line QoS) and/or the reliability
traffic (ACKs, NACKs, HEARTBEATs) confidential. In some cases, the discovery information (who is
publishing what and its QoS) may need to be kept confidential as well.
To help clarify these requirements, sub clause 7.3.1 explains the structure of the RTPS Message and
the different Submessages it may contain.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-28-320.jpg)
![DDS Security v1.0 Beta 1 21
7.3.3 Constraints of the DomainParticipant BuiltinTopicKey_t (GUID)
The DDS and the DDS Interoperability Wire Protocol specifications state that DDS
DomainParticipant entities are identified by a unique 16-byte GUID.
This DomainParticipant GUID is communicated as part of DDS Discovery in the
ParticipantBuiltinTopicData in the attribute participant_key of type
BuiltinTopicKey_t defined as:
typedef octet BuiltinTopicKey_t[16];
Allowing a DomainParticipant to select its GUID arbitrarily would allow hostile applications to
perform a “squatter” attack, whereby a DomainParticipant with a valid certificate could
announce itself into the DDS Domain with the GUID of some other DomainParticipant. Once
authenticated the “squatter” DomainParticipant would preclude the real
of the already existing
one.
To prevent the aforementioned “squatter” attack, this specification constrains the GUID that can be
chosen by a DomainParticipant, so that it is tied to the Identity of the DomainParticipant.
This is enforced by the Authentication plugin.
7.3.4 Mandatory use of the KeyHash for encrypted messages
The RTPS Data and DataFrag submessages can optionally contain the KeyHash as an inline Qos
(see sub clause 9.6.3.3, titled “KeyHash (PID_KEY_HASH)”) of the DDS-RTPS specification version
2.3. In this sub clause it is specified that when present, the key hash shall be computed either as the
serialized key or as an MD5 on the serialized key.
The key values are logically part of the data and therefore in situations where the data is considered
sensitive the key should also be considered sensitive.
For this reason the DDS Security specification imposes additional constrains in the use of the key hash.
These constraints apply only to the Data or DataFrag RTPS SubMessages where the
SerializedData SubmessageElement is encrypted by the operation
encode_serialized_data of the CryptoTransform plugin:
(1) The KeyHash shall be included in the Inline Qos.
(2) The KeyHash shall be computed as the 128 bit MD5 Digest (IETF RFC 1321) applied to the
CDR Big- Endian encapsulation of all the Key fields in sequence. Unlike the rule stated in sub
clause 9.6.3.3 of the DDS specification, the MD5 hash shall be used regardless of the
maximum-size of the serialized key.
These rules accomplish two objectives:
(1) Avoid leaking the value of the key fields in situations where the data is considered sensitive
and therefore appears encrypted within the Data or DataFrag submessages.
(2) Enable the operation of infrastructure services without needed to leak to them the value of the
key fields (see 7.1.1.4).
Note that the use of the MD5 hashing function for these purposes does not introduce significant
vulnerabilities. While MD5 is considered broken as far as resistance to collisions (being able to find](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-31-320.jpg)
![DDS Security v1.0 Beta 1 23
SecuredPayload. The specific format of this shall be defined by each Cryptographic plugin
implementation.
7.3.6.2 RTPS Submessage: SecureSubMsg
This specification introduces a new RTPS submessage: SecureSubMsg. The format of the
SecureSubMsg complies with the RTPS SubMessage format mandated in the RTPS specification.
It consists of the RTPS SubmessageHeader followed by a set of RTPS SubmessageElement
elements.
Since the SecureSubMsg conforms to the general structure of RTPS submessages, it can appear
inside a well-formed RTPS message.
class SecureSubmessage
RTPS::SubmessageHeader
- submessageId :SubmessageKind
- submessagLengh :ushort
- flags :SubmessageFlag[8]
SecureSubMsg
RTPS::Submessage
«interface»
CryptoTransformIdentifier
- transformationKind :long
- transformationId :octet[8]
SecuredPayload
- transformationId :CryptoTransformIdentifier
- value :octet[*]
RTPS::SubmessageElement0..*
«use»
1
Figure 6 – Secure Submessage and Secured Payload Model
7.3.6.2.1 Purpose
The SecureSubMsg submessage is used to wrap one or more regular RTPS submessages in such a
way that their contents are secured via encryption, message authentication, and/or digital signatures.
7.3.6.2.2 Content
The elements that form the structure of the RTPS SecureSubMsg are described in the table below.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-33-320.jpg)
![DDS Security v1.0 Beta 1 25
Figure 7 – RTPS message transformations
7.3.7 Mapping to UDP/IP PSM
The DDS-RTPS specification defines the RTPS protocol in terms of a platform-independent model
(PIM) and then maps it to a UDP/IP transport PSM (see clause 9, “Platform Specific Model (PSM):
UDP/IP” of the DDS-RTPS specification [2]).
Sub clause 7.3.7 does the same thing for the new RTPS submessage elements and submessages
introduced by the DDS Security specification.
7.3.7.1 Mapping of the EntityIds for the Builtin DataWriters and DataReaders
Sub clause 7.4 defines a set of builtin Topics and corresponding DataWriter and DataReader entities
that shall be present on all compliant implementations of the DDS Security specification. The
corresponding EntityIds used when these endpoints are used on the UDP/IP PSM are given in the table
below.
Table 5 – EntityId values for secure builtin data writers and data readers
Entity EntityId_t name EntityId_t value
SEDPbuiltinPublicationsSecureWr](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-35-320.jpg)
![26 DDS Security v1.0 Beta1
iter
SEDPbuiltinPublicationsSecureRe
ader
SEDPbuiltinSubscriptionsSecureW
riter
SEDPbuiltinSubscriptionsSecureR
eader
BuiltinParticipantMessageSecure
Writer
BuiltinParticipantMessageSecure
Reader
BuiltinParticipantStatelessMessag
eWriter
BuiltinParticipantStatelessMessag
eReader
BuiltinParticipantVolatileMessage
SecureWriter
BuiltinParticipantVolatileMessage
SecureReader
7.3.7.2 Mapping of the CryptoTransformIdentifier Type
The UDP/IP PSM maps the CryptoTransformIdentifier to the following extended IDL
structure:
typedef octet OctetArray8[8];
@Extensibility(FINAL_EXTENSIBILITY)
struct CryptoTransformIdentifier {
long transformationKind;
OctetArray8 transformationId;
};
The CryptoTransformIdentifier shall be serialized using CDR using the endianess specified
by the EndianessFlag in the SubmessageHeader.
7.3.7.3 Mapping of the SecuredPayload SubmessageElement
A SecuredPayload SubmessageElement contains the result of cryptographically transforming
either an RTPS Message or a single RTPS Submessage. In both cases the SecuredPayload shall
start with the CryptoTransformIdentifier and be followed by the ciphertext returned by the
encoding transformation.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-36-320.jpg)
![DDS Security v1.0 Beta 1 27
The UDP/IP wire representation for the SecuredPayload shall be:
0...2...........8...............16.............24...............32
+---------------+---------------+---------------+---------------+
| long transformationKind |
+---------------+---------------+---------------+---------------+
| |
+ octet transformationId[8] +
| |
+---------------+---------------+---------------+---------------+
| |
~ octet ciphertext[] ~
| |
+---------------+---------------+---------------+---------------+
7.3.7.4 SecureSubMsg Submessage
7.3.7.4.1 Wire Representation
The UDP/IP wire representation for the SecureSubMsg shall be:
0...2...........8...............16.............24...............32
+---------------+---------------+---------------+---------------+
| SecureSubMsgId|X|X|X|X|X|X|S|E| octetsToNextHeader |
+---------------+---------------+---------------+---------------+
| |
+ SecuredPayload payload +
| |
+---------------+---------------+---------------+---------------+
7.3.7.4.2 Submessage Id
The SecureSubMsg shall have the submessageId set to the value 0x30.
7.3.7.4.3 Flags in the Submessage Header
In addition to the EndiannessFlag, the SecureSubMsg introduces the SingleSubmessageFlag (see
7.3.6.2.2). The PSM maps these flags as follows:
The SingleSubmessageFlag is represented with the literal ‘S.’ The value of the InlineQosFlag can be
obtained from the expression:
S = SubmessageHeader.flags & 0x02
The SingleSubmessageFlag is interpreted as follows:
S=0 means that the SecureSubMsg submessage is an envelope for a full RTPS message.
S=1 means that the SecureSubMsg submessage is an envelope for a single RTPS submessage.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-37-320.jpg)
![28 DDS Security v1.0 Beta1
7.4 DDS Support for Security Plugin Information Exchange
In order to perform their function, the security plugins associated with different DDS
DomainParticipant entities need to exchange information representing things such as Identity
and Permissions of the DomainParticipant entities, authentication challenge messages, tokens
representing key material, etc.
DDS already has several mechanisms for information exchange between DomainParticipant
entities. Notably the builtin DataWriter and DataReader entities used by the Simple Discovery
Protocol (see sub clause 8.5 of the DDS Interoperability Wire Protocol [2]) and the
BuiltinParticipantMessageWriter and BuiltinParticipantMessageReader (see sub clause 9.6.2.1 of the
DDS Interoperability Wire Protocol [2]).
Where possible, this specification tries to reuse and extend existing DDS concepts and facilities so that
they can fulfill the needs of the security plugins, rather than defining entirely new ones. This way, the
Security Plugin implementation can be simplified and it does not have to implement a separate
messaging protocol.
7.4.1 Secure builtin Discovery Topics
7.4.1.1 Background (Non-Normative)
DDS discovery information is sent using builtin DDS DataReaders and DataWriters. These are
regular DDS DataReaders and DataWriters, except they are always present in the system and
their Topic names, associated data types, QoS, and RTPS EntityIds are all specified as part of the
DDS and RTPS specifications, so they do not need to be discovered.
The DDS specification defines three discovery builtin Topic entities: the DCPSParticipants used to
discover the presence of DomainParticipants, the DCPSPublications used to discover
DataWriters, and the DCPSSubscriptions used to discover DataReaders (see sub clause 8.5 of
the DDS Interoperability Wire Protocol [2]).
Much of the discovery information could be considered sensitive in secure DDS systems. Knowledge
of things like the Topic names that an application is publishing or subscribing to could reveal
sensitive information about the nature of the application. In addition, the integrity of the discovery
information needs to be protected against tampering, since could cause erroneous behaviors or
malfunctions.
One possible approach to protecting discovery information would be to require that the discovery
builtin Topic entities always be protected via encryption and message authentication. However, this
would entail the problems explained below.
The DCPSParticipants builtin Topic is used to bootstrap the system, detect the presence of
DomainParticipant entities, and kick off subsequent information exchanges and handshakes. It
contains the bare minimum information needed to establish protocol communications (addresses, port
numbers, version number, vendor IDs, etc.). If this Topic were protected, the Secure DDS system
would have to create an alternative mechanism to bootstrap detection of other participants and gather
the same information—which needs to happen prior to being able to perform mutual authentication and
exchange of key material. This mechanism would, in essence, duplicate the information in the
DCPSParticipants builtin Topic. Therefore, it makes little sense to protect the DCPSParticipants
builtin Topic. A better approach is to augment the information sent using the DCPSParticipants](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-38-320.jpg)
![DDS Security v1.0 Beta 1 29
builtin Topic with any additional data the Secure DDS system needs for bootstrapping
communications (see 7.4.1.3).
Secure DDS systems need to co-exist in the same network and, in some cases, interoperate with non-
secure DDS systems. There may be systems built using implementations compliant with the DDS
Security specification which do not need to protect their information. Or there may be systems
implemented with legacy DDS implementations that do not support DDS Security. In this situation, the
fact that a secure DDS implementation is present on the network should not impact the otherwise
correct behavior of the non-secure DDS systems. In addition, even in secure systems not all Topics are
necessarily sensitive, so it is desirable to provide ways to configure a DDS Secure system to have
Topics that are “unprotected” and be able to communicate with non-secure DDS systems on those
“unprotected” Topics.
To allow co-existence and interoperability between secure DDS systems and DDS systems that do not
implement DDS security, secure DDS systems must retain the same builtin Topics as the regular DDS
systems (with the same GUIDs, topics names, QoS, and behavior). Therefore, to protect the discovery
and liveliness information of Topics that are considered sensitive, Secure DDS needs to use additional
builtin discovery Topics protected by the DDS security mechanisms.
7.4.1.2 Extending the Data Types used by DDS Discovery
The DDS Interoperability Wire Protocol specifies the serialization of the data types used for the
discovery of builtin Topics (ParticipantBuiltinTopicData, PublicationBuiltinTopicData, and
SubscriptionBuiltinTopicData) using a representation called using a ParameterList. Although this
description precedes the DDS-XTYPES specification, the serialization format matches the Extended
CDR representation defined in DDS-XTYPES for data types declared with MUTABLE extensibility.
This allows the data type associated with discovery topics to be extended without breaking
interoperability.
Given that DDS-XTYPES formalized the ParameterList serialization approach, first defined in the
DDS Interoperability and renamed it to “Extended CDR,” this specification will use the DDS
Extensible Types notation to define the data types associated with the builtin Topics. This does not
imply that compliance to the DDS-XTYPES is required to comply with DDS Security. All that is
required is to serialize the specific data types defined here according to the format described in the
DDS-XTYPES specification.
7.4.1.3 Extension to RTPS Standard DCPSParticipants Builtin Topic
The DDS specification specifies the existence of the DCPSParticipants builtin Topic and a
corresponding builtin DataWriter and DataReader to communicate this Topic. These
endpoints are used to discover DomainParticipant entities.
The data type associated with the DCPSParticipants builtin Topic is ParticipantBuiltinTopicData,
defined in sub clause 7.1.5 of the DDS specification.
The DDS Interoperability Wire Protocol specifies the serialization of ParticipantBuiltinTopicData.
The format used is what the DDS Interoperability Wire Protocol calls a ParameterList whereby each
member of the ParticipantBuiltinTopicData is serialized using CDR but preceded in the stream by the
serialization of a short ParameterID identifying the member, followed by another short containing the
length of the serialized member, followed by the serialized member. See sub clause 8.3.5.9 of the DDS
Interoperability Wire Protocol [2]. This serialization format allows the ParticipantBuiltinTopicData to
be extended without breaking interoperability.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-39-320.jpg)
![32 DDS Security v1.0 Beta1
@extensibility(MUTABLE_EXTENSIBILITY)
struct SubscriptionBuiltinTopicDataSecure: SubscriptionBuiltinTopicData {
@ID(0x1003) DataTags data_tags;
};
The QoS associated with the DCPSSubscriptionsSecure Topic shall be the same as for the
DCPSSubscriptions Topic.
The builtin DataWriter for the DCPSSubscriptionsSecure Topic shall be referred to as the
SEDPbuiltinSubscriptionsSecureWriter. The builtin DataReader for the DCPSPublicationsSecure
Topic shall be referred to as the SEDPbuiltinSubscriptionsSecureReader.
The RTPS EntityId_t associated with the SEDPbuiltinSubscriptionsSecureWriter and
SEDPbuiltinSubscriptionsSecureReader shall be as specified in 7.4.5.
7.4.2 New ParticipantMessageSecure builtin Topic
The DDS Interoperability Wire Protocol specifies the BuiltinParticipantMessageWriter and
BuiltinParticipantMessageReader (see sub clauses 8.4.13 and 9.6.2.1 of the DDS Interoperability
Wire Protocol[2]). These entities are used to send information related to the LIVELINESS QoS. This
information could be considered sensitive and therefore secure DDS systems need to provide an
alternative protected way to send liveliness information.
The data type associated with these endpoints is ParticipantMessageData defined in sub clause 9.6.2.1
of the DDS Interoperability Wire Protocol specification [2].
To support coexistence and interoperability with non-secure DDS applications, implementations of the
DDS Security specification shall use the same standard BuiltinParticipantMessageWriter and
BuiltinParticipantMessageReader to communicate liveliness information on Topic entities that are
not considered sensitive.
Implementations of the DDS Security specification shall have an additional
ParticipantMessageSecure builtin Topic and associated builtin DataReader and DataWriter
entities to communicate the liveliness information for Topic entities that are considered sensitive.
The data type associated with the ParticipantMessageSecure Topic shall be the same as the
ParticipantMessageData structure.
The QoS associated with the ParticipantMessageSecure Topic shall be the same as for the
ParticipantMessageSecure Topic as defined in sub clause 8.4.13 of the DDS Interoperability Wire
Protocol [2].
The builtin DataWriter for the ParticipantMessageSecure Topic shall be referred to as the
BuiltinParticipantMessageSecureWriter. The builtin DataReader for the
ParticipantMessageSecure Topic shall be referred to as the
BuiltinParticipantMessageSecureReader.
The RTPS EntityId_t associated with the BuiltinParticipantMessageSecureWriter and
BuiltinParticipantMessageSecureReader shall be as specified in 7.4.5.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-42-320.jpg)
![DDS Security v1.0 Beta 1 33
7.4.3 New ParticipantStatelessMessage builtin Topic
To perform mutual authentication between DDS DomainParticipant entities, the security plugins
associated with those participants need to be able to send directed messages to each other. As described
in 7.4.3.1 below, the mechanisms provided by existing DDS builtin Topic entities are not adequate
for this purpose. For this reason, this specification introduces a new ParticipantStatelessMessage
builtin Topic and corresponding builtin DataReader and DataWriter entities to read and write
the Topic.
7.4.3.1 Background: Sequence Number Attacks (non normative)
DDS has a builtin mechanism for participant-to-participant messaging: the
BuiltinParticipantMessageWriter and BuiltinParticipantMessageReader (see sub clause 9.6.2.1 of the
DDS Interoperability Wire Protocol [2]). However this mechanism cannot be used for mutual
authentication because it relies on the RTPS reliability protocol and suffers from the sequence-number
prediction vulnerability present in unsecured reliable protocols:
The RTPS reliable protocol allows a DataWriter to send to a DataReader Heartbeat
messages that advance the first available sequence number associated with the DataWriter. A
DataReader receiving a Heartbeat from a DataWriter will advance its first available
sequence number for that DataWriter and ignore any future messages it receives with sequence
numbers lower than the first available sequence number for the DataWriter. The reliable
DataReader will also ignore duplicate messages for that same sequence number.
The behavior of the reliability protocol would allow a malicious application to prevent other
applications from communicating by sending Heartbeats pretending to be from other
DomainParticipants that contain large values of the first available sequence number. All the
malicious application needs to do is learn the GUIDs of other applications, which can be done from
observing the initial discovery messages on the wire, and use that information to create fake
Heartbeats.
Stated differently: prior to performing mutual authentication and key exchange, the applications cannot
rely on the use of encryption and message access codes to protect the integrity of the messages.
Therefore, during this time window, they are vulnerable to this kind of sequence-number attack. This
attack is present in most reliable protocols. Stream-oriented protocols such as TCP are also vulnerable
to sequence-number-prediction attacks but they make it more difficult by using a random initial
sequence number on each new connection and discarding messages with sequence numbers outside the
window. This is something that RTPS cannot do given the data-centric semantics of the protocol.
In order to avoid this vulnerability, the Security plugins must exchange messages using writers and
readers sufficiently robust to sequence number prediction attacks. The RTPS protocol specifies
endpoints that meet this requirement: the RTPS StatelessWriter and StatelessReader (see
8.4.7.2 and 8.4.10.2 of the DDS Interoperability Wire Protocol [2]) but there are not DDS builtin
endpoints that provide access to this underlying RTPS functionality.
7.4.3.2 BuiltinParticipantStatelessMessageWriter and BuiltinParticipantStatelessMessageReader
The DDS Security specification defines two builtin Endpoints: the
BuiltinParticipantStatelessMessageWriter and the BuiltinParticipantStatelessMessageReader. These
two endpoints shall be present in compliant implementations of this specification. These endpoints are
used to write and read the builtin ParticipantStatelessMessage Topic.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-43-320.jpg)
![34 DDS Security v1.0 Beta1
The BuiltinParticipantStatelessMessageWriter is an RTPS Best-Effort StatelessWriter (see sub
clause 8.4.7.2 of the DDS Interoperability Wire Protocol [2]).
The BuiltinParticipantStatelessMessageReader is an RTPS Best-Effort StatelessReader (see
sub clause 8.4.10.2 of the DDS Interoperability Wire Protocol [2]).
The data type associated with these endpoints is ParticipantStatelessMessage defined
below (see also 7.2.6):
typedef ParticipantStatelessMessage ParticipantGenericMessage;
The RTPS EntityId_t associated with the BuiltinParticipantStatelessMessageWriter and
BuiltinParticipantStatelessMessageReader shall be as specified in 7.4.5.
7.4.3.3 Contents of the ParticipantStatelessMessage
The ParticipantStatelessMessage is intended as a holder of information that is sent point-
to-point from a DomainParticipant to another.
The message_identity uniquely identifies each individual ParticipantStatelessMessage:
The source_guid field within the message_identity shall be set to match the
BuiltinTopicKey_t of the BuiltinParticipantStatelessMessageWriter that writes the message.
The sequence_number field within the message_identity shall start with the value set to one and be
incremented for each different message sent by the BuiltinParticipantStatelessMessageWriter.
The related_message_identity uniquely identifies another ParticipantStatelessMessage that
is related to the message being processed. It shall be set to either the tuple {GUID_UNKNOWN, 0} if
the message is not related to any other message, or else set to match the message_identity of the
related ParticipantStatelessMessage.
The destination_participant_key shall contain either the value GUID_UNKNOWN (see sub clause
9.3.1.5 of the DDS Interoperability Wire Protocol [2]) or else the BuiltinTopicKey_t of the
destination DomainParticipant.
The destination_endpoint_key provides a mechanism to specify finer granularity on the intended
recipient of a message beyond the granularity provided by the destination_participant_key. It can
contain either GUID_UNKNOWN or else the GUID of a specific endpoint within destination
DomainParticipant. The targeted endpoint is the one whose Endpoint (DataWriter or
DataReader) BuiltinTopic_t matches the destination_endpoint_key.
The contents message_data depend on the value of the message_class_id and are defined in this
specification in the sub clause that introduces each one of the pre-defined values of the
GenericMessageClassId. See 7.4.3.5 and 7.4.3.6.
7.4.3.4 Destination of the ParticipantStatelessMessage
If the destination_participant_key member is not set to GUID_UNKNOWN, the message written is
intended only for the BuiltinParticipantStatelessMessageReader belonging to the
DomainParticipant with a matching Participant Key.
This is equivalent to saying that the BuiltinParticipantStatelessMessageReader has an implied content
filter with the logical expression:](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-44-320.jpg)
![36 DDS Security v1.0 Beta1
to be explicitly encrypted and signed prior to being given to the
ParticipantStatelessMessageWriter.
The new ParticipantMessageSecure is not suitable because its QoS is has DURABILITY kind
TRANSIENT_LOCAL (see sub clause 8.4.13 of the DDS Interoperability Wire Protocol [2]) rather
than the required DURABILITY kind VOLATILE.
For this reason, implementations of the DDS Security specification shall have an additional builtin
Topic ParticipantVolatileMessageSecure and corresponding builtin DataReader and
DataWriter entities to read and write the Topic.
7.4.4.2 BuiltinParticipantVolatileMessageSecureWriter and
BuiltinParticipantVolatileMessageSecureReader
The DDS Security specification defines two new builtin Endpoints: The
BuiltinParticipantVolatileMessageSecureWriter and the
BuiltinParticipantVolatileMessageSecureReader. These two endpoints shall be present in compliant
implementations of this specification. These endpoints are used to write and read the builtin
ParticipantVolatileSecureMessage Topic.
The BuiltinParticipantVolatileMessageSecureWriter is an RTPS Reliable StatefulWriter (see sub
clause 8.4.9.2 of the DDS Interoperability Wire Protocol [2]). The DDS DataWriter Qos associated
with the DataWriter shall be as defined in the table below. Any policies that are not shown in the
table shall be set corresponding to the DDS defaults.
Table 9 – Non-default Qos policies for BuiltinParticipantVolatileMessageSecureWriter
The BuiltinParticipantVolatileMessageSecureReader is an RTPS Reliable StatefulReader (see sub
clause 8.4.11.2 of the DDS Interoperability Wire Protocol [2]). The DDS DataReader Qos
associated with the DataReader shall be as defined in the table below. Any policies that are not
shown in the table shall be set corresponding to the DDS defaults.
Table 10 – Non-default Qos policies for BuiltinParticipantVolatileMessageSecureReader
The data type associated with these endpoints is ParticipantVolatileSecureMessage
defined as:
typedef ParticipantVolatileSecureMessage ParticipantGenericMessage;](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-46-320.jpg)
![DDS Security v1.0 Beta 1 37
The RTPS EntityId_t associated with associated with the
BuiltinParticipantVolatileMessageSecureWriter and
BuiltinParticipantVolatileMessageSecureReader shall be as specified in 7.4.5.
7.4.4.3 Contents of the ParticipantVolatileSecureMessage
The ParticipantVolatileSecureMessage is intended as a holder of secure information that
is sent point-to-point from a DomainParticipant to another.
The destination_participant_key shall contain either the value GUID_UNKNOWN (see sub clause
9.3.1.5 of the DDS Interoperability Wire Protocol [2] or else the BuiltinTopicKey_t of the
destination DomainParticipant.
The message_identity uniquely identifies each individual
ParticipantVolatileSecureMessage:
The source_guid field within the message_identity shall be set to match the
BuiltinTopicKey_t of the BuiltinParticipantVolatileMessageSecureWriter that writes the
message.
The sequence_number field within the message_identity shall start with the value set to one and be
incremented for each different message sent by the
BuiltinParticipantVolatileMessageSecureWriter.
The related_message_identity uniquely identifies another
ParticipantVolatileSecureMessage that is related to the message being processed. It shall
be set to either the tuple {GUID_UNKNOWN, 0} if the message is not related to any other message, or
else set to match the message_identity of the related ParticipantVolatileSecureMessage.
The contents message_data depend on the value of the message_class_id and are defined in this
specification in the sub clause that introduces each one of the defined values of the
GenericMessageClassId, see 7.4.4.5.
7.4.4.4 Destination of the ParticipantVolatileSecureMessage
If the destination_participant_key member is not set to GUID_UNKNOWN, the message written is
intended only for the BuiltinParticipantVolatileMessageSecureReader belonging to the
DomainParticipant with a matching Participant Key.
This is equivalent to saying that the BuiltinParticipantVolatileMessageSecureReader has an implied
content filter with the logical expression:
“destination_participant_key == GUID_UNKNOWN
|| destination_participant_key ==
BuiltinParticipantVolatileMessageSecureReader.participant.key”
Implementations of the specification can use this content filter or some other mechanism as long as the
resulting behavior is equivalent to having this filter.
If the destination_endpoint_key member is not set to GUID_UNKNOWN the message written targets
a specific endpoint within the destination DomainParticipant. The targeted endpoint is the one whose
Endpoint Key (DataWriter or DataReader BuiltinTopic_t) matches the destination_endpoint_key. This](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-47-320.jpg)
![DDS Security v1.0 Beta 1 45
8.3.2.8 Authentication
This interface is the starting point for all the security mechanisms. When a DomainParticipant
is either locally created or discovered, it needs to be authenticated in order to be able to communicate
in a DDS Domain.
The interaction between the DDS implementation and the Authentication plugin has been designed in a
flexible manner so it is possible to support various authentication mechanisms, including those that
require a handshake and/or perform mutual authentication between participants. It also supports the
establish a shared secret. This interaction is described in the state machine illustrated in the figure
below.
stm AuthBehavior
HandshakeInit
HandshakeInitReply
Choice
Initialized
EntryPoint
Validation_OK
Validation_Failed
HandshakeMessageSend
Choice
HandshakeCompletedOK
HandshakeMessageWait
HandshakeInitMessageWait
HandshakeFinalMessage
HandshakeMessageReceived
[VALIDATION_FAILED]
begin_handshake_reply()
[VALIDATION_PENDING_HANDSHAKE_REQUEST] [VALIDATION_PENDING_HANDSHAKE_MESSAGE]
[VALIDATION_OK] [VALIDATION_FAILED]
validate_remote_identity()
begin_handshake_request()
DDS::send_message()
process_handshake()
[VALIDATION_OK]
[VALIDATION_PENDING_HANDSHAKE_MESSAGE]
[VALIDATION_OK_WITH_FINAL_MESSAGE]
get_shared_secret()
DDS::receive_message()
DDS::receive_message()
DDS::send_message()
validate_local_identity()
Figure 10 – Authentication plugin interaction state machine
8.3.2.8.1 Reliability of the Authentication Handshake
In order to be sufficiently robust to avert sequence number attacks (7.4.3.1), the Authentication
Handshake uses the BuiltinParticipantStatelessMessageWriter and
BuiltinParticipantStatelessMessageReader endpoints (7.4.3) with GenericMessageClassId set
to GMCLASSID_SECURITY_AUTH_HANDSHAKE (7.4.3.5). These stateless endpoints send
messages best-effort without paying attention to any sequence number information to remove](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-55-320.jpg)
![80 DDS Security v1.0 Beta1
8.5 Cryptographic Plugin
The Cryptographic plugin defines the types and operations necessary to support encryption,
digest, message authentication codes, and key exchange for DDS DomainParticipants,
DataWriters and DDS DataReaders.
Users of DDS may have specific cryptographic libraries they use for encryption, as well as, specific
requirements regarding the algorithms for digests, message authentication, and signing. In addition,
applications may require having only some of those functions performed, or performed only for certain
DDS Topics and not for others. Therefore, the plugin API has to be general enough to allow flexible
configuration and deployment scenarios.
8.5.1 Cryptographic Plugin Model
The Cryptographic plugin model is presented in the figure below. It combines related
cryptographic interfaces for key creation, key exchange, encryption, message authentication, hashing,
and signature.
class Cryptographic
«interface»
Cryptographic
«interface»
CryptoKeyFactory
+ register_local_participant() :ParticipantCryptoHandle
+ register_matched_remote_participant() :ParticipantCryptoHandle
+ register_local_datawriter() :DatawriterCryptoHandle
+ register_matched_remote_datareader() :DatareaderCryptoHandle
+ register_local_datareader() :DatareaderCryptoHandle
+ register_matched_remote_datawriter() :DatawriterCryptoHandle
+ unregister_participant() :Boolean
+ unregister_datawriter() :Boolean
+ unregister_datareader() :Boolean
«primitive»
ParticipantCryptoHandle
«primitive»
DatawriterCryptoHandle
«primitive»
DatareaderCryptoHandle
«interface»
CryptoKeyExchange
+ create_local_participant_crypto_tokens() :Boolean
+ set_remote_participant_crypto_tokens() :Boolean
+ create_local_datawriter_crypto_tokens() :Boolean
+ set_remote_datawriter_crypto_tokens() :Boolean
+ create_local_datareader_crypto_tokens() :Boolean
+ set_remote_datareader_crypto_tokens() :Boolean
+ return_cypto_tokens() :Boolean
«interface»
CryptoTransform
+ encode_serialized_data() :Boolean
+ encode_datawriter_submessage() :Boolean
+ encode_datareader_submessage() :Boolean
+ encode_rtps_message() :Boolean
+ decode_rtps_message() :Boolean
+ preprocess_rtps_submessage() :Boolean
+ decode_datawriter_submessage() :Boolean
+ decode_datareader_submessage() :Boolean
+ decode_serialized_data() :Boolean
Token
CryptoToken
«primitive»
IdentityHandle
«primitive»
PermissionsHandle
«dataType»
CryptoTransformIdentifier
- transformation_kind_id :octet[4]
- transformation_key_id :octet[8]
«primitive»
SharedSecretHandle
Figure 12 – Cryptographic Plugin Model
8.5.1.1 CryptoToken
This class represents a generic holder for key material. A CryptoToken object contains all the
information necessary to construct a set of keys to be used to encrypt and/or sign plain text
transforming it into cipher-text or to reverse those operations.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-90-320.jpg)
![DDS Security v1.0 Beta 1 81
The format and interpretation of the CryptoToken depends on the implementation of the
Cryptographic plugin. Each plugin implementation shall fully define itself, so that applications are able
to interoperate. In general, the CryptoToken will contain one or more keys and any other necessary
material to perform crypto-transformation and/or verification, such as, initialization vectors (IVs),
salts, etc.
8.5.1.2 ParticipantCryptoHandle
The ParticipantCryptoHandle object is an opaque local reference that represents the key
material used to encrypt and sign whole RTPS Messages. It is used by the operations
encode_rtps_message and decode_rtps_message.
8.5.1.3 DatawriterCryptoHandle
The DatawriterCryptoHandle object is an opaque local reference that represents the key
material used to encrypt and sign RTPS submessages sent from a DataWriter. This includes the RTPS
submessages Data, DataFrag, Gap, Heartbeat, and HeartbeatFrag, as well as, the
SerializedData submessage element that appears in the Data and DataFrag submessages.
It is used by the operations encode_datawriter_submessage,
decode_datawriter_submessage, encode_serialized_data, and
decode_serialized_data.
8.5.1.4 DatareaderCryptoHandle
The DatareaderCryptoHandle object is an opaque local reference that represents the key
material used to encrypt and sign RTPS Submessages sent from a DataReader. This includes the
RTPS Submessages AckNack and NackFrag.
It is used by the operations encode_datareader_submessage,
decode_datareader_submessage.
8.5.1.5 CryptoTransformIdentifier
The CryptoTransformIdentifier object used to uniquely identify the transformation applied
on the sending side (encoding) so that the receiver can locate the necessary key material to perform the
inverse transformation (decoding). The generation of CryptoTransformIdentifier is
performed by the Cryptographic plugin.
To enable interoperability and avoid misinterpretation of the key material, the structure of the
CryptoTransformIdentifier is defined for all Cryptographic plugin implementations as
follows:
Table 20 – CryptoTranformIdentifier class
CryptoTransformIdentifier
Attributes
transformation_kind_id octet[4]
transformation_key_id octet[8]](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-91-320.jpg)
![82 DDS Security v1.0 Beta1
8.5.1.5.1 Attribute: transformation_kind_id
Uniquely identifies the type of cryptographic transformation
Values of transformation_kind_id having the first two octets set to zero are reserved by this
specification, including future versions of this specification.
Implementers can use the transformation_kind_id attribute to identify non-standard
cryptographic transformations. In order to avoid collisions, the first two octets in the
transformation_kind_id shall be set to a registered RTPS VendorId [36]. The RTPS
VendorId used shall either be one reserved to the implementer of the Cryptographic Plugin, or else
the implementer of the Cryptographic Plugin shall secure permission from the registered owner of
the RTPS VendorId to use it.
8.5.1.5.2 Attribute: transformation_key_id
Uniquely identifies the key material used to perform a cryptographic transformation within the scope
of all transformations that could be performed by transformations belonging to that
transformation_kind_id.
In combination with the transformation_kind_id, the transformation_key_id attribute
allows the receiver to select the proper key material to decrypt/verify a message that has been
encrypted and/or signed. The use of this attribute allows a receiver to be robust to dynamic changes in
keys and key material in the sense that it can identify the correct key or at least detect that it does not
have the necessary keys and key material.
The values of the transformation_key_id are defined by the Cryptographic plugin
implementation and understood only by that plugin.
8.5.1.6 SecureSubmessageCategory_t
Enumerates the possible categories of RTPS submessages.
Table 21 – SecureSubmessageCategory_t
SecureSubmessageCategory_t
INFO_SUBMESSAGE Indicates an RTPS Info submesage: InfoSource, InfoDestination, or
InfoTimestamp.
DATAWRITER_SUMBES
SAGE
Indicates an RTPS submessage that was sent from a DataWriter: Data,
DataFrag, HeartBeat, Gap.
DATAREADER_SUMBES
SAGE
Indicates an RTPS submessage that was sent from a DataReader:
AckNack, NackFrag.
8.5.1.7 CryptoKeyFactory interface
This interface groups the operations related to the creation of keys used for encryption and digital
signing of both the data written by DDS applications and the RTPS submessage and message headers,
used to implement the discovery protocol, distribute the DDS data, implement the reliability protocol,
etc.
Table 22 – CryptoKeyFactory Interface](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-92-320.jpg)
![96 DDS Security v1.0 Beta1
transformation to perform (encrypt and/or produce a digest and/or a MAC and/or signature) is left to
the plugin implementation.
Table 24 – CryptoTransform interface
CryptoTransform
No Attributes
Operations
Boolean
out:
encoded_buffer
octet[]
plain_buffer octet[]
sending_datawrit
er_crypto
DatawriterCryptoHandle
encode_serialized_da
ta
out: exception SecurityException
Boolean
out:
encoded_rtps_sub
message
octet[]
plain_rtps_subme
ssage
octet[]
sending_datawrit
er_crypto
DatawriterCryptoHandle
receiving_datare
ader_crypto_list
DatareaderCryptoHandle[]
encode_datawriter_su
bmessage
out: exception SecurityException
Boolean
out:
encoded_rtps_sub
message
octet[]
plain_rtps_subme
ssage
octet[]
sending_dataread
er_crypto
DatareaderCryptoHandle
receiving_datawr
iter_crypto_list
DatawriterCryptoHandle[]
encode_datareader_su
bmessage
out: exception SecurityException
encode_rtps_message Boolean](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-106-320.jpg)
![DDS Security v1.0 Beta 1 97
out:
encoded_rtps_mes
sage
octet[]
plain_rtps_messa
ge
octet[]
sending_crypto ParticipantCryptoHandle
receiving_crypto
_list
ParticipantCryptoHandle[]
out: exception SecurityException
Boolean
out:
plain_buffer
octet[]
encoded_buffer octet[]
receiving_crypto ParticipantCryptoHandle
sending_crypto ParticipantCryptoHandle
decode_rtps_message
out: exception SecurityException
Boolean
out:
datawriter_crypt
o
DatawriterCryptoHandle
out:
datareader_crypt
o
DatareaderCryptoHandle
out:
secure_submessag
e_category
DDS_SecureSumessageCatego
ry_t
in:
encoded_rtps_sub
message
octet[]
receiving_crypto ParticipantCryptoHandle
sending_crypto ParticipantCryptoHandle
preprocess_secure_su
bmsg
out: exception SecurityException
Booleandecode_datawriter_su
bmessage
out:
plain_rtps_subme
octet[]](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-107-320.jpg)
![98 DDS Security v1.0 Beta1
8.5.1.9.1 Operation: encode_serialized_data
This operation shall be called by the DDS implementation as a result of the application calling the
write operation on the DataWriter associated with the DatawriterCryptoHandle specified in the
sending_datawriter_crypto parameter.
The operation receives the data written by the DataWriter in serialized form wrapped inside the RTPS
SerializedData submessage element and shall output a RTPS SecuredPayload submessage
element.
ssage
encoded_rtps_sub
message
octet[]
receiving_datare
ader_crypto
DatareaderCryptoHandle
sending_datawrit
er_crypto
DatawriterCryptoHandle
out: exception SecurityException
Boolean
out:
plain_rtps_subme
ssage
octet[]
encoded_rtps_sub
message
octet[]
receiving_datawr
iter_crypto
DatawriterCryptoHandle
sending_dataread
er_crypto
DatareaderCryptoHandle
decode_datareader_su
bmessage
out: exception SecurityException
Boolean
out:
plain_buffer
octet[]
encoded_buffer octet[]
receiving_datare
ader_crypto
DatareaderCryptoHandle
sending_datawrit
er_crypto
DatawriterCryptoHandle
decode_serialized_da
ta
out: exception SecurityException](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-108-320.jpg)
![DDS Security v1.0 Beta 1 145
ciphers, hashing and digital signing. To the extent possible, ideas and approaches from existing
protocols for key management and secure multicast are also leveraged, although where appropriate
they have been adapted to the data-centric communications model of DDS and the DDS-RTPS wire
protocol.
9.2.5 Ease-of-Use while Supporting Common Application Requirements
It is anticipated that specialized applications may need to develop their own security plugins to either
integrate existing security infrastructure or meet specialized requirements. Therefore the primary
consumers of the builtin plugins will be users who want to secure their systems but not have complex
needs or significant legacy components. Under these conditions, ease-of-use is essential. A security
infrastructure that is too hard to configure or too complex to understand or maintain is less likely to be
used, or may be used wrongly, resulting in systems that are less secure overall.
The builtin plugins balance rich functionality and ease-of-use, providing for the most common use
cases, in a manner that is easy to understand and use correctly.
9.3 Builtin Authentication: DDS:Auth:PKI-RSA/DSA-DH
This builtin 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 trusted Certificate
Authority (CA). It performs mutual authentication between discovered participants using the
Digital Signature Algorithm (DSA) [11] and establishes a shared secret using Diffie-Hellman (D-H)
Key Agreement Method [12].
The CA could be an existing one. Or a new one could be created for the purpose of deploying
applications on a DDS Domain. The nature or manner in which the CA is selected is not important
because the way it is used enforces a shared recognition by all participating applications.
Prior to a DomainParticipant being enabled the DDS:Auth:PKI-RSA/DSA-DH plugin associated
with the DomainParticipant must be configured with three things:
1. The X.509 Certificate that defines the Shared CA. This certificate contains the 2048-
bit RSA Public Key of the CA.
2. The 2048-bit RSA Private Key of the DomainParticipant.
3. An X.509 Certificate that chains up to the Shared CA , that binds the 2048-bit RSA
Public Key of the DomainParticipant to the Distinguished Name (subject
name) for the DomainParticipant and any intermediate CA certificates required to build
the chain.
9.3.1 Configuration
The specific format of the root CA certificate, the private key of the DomainParticipant, and the
certificate for the DomainParticipant are not dictated by this specification. Implementations may
use standard formats for certificates and keys and configure them using an API, an extended QoS
Policy, or some other implementation-specific mechanism.
Leaving the details of the DDS:Auth:PKI-RSA/DSA-DH plugin configuration unspecified does not
affect interoperability and might be required to accommodate different security concerns and](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-155-320.jpg)
![172 DDS Security v1.0 Beta1
This Section is delimited by the XML element <domain_id>. The contents of this element shall be an
expression defining the set of DDS Domain Id values to which the allow rule applies. The expression
syntax and matching shall use the syntax and rules of the POSIX fnmatch() function as specified in
POSIX 1003.2-1992, Section B.6 [38].
For example:
<domain_id>0</domain_id>
9.4.1.3.2.3.1.2 Publish Section
This Section defines the Topic names that the rule allows to be published.
The publish Section shall be delimited by the <publish> XML Element.
The topic names appear in the Section delimited by the <topics> XML element. Topic names may be
given explicitly or by means of Topic name expressions. The Topic name expression syntax and
matching shall use the syntax and rules of the POSIX fnmatch() function as specified in POSIX
1003.2-1992, Section B.6 [38].
The publish Section may also include one or more sections delimited by the <partitions> XML
Element. The <partition> XML Elements contain the DDS Partition names where it is allowed to
publish the specified Topic names. Partition names may be given explicitly or by means of Partition
name expressions. The Partition name expression syntax and matching shall use the syntax and rules of
the POSIX fnmatch() function as specified in POSIX 1003.2-1992, Section B.6 [38]. If there is no
<partitions> Section then the rule allows publishing on any partition.
The publish Section may also include one or more sections delimited by the <data_tags> XML
Element. The <data_tags> XML Elements contain a set of tags that shall be associated with the
DataWriter that publishes the data on the Topic names allowed by the rule.
Example1:
<publish>
<topic>Circle1</topic>
</publish>
Example2:
<publish>
<topic>Square</topic>
<partition>A_partition</partition>
</publish>
Example3:
<publish>
<topic>Cir*</topic>
<data_tags>
<tag>
<name>aTagName1</name>
<value>aTagValue1</value>
</tag>
</data_tags>
</publish>
9.4.1.3.2.3.1.3 Subscribe Section](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-182-320.jpg)
![DDS Security v1.0 Beta 1 173
This Section defines the Topic names that the rule allows to be subscribed.
The publish Section shall be delimited by the <subscribe> XML Element.
The topic names appear in the Section delimited by the <topics> XML element. Topic names may be
given explicitly or by means of Topic name expressions. The Topic name expression syntax and
matching shall use the syntax and rules of the POSIX fnmatch() function as specified in POSIX
1003.2-1992, Section B.6 [38].
The subscribe Section may also include one or more sections delimited by the <partitions> XML
Element. The <partition> XML Elements contain the DDS Partition names where it is allowed to
subscribe to the specified Topic names. Partition names may be given explicitly or by means of
Partition name expressions. The Partition name expression syntax and matching shall use the syntax
and rules of the POSIX fnmatch() function as specified in POSIX 1003.2-1992, Section B.6 [38]. If
there is no <partitions> Section then the rule allows subscribing on any partition.
The subscribe Section may also include one or more sections delimited by the <data_tags> XML
Element. The <data_tags> XML Elements contain a set of tags that shall be associated with the
DataReader that subscribes the data on the Topic names allowed by the rule.
Example1:
<subscribe>
<topic>Circle1</topic>
</subscribe>
Example2:
<subscribe>
<topic>Square</topic>
<partition>A_partition</partition>
</subscribe>
Example3:
<subscribe>
<topic>Cir*</topic>
<data_tags>
<tag>
<name>aTagName1</name>
<value>aTagValue1</value>
</tag>
</data_tags>
</subscribe>
9.4.1.3.2.3.1.4 Example allow rule
<allow_rule>
<domain_id>0</domain_id>
<publish>
<topic>Cir*</topic>
<data_tags>
<tag>
<name>aTagName1</name>
<value>aTagValue1</value>
</tag>](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-183-320.jpg)
![180 DDS Security v1.0 Beta1
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.
9.5 Builtin Crypto: DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH
The builtin 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 Advanced
Encryption Standard (AES) in counter (CTR) mode. It supports two AES key sizes: 128 bits and 256
bits. It also provides hash-based message authentication (HMAC) services with two different hashing
functions: SHA256 and SHA1.
The approach followed is conceptually similar to that used for SRTP [20]. However it has been
enhanced to be able to support additional scenarios, such as the presence of services like a DDS
persistence service or a data relay service, which are present in DDS-RTPS systems and not supported
by SRTP.
The algorithm used for data confidentiality is AES in CTR mode. While AES is a block cipher, the use
of counter mode effectively turns it into a stream cipher. It generates key-stream blocks that are
XORed with the plaintext blocks to get the ciphertext. Since the XOR operation is symmetric the
decryption operation is exactly the same. It is called counter mode because the key-stream blocks are
generated encrypting successive values of a "counter" with the key. This mode of operation requires
the SessionKey to be kept secret, however the counter does not need to be protected and can be any
function that creates a sequence that does not repeat in a long time, in particular it can be a simple
incrementing integer.
Figure 35 – User of AES encryption in counter-mode](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-190-320.jpg)
![DDS Security v1.0 Beta 1 181
The use of counter mode allows decryption of blocks in arbitrary order. All that is needed to decrypt a
block are the SessionKey and the counter. This is very important for DDS because a DataReader
may not receive all the samples written by a matched DataWriter. The use of DDS
ContentFilteredTopics as well as DDS QoS policies such as History (with KEEP_LAST
kind), Reliability (with BEST_EFFORTS kind), Lifespan, and TimeBasedFilter, among
others, can result in a DataReader receiving 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-based
Message Authentication Code (HMAC). The plugin supports two hashing algorithms to use with
HMAC-SHA256 and HMAC-SHA1. HMAC is defined by IETF RFC 2014 [27]. HMAC keys must be
at least as long as the block size of the underlying hash algorithm. The MAC may be computed over
the entire RTPS message, which can include multiple submessages, encrypted using different AES
keys or may be over particular submessages.
9.5.1 Configuration
The configuration of the DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH plugin is not dictated by this
specification and therefore is implementation specific. Implementations may provide, for example, an
API, an extended QoS Policy, or some other mechanism. The requirement is that the different modes of
operation should all be supported and configurable.
9.5.2 DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH Types
The Cryptographic plugin defines a set of generic data types to be used to initialize the plugin and
to externalize the properties and material that must be shared with the applications that need to decode
the cipher material, verify signatures, etc.
Each plugin implementation defines the contents of these types in a manner appropriate for the
algorithms it uses. All “Handle” types are local opaque handles that are only understood by the local
plugin object that creates them. The remaining types shall be fully specified so that independent
implementations of DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH can interoperate.
9.5.2.1 DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH CryptoToken
The DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH plugin shall set the attributes of the
CryptoToken object as specified in the table below:
Table 41 – CryptoToken class for the builtin AccessControl plugin
Attribute name Attribute value
KeyMaterial_AES_CTR_HMAC
KxKey
binary_value1
KxMacKey](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-191-320.jpg)
![198 DDS Security v1.0 Beta1
10Plugin Language Bindings
10.1Introduction
Clause 8 defines the plugin interfaces in a programming-language independent manner using UML.
Using the terminology of the DDS specification this UML definition could be considered a Platform
Independent Model (PIM) for the plugin interfaces. The mapping to each specific programming
languages platform could therefore be considered a Platform Specific Model (PSM) for that
programming language.
The mapping of the plugin interfaces to specific programming languages is defined by first defining
the interfaces using OMG-IDL version 3.5 with the additional syntax defined in the DDS-XTYPES
specification and subsequently applying the IDL to language mapping to the target language.
IDL Types lacking the DDS-XTYPES @Entensibility annotation shall be interpreted as having
the extensibility kind EXTENSIBLE_EXTENSIBILITY. This matches the DDS-XTYPES
specification implied extensibility of un-annotated types.
For consistency with the DDS specification, the DDS security specification defines language bindings
to each of the language PSMs specified for DDS, namely:
C as derived from the IDL to C mapping
C++ classic, as derived from the IDL to C++ mapping
Java classic, as derived from the IDL to Java mapping
C++ modern, aligned with the DDS-STDC++ specification, this is derived from the IDL to C++11
mapping
Java modern with the DDS-JAVA5+ specification
10.2IDL representation of the plugin interfaces
For consistency in the resulting APIs, the mapping from the plugin interfaces defined in clause 8 and
the OMG IDL follows the same PIM to PSM mapping rules as the OMG DDS specification (see sub
clause 7.2.2 of the DDS specification version 1.2 [1]). A relevant subset of these rules is repeated here.
In this rules “PIM” refers to the UML description of the interfaces in clause 8 and PSM refers to the
OMG-IDL description of the interfaces that appears in the associated file: dds_security.idl
The PIM to PSM mapping maps the UML interfaces and classes into IDL interfaces. Plain data
types are mapped into structures.
‘Out’ parameters in the PIM are conventionally mapped to ‘inout’ parameters in the PSM in order
to minimize the memory allocation performed by the Service and allow for more efficient
implementations. The intended meaning is that the caller of such an operation should provide an
object to serve as a “container” and that the operation will then “fill in” the state of that objects
appropriately.
The resulting IDL representation of the plugin interfaces appears in the file dds_security.idl which
shall be considered part of the DDS Security specification.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-208-320.jpg)
![DDS Security v1.0 Beta 1 199
10.3C language representation of the plugin interfaces
The C language representation of the plugin interfaces shall be obtained applying the IDL to C
mapping [5] to the dds_security.idl file.
10.4C++ classic representation of the plugin interfaces
The C++ classic (without the use of the C++ standard library) language representation of the plugin
interfaces shall be obtained using the IDL2C++ mapping [7] to the dds_security.idl file.
10.5Java classic
The Java classic language representation of the plugin interfaces shall be obtained using the IDL2Java
mapping [6] to the dds_security.idl file.
10.6C++11 representation of the plugin interfaces
This representation is aligned with the DDS-STDC++ PSM.
The C++ classic language representation of the plugin interfaces shall be obtained using the
IDL2C++11 mapping [8] to the dds_security.idl file with the following exceptions:
1. The IDL module DDS shall be mapped to the C++ namespace dds so it matches the namespace
used by the DDS-STD-C++ PSM.
2. The mapping shall not use any C++11-only feature of the language or the library (e.g., move
constructors, noexcept, override, std::array).
3. Arrays shall map to the dds::core::array template defined in the DDS-STD-C++ PSM.
4. The enumerations shall map to the dds::core::safe_enum template defined in the DDS-STD-
C++ PSM.
5. The IDL DynamicData native type shall be mapped to the C++ type
dds::code::xtypes::DynamicData defined in the DDS-STDC++ PSM.
10.7Java modern aligned with the DDS-JAVA5+ PSM
The Java classic language representation of the plugin interfaces shall be obtained using the IDL2Java
mapping [6] to the dds_security.idl file with the following exceptions:
1. The IDL module DDS shall be mapped to the Java namespace org.omg.dds so it matches the
namespace used by the DDS-JAVA5+ PSM.
2. The IDL DynamicData native type shall be mapped to the type
org.omg.dds.type.dynamic.DynamicData defined in the DDS-JAVA5+ PSM.](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-209-320.jpg)
![200 DDS Security v1.0 Beta1
Annex A - References
[1] DDS: Data-Distribution Service for Real-Time Systems version 1,2.
http://www.omg.org/spec/DDS/1.2
[2] DDS-RTPS: Data-Distribution Service Interoperability Wire Protocol version 2.1,
http://www.omg.org/spec/DDS-RTPS/2.1/
[3] DDS-XTYPES: Extensible and Dynamic Topic-Types for DDS version 1.0
http://www.omg.org/spec/DDS-XTypes/1.0
[4] OMG-IDL: Interface Definition Language (IDL) version 3.5 http://www.omg.org/spec/IDL35/
[5] IDL2C: IDL to C Language Mapping, Version 1.0. http://www.omg.org/spec/C/1.0/
[6] IDL2Java: IDL To Java Language Mapping, Version 1.3 http://www.omg.org/spec/I2JAV/1.3/
[7] IDL2C++: IDL to C++ Language Mapping (CPP), Version 1.3
http://www.omg.org/spec/CPP/1.3/PDF
[8] IDL2C++11: IDL To C++11 Language Mapping http://www.omg.org/spec/CPP11/
[9] Transport Layer Security, http://en.wikipedia.org/wiki/Transport_Layer_Security
[10] IPSec, http://en.wikipedia.org/wiki/IPsec
[11] DSA, FIPS PUB 186-3 Digital Signature Standard (DSS).
http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf
[12] Diffie-Hellman (D-H) Key Agreement Method. IETF RFC 2631.
http://tools.ietf.org/html/rfc2631
[13] 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
[14] Erramilli, S.; Gadgil, S.; Natarajan, N., “Efficient assignment of multicast groups to publish-
subscribe information topics in tactical networks”, MILCOM 2008
[15] “RFC 2094 - Group Key Management Protocol (GKMP) Architecture”,
http://www.faqs.org/rfcs/rfc2094.html
[16] Raghav Bhaskar, Daniel Augot, Cedric Adjih, Paul Muhlethaler and Saadi Boudjit, “AGDH
(Asymmetric Group Diffie Hellman): An Efficient and Dynamic Group Key Agreement
Protocol for Ad hoc Networks”, Proceedings of New Technologies, Mobility and Security
(NTMS) conference, Paris, France, May 2007
[17] Qianhong Wu, Yi Mu, Willy Susilo, Bo Qin and Josep Domingo-Ferrer “Asymmetric Group
Key Agreement”, EUROCRYPT 2009
[18] “Secure IP Multicast”,
http://www.cisco.com/en/US/prod/collateral/iosswrel/ps6537/ps6552/prod_presentation0900ae
cd80473105.pdf
[19] 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
[20] M. Baugher, D. McGrew, M. Naslund, E. Carrara, K. Norrman, “The Secure Real-time
Transport Protocol (SRTP)” IETF RFC 3711, http://tools.ietf.org/html/rfc3711
[21] Baugher, M., Weis, B., Hardjono, T. and H. Harney, "The Group Domain of Interpretation,”
IETF RFC 3547, http://tools.ietf.org/html/rfc3547, July 2003.
[22] P. Zimmerman, A. Johnston, and J. Callas, “ZRTP: Media Path Key Agreement for Secure
RTP”, Internet-Draft, March 2009
[23] F. Andreason, M. Baugher, and D. Wing, “Session description protocol (SDP) security
description for media streams,” IETF RFC 4568, July 2006](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-210-320.jpg)
![DDS Security v1.0 Beta 1 201
[24] D. Ignjatic, L. Dondeti, F. Audet, P. Lin, “MIKEY-RSA-R: An Additional Mode of Key
Distribution in Multimedia Internet KEYing (MIKEY)”, RFC 4738, November 2006.
[25] 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.
[26] Bruce Schneier (August 2005). "SHA-1 Broken". Retrieved 2009-01-09. "
[27] H. Krawczyk, M. Bellare, and R.Canetti, “HMAC: Keyed-Hashing for Message
Authentication” IETF RFC 2104, http://tools.ietf.org/html/rfc2104
[28] Bellare, Mihir (June 2006). "New Proofs for NMAC and HMAC: Security without Collision-
Resistance". In Dwork, Cynthia. Advances in Cryptology – Crypto 2006 Proceedings. Lecture
Notes in Computer Science 4117. Springer-Verlag.
[29] 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
[30] 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_whit
e_paper0900aecd804c363f.html
[31] CiscoIOS Secure Multicast,
http://www.cisco.com/en/US/prod/collateral/iosswrel/ps6537/ps6552/prod_white_paper0900ae
cd8047191e.html
[32] A. Mason. IPSec Overview Part Two: Modes and Transforms.
http://www.ciscopress.com/articles/article.asp?p=25477
[33] 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 Network
and Distributed Systems Security Symposium, San Diego, CA, 2000
[34] T. Aurisch, and C. Karg, “Using the IPSec architecture for secure multicast communications,”
8th
International Command and Control Research and Technology Symposium (ICCRTS),
Washington D.C., 2003
[35] J. Zhang and C. Gunter. Application-aware secure multicast for power grid communications,
International Journal of Security and Networks, Vol 6, No 1, 2011
[36] List of reserved RTPS Vendor Ids. http://portals.omg.org/dds/content/page/dds-rtps-vendor-
and-product-ids
[37] PKCS #7: Cryptographic Message Syntax Version 1.5. IETF RFC 2315.
http://tools.ietf.org/html/rfc2315
[38] File expression matching syntax for fnmatch() ; POSIX fnmatch API (IEEE 1003.2-1992
Section B.6)](https://image.slidesharecdn.com/ddssecurityspecificationptc-14-06-01-140703023638-phpapp02/85/DDS-Security-Specification-Adopted-Beta1-June-2014-211-320.jpg)
DDS Security Specification (Adopted Beta1 June 2014)
- 1. Date: June 2014 DDS Security FTF Beta 1 OMG Document Number: ptc/2014-06-01 Standard document URL: http://www.omg.org/spec/DDS-SECURITY Machine Consumable Files: Normative: http://www.omg.org/spec/DDS-SECURITY/20140301/dds_security_plugins.idl http://www.omg.org/spec/DDS-SECURITY/20140301/dds_security_governance.xsd http://www.omg.org/spec/DDS-SECURITY/20140301/dds_security_permissions.xsd http://www.omg.org/spec/DDS-SECURITY/20140301/dds_security_plugins_model.xmi Non-normative: http://www.omg.org/spec/DDS-SECURITY/20140301/dds_security_governance_example.xml http://www.omg.org/spec/DDS-SECURITY/20140301/dds_security_permissions_example.xml http://www.omg.org/spec/DDS-SECURITY/20140301/dds_security_plugins_model.eap This OMG document replaces the submission document (mars/14-02-03, Alpha). It is an OMG Adopted Beta Specification and is currently in the finalization phase. Comments on the content of this document are welcome, and should be directed to issues@omg.org by October 15, 2014. You may view pending issues for this specification from the OMG revision issues web page http://www.omg.org/issues. The FTF Recommendation and Report for this specification will be published on April 3, 2015. If you are reading this after that date, please download the available specification from the OMG Specifications web page http://www.omg.org/spec/. u
- 2. Copyright © 2014, Object Management Group, Inc. (OMG) Copyright © 2014, PrismTech. Copyright © 2014, Real-Time Innovations, Inc. (RTI) USE OF SPECIFICATION - TERMS, CONDITIONS & NOTICES The material in this document details an Object Management Group specification in accordance with the terms, conditions and notices set forth below. This document does not represent a commitment to implement any portion of this specification in any company's products. The information contained in this document is subject to change without notice. LICENSES The companies listed above have granted to the Object Management Group, Inc. (OMG) a nonexclusive, royalty-free, paid up, worldwide license to copy and distribute this document and to modify this document and distribute copies of the modified version. Each of the copyright holders listed above has agreed that no person shall be deemed to have infringed the copyright in the included material of any such copyright holder by reason of having used the specification set forth 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 specification hereby 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 and special purpose specifications that are based upon this specification, and to use, copy, and distribute this specification as provided under the Copyright Act; provided that: (1) both the copyright notice identified above and this permission notice appear on any copies of this specification; (2) the use of the specifications is for informational purposes and will not be copied or posted on any network computer or broadcast in any media and will not be otherwise resold or transferred for commercial purposes; and (3) no modifications are made to this specification. This limited permission automatically terminates without notice if you breach any of these terms or conditions. Upon termination, you will destroy immediately any copies of the specifications in your possession or control. PATENTS The attention of adopters is directed to the possibility that compliance with or adoption of OMG specifications may require use of an invention covered by patent rights. OMG shall not be responsible for identifying patents for which a license may be required by any OMG specification, or for conducting legal inquiries into the legal validity or scope of those patents that are brought to its attention. OMG specifications are prospective and advisory only. Prospective users are responsible for protecting themselves against liability for infringement of patents. GENERAL USE RESTRICTIONS Any unauthorized use of this specification may violate copyright laws, trademark laws, and communications regulations and statutes. This document contains information which is protected by copyright. All Rights Reserved. No part of this work covered by copyright herein may be reproduced or used in any form or by any means--graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems--without permission of the copyright owner. DISCLAIMER OF WARRANTY WHILE THIS PUBLICATION IS BELIEVED TO BE ACCURATE, IT IS PROVIDED "AS IS" AND MAY CONTAIN ERRORS OR MISPRINTS. THE OBJECT MANAGEMENT GROUP AND THE COMPANIES LISTED ABOVE MAKE NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS PUBLICATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF TITLE OR OWNERSHIP, IMPLIED WARRANTY OF MERCHANTABILITY OR WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE OR USE. IN NO EVENT SHALL THE OBJECT MANAGEMENT GROUP OR ANY OF THE COMPANIES LISTED ABOVE BE LIABLE FOR ERRORS CONTAINED HEREIN OR FOR DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, RELIANCE OR COVER DAMAGES, INCLUDING LOSS OF PROFITS, REVENUE, DATA OR USE, INCURRED BY ANY USER OR ANY THIRD PARTY IN CONNECTION WITH THE FURNISHING,
- 3. PERFORMANCE, OR USE OF THIS MATERIAL, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. The entire risk as to the quality and performance of software developed using this specification is borne by you. This disclaimer of warranty constitutes an essential part of the license granted to you to use this specification. RESTRICTED RIGHTS LEGEND Use, duplication or disclosure by the U.S. Government is subject to the restrictions set forth in subparagraph (c) (1) (ii) of The Rights in Technical Data and Computer Software Clause at DFARS 252.227-7013 or in subparagraph (c)(1) and (2) of the Commercial Computer Software - Restricted Rights clauses at 48 C.F.R. 52.227-19 or as specified in 48 C.F.R. 227- 7202-2 of the DoD F.A.R. Supplement and its successors, or as specified in 48 C.F.R. 12.212 of the Federal Acquisition Regulations and its successors, as applicable. The specification copyright owners are as indicated above and may be contacted through the Object Management Group, 109 Highland Avenue, Needham, MA 02494, U.S.A. TRADEMARKS IMM®, MDA®, Model Driven Architecture®, UML®, UML Cube logo®, OMG Logo®, CORBA® and XMI® are registered trademarks of the Object Management Group, Inc., and Object Management Group™, OMG™ , Unified Modeling Language™, Model Driven Architecture Logo™, Model Driven Architecture Diagram™, CORBA logos™, XMI Logo™, CWM™, CWM Logo™, IIOP™, MOF™, OMG Interface Definition Language (IDL)™, and OMG SysML™ are trademarks of the Object Management Group. All other products or company names mentioned are used for identification purposes only, and may be trademarks of their respective owners. COMPLIANCE The copyright holders listed above acknowledge that the Object Management Group (acting itself or through its designees) is and shall at all times be the sole entity that may authorize developers, suppliers and sellers of computer software to use certification marks, trademarks or other special designations to indicate compliance with these materials. Software developed under the terms of this license may claim compliance or conformance with this specification if and only if the software compliance is of a nature fully matching the applicable compliance points as stated in the specification. Software developed only partially matching the applicable compliance points may claim only that the software was based on this specification, but may not claim compliance or conformance with this specification. In the event that testing suites are implemented or approved by Object Management Group, Inc., software developed using this specification may claim compliance or conformance with the specification only if the software satisfactorily completes the testing suites.
- 4. OMG’s Issue Reporting Procedure All OMG specifications are subject to continuous review and improvement. As part of this process we encourage readers to report any ambiguities, inconsistencies, or inaccuracies they may find by completing the Issue Reporting Form listed on the main web page http://www.omg.org, under Documents, Report a Bug/Issue (http://www.omg.org/report_issue.htm).
- 5. DDS Security v1.0 Beta 1 i Table of Contents Preface..............................................................................................................................................v 1 Scope.........................................................................................................................................1 1.1 General .........................................................................................................................................1 1.2 Overview of this Specification........................................................................................................1 2 Conformance.............................................................................................................................2 2.1 Changes to Adopted OMG Specifications .......................................................................................2 2.2 Conformance points ......................................................................................................................2 2.2.1 Builtin plugin interoperability (mandatory)....................................................................................... 3 2.2.2 Plugin framework (mandatory): ........................................................................................................ 3 2.2.3 Plugin Language APIs (optional):....................................................................................................... 3 2.2.4 Logging and Tagging profile (optional):............................................................................................. 4 3 Normative References ...............................................................................................................4 4 Terms and Definitions................................................................................................................4 5 Symbols.....................................................................................................................................6 6 Additional Information..............................................................................................................7 6.1 Acknowledgments.........................................................................................................................7 7 Support for DDS Security...........................................................................................................8 7.1 Security Model ..............................................................................................................................8 7.1.1 Threats............................................................................................................................................... 8 7.2 Types used by DDS Security ......................................................................................................... 11 7.2.1 Property........................................................................................................................................... 12 7.2.2 BinaryProperty................................................................................................................................. 12 7.2.3 DataHolder ...................................................................................................................................... 13 7.2.4 Credential ........................................................................................................................................ 14 7.2.5 Token ............................................................................................................................................... 16 7.2.6 ParticipantGenericMessage............................................................................................................. 17 7.2.7 Additional DDS Return Code: NOT_ALLOWED_BY_SEC................................................................... 18 7.3 Securing DDS Messages on the Wire............................................................................................ 18
- 6. ii DDS Security v1.0 Beta 1 7.3.1 RTPS Background (Non Normative) ................................................................................................ 18 7.3.2 Secure RTPS Messages..................................................................................................................... 20 7.3.3 Constraints of the DomainParticipant BuiltinTopicKey_t (GUID) .................................................... 21 7.3.4 Mandatory use of the KeyHash for encrypted messages................................................................ 21 7.3.5 Immutability of Publisher Partition Qos in combination with non volatile Durability kind............ 22 7.3.6 Platform Independent Description.................................................................................................. 22 7.3.7 Mapping to UDP/IP PSM.................................................................................................................. 25 7.4 DDS Support for Security Plugin Information Exchange................................................................ 28 7.4.1 Secure builtin Discovery Topics ....................................................................................................... 28 7.4.2 New ParticipantMessageSecure builtin Topic ................................................................................. 32 7.4.3 New ParticipantStatelessMessage builtin Topic .............................................................................. 33 7.4.4 New ParticipantVolatileMessageSecure builtin Topic ..................................................................... 35 7.4.5 Definition of the “Builtin Secure Endpoints”................................................................................... 39 8 Plugin Architecture..................................................................................................................40 8.1 Introduction ................................................................................................................................ 40 8.2 Common Types............................................................................................................................ 41 8.2.1 Security Exception ........................................................................................................................... 41 8.3 Authentication Plugin.................................................................................................................. 42 8.3.1 Background (Non Normative) ......................................................................................................... 42 8.3.2 Authentication Plugin Model........................................................................................................... 42 8.4 Access Control Plugin................................................................................................................... 60 8.4.1 Background (Non Normative) ......................................................................................................... 60 8.4.2 AccessControl Plugin Model............................................................................................................ 60 8.5 Cryptographic Plugin ................................................................................................................... 80 8.5.1 Cryptographic Plugin Model............................................................................................................ 80 8.6 The Logging Plugin..................................................................................................................... 110 8.6.1 Background (Non Normative) ....................................................................................................... 110 8.6.2 Logging Plugin Model .................................................................................................................... 110 8.7 Data Tagging.............................................................................................................................. 113 8.7.1 Background (Non Normative) ....................................................................................................... 113 8.7.2 DataTagging Model........................................................................................................................ 113 8.7.3 DataTagging Types ......................................................................................................................... 113
- 7. DDS Security v1.0 Beta 1 iii 8.8 Security Plugins Behavior .......................................................................................................... 114 8.8.1 Authentication and AccessControl behavior with local DomainParticipant.................................. 114 8.8.2 Authentication behavior with discovered DomainParticipant ...................................................... 116 8.8.3 AccessControl behavior with local domain entity creation........................................................... 119 8.8.4 AccessControl behavior with remote participant discovery.......................................................... 121 8.8.5 AccessControl behavior with remote domain entity discovery..................................................... 123 8.8.6 Cryptographic Plugin key generation behavior ............................................................................. 126 8.8.7 Cryptographic Plugin key exchange behavior................................................................................ 128 8.8.8 Cryptographic Plugins encoding/decoding behavior .................................................................... 133 9 Builtin Plugins .......................................................................................................................142 9.1 Introduction .............................................................................................................................. 142 9.2 Requirements and Priorities (Non Normative)........................................................................... 142 9.2.1 Performance and Scalability.......................................................................................................... 143 9.2.2 Robustness and Availability........................................................................................................... 144 9.2.3 Fitness to the DDS Data Centric Model......................................................................................... 144 9.2.4 Leverage and Reuse of Existing Security Infrastructure and Technologies.................................... 144 9.2.5 Ease of Use while Supporting Common Application Requirements............................................. 145 9.3 Builtin Authentication: DDS:Auth:PKI RSA/DSA DH ................................................................... 145 9.3.1 Configuration................................................................................................................................. 145 9.3.2 DDS:Auth:PKI RSA/DSA DH Types ................................................................................................. 146 9.3.3 DDS:Auth:PKI RSA/DSA DH plugin behavior ................................................................................. 149 9.3.4 DDS:Auth:PKI RSA/DSA DH plugin authentication protocol ......................................................... 155 9.4 Builtin Access Control: DDS:Access:PKI Signed XML Permissions ............................................... 157 9.4.1 Configuration................................................................................................................................. 158 9.4.2 DDS:Access:PKI Signed XML Permissions Types ........................................................................... 176 9.4.3 DDS:Access:PKI Signed XML Permissions plugin behavior ........................................................... 177 9.5 Builtin Crypto: DDS:Crypto:AES CTR HMAC RSA/DSA DH .......................................................... 180 9.5.1 Configuration................................................................................................................................. 181 9.5.2 DDS:Crypto:AES CTR HMAC RSA/DSA DH Types........................................................................... 181 9.5.3 DDS:Crypto:AES CTR HMAC RSA/DSA DH plugin behavior........................................................... 184 9.6 Builtin Logging Plugin ................................................................................................................ 195 9.6.1 DDS:Logging:DDS_LogTopic plugin behavior................................................................................. 196
- 8. iv DDS Security v1.0 Beta 1 10 Plugin Language Bindings...................................................................................................198 10.1 Introduction .............................................................................................................................. 198 10.2 IDL representation of the plugin interfaces ................................................................................ 198 10.3 C language representation of the plugin interfaces .................................................................... 199 10.4 C++ classic representation of the plugin interfaces..................................................................... 199 10.5 Java classic ................................................................................................................................ 199 10.6 C++11 representation of the plugin interfaces............................................................................ 199 10.7 Java modern aligned with the DDS JAVA5+ PSM ........................................................................ 199 Annex A References ....................................................................................................................200
- 9. DDS Security v1.0 Beta 1 v Preface About the Object Management Group OMG Founded in 1989, the Object Management Group, Inc. (OMG) is an open membership, not-for-profit computer industry standards consortium that produces and maintains computer industry specifications for interoperable, portable and reusable enterprise applications in distributed, heterogeneous environments. Membership includes Information Technology vendors, end users, government agencies and academia. OMG member companies write, adopt, and maintain its specifications following a mature, open process. OMG's specifications implement the Model Driven Architecture® (MDA®), maximizing ROI through a full-lifecycle approach to enterprise integration that covers multiple operating systems, programming languages, middleware and networking infrastructures, and software development environments. OMG’s specifications include: UML® (Unified Modeling Language™); CORBA® (Common Object Request Broker Architecture); CWM™ (Common Warehouse Metamodel); and industry-specific standards for dozens of vertical markets. More information on the OMG is available at http://www.omg.org/. OMG Specifications As noted, OMG specifications address middleware, modeling, and vertical domain frameworks. A listing of all OMG Specifications is available from the OMG website at: http://www.omg.org/spec/index.htm Specifications are organized by the following categories: Business Modeling Specifications Middleware Specifications • CORBA/IIOP • Data Distribution Services • Specialized CORBA IDL/Language Mapping Specifications Modeling and Metadata Specifications • UML, MOF, CWM, XMI • UML Profile
- 10. vi DDS Security v1.0 Beta 1 Modernization Specifications Platform Independent Model (PIM), Platform Specific Model (PSM), Interface Specifications • CORBAServices • CORBAFacilities OMG Domain Specifications CORBA Embedded Intelligence Specifications CORBA Security Specifications All of OMG’s formal specifications may be downloaded without charge from our website. (Products implementing OMG specifications are available from individual suppliers.) Copies of specifications, available in PostScript and PDF format, may be obtained from the Specifications Catalog cited above or by contacting the Object Management Group, Inc. at: OMG Headquarters 109 Highland Avenue Needham, MA 02494 USA Tel: +1-781-444-0404 Fax: +1-781-444-0320 Email: pubs@omg.org Certain OMG specifications are also available as ISO standards. Please consult http://www.iso.org. Issues The reader is encouraged to report any technical or editing issues/problems with this specification to http://www.omg.org/report_issue.htm.
- 11. DDS Security v1.0 Beta 1 1 1 Scope 1.1 General This submission adds several new “DDS Security Support” compliance points (“profile”) to the DDS Specification. See the compliance levels within the Conformance Clause below. 1.2 Overview of this Specification This specification defines the Security Model and Service Plugin Interface (SPI) architecture for compliant DDS implementations. The DDS Security Model is enforced by the invocation of these SPIs by the DDS implementation. This specification also defines a set of builtin implementations of these SPIs. The specified builtin SPI implementations enable out-of-the box security and interoperability 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 customization of Authentication, Access Control, Encryption, Message Authentication, Digital Signing, Logging and Data Tagging. Figure 1 – Overall architecture for DDS Security This specification defines five SPIs that when combined together provide Information Assurance to DDS systems:
- 12. 2 DDS Security v1.0 Beta1 Authentication Service Plugin. Provides the means to verify the identity of the application and/or user that invokes operations on DDS. Includes facilities to perform mutual authentication between participants and establish a shared secret. AccessControl Service Plugin. 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 to, etc. Cryptographic Service Plugin. Implements (or interfaces with libraries that implement) all cryptographic operations including encryption, decryption, hashing, digital signatures, etc. This includes the means to derive keys from a shared secret. Logging Service Plugin. Supports auditing of all DDS security-relevant events Data Tagging Service Plugin. Provides a way to add tags to data samples. 2 Conformance 2.1 Changes to Adopted OMG Specifications This specification does not modify any existing adopted OMG specifications. It reuses and/or adds functionality on top of the current set of OMG specifications. DDS: This specification does not modify or invalidate any existing DDS profiles or compliance levels. It extends some of the DDS builtin Topics to carry additional information in a compatible way with existing implementations of DDS. DDS-RTPS: This specification does not require any modifications to RTPS; however, it may impact interoperability with existing DDS-RTPS implementations. In particular, DDS-RTPS implementations that do not implement the DDS Security specification will have limited interoperability with implementations that do implement the mechanisms introduced by this specification. Interoperability is limited to systems configured to allow “unauthorized” DomainParticipant entities and within those systems, only to Topics configured to be “unprotected.” DDS-XTYPES: This specification depends on the IDL syntax introduced by and the Extended CDR encoding defined in the DDS-XTYPES specification. It does not require any modifications of DDS-XTYPES. OMG IDL: This specification does not modify any existing IDL-related compliance levels. 2.2 Conformance points This specification defines the following conformance points: (1) Builtin plugin interoperability (mandatory) (2) Plugin framework (mandatory) (3) Plugin language APIs (optional) (4) Logging and Tagging (optional) Conformance with the “DDS Security” specification requires conformance with all the mandatory conformance points.
- 13. DDS Security v1.0 Beta 1 3 2.2.1 Builtin plugin interoperability (mandatory) This point provides interoperability with all the builtin plugins with the exception of the Logging plugin. Conformance to this point requires conformance to: Clause 7 (the security model and the support for interoperability between DDS Security implementations). The configuration of the plugins and the observable wire-protocol behavior specified in Clause 9, (the builtin-plugins) except for sub clause 9.6. This conformance point does not require implementation of the APIs between the DDS implementation and the plugins. 2.2.2 Plugin framework (mandatory): This point provides the architectural framework and abstract APIs needed to develop new security plugins and “plug them” into a DDS middeware implementation. Plugins developed using this framework are portable between conforming DDS implementations. However portability for a specific programming language also requires conformance to the specific language API (see 2.2.3). Conformance to this point requires conformance to: Clause 7 (the security model and the support for interoperability between DDS Security implementations). Clause 8 (the plugin model) with the exception of 8.6 and 8.7 (Logging and Data Tagging plugins). The conformance to the plugin model is at the UML level; it does not mandate a particular language mapping. Clause 9, the builtin-plugins, except for 9.6 (Builtin Logging Plugin). In addition it requires the conforming DDS implementation to provide a public API to insert the plugins that conform to the aforementioned sections. 2.2.3 Plugin Language APIs (optional): These conformance points provide portability across compliant DDS implementations of the security plugins developed using a specific programming language. Conformance to any of the language portability points requires conformance to the (mandatory) plugin architecture framework point. These are 5 “plugin language API” points, each corresponding to a different programming language used to implement the plugins. Each language point is a separate independent conformance point. Conformance with the “plugin language API” point requires conformance with at least one of the 5 language APIs enumerated below: C Plugin APIs. Conformance to sub clauses 10.2 and 10.3 C++ classic Plugin APIs. Conformance to sub clauses 10.2 and 10.4 Java classic Plugin APIs. Conformance to sub clauses 10.2 and 10.5 C++11 Plugin APIs. Conformance to sub clauses 10.2 and 10.6 Java5+ Plugin APIs. Conformance to sub clauses 10.2 and 10.7.
- 14. 4 DDS Security v1.0 Beta1 2.2.4 Logging and Tagging profile (optional): This point adds support for logging and tagging. Conformance to this point requires conformance to sub clauses 8.6, 8.7, and 9.6. 3 Normative References DDS: Data-Distribution Service for Real-Time Systems version 1,2. http://www.omg.org/spec/DDS/1.2 DDS-RTPS: Data-Distribution Service Interoperability Wire Protocol version 2.1, http://www.omg.org/spec/DDS-RTPS/2.1/ DDS-XTYPES: Extensible and Dynamic Topic-Types for DDS version 1.0 http://www.omg.org/spec/DDS-XTypes/1.0/ OMG-IDL: Interface Definition Language (IDL) version 3.5 http://www.omg.org/spec/IDL35/ HMAC: Keyed-Hashing for Message Authentication. H. Krawczyk, M. Bellare, and R.Canetti, IETF RFC 2104, http://tools.ietf.org/html/rfc2104 PKCS #7: Cryptographic Message Syntax Version 1.5. IETF RFC 2315. http://tools.ietf.org/html/rfc2315 4 Terms and Definitions For the purposes of this specification, the following terms and definitions apply: Access Control Mechanism that enables an authority to control access to areas and resources in a given physical facility or computer-based information system. Authentication Security measure(s) designed to establish the identity of a transmission, message, or originator. Authorization Access privileges that are granted to an entity; conveying an “official” sanction to perform a security function or activity. Ciphertext Data in its encrypted or signed form. Certification authority The entity in a Public Key Infrastructure (PKI) that is responsible for issuing certificates, and exacting compliance to a PKI policy. Confidentiality Assurance that information is not disclosed to unauthorized individuals, processes, or devices.
- 15. DDS Security v1.0 Beta 1 5 Cryptographic algorithm A well-defined computational procedure that takes variable inputs, including a cryptographic key and produces an output. Cryptographic key A parameter used in conjunction with a cryptographic algorithm that operates in such a way that another agent with knowledge of the key can reproduce or reverse the operation, while an agent without knowledge of the key cannot. Examples include: 1. The transformation of plaintext data into ciphertext 2. The transformation of ciphertext data into plaintext 3. The computation of a digital signature from data 4. The verification of a digital signature 5. The computation of a message authentication code from data 6. The verification of a message authentication code from data and a received authentication code Data-Centric Publish-Subscribe (DCPS) The mandatory portion of the DDS specification used to provide the functionality required for an application to publish and subscribe to the values of data objects. Data Distribution Service (DDS) An OMG distributed data communications specification that allows Quality of Service policies to be specified for data timeliness and reliability. It is independent of the implementation language. Digital signature The result of a cryptographic transformation of data that, when properly implemented with supporting infrastructure and policy, provides the services of: 1. origin authentication 2. data integrity 3. signer non-repudiation Extended IDL Extended Interface Definition Language (IDL) used to describe data types in a way that can be represented in a machine neutral format for network communications. This syntax was introduced as part of the DDS-XTYPES specification [3]. Hashing algorithm A one-way algorithm that maps an input byte buffer of arbitrary length to an output fixed-length byte array in such a way that: (a) Given the output it is computationally infeasible to determine the input. (b) It is computationally infeasible to find any two distinct inputs that map to the same output.
- 16. 6 DDS Security v1.0 Beta1 Information Assurance The practice of managing risks related to the use, processing, storage, and transmission of information or data and the systems and processes used for those purposes. Integrity Protection against unauthorized modification or destruction of information. Key management The handling of cryptographic material (e.g., keys, Initialization Vectors) during their entire life cycle of the keys from creation to destruction. Message authentication code (MAC) A cryptographic hashing algorithm on data that uses a symmetric key to detect both accidental and intentional modifications of data. Non-Repudiation Assurance that the sender of data is provided with proof of delivery and the recipient is provided with proof of the sender's identity, so neither can later deny having received or processed the data. Public key A cryptographic key used with a public key cryptographic algorithm that is uniquely associated with an entity and that may be made public. The public key is associated with a private key. The public key may be known by anyone and, depending on the algorithm, may be used to: 1. Verify a digital signature that is signed by the corresponding private key, 2. Encrypt data that can be decrypted by the corresponding private key, or 3. Compute a piece of shared data. Public key certificate A set of data that uniquely identifies an entity, contains the entity's public key and possibly other information, and is digitally signed by a trusted party, thereby binding the public key to the entity. Public key cryptographic algorithm A cryptographic algorithm that uses two related keys, a public key and a private key. The two keys have the property that determining the private key from the public key is computationally infeasible. Public Key Infrastructure A framework that is established to issue, maintain and revoke public key certificates. 5 Symbols This specification does not define any symbols or abbreviations.
- 17. DDS Security v1.0 Beta 1 7 6 Additional Information 6.1 Acknowledgments The following individials and companies submitted content that was incorporated into this specification: Submitting contributors: (lead) Gerardo Pardo-Castellote, Ph.D., Real-Time Innovations. gerardo.pardo AT rti.com Jaime Martin-Losa, eProsima JaimeMartin AT eprosima.com Angelo Corsaro, Ph.D., PrismTech. angelo.corsaro AT prismtech.com Supporting contributors: Char Wales, MITRE charwing AT mitre.org Clark Tucker, Twin Oaks Computing, Inc. ctucker AT twinoakscomputing.com
- 18. 8 DDS Security v1.0 Beta1 7 Support for DDS Security 7.1 Security Model The Security Model for DDS defines the security principals (users of the system), the objects that are being secured, and the operations on the objects that are to be restricted. DDS applications share information on DDS Global Data Spaces (called DDS Domains) where the information is organized into Topics and accessed by means of read and write operations on data-instances of those Topics. Ultimately what is being secured is a specific DDS Global Data Space (domain) and, within the domain, the ability to access (read or write) information (specific Topic or even data-object instances within the Topic) in the DDS Global Data Space. Securing DDS means providing: Confidentiality of the data samples Integrity of the data samples and the messages that contain them Authentication of DDS writers and readers Authorization of DDS writers and readers Non-repudiation of data To provide secure access to the DDS Global Data Space, applications that use DDS must first be authenticated, so that the identity of the application (and potentially the user that interacts with it) can be established. Once authentication has been obtained, the next step is to enforce access control decisions that determine whether the application is allowed to perform specific actions. Examples of actions are: joining a DDS Domain, defining a new Topic, reading or writing a specific DDS Topic, and even reading or writing specific Topic instances (as identified by the values of key fields in the data). Enforcement of access control shall be supported by cryptographic techniques so that information confidentiality and integrity can be maintained, which in turn requires an infrastructure to manage and distribute the necessary cryptographic keys. 7.1.1 Threats In order to understand the decisions made in the design of the plugins, it is important to understand some of the specific threats impacting applications that use DDS and DDS Interoperability Wire Protocol (RTPS). Most relevant are four categories of threats: 1. Unauthorized subscription 2. Unauthorized publication 3. Tampering and replay 4. Unauthorized access to data
- 19. DDS Security v1.0 Beta 1 9 These threats are described in the context of a hypothetical communication scenario with six actors all attached to the same network: Alice. A DDS DomainParticipant who is authorized to publish data on a Topic T. Bob. A DDS DomainParticipant who is authorized to subscribe to data on a Topic T. Eve. An eavesdropper. Someone who is not authorized to subscribe to data on Topic T. However Eve uses the fact that she is connected to the same network to try to see the data. Trudy. An intruder. A DomainParticipant who is not authorized to publish on Topic T. However, Trudy uses the fact that she 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 she is not authorized to publish on Topic T. However, Mallory will try to use information 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 who needs to receive and send information on Topic T. For example, Trent can be a persistence service or a relay service. He is trusted to relay information without having malicious intent. However he is not trusted to see the content of the information. Figure 2 – Threat actors 7.1.1.1 Unauthorized Subscription The DomainParticipant Eve is connected to the same network infrastructure as the rest of the agents and is able to observe the network packets despite the fact that the messages are not intended to be sent to Eve. Many scenarios can lead to this situation. Eve could tap into a network switch or observe the communication channels. Alternatively, in situations where Alice and Bob are communicating over multicast, Eve could simply subscribe to the same multicast address. Protecting against Eve is reasonably simple. All that is required is for Alice to encrypt the data she writes using a secret key that is only shared with authorized receivers such as Bob, Trent, and Mallory.
- 20. 10 DDS Security v1.0 Beta1 7.1.1.2 Unauthorized Publication The DomainParticipant Trudy is connected to the same network infrastructure as the rest of the agents and is able to inject network packets with any data contents, headers and destination she wishes (e.g., Bob). The network infrastructure will route those packets to the indicated destination. To protect against Trudy, Bob, Trent and Mallory need to realize that the data is not originating from Alice. They need to realize that the data is coming from someone not authorized to send data on Topic T and therefore reject (i.e., not process) the packet. Protecting against Trudy is also reasonably simple. All that is required is for the protocol to require that the messages include either a hash-based message authentication code (HMAC) or digital signature. 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 can recognize messages that originate from Alice. Since Trudy is not authorized to publish Topic T, Bob and the others will not recognize any HMACs Trudy produces (i.e., they will not recognize Trudy’s key). A digital signature is based on public key cryptography. To create a sigital signature, Alice encrypts a digest of the message using Alice’s private key. Everybody (including Bob, Mallory and Trent) has access to Alice’s public key. Similar to the HMAC above, the recipients can identify messages from Alice, as they are the only ones whose digital signature can be interpreted with Alice’s public key. Any digital signatures Trudy may use will be rejected by the recipients, as Trudy is not authorized to write Topic T. The use of HMACs versus digital signatures presents tradeoffs that will be discussed further in subsequent sections. Suffice it to say that in many situations the use of HMACs is preferred because the performance to compute and verify them is about 1000 times faster than the performance of computing/verifying digital signatures. 7.1.1.3 Tampering and Replay Mallory is authorized to subscribe to Topic T. Therefore Alice has shared with Mallory the secret key to encrypt the topic and also, if an HMAC is used, the secret key used for the HMAC. Assume Alice used HMACs instead of digital signatures. Then Mallory can use her knowledge of the secret keys used for data encryption and the HMACs to create a message on the network and pretend it came from Alice. Mallory can fake all the TCP/UDP/IP headers and any necessary RTPS identifiers (e.g., Alice’s RTPS DomainParticipant and DataWriter GUIDs). Mallory has the secret key that was used to encrypt the data so she can create encrypted data payloads with any contents she wants. She has the secret key used to compute HMACs so she can also create a valid HMAC for the new message. Bob and the others will have no way to see that message came from Mallory and will accept it, thinking it came from Alice. So if Alice used an HMAC, the only solution to the problem is that the secret key used for the HMAC when sending the message to Mallory cannot be the same as the key used for the HMAC when sending messages to Bob. In other words, Alice must share a different secret key for the HMAC with each recipient. Then Mallory will not have the HMAC key that Bob expects from Alice and the messages from Mallory to Bob will not be misinterpreted as coming from Alice. Recall that Alice needs to be able to use multicast to communicate efficiently with multiple receivers. Therefore, if Alice wants to send an HMAC with a different key for every receiver, the only solution is
- 21. DDS Security v1.0 Beta 1 11 to append multiple HMACs to the multicast message with some key-id that allows the recipient to select the correct HMAC to verify. If Alice uses digital signatures to protect the integrity of the message, then this ‘masquerading’ problem does not arise and Alice can send the same digital signature to all recipients. This makes using multicast simpler. However, the performance penalty of using digital signatures is so high that in many situations it will be better to compute and send multiple HMACs as described earlier. 7.1.1.4 Unauthorized Access to Data by Infrastructure Services Infrastructure services, such as the DDS Persistence Service or relay services need to be able to receive messages, verify their integrity, store them, and send them to other participants on behalf of the original application. These services can be trusted not to be malicious; however, often it is not desirable to grant them the privileges they would need to understand the contents of the data. They are allowed to store and forward the data, but not to see inside the data. Trent is an example of such a service. To support deployment of these types of services, the security model needs to support the concept of having a participant, such as Trent, who is allowed to receive, process, and relay RTPS messages, but is not allowed to see the contents of the data within the message. In other words, he can see the headers and sample information (writer GUID, sequence numbers, keyhash and such) but not the message contents. To support services like Trent, Alice needs to accept Trent as a valid destination for her messages on topic T and share with Trent only the secret key used to compute the HMAC for Trent, but not the secret key used to encrypt the data itself. In addition, Bob, Mallory and others need to accept Trent as someone who is able to write on Topic T and relay messages from Alice. This means two things: (1) accept and interpret messages encrypted with Alice’s secret key and (2) allow Trent to include in his sample information, the information he got from Alice (writer GUID, sequence number and anything else needed to properly process the relayed message). Assume Alice used an HMAC in the message sent to Trent. Trent will have received from Alice the secret key needed to verify the HMAC properly. Trent will be able to store the messages, but lacking the secret key used for its encryption, will be unable to see the data. When he relays the message to Bob, he will include the information that indicates the message originated from Alice and produce an HMAC with its own secret HMAC key that was shared with Bob. Bob will receive the message, verify the HMAC and see it is a relayed message from Alice. Bob recognizes Trent is authorized to relay messages, so Bob will accept the sample information that relates to Alice and process the message as if it had originated with Alice. In particular, he will use Alice’s secret key to decrypt the data. If Alice had used digital signatures, Trent would have two choices. If the digital signature only covered the data and the sample information he needs to relay from Alice, Trent could simply relay the digital signature as well. Otherwise, Trent could strip out the digital signature and put in his own HMAC. Similar to before, Bob recognizes that Trent is allowed to relay messages from Alice and will be able to properly verify and process the message. 7.2 Types used by DDS Security The DDS security specification includes extensions to the DDS Interoperability Wire Protocol (DDS- RTPS), as well as, new API-level functions in the form of Security Plugins. The types described in sub clause 7.2 are used in these extensions.
- 22. 12 DDS Security v1.0 Beta1 7.2.1 Property Property is a data type that holds a pair of strings. One string is considered the property “name” and the other is the property “value” associated with that name. Property sequences are used as a generic data type to configure the security plugins, pass metadata and provide an extensible mechanism for vendors to configure the behavior of their plugins without breaking portability or interoperability. Property objects with names that start with the prefix “dds.sec.” are reserved by this specification, including future versions of this specification. Plugin implementers can also use this mechanism to pass metadata and configure the behavior of their plugins. In order to avoid collisions with the value of the “name” attribute, implementers shall use property names that start with a prefix to an ICANN domain name they own, in reverse order. For example,the prefix would be “com.acme.” for plugins developed by a hypothetical vendor that owns the domain “acme.com”. The names and interpretation of the expected properties shall be specified by each plugin implementation. Table 1 – Property class Property Attributes name String value String 7.2.1.1 IDL Representation for Property The Property type may be used for information exchange over the network. When a Property is sent over the network it shall be serialized using Extended CDR format according to the Extended IDL representation [3] below. @Extensibility (EXTENSIBLE_EXTENSIBILITY) struct Property { string key; string value; }; typedef sequence< Property > Properties; 7.2.2 BinaryProperty BinaryProperty is a data type that holds a string and an octet sequence. The string is considered the property “name” and the octet sequence the property “value” associated with that name. Sequences of BinaryProperty are used as a generic data type to configure the plugins, pass metadata and provide an extensible mechanism for vendors to configure the behavior of their plugins without breaking portability or interoperability. BinaryProperty objects with a “name” attribute that start with the prefix “dds.sec.” are reserved by this specification, including future versions of this specification. Plugin implementers may use this mechanism to pass metadata and configure the behavior of their plugins. In order to avoid collisions with the value of the “name” attribute implementers, shall use
- 23. DDS Security v1.0 Beta 1 13 property names that start with a prefix to an ICANN domain name they own, in reverse order. For example, the prefix would be “com.acme.” for plugins developed by a hypothetical vendor that owns the domain “acme.com”. The valid values of the “name” attribute and the interpretation of the associated “value” shall be specified by each plugin implementation. Table 2 – BinaryProperty class BinaryProperty Attributes name String value OctetSeq 7.2.2.1 IDL Representation for BinaryProperty The BinaryProperty type may be used for information exchange over the network. When a BinaryProperty is sent over the network, it shall be serialized using Extended CDR format according to the Extended IDL representation [3] below. @Extensibility (EXTENSIBLE_EXTENSIBILITY) struct BinaryProperty { string key; OctetSeq value; }; typedef sequence< BinaryProperty > BinaryProperties; 7.2.3 DataHolder DataHolder is a data type used to hold generic data. It contains various attributes used to store data of different types and formats. DataHolder appears as a building block for other types, such as Token and GenericMessageData. Table 3 – DataHolder class DataHolder Attributes class_id String string_properties PropertySeq binary_properties BinaryPropertySeq string_values StringSeq binary_value1 OctetSeq binary_value2 OctetSeq longlongs_value LongLongSeq
- 24. 14 DDS Security v1.0 Beta1 7.2.3.1 IDL representation for DataHolder The DataHolder type may be used for information exchange over the network. When a DataHolder is sent over the network, it shall be serialized using Extended CDR format according to the Extended IDL representation [3] below. typedef sequence<string> StringSeq; typedef sequence<octet> OctetSeq; typedef sequence<long long> LongLongSeq; @Extensibility (EXTENSIBLE_EXTENSIBILITY) struct DataHolder { string class_id; @Optional Properties string_properties; @Optional BinaryProperties binary_properties; @Optional StringSeq string_values; @Optional OctetSeq binary_value1; @Optional OctetSeq binary_value2; @Optional LongLongSeq longlongs_value; }; typedef sequence<DataHolder> DataHolderSeq; 7.2.4 Credential Credential objects provide a generic mechanism to pass information from DDS to the security plugins. This information is used to identify the application that is running and its permissions. The Credential class provides a generic container for security credentials and certificates. The actual interpretation of the credentials and how they are configured is specific to each implementation of the security plugins and shall be specified by each security plugin. The typical use of credentials would be signed certificates or signed permissions documents. Credential objects are only exchanged locally between the DDS implementation and plugins running in the same process space. They are never sent between processes or over a network. The Credential class is structurally identical to the DataHolder class and therefore has the same structure for all plugin implementations. However the contents and interpretation of the Credential attributes shall be specified by each plugin implementation. There are several specializations of the Credential class. They all share the same format but are used for different purposes. This is modeled by defining specialized classes.
- 25. DDS Security v1.0 Beta 1 15 class Credentials Credential IdentityCredential PermissionsCredential DataHolder - class_id :string - string_properties :Property[] - binary_properties :BinaryProperty[] - string_values :string[] - binary_value1 :byte[] - binary_value2 :byte[] - longlong_values :LongLong[] Figure 3 – Credential Model 7.2.4.1 Attribute: class_id When used as a Credential class, the class_id attribute in the DataHolder identifies the kind of Credential Values of the class_id with the prefix “dds.sec.” are reserved for this specification, including future versions of the specification. Implementers of this specification can use this attribute to identify non- standard credentials. In order to avoid collisions, the class_id they use shall start with a prefix to an ICANN domain name they own, using the same rules specified in 7.2.1 for property names. 7.2.4.2 IDL Representation for Credential and Specialized Classes The Credential class is used to hold information passed as parameters to the plugin operations. Its structure can be defined in IDL such that the mapping to different programming languages is unambiguously defined. typedef DataHolder Credential;
- 26. 16 DDS Security v1.0 Beta1 typedef Credential IdentityCredential; typedef Credential PermissionsCredential; 7.2.5 Token The Token class provides a generic mechanism to pass information between security plugins using DDS as the transport. Token objects are meant for transmission over the network using DDS either embedded within the builtin topics sent via DDS discovery or via special DDS Topic entities defined in this specification. The Token class is structurally identical to the DataHolder class and therefore has the same structure for all plugin implementations. However, the contents and interpretation of the Token objects shall be specified by each plugin implementation. There are multiple specializations of the Token class. They all share the same format, but are used for different purposes. This is modeled by defining specialized classes. class Tokens CryptoToken Token «discovery» IdentityToken «discovery» PermissionsToken MessageTokenPermissionsCredentialToken DataHolder - class_id :string - string_properties :Property[] - binary_properties :BinaryProperty[] - string_values :string[] - binary_value1 :byte[] - binary_value2 :byte[] - longlong_values :LongLong[] Figure 4 – Token Model 7.2.5.1 Attribute: class_id When used as a Token class, the class_id attribute in the DataHolder identifies the kind of Token Strings with the prefix “dds.sec.” are reserved for this specification, including future versions of the specification. Implementers of this specification can use this attribute to identify non-standard tokens. In order to avoid collisions, the class_id they use shall start with a prefix to an ICANN domain name they own, using the same rules specified in 7.2.1 for property names. 7.2.5.2 IDL Representation for Token and Specialized Classes The Token class is used to hold information exchanged over the network. When a Token is sent over the network, it shall be serialized using Extended CDR format according to the Extended IDL representation below:
- 27. DDS Security v1.0 Beta 1 17 typedef DataHolder Token; typedef Token HandshakeMessageToken; typedef Token IdentityToken; typedef Token PermissionsToken; typedef Token IdentityCredentialToken; typedef Token PermissionsCredentialToken; typedef Token CryptoToken; typedef Token ParticipantCryptoToken; typedef Token DatawriterCryptoToken; typedef Token DatareaderCryptoToken; typedef sequence<HandshakeMessageToken> HandshakeMessageTokenSeq; typedef sequence<CryptoToken> CryptoTokenSeq; typedef CryptoTokenSeq ParticipantCryptoTokenSeq; typedef CryptoTokenSeq DatawriterCryptoTokenSeq; typedef CryptoTokenSeq DatareaderCryptoTokenSeq; 7.2.6 ParticipantGenericMessage This specification introduces additional builtin DataWriter and DataReader entities used to send generic messages between the participants. To support these entities, this specification uses a general- purpose data type called ParticipantGenericMessage, which is defined by the following extended IDL: typedef octet[16] BuiltinTopicKey_t; @Extensibility (EXTENSIBLE_EXTENSIBILITY) struct MessageIdentity { BuiltinTopicKey_t source_guid; long long sequence_number; }; typedef string<> GenericMessageClassId; @Extensibility (EXTENSIBLE_EXTENSIBILITY) struct ParticipantGenericMessage { /* target for the request. Can be GUID_UNKNOWN */ MessageIdentity message_identity; MessageIdentity related_message_identity; BuiltinTopicKey_t destination_participant_key; BuiltinTopicKey_t destination_endpoint_key; BuiltinTopicKey_t source_endpoint_key; GenericMessageClassId message_class_id; DataHolderSeq message_data; };
- 28. 18 DDS Security v1.0 Beta1 7.2.7 Additional DDS Return Code: NOT_ALLOWED_BY_SEC The DDS specification defines a set of return codes that may be returned by the operations on the DDS API (see sub clause 7.1.1 of the DDS specification). The DDS Security specification add an additional return code NOT_ALLOWED_BY_SEC, which shall be returned by any operation on the DDS API that fails because the security plugins do not allow it. 7.3 Securing DDS Messages on the Wire OMG DDS uses the Real-Time Publish-Subscribe (RTPS) on-the-wire protocol [2] for communicating data. The RTPS protocol includes specifications on how discovery is performed, the metadata sent during discovery, and all the protocol messages and handshakes required to ensure reliability. RTPS also specifies how messages are put together. 7.3.1 RTPS Background (Non-Normative) In a secure system where efficiency and message latency are also considerations, it is necessary to define exactly what needs to be secured. Some applications may require only the data payload to be confidential and it is acceptable for the discovery information, as well as, the reliability meta-traffic (HEARTBEATs, ACKs, NACKs, etc.) to be visible, as long as it is protected from modification. Other applications may also want to keep the metadata (sequence numbers, in-line QoS) and/or the reliability traffic (ACKs, NACKs, HEARTBEATs) confidential. In some cases, the discovery information (who is publishing what and its QoS) may need to be kept confidential as well. To help clarify these requirements, sub clause 7.3.1 explains the structure of the RTPS Message and the different Submessages it may contain.
- 29. DDS Security v1.0 Beta 1 19 Figure 5 – RTPS message structure An RTPS Message is composed of a leading RTPS Header followed by a variable number of RTPS Submessages. Each RTPS Submessage is composed of a SubmessageHeader followed by a variable number of SubmessagElements. There are various kinds of SubmessageElements to communicate things like sequence numbers, unique identifiers for DataReader and DataWriter entities, SerializedKeys or KeyHash of the application data, source timestamps, QoS, etc. There is one kind of SubmessageElement called SerializedData that is used to carry the data sent by DDS applications. For the purposes of securing communications we distinguish three types of RTPS Submessages: 1. DataWriter Submessages. These are the RTPS submessages sent by a DataWriter to one or more DataReader entities. These include the Data, DataFrag, Gap, Heartbeat, and HeartbeatFrag submessages. 2. DataReader Submessages. These are the RTPS submessages sent by a DataReader to one or more DataWriter entities. These include the AckNack and NackFrag submessages 3. Interpreter Submessages. These are the RTPS submessages that are destined to the Message Interpreter and affect the interpretation of subsequent submessages. These include all the “Info” messages. The only RTPS submessages that contain application data are the Data and DataFrag. The application data is contained within the SerializedData submessage element. In addition to the
- 30. 20 DDS Security v1.0 Beta1 SerializedData, these submessages contain sequence numbers, inline QoS, the Key Hash, identifiers 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 submessage contains either: A serialized representation of the values of all the attributes declared as ‘key’ attributes in the associated data type, or An MD5 hash computed over the aforementioned serialized key attributes. Different RTPS Submessage within the same RTPS Message may originate on different DataWriter or DataReader entities within the DomainParticipant that sent the RTPS message. It is also possible for a single RTPS Message to combine submessages that originated on different DDS DomainParticipant entities. This is done by preceding the set of RTPS Submessages that originate from a common DomainParticipant with an InfoSource RTPS submessage. 7.3.2 Secure RTPS Messages Sub clause 7.1.1 identified the threats addressed by the DDS Security specification. To protect against the “Unauthorized Subscription” threat it is necessary to use encryption to protect the sensitive parts of the RTPS message. Depending on the application requirements, it may be that the only thing that should be kept confidential is the content of the application data; that is, the information contained in the SerializedData RTPS submessage element. However, other applications may also consider the information in other RTPS SubmessageElements (e.g., sequence numbers, KeyHash, and unique writer/reader identifiers) to be confidential. So the entire Data (or DataFrag) submessage may need to be encrypted. Similarly, certain applications may consider other submessages such as Gap, AckNack, Heartbeat, HeartbeatFrag, etc. also to be confidential. For example, a Gap RTPS Submessage instructs a DataReader that a range of sequence numbers is no longer relevant. If an attacker can modify or forge a Gap message from a DataWriter, it can trick the DataReader into ignoring the data that the DataWriter is sending. To protect against “Unauthorized Publication” and “Tampering and Replay” threats, messages must be signed using secure hashes or digital signatures. Depending on the application, it may be sufficient to sign only the application data (SerializedData submessage element), the whole Submessage, and/or the whole RTPS Message. To support different deployment scenarios, this specification uses a “message transformation” mechanism that gives the Security Plugin Implementations fine-grain control over which parts of the RTPS Message need to be encrypted and/or signed. The Message Transformation performed by the Security Plugins transforms an RTPS Message into another RTPS Message. A new RTPS Header may be added and the content of the original 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.
- 31. DDS Security v1.0 Beta 1 21 7.3.3 Constraints of the DomainParticipant BuiltinTopicKey_t (GUID) The DDS and the DDS Interoperability Wire Protocol specifications state that DDS DomainParticipant entities are identified by a unique 16-byte GUID. This DomainParticipant GUID is communicated as part of DDS Discovery in the ParticipantBuiltinTopicData in the attribute participant_key of type BuiltinTopicKey_t defined as: typedef octet BuiltinTopicKey_t[16]; Allowing a DomainParticipant to select its GUID arbitrarily would allow hostile applications to perform a “squatter” attack, whereby a DomainParticipant with a valid certificate could announce itself into the DDS Domain with the GUID of some other DomainParticipant. Once authenticated the “squatter” DomainParticipant would preclude the real of the already existing one. To prevent the aforementioned “squatter” attack, this specification constrains the GUID that can be chosen by a DomainParticipant, so that it is tied to the Identity of the DomainParticipant. This is enforced by the Authentication plugin. 7.3.4 Mandatory use of the KeyHash for encrypted messages The RTPS Data and DataFrag submessages can optionally contain the KeyHash as an inline Qos (see sub clause 9.6.3.3, titled “KeyHash (PID_KEY_HASH)”) of the DDS-RTPS specification version 2.3. In this sub clause it is specified that when present, the key hash shall be computed either as the serialized key or as an MD5 on the serialized key. The key values are logically part of the data and therefore in situations where the data is considered sensitive the key should also be considered sensitive. For this reason the DDS Security specification imposes additional constrains in the use of the key hash. These constraints apply only to the Data or DataFrag RTPS SubMessages where the SerializedData SubmessageElement is encrypted by the operation encode_serialized_data of the CryptoTransform plugin: (1) The KeyHash shall be included in the Inline Qos. (2) The KeyHash shall be computed as the 128 bit MD5 Digest (IETF RFC 1321) applied to the CDR Big- Endian encapsulation of all the Key fields in sequence. Unlike the rule stated in sub clause 9.6.3.3 of the DDS specification, the MD5 hash shall be used regardless of the maximum-size of the serialized key. These rules accomplish two objectives: (1) Avoid leaking the value of the key fields in situations where the data is considered sensitive and therefore appears encrypted within the Data or DataFrag submessages. (2) Enable the operation of infrastructure services without needed to leak to them the value of the key fields (see 7.1.1.4). Note that the use of the MD5 hashing function for these purposes does not introduce significant vulnerabilities. While MD5 is considered broken as far as resistance to collisions (being able to find
- 32. 22 DDS Security v1.0 Beta1 two inputs that result in an identical unspecified hash) there are still no known practical preimage attacks on MD5 (being able to find the input that resulted on a given hash). 7.3.5 Immutability of Publisher Partition Qos in combination with non-volatile Durability kind The DDS specification allows the PartitionQos policy of a Publisher to be changed after the Publisher has been enabled. See sub clause 7.1.3 titled “Supported QoS) of the DDS 1.2 specification. The DDS Security specification restricts this situation. The DDS implementation shall not allow a Publisher to change PartitionQos policy after the Publisher has been enabled if it contains any DataWriter that meets the following two criteria: (1) The DataWriter either encrypts the SerializedData submessage element or encrypts the Data or DataFrag submessage elements. (2) The DataWriter has the DurabilityQos policy kind set to something other than VOLATILE. This rule prevents data that was published while the DataWriter had associated a set of Partitions from being sent to DataReaders that were not matching before the Partition change and match after the Partition is changed 7.3.6 Platform Independent Description 7.3.6.1 RTPS Secure Submessage Elements This specification introduces new RTPS SubmessageElements that may appear inside RTPS Submessages. 7.3.6.1.1 CryptoTransformIdentifier The CryptoTransformIdentifier submessage element identifies the kind of cryptographic transformation that was performed in an RTPS Submessage or an RTPS SubmessageElement and also provides a unique identifier of the key material used for the cryptographic transformation. The way in which attributes in the CryptoTransformIdentifier are set shall be specified for each Cryptographic plugin implementation. However, all Cryptographic plugin implementations shall be set in a way that allows the operations preprocess_secure_submsg, decode_datareader_submessage, decode_datawriter_submessage, and decode_serialized_data to uniquely recognize the cryptographic material they shall use to decode the message, or recognize that they do not have the necessary key material. 7.3.6.1.2 SecuredPayload The SecuredPayload submessage element is used to wrap either a Submessage or a complete RTPS Message. It is the result of applying one of the encoding transformations on the CryptoTransform plugin. The leading bytes in the SecuredPayload shall encode the CryptoTransformIdentifier. Therefore, the transformationKind is guaranteed to be the first element within the
- 33. DDS Security v1.0 Beta 1 23 SecuredPayload. The specific format of this shall be defined by each Cryptographic plugin implementation. 7.3.6.2 RTPS Submessage: SecureSubMsg This specification introduces a new RTPS submessage: SecureSubMsg. The format of the SecureSubMsg complies with the RTPS SubMessage format mandated in the RTPS specification. It consists of the RTPS SubmessageHeader followed by a set of RTPS SubmessageElement elements. Since the SecureSubMsg conforms to the general structure of RTPS submessages, it can appear inside a well-formed RTPS message. class SecureSubmessage RTPS::SubmessageHeader - submessageId :SubmessageKind - submessagLengh :ushort - flags :SubmessageFlag[8] SecureSubMsg RTPS::Submessage «interface» CryptoTransformIdentifier - transformationKind :long - transformationId :octet[8] SecuredPayload - transformationId :CryptoTransformIdentifier - value :octet[*] RTPS::SubmessageElement0..* «use» 1 Figure 6 – Secure Submessage and Secured Payload Model 7.3.6.2.1 Purpose The SecureSubMsg submessage is used to wrap one or more regular RTPS submessages in such a way that their contents are secured via encryption, message authentication, and/or digital signatures. 7.3.6.2.2 Content The elements that form the structure of the RTPS SecureSubMsg are described in the table below.
- 34. 24 DDS Security v1.0 Beta1 Table 4 – SecureSubMsg class Element Type Meaning 7.3.6.2.3 Validity The RTPS Submessage is invalid if the submessageLength in the Submessage header is too small. 7.3.6.2.4 Logical Interpretation The SecureSubMsg provides a way to send secure content inside a legal RTPS submessage. A SecureSubMsg may wrap a single RTPS Submessage or a whole RTPS Message. These two situations are distinguished by the value of the MultisubmsgFlag. The SecuredPayload shall follow immediately after the SubmessageHeader. If the SingleSubmsgFlag is true, the SecuredPayload contains a single RTPS submessage that was obtained as a result of the encode_datawriter_submessage or encode_datawriter_submessage operations on the CryptoTransform plugin. If the SingleSubmsgFlag is false, the SecuredPayload contains the whole RTPS message obtained as a result of the encode_rtps_message operation on the CryptoTransform plugin.
- 35. DDS Security v1.0 Beta 1 25 Figure 7 – RTPS message transformations 7.3.7 Mapping to UDP/IP PSM The DDS-RTPS specification defines the RTPS protocol in terms of a platform-independent model (PIM) and then maps it to a UDP/IP transport PSM (see clause 9, “Platform Specific Model (PSM): UDP/IP” of the DDS-RTPS specification [2]). Sub clause 7.3.7 does the same thing for the new RTPS submessage elements and submessages introduced by the DDS Security specification. 7.3.7.1 Mapping of the EntityIds for the Builtin DataWriters and DataReaders Sub clause 7.4 defines a set of builtin Topics and corresponding DataWriter and DataReader entities that shall be present on all compliant implementations of the DDS Security specification. The corresponding EntityIds used when these endpoints are used on the UDP/IP PSM are given in the table below. Table 5 – EntityId values for secure builtin data writers and data readers Entity EntityId_t name EntityId_t value SEDPbuiltinPublicationsSecureWr
- 36. 26 DDS Security v1.0 Beta1 iter SEDPbuiltinPublicationsSecureRe ader SEDPbuiltinSubscriptionsSecureW riter SEDPbuiltinSubscriptionsSecureR eader BuiltinParticipantMessageSecure Writer BuiltinParticipantMessageSecure Reader BuiltinParticipantStatelessMessag eWriter BuiltinParticipantStatelessMessag eReader BuiltinParticipantVolatileMessage SecureWriter BuiltinParticipantVolatileMessage SecureReader 7.3.7.2 Mapping of the CryptoTransformIdentifier Type The UDP/IP PSM maps the CryptoTransformIdentifier to the following extended IDL structure: typedef octet OctetArray8[8]; @Extensibility(FINAL_EXTENSIBILITY) struct CryptoTransformIdentifier { long transformationKind; OctetArray8 transformationId; }; The CryptoTransformIdentifier shall be serialized using CDR using the endianess specified by the EndianessFlag in the SubmessageHeader. 7.3.7.3 Mapping of the SecuredPayload SubmessageElement A SecuredPayload SubmessageElement contains the result of cryptographically transforming either an RTPS Message or a single RTPS Submessage. In both cases the SecuredPayload shall start with the CryptoTransformIdentifier and be followed by the ciphertext returned by the encoding transformation.
- 37. DDS Security v1.0 Beta 1 27 The UDP/IP wire representation for the SecuredPayload shall be: 0...2...........8...............16.............24...............32 +---------------+---------------+---------------+---------------+ | long transformationKind | +---------------+---------------+---------------+---------------+ | | + octet transformationId[8] + | | +---------------+---------------+---------------+---------------+ | | ~ octet ciphertext[] ~ | | +---------------+---------------+---------------+---------------+ 7.3.7.4 SecureSubMsg Submessage 7.3.7.4.1 Wire Representation The UDP/IP wire representation for the SecureSubMsg shall be: 0...2...........8...............16.............24...............32 +---------------+---------------+---------------+---------------+ | SecureSubMsgId|X|X|X|X|X|X|S|E| octetsToNextHeader | +---------------+---------------+---------------+---------------+ | | + SecuredPayload payload + | | +---------------+---------------+---------------+---------------+ 7.3.7.4.2 Submessage Id The SecureSubMsg shall have the submessageId set to the value 0x30. 7.3.7.4.3 Flags in the Submessage Header In addition to the EndiannessFlag, the SecureSubMsg introduces the SingleSubmessageFlag (see 7.3.6.2.2). The PSM maps these flags as follows: The SingleSubmessageFlag is represented with the literal ‘S.’ The value of the InlineQosFlag can be obtained from the expression: S = SubmessageHeader.flags & 0x02 The SingleSubmessageFlag is interpreted as follows: S=0 means that the SecureSubMsg submessage is an envelope for a full RTPS message. S=1 means that the SecureSubMsg submessage is an envelope for a single RTPS submessage.
- 38. 28 DDS Security v1.0 Beta1 7.4 DDS Support for Security Plugin Information Exchange In order to perform their function, the security plugins associated with different DDS DomainParticipant entities need to exchange information representing things such as Identity and Permissions of the DomainParticipant entities, authentication challenge messages, tokens representing key material, etc. DDS already has several mechanisms for information exchange between DomainParticipant entities. Notably the builtin DataWriter and DataReader entities used by the Simple Discovery Protocol (see sub clause 8.5 of the DDS Interoperability Wire Protocol [2]) and the BuiltinParticipantMessageWriter and BuiltinParticipantMessageReader (see sub clause 9.6.2.1 of the DDS Interoperability Wire Protocol [2]). Where possible, this specification tries to reuse and extend existing DDS concepts and facilities so that they can fulfill the needs of the security plugins, rather than defining entirely new ones. This way, the Security Plugin implementation can be simplified and it does not have to implement a separate messaging protocol. 7.4.1 Secure builtin Discovery Topics 7.4.1.1 Background (Non-Normative) DDS discovery information is sent using builtin DDS DataReaders and DataWriters. These are regular DDS DataReaders and DataWriters, except they are always present in the system and their Topic names, associated data types, QoS, and RTPS EntityIds are all specified as part of the DDS and RTPS specifications, so they do not need to be discovered. The DDS specification defines three discovery builtin Topic entities: the DCPSParticipants used to discover the presence of DomainParticipants, the DCPSPublications used to discover DataWriters, and the DCPSSubscriptions used to discover DataReaders (see sub clause 8.5 of the DDS Interoperability Wire Protocol [2]). Much of the discovery information could be considered sensitive in secure DDS systems. Knowledge of things like the Topic names that an application is publishing or subscribing to could reveal sensitive information about the nature of the application. In addition, the integrity of the discovery information needs to be protected against tampering, since could cause erroneous behaviors or malfunctions. One possible approach to protecting discovery information would be to require that the discovery builtin Topic entities always be protected via encryption and message authentication. However, this would entail the problems explained below. The DCPSParticipants builtin Topic is used to bootstrap the system, detect the presence of DomainParticipant entities, and kick off subsequent information exchanges and handshakes. It contains the bare minimum information needed to establish protocol communications (addresses, port numbers, version number, vendor IDs, etc.). If this Topic were protected, the Secure DDS system would have to create an alternative mechanism to bootstrap detection of other participants and gather the same information—which needs to happen prior to being able to perform mutual authentication and exchange of key material. This mechanism would, in essence, duplicate the information in the DCPSParticipants builtin Topic. Therefore, it makes little sense to protect the DCPSParticipants builtin Topic. A better approach is to augment the information sent using the DCPSParticipants
- 39. DDS Security v1.0 Beta 1 29 builtin Topic with any additional data the Secure DDS system needs for bootstrapping communications (see 7.4.1.3). Secure DDS systems need to co-exist in the same network and, in some cases, interoperate with non- secure DDS systems. There may be systems built using implementations compliant with the DDS Security specification which do not need to protect their information. Or there may be systems implemented with legacy DDS implementations that do not support DDS Security. In this situation, the fact that a secure DDS implementation is present on the network should not impact the otherwise correct behavior of the non-secure DDS systems. In addition, even in secure systems not all Topics are necessarily sensitive, so it is desirable to provide ways to configure a DDS Secure system to have Topics that are “unprotected” and be able to communicate with non-secure DDS systems on those “unprotected” Topics. To allow co-existence and interoperability between secure DDS systems and DDS systems that do not implement DDS security, secure DDS systems must retain the same builtin Topics as the regular DDS systems (with the same GUIDs, topics names, QoS, and behavior). Therefore, to protect the discovery and liveliness information of Topics that are considered sensitive, Secure DDS needs to use additional builtin discovery Topics protected by the DDS security mechanisms. 7.4.1.2 Extending the Data Types used by DDS Discovery The DDS Interoperability Wire Protocol specifies the serialization of the data types used for the discovery of builtin Topics (ParticipantBuiltinTopicData, PublicationBuiltinTopicData, and SubscriptionBuiltinTopicData) using a representation called using a ParameterList. Although this description precedes the DDS-XTYPES specification, the serialization format matches the Extended CDR representation defined in DDS-XTYPES for data types declared with MUTABLE extensibility. This allows the data type associated with discovery topics to be extended without breaking interoperability. Given that DDS-XTYPES formalized the ParameterList serialization approach, first defined in the DDS Interoperability and renamed it to “Extended CDR,” this specification will use the DDS Extensible Types notation to define the data types associated with the builtin Topics. This does not imply that compliance to the DDS-XTYPES is required to comply with DDS Security. All that is required is to serialize the specific data types defined here according to the format described in the DDS-XTYPES specification. 7.4.1.3 Extension to RTPS Standard DCPSParticipants Builtin Topic The DDS specification specifies the existence of the DCPSParticipants builtin Topic and a corresponding builtin DataWriter and DataReader to communicate this Topic. These endpoints are used to discover DomainParticipant entities. The data type associated with the DCPSParticipants builtin Topic is ParticipantBuiltinTopicData, defined in sub clause 7.1.5 of the DDS specification. The DDS Interoperability Wire Protocol specifies the serialization of ParticipantBuiltinTopicData. The format used is what the DDS Interoperability Wire Protocol calls a ParameterList whereby each member of the ParticipantBuiltinTopicData is serialized using CDR but preceded in the stream by the serialization of a short ParameterID identifying the member, followed by another short containing the length of the serialized member, followed by the serialized member. See sub clause 8.3.5.9 of the DDS Interoperability Wire Protocol [2]. This serialization format allows the ParticipantBuiltinTopicData to be extended without breaking interoperability.
- 40. 30 DDS Security v1.0 Beta1 This DDS Security specification adds several new members to the ParticipantBuiltinTopicData structure. The member types and the ParameterIDs used for the serialization are described below. Table 6 Additional parameter IDs in ParticipantBuiltinTopicData Member name Member type Parameter ID name Parameter ID value @extensibility(MUTABLE_EXTENSIBILITY) struct ParticipantBuiltinTopicDataSecure: ParticipantBuiltinTopicData { @ID(0x1001) IdentityToken identity_token; @ID(0x1002) PermissionsToken permissions_token; }; 7.4.1.4 New DCPSPublicationsSecure Builtin Topic The DDS specification specifies the existence of the DCPSPublications builtin Topic with topic name “DCPSPublications” and corresponding builtin DataWriter and DataReader entities to communicate on this Topic. These endpoints are used to discover non-builtin DataWriter entities. The data type associated with the DCPSPublications Topic is PublicationBuiltinTopicData, defined in sub clause 7.1.5 of the DDS specification. Implementations of the DDS Security shall use that same DCPSPublications Topic to communicate the DataWriter information for Topic entities that are not considered sensitive. Implementations of the DDS Security specification shall have an additional builtin Topic referred as DCPSPublicationsSecure and associated builtin DataReader and DataWriter entities to communicate the DataWriter information for Topic entities that are considered sensitive. The determination of which Topic entities are considered sensitive shall be specified by the AccessControl plugin. The Topic name for the DCPSPublicationsSecure Topic shall be “DCPSPublicationsSecure”. The data type associated with the DCPSPublicationsSecure Topic shall be PublicationBuiltinTopicDataSecure, defined to be the same as the PublicationBuiltinTopicData structure used by the DCPSPublications Topic, except the structure has the additional member data_tags with the data type and ParameterIds described below. Table 7 Additional parameter IDs in PublicationBuiltinTopicDataSecure Member name Member type Parameter ID name Parameter ID value struct Tag { string name; string value;
- 41. DDS Security v1.0 Beta 1 31 }; typedef sequence<Tag> TagSeq; struct DataTags { TagSeq tags; }; @extensibility(MUTABLE_EXTENSIBILITY) struct PublicationBuiltinTopicDataSecure: PublicationBuiltinTopicData { @ID(0x1003) DataTags data_tags; }; The QoS associated with the DCPSPublicationsSecure Topic shall be the same as for the DCPSPublications Topic. The builtin DataWriter for the DCPSPublicationsSecure Topic shall be referred to as the SEDPbuiltinPublicationsSecureWriter. The builtin DataReader for the DCPSPublicationsSecure Topic shall be referred to as the SEDPbuiltinPublicationsSecureReader. The RTPS EntityId_t associated with the SEDPbuiltinPublicationsSecureWriter and SEDPbuiltinPublicationsSecureReader shall be as specified in 7.4.5. 7.4.1.5 New DCPSSubscriptionsSecure Builtin Topic The DDS specification specifies the existence of the DCPSSubscriptions builtin Topic with Topic name “DCPSSubscriptions” and corresponding builtin DataWriter and DataReader entities to communicate on this Topic. These endpoints are used to discover non-builtin DataReader entities. The data type associated with the DCPSSubscriptions is SubscriptionBuiltinTopicData is defined in sub clause 7.1.5 of the DDS specification. Implementations of the DDS Security specification shall use that same DCPSSubscriptions Topic to send the DataReader information for Topic entities that are not considered sensitive. The existence and configuration of Topic entities as non-sensitive shall be specified by the AccessControl plugin. Implementations of the DDS Security specification shall have an additional builtin Topic referred to as DCPSSubscriptionsSecure and associated builtin DataReader and DataWriter entities to communicate the DataReader information for Topic entities that are considered sensitive. The determination of which Topic entities are considered sensitive shall be specified by the AccessControl plugin. The data type associated with the DCPSSubscriptionsSecure Topic shall be SubscriptionBuiltinTopicDataSecure defined to be the same as the SubscriptionBuiltinTopicData structure used by the DCPSSubscriptions Topic, except the structure has the additional member data_tags with the data type and ParameterIds described below. Table 8 Additional parameter IDs in SubscriptionBuiltinTopicDataSecure Member name Member type Parameter ID name Parameter ID value
- 42. 32 DDS Security v1.0 Beta1 @extensibility(MUTABLE_EXTENSIBILITY) struct SubscriptionBuiltinTopicDataSecure: SubscriptionBuiltinTopicData { @ID(0x1003) DataTags data_tags; }; The QoS associated with the DCPSSubscriptionsSecure Topic shall be the same as for the DCPSSubscriptions Topic. The builtin DataWriter for the DCPSSubscriptionsSecure Topic shall be referred to as the SEDPbuiltinSubscriptionsSecureWriter. The builtin DataReader for the DCPSPublicationsSecure Topic shall be referred to as the SEDPbuiltinSubscriptionsSecureReader. The RTPS EntityId_t associated with the SEDPbuiltinSubscriptionsSecureWriter and SEDPbuiltinSubscriptionsSecureReader shall be as specified in 7.4.5. 7.4.2 New ParticipantMessageSecure builtin Topic The DDS Interoperability Wire Protocol specifies the BuiltinParticipantMessageWriter and BuiltinParticipantMessageReader (see sub clauses 8.4.13 and 9.6.2.1 of the DDS Interoperability Wire Protocol[2]). These entities are used to send information related to the LIVELINESS QoS. This information could be considered sensitive and therefore secure DDS systems need to provide an alternative protected way to send liveliness information. The data type associated with these endpoints is ParticipantMessageData defined in sub clause 9.6.2.1 of the DDS Interoperability Wire Protocol specification [2]. To support coexistence and interoperability with non-secure DDS applications, implementations of the DDS Security specification shall use the same standard BuiltinParticipantMessageWriter and BuiltinParticipantMessageReader to communicate liveliness information on Topic entities that are not considered sensitive. Implementations of the DDS Security specification shall have an additional ParticipantMessageSecure builtin Topic and associated builtin DataReader and DataWriter entities to communicate the liveliness information for Topic entities that are considered sensitive. The data type associated with the ParticipantMessageSecure Topic shall be the same as the ParticipantMessageData structure. The QoS associated with the ParticipantMessageSecure Topic shall be the same as for the ParticipantMessageSecure Topic as defined in sub clause 8.4.13 of the DDS Interoperability Wire Protocol [2]. The builtin DataWriter for the ParticipantMessageSecure Topic shall be referred to as the BuiltinParticipantMessageSecureWriter. The builtin DataReader for the ParticipantMessageSecure Topic shall be referred to as the BuiltinParticipantMessageSecureReader. The RTPS EntityId_t associated with the BuiltinParticipantMessageSecureWriter and BuiltinParticipantMessageSecureReader shall be as specified in 7.4.5.
- 43. DDS Security v1.0 Beta 1 33 7.4.3 New ParticipantStatelessMessage builtin Topic To perform mutual authentication between DDS DomainParticipant entities, the security plugins associated with those participants need to be able to send directed messages to each other. As described in 7.4.3.1 below, the mechanisms provided by existing DDS builtin Topic entities are not adequate for this purpose. For this reason, this specification introduces a new ParticipantStatelessMessage builtin Topic and corresponding builtin DataReader and DataWriter entities to read and write the Topic. 7.4.3.1 Background: Sequence Number Attacks (non normative) DDS has a builtin mechanism for participant-to-participant messaging: the BuiltinParticipantMessageWriter and BuiltinParticipantMessageReader (see sub clause 9.6.2.1 of the DDS Interoperability Wire Protocol [2]). However this mechanism cannot be used for mutual authentication because it relies on the RTPS reliability protocol and suffers from the sequence-number prediction vulnerability present in unsecured reliable protocols: The RTPS reliable protocol allows a DataWriter to send to a DataReader Heartbeat messages that advance the first available sequence number associated with the DataWriter. A DataReader receiving a Heartbeat from a DataWriter will advance its first available sequence number for that DataWriter and ignore any future messages it receives with sequence numbers lower than the first available sequence number for the DataWriter. The reliable DataReader will also ignore duplicate messages for that same sequence number. The behavior of the reliability protocol would allow a malicious application to prevent other applications from communicating by sending Heartbeats pretending to be from other DomainParticipants that contain large values of the first available sequence number. All the malicious application needs to do is learn the GUIDs of other applications, which can be done from observing the initial discovery messages on the wire, and use that information to create fake Heartbeats. Stated differently: prior to performing mutual authentication and key exchange, the applications cannot rely on the use of encryption and message access codes to protect the integrity of the messages. Therefore, during this time window, they are vulnerable to this kind of sequence-number attack. This attack is present in most reliable protocols. Stream-oriented protocols such as TCP are also vulnerable to sequence-number-prediction attacks but they make it more difficult by using a random initial sequence number on each new connection and discarding messages with sequence numbers outside the window. This is something that RTPS cannot do given the data-centric semantics of the protocol. In order to avoid this vulnerability, the Security plugins must exchange messages using writers and readers sufficiently robust to sequence number prediction attacks. The RTPS protocol specifies endpoints that meet this requirement: the RTPS StatelessWriter and StatelessReader (see 8.4.7.2 and 8.4.10.2 of the DDS Interoperability Wire Protocol [2]) but there are not DDS builtin endpoints that provide access to this underlying RTPS functionality. 7.4.3.2 BuiltinParticipantStatelessMessageWriter and BuiltinParticipantStatelessMessageReader The DDS Security specification defines two builtin Endpoints: the BuiltinParticipantStatelessMessageWriter and the BuiltinParticipantStatelessMessageReader. These two endpoints shall be present in compliant implementations of this specification. These endpoints are used to write and read the builtin ParticipantStatelessMessage Topic.
- 44. 34 DDS Security v1.0 Beta1 The BuiltinParticipantStatelessMessageWriter is an RTPS Best-Effort StatelessWriter (see sub clause 8.4.7.2 of the DDS Interoperability Wire Protocol [2]). The BuiltinParticipantStatelessMessageReader is an RTPS Best-Effort StatelessReader (see sub clause 8.4.10.2 of the DDS Interoperability Wire Protocol [2]). The data type associated with these endpoints is ParticipantStatelessMessage defined below (see also 7.2.6): typedef ParticipantStatelessMessage ParticipantGenericMessage; The RTPS EntityId_t associated with the BuiltinParticipantStatelessMessageWriter and BuiltinParticipantStatelessMessageReader shall be as specified in 7.4.5. 7.4.3.3 Contents of the ParticipantStatelessMessage The ParticipantStatelessMessage is intended as a holder of information that is sent point- to-point from a DomainParticipant to another. The message_identity uniquely identifies each individual ParticipantStatelessMessage: The source_guid field within the message_identity shall be set to match the BuiltinTopicKey_t of the BuiltinParticipantStatelessMessageWriter that writes the message. The sequence_number field within the message_identity shall start with the value set to one and be incremented for each different message sent by the BuiltinParticipantStatelessMessageWriter. The related_message_identity uniquely identifies another ParticipantStatelessMessage that is related to the message being processed. It shall be set to either the tuple {GUID_UNKNOWN, 0} if the message is not related to any other message, or else set to match the message_identity of the related ParticipantStatelessMessage. The destination_participant_key shall contain either the value GUID_UNKNOWN (see sub clause 9.3.1.5 of the DDS Interoperability Wire Protocol [2]) or else the BuiltinTopicKey_t of the destination DomainParticipant. The destination_endpoint_key provides a mechanism to specify finer granularity on the intended recipient of a message beyond the granularity provided by the destination_participant_key. It can contain either GUID_UNKNOWN or else the GUID of a specific endpoint within destination DomainParticipant. The targeted endpoint is the one whose Endpoint (DataWriter or DataReader) BuiltinTopic_t matches the destination_endpoint_key. The contents message_data depend on the value of the message_class_id and are defined in this specification in the sub clause that introduces each one of the pre-defined values of the GenericMessageClassId. See 7.4.3.5 and 7.4.3.6. 7.4.3.4 Destination of the ParticipantStatelessMessage If the destination_participant_key member is not set to GUID_UNKNOWN, the message written is intended only for the BuiltinParticipantStatelessMessageReader belonging to the DomainParticipant with a matching Participant Key. This is equivalent to saying that the BuiltinParticipantStatelessMessageReader has an implied content filter with the logical expression:
- 45. DDS Security v1.0 Beta 1 35 “destination_participant_key == GUID_UNKNOWN || destination_participant_key == BuiltinParticipantStatelessMessageReader.participant.key” Implementations of the specification can use this content filter or some other mechanism as long as the resulting behavior is equivalent to having this content filter. If the destination_endpoint_key member is not set to GUID_UNKNOWN, the message written targets the specific endpoint within the destination DomainParticipant with am matching Endpoint Key. 7.4.3.5 Reserved values of ParticipantStatelessMessage GenericMessageClassId This specification, including future versions of this specification reserves GenericMessageClassId values that start with the prefix “dds.sec.” (without quotes) . The specification defines and uses the following specific values for the GenericMessageClassId: #define GMCLASSID_SECURITY_AUTH_HANDSHAKE “dds.sec.auth” Additional values of the GenericMessageClassId may be defined with each plugin implementation. 7.4.3.6 Format of data within ParticipantStatelessMessage Each value for the GenericMessageClassId uses different schema to store data within the generic attributes in the message_data. 7.4.3.6.1 Data for message class GMCLASSID_SECURITY_AUTH_HANDSHAKE If GenericMessageClassId is GMCLASSID_SECURITY_AUTH_HANDSHAKE the message_data attribute shall contain the HandshakeMessageTokenSeq containing one element. The specific contents of the HandshakeMessageToken element shall be defined by the Authentication Plugin. The destination_participant_key shall be set to the BuiltinTopicKey_t of the destination DomainParticipant. The destination_endpoint_key shall be set to GUID_UNKNOWN. This indicates that there is no specific endpoint targeted by this message: It is intended for the whole DomainParticipant. The source_endpoint_key shall be set to GUID_UNKNOWN. 7.4.4 New ParticipantVolatileMessageSecure builtin Topic 7.4.4.1 Background (Non-Normative) In order to perform key exchange between DDS DomainParticipant entities, the security plugins associated with those participants need to be able to send directed messages to each other using a reliable and secure channel. These messages are intended only for Participants that are currently in the system and therefore need a DURABILITY Qos of kind VOLATILE. The existing mechanisms provided by DDS are not adequate for this purpose: The new ParticipantStatelessMessage is not suitable because it is a stateless best-effort channel not protected by the security mechanisms in this specification and therefore requires the message data
- 46. 36 DDS Security v1.0 Beta1 to be explicitly encrypted and signed prior to being given to the ParticipantStatelessMessageWriter. The new ParticipantMessageSecure is not suitable because its QoS is has DURABILITY kind TRANSIENT_LOCAL (see sub clause 8.4.13 of the DDS Interoperability Wire Protocol [2]) rather than the required DURABILITY kind VOLATILE. For this reason, implementations of the DDS Security specification shall have an additional builtin Topic ParticipantVolatileMessageSecure and corresponding builtin DataReader and DataWriter entities to read and write the Topic. 7.4.4.2 BuiltinParticipantVolatileMessageSecureWriter and BuiltinParticipantVolatileMessageSecureReader The DDS Security specification defines two new builtin Endpoints: The BuiltinParticipantVolatileMessageSecureWriter and the BuiltinParticipantVolatileMessageSecureReader. These two endpoints shall be present in compliant implementations of this specification. These endpoints are used to write and read the builtin ParticipantVolatileSecureMessage Topic. The BuiltinParticipantVolatileMessageSecureWriter is an RTPS Reliable StatefulWriter (see sub clause 8.4.9.2 of the DDS Interoperability Wire Protocol [2]). The DDS DataWriter Qos associated with the DataWriter shall be as defined in the table below. Any policies that are not shown in the table shall be set corresponding to the DDS defaults. Table 9 – Non-default Qos policies for BuiltinParticipantVolatileMessageSecureWriter The BuiltinParticipantVolatileMessageSecureReader is an RTPS Reliable StatefulReader (see sub clause 8.4.11.2 of the DDS Interoperability Wire Protocol [2]). The DDS DataReader Qos associated with the DataReader shall be as defined in the table below. Any policies that are not shown in the table shall be set corresponding to the DDS defaults. Table 10 – Non-default Qos policies for BuiltinParticipantVolatileMessageSecureReader The data type associated with these endpoints is ParticipantVolatileSecureMessage defined as: typedef ParticipantVolatileSecureMessage ParticipantGenericMessage;
- 47. DDS Security v1.0 Beta 1 37 The RTPS EntityId_t associated with associated with the BuiltinParticipantVolatileMessageSecureWriter and BuiltinParticipantVolatileMessageSecureReader shall be as specified in 7.4.5. 7.4.4.3 Contents of the ParticipantVolatileSecureMessage The ParticipantVolatileSecureMessage is intended as a holder of secure information that is sent point-to-point from a DomainParticipant to another. The destination_participant_key shall contain either the value GUID_UNKNOWN (see sub clause 9.3.1.5 of the DDS Interoperability Wire Protocol [2] or else the BuiltinTopicKey_t of the destination DomainParticipant. The message_identity uniquely identifies each individual ParticipantVolatileSecureMessage: The source_guid field within the message_identity shall be set to match the BuiltinTopicKey_t of the BuiltinParticipantVolatileMessageSecureWriter that writes the message. The sequence_number field within the message_identity shall start with the value set to one and be incremented for each different message sent by the BuiltinParticipantVolatileMessageSecureWriter. The related_message_identity uniquely identifies another ParticipantVolatileSecureMessage that is related to the message being processed. It shall be set to either the tuple {GUID_UNKNOWN, 0} if the message is not related to any other message, or else set to match the message_identity of the related ParticipantVolatileSecureMessage. The contents message_data depend on the value of the message_class_id and are defined in this specification in the sub clause that introduces each one of the defined values of the GenericMessageClassId, see 7.4.4.5. 7.4.4.4 Destination of the ParticipantVolatileSecureMessage If the destination_participant_key member is not set to GUID_UNKNOWN, the message written is intended only for the BuiltinParticipantVolatileMessageSecureReader belonging to the DomainParticipant with a matching Participant Key. This is equivalent to saying that the BuiltinParticipantVolatileMessageSecureReader has an implied content filter with the logical expression: “destination_participant_key == GUID_UNKNOWN || destination_participant_key == BuiltinParticipantVolatileMessageSecureReader.participant.key” Implementations of the specification can use this content filter or some other mechanism as long as the resulting behavior is equivalent to having this filter. If the destination_endpoint_key member is not set to GUID_UNKNOWN the message written targets a specific endpoint within the destination DomainParticipant. The targeted endpoint is the one whose Endpoint Key (DataWriter or DataReader BuiltinTopic_t) matches the destination_endpoint_key. This
- 48. 38 DDS Security v1.0 Beta1 attribute provides a mechanism to specify finer granularity on the intended recipient of a message beyond the granularity provided by the destination_participant_key. 7.4.4.5 Reserved values of ParticipantVolatileSecureMessage GenericMessageClassId This specification, including future versions of this specification reserves GenericMessageClassId values that start with the prefix “dds.sec.” (without the quotes) . The specification defines and uses the following specific values for the GenericMessageClassId: #define GMCLASSID_SECURITY_PARTICIPANT_CRYPTO_TOKENS ”dds.sec.participant_crypto_tokens” #define GMCLASSID_SECURITY_DATAWRITER_CRYPTO_TOKENS ”dds.sec.datawriter_crypto_tokens” #define GMCLASSID_SECURITY_DATAREADER_CRYPTO_TOKENS ”dds.sec.datareader_crypto_tokens” Additional values of the GenericMessageClassId may be defined with each plugin implementation. 7.4.4.6 Format of data within ParticipantVolatileSecureMessage Each value for the GenericMessageClassId uses different schema to store data within the generic attributes in the message_data. 7.4.4.6.1 Data for message class GMCLASS_SECURITY_PARTICIPANT_CRYPTO_TOKENS If GenericMessageClassId is GMCLASSID_SECURITY_PARTICIPANT_CRYPTO_TOKENS the message_data attribute shall contain the ParticipantCryptoTokenSeq. This message is intended to send cryptographic material from one DomainParticipant to another when the cryptographic material applies to the whole DomainParticipant and not a specific DataReader or DataWriter within. The concrete contents of the ParticipantCryptoTokenSeq shall be defined by the Cryptographic Plugin (CryptoKeyFactory). The destination_participant_key shall be set to the BuiltinTopicKey_t of the destination DomainParticipant. The destination_endpoint_key shall be set to GUID_UNKNOWN. This indicates that there is no specific endpoint targeted by this message: It is intended for the whole DomainParticipant. The source_endpoint_key shall be set to GUID_UNKNOWN. 7.4.4.6.2 Data for message class GMCLASSID_SECURITY_DATAWRITER_CRYPTO_TOKENS If GenericMessageClassId is GMCLASSID_SECURITY_DATAWRITER_CRYPTO_TOKENS, the message_data shall contain the DatawriterCryptoTokenSeq. This message is intended to send cryptographic material from one DataWriter to a DataReader whom it wishes to send information to. The cryptographic material applies to a specific ‘sending’ DataWriter and it is constructed for a specific ‘receiving’ DataReader. This may be used to send the crypto keys used by a DataWriter to encrypt data and sign the data it sends to a DataReader.
- 49. DDS Security v1.0 Beta 1 39 The concrete contents of the DatawriterCryptoTokenSeq shall be defined by the Cryptographic Plugin (CryptoKeyFactory). The destination_endpoint_key shall be set to the BuiltinTopicKey_t of the DataReader that should receive the CryptoToken values in the message. The source_endpoint_key shall be set to the BuiltinTopicKey_t of the DataWriter that what will be using the CryptoToken values to encode the data it sends to the DataReader. 7.4.4.6.3 Data for message class GMCLASSID_SECURITY_DATAREADER_CRYPTO_TOKENS If GenericMessageClassId is GMCLASSID_SECURITY_DATAWRITER_CRYPTO_TOKENS, the message_data attribute shall contain the DatareaderCryptoTokenSeq. This message is intended to send cryptographic material from one DataReader to a DataWriter whom it wishes to send information to. The cryptographic material applies to a specific ‘sending’ DataReader and it is constructed for a specific ‘receiving’ DataWriter. This may be used to send the crypto keys used by a DataReader to encrypt data and sign the ACKNACK messages it sends to a DataWriter. The concrete contents of the DatareaderCryptoTokenSeq shall be defined by the Cryptographic Plugin (CryptoKeyFactory). The destination_endpoint_key shall be set to the BuiltinTopicKey_t of the DataWriter that should receive the CryptoToken values in the message. The source_endpoint_key shall be set to the BuiltinTopicKey_t of the DataReader that what will be using the CryptoToken values to encode the data it sends to the DataWriter. 7.4.5 Definition of the “Builtin Secure Endpoints” The complete list of builtin Endpoints that are protected by the security mechanism introduced in the DDS Security specification is: SEDPbuiltinPublicationsSecureWriter, SEDPbuiltinPublicationsSecureReader, SEDPbuiltinSubscriptionsSecureWriter, SEDPbuiltinSubscriptionsSecureReader, BuiltinParticipantMessageSecureWriter, BuiltinParticipantMessageSecureReader, BuiltinParticipantVolatileMessageSecureWriter, and BuiltinParticipantVolatileMessageSecureReader. This list shall be referred to as the builtin secure endpoints.
- 50. 40 DDS Security v1.0 Beta1 8 Plugin Architecture 8.1 Introduction There are five plugin SPIs: Authentication, Access-Control, Cryptographic, Logging, and Data Tagging. class DDS::SecurityOverview SecurityPlugin «interface» Authentication SecurityPlugin «interface» AccessControl «primitive» IdentityHandle «primitive» PermissionsHandle «interface» AccessControlListener «interface» AuthenticationListener SecurityPlugin «interface» Logging Token «discovery» IdentityToken Token CryptoToken Credential PermissionsCredential SecurityPlugin «interface» DataTagging Credential IdentityCredential Token «discovery» PermissionsToken CryptoKeyExchange CryptoKeyFactory CryptoTransform «interface» Cryptographic «primitive» SharedSecretHandle «primitive» DatareaderCryptoHandle «primitive» DatawriterCryptoHandle «primitive» ParticipantCryptoHandle «dataType» CryptoTransformIdentifier «create» «create» «create» «create» «use»«create» «use» «use» «create» «create» «create» «create» «create» «use» «use» Figure 8 – Plugin Architecture Model The responsibilities and interactions between these Service Plugins are summarized in the table below and detailed in the sections that follow.
- 51. DDS Security v1.0 Beta 1 41 Table 11 – Purpose of each Security Plugin Service Plugin Purpose Interactions Authentication Authenticate the principal that is joining a DDS Domain. Support mutual authentication between participants and establish a shared secret. The principal may be an application/process or the user associated with that application or process. AccessControl Decide whether a principal is allowed to perform a protected operation. Protected operations include joining a specific DDS domain, creating a Topic, reading a Topic, writing a Topic, etc. Cryptography Generate keys. Perform Key Exchange. Perform the encryption and decryption operations. Compute digests, compute and verify Message Authentication Codes. Sign and verify signatures of messages. This plugin implements 3 complementary interfaces: CryptoKeyFactory, CryptoKeyExchange, and CryptoTransform. Logging Log all security relevant events This plugin is accessible to all other plugins such that they can log the relevant events DataTagging 8.2 Common Types 8.2.1 Security Exception SecurityException is a data type used to hold error information. SecurityException objects are potentially returned from many of the calls in the Security plugins. They are used to return an error code and message. Table 12 – SecurityException class SecurityException Attributes code SecurityExceptionCode minor_code long message String
- 52. 42 DDS Security v1.0 Beta1 8.3 Authentication Plugin The Authentication Plugin SPI defines the types and operations necessary to support the authentication of DDS DomainParticipants. 8.3.1 Background (Non-Normative) Without the security enhancements, any DDS DomainParticipant is allowed to join a DDS Domain without authenticating. However, in the case of a secure DDS system, every DDS participant will be required to authenticate to avoid data contamination from unauthenticated participants. The DDS protocol uses its native discovery mechanism to detects when participants enter the DDS Domain. The discovery mechanism that registers participants with the DDS middleware is enhanced with an authentication protocol. For protected DDS Domains a DomainParticipant that enables the authentication plugin will only communicate with another DomainParticipant that has the authentication plugin enabled. The plugin SPI is designed to support multiple implementations with varying numbers of message exchanges. The message exchanges may be used by two DomainParticipant entities to challenge each other so that their identity can be authenticated. Often a shared secret is also derived from a successful authentication message exchange. The shared secret can be used to exchange cryptographic materal in support encryption and message authentication. 8.3.2 Authentication Plugin Model The Authentication Plugin model is presented in the figure below.
- 53. DDS Security v1.0 Beta 1 43 class Authentication SecurityPlugin «interface» Authentication + validate_local_identity() :ValidationResult_t + get_identity_token() :Boolean + set_permissions_credential_and_token() :Boolean + validate_remote_identity() :ValidationResult_t + begin_handshake_request() :ValidationResult_t + begin_handshake_reply() :ValidationResult_t + process_handshake() :ValidationResult_t + get_shared_secret() :SharedSecretHandle + get_peer_permissions_credential_token() :Boolean + set_listener() :Boolean + return_identity_token() :Boolean + return_peer_permissions_credential_token() :Boolean + return_handshake_handle() :Boolean + return_identity_handle() :Boolean + return_sharedsecret_handle() :Boolean «primitive» IdentityHandle «interface» AuthenticationListener + revoke_identity() :Boolean Token «discovery» IdentityToken Credential IdentityCredential Token MessageToken «primitive» HandshakeHandle «primitive» SharedSecretHandle Token PermissionsCredentialToken «create» «create» «create» «use» «create» «create» Figure 9 – Authentication plugin model 8.3.2.1 IdentityCredential The IdentityCredential encodes the identity information of a DomainParticipant in a manner that can be communicated to the Authentication plugin to verify the identity of a local DomainParticipant. The IdentityCredential is only used as part of local operations that occur within a single process boundary. The specific content of the IdentityCredential shall be defined by each Authentication plugin specialization and it may not be used by some Authentication plugin specializations. The interpretation of the contents as well as the mechanism used to pass it to the Authentication plugin shall be specified by each plugin implementation.
- 54. 44 DDS Security v1.0 Beta1 8.3.2.2 IdentityToken An IdentityToken contains summary information on the identity of a DomainParticipant in a manner that can be externalized and propagated via DDS discovery. The specific content of the IdentityToken shall be defined by each Authentication plugin specialization. The intent is to provide only summary information on the permissions or derived information such as a hash. 8.3.2.3 IdentityCredentialToken An IdentityCredentialToken contains information on the identity of a DomainParticipant in a manner that can be externalized and send over the network. The IdentityCredentialToken may be exchanged by the DomainParticipant entities as part of the authentication handshake. The specific content of the IdentityCredentialToken shall be defined by each Authentication plugin specialization. 8.3.2.4 IdentityHandle An IdentityHandle is an opaque local reference to internal state within the Authentication plugin, which uniquely identifies a DomainParticipant. It is understood only by the Authentication plugin and references the authentication state of the DomainParticipant. This object is returned by the Authentication plugin as part of the validation of the identity of a DomainParticipant and is used whenever a client of the Authentication plugin needs to refer to the identity of a previously identified DomainParticipant. 8.3.2.5 HandshakeHandle A HandshakeHandle is an opaque local reference used to refer to the internal state of a possible mutual authentication or handshake protocol. 8.3.2.6 HandshakeMessageToken A HandshakeMessageToken encodes plugin-specific information that the Authentication plugins associated with two DomainParticipant entities exchange as part of the mutual authentication handshake. The HandshakeMessageToken are understood only by the AuthenticationPlugin implementations on either side of the handshake. The HandshakeMessageToken are sent and received by the DDS implementation under the direction of the AuthenticationPlugins. 8.3.2.7 SharedSecretHandle A SharedSecretHandle is an opaque local reference to internal state within the AuthenticationPlugin containing a secret that is shared between the AuthenticationPlugin implementation and the peer AuthenticationPlugin implementation associated with a remote DomainParticipant. It is understood only by the two AuthenticationPlugin implementations that share the secret. The shared secret is used to encode Tokens, such as the CryptoToken, such that they can be exchanged between the two DomainParticipants in a secure manner.
- 55. DDS Security v1.0 Beta 1 45 8.3.2.8 Authentication This interface is the starting point for all the security mechanisms. When a DomainParticipant is either locally created or discovered, it needs to be authenticated in order to be able to communicate in a DDS Domain. The interaction between the DDS implementation and the Authentication plugin has been designed in a flexible manner so it is possible to support various authentication mechanisms, including those that require a handshake and/or perform mutual authentication between participants. It also supports the establish a shared secret. This interaction is described in the state machine illustrated in the figure below. stm AuthBehavior HandshakeInit HandshakeInitReply Choice Initialized EntryPoint Validation_OK Validation_Failed HandshakeMessageSend Choice HandshakeCompletedOK HandshakeMessageWait HandshakeInitMessageWait HandshakeFinalMessage HandshakeMessageReceived [VALIDATION_FAILED] begin_handshake_reply() [VALIDATION_PENDING_HANDSHAKE_REQUEST] [VALIDATION_PENDING_HANDSHAKE_MESSAGE] [VALIDATION_OK] [VALIDATION_FAILED] validate_remote_identity() begin_handshake_request() DDS::send_message() process_handshake() [VALIDATION_OK] [VALIDATION_PENDING_HANDSHAKE_MESSAGE] [VALIDATION_OK_WITH_FINAL_MESSAGE] get_shared_secret() DDS::receive_message() DDS::receive_message() DDS::send_message() validate_local_identity() Figure 10 – Authentication plugin interaction state machine 8.3.2.8.1 Reliability of the Authentication Handshake In order to be sufficiently robust to avert sequence number attacks (7.4.3.1), the Authentication Handshake uses the BuiltinParticipantStatelessMessageWriter and BuiltinParticipantStatelessMessageReader endpoints (7.4.3) with GenericMessageClassId set to GMCLASSID_SECURITY_AUTH_HANDSHAKE (7.4.3.5). These stateless endpoints send messages best-effort without paying attention to any sequence number information to remove
- 56. 46 DDS Security v1.0 Beta1 duplicates or attempt ordered delivery. Despite this, the Authentication Handshake needs to be able to withstand the message loss that may occur on the network. In order to operate robustly in the presence of message loss and sequence number attacks DDS Security implementations shall follow the rules below: 1. The DDS security implementation shall pass to the AuthenticationPlugin any message received by the BuiltinParticipantStatelessMessageReader that has a GenericMessageClassId set to GMCLASSID_SECURITY_AUTH_HANDSHAKE. 2. Any time the state-machine indicates that a message shall be sent using the BuiltinParticipantStatelessMessageWriter and a reply message needs to be received by the BuiltinParticipantStatelessMessageReader, the DDS implementation shall cache the message that was sent and set a timer. If a correct reply message is not received when the timer expires, the BuiltinParticipantStatelessMessager shall send the same message again. This process shall be repeated multiple times until a correct message is received. 3. Whenever a message is sent using the BuiltinParticipantStatelessMessageWriter, a reply message is received by the BuiltinParticipantStatelessMessageReader. The reply is then passed to the AuthenticationPlugin. If the plugin operation returns VALIDATION_NOT_OK, the implementation transitions back to the previous state that caused the message to be sent and resends the same message. Rule #2 makes authentication robust to message loss. Rule #3 makes authentication robust to an attacker trying to disrupt an authentication exchange by sending bad replies. Example application of rule #2: Assume the DDS implementation transitioned to the HandshakeMessageSend state, sent the message M1 and is now in the HandshakeMessageWait state waiting for the reply. If not reply is received within an implementation-specific retry-time, the same message M1 shall be sent again and the process repeated until either a reply is received or an implementation-specific timeout elapses (or a maximum number of retries is reached). Example application of rule #3: Assume the DDS implementation transitioned to the HandshakeMessageSend state, sent the message M2, transitions to HandshakeMessageWait, receives the reply, transitions to HandshakeMessageReceived, calls process_handshake() and the operation returns VALIDATION_NOT_OK. In this situation the DDS implementation shall transition back to HandshakeMessageSend and resent M2 again. 8.3.2.9 Unauthenticated DomainParticipant entities The term “Unauthenticated” DomainParticipant entity refers to a discovered DomainParticipant that cannot be authenticated by the Authentication plugin. This can be either because they lack support for the Authentication plugin being used, have incompatible plugins, or simply fail the authentication protocol. 8.3.2.9.1 Authentication plugin interface The Authentication plugin shall have the operations shown in the table below. Table 13 – Authentication plugin interface Authentication No Attributes
- 57. DDS Security v1.0 Beta 1 47 Operations ValidationResult_t out: local_identity_handle IdentityHandle out: adjusted_participant_key BuiltinTopicKey_t credential IdentityCredential candidate_participant_key BuiltinTopicKey_t validate_local_iden tity exception SecurityException Boolean out: identity_token IdentityToken handle IdentityHandle get_identity_token exception SecurityException Boolean handle IdentityHandle permissions_credential PermissionsCredentia l permissions_token PermissionsToken set_permissions_cre dential_and_token exception SecurityException ValidationResult_t out: remote_identity_handle IdentityHandle local_identity_handle IdentityHandle remote_identity_token IdentityToken remote_participant_key BuiltinTopicKey_t validate_remote_ide ntity out: exception SecurityException ValidationResult_t out: handshake_handle HandshakeHandle out: handshake_message HandshakeMessageToke n initiator_identity_handle IdentityHandle begin_handshake_req uest replier_identity_handle IdentityHandle
- 58. 48 DDS Security v1.0 Beta1 exception SecurityException ValidationResult_t out: handshake_handle HandshakeHandle out: handshake_message_out HandshakeMessageToke n handshake_message_in HandshakeMessageToke n initiator_identity_handle IdentityHandle replier_identity_handle IdentityHandle begin_handshake_rep ly out: exception SecurityException ValidationResult_t out: handshake_message_out HandshakeMessageToke n handshake_message_in HandshakeMessageToke n handshake_handle HandshakeHandle process_handshake out: exception SecurityException SharedSecretHandle handshake_handle HandshakeHandle get_shared_secret out: exception SecurityException Boolean out: permissions_credential_to ken PermissionsCredentia lToken handshake_handle HandshakeHandle get_peer_permission s_credential_token out: exception SecurityException Boolean listener AuthenticationListen er set_listener out: exception SecurityException Boolean token IdentityToken return_identity_tok en out: exception SecurityException
- 59. DDS Security v1.0 Beta 1 49 Boolean permissions_redential_tok en PermissionsCredentia lToken return_peer_permiss ions_credential_tok en out: exception SecurityException Boolean handshake_handle HandshakeHandle return_handshake_ha ndle out: exception SecurityException Boolean identity_handle IdentityHandle return_identity_han dle out: exception SecurityException Boolean sharedsecret_handle SharedSecretHandle return_sharedsecret _handle out: exception SecurityException 8.3.2.9.2 Type: ValidationResult_t Enumerates the possible return values of the validate_local_identity and validate_remote_identity operations. Table 14 – Values for ValidationResult_t ValidationResult_t VALIDATION_OK Indicates the validation has succeeded VALIDATION_FAILED Indicates the validation has failed VALIDATION_PENDING_ RETRY Indicates that validation is still proceeding. The operation shall be retried at a later point in time. VALIDATION_PENDING_ HANDSHAKE_REQUEST Indicates that validation of the submitted IdentityToken requires sending a handshake message. The DDS Implementation shall call the operation begin_handshake_request and send the HandshakeMessageToken obtained from this call using the InterParticipantStatelessWriter with GenericMessageClassId set to GMCLASSID_SECURITY_AUTH_HANDSHAKE. VALIDATION_PENDING_ HANDSHAKE_MESSAGE Indicates that validation is still pending. The DDS Implementation shall wait for a message on the InterParticipantStatelessReader and, once this is received, call process_handshake to pass the information received in that message. VALIDATION_OK_FINAL _MESSAGE Indicates that validation has succeeded but the DDS Implementation shall send a final message using the InterParticipantStatelessWriter
- 60. 50 DDS Security v1.0 Beta1 with GenericMessageClassId set to GMCLASID_SECURITY_AUTH_HANDSHAKE. 8.3.2.9.3 Operation: validate_local_identity Validates the identity of the local DomainParticipant, provided by an IdentityCredential. The operation returns as an output parameter the IdentityHandle, which can be used to locally identify the local Participant to the Authentication Plugin. In addition to validating the identity, this operation also returns the DomainParticipant BuiltinTopicKey_t that shall be used by the DDS implementation to uniquely identify the DomainParticipant on the network. If an error occurs, this method shall return VALIDATION_FAILED and fill the SecurityException. The method shall return either VALIDATION_OK if the validation succeeds, or VALIDATION_FAILED if it fails, or VALIDATION_PENDING_RETRY if the verification has not finished. If VALIDATION_PENDING_RETRY has been returned, the operation shall be called again after a configurable delay to check the status of verification. This shall continue until the operation returns either VALIDATION_OK (if the validation succeeds), or VALIDATION_FAILED. This approach allows non-blocking interactions with services whose verification may require invoking remote services. Parameter (out) local_identity_handle: A handle that can be used to locally refer to the Authenticated Participant in subsequent interactions with the Authentication plugin. The nature of the handle is specific to each Authentication plugin implementation. The handle will only be meaningful if the operation returns VALIDATION_OK. Parameter (out) adjusted_participant_key: The BuiltinTopicKey_t that the DDS implementation shall use to uniquely identify the DomainParticipant on the network. The returned adjusted_participant_key shall be the one that eventually appears in the participant_key attribute of the ParticipantBuiltinTopicData sent via discovery. Parameter credential: A credential that the Authentication plugin implementation may use to validate the identity of the local DomainParticipant. The nature and configuration of the credential is specific to each Authentication plugin implementation. Parameter candidate_participant_key: The BuiltinTopicKey_t that the DDS implementation would have used to uniquely identify the DomainParticipant if the Security plugins were not enabled. 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.
- 61. DDS Security v1.0 Beta 1 51 8.3.2.9.4 Operation: validate_remote_identity Initiates the process of validating the identity of the discovered remote DomainParticipant, represented as an IdentityToken object. The operation returns the ValidationResult_t indicating whether the validation succeeded, failed, or is pending a handshake. If the validation succeeds, an IdentityHandle object is returned, which can be used to locally identify the remote DomainParticipant to the Authentication plugin. If the validation can be performed with the information passed and succeeds, the operation shall return VALIDATION_OK. If it can be performed with the information passed and it fails, it shall return VALIDATION_FAILED. The validation of a remote participant might require the remote participant to perform a handshake. In this situation, the validate_remote_identity operation shall return VALIDATION_PENDING_HANDSHAKE_REQUEST or VALIDATION_PENDING_HANDSHAKE_MESSAGE. If the operation returns VALIDATION_PENDING_HANDSHAKE_REQUEST, then the DDS implementation shall call the operation begin_handshake_request to continue the validation process. If the operation returns VALIDATION_PENDING_HANDSHAKE_MESSAGE, then the DDS implementation shall wait until it receives a InterParticipantStatelessMessage from the remote participant identified by the remote_participant_key using the contents described in 8.3.2.9.6 and then call the operation begin_handshake_reply. If an error occurs, this method shall return VALIDATION_FAILED and fill the SecurityException. Parameter remote_identity_token : A token received as part of ParticipantBuiltinTopicData, representing the identity of the remote DomainParticipant. Parameter local_identity_handle: A handle to the local DomainParticipant requesting the remote participant to be validated. The local handle shall be the result of an earlier call to validate_local_identity. Parameter (out) remote_identity_handle: A handle that can be used to locally refer to the remote Authenticated Participant in subsequent interactions with the AuthenticationPlugin. The nature of the remote_identity_handle is specific to each AuthenticationPlugin implementation. The handle will only be provided if the operation returns something other than VALIDATION_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. If this is returned, the DDS implementation shall call begin_handshake_request, to continue the validation.
- 62. 52 DDS Security v1.0 Beta1 VALIDATION_PENDING_HANDSHAKE_MESSAGE if validation has not completed. If this is returned, the DDS implementation shall wait for a message on the InterParticipantStatelessReader with the message_identity containing a source_guid that matches the remote_participant_key and a message_class_id set to GMCLASSID_SECURITY_AUTH_HANDSHAKE. VALIDATION_PENDING RETRY if the validation has not completed. If this is returned, the operation should be called again at a later point in time to check the validation status. 8.3.2.9.5 Operation: begin_handshake_request This operation is used to initiate a handshake. It shall be called by the DDS middleware solely as a result of having a previous call to validate_remote_identity returns VALIDATION_PENDING_HANDSHAKE_REQUEST. This operation returns a HandshakeMessageToken that shall be used to send a handshake to the remote participant identified by the replier_identity_handle. The contents of the HandshakeMessageToken are specified by the plugin implementation. If an error occurs, this method shall return VALIDATION_FAILED and fill the SecurityException. Parameter (out) handshake_handle: A handle returned by the Authentication plugin used to keep the state of the handshake. It is passed to other operations in the Authentication plugin. Parameter (out) handshake_message_token: A HandshakeMessageToken to be sent using the InterParticipantStatelessWriter. 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 validated. 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. If this is returned, the DDS implementation shall send the handshake_message_out using the InterParticipantStatelessWriter and then wait for the reply message on the InterParticipantStatelessReader. The DDS implementation shall set the InterParticipantStatelessMessage participantGuidPrefix message_class_id to GMCLASSID_SECURITY_AUTH_HANDSHAKE and fill the message_data with the handshake_message HandshakeMessageToken and set the destination_participant_key to match the DDS BuiltinTopicKey_t of the destination DomainParticipant. When the reply message is received the DDS implementation shall call the operation begin_handshake_reply, to continue the validation. VALIDATION_OK_FINAL_MESSAGE if the validation succeeded. If this is returned, the DDS implementation shall send the returned handshake_message using the InterParticipantStatelessReader.
- 63. DDS Security v1.0 Beta 1 53 VALIDATION_PENDING RETRY if the validation has not completed. If this is returned, the DDS implementation shall call the operation again at a later point in time to check the validation status. In the cases where the return code indicates that a message shall be sent using the InterParticipantStatelessWriter, the DDS implementation shall set the InterParticipantStatelessMessage as follows: The message_class_id shall be set to GMCLASSID_SECURITY_AUTH_HANDSHAKE. The destination_participant_key shall be set to match the DDS BuiltinTopicKey_t of the destination DomainParticipant. The message_identity shall be set to have the source_guid matching the DDS BuiltinTopicKey_t of the DomainParticipant that is sending the message and the sequence_number to the value in the previous message sent by the InterParticipantStatelessWriter, incremented by one. The related_message_identity shall be set with source_guid as GUID_UNKNOWN and sequence_number to zero. The message_data shall be filled with the CDR serialization of the handshake_message HandshakeMessageToken. 8.3.2.9.6 Operation: begin_handshake_reply This operation shall be invoked by the DDS implementation in reaction to the reception of the initial handshake message that originated on a DomainParticipant that called the begin_handshake_request operation. It shall be called by the DDS implementation solely as a result of having a previous call to validate_remote_identity returns VALIDATION_PENDING_HANDSHAKE_MESSAGE and having received a message on the InterParticipantStatelessReader with attributes set as follows: message_class_id GMCLASSID_SECURITY_AUTH_HANDSHAKE message_identity source_guid matching the BuiltinTopicKey_t of the DomainParticipant associated with the initiator_identity_handle destination_participant_key matching the BuiltinTopicKey_t of the receiving DomainParticipant This operation generates a handshake_message_out in response to a received handshake_message_in. Depending on the return value of the operation, the DDS implementation shall send the handshake_message_out using the InterParticipantStatelessWriter to the participant identified by the initiator_identity_handle. The contents of the handshake_message_out HandshakeMessageToken are specified by the plugin implementation. If an error occurs, this method shall return VALIDATION_FAILED and fill the SecurityException. Parameter (out) handshake_handle: A handle returned by the Authentication Plugin used keep the state of the handshake. It is passed to other operations in the Plugin. Parameter (out) handshake_message_out: A HandshakeMessageToken containing a message to be sent using the InterParticipantStatelessWriter. The contents shall be specified by each plugin implementation.
- 64. 54 DDS Security v1.0 Beta1 Parameter handshake_message_in: A HandshakeMessageToken containing a message received from the InterParticipantStatelessReader. The contents shall be specified by each plugin implementation. Parameter initiator_identity_handle: Handle to the remote participant that originated the handshake. Parameter replier_identity_handle: Handle to the local participant that is initiating the handshake response. Parameter exception: A SecurityException object. Return: The operation shall return: VALIDATION_OK if the validation was successful. VALIDATION_FAILED if it failed. VALIDATION_PENDING_HANDSHAKE_MESSAGE if validation has not completed. If this is returned, the DDS implementation shall send the handshake_message_out using the InterParticipantStatelessWriter and then wait for a reply message on the InterParticipantStatelessReader from that remote DomainParticipant. VALIDATION_OK_FINAL_MESSAGE if the validation succeeded. If this is returned, the DDS implementation shall send the returned handshake_message_out using the InterParticipantStatelessWriter. VALIDATION_PENDING RETRY if the validation has not completed. If this is returned, the DDS implementation shall call the operation again at a later point in time to check the validation status. In cases where the return code indicates that a message shall be sent using the InterParticipantStatelessWriter, the DDS implementation shall set the InterParticipantStatelessMessage as follows: The message_class_id shall be set to GMCLASSID_SECURITY_AUTH_HANDSHAKE. The destination_participant_key shall be set to match the DDS BuiltinTopicKey_t of the destination DomainParticipant. The message_identity shall be set to have the source_guid matching the DDS BuiltinTopicKey_t of the DomainParticipant that is sending the message and the sequence_number to the value in the previous message sent by the InterParticipantStatelessWriter, incremented by one. The related_message_identity shall be set to match the message_identity of the InterParticipantStatelessMessage received that triggered the execution of the begin_handshake_reply operation. The message_data shall be filled with the CDR serialization of the handshake_message_out HandshakeMessageToken. 8.3.2.9.7 Operation: process_handshake This operation is used to continue a handshake. It shall be called by the DDS middleware solely as a result of having a previous call to begin_handshake_request or begin_handshake_reply that returned VALIDATION_PENDING_HANDSHAKE_MESSAGE and having also received a InterParticipantStatelessMessage on the InterParticipantStatelessReader with attributes set as follows: message_class_id GMCLASSID_SECURITY_AUTH_HANDSHAKE
- 65. DDS Security v1.0 Beta 1 55 message_identity source_guid matching the BuiltinTopicKey_t of the peer DomainParticipant associated with the handshake_handle related_message_identity matching the message_identity of the last InterParticipantStatelessMessage sent to the peer DomainParticipant associated with the handshake_handle. destination_participant_key matching the BuiltinTopicKey_t of the receiving DomainParticipant. This operation generates a handshake_message_out HandshakeMessageToken in response to a received handshake_message_in HandshakeMessageToken. Depending on the return value of the function the DDS implementation shall send the handshake_message_out using the InterParticipantStatelessWriter to the peer participant identified by the handshake_handle. The contents of the handshake_message_out HandshakeMessageToken are specified by the plugin implementation. If an error occurs, this method shall return VALIDATION_FAILED and fill the SecurityException. Parameter (out) handshake_message_out: A HandshakeMessageToken containing the message_data that should be placed in a InterParticipantStatelessMessage to be sent using the InterParticipantStatelessWriter. The contents shall be specified by each plugin implementation. Parameter handshake_message_in: The HandshakeMessageToken contained in the message_data attribute of the InterParticipantStatelessMessage received. The interpretation of the contents shall be specified by each plugin implementation. Parameter handshake_handle: Handle returned by a corresponding previous call to begin_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. If this is returned, the DDS implementation shall send an InterParticipantStatelessMessage continuing the returned handshake_message_out using the InterParticipantStatelessWriter and then wait for a reply message on the InterParticipantStatelessReader from that remote DomainParticipant. VALIDATION_OK_FINAL_MESSAGE if the validation succeeded. If this is returned, the DDS implementation shall send a InterParticipantStatelessMessage containing the returned handshake_message_out using the InterParticipantStatelessWriter but not wait for any replies. VALIDATION_PENDING RETRY if the validation has not completed. If this is returned, the DDS implementation shall call the operation again at a later point in time to check the validation status.
- 66. 56 DDS Security v1.0 Beta1 In the cases where the return code indicates that a InterParticipantStatelessMessage shall be sent using the InterParticipantStatelessWriter the DDS implementation shall set the fields of the InterParticipantStatelessMessage as follows: The message_class_id shall be set to GMCLASSID_SECURITY_AUTH_HANDSHAKE. The destination_participant_key shall be set to match the DDS BuiltinTopicKey_t of the destination DomainParticipant. The message_identity shall be set to have the source_guid matching the DDS BuiltinTopicKey_t of the DomainParticipant that is sending the message and the sequence_number to the value in the previous message sent by the InterParticipantStatelessWriter, incremented by one. The related_message_identity shall be set to match the message_identity of the InterParticipantStatelessMessage received that triggered the execution of the begin_handshake_reply operation. The message_data shall be filled with the CDR serialization of the handshake_message_out HandshakeMessageToken. 8.3.2.9.8 Operation: get_shared_secret Retrieves the SharedSecretHandle resulting with a successfully completed handshake. This operation shall be called by the DDS middleware after on each HandshakeHandle after the handshake that uses that handle completes successfully, that is after the last ‘handshake’ operation called on that handle (begin_handshake_request, begin_handshake_reply, or process_handshake) returns VALIDATION_OK or VALIDATION_OK_FINAL_MESSAGE. The retrieved SharedSecretHandle shall be used by the DDS middleware in conjunction with the CryptoKeyExchange interface of the Cryptographic Plugin to exchange cryptographic key material with other DomainParticipant entities. If an error occurs, this method shall return the NILHandle and fill the SecurityException. Parameter handshake_handle: Handle returned by a corresponding previous call to begin_handshake_request or begin_handshake_reply, which has successfully completed the handshake operations. Parameter exception: A SecurityException object. 8.3.2.9.9 Operation: get_peer_permissions_credential_token Retrieves the PermissionsCredentialToken resulting with a successfully completed authentication of a discovered DomainParticipant. This operation shall be called by the DDS middleware on each HandshakeHandle after the handshake that uses that handle completes successfully, that is after the last ‘handshake’ operation called on that handle (begin_handshake_request, begin_handshake_reply, or process_handshake) returns VALIDATION_OK or VALIDATION_OK_FINAL_MESSAGE. The retrieved PermissionsCredentialToken shall match the PermissionsCredentialToken that was set using the operation
- 67. DDS Security v1.0 Beta 1 57 set_permissions_credential_and_token on the peer DomainParticipant that completed the handshake represented by the HandshakeHandle. If an error occurs, this method shall return false and fill the SecurityException. Parameter permissions_credential_token (out): A placeholder for the returned PermissionsCredentialToken. Parameter handshake_handle: HandshakeHandle returned by a corresponding previous call to begin_handshake_request or begin_handshake_reply, which has successfully completed the handshake operations. Parameter exception: A SecurityException object. 8.3.2.9.10 Operation: get_identity_token Retrieves an IdentityToken used to represent on the network the identity of the DomainParticipant identified by the specified IdentityHandle. Parameter identity_token (out): The returned IdentityToken. Parameter handle: The handle used to locally identify the DomainParticipant for which an IdentityToken is desired. The handle must have been returned by a successful call to validate_local_identity, otherwise the operation shall return false and fill the SecurityException. Parameter exception: A SecurityException object. Return: If an error occurs, this method shall return false and fill the SecurityException. otherwise it shall return the IdentityToken. 8.3.2.9.11 Operation: set_permissions_credential_and_token Associates the PermissionsCredentialToken (see 8.4.2.3) and the PermissionsToken (see 8.4.2.2) returned by the AccessControl plugin operation get_permissions_credential_token and get_permissions_token with the local DomainParticipant identified by the IdentityHandle. This operation shall be called by the middleware after calling validate_local_identity and prior to any calls to validate_remote_identity. Parameter handle: The handle used to locally identify the DomainParticipant whose PermissionsCredential is being supplied. The handle must have been returned by a successful call to validate_local_identity, otherwise the operation shall return false and fill the SecurityException. Parameter permissions_credential_token: The PermissionsCredentialToken associated with the DomainParticipant identified by the IdentityHandle. The permissions_credential_token must have been returned by a successful call to get_permissions_credential_token, on the AccessControl plugin. Otherwise the operation shall return false and fill the SecurityException.
- 68. 58 DDS Security v1.0 Beta1 Parameter permissions_token: The PermissionsToken associated with the DomainParticipant identified by the IdentityHandle. The permissions_token must have been returned by a successful call to get_permissions_token, on the AccessControl plugin. Otherwise the operation shall return false and fill the SecurityException. Parameter exception: A SecurityException object. Return: If an error occurs, this method shall return false, otherwise it shall return true. 8.3.2.9.12 Operation: set_listener Sets the AuthenticationListener that the Authentication plugin will use to notify the DDS middleware infrastructure of events relevant to the Authentication of DDS Participants. If an error occurs, this method shall return false and fill the SecurityException. Parameter listener: An AuthenticationListener object to be attached to the Authentication object. If this argument is nil, it indicates that there shall be no listener. Parameter exception: A SecurityException object, which provides details in case the operation returns false. 8.3.2.9.13 Operation: return_identity_token Returns 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 this operation returns false. 8.3.2.9.14 Operation: return_peer_permissions_credential_token Returns the PermissionsCredentialToken object to the plugin so it can be disposed of. Parameter permissions_credential_token: A PermissionsCredentialToken issued by the plugin on a prior call to get_peer_permissions_credential_token. Parameter exception: A SecurityException object, which provides details in the case this operation returns false. 8.3.2.9.15 Operation: return_handshake_handle Returns 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 begin_hadshake_request or begin_handshake_reply. Parameter exception: A SecurityException object, which provides details in the case this operation returns false. 8.3.2.9.16 Operation: return_identity_handle Returns the IdentityHandle object to the plugin so it can be disposed of.
- 69. DDS Security v1.0 Beta 1 59 Parameter identity_handle: An IdentityHandle issued by the plugin on a prior call to validate_local_identity or validate_remote_identity. Parameter exception: A SecurityException object, which provides details in the case this operation returns false. 8.3.2.9.17 Operation: return_sharedsecret_handle Returns 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 to get_shared_secret. Parameter exception: A SecurityException object, which provides details in the case this operation returns false. 8.3.2.10 AuthenticationListener The AuthenticationListener provides the means for notifying the DDS middleware infrastructure of events relevant to the authentication of DDS DomainParticipant entities. For example, identity certificates can expire; in this situation, the AuthenticationListener shall call the AuthenticationListener to notify the DDS implementation that the identity of a specific DomainParticipant is being revoked. Table 15 – Authentication listener class AuthenticationListener No Attributes Operations Boolean plugin Authentication handle IdentityHandle on_revoke_identity exception SecurityException 8.3.2.10.1 Operation: on_revoke_identity Revokes the identity of the participant identified by the IdentityHandle. The corresponding IdentityHandle becomes invalid. As a result of this, the DDS middleware shall terminate any communications with the DomainParticipant associated with 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 Participant whose identity is being revoked.
- 70. 60 DDS Security v1.0 Beta1 8.4 Access Control Plugin The Access Control Plugin API defines the types and operations necessary to support an access control mechanism for DDS DomainParticipants. 8.4.1 Background (Non-Normative) Once a DomainParticipant is authenticated, its permissions need to be validated and enforced. Permissions or access rights are often described using an access control matrix where the rows are subjects (i.e., users), the columns are objects (i.e., resources), and a cell defines the access rights that a given subject has over a resource. Typical implementations provide either a column-centric view (i.e., access control lists) or a row-centric view (i.e., a set of capabilities stored with each subject). With the proposed AccessControl SPI, both approaches can be supported. Before we can describe the access control plugin SPI, we need to define the permissions that can be attached to a DomainParticipant. Every DDS application uses a DomainParticipant to access or produce information on a Domain; hence the DomainParticipant has to be allowed to run in a certain Domain. Moreover, a DomainParticipant is responsible for creating DataReaders and DataWriters that communicate over a certain Topic. Hence, a DomainParticipant has to have the permissions needed to create a Topic, to publish through its DataWriters certain Topics, and to subscribe via its DataReaders to certain Topics. There is a very strong relationship between the AccessControl plugin and the Cryptographic plugin because encryption keys need to be generated for DataWriters based on the DomainParticipant’s permissions. 8.4.2 AccessControl Plugin Model The AccessControl plugin model is presented in the figure below.
- 71. DDS Security v1.0 Beta 1 61 class AccessControl SecurityPlugin «interface» AccessControl + validate_local_permissions() :PermissionsHandle + validate_remote_permissions() :PermissionsHandle + check_create_participant() :Boolean + check_create_datawriter() :Boolean + check_create_datareader() :Boolean + check_create_topic() :Boolean + check_local_datawriter_register_instance() :Boolean + check_local_datawriter_dispose_instance() :Boolean + check_remote_participant() :Boolean + check_remote_datawriter() :Boolean + check_remote_datareader() :Boolean + check_remote_topic() :Boolean + check_local_datawriter_match() :Boolean + check_local_datareader_match() :Boolean + check_remote_datawriter_register_instance() :Boolean + check_remote_datawriter_dispose_instance() :Boolean + get_permissions_token() :Boolean + get_permissions_credential_token() :Boolean + get_participant_sec_attributes() :Boolean + get_endpoint_sec_attributes() :Boolean + set_listener() :Boolean + return_permissions_token() :Boolean + return_permissions_credential_token() :Boolean «primitive» PermissionsHandle «interface» AccessControlListener + revoke_persimissions() :Boolean Token «discovery» PermissionsToken Credential PermissionsCredential «primitive» IdentityHandle ParticipantSecurityAttributes + is_access_protected :Boolean + is_rtps_protected :Boolean EndpointSecurityAttributes + ia_access_protected :Boolean + is_discovery_protected :Boolean + is_submessage_protected :Boolean + is_payload_protected :Boolean «create» «create» «use» «use» «create» «create» Figure 11 – AccessControl Plugin Model 8.4.2.1 PermissionsCredential The PermissionsCredential encodes the permissions and access information for a DomainParticipant in a manner that can be communicated to the AccessControl plugin to verify the permissions of a local DomainParticipant and perform all the access-control decisions related to the local DomainParticipant, including determining whether it can join a domain, create local DataWriters or DataReaders, etc. The PermissionsCredential is only used as part of local operations that occur within a single process boundary. The specific content of the PermissionsCredential shall be defined by each AccessControl plugin specialization and it may not be used by some AccessControl plugin
- 72. 62 DDS Security v1.0 Beta1 specializations. The interpretation of the contents as well as the mechanism used to pass it to the AccessControl plugin shall be specified by each plugin implementation. 8.4.2.2 PermissionsToken A PermissionsToken contains summary information on the permissions for a DomainParticipant in a manner that can be externalized and propagated over DDS discovery. The specific content of the PermissionsToken shall be defined by each AccessControlPlugin specialization. The intent is to provide only summary information on the permissions or derived information such as a hash. 8.4.2.3 PermissionsCredentialToken A PermissionsCredentialToken encodes the permissions and access information for a DomainParticipant in a manner that can be externalized and sent over the network. The PermissionsCredential is used by the AccessControl plugin to verify the permissions of a peer DomainParticipant and perform all the access-control decisions related to that peer DomainParticipant, including determining whether it can join a domain, match specific local DataWriters or DataReaders, etc. The PermissionsCredentialToken is intended for dissemination during the authentication handshake. The specific content of the PermissionsCredentialToken shall be defined by each AccessControl plugin specialization and it may not be used by some AccessControl plugin specializations. 8.4.2.4 PermissionsHandle A PermissionsHandle is an opaque local reference to internal state within the AccessControl plugin. It is understood only by the AccessControl plugin and characterizes the permissions associated with a specific DomainParticipant. This object is returned by the AccessControl plugin as part of the validation of the permissions of a DomainParticipant and is used whenever a client of the AccessControl plugin needs to refer to the permissions of a previously validated DomainParticipant. 8.4.2.5 ParticipantSecurityAttributes The ParticipantSecurityAttributes describe how the middleware should protect the DomainParticipant. This is a structured type whose members are described in the table below: Table 16 – Description of the ParticipantSecurityAttributes Member Type Meaning allow_unauthenticated_participants allow_unauthenticated_participants
- 73. DDS Security v1.0 Beta 1 63 is_access_protected is_access_protected is_rtps_protected is_rtps_protected 8.4.2.6 EndpointSecurityAttributes The EndpointSecurityAttributes describe how the middleware shall protect the Entity. This is a structured type, whose members are described in the table below: Table 17 – Description of the EndpointSecurityAttributes Member Type Meaning access is_access_protected
- 74. 64 DDS Security v1.0 Beta1 is_discoverye_protected SEDPbuiltinPublicationsSecureWriter SEDPbuiltinPublicationsSecureReader. is_discoverye_protected SEDPbuiltinPublicationsWriter SEDPbuiltinSubscriptionsSecureWriter. is_submessage_protected is_submessage_protected is_submessage_protected is_submessage_protected is_payload_protected is_payload_protected
- 75. DDS Security v1.0 Beta 1 65 is_ payload_protected is_ payload_protected 8.4.2.7 AccessControl interface Table 18 – AccessControl Interface AccessControl No Attributes Operations PermissionsHandle auth_plugin AuthenticationPlugin identity IdentityHandle credential PermissionsCredential validate_local_permi ssions out: exception SecurityException PermissionsHandle auth_plugin AuthenticationPlugin local_identity_h andle IdentityHandle remote_identity_ handle IdentityHandle remote_permissio ns_token PermissionsToken remote_permissio ns_credential_to ken PermissionsCredentialToke n validate_remote_perm issions out: exception SecurityException Boolean permissions_hand le PermissionsHandle domain_id DomainId_t check_create_partici pant qos DomainParticipantQoS
- 76. 66 DDS Security v1.0 Beta1 out: exception SecurityException Boolean permissions_hand le PermissionsHandle domain_id DomainId_t topic_name String qos DataWriterQoS partition PartitionQosPolicy data_tag DataTag check_create_datawri ter out: exception SecurityException Boolean permissions_hand le PermissionsHandle domain_id DomainId_t topic_name String qos DataReaderQoS partition PartitionQosPolicy data_tag DataTag check_create_datarea der out: exception SecurityException Boolean permissions_hand le PermissionsHandle domain_id DomainId_t topic_name String property Properties qos TopicQoS check_create_topic out: exception SecurityException Boolean permissions_hand le PermissionsHandle writer DataWriter check_local_datawrit er_register_instance key DynamicData
- 77. DDS Security v1.0 Beta 1 67 out: exception SecurityException Boolean permissions_hand le PermissionsHandle writer DataWriter key DynamicData check_local_datawrit er_dispose_instance out: exception SecurityException Boolean permissions_hand le PermissionsHandle domain_id DomainId_t participant_data ParticipantBuiltinTopicDa taSecure check_remote_partici pant out: exception SecurityException Boolean permissions_hand le PermissionsHandle domain_id DomainId_t publication_data PublicationBuiltinTopicDa taSecure check_remote_datawri ter out: exception SecurityException Boolean permissions_hand le PermissionsHandle domain_id DomainId_t subscription_dat a SubscriptionBuiltinTopicD ataSecure out: relay_only Boolean check_remote_datarea der out: exception SecurityException Boolean permissions_hand le PermissionsHandle check_remote_topic DomainId_t domain_id
- 78. 68 DDS Security v1.0 Beta1 topic_data TopicBuiltinTopicData out: exception SecurityException Boolean writer_permissio ns_handle PermissionsHandle reader_permissio ns_handle PermissionsHandle writer_data_tag DataTag reader_data_tag DataTag check_local_datawrit er_match out: exception SecurityException Boolean reader_permissio ns_handle PermissionsHandle writer_permissio ns_handle PermissionsHandle reader_data_tag DataTag writer_data_tag DataTag check_local_dataread er_match out: exception SecurityException Boolean permissions_hand le PermissionsHandle reader DataReader publication_hand le InstanceHandle_t key DynamicData instance_handle InstanceHandle_t check_remote_datawri ter_register_instanc e out: exception SecurityException Boolean permissions_hand le PermissionsHandle reader DataReader check_remote_datawri ter_dispose_instance publication_hand le InstanceHandle_t
- 79. DDS Security v1.0 Beta 1 69 8.4.2.7.1 Operation: validate_local_permissions key DynamicData out: exception SecurityException PermissionsToken handle PermissionsHandle get_permissions_toke n exception SecurityException PermissionsCredentialToke n handle PermissionsHandle get_permissions_cred ential_token out: exception SecurityException Boolean listener AccessControlListener set_listener out: exception SecurityException Boolean token PermissionsToken return_permissions_t oken out: exception SecurityException Boolean permissions_cred ential_token PermissionsCredentialToke n return_permissions_c redential_token out: exception SecurityException Boolean permissions_hand le PermissionsHandle out: attributes ParticipantSecurityAttrib utes get_participant_sec_ attributes out: exception SecurityException Boolean permissions_hand le PermissionsHandle out: attributes EndpointSecurityAttribute s get_endpoint_sec_att ributes out: exception SecurityException
- 80. 70 DDS Security v1.0 Beta1 Validates the permissions of the local DomainParticipant, provided the PermissionsCredential. The operation returns a PermissionsHandle object, if successful. The PermissionsHandle can be used to locally identify the permissions of the local DomainParticipant to the AccessControl plugin. If an error occurs, this method shall return HandleNIL. Parameter auth_plugin: The Authentication plugin, which validated the identity of the local DomainParticipant. If this argument is nil, the operation shall return HandleNIL. Parameter identity: The IdentityHandle returned by the authentication plugin from a successful call to validate_local_identity. Parameter credential: A credential that can be used to validate the permissions of the local DomainParticipant. The nature of the credential is specific to each AccessControl plugin implementation. Parameter exception: A SecurityException object, which provides details, in case this operation returns HandleNIL. 8.4.2.7.2 Operation: validate_remote_permissions Validates the permissions of the previously authenticated remote DomainParticipant, given the PermissionsToken object received via DDS discovery and the PermissionsCredentialToken obtained as part of the authentication process. The operation returns a PermissionsHandle object, if successful. If an error occurs, this method shall return HandleNIL. Parameter auth_plugin: The Authentication plugin, which validated the identity of the remote DomainParticipant. If this argument is nil, the operation shall return HandleNIL. Parameter local_identity_handle: The IdentityHandle returned by the authentication plugin. Parameter remote_identity_handle: The IdentityHandle returned by a successful call to the validate_remote_identity operation on the Authentication plugin. Parameter remote_permissions_token: The PermissionsToken of the remote DomainParticipant received via DDS discovery inside the permissions_token member of the ParticipantBuiltinTopicData. See 7.4.1.3. Parameter remote_permissions_credential_token: The PermissionsCredentialToken of the remote DomainParticipant returned by the operation get_peer_participant_credential_token on the Authentication plugin. Parameter exception: A SecurityException object, which provides details, in case this operation returns HandleNIL. 8.4.2.7.3 Operation: check_create_participant Enforces the permissions of the local DomainParticipant. When the local DomainParticipant is created, its permissions must allow it to join the DDS Domain specified
- 81. DDS Security v1.0 Beta 1 71 by the domain_id. Optionally the use of the specified value for the DomainParticipantQoS must also 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 local DomainParticipant. If this argument is nil, the operation shall return false. Parameter domain_id: The domain id where the local DomainParticipant is about to be created. If this argument is nil, the operation shall return false. Parameter qos: The QoS policies of the local DomainParticipant. If this argument is nil, the operation shall return false. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.4 Operation: check_create_datawriter Enforces the permissions of the local DomainParticipant. When the local DomainParticipant creates a DataWriter for topic_name with the specified DataWriterQos associated with the data_tag, its permissions must allow this. The operation returns a Boolean object. If an error occurs, this method shall return false. Parameter permissions_handle: The PermissionsHandle object associated with the local DomainParticipant. If this argument is nil, the operation shall return false. Parameter domain_id: The DomainId_t of the local DomainParticipant to which the local DataWriter will belong. Parameter topic_name: The topic name that the DataWriter is supposed to write. If this argument is nil, the operation shall return false. Parameter qos: The QoS policies of the local DataWriter. If this argument is nil, the operation shall return false. Parameter partition: The PartitionQosPolicy of the local Publisher to which the DataWriter will belong. Parameter data_tag: The data tags that the local DataWriter is requesting to be associated 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 operation returns false. 8.4.2.7.5 Operation: check_create_datareader Enforces the permissions of the local DomainParticipant. When the local DomainParticipant creates a DataReader for a Topic for topic_name with the specified DataReaderQos qos associated with the data_tag, its permissions must allow this. The operation returns a Boolean value.
- 82. 72 DDS Security v1.0 Beta1 If an error occurs, this method shall return false. Parameter permissions_handle: The PermissionsHandle object associated with the local DomainParticipant. If this argument is nil, the operation shall return false. Parameter domain_id: The DomainId_t of the local DomainParticipant to which the local DataReader will belong. Parameter topic_name: The topic name that the DataReader is supposed to read. If this argument is nil, the operation shall return false. Parameter qos: The QoS policies of the local DataReader. If this argument is nil, the operation shall return false. Parameter partition: The PartitionQosPolicy of the local Subscriber to which the DataReader will belong. Parameter data_tag: The data tags that the local DataReader is requesting read access to. This argument can be nil if it is not considered for access control. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.6 Operation: check_create_topic Enforces the permissions of the local DomainParticipant. When an entity of the local DomainParticipant creates a Topic with topic_name and TopicQos qos its permissions must 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 local DomainParticipant. If this argument is nil, the operation shall return false. Parameter domain_id: The DomainId_t of the local DomainParticipant that creates the Topic. Parameter topic_name: The topic name to be created. 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 shall return false. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.7 Operation: check_local_datawriter_register_instance Enforces the permissions of the local DomainParticipant. In case the access control requires a finer granularity at the instance level, this operation enforces the permissions of the local DataWriter. The key identifies the instance being registered and permissions are checked to determine if registration of the specified instance is allowed. The operation returns a Boolean value. If an error occurs, this method shall return false.
- 83. DDS Security v1.0 Beta 1 73 Parameter permissions_handle: The PermissionsHandle object associated with the local DomainParticipant. If this argument is nil, the operation shall return false. Parameter writer: DataWriter object that registers the instance. If this argument is nil, the operation shall return false. Parameter key: The key of the instance for which the registration permissions are being checked. If this argument is nil, the operation shall return false. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.8 Operation: check_local_datawriter_dispose_instance Enforces the permissions of the local DomainParticipant. In case the access control requires a finer granularity at the instance level, this operation enforces the permissions of the local DataWriter. The key has to match the permissions for disposing an instance. The operation returns a Boolean object. If an error occurs, this method shall return false. Parameter permissions_handle: The PermissionsHandle object associated with the local DomainParticipant. If this argument is nil, the operation shall return false. Parameter writer: DataWriter object that registers the instance. If this argument is nil, the operation shall return false. Parameter key: The key identifies the instance being registered and the permissions are checked to determine if disposal of the specified instance is allowed. If this argument is nil, the operation shall return false. Parameter exception: A SecurityException object, which provides details in case this operation returns nil. 8.4.2.7.9 Operation: check_remote_participant Enforces the permissions of the remote DomainParticipant. When the remote DomainParticipant is discovered, the domain_id and, optionally, the DomainParticipantQoS are checked 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 remote DomainParticipant. If this argument is nil, the operation shall return false. Parameter domain_id: The domain id where the remote DomainParticipant is about to be created. If this argument is nil, the operation shall return false. Parameter participant_data: The ParticipantBuiltInTopicDataSecure object associated with the remote DomainParticipant. If this argument is nil, the operation shall return false. Parameter exception: A SecurityException object, which provides details in case this operation returns nil.
- 84. 74 DDS Security v1.0 Beta1 8.4.2.7.10 Operation: check_remote_datawriter Enforces the permissions of a remote DomainParticipant. This operation shall be called by a DomainParticipant prior to matching a local DataReader belonging to that DomainParticipant with a DataWriter belonging to a different (peer) DomainParticipant. This operation shall also be called whenever a DomainParticipant detects a QoS change for a DataWriter belonging to a different (peer) DomainParticipant that is matched with a local DataReader. This operation verifies that the peer DomainParticipant has the permissions necessary to publish data on the DDS Topic with name topic_name using the DataWriterQoS that appears in publication_data. The operation returns a Boolean value. If an error occurs, this method shall return false. Parameter permissions_handle: The PermissionsHandle object associated with the remote DomainParticipant. If this argument is nil, the operation shall return false. Parameter publication_data: The PublicationBuiltInTopicDataSecure object associated with the remote DataWriter. If this argument is nil, the operation shall return false. Parameter subscriber_partition: The PartitionQosPolicy of the local Subscriber that contains the local DataReader that is matched with the remote DataWriter. Parameter subscription_data_tag: The data tags associated with the local DataReader. This argument can be nil if it is not considered for access control. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.11 Operation: check_remote_datareader Enforces the permissions of a remote DomainParticipant. This operation shall be called by a DomainParticipant prior to matching a local DataWriter belonging to that DomainParticipant with a DataReader belonging to a different (peer) DomainParticipant. This operation shall also be called whenever a DomainParticipant detects a QoS change for a DataReader belonging to a different (peer) DomainParticipant that is matched with a local DataWriter. This operation verifies that the peer DomainParticipant has the permissions necessary to subscribe to data on the DDS Topic with name topic_name using the DataReaderQoS that appears in subscription_data. The operation returns a Boolean value and also sets the relay_only output parameter. If the operation returns true, the DDS middleware shall allow the local DataWriter to match with the remote DataReader, if it returns false, it shall not allow it.
- 85. DDS Security v1.0 Beta 1 75 If the operation returns true, the relay_only parameter shall be remembered by the DDS middleware and passed to the register_matched_remote_datareader operation on the CryptoKeyFactory. If an error occurs, this method shall return false. Parameter permissions_handle: The PermissionsHandle object associated with the local DomainParticipant. If this argument is nil, the operation shall return false. Parameter subscription_data: The SubscriptionBuiltInTopicDataSecure object associated with the remote DataReader. If this argument is nil, the operation shall return false. Parameter publisher_partition: The PartitionQosPolicy of the local Publisher that contains the local DataWriter that is matched with the remote DataReader. Parameter data_tag: The data tag that the remote DataReader is about to read. This argument can be nil if it is not considered for access control. Parameter (out) relay_only: Boolean indicating whether the permissions of the remote DataReader are restricted to relaying the information (understanding sequence numbers and other SubmessageHeader information) but not decoding the data itself. This parameter is only meaningful if the operation returns true. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.12 Operation: check_remote_topic Enforces the permissions of the remote DomainParticipant. When the remote DomainParticipant creates a certain topic, the topic_name and optionally the TopicQoS extracted from the topic_data are verified to ensure the remote DomainParticipant permissions allow 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 remote DomainParticipant. If this argument is nil, the operation shall return false. Parameter topic_data: The TopicBuiltInTopicData object associated with the Topic. If this argument is nil, the operation shall return false. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.13 Operation: check_local_datawriter_match Provides the means for the AccessControl plugin to enforce access control rules that are based on the DataTag associated with DataWriter and a matching DataReader. The operation shall be called for any local DataWriter that matches a DataReader. The operation shall be called after the operation check_local_datawriter has been called on the local
- 86. 76 DDS Security v1.0 Beta1 DataWriter and either check_local_datareader or check_remote_datareader has been called on the DataReader. This operation shall also be called when a local DataWriter, matched with a DataReader, detects a change on the Qos of the DataReader. The operation shall be called only if the aforementioned calls to check_local_datawriter and check_local_datareader or check_remote_datareader are returned successfully. The operation returns a Boolean value. If an error occurs, this method shall return false and the SecurityException filled. Parameter writer_permissions_handle: The PermissionsHandle object associated with the DomainParticipant that contains the local DataWriter. If this argument is nil, the operation shall return false. Parameter reader_permissions_handle: The PermissionsHandle object associated with the remote DomainParticipant. If this argument is nil, the operation shall return false. Parameter writer_data_tag: The DataTag associated with the local DataWriter. Parameter reader_data_tag: The DataTag associated with the matched DataReader. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.14 Operation: check_local_datareader_match Provides the means for the AccessControl plugin to enforce access control rules that are based on the DataTag associated with a DataReader and a matching DataWriter. The operation shall be called for any local DataReader that matches a DataWriter. The operation shall be called after the operation check_local_datareader has been called on the local DataReader and either check_local_datawriter or check_remote_datawriter has been called on the DataWriter. This operation shall also be called when a local DataReader, matched with a DataWriter, detects a change on the Qos of the DataWriter. The operation shall be called only if the aforementioned calls to check_local_datareader and check_local_datawriter or check_remote_datarwriter are returned successfully. The operation returns a Boolean value. If an error occurs, this method shall return false and the SecurityException filled. Parameter writer_permissions_handle: The PermissionsHandle object associated with the DomainParticipant that contains the local DataReader. If this argument is nil, the operation shall return false. Parameter reader_permissions_handle: The PermissionsHandle object associated with the remote DomainParticipant. If this argument is nil, the operation shall return false. Parameter writer_data_tag: The DataTag associated with the local DataWriter.
- 87. DDS Security v1.0 Beta 1 77 Parameter reader_data_tag: The DataTag associated with the matched DataReader. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.15 Operation: check_remote_datawriter_register_instance Enforces the permissions of the remote DomainParticipant. In case the access control requires a finer granularity at the instance level, this operation enforces the permissions of the remote DataWriter. The key has to match the permissions for registering an instance. The operation returns a Boolean value. If an error occurs, this method shall return false. Parameter permissions_handle: The PermissionsHandle object associated with the remote DomainParticipant. If this argument is nil, the operation shall return false. Parameter reader: The local DataReader object that is matched to the remote DataWriter that registered an instance. Parameter publication handle: Handle that identifies the remote DataWriter . Parameter key: The key of the instance that needs to match the permissions for registering an instance. If this argument is nil, the operation shall return false. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.16 Operation: check_remote_datawriter_dispose_instance Enforces the permissions of the remote DomainParticipant. In case the access control requires a finer granularity at the instance level, this operation enforces the permissions of the remote DataWriter. The key has to match the permissions for disposing an instance. The operation returns a Boolean value. If an error occurs, this method shall return false. Parameter permissions_handle: The PermissionsHandle object associated with the remote DomainParticipant. If this argument is nil, the operation shall return false. Parameter reader: The local DataReader object that is matched to the Publication that disposed 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 disposing an instance. If this argument is nil, the operation shall return false. Parameter exception: A SecurityException object, which provides details in case this operation returns false.
- 88. 78 DDS Security v1.0 Beta1 8.4.2.7.17 Operation: get_permissions_token Retrieves a PermissionsToken object. The PermissionsToken is propagated via DDS discovery to summarize the permissions of the DomainParticipant identified by the specified PermissionsHandle . If an error occurs, this method shall return false. Parameter permissions_token (out): The returned PermissionsToken Parameter handle: The handle used to locally identify the permissions of the DomainParticipant for which 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 operation returns false. 8.4.2.7.18 Operation: get_permissions_credential_token Retrieves a PermissionsCredentialToken object that can be used to represent on the network the pemissions of the DomainParticipant identified by the specified PermissionsHandle. If an error occurs, this method shall return false. Parameter permissions_credential_token (out): The returned PermissionsCredentialToken. Parameter handle: The PermissionsHandle used to locally identify the permissions of the DomainParticipant for which a PermissionsCredentialToken is desired. If this argument is nil, the operation shall return nil. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.19 Operation: set_listener Sets the listener for the AccessControl plugin. If an error occurs, this method shall return false. Parameter listener: An AccessControlListener object to be attached to the AccessControl plugin. If this argument is nil, the operation returns false. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.20 Operation: return_permissions_token Returns the PermissionsToken to the plugin for disposal. Parameter token: A PermissionsToken to be disposed of. It should correspond to the PermissionsToken returned by a prior call to get_permissions_token on the same plugin. Parameter exception: A SecurityException object, which provides details in case this operation returns false.
- 89. DDS Security v1.0 Beta 1 79 8.4.2.7.21 Operation: return_permissions_credential_token Returns the PermissionsCredentialToken to the plugin for disposal. Parameter permissions_credential_token: A PermissionsCredentialToken to be disposed of. It should correspond to the PermissionsCredentialToken returned by a prior call to get_permissions_credential_token on the same plugin. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.4.2.7.22 Operation: get_participant_sec_attributes Retrieves the ParticipantSecurityAttributes, which describe how the DDS middleware should enforce the security and integrity of the information produced and consumed via the DomainParticipant. 8.4.2.7.23 Operation: get_endpoint_sec_attributes Retrieves the EndpointSecurityAttributes, which describe how the DDS middleware should enforce the security and integrity of the information related to the endpoint: DDS DataReader or DDS DataWriter. 8.4.2.8 AccessControlListener interface The purpose of the AccessControlListener is to be notified of all status changes for different identities. For example, permissions can change; hence, the AccessControlListener is notified and enforces the new permissions. Table 19 – AccessControlListener interface AccessControlListener No Attributes Operations Boolean plugin AccessControl on_revoke_permissions handle PermissionsHandle 8.4.2.8.1 Operation: on_revoke_permissions DomainParticipants’ Permissions can be revoked/changed. This listener provides a callback for 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 DDS Participant whose permissions are being revoked.
- 90. 80 DDS Security v1.0 Beta1 8.5 Cryptographic Plugin The Cryptographic plugin defines the types and operations necessary to support encryption, digest, message authentication codes, and key exchange for DDS DomainParticipants, DataWriters and DDS DataReaders. Users of DDS may have specific cryptographic libraries they use for encryption, as well as, specific requirements regarding the algorithms for digests, message authentication, and signing. In addition, applications may require having only some of those functions performed, or performed only for certain DDS Topics and not for others. Therefore, the plugin API has to be general enough to allow flexible configuration and deployment scenarios. 8.5.1 Cryptographic Plugin Model The Cryptographic plugin model is presented in the figure below. It combines related cryptographic interfaces for key creation, key exchange, encryption, message authentication, hashing, and signature. class Cryptographic «interface» Cryptographic «interface» CryptoKeyFactory + register_local_participant() :ParticipantCryptoHandle + register_matched_remote_participant() :ParticipantCryptoHandle + register_local_datawriter() :DatawriterCryptoHandle + register_matched_remote_datareader() :DatareaderCryptoHandle + register_local_datareader() :DatareaderCryptoHandle + register_matched_remote_datawriter() :DatawriterCryptoHandle + unregister_participant() :Boolean + unregister_datawriter() :Boolean + unregister_datareader() :Boolean «primitive» ParticipantCryptoHandle «primitive» DatawriterCryptoHandle «primitive» DatareaderCryptoHandle «interface» CryptoKeyExchange + create_local_participant_crypto_tokens() :Boolean + set_remote_participant_crypto_tokens() :Boolean + create_local_datawriter_crypto_tokens() :Boolean + set_remote_datawriter_crypto_tokens() :Boolean + create_local_datareader_crypto_tokens() :Boolean + set_remote_datareader_crypto_tokens() :Boolean + return_cypto_tokens() :Boolean «interface» CryptoTransform + encode_serialized_data() :Boolean + encode_datawriter_submessage() :Boolean + encode_datareader_submessage() :Boolean + encode_rtps_message() :Boolean + decode_rtps_message() :Boolean + preprocess_rtps_submessage() :Boolean + decode_datawriter_submessage() :Boolean + decode_datareader_submessage() :Boolean + decode_serialized_data() :Boolean Token CryptoToken «primitive» IdentityHandle «primitive» PermissionsHandle «dataType» CryptoTransformIdentifier - transformation_kind_id :octet[4] - transformation_key_id :octet[8] «primitive» SharedSecretHandle Figure 12 – Cryptographic Plugin Model 8.5.1.1 CryptoToken This class represents a generic holder for key material. A CryptoToken object contains all the information necessary to construct a set of keys to be used to encrypt and/or sign plain text transforming it into cipher-text or to reverse those operations.
- 91. DDS Security v1.0 Beta 1 81 The format and interpretation of the CryptoToken depends on the implementation of the Cryptographic plugin. Each plugin implementation shall fully define itself, so that applications are able to interoperate. In general, the CryptoToken will contain one or more keys and any other necessary material to perform crypto-transformation and/or verification, such as, initialization vectors (IVs), salts, etc. 8.5.1.2 ParticipantCryptoHandle The ParticipantCryptoHandle object is an opaque local reference that represents the key material used to encrypt and sign whole RTPS Messages. It is used by the operations encode_rtps_message and decode_rtps_message. 8.5.1.3 DatawriterCryptoHandle The DatawriterCryptoHandle object is an opaque local reference that represents the key material used to encrypt and sign RTPS submessages sent from a DataWriter. This includes the RTPS submessages Data, DataFrag, Gap, Heartbeat, and HeartbeatFrag, as well as, the SerializedData submessage element that appears in the Data and DataFrag submessages. It is used by the operations encode_datawriter_submessage, decode_datawriter_submessage, encode_serialized_data, and decode_serialized_data. 8.5.1.4 DatareaderCryptoHandle The DatareaderCryptoHandle object is an opaque local reference that represents the key material used to encrypt and sign RTPS Submessages sent from a DataReader. This includes the RTPS Submessages AckNack and NackFrag. It is used by the operations encode_datareader_submessage, decode_datareader_submessage. 8.5.1.5 CryptoTransformIdentifier The CryptoTransformIdentifier object used to uniquely identify the transformation applied on the sending side (encoding) so that the receiver can locate the necessary key material to perform the inverse transformation (decoding). The generation of CryptoTransformIdentifier is performed by the Cryptographic plugin. To enable interoperability and avoid misinterpretation of the key material, the structure of the CryptoTransformIdentifier is defined for all Cryptographic plugin implementations as follows: Table 20 – CryptoTranformIdentifier class CryptoTransformIdentifier Attributes transformation_kind_id octet[4] transformation_key_id octet[8]
- 92. 82 DDS Security v1.0 Beta1 8.5.1.5.1 Attribute: transformation_kind_id Uniquely identifies the type of cryptographic transformation Values of transformation_kind_id having the first two octets set to zero are reserved by this specification, including future versions of this specification. Implementers can use the transformation_kind_id attribute to identify non-standard cryptographic transformations. In order to avoid collisions, the first two octets in the transformation_kind_id shall be set to a registered RTPS VendorId [36]. The RTPS VendorId used shall either be one reserved to the implementer of the Cryptographic Plugin, or else the implementer of the Cryptographic Plugin shall secure permission from the registered owner of the RTPS VendorId to use it. 8.5.1.5.2 Attribute: transformation_key_id Uniquely identifies the key material used to perform a cryptographic transformation within the scope of all transformations that could be performed by transformations belonging to that transformation_kind_id. In combination with the transformation_kind_id, the transformation_key_id attribute allows the receiver to select the proper key material to decrypt/verify a message that has been encrypted and/or signed. The use of this attribute allows a receiver to be robust to dynamic changes in keys and key material in the sense that it can identify the correct key or at least detect that it does not have the necessary keys and key material. The values of the transformation_key_id are defined by the Cryptographic plugin implementation and understood only by that plugin. 8.5.1.6 SecureSubmessageCategory_t Enumerates the possible categories of RTPS submessages. Table 21 – SecureSubmessageCategory_t SecureSubmessageCategory_t INFO_SUBMESSAGE Indicates an RTPS Info submesage: InfoSource, InfoDestination, or InfoTimestamp. DATAWRITER_SUMBES SAGE Indicates an RTPS submessage that was sent from a DataWriter: Data, DataFrag, HeartBeat, Gap. DATAREADER_SUMBES SAGE Indicates an RTPS submessage that was sent from a DataReader: AckNack, NackFrag. 8.5.1.7 CryptoKeyFactory interface This interface groups the operations related to the creation of keys used for encryption and digital signing of both the data written by DDS applications and the RTPS submessage and message headers, used to implement the discovery protocol, distribute the DDS data, implement the reliability protocol, etc. Table 22 – CryptoKeyFactory Interface
- 93. DDS Security v1.0 Beta 1 83 CryptoKeyFactory No Attributes Operations ParticipantCryptoHandle participant_ide ntity IdentityHandle participant_per missions PermissionsHandle participant_pro perties Properties register_local_partic ipant out: exception SecurityException ParticipantCryptoHandle local_participa nt_crypto_handl e ParticipantCryptoHandle remote_particip ant_identity IdentityHandle remote_particip ant_permissions PermissionsHandle shared_secret SharedSecretHandle register_matched_remo te_participant out: exception SecurityException DatawriterCryptoHandle participant_cry pto ParticipantCryptoHandle datawriter_prop erties Properties register_local_datawr iter out: exception SecurityException DatareaderCryptoHandle local_datawrite rt_crypto_handl e DatawriterCryptoHandle remote_particip ant_crypto ParticipantCryptoHandle register_matched_remo te_datareader shared_secret SharedSecretHandle
- 94. 84 DDS Security v1.0 Beta1 8.5.1.7.1 Operation: register_local_participant Registers a local DomainParticipant with the Cryptographic Plugin. The DomainParticipant must have been already authenticated and granted access to the DDS Domain. The operation shall create any necessary key material that is needed to Encrypt and Sign secure messages that are directed to other DDS DomainParticipant entities on the DDS Domain. relay_only Boolean out: exception SecurityException DatareaderCryptoHandle participant_cry pto ParticipantCryptoHandle datareader_prop erties Properties register_local_datare ader out: exception SecurityException DatawriterCryptoHandle local_datareade r_crypto_handle DatareaderCryptoHandle remote_particip ant_crypt ParticipantCryptoHandle shared_secret SharedSecretHandle register_matched_remo te_datawriter out: exception SecurityException Boolean participant_cry pto_handle ParticipantCryptoHandle unregister_participan t out: exception SecurityException Boolean datawriter_cryp to_handle DatawriterCryptoHandle unregister_datawriter out: exception SecurityException Boolean datareader_cryp to_handle DatareaderCryptoHandle unregister_datareader out: exception SecurityException
- 95. DDS Security v1.0 Beta 1 85 Parameter participant_identity: An IdentityHandle returned by a prior call to validate_local_identity. If this argument is nil, the operation returns HandleNIL. Parameter participant_permissions: A PermissionsHandle returned by a prior call to validate_local_permissions. If this argument is nil, the operation returns HandleNIL. Parameter participant_property: The QoS properties of the local DomainParticipant (name/values pairs that can be used to configure certain parameters and are not exposed through formal QoS policies). Parameter exception: A SecurityException object, which provides details in case this operation returns HandleNIL. 8.5.1.7.2 Operation: register_matched_remote_participant Registers a remote DomainParticipant with the Cryptographic Plugin. The remote DomainParticipant must have been already Authenticated and granted Access to the DDS Domain. The operation performs two functions: 1. It shall create any necessary key material needed to decrypt and verify the signatures of messages received from that remote DomainParticipant and directed to the local DomainParticipant. 2. It shall create any necessary key material that will be used by the local DomainParticipant when encrypting or signing messages that are intended only for that remote DomainParticipant. Parameter local_participant_crypto_handle: A ParticipantCryptoHandle returned by a prior call to register_local_participant. If this argument is nil, the operation returns false. Parameter remote_participant_identity: An IdentityHandle returned by a prior call to validate_remote_identity. If this argument is nil, the operation returns nil. Parameter participant_permissions: A PermissionsHandle returned by a prior call to validate_remote_permissions. If this argument is nil, the operation returns nil Parameter shared_secret: The SharedSecretHandle returned by a prior call to get_shared_secret as a result of the successful completion of the Authentication handshake between the local and remote DomainParticipant entities. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.7.3 Operation: register_local_datawriter Registers a local DataWriter with the Cryptographic Plugin. The fact that the DataWriter was 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 its Topic. This operation shall create the cryptographic material necessary to encrypt and/or sign the data written by the DataWriter and returns a DatawriterCryptoHandle to be used for any cryptographic operations affecting messages sent or received by the DataWriter.
- 96. 86 DDS Security v1.0 Beta1 If an error occurs, this method shall return false. If it succeeds, the operation shall return an opaque handle that can be used to refer to that key material. Parameter local_participant_identity: An IdentityHandle returned by a prior call to validate_local_identity. It shall correspond to the DomainParticipant to which the DataWriter belongs. If this argument is nil, the operation returns nil. Parameter participant_crypto: A ParticipantCryptoHandle returned by a prior call to register_local_participant. It shall correspond to the ParticipantCryptoHandle of the DomainParticipant to which the DataWriter belongs. If this argument is nil, the operation returns false. Parameter local_datawriter_properties: The Properties of the local DataWriter (name/values pairs that can be used to configure certain parameters and are not exposed through formal QoS policies). This parameter shall contain all the properties in the DataWriter whose name has the prefix “dds.sec.crypto.” The purpose of this parameter is to allow configuration of the Cryptographic Plugin by the DataWriter, e.g., selection of the cryptographic algorithm, key size, or even setting of the key. The use of this parameter depends on the particular implementation of the plugin and shall be specified for each implementation. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.7.4 Operation: register_matched_remote_datareader Registers a remote DataReader with the Cryptographic Plugin. The remote DataReader shall correspond 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 RTPS submessages (Data, DataFrag, Gap, Heartbeat, HeartbeatFrag) sent from the local DataWriter to that DataReader. It shall also create the cryptographic material necessary to process RTPS Submessages (AckNack, NackFrag) sent from the remote DataReader to the DataWriter. The operation shall associate the value of the relay_only parameter with the returned DatawriterCryptoHandle. This information shall be used in the generation of the KeyToken objects to be sent to the DataReader. Parameter local_datawriter_crypto_handle: A DatawriterCryptoHandle returned by a prior call to register_local_datawriter. If this argument is nil, the operation returns HandleNIL. Parameter remote_participant_crypto: A ParticipantCryptoHandle returned by a prior call to register_matched_remote_participant. It shall correspond to the ParticipantCryptoHandle of the DomainParticipant to which the remote DataReader belongs. If this argument is nil, the operation returns HandleNIL. Parameter remote_participant_permissions: A PermissionsHandle returned by a prior call to validate_remote_permissions. It shall correspond to the DomainParticipant to which the DataReader belongs. If this argument is nil, the operation returns HandleNIL
- 97. DDS Security v1.0 Beta 1 87 Parameter shared_secret: The SharedSecretHandle returned by a prior call to get_shared_secret as a result of the successful completion of the Authentication handshake between the local and remote DomainParticipant entities. Parameter (out) relay_only: Boolean indicating whether the cryptographic material to be generated for the remote DataReader shall contain everything, or only the material necessary to relay (store and forward) the information (i.e., understand the SubmessageHeader) without being able to decode the data itself (i.e., decode the SecureData). Parameter exception: A SecurityException object, which provides details in case this operation returns HandleNIL. 8.5.1.7.5 Operation: register_local_datareader Registers a local DataReader with the Cryptographic Plugin. The fact that the DataReader was 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 its Topic. This operation shall create the cryptographic material necessary to encrypt and/or sign the messages sent 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 cryptographic operations affecting messages sent or received by the DataWriter. Parameter participant_crypto: A ParticipantCryptoHandle returned by a prior call to register_local_participant. It shall correspond to the ParticipantCryptoHandle of the DomainParticipant to which the DataReader belongs. If this argument is nil, the operation returns HandleNIL. Parameter local_datareader_properties: The Properties of the local DataReader (name/values pairs that can be used to configure certain parameters and are not exposed through formal QoS policies). Parameter exception: A SecurityException object, which provides details in case this operation returns HandleNIL. 8.5.1.7.6 Operation: register_matched_remote_datawriter Registers a remote DataWriter with the Cryptographic Plugin. The remote DataWriter shall 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 signatures of the RTPS submessages (Data, DataFrag, Heartbeat, HeartbeatFrag, Gap) sent from the remote DataWriter to the DataReader. The operation shall also create the cryptographic 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 a prior call to register_local_datawriter. If this argument is nil, the operation returns nil. Parameter remote_participant_crypto: A ParticipantCryptoHandle returned by a prior call to register_matched_remote_participant. It shall correspond to the
- 98. 88 DDS Security v1.0 Beta1 ParticipantCryptoHandle of the DomainParticipant to which the remote DataWriter belongs. If this argument is nil, the operation returns nil. Parameter shared_secret: The SharedSecretHandle returned by a prior call to get_shared_secret as a result of the successful completion of the Authentication handshake between the local and remote DomainParticipant entities. Parameter exception: A SecurityException object, which provides details in case this operation returns HandleNIL. 8.5.1.7.7 Operation: unregister_participant Releases the resources, associated with a DomainParticipant, that the Cryptographic plugin maintains. After calling this function, the DDS Implementation shall not use the participant_crypto_handle anymore. The DDS Implementation shall call this function when it determines that there will be no further communication with the DDS DomainParticipant associated with the participant_crypto_handle. Specifically, it shall be called when the application deletes a local DomainParticipant and also when the DDS Discovery mechanism detects that a matched DomainParticipant is no longer in the system. Parameter participant_crypto_handle: A ParticipantCryptoHandle returned by a prior call to register_local_participant, or register_matched_remote_participant if this argument is nil, the operation returns false. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.7.8 Operation: unregister_datawriter Releases the resources, associated with a DataWriter, that the Cryptographic plugin maintains. After calling this function, the DDS Implementation shall not use the datawriter_crypto_handle anymore. The DDS Implementation shall call this function when it determines that there will be no further communication 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 DDS Discovery mechanism detects that a matched DataWriter is no longer in the system. Parameter datawriter_crypto_handle: A ParticipantCryptoHandle returned by a prior call to register_local_datawriter, or register_matched_remote_datawriter if this argument is nil, the operation returns false. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.7.9 Operation: unregister_datareader Releases the resources, associated with a DataReader, that the Cryptographic plugin maintains. After calling this function, the DDS Implementation shall not use the datareader_crypto_handle anymore.
- 99. DDS Security v1.0 Beta 1 89 The DDS Implementation shall call this function when it determines that there will be no further communication 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 the DDS Discovery mechanism detects that a matched DataReader is no longer in the system. Parameter datareader_crypto_handle: A ParticipantCryptoHandle returned by a prior call to register_local_datareader, or register_matched_remote_datareader if this argument is nil, the operation returns false. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.8 CryptoKeyExchange Interface The key exchange interface manages the creation of keys and assist in the secure distribution of keys and key material. Table 23 – CryptoKeyExchange Interface CryptoKeyExchange No Attributes Operations Boolean local_participan t_crypto_tokens ParticipantCryptoTokenSeq local_participan t_crypto ParticipantCryptoHandle remote_participa nt_crypto ParticipantCryptoHandle create_local_partici pant_crypto_tokens out: exception SecurityException Boolean local_participan t_crypto ParticipantCryptoHandle remote_participa nt_crypto ParticipantCryptoHandle remote_participa nt_tokens ParticipantCryptoTokenSeq set_remote_participa nt_crypto_tokens out: exception SecurityException Boolean local_datawriter _crypto_tokens DatawriterCryptoTokenSeq create_local_datawri ter_crypto_tokens local_datawriter DatawriterCryptoHandle
- 100. 90 DDS Security v1.0 Beta1 8.5.1.8.1 Operation: create_local_participant_crypto_tokens This operation creates a sequence of CryptoToken tokens containing the information needed to correctly interpret cipher text encoded using the local_participant_crypto. That is, the CryptoToken _crypto remote_datareade r_crypto DatareaderCryptoHandle out: exception SecurityException Boolean local_datareader _crypto DatareaderCryptoHandle remote_datawrite r_crypto DatawriterCryptoHandle remote_datawrite r_tokens DatawriterCryptoTokenSeq set_remote_datawrite r_crypto_tokens out: exception SecurityException Boolean local_datareader _crypto_tokens DatareaderCryptoTokenSeq local_datareader _crypto DatareaderCryptoHandle remote_datawrite r_crypto DatawriterCryptoHandle create_local_datarea der_crypto_tokens out: exception SecurityException Boolean local_datawriter _crypto DatawriterCryptoHandle remote_datareade r_crypto DatareaderCryptoHandle remote_datareade r_tokens DatareaderCryptoTokenSeq set_remote_datareade r_crypto_tokens out: exception SecurityException Boolean crypto_tokens CryptoTokenSeq return_crypto_tokens out: exception SecurityException
- 101. DDS Security v1.0 Beta 1 91 sequence contains the information needed to decrypt any data encrypted using the local_participant_crypto, as well as, verify any signatures produced using the local_participant_crypto. The returned CryptoToken sequence contains opaque data, which only the plugins understand. The returned CryptoToken sequence is intended for transmission in “clear text” to the remote DomainParticipant associated with the remote_participant_crypto so that the remote DomainParticipant has access to the necessary key material. For this reason, the CryptoKeyExchange plugin implementation may encrypt the sensitive information inside the CryptoToken using shared secrets and keys obtained from the remote_participant_crypto. The specific ways in which this is done depend on the plugin implementation. The DDS middleware implementation shall call this operation for each remote DomainParticipant that matches a local DomainParticipant. That is, remote participants that have been successfully authenticated and granted access by the AccessControl plugin. The returned ParticipantCryptoTokenSeq shall be sent to the remote DomainParticipant using the BuiltinParticipantVolatileMessageSecureWriter with kind set to GMCLASSID_SECURITY_PARTICIPANT_CRYPTO_TOKENS (see 7.4.3.5). The returned ParticipantCryptoTokenSeq sequence shall appear in the message_data attribute of the ParticipantVolatileSecureMessage (see 7.4.4). Parameter local_participant_crypto_tokens (out): The returned ParticipantCryptoTokenSeq. Parameter local_participant_crypto: A ParticipantCryptoHandle, returned by a previous call to register_local_participant, which corresponds to the DomainParticipant that will be encrypting and signing messages. Parameter remote_participant_crypto: A ParticipantCryptoHandle, returned by a previous call to register_matched_remote_participant, that corresponds to the DomainParticipant that will be receiving the messages from the local DomainParticipant and will be decrypting them and verifying their signature. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.8.2 Operation: set_remote_participant_crypto_tokens This operation shall be called by the DDS implementation upon reception of a message on the BuiltinParticipantVolatileMessageSecureReader with kind set to GMCLASSID_SECURITY_PARTICIPANT_CRYPTO_TOKENS (see 7.4.3.5). The operation configures the Cryptographic plugin with the key material necessary to interpret messages encoded by the remote DomainParticipant associated with the remote_participant_crypto and destined to the local DomainParticipant associated with the local_participant_crypto. The interpretation of the CryptoToken sequence is specific to each Cryptographic plugin implementation. The CryptoToken sequence may contain information that is encrypted and/or signed. Typical implementations of the Cryptographic plugin will use the previously configured shared secret associated with the local and remote ParticipantCryptoHandle to decode the CryptoToken sequence and retrieve the key material within.
- 102. 92 DDS Security v1.0 Beta1 Parameter remote_participant_crypto: A ParticipantCryptoHandle, returned by a previous call to register_matched_remote_participant, that corresponds to the DomainParticipant that will be sending the messages from the local DomainParticipant and will be encrypting/signing them with the key material encoded in the CryptoToken sequence. Parameter local_participant_crypto: A ParticipantCryptoHandle, returned by a previous call to register_local_participant, that corresponds to the DomainParticipant that will be receiving messages from the remote DomainParticipant and will need to decrypt and/or verify their signature. Parameter remote_participant_tokens: A ParticipantCryptoToken sequence received via the BuiltinParticipantVolatileMessageSecureReader. The CryptoToken sequence shall correspond to the one returned by a call to create_local_participant_crypto_tokens performed by the remote DomainParticipant on the remote side. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.8.3 Operation: create_local_datawriter_crypto_tokens This operation creates a DatawriterCryptoTokenSeq containing the information needed to correctly interpret cipher text encoded using the local_datawriter_crypto. That is, the CryptoToken sequence contains that information needed to decrypt any data encrypted using the local_datawriter_crypto as well as verify any signatures produced using the local_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 with the remote_datareader_crypto so that the remote DataReader has access to the necessary key material. The operation shall take into consideration the value of the relay_only parameter associated with the DatawriterCryptoHandle (see 8.5.1.7.4) this parameter shall control whether the Tokens returned contain all the cryptographic material needed to decode/verify both the RTPS SubMessage and the SecuredPayload submessage element within or just part of it. If the value of the relay_only parameter was FALSE, the Tokens returned contain all the cryptographic material. If the value of the relay_only parameter was TRUE, the Tokens returned contain only the cryptographic material needed to verify and decode the RTPS SubMessage but not the SecuredPayload submessage element within. The DDS middleware implementation shall call this operation for each remote DataReader that matches a local DataWriter. The returned CryptoToken sequence shall be sent by the DDS middleware to the remote DataReader using the BuiltinParticipantVolatileMessageSecureWriter with kind set to GMCLASSID_SECURITY_DATAWRITER_CRYPTO_TOKENS(see 7.4.3.5). The returned DatawriterCryptoToken shall appear in the message_data attribute of the ParticipantVolatileSecureMessage (see 7.4.4.2). The source_endpoint_key attribute shall be set to the BuiltinTopicKey_t of the local DataWriter and the destination_endpoint_key attribute shall be set to the BuiltinTopicKey_t of the remote DataReader. Parameter local_datawriter_crypto_tokens: The returned DatawriterCryptoTokenSeq.
- 103. DDS Security v1.0 Beta 1 93 Parameter local_datawriter_crypto: A DatawriterCryptoHandle, returned by a previous call to register_local_datawriter that corresponds to the DataWriter that will be encrypting and signing messages. Parameter remote_datareader_crypto: A DatareaderCryptoHandle, returned by a previous call to register_matched_remote_datareader, that corresponds to the DataReader that will be receiving the messages from the local DataWriter and will be decrypting them and verifying their signature. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.8.4 Operation: set_remote_datawriter_crypto_tokens This operation shall be called by the DDS implementation upon reception of a message on the BuiltinParticipantVolatileMessageSecureReader with kind set to GMCLASSID_SECURITY_DATAWRITER_CRYPTO_TOKENS (see 7.4.3.5). The operation configures the Cryptographic plugin with the key material necessary to interpret messages encoded by the remote DataWriter associated with the remote_datawriter_crypto and destined to the local DataReader associated with the local_datareader_crypto. The interpretation of the DatawriterCryptoTokenSeq sequence is specific to each Cryptographic plugin implementation. The CryptoToken sequence may contain information that is encrypted and/or signed. Typical implementations of the Cryptographic plugin will use the previously configured shared secret associated with the remote DatawriterCryptoHandle and local DatareaderCryptoHandle to decode the CryptoToken sequence and retrieve the key material within. Parameter remote_datawriter_crypto: A DatawriterCryptoHandle, returned by a previous call to register_matched_remote_datawriter, that corresponds to the DataWriter that will be sending the messages to the local DataReader and will be encrypting/signing them with the key material encoded in the CryptoToken. Parameter local_datareader_crypto: A DatareaderCryptoHandle, returned by a previous call to register_local_datareader, that corresponds to the DataReader that will be receiving messages from the remote DataWriter and will need to decrypt and/or verify their signature. Parameter remote_datawriter_tokens: A CryptoToken sequence received via the BuiltinParticipantVolatileMessageSecureReader. The DatawriterCryptoToken shall correspond to the one returned by a call to create_local_datawriter_crypto_tokens performed by the remote DataWriter on the remote side. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.8.5 Operation: create_local_datareader_crypto_tokens This operation creates a DatareaderCryptoTokenSeq containing the information needed to correctly interpret cipher text encoded using the local_datareader_crypto. That is, the CryptoToken sequence contains that information needed to decrypt any data encrypted using the local_datareader_crypto as well as verify any signatures produced using the local_datareader_crypto.
- 104. 94 DDS Security v1.0 Beta1 The returned CryptoToken sequence contains opaque data, which only the plugins understand. The returned CryptoToken sequence shall be sent to the remote DataWriter associated with the remote_datawriter_crypto so that the remote DataWriter has access to the necessary key material. For this reason, the CryptoKeyExchange plugin implementation may encrypt the sensitive information inside the CryptoToken sequence using shared secrets and keys obtained from the remote_datawriter_crypto. The specific ways in which this is done depend on the plugin implementation. The DDS middleware implementation shall call this operation for each remote DataWriter that matches a local DataReader. The returned DatareaderCryptoTokenSeq shall be sent by the DDS middleware to the remote DataWriter using the BuiltinParticipantVolatileMessageSecureWriter with kind set to GMCLASSID_SECURITY_DATAREADER_CRYPTO_TOKENS(see 7.4.4.2). The returned DatareaderCryptoTokenSeq shall appear in the message_data attribute of the ParticipantVolatileSecureMessage (see 7.4.4.2). The source_endpoint_key attribute shall be set to the BuiltinTopicKey_t of the local DataReader and the destination_endpoint_key attribute shall be set to the BuiltinTopicKey_t of the remote DataWriter. Parameter local_datareader_crypto_tokens (out): The returned DatareaderCryptoTokenSeq. Parameter local_datareader_crypto: A DatareaderCryptoHandle, returned by a previous call to register_local_datareader, that corresponds to the DataReader that will be encrypting and signing messages. Parameter remote_datawriter_crypto: A DatawriterCryptoHandle, returned by a previous call to register_matched_remote_datawriter, that corresponds to the DataWriter that will be receiving the messages from the local DataReader and will be decrypting them and verifying their signature. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.8.6 Operation: set_remote_datareader_crypto_tokens This operation shall be called by the DDS implementation upon reception of a message on the BuiltinParticipantVolatileMessageSecureReader with kind set to GMCLASSID_SECURITY_DATAREADER_CRYPTO_TOKENS(see 7.4.4.2). The operation configures the Cryptographic plugin with the key material necessary to interpret messages encoded by the remote DataReader associated with the remote_datareader_crypto and destined to the local DataWriter associated with the local_datawriter_crypto. The interpretation of the DatareaderCryptoTokenSeq is specific to each Cryptographic plugin implementation. The CryptoToken sequence may contain information that is encrypted and/or signed. Typical implementations of the Cryptographic plugin will use the previously configured shared secret associated with the remote DatareaderCryptoHandle and local DatawriterCryptoHandle to decode the CryptoToken sequence and retrieve the key material within.
- 105. DDS Security v1.0 Beta 1 95 Parameter remote_datareader_crypto: A DatareaderCryptoHandle, returned by a previous call to register_matched_remote_datareader, that corresponds to the DataReader that will be sending the messages to the local DataWriter and will be encrypting/signing them with the key material encoded in the CryptoToken sequence. Parameter local_datawriter_crypto: A DatawriterCryptoHandle returned by a previous call to register_local_datawriter, that corresponds to the DataWriter that will be receiving messages from the remote DataReader and will need to decrypt and/or verify their signature. Parameter remote_datareader_tokens: A CryptoToken sequence received via the BuiltinParticipantVolatileMessageSecureReader. The DatareaderCryptoToken shall correspond to the one returned by a call to create_local_datareader_crypto_tokens performed by the remote DataReader on the remote side. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.8.7 Operation: return_crypto_tokens Returns the tokens in the CryptoToken sequence to the plugin so the plugin can release any information associated with it. Parameter crypto_tokens: Contains CryptoToken objects issued by the plugin on a prior call to one of the following operations: create_local_participant_crypto_tokens create_local_datawriter_crypto_tokens create_local_datareader_crypto_tokens Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.9 CryptoTransform interface This interface groups the operations related to encrypting/decrypting, as well as, computing and verifying 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 computation of a MAC (also known as a keyed cryptographic hash function), takes as input a secret key and an arbitrary-length message to be authenticated, and outputs a MAC. The MAC value protects both a message's data integrity, as well as, its authenticity by allowing verifiers (who also possess the secret key) 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 algorithms, the API is chosen such that plugins can implement HMAC if they so choose. The operations in the CryptoTransform Plugin are defined to be quite generic, taking an input byte array to transform and producing the transformed array of bytes as an output. The DDS implementation is only responsible for calling the operations in the CryptoTransform plugin at the appropriate times as it generates and processes the RTPS messages, substitutes the input bytes with the transformed bytes produced by the CryptoTransform operations, and proceeds to generate/send or process the RTPS message as normal but with the replaced bytes. The decision of the kind of
- 106. 96 DDS Security v1.0 Beta1 transformation to perform (encrypt and/or produce a digest and/or a MAC and/or signature) is left to the plugin implementation. Table 24 – CryptoTransform interface CryptoTransform No Attributes Operations Boolean out: encoded_buffer octet[] plain_buffer octet[] sending_datawrit er_crypto DatawriterCryptoHandle encode_serialized_da ta out: exception SecurityException Boolean out: encoded_rtps_sub message octet[] plain_rtps_subme ssage octet[] sending_datawrit er_crypto DatawriterCryptoHandle receiving_datare ader_crypto_list DatareaderCryptoHandle[] encode_datawriter_su bmessage out: exception SecurityException Boolean out: encoded_rtps_sub message octet[] plain_rtps_subme ssage octet[] sending_dataread er_crypto DatareaderCryptoHandle receiving_datawr iter_crypto_list DatawriterCryptoHandle[] encode_datareader_su bmessage out: exception SecurityException encode_rtps_message Boolean
- 107. DDS Security v1.0 Beta 1 97 out: encoded_rtps_mes sage octet[] plain_rtps_messa ge octet[] sending_crypto ParticipantCryptoHandle receiving_crypto _list ParticipantCryptoHandle[] out: exception SecurityException Boolean out: plain_buffer octet[] encoded_buffer octet[] receiving_crypto ParticipantCryptoHandle sending_crypto ParticipantCryptoHandle decode_rtps_message out: exception SecurityException Boolean out: datawriter_crypt o DatawriterCryptoHandle out: datareader_crypt o DatareaderCryptoHandle out: secure_submessag e_category DDS_SecureSumessageCatego ry_t in: encoded_rtps_sub message octet[] receiving_crypto ParticipantCryptoHandle sending_crypto ParticipantCryptoHandle preprocess_secure_su bmsg out: exception SecurityException Booleandecode_datawriter_su bmessage out: plain_rtps_subme octet[]
- 108. 98 DDS Security v1.0 Beta1 8.5.1.9.1 Operation: encode_serialized_data This operation shall be called by the DDS implementation as a result of the application calling the write operation on the DataWriter associated with the DatawriterCryptoHandle specified in the sending_datawriter_crypto parameter. The operation receives the data written by the DataWriter in serialized form wrapped inside the RTPS SerializedData submessage element and shall output a RTPS SecuredPayload submessage element. ssage encoded_rtps_sub message octet[] receiving_datare ader_crypto DatareaderCryptoHandle sending_datawrit er_crypto DatawriterCryptoHandle out: exception SecurityException Boolean out: plain_rtps_subme ssage octet[] encoded_rtps_sub message octet[] receiving_datawr iter_crypto DatawriterCryptoHandle sending_dataread er_crypto DatareaderCryptoHandle decode_datareader_su bmessage out: exception SecurityException Boolean out: plain_buffer octet[] encoded_buffer octet[] receiving_datare ader_crypto DatareaderCryptoHandle sending_datawrit er_crypto DatawriterCryptoHandle decode_serialized_da ta out: exception SecurityException
- 109. DDS Security v1.0 Beta 1 99 The DDS implementation shall call this operation for all outgoing RTPS Submessages with submessage kind Data and DataFrag. The DDS implementation shall substitute the SerializedData submessage element within the aforementioned RTPS submessages with the SecuredPayload produced by this operation. The implementation of encode_serialized_data can perform any desired cryptographic transformation of the SerializedData using the key material in the sending_datawriter_crypto, including encryption, addition of a MAC, and/or signature. The SecuredPayload shall include within the CryptoTransformIdentifier any additional information beyond the one shared via the CryptoToken that would be needed to identify the key used and decode the SecuredPayload submessage element. Figure 13 – Effect of encode_serialized_data within an RTPS message If an error occurs, this method shall return false. Parameter encoded_buffer: The output containing the SecuredPayload 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 to register_local_datawriter for the DataWriter that wrote the SerializedData. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.9.2 Operation: encode_datawriter_submessage This operation shall be called by the DDS implementation whenever it has constructed a RTPS submessage of kind Data, DataFrag, Gap, Heartbeat, or HeartbeatFrag. The operation receives the DatawriterCryptoHandle of the DataWriter that is sending the submessage, as well as, a list of DatareaderCryptoHandle corresponding to all the DataReader entities to which the submessage is being sent.
- 110. 100 DDS Security v1.0 Beta1 The operation receives the complete RTPS submessage as it would normally go onto the wire in the parameter rtps_submessage and shall output a RTPS SecureSubMsg in the output parameter encoded_rtps_submessage. The DDS implementation shall substitute the original RTPS submessage that was passed in the rtps_submessage with the SecureSubMsg returned in the encoded_rtps_submessage output parameter and use the SecureSubMsg in the construction of the RTPS message that is eventually sent to the intended recipients. The implementation of encode_datawriter_submessage can perform any desired cryptographic transformation of the RTPS Submessage using the key material in the sending_datawriter_crypto; it can also add one or more MACs and/or signatures. The fact that the cryptographic material associated with the list of intended DataReader entities is passed in the parameter receiving_datareader_crypto_list allows the plugin implementation to include MACs that may be computed differently for each DataReader. The implementation of encode_datawriter_submessage shall include, within the SecureSubMsg, the CryptoTransformIdentifier containing any additional information necessary for the receiving plugin to identify the DatawriterCryptoHandle associated with the DataWriter that sent the message, as well as, the DatareaderCryptoHandle associated with the DataReader that is meant to process the submessage. How this is done depends on the plugin implementation. The CryptoTransformIdentifier should also contain any additional information beyond the one shared via the CryptoToken that would be needed to identify the key used and decode the SecureSubMsg submessage back into the original RTPS submessage. If an error occurs, this method shall return false. Figure 14 – Effect of encode_datawriter_submessage within an RTPS message Parameter encoded_rtps_submessage: The output containing the RTPS SecureSubMsg submessage, which shall be used to replace the input rtps_submessage. Parameter plain_rtps_submessage: The input containing the RTPS submessage created by a DataWriter. This submessage will be one of following kinds: Data, DataFrag, Gap, Heartbeat, and HeartbeatFrag. Parameter sending_datawriter_crypto: The DatawriterCryptoHandle returned by a previous call to register_local_datawriter for the DataWriter whose GUID is inside the rtps_submessage.
- 111. DDS Security v1.0 Beta 1 101 Parameter receiving_datareader_crypto_list: The list of DatareaderCryptoHandle returned by previous calls to register_matched_remote_datareader for the DataReader entities to which the submessage will be sent. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.9.3 Operation: encode_datareader_submessage This operation shall be called by the DDS implementation whenever it has constructed a RTPS submessage of kind AckNack or NackFrag. The operation receives the DatareaderCryptoHandle of the DataReader that is sending the submessage, as well as, a list of DatawriterCryptoHandle corresponding to all the DataWriter entities to which the submessage is being sent. The operation receives the complete RTPS submessage as it would normally go onto the wire in the parameter rtps_submessage and shall output a RTPS SecureSubMsg in the output parameter encoded_rtps_submessage. The DDS implementation shall substitute the original RTPS submessage that was passed in the rtps_submessage with the SecureSubMsg returned in the encoded_rtps_submessage output parameter and use the SecureSubMsg in the construction of the RTPS message that is eventually sent to the intended recipients. The implementation of encode_datareader_submessage can perform any desired cryptographic transformation of the RTPS Submessage using the key material in the sending_datareader_crypto, it can also add one or more MACs, and/or signatures. The fact that the cryptographic material associated with the list of intended DataWriter entities is passed in the parameter receiving_datawriter_crypto_list allows the plugin implementation to include one of MAC that may be computed differently for each DataWriter. The implementation of encode_datareader_submessage shall include within the SecureSubMsg the CryptoTransformIdentifier containing any additional information necessary for the receiving plugin to identify the DatareaderCryptoHandle associated with the DataReader that sent the message as well as the DatawriterCryptoHandle associated with the DataWriter that is meant to process the submessage. How this is done depends on the plugin implementation. The CryptoTransformIdentifier should also contain any additional information beyond the one shared via the CryptoToken that would be needed to identify the key used and decode the SecureSubMsg submessage back into the original RTPS submessage. If an error occurs, this method shall return false.
- 112. 102 DDS Security v1.0 Beta1 Figure 15 – Effect of encode_datareader_submessage within an RTPS message Parameter encoded_rtps_submessage: The output containing the RTPS SecureSubMsg submessage, which shall be used to replace the input rtps_submessage. Parameter plain_rtps_submessage: The input containing the RTPS submessage created by a DataReader. This submessage will be one of following kinds: AckNack, NackFrag. Parameter sending_datareader_crypto: The DatareaderCryptoHandle returned by a previous call to register_local_datareader for the DataReader whose GUID is inside the rtps_submessage. Parameter receiving_datawriter_crypto_list: The list of DatawriterCryptoHandle returned by previous calls to register_matched_remote_datawriter for the DataWriter entities to which the submessage will be sent. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.9.4 Operation: encode_rtps_message This operation shall be called by the DDS implementation whenever it has constructed a RTPS message prior to sending it on the wire. The operation receives the ParticipantCryptoHandle of the DomainParticipant that is sending the submessage, as well as, a list of ParticipantCryptoHandle corresponding to all the DomainParticipant 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 parameter rtps_message and shall also output an RTPS message containing a single SecureSubMsg in the output parameter encoded_rtps_message. The DDS implementation shall substitute the original RTPS message that was passed in the rtps_message with the encoded_rtps_message returned by this operation and proceed to send it to the intended recipients. This operation may optionally not perform any transformation of the input RTPS message. In this case, the operation shall return false but not set the exception object. In this situation the DDS implementation shall send the original RTPS message. If this operation performs any transformation of the original RTPS message, it shall output an RTPS Header followed by a single SecureSubMsg with the MultiSubmsgFlag (see 7.3.6.2) set to true. The output RTPS Header shall have its fields set as shown in the table below: Table 25 – RTPS header resulting from the encode_rtps_message transformation
- 113. DDS Security v1.0 Beta 1 103 RTPS Header field Mandatory values The purpose of using this specially-constructed RTPS Header is to let the encoded_rtps_message remain a legal RTPS message containing a valid protocol signature and version while at the same time hiding the vendorId and more importantly the guidPrefix which could be considered sensitive. The implementation of encode_rtps_message may perform any desired cryptographic transformation of the whole RTPS Message using the key material in the sending_participant_crypto, it can also add one or more MACs, and/or signatures. The fact that the cryptographic material associated with the list of intended DataWriter entities is passed in the parameter receiving_participant_crypto_list allows the plugin implementation to include one of MAC that may be computed differently for each destination DomainParticipant. The implementation of encode_ rtps_message shall include within the SecureSubMsg the CryptoTransformIdentifier containing any additional information beyond the one shared via the CryptoToken that would be needed to identify the key used and decode the SecureSubMsg submessage back into the original RTPS message. If an error occurs, this method shall return false and set the exception object. Figure 16 – Effect of encode_rtps within a RTPS message Parameter encoded_rtps_message: The output containing the encoded RTPS message. The output message shall contain the modified RTPS Header followed by a single SecureSubMsg submessage with the MultiSubmsgFlag set to true.
- 114. 104 DDS Security v1.0 Beta1 Parameter plain_rtps_message: The input containing the RTPS messages the DDS implementation intended to send. Parameter sending_participant_crypto: The ParticipantCryptoHandle returned by a previous call to register_local_participant for the DomainParticipant whose GUID is inside the RTPS Header. Parameter receiving_participant_crypto_list: The list of ParticipantCryptoHandle returned by previous calls to register_matched_remote_participant for the DomainParticipant entities to which the message will be sent. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.9.5 Operation: decode_rtps_message This operation shall be called by the DDS implementation whenever it receives an RTPS message prior to parsing it. This operation shall reverse the transformation performed by the encode_rtps_message operation, decrypting the content if appropriate and verifying any MACs or digital signatures that were produced by the encode_rtps_message operation. This operation expects the RTPS Header to be followed by a single SecureSubMsg with the MultiSubmsgFlag (see 7.3.6.2) set to true. If this is not the case the operation shall perform no transformation, return false, but not set the exception object. This situation is not considered an error. It simply indicates that the encode_rtps_message operation did not transform the original RTPS message. If an error occurs, this method shall return an exception. Figure 17 – Effect of decode_rtps within an RTPS message
- 115. DDS Security v1.0 Beta 1 105 Parameter plain_rtps_message: The output containing the decoded RTPS message. The output message shall contain the original RTPS Header and the set of RTPS SubmessagesMsg that were encapsulated inside the SecureSubMsg submessage. Parameter encoded_rtps_message: The input containing the encoded RTPS message the DDS implementation received. Parameter receiving_participant_crypto: The ParticipantCryptoHandle returned by previous calls to register_local_participant for the DomainParticipant entity that received the RTPS message. Parameter sending_participant_crypto: The ParticipantCryptoHandle returned by a previous call to register_matched_remote_participant for the DomainParticipant that sent the RTPS message whose GUID is inside the RTPS Header. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.9.6 Operation: preprocess_secure_submsg This operation shall be called by the DDS implementation as a result of a DomainParticipant receiving a RTPS SecureSubMsg with the MultiSubmsgFlag (see 7.3.6.2) set to false. The purpose of the operation is to determine whether the secure submessage was produced as a result of a call to encode_datawriter_submessage or a call to encode_datareader_submessage, and retrieve the appropriate DatawriterCryptoHandle and DatareaderCryptoHandle needed to decode the submessage. If the operation returns successfully, the DDS implementation shall call the appropriate decode operation based on the returned SecureSubmessageCategory_t: If the returned SecureSubmessageCategory_t equals DATAWRITER_SUBMESSAGE, then the DDS Implementation shall call decode_datawriter_submessage. If the returned SecureSubmessageCategory_t equals DATAREADER_SUBMESSAGE, then the DDS Implementation shall call decode_datareader_submessage. If the re returned SecureSubmessageCategory_t equals INFO_SUBMESSAGE, then the DDS Implementation proceed normally to process the submessage without further decoding. Parameter secure_submessage_category: Output SecureSubmessageCategory_t. It shall be set to DATAWRITER_SUBMESSAGE if the SecureSubMsg was created by a call to encode_datawriter_submessage or set to DATAREADER_SUBMESSAGE if the SecureSubMsg was created by a call to encode_datareader_submessage. If none of these conditions apply, the operation shall return false. Parameter datawriter_crypto: Output DatawriterCryptoHandle. The setting depends on the retuned value of secure_submessage_category: If secure_submessage_category is DATAWRITER_SUBMESSAGE, the datawriter_crypto shall be the DatawriterCryptoHandle returned by a previous call
- 116. 106 DDS Security v1.0 Beta1 to register_matched_remote_datawriter for the DataWriter that wrote the RTPS Submessage. If secure_submessage_category is DATAREADER_SUBMESSAGE, the datawriter_crypto shall be the DatawriterCryptoHandle returned by a previous call to register_local_datawriter for the DataWriter that is also the destination of the RTPS Submessage. Parameter datareader_crypto: Output DatareaderCryptoHandle. The setting depends on the retuned value of secure_submessage_category: If secure_submessage_category is DATAWRITER_SUBMESSAGE, 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 DATAREADER_SUBMESSAGE, 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 previous calls to register_local_participant for the DomainParticipant that received the RTPS message. Parameter sending_participant_crypto: The ParticipantCryptoHandle returned by a previous call to register_matched_remote_participant for the DomainParticipant whose GUID is inside the RTPS Header. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.9.7 Operation: decode_datawriter_submessage This operation shall be called by the DDS implementation as a result of receiving a SecureSubMsg with the MultiSubmsgFlag set to false whenever the preceding call to preprecess_secure_submessage identified the SecureSubmessageCategory_t as DATAWRITER_SUBMESSAGE. This operation shall reverse the transformation performed by the encode_datawriter_submessage operation, decrypting the content if appropriate and verifying any MACs or digital signatures that were produced by the encode_datawriter_submessage operation. The DDS implementation shall substitute the RTPS SecureSubMsg submessage within the received submessages with the RTPS Submessage produced by this operation. If an error occurs, this method shall return false.
- 117. DDS Security v1.0 Beta 1 107 Figure 18 – Effect of decode_datawriter_submessage within an RTPS message Parameter plain_rtps_submessage: The output containing the RTPS submessage created by a DataWriter. This submessage will be one of following kinds: Data, DataFrag, Gap, Heartbeat, and HeartbeatFrag. Parameter encoded_rtps_submessage: The input containing the RTPS SecureSubMsg submessage, which was created by a call to encode_datawriter_submessage. Parameter receiving_datareader_crypto: The DatareaderCryptoHandle returned by the preceding call to prepreprocess_secure_submessage performed on the received SecureSubMsg. It shall contain the DatareaderCryptoHandle corresponding to the DataReader that is receiving the RTPS Submessage. Parameter sending_datawriter_crypto: The DatawriterCryptoHandle returned by the preceding call to prepreprocess_secure_submsg performed on the received SecureSubMsg. It shall contain the DatawriterCryptoHandle corresponding to the DataWriter that is sending the RTPS Submessage. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.5.1.9.8 Operation: decode_datareader_submessage This operation shall be called by the DDS implementation as a result of receiving a SecureSubMsg with the MultiSubmsgFlag set to false whenever the preceding call to preprecess_secure_submessage identified the SecureSubmessageCategory_t as DATAREADER_SUBMESSAGE. This operation shall reverse the transformation performed by the encode_datareader_submessage operation, decrypting the content if appropriate and verifying any MACs or digital signatures that were produced by the encode_datareader_submessage operation. The DDS implementation shall substitute the RTPS SecureSubMsg submessage within the received submessages with the RTPS Submessage produced by this operation. If an error occurs, this method shall return false.
- 118. 108 DDS Security v1.0 Beta1 Figure 19 – Effect of decode_datawriter_submessage within an RTPS message Parameter plain_rtps_submessage: The output containing the RTPS submessage created by a DataReader. This submessage will be one of following kinds: AckNack, NackFrag. Parameter encoded_rtps_submessage: The input containing the RTPS SecureSubMsg submessage, which was created by a call to encode_datareader_submessage. Parameter receiving_datawriter_crypto: The DatawriterCryptoHandle returned by the preceding call to prepreprocess_secure_subessage performed on the received SecureSubMsg. It shall contain the DatawriterCryptoHandle corresponding to the DataWriter that is receiving the RTPS Submessage. Parameter sending_datareader_crypto: The DatareaderCryptoHandle returned by the preceding call to prepreprocess_secure_submessage performed on the received SecureSubMsg. It shall contain the DatareaderCryptoHandle corresponding to the DataReader that is sending the RTPS Submessage. 8.5.1.9.9 Operation: decode_serialized_data This operation shall be called by the DDS implementation as a result of a DataReader receiving a Data or DataFrag submessage containing a SecuredPayload RTPS submessage element (instead of the normal SerializedData). The DDS implementation shall substitute the SecuredPayload submessage element within the received submessages with the SerializedData produced by this operation. The implementation of decode_serialized_data shall undo the cryptographic transformation of the SerializedData that was performed by the corresponding call to encode_serialized_data on the DataWriter side. The DDS implementation shall use the available information on the remote DataWriter that wrote the message and the receiving DataReader to locate the corresponding DatawriterCryptoHandle and DatareaderCryptoHandle and pass them as parameters to the operation. In addition, it shall use the CryptoTransformIdentifier present in the SecuredPayload to verify that the correct key us available and obtain any additional data needed to decode the SecuredPayload.
- 119. DDS Security v1.0 Beta 1 109 Figure 20 – Effect of decode_serialized_data within an RTPS message 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 SecuredPayload RTPS submessage element. Parameter receving_reader_crypto: The DatareaderCryptoHandle returned by a previous call to register_local_datareader for the DataReader that received the Submessage containing the SecuredPayload. Parameter sending_datawriter_crypto: The DatawriterCryptoHandle returned by a previous call to register_matched_remote_datawriter for the DataWriter that wrote the SecuredPayload. Parameter exception: A SecurityException object, which provides details in case this operation returns false.
- 120. 110 DDS Security v1.0 Beta1 8.6 The Logging Plugin The Logging Control Plugin API defines the types and operations necessary to support logging of security events for a DDS DomainParticipant. 8.6.1 Background (Non-Normative) The Logging plugin provides the capability to log all security events, including expected behavior and all security violations or errors. The goal is to create security logs that can be used to support audits. The rest of the security plugins will use the logging API to log events. The Logging plugin will add an ID to the log message that uniquely specifies the DomainParticipant. It will also add 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 for collection and storage. The second is to distribute log events securely over DDS. 8.6.2 Logging Plugin Model The logging model is shown in the figure below. class Logging SecurityPlugin «interface» Logging + enable_logging() :void + log() :void + set_log_options() :boolean «primitive» LogOptions Figure 21 – Logging Plugin Model 8.6.2.1 LogOptions The LogOptions let the user control the log level and where to log. The options must be set before logging starts and may not be changed at run-time after logging has commenced. This is to ensure that an attacker cannot temporarily suspend logging while they violate security rules, and then start it up again. The options specify if the messages should be logged to a file and, if so, the file name. The LogOptions also specify whether the log messages should be distributed to remote services or only kept locally. Table 26 – LogOptions values LogOptions Attributes
- 121. DDS Security v1.0 Beta 1 111 log_level Long log_file String distribute Boolean 8.6.2.1.1 Attribute: log_level Specifies what level of log messages will be logged. Messages at or below the log_level are logged. The levels are as follows, from low to high: 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 information 8.6.2.1.2 Attribute: log_file Specifies the full path to a local file for logging events. If the file already exists, the logger will append log messages to the file. If it is NULL, then the logger will not log messages to a file. 8.6.2.1.3 Attribute: distribute Specifies whether the log events should be distributed over DDS. If it is TRUE, each log message at or above the log_level is published as a DDS Topic. 8.6.2.2 Logging Table 27 – Logging Interface Logging No Attributes Operations Boolean options LogOptions set_log_options exception SecurityException void log_level long log message String
- 122. 112 DDS Security v1.0 Beta1 8.6.2.2.1 Operation: set_log_options Sets the options for the logger. This must be called before enable_logging; it is an error to set the options 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 options. Parameter exception: A SecurityException object, which provides details in case this operation returns false. 8.6.2.2.2 Operation: log Log a message. The logger shall log the message if its log_level is at or above the level set in the LogOptions. The Logger shall add to the message the RTPS GUID of the DomainParticipant whose operations are being logged. If it is sent out over DDS, then DDS shall add a timestamp. If it is logged locally, a timestamp shall be added when it is logged. Parameter log_level: The level of the log message. It must correspond to one of the levels defined in 8.6.2.1.1. Parameter message: The log message. Parameter category: A category for the log message. This can be used to specify which security plugin generated the message. Parameter exception: A SecurityException object that will return an exception if there is an error with logging. 8.6.2.2.3 Operation: enable_logging Enables logging. After this method is called, any call to log shall log the messages according to the options. After this method is called, the options may not be modified. This is to ensure that the logger 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 options. Parameter exception: A SecurityException object, which provides details in case this operation returns false. category String exception SecurityException voidenable_logging exception SecurityException
- 123. DDS Security v1.0 Beta 1 113 8.7 Data Tagging Data tagging is the ability to add a security label or tag to data. This is often used to specify a classification level of the data including information about its releasability. In a DDS context, it could have several 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 service 8.7.1 Background (Non-Normative) There are four different approaches to data tagging: 1. 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. 2. 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. 3. Individual sample tagging: every DDS sample has its own tag attached. 4. Per-field sample tagging: very complex management of the tags. This specification supports DataWriter tagging. This was considered the best choice as it meets the majority of uses cases. It fits into the DDS paradigm, as the metadata for all samples from a DataWriter is the same. It is also the highest performance, as the tag only needs to be exchanged once when the DataWriter is discovered, not sent with each sample. This approach directly supports typical use cases where each application or DomainParticipant writes data on a Topic with a common set of tags (e.g., all at the same specified security level). For use cases where an application creates data at different classifications, that application can create multiple DataWriters with different tags. 8.7.2 DataTagging Model The DataWriter tag will be associated with every sample written by the DataWriter. The DataWriter DataTag is implemented as an immutable DataWriterQos. The DataWriter DataTag shall be propagated via in the PublicationBuiltinTopicData as part of the DDS discovery protocol. The DataReader DataTag is implemented as an immutable DataReaderQos. The DataReader DataTag shall be propagated via in the SubscriptionBuiltinTopicData as part of the DDS discovery protocol. 8.7.3 DataTagging Types The following data types are used for the DataTag included as part of both DataReader and DataWriter Qos. typedef DataTagQosPolicy DataTag;
- 124. 114 DDS Security v1.0 Beta1 8.8 Security Plugins Behavior In the previous sub clauses, the functionality and APIs of each plugin have been described. This sub clause provides additional information on how the plugins are integrated with the middleware. 8.8.1 Authentication and AccessControl behavior with local DomainParticipant The figure below illustrates the functionality of the security plugins with regards to a local DomainParticipant. In this sub clause the term “DDS application” refers to the application code that calls the DDS API. The term “DDS middleware” refers to a DDS Implementation that complies with the DDS Security specification. sd DDS::Security-Participant Authentication DDS-DiscoveryDDSApplication Participant AccessControl «create» validate_local_identity() :ValidationResult_t validate_local_permissions() :PermissionsHandle check_create_participant() :Boolean get_identity_token() :Boolean get_permissions_token() :Boolean get_permissions_credential_token() :Boolean set_permissions_credential_and_token() :Boolean get_participant_sec_attributes() :Boolean configure( IdentityToken, PermissionsToken ) Figure 22 – Authentication and AccessControl sequence diagram with local DomainParticipant This behavior sequence is triggered when the DDS application initiates the creation of a local DomainParticpant by calling the create_participant operation on the DomainParticipantFactory. The following are mandatory steps that the DDS middleware shall perform prior to creating the DomainParticipant. The steps need not occur exactly as described as long as the observable behavior matches the one described below.
- 125. DDS Security v1.0 Beta 1 115 1. The DDS middleware shall validate the identity of the application attempting to create the DomainParticipant by calling the Authentication::validate_local_identity operation, passing the IdentityCredential and a candidate_participant_key. The Authentication plugin validates the identity of the local DomainParticipant and returns an IdentityHandle for the holder of the identity (DomainParticipant), which will be necessary for interacting with the access control plugin. The validate_local_identity operation also returns an adjusted_participant_key. If the identity is not successfully validated, the DDS middleware shall not create the DomainParticipant and the create_participant operation shall return NIL and set the return code to NOT_ALLOWED_BY_SEC. 2. The DDS middleware shall validate that the DDS application has the necessary permissions to join DDS domains by calling the AccessControl::validate_local_permissions operation. The Access Control plugin shall validates the permissions and issue a signed PermissionsHandle for the holder of the identity (DomainParticipant). If the permissions are not validated, the DomainParticipant shall not be created, the create_participant operation shall return NIL and set the return code to NOT_ALLOWED_BY_SEC. 3. The DDS middleware shall verify that the DDS application has the necessary permissions to join the specific Domain identified by the domainId by calling the operation AccessControl::check_create_participant. If this operation returns FALSE, the DomainParticipant shall not be created, the create_participant operation shall return NIL and set the return code to NOT_ALLOWED_BY_SEC. 4. The DDS middleware shall call the get_identity_token operation to obtain the IdentityToken object corresponding to the received IdentityHandle. The IdentityToken object shall be placed in the ParticipantBuiltinTopicData sent via discovery, see 7.4.1.3. 5. The middleware shall call the get_permissions_token operation on the AccessControl plugin to obtain the PermissionsToken object corresponding to the received PermissionsHandle. The PermissionsToken shall be placed in the ParticipantBuiltinTopicData sent via discovery, see 7.4.1.3. 6. The middleware calls the get_permissions_credential operation on the AccessControl plugin, which returns the PermissionsCredential object corresponding to the received PermissionsHandle. The PermissionsCredential object is necessary to configure the Authentication plugin. 7. The middleware calls the set_permissions_credential_and_token operation on the Authentication plugin such that it can be sent during the authentication handshake. 8. The middleware calls the get_psrticipant_sec_attributes operation on the AccessControl plugin to obtain the ParticipantSecurityAttributes such that it knows how to handle remote participants that fail to authenticate.
- 126. 116 DDS Security v1.0 Beta1 9. The DomainParticipant’s IdentityToken and PermissionsToken are used to configure DDS discovery such that they are propagated inside the identity_token and the permissions_token members of the ParticipantBuiltinTopicData. This operation is internal to the DDS implementation and therefore this API is not specified by the DDS Security specification. It is mentioned here to provide guidance to implementers. 8.8.2 Authentication behavior with discovered DomainParticipant Depending on the ParticipantSecurityAttributes returned by the AccessControl operation get_participant_sec_attributes the DomainParticipant may allow remote DomainParticipants that lack the ability to authenticate (e.g., do not implement DDS Security) to match. 8.8.2.1 Behavior when is_access_protected is set to FALSE If the ParticipantSecurityAttributes returned by the operation get_participant_sec_attributes has the member is_access_protected set to FALSE, the DomainParticipant shall match remote DomainParticipant entities that are not able to authenticate. Specifically: Discovered DomainParticipant entities that do not implement the DDS Security specification or do not contain compatible Security Plugins shall be matched without the DomainParticipant attempting to authenticate them and shall be treated as “Unauthenticated” DomainParticipant entities. Discovered DomainParticipant entities that do implement the DDS Security specification and declare compatible Security Plugins but fail the Authentication protocol shall be matched and treated as “Unauthenticated” DomainParticipants entities. For any matched “Unauthenticated” DomainParticipant entities, the DomainParticipant shall match only the regular builtin Endpoints (ParticipantMessage, DCPSParticipants, DCPSPublications, DCPSSubscriptions) and not the builtin secure Endpoints (see 7.4.5 for the complete list). For any matched authenticated DomainParticipant entities, the DomainParticipant shall match all the builtin endpoints. 8.8.2.2 Behavior when is_access_protected is set to TRUE If the ParticipantSecurityAttributes has the member is_access_protected set to TRUE, the DomainParticipant shall reject remote DomainParticipant entities that are not able to authenticate. Specifically: Discovered DomainParticipant entities that do not implement the DDS Security specification or do not contain compatible Security Plugins shall be rejected without the DomainParticipant attempting to authenticate them. Discovered DomainParticipant entities that do implement the DDS Security specification, declare compatible Security Plugins but fail the Authentication protocol shall be rejected. Discovered DomainParticipant entities that do implement the DDS Security specification, declare compatible Security Plugins and pass the Authentication protocol successfully shall be
- 127. DDS Security v1.0 Beta 1 117 matched and the DomainParticipant shall also match all the builtin endpoints of the discovered DomainParticipant. The figure below illustrates the behavior of the security plugins with regards to a discovered DomainParticipant that also implements the DDS Security specification and announces compatible security plugins. The exact operations depend on the plugin implementations. The sequence diagram shown below is just indicative of one possible sequence of events and matches what the builtin DDS:Auth:PKI-RSA/DSA-DH plugin (see 9.3.3) does. sd DDS::Security-RemoteParticipant DDS-DiscoveryParticipant1 Participant2DDS-Protocol «interface» :Authentication «interface» :Authentication discoveredParticipant(Participant1, IdentityToken1, PermissionsToken1) validate_remote_identity() : PENDING_HANDSHAKE_MESSAGEdiscoveredParticipant(Participant2, IdentityToken2, PermissionsToken2) validate_remote_identity() : PENDING_HANDSHAKE_REQUEST begin_handshake_request(out: messageToken1) : PENDING_HANDSHAKE_MESSAGE send( messageToken1 ) begin_handshake_reply(out: messageToken2, in: messageToken1) : PENDING_HANDSHAKE_MESSAGE send(messageToken2) process_handshake() : OK_WITH_FINAL_MESSAGE send(messageToken3) process_handshake() :OK get_shared_secret() :SharedSecret get_peer_permissions_credential_token() : Boolean get_shared_secret() :SharedSecret get_peer_permissions_credential_token() : Boolean Figure 23 – Authentication sequence diagram with discovered DomainParticipant 1. Participant2 discovers Participant1via the discovery protocol. The BuiltinParticipantTopicData contains the IdentityToken and PermissionsToken of Participant1. 2. Participant2 calls the validate_remote_identity operation to validate the identity of Participant1 passing the IdentityToken and PermissionsToken of Participant1 received via discovery and obtains an IdentityHandle for Participant1, needed for further operations involving Participant1. The operation returns PENDING_HANDSHAKE_MESSAGE indicating that further handshake messages are needed to complete the validation and that Participant2 should wait for a HandshakeMessageToken to be received from Participant1. Participant2 waits for this message.
- 128. 118 DDS Security v1.0 Beta1 3. Participant1 discovers Participant2 via the DDS discovery protocol. The BuiltinParticipantTopicData contains the IdentityToken and PermissionsToken of Participant2. 4. Participant1 calls the operation validate_remote_identity to validate the identity of Participant2 passing the IdentityToken and PermissionsToken of Participant2 received via discovery and obtains an IdentityHandle for Participant2, needed for further operations involving Participant2. The operation returns PENDING_HANDSHAKE_REQUEST indicating further handshake messages are needed and Participant1 should initiate the handshake. . 5. Participant1 calls begin_handshake_request to begin the requested handshake. The operation outputs a HandshakeHandle and a HandshakeMessageToken (messageToken1). The operation returns PENDING_HANDSHAKE_MESSAGE indicating authentication is not complete and the returned messageToken1 needs to be sent to Participant2 and a reply should be expected.. 6. Participant1 sends the HandshakeMessageToken (messageToken1) to Participant2 using the BuiltinParticipantMessageWriter. 7. Participant2 receives the HandshakeMessageToken (messageToken1) on the BuiltinParticipantMessageReader. Participant2 determines the message originated from a remote DomainParticipant (Participant1) for which it had already called validate_remote_identity where the function had returned PENDING_HANDSHAKE_REPLY. 8. Participant2 calls begin_handshake_reply passing the received HandshakeMessageToken (messageToken1). The Authentication plugin processes the HandshakeMessageToken (messageToken1) and outputs a HandshakeMessageToken (messageToken2) in response and a HandshakeHandle. The operation begin_handshake_reply returns PENDING_HANDSHAKE_MESSAGE, indicating authentication is not complete and an additional message needs to be received. 9. Participant2 sends the HandshakeMessageToken (messageToken2) back to Participant1 using the BuiltinParticipantMessageWriter. 10. Participant1 receives the HandshakeMessageToken (messageToken2) on the BuiltinParticipantMessageReader. Participant1 determines this is message originated from a remote DomainParticipant (Participant2) for which it had already called validate_remote_identity where the function had returned PENDING_HANDSHAKE_REQUEST. 11. Participant1 calls process_handshake passing the received HandshakeMessageToken (messageToken2). The Authentication plugin processes messageToken2, verifies it is a valid reply to the messageToken1 it had sent and outputs the HandshakeMessageToken messageToken3 in response. The process_handshake operation returns OK_WITH_FINAL_MESSAGE, indicating authentication is complete but the returned HandshakeMessageToken (messageToken3) must be sent to Participant2.
- 129. DDS Security v1.0 Beta 1 119 12. Participant1 sends the HandshakeMessageToken (messageToken3) to Participant2 using the BuiltinParticipantMessageWriter. 13. Participant2 receives the HandshakeMessageToken (messageToken3) on the BuiltinParticipantMessageReader. Participant2 determines this is message originated from a remote DomainParticipant (Participamt1) for which it had already called the operation begin_handshake_reply where the call had returned PENDING_HANDSHAKE_MESSAGE. 14. Participant2 calls the process_handshake operation, passing the received HandshakeMessageToken (messageToken3). The Authentication plugin processes the messageToken2, verifies 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 received. 15. Participant1, having completed the authentication of Participant2, calls the operation get_shared_secret to retrieve the SharedSecret, which is used with the other Plugins to create Tokens to exchange with Participant2. 16. Participant1, having completed the authentication of Participant2, calls the operation get_peer_permissions_credential to retrieve the PermissionsCredential associated with Participant2, which is used with the AccessControl plugin to determine the permissions that Participant1 will grant to Participant2. 17. Participant2, having completed the authentication of Participant1, calls the operation get_shared_secret to retrieve the SharedSecret, which is used with the other Plugins to create Tokens to exchange with Participant1. 18. Participant2, having completed the Authentication of Participant1, calls the operation get_peer_permissions_credential to retrieve the PermissionsCredential associated with Participant2 which is used with the AccessControl plugins to determine the permissions that Participant2 will grant to Participant1. 8.8.3 AccessControl behavior with local domain entity creation The figure below illustrates the functionality of the security plugins with regards to the creation of local DDS domain entities: Topic, DataWriter, and DataReader entities.
- 130. 120 DDS Security v1.0 Beta1 sd DDS::Security-LocalParticipantAccess DDSApplication DataWriter DataReader AccessControlTopic DDS-SecureDiscoveryDDS-RegularDiscovery «create» check_create_topic() :Boolean «create» check_create_datawriter() :Boolean get_endpoint_sec_attributes() :Boolean configure() «create» check_create_datareader() :Boolean get_endpoint_sec_attributes() :Boolean configure() register_instance() check_local_datawriter_register_instance() :Boolean dispose_instance() check_local_datawriter_dispose_instance() :Boolean Figure 24 – AccessControl sequence diagram with local entities 1. The DDS application initiates the creation of a new Topic for the DomainParticpant. 2. The middleware verifies the DomainParticipant 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. Operation 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 middleware calls AccessControl::get_endpoint_sec_attributes to obtain the EndpointSecurityAttributes for the created DataWriter. 6. This sequence diagram illustrates the situation where the EndpointSecurityAttributes for the created DataWriter has the is_discovery_protected attribute set to FALSE. In this situation the middleware configures Discovery to use regular (not secure) publications discovery endpoint (DCPSPublications) to propagate the PublicationBuiltinTopicData for the created DataWriter.
- 131. DDS Security v1.0 Beta 1 121 7. The DDS application initiates the creation of a local DataReader. 8. 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. 9. The middleware calls the operation AccessControl::get_endpoint_sec_attributes to obtain the EndpointSecurityAttributes for the created DataReader entity. 10. This sequence diagram illustrates the situation where the EndpointSecurityAttributes for the created DataReader has the is_discovery_protected attribute set to TRUE. In this situation the middleware configures Discovery to use the secure subscriptions discovery endpoint (DCPSSecureSubscritions) to propagate the SubscriptionBuiltinTopicData for the created DataReader. 11. The DDS application initiates the registration of a data instance on the DataWriter. 12. The middleware verifies that the DataWriter has the right permissions to register the instance. The operation AccessControl::check_local_datawriter_register_instance() is called for this verification. If the verification doesn’t succeed, the instance is not registered. 13. The DDS application initiates the disposal of an instance of the DataWriter. 14. The middleware verifies that the DataWriter has the right permissions to dispose the instance. The operation AccessControl::check_local_datawriter_dispose_instance() is called for this verification. If the verification doesn’t succeed, the instance is not disposed. 8.8.4 AccessControl behavior with remote participant discovery If the ParticipantSecurityAttributes object returned by the AccessControl operation get_participant_sec_attributes has the is_access_protected attribute set to FALSE, the DomainParticipant may discover DomainParticipants that cannot be authenticated because they either lack support for the authentication protocol or they fail the authentication protocol. These “Unauthenticated” DomainParticipant entities shall be matched and considered “Unauthenticated” DomainParticipant entities. If the DomainParticipant discovers a DomainParticipant entity that it can authenticate successfully, then it shall validate with the AccessControl plugin that it has the permissions necessary to join the DDS domain: If the validation succeeds, the discovered DomainParticipant shall be considered “Authenticated” and all the builtin Topics automatically matched. If the validation fails, the discovered DomainParticipant shall be considered ignored and all the builtin Topics should not be matched.
- 132. 122 DDS Security v1.0 Beta1 The figure below illustrates the functionality of the security plugins with regards to the discovery of remote DomainParticipant entity that has been successfully authenticated by the Authentication plugin. sd DDS::Security-RemoteParticipantAccess Participant1 AccessControl DDS-Discovery Participant2 discoveredParticipant(Participant2) Authentication Process() : PermissionsCredentialTokenvalidate_remote_permissions(PermissionsCredentialToken) : PermissionsHandle check_remote_participant(PermissionsHandle) :Boolean discoveredTopic() check_remote_topic(PermissionsHandle) :Boolean Figure 25 – AccessControl sequence diagram with discovered DomainParticipant 1. The DomainParticipant Participant1 discovers the DomainParticipant (Participant2) via the discovery protocol and successfully authenticates Participant2 and obtains the PermissionsCredential as described in 8.8.2. 2. Participant1 calls the operation validate_remote_permissions to validate the permissions of Participant2, passing the PermissionsToken obtained via discovery from Participant2 and the PermissionsCredential returned by the operation get_peer_permissions_credential on the Authentication plugin. The operation validate_remote_permissions returns a PermissionsHandle, which the middleware will use whenever an access control decision must be made for the remote DomainParticipant. 3. Participant1 calls the operation check_remote_participant to verify the remote DomainParticipant (Participant2) is allowed to join the DDS domain with the specified domainId, passing the PermissionsHandle returned by the validate_remote_permissions operation. If the verification fails, the remote DomainParticipant is ignored and all the endpoints corresponding to the builtin Topics are unmatched. 4. Participant1 discovers that DomainParticipant (Participant2) has created a new DDS Topic. 5. Participant1 verifies that the remote DomainParticpant (Participant2) has the permissions needed to create a DDS Topic with name topicName. The operation check_remote_topic is called for this verification. If the verification fails, the discovered Topic is ignored.
- 133. DDS Security v1.0 Beta 1 123 8.8.5 AccessControl behavior with remote domain entity discovery This sub clause describes the functionality of the AccessControl plugin relative to the discovery of remote domain entities, that is, Topic, DataWriter, and DataReader entities. If the ParticipantSecurityAttributes object returned by the AccessControl operation get_participant_sec_attributes has the is_access_protected attribute set to FALSE, the DomainParticipant may have matched a remote “Unauthenticated” DomainParticipant, i.e., a DomainParticipant that has not authenticated successfully and may therefore discover endpoints via the regular (non-secure) discovery endpoints from an “Unauthenticated” DomainParticipant. 8.8.5.1 AccessControl behavior with discovered endpoints from “Unauthenticated” DomainParticipant If the DomainParticipant discovers endpoints from an “Unauthenticated” DomainParticipant it shall: Match automatically the local endpoints for whom the EndpointSecurityAttributes object returned by the operation get_endpoint_sec_attributes have the attribute is_access_protected set to FALSE. Not match automatically the local endpoints for whom the EndpointSecurityAttributes object returned by the operation get_endpoint_sec_attributes have the attribute is_access_protected set to TRUE. Note that, as specified in 8.8.2.2, a DomainParticipant for whom the ParticipantSecurityAttributes object returned by the AccessControl operation get_participant_sec_attributes has the is_access_protected attribute set to TRUE, cannot be matched with an “Unauthenticated” DomainParticipant and therefore cannot discover any endpoints from an “Unauthenticated” DomainParticipant. 8.8.5.2 AccessControl behavior with discovered endpoints from “Authenticated” DomainParticipant If the DomainParticipant discovers endpoints from an “authenticated” DomainParticipant it shall: Match automatically the local endpoints for whom the EndpointSecurityAttributes object returned by the operation get_endpoint_sec_attributes has the is_access_protected attribute set to FALSE. Perform the AccessControl checks for discovered endpoints that would match local endpoints for whom the is_access_protected attribute is set to TRUE, and only match the discovered endpoints for whom the access control checks succeed. The figure below illustrates the behavior relative to discovered endpoints coming from an “Authenticated” DomainParticipant that would match local endpoints for whom the is_access_protected attribute set to FALSE.
- 134. 124 DDS Security v1.0 Beta1 sd DDS::Security-RemoteEndpoint-UnprotectedAccess AccessControl DDS-Discovery DDS-ProtocolDataReader1 DataWriter1 Entities with is_access_protected = FALSE discoveredDatawriter() newInstance() disposedInstance() Sample() RTPS_Heartbeat_Gap() discoveredDatareader() RTPS_AckNack() Figure 26 – AccessControl sequence diagram with discovered entities when is_access_protected==FALSE 1. DataReader1 discovers via the discovery protocol that a remote DataWriter (DataWriter2) on a Topic with name topicName. The DataReader1 shall not call any operations on the AccessControl plugin and shall proceed to match DataWriter2 subject to the matching criteria specified in the DDS and DDS-XTypes specifications. check_remote_datawriter to verify that Partcipant2 has the permissions needed to publish the DDS Topic with name topicName. 2. DataReader1 receives a Sample from DataWriter2 with DDS ViewState NEW, indicating this is the first sample for that instance received by the DataReader. This sample shall be processed according to the DDS specification without any calls to the AccessControl plugin. 3. DataReader1 receives a Sample from DataWriter2 with DDS InstanceState NOT_ALIVE_DISPOSED, indicating the remote DataWriter disposed an instance. This sample shall be processed according to the DDS specification without any calls to the AccessControl plugin. 4. DataReader1 receives a Sample from DataWriter2 with DDS ViewState NOT_NEW. DataReader1 shall operate according to the DDS and DDS-RTPS specifications without any calls to the AccessControl plugin. 5. DataReader1 receives a RTPS HeartBeat message or a RTPS Gap message from DataWriter2. In both these cases DataReader1 shall operate according to the DDS and DDS-RTPS specifications without any calls to the AccessControl plugin. 6. DataWriter1 discovers via the discovery protocol that a remote DataReader (DataReader2) on a Topic with name topicName. DataWriter1 shall not call any
- 135. DDS Security v1.0 Beta 1 125 operations on the AccessControl plugin and shall to match DataWriter2 subject to the matching criteria specified in the DDS and DDS-XTypes specifications. 7. DataWriter1 receives an RTPS AckNack message from DataReader2. DataReader1 shall operate according to the DDS and DDS-RTPS specifications without any calls to the AccessControl plugin. The figure below illustrates the behavior relative to discovered endpoints coming from an “Authenticated” DomainParticipant that would match local endpoints for whom the is_access_protected attribute set to TRUE. sd DDS::Security-RemoteEndpoint-ProtectedAccess AccessControl DDS-Discovery DDS-ProtocolDataReader2 DataWriter2 Entities with is_access_protected=TRUE discoveredDatawriter() check_remote_datawriter() :Boolean newInstance()check_remote_datawriter_register_instance() :Boolean disposedInstance()check_remote_datawriter_dispose_instance() :Boolean Sample() RTPS_Heartbeat_Gap() discoveredDatareader() check_remote_datareader() :Boolean RTPS_AckNack() Figure 27 – AccessControl sequence diagram with discovered entities when is_access_protected==TRUE 1. DataReader1 discovers via the discovery protocol a remote DataWriter (DataWriter2) on a Topic with name topicName that matches the DataReader1 Topic topicName. 2. DataReader1 shall call the operation check_remote_datawriter to verify that Partcipant2 (the DomainParticipant to whom DataWriter2 belongs) has the permissions needed to publish the DDS Topic with name topicName. As an optional behavior, the same operation can also verify if the DataWriter2 is allowed to tag data with dataTag that are associated with it. 1. If the verification doesn’t succeed, the DataWriter2 is ignored. 2. If the verification succeeds, DataReader1 shall proceed to match DataWriter2 subject to the matching criteria specified in the DDS and DDS-XTypes specifications. 3. DataReader1 receives a Sample from DataWriter2 with DDS ViewState NEW, indicating this is the first sample for that instance received by the DataReader. This sample shall be processed according to the DDS specification without any calls to the AccessControl plugin.
- 136. 126 DDS Security v1.0 Beta1 4. DataReader1 shall call the operation check_remote_datawriter_register_instance to verify that Participant2 has the permissions needed to register the instance. If the verification doesn’t succeed, the sample shall be ignored. 5. DataReader1 receives a Sample from DataWriter2 with DDS InstanceState NOT_ALIVE_DISPOSED, indicating the remote DataWriter disposed an instance. 6. DataReader1 shall call the operation check_remote_datawriter_dispose_instance to verify that Participant2 has the permissions needed to dispose the instance. If the verification doesn’t succeed, the instance disposal shall be ignored. 7. DataReader1 receives a Sample from DataWriter2 with DDS ViewState NOT_NEW, indicating this DataReader1 already received samples on that instance. This sample shall be processed according to the DDS specification without any calls to the AccessControl plugin. 8. DataReader1 receives a RTPS HeartBeat message or a RTPS Gap message from DataWriter2. In both these cases DataReader1 shall operate according to the DDS and DDS-RTPS specifications without any calls to the AccessControl plugin. 9. DataWriter1 discovers via the discovery protocol a remote DataReader (DataReader2) on a Topic with name topicName that matches the DataReader1 Topic topicName. 10. DataWriter1 shall call the operation check_remote_datareader to verify that Partcipant2 (the DomainParticipant to whom DataReader2 belongs) has the permissions needed to subscribe the DDS Topic with name topicName. As an optional behavior, the same operation can also verify if the DataReader2 is allowed to read data with dataTag that are associated with DataWriter1. 1. If the verification doesn’t succeed, DataReader2 is ignored. 2. If the verification succeeds, DataWriter1 shall proceed to match DataReader2 subject to the matching criteria specified in the DDS and DDS-XTypes specifications. 11. DataWriter1 receives an RTPS AckNack message from DataReader2. DataReader1 shall operate according to the DDS and DDS-RTPS specifications without any calls to the AccessControl plugin. 8.8.6 Cryptographic Plugin key generation behavior Key Generation is potentially needed for: The DomainParticipant as a whole Each DomainParticipant match pair Each builtin secure endpoint (DataWriter or DataReader) Each builtin secure endpoint match pair Each application secure endpoint (DataWriter or DataReader) Each application secure endpoint match pair 8.8.6.1 Key generation for the BuiltinParticipantVolatileMessageSecureWriter and BuiltinParticipantVolatileMessageSecureReader The BuiltinParticipantVolatileMessageSecureWriter and BuiltinParticipantVolatileMessageSecureReader endpoints are special in that they are the ones used to securely send the Crytpo Tokens. Therefore the key material needed to secure this channel has to be
- 137. DDS Security v1.0 Beta 1 127 derivable from the SharedSecret without having access to Crytpo Tokens returned by the create_local_datawriter_crypto_tokens or create_local_datareader_crypto_tokens. Effectively this means the key material used for key-exchange is always derived from the SharedSecret. For the BuiltinParticipantVolatileMessageSecureWriter the creation of the key material necessary to communicate with a matched BuiltinParticipantVolatileMessageSecureReader shall complete during the operation register_matched_remote_datareader and the DDS middleware shall not call the operation create_local_datawriter_crypto_tokens or the operation set_remote_datareader_crypto_tokens on the CryptoKeyExchange. For the BuiltinParticipantVolatileMessageSecureReader the creation of the key material necessary to communicate with a matched BuiltinParticipantVolatileMessageSecureWriter shall complete during the operation register_matched_remote_datawriter and the DDS middleware shall not call the operation create_local_datareader_crypto_tokens or the operation set_remote_datawriter_crypto_tokens on the CryptoKeyExchange. The DDS implementation shall add a property with name “dds.sec.builtin_endpoint_name” and value “BuiltinParticipantVolatileMessageSecureWriter” to the Property passed to the operation register_local_datawriter when it registers the BuiltinParticipantVolatileMessageSecureWriter with the CryptoKeyFactory. The DDS implementation shall add a property with name “dds.sec.builtin_endpoint_name” and value “BuiltinParticipantVolatileMessageSecureReader” to the Property passed to the operation register_local_datareader when it registers the BuiltinParticipantVolatileMessageSecureReader with the CryptoKeyFactory. Setting the Property as described above allows the CryptoKeyFactory to recognize the BuiltinParticipantVolatileMessageSecureWriter and the BuiltinParticipantVolatileMessageSecureReader. 8.8.6.2 Key generation for the DomainParticipant For each local DomainParticipant that is successfully created the DDS implementation shall call the operation register_local_participant on the KeyFactory. For each discovered DomainParticipant that has successfully authenticated and has been matched to the local DomainParticipant the DDS middleware shall call the operation register_matched_remote_participant on the KeyFactory. Note that this operation takes as one parameter the SharedSecret obtained from the Authentication plugin. 8.8.6.3 Key generation for the builtin endpoints For each DataWriter belonging to list of “Builtin Secure Endpoints”, see 7.4.5, with the exception of the BuiltinParticipantVolatileMessageSecureWriter, the DDS middleware shall call the operation create_local_datawriter_crypto_tokens on the KeyFactory to obtain the DatawriterCryptoHandle for the builtin DataWriter. For each DataReader belonging to list of “Builtin Secure Endpoints”, see 7.4.5, with the exception of the BuiltinParticipantVolatileMessageSecureReader, the DDS middleware shall call the operation
- 138. 128 DDS Security v1.0 Beta1 create_local_datareader_crypto_tokens on the KeyFactory to obtain the DatareaderCryptoHandle for the corresponding builtin DataReader. For each discovered DomainParticipant that has successfully authenticated and has been matched to the local DomainParticipant the DDS middleware shall: 1. Call the operation KeyFactory::register_matched_remote_datawriter for each local DataWriter belonging to the “Builtin Secure Endpoints” passing it the local DataWriter and the corresponding remote DataReader belonging to the “Builtin Secure Endpoints” of the discovered DomainParticipant. 2. Call the operation KeyFactory::register_matched_remote_datareader for each local DataReader belonging to the “Builtin Secure Endpoints” passing it the local DataReader , the corresponding remote DataWriter belonging to the “Builtin Secure Endpoints” of the discovered DomainParticipant, and the SharedSecret obtained from the Authentication plugin. 8.8.6.4 Key generation for the application-defined endpoints Recall that for each application-defined (non-builtin) DataWriter and DataReader successfully created by the DDS Application the DDS middleware has an associated EndpointSecurityAttributes object which is the one returned by the AccessControl::get_endpoint_sec_attributes. For each non-builtin DataWriter for whom the associated EndpointSecurityAttributes object has either the member is_submessage_protected or the member is_payload_protected set to TRUE, the DDS middleware shall: 1. Call the operation create_local_datawriter_crypto_tokens on the KeyFactory to obtain the DatawriterCryptoHandle for the DataWriter. 2. Call the operation register_matched_remote_datawriter for each discovered DataReader that matches the DataWriter. For each non-builtin DataReader for whom the associated EndpointSecurityAttributes object has either the member is_submessage_protected or the member is_payload_protected set to TRUE, the DDS middleware shall: 1. Call the operation create_local_datareader_crypto_tokens on the KeyFactory to obtain the DatareaderCryptoHandle for the DataReader. 2. Call the operation register_matched_remote_datawriter for each discovered DataReader that matches the DataWriter. 8.8.7 Cryptographic Plugin key exchange behavior Cryptographic key exchange is potentially needed for: Each DomainParticipant match pair Each builtin secure endpoint match pair Each application secure endpoint match pair
- 139. DDS Security v1.0 Beta 1 129 8.8.7.1 Key Exchange with discovered DomainParticipant Cryptographic key exchange shall occur between each DomainParticipant and each discovered DomainParticipant that has successfully authenticated. This key exchange propagates the key material related to encoding/signing/decoding/verifying the whole RTPS message. In other words the key material needed to support the CryptoTransform operations encode_rtps_message and decode_rtps_message. Given a local DomainParticipant the DDS middleware shall: 1. Call the operation create_local_participant_crypto_tokens on the KeyFactory for each discovered DomainParticipant that has successfully authenticated and has been matched to the local DomainParticipant. This operation takes as parameters the local and remote ParticipantCryptoHandle. 2. Send the ParticipantCryptoTokenSeq returned by operation create_local_participant_crypto_tokens to the discovered DomainParticipant using BuiltinParticipantVolatileMessageSecureWriter. The discovered DomainParticipant shall call the operation set_remote_participant_crypto_tokens passing the ParticipantCryptoTokenSeq received by the BuiltinParticipantVolatileMessageSecureWriter. The figure below illustrates the functionality of the Cryptographic KeyExchange plugins with regards to the discovery and match of an authenticated remote DomainParticipant entity. sd DDS::Security-Kx-Participant DDS-Discovery DDS-ProtocolParticipant1 Participant2 «interface» :CryptoKeyExchange «interface» CryptoKeyFactory «interface» :CryptoKeyExchange discoveredParticipant(Participant1) discoveredParticipant(Participant2) register_matched_remote_participant() :ParticipantCryptoHandle create_local_participant_crypto_tokens() :Boolean send(BuiltinParticipantVolatileMessageSecureWriter) receive(BuiltinParticipantVolatileMessageSecureReader) set_remote_participant_crypto_tokens() : Boolean Figure 28 – Cryptographic KeyExchanage plugin sequence diagram with discovered DomainParticipant 1. Participant2 discovers the DomainParticipant (Participant1) via the DDS discovery protocol. This sequence is not described here as it equivalent to the sequence that Participant1 performs when it discovers Participant2.
- 140. 130 DDS Security v1.0 Beta1 2. Participant1 discovers the DomainParticipant (Participant2) via the DDS discovery protocol. Participant2 is authenticated and its permissions are checked as described in 8.8.2 and 8.8.4. This is not repeated here. The authentication and permissions checking resulted in the creation of an IdentityHandle, a PermissionsHandle, and a SharedSecretHandle for Participant2. 3. Participant1 calls the operation register_matched_remote_participant on the Cryptographic plugin (CryptoKeyFactory interface) to store the association of the remote identity and the SharedSecret. 4. Participant1 calls the operation create_local_participant_crypto_tokens on the Cryptographic plugin (CryptoKeyExchange interface) to obtain a collection of CriptoToken (cryptoTokensParticipant1ForParticipant2) to send to the remote DomainParticipant (Participant2). 5. Participant1 sends the collection of CryptoToken objects (cryptoTokensParticipant1ForParticipant2) to Participant2 using the BuiltinParticipantVolatileMessageSecureWriter. 6. Participant2 receives the CryptoToken objects (cryptoTokensParticipant1ForParticipant2) and calls the operation set_remote_participant_crypto_tokens()to register the CryptoToken sequence with the DomainParticipant. This will enable the Cryptographic plugin on Participant2 to decode and verify MACs on the RTPS messages sent by Participant1 to Participant2. 8.8.7.2 Key Exchange with remote DataReader Cryptographic key exchange shall occur between each builtin secure DataWriter and the matched builtin secure DataReader entities of authenticated matched DomainParticipant entities, see 7.4.5, with the exception of the BuiltinParticipantVolatileMessageSecureReader. Cryptographic key exchange shall also occur between each application DataWriter whose EndpointSecurityAttributes object has either the is_submessage_protected or the is_payload_protected members set to TRUE, and each of its matched DataReader entities. Given a local DataWriter that is either a builtin secure DataWriter or an application DataWriter meeting the condition stated above the DDS middleware shall: 1. Call the operation create_local_datawriter_crypto_tokens on the KeyFactory for each matched DataReader. This operation takes as parameters the local DatawriterCryptoHandle and the remote DatareaderCryptoHandle. 2. Send the DatawriterCryptoTokenSeq returned by operation create_local_ datawriter_crypto_tokens to the discovered DomainParticipant using BuiltinParticipantVolatileMessageSecureWriter. The matched DataReader shall call the operation set_remote_datawriter_crypto_tokens passing the DatawriterCryptoTokenSeq received by the BuiltinParticipantVolatileMessageSecureWriter.
- 141. DDS Security v1.0 Beta 1 131 The figure below illustrates the functionality of the Cryptographic KeyExchange plugin with regards to the discovery and match of a local secure DataWriter and a matched DataReader. sd DDS::Security-Kx-Reader Participant1 DDS-Discovery DDS-Protocol Participant2 «interface» CryptoKeyExchange «interface» CryptoKeyFactory discoveredDatawriter(Participant1, Writer1) discoveredDatareader(Participant2, Reader2) register_matched_remote_datareader() :DatareaderCryptoHandle create_local_datawriter_crypto_tokens() :Boolean send(BuiltinParticipantVolatileSecureMessage ) receive(BuiltinParticipantVolatileSecureMessage ) set_remote_datawriter_crypto_tokens() :Boolean Figure 29 – Cryptographic KeyExchanage plugin sequence diagram with discovered DataReader 1. Participant2 discovers a DataWriter (Writer1) belonging to Participant1 that matches a local DataReader (Reader2) according to the constraints in the DDS security specification. 2. Participant1 discovers a DataReader (Reader2) belonging to Participant2 that matches a local DataWriter (Writer1) according to the constraints in the DDS security specification. 3. Participant1 calls the operation register_matched_remote_datareader as stated in 8.8.6. 4. Partcipant1 calls the operation create_local_datawriter_crypto_tokens on the CryptoKeyExchange to obtain a collection of CriptoToken objects (cryptoTokensWriter1ForReader2). 5. Participant1 sends the collection of CryptoToken objects (cryptoTokensWriter1ForReader2) to Participant2 using the BuiltinParticipantVolatileMessageSecureWriter. 6. Participant2 receives the CryptoToken objects (cryptoTokensWriter1ForReader2) and calls the operation set_remote_ datawriter_crypto_tokens()to register the CryptoToken sequence with the DataWriter (Writer1). This will enable the Cryptographic plugin on Participant2 to decode and verify MACs on the RTPS submessages and data payloads sent from Writer1to Reader2. 8.8.7.3 Key Exchange with remote DataWriter Cryptographic key exchange shall occur between each builtin secure DataReader and the matched builtin secure DataWriter entities of authenticated matched DomainParticipant entities, see 7.4.5, with the exception of the BuiltinParticipantVolatileMessageSecureReader.
- 142. 132 DDS Security v1.0 Beta1 Cryptographic key exchange shall also occur between each application DataReader whose EndpointSecurityAttributes object has the is_submessage_protected member set to TRUE, and each of its matched DataWriter entities. Given a local DataReader that is either a builtin secure DataReader or an application DataReader meeting the condition stated above the DDS middleware shall: 1. Call the operation create_local_datareader_crypto_tokens on the KeyFactory for each matched DataWriter. This operation takes as parameters the local DatareaderCryptoHandle and the remote DatawriterCryptoHandle. 2. Send the DatareaderCryptoTokenSeq returned by operation create_local_ datareader_crypto_tokens to the discovered DomainParticipant using BuiltinParticipantVolatileMessageSecureWriter. The matched DataWriter shall call the operation set_remote_datareader_crypto_tokens passing the DatareaderCryptoTokenSeq received by the BuiltinParticipantVolatileMessageSecureWriter. The figure below illustrates the functionality of the Cryptographic KeyExchange plugin with regards to the discovery and match of a local secure DataReader and a matched DataWriter. Cryptographic key exchange shall occur between each DataReader whose EndpointSecurityAttributes has the is_submessage_protected members set to TRUE and each of its matched DataWriter entities. sd DDS::Security-Kx-Writer Participant1 DDS-Discovery DDS-Protocol Participant2 «interface» CryptoKeyExchange «interface» CryptoKeyFactory discoveredDatareader(Participant2, Reader2) discoveredDatawriter(Participant1, Writer1) register_matched_remote_datawriter() :DatawriterCryptoHandle create_local_datareader_crypto_tokens() :Boolean send(BuiltinParticipantVolatileSecureMessageWriter) receive(receive(BuiltinParticipantVolatileSecureMessageReader) set_remote_datareader_crypto_tokens() :Boolean Figure 30 – Cryptographic KeyExchanage plugin sequence diagram with discovered DataWriter 1. Participant1 discovers a DataReader (Reader2) belonging to Participant2 that matches a local DataWriter (Writer1) according to the constraints in the DDS security specification. 2. Participant2 discovers a DataWriter (Writer1) belonging to Participant1 that matches a local DataReader (Reader2) according to the constraints in the DDS security specification.
- 143. DDS Security v1.0 Beta 1 133 3. Participant2 calls the operation register_matched_remote_datawriter as stated in 8.8.6. 4. Partcipant2 calls the operation create_local_datareader_crypto_tokens on the CryptoKeyExchange to obtain a collection of CriptoToken objects (cryptoTokensReader2ForWriter1). 5. Participant2 sends the collection of CryptoToken objects (cryptoTokensReader2ForWriter1) to Participant1 using the BuiltinParticipantVolatileMessageSecureWriter. 6. Participant1 receives the CryptoToken objects (cryptoTokensReader2ForWriter1) and calls the operation set_remote_ datareader_crypto_tokens()to register the CryptoToken sequence with the DataWriter (Writer1). This will enable the Cryptographic plugin on Participant1 to decode and verify MACs on the RTPS submessages sent from Reader2 to Writer1. 8.8.8 Cryptographic Plugins encoding/decoding behavior This sub clause describes the behavior of the DDS implementation related to the CryptoTransform interface. This specification does not mandate a specific DDS implementation in terms of the internal logic or timing when the different operations in the CryptoTransform plugin are invoked. The sequence charts below just express the requirements in terms of the operations that need to be called and their interleaving. This specification only requires that by the time the RTPS message appears on the wire the proper encoding operations have been executed first on each SerializedData submessage element, then on the enclosing RTPS Submessage, and finally on the RTPS Message. Similarly by the time a received RTPS Message is interpreted the proper decoding operations are executed on the reverse order. First on the encoded RTPS Message, then on each SecureSubMsg, and finally on each SecuredPayload submessage element. 8.8.8.1 Encoding/decoding of a single writer message on an RTPS message The figure below illustrates the functionality of the security plugins with regards to encoding the data, Submessages and RTPS messages in the situation where the intended RTPS Message contains a single writer RTPS Submessage.
- 144. 134 DDS Security v1.0 Beta1 sd DDS::Security-Xform-Writer DDSApplication «interface» :CryptoTransform DDS-Protocol Participant2 DataWriter Participant1 DataReader «interface» :CryptoTransform write() encode_serialized_data() :Boolean notify_data() encode_datawriter_submessage() :Boolean encode_rtps_message() :Boolean send(RTPS encoded message) decode_rtps_message() :boolean preprocess_rtps_submessage() :boolean decode_datawriter_submessage() :boolean on_data() decode_serialized_data() :boolean Figure 31 – Cryptographic CryptoTransform plugin sequence diagram for encoding/decoding a single DataWriter submessage 1. The application writes data using a DataWriter belonging to Participant1. The DDS implementation serializes the data. 2. The DataWriter in Participant1 constructs the SerializedData RTPS submessage element and calls the operation encode_serialized_data. This operation creates a RTPS SecData that protects the SerializedData potentially encrypting it, adding a MAC and/or digital signature. 3. This step is notional; the specific mechanism depends on the DDS Implementation. Participant1 realizes it is time to send the data written by the DataWriter to a remote DataReader in Participant2. 4. Participant1 constructs the RTPS Data Submessage to send to the DataReader and calls the operation 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 parameters 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. Participant1 constructs the RTPS Message it intends to send to the DataReader (or readers). It then calls encode_rtps_message to transform the original RTPS Message
- 145. DDS Security v1.0 Beta 1 135 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. Participant1 sends the new “encoded” RTPS Message obtained as a result of the previous step to Participant2. 7. Participant2 receives the “encoded” RTPS Message. Participant2 parses the message and detects a RTPS SecureSubMsg with the MultiSubmsgFlag (see 7.3.6.2) set to true. This indicates it shall call the operation 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. Participant2 encounters parses the RTPS Message resulting from the previous step and encounters a RTPS SecureSubMsg with the MultiSubmsgFlag (see 7.3.6.2) set to false. This indicates it shall call the operation prepare_rtps_submessage to determine whether this is a Writer submessage or a Reader submessage and obtain the DatawriterCryptoHandle and DatareaderCryptoHandle handles it needs to decode the message. This function determines it is a Writer submessage. 9. Participant2 calls the operation 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 SecuredPayload 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. Participant2 realizes it is time to notify the DataReader and retrieve the actual data sent by the DataWriter. 11. Participant2 calls decode_serialized_data passing in the RTPS SecuredPayload 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 step 8. 8.8.8.2 Encoding/decoding of multiple writer messages on an RTPS message The figure below illustrates the functionality of the security plugins in the situation where the intended RTPS message contains a multiple DataWriter RTPS Submessages, which can represent multiple samples, from the same DataWriter or from multiple DataWriter entities, as well as, a mix of Data, Heartbeat, Gap, and any other DataWriter RTPS Submessage as defined in 7.3.1.
- 146. 136 DDS Security v1.0 Beta1 sd DDS::Security-Xform-Multiwriter DDSApplication «interface» :CryptoTransform DDS-Protocol Participant2 DataWriter Participant1 DataReader «interface» :CryptoTransform write() encode_serialized_data() :Boolean write() encode_serialized_data() :Boolean notify_data() get_data_to_send() encode_datawriter_submessage(Data) :boolean encode_datawriter_submessage(Data) :boolean encode_datawriter_submessage(Heartbeat) :boolean encode_rtps_message() :Boolean send(RTPS encoded message) decode_rtps_message() :boolean preprocess_rtps_submessage() :boolean decode_datawriter_submessage() :boolean preprocess_rtps_submessage() :boolean decode_datawriter_submessage() :boolean preprocess_rtps_submessage() :boolean decode_datawriter_submessage() :boolean on_data() decode_serialized_data() :boolean decode_serialized_data() :boolean Figure 32 – Cryptographic CryptoTransform plugin sequence diagram for encoding/decoding multiple DataWriter submessages The steps followed to encode and decode multiple DataWriter Submessages within the same RTPS message are very similar to the ones used for a single Writer message. The only difference is that on the writer side can create multiple RTPS Submessages. In this case, Participant1 creates two Data Submessages and a Heartbeat Submessage, transforms each separately using the encode_datawriter_submessage, places them in the same RTPS message and then transforms the RTPS Message containing all the resulting SecureSubMsg submessages using encode_rtps_message. The steps followed to decode the message are the reverse ones. Note that the DataWriter entities that are sending the submessages and/or the DataReader entities that are the destination of the different Submessages may be different. In this situation each call to encode_serialized_data(), encode_datawriter_submessage(),
- 147. DDS Security v1.0 Beta 1 137 decode_datawriter_submessage(), and encode_serialized_data(), shall receive the proper DatawriterCryptoHandle and DatareaderCryptoHandle handles. 8.8.8.3 Encoding/decoding of multiple reader messages on an RTPS message The figure below illustrates the functionality of the security plugins in the situation where the intended RTPS message contains multiple DataReader RTPS submessages from the same DataReader or from multiple DataReader entities. These include AckNack and NackFrag RTPS Submessages as defined in 7.3.1. sd DDS::Security-Xform-Multireader DataReaderDataWriter «interface» :CryptoTransform DDS-ProtocolParticipant1 Participant2 «interface» :CryptoTransform get_acknack_to_send() get_acknack_to_send() encode_datareader_submessage() :boolean encode_datareader_submessage() :boolean encode_rtps_message() :boolean send(RTPS encoded message) decode_rtps_message() :Boolean preprocess_rtps_submessage() :Boolean decode_datareader_submessage() :Boolean on_acknack() preprocess_rtps_submessage() :Boolean decode_datareader_submessage() :Boolean on_acknack() Figure 33 -- Cryptographic CryptoTransform plugin sequence diagram for encoding/decoding multiple DataReader submessages 1. This step is notional; the specific mechanism depends on the DDS Implementation. Participant2 realizes it is time to send an AckNack or NackFrag submessage from DataReader to a remote DataWriter. 2. Participant2 constructs the AckNack (or any other DataReader RTPS Submessage) and calls the operation encode_datareader_submessage. This operation creates an RTPS SecureSubMsg that protects the original Submessage potentially encrypting it, adding a MAC and/or digital signature. This operation shall receive as parameter the DatareaderCryptoHandle of the DataReader that sends the submessage and a list of DatawriterCryptoHandle handles of all the DataWriter entities to which the Submessage will be sent. 3. Step 2 may be repeated multiple times constructing various SecureSubMsg submessages from different DataReader RTPS Submessages. Different submessages may
- 148. 138 DDS Security v1.0 Beta1 originate on different DataReader entities and/or be destined for different DataWriter entities. On each case the encode_datareader_submessage operation shall receive the DatareaderCryptoHandle and list of DatawriterCryptoHandle that correspond to the source and destinations of that particular Submessage. 4. Participant2 constructs the RTPS Message that contains the SecureSubMsg submessages obtained as a result of the previous steps. It shall then call encode_rtps_message to transform the “original” RTPS Message into another “encoded” RTPS Message containing a single SecureSubMsg with the MultiSubmsgFlag (see 7.3.6.2) set to true. 5. Participant2 sends the “encoded” RTPS Message to Participant1 (and any other destination DomainParticipant). 6. Participant1 receives the “encoded” RTPS Message. The DDS implementation parses the message and detects a RTPS SecureSubMsg with the MultiSubmsgFlag (see 7.3.6.2) set to true. This indicates it shall call the 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. Participant1 encounters parses the RTPS Message resulting from the previous step and encounters a RTPS SecureSubMsg with the MultiSubmsgFlag (see 7.3.6.2) set to false. This indicates it shall call 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. Participant1 calls 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. Participant1 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 MultiSubmsgFlag (see 7.3.6.2) set to false is processed in this same way. The operation prepare_rtps_submessage is first invoked and it indicates it is a DataReader submessage Participant1 shall call decode_datareader_submessage() on the submessage. 8.8.8.4 Encoding/decoding of reader and writer messages on an RTPS message The figure below illustrates the functionality of the security plugins with regards to encoding the data, Submessages and RTPS messages in the situation where the intended RTPS message contains multiple RTPS Submessages which can represent a mix of different kinds of DataWriter and DataReader submessages such as Data, Heartbeat, Gap, AckNack, NackFrag and any other RTPS Submessage as defined in 7.3.1.
- 149. DDS Security v1.0 Beta 1 139 sd DDS::Security-Xform-Multi-Reader-Writer DDSApplication «interface» :CryptoTransform DDS-Protocol Participant2Participant1 :DataReader:DataWriter :DataWriter:DataReader «interface» :CryptoTransform write() encode_serialized_data() :Boolean notify_data() get_data_to_send() encode_datawriter_submessage(Data) :boolean encode_datawriter_submessage(Heartbeat) :boolean get_acknack_to_send() encode_datareader_submessage(AckNack) :boolean encode_rtps_message() :Boolean send(RTPS encoded message) decode_rtps_message() :boolean preprocess_rtps_submessage() :boolean decode_datawriter_submessage() :boolean on_data() decode_serialized_data() :boolean preprocess_rtps_submessage() :boolean decode_datawriter_submessage() :boolean on_heartbeat() preprocess_rtps_submessage() :boolean decode_datareader_submessage() :Boolean on_acknack() Figure 34 – Cryptographic CryptoTransform plugin sequence diagram for encoding/decoding multiple DataWriter and DataReader submessages 1. The application writes data using a DataWriter belonging to Participant1. The DDS implementation serializes the data. 2. The DataWriter in Participant1 constructs the SerializedData RTPS submessage element and calls the operation encode_serialized_data. This operation creates a RTPS SecData that protects the SerializedData potentially encrypting it, adding a MAC and/or digital signature. 3. This step is notional; the specific mechanism depends on the DDS Implementation. Participant1 realizes it is time to send the data written by the DataWriter to a remote DataReader. 4. Participant1 constructs the RTPS Data Submessage that it will send to the DataReader and calls the operation 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. Participant1 decides it needs to send a Heartbeat submessage along with the Data submessage. It constructs the RTPS Heartbeat submessage and calls the operation encode_datawriter_submessage() to transform the original Heartbeat submessage to a SecureSubMsg.
- 150. 140 DDS Security v1.0 Beta1 6. This step is notional. The specific mechanism depends on the DDS Implementation. Participant1 decides it also wants 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. Participant1 constructs the RTPS AckNack submessage and calls encode_datareader_submessage to transform the original AckNack submessage to a SecureSubMsg. 8. Participant1 constructs the RTPS Message that contains the SecureSubMsg submessages obtained as a result of the previous steps. It shall then call encode_rtps_message. To transform the “original” RTPS Message into another “encoded” RTPS Message containing a single SecureSubMsg with the MultiSubmsgFlag (see 7.3.6.2) set to true. 9. Participant1 sends the “encoded” RTPS Message to Participant2 (and any other destination DomainParticipant). 10. Participant2 receives the “encoded” RTPS Message. Participant2 parses the message and detects a RTPS SecureSubMsg with the MultiSubmsgFlag (see 7.3.6.2) set to true. This indicates it shall call the 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. Participant2 parses the RTPS Message resulting from the previous step and encounters a RTPS SecureSubMsg with the MultiSubmsgFlag (see 7.3.6.2) set to false. This indicates it shall call 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. Participant1 calls the operation 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. 13. This step is notional; the specific mechanism depends on the DDS Implementation. The Participant2 realizes it is time to notify the DataReader of the arrival of data. 14. Participant2 calls decode_serialized_data passing in the RTPS SecuredPayload 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.
- 151. DDS Security v1.0 Beta 1 141 16. Step 12 is repeated, Participant2 calls 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. Participant2 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. Participant2 calls decode_datareader_submessage passing in the RTPS SecureSubMsg and obtains the original AckNack submessage that was the input to the encode_datareader_submessage on Participant1. This operation 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. Participant2 notifies DataWriter of the AckNack.
- 152. 142 DDS Security v1.0 Beta1 9 Builtin Plugins 9.1 Introduction This specification defines the behavior and implementation of at least one builtin plugin for each kind of plugin. The builtin plugins provide out-of-the-box interoperability between implementations of this specification. The builtin plugins are summarized in the table below: Table 28 – Summary of the Builtin Plugins SPI Plugin Name Description Authentication AccessControl Permissions document signed by shared Certificate Authority Cryptography AES128 for encryption (in counter mode) SHA1 and SHA256 for digest HMAC-SHA1 and HMAC-256 for MAC DataTagging Send Tags via Endpoint Discovery Logging 9.2 Requirements and Priorities (Non-Normative) The selection of the builtin plugins was driven by several functional, as well as, non-functional requirements, as described below. Most DDS users surveyed consider the following functional requirements as essential elements of a secure DDS middleware: Authentication of applications (DDS Domain Participants) joining a DDS Domain Access control of applications subscribing to specific data at the Domain and Topic level Message integrity and authentication Encryption of a data sample using different encryption keys for different Topics
- 153. DDS Security v1.0 Beta 1 143 In addition to these essential needs, many users also required that secure DDS middleware should provide for: Sending digitally signed data samples Sending data securely over multicast Tagging data Integrating with open standard security plugins Other functional requirements which are considered useful but less common were: Access control to certain samples within a Topic but not others, with 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 as defined by their permissions. Permissions that control which QoS might be used by a specific DDS Entity: DomainParticipant, Publisher, DataWriter, Subscriber, or DataReader. The primary non-functional requirements that informed the selection of the builtin 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 requirements 9.2.1 Performance and Scalability DDS is commonly deployed in systems that demand high performance and need to scale to large numbers 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) performed by the plugins should not adversely degrade system performance and scalability beyond what is tolerable and strictly needed. In practice this means several things for the builtin plugins: The use of Asymmetric Key Cryptography shall be limited to the discovery, authentication, session and shared-secret establishment phase (i.e., when a Participant discovers another Participant, a DataReader and matching DataWriter). To the extent possible it shall not be used in the critical path of data distribution. 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. Multicast shall be supported even for ciphered data.
- 154. 144 DDS Security v1.0 Beta1 9.2.2 Robustness and Availability DDS is deployed in mission-critical systems, which must continue to operate 24/7 despite partial system malfunction. DDS also operates in fielded environments where specific components or systems may be subject to accidental failure or active attack. DDS provides a highly robust infrastructure due to the way the communication model and protocols are defined as they can be (and commonly are) implemented in a peer-to-peer fashion without any centralized services. For this reason, many DDS implementations have no single points of failure. The builtin plugins should not negate these desirable properties present in the underlying DDS middleware 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 because they can be easily disrupted by disrupting just one party. Security tokens and keys should be compartmentalized as much as possible such that compromise of an application component is contained to that component itself. For example, selection of a system-wide secret key for the whole Domain or even for a Topic should be avoided. 9.2.3 Fitness to the DDS Data-Centric Model Application 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 must join and the Topics that the application needs to read and write. Therefore, the builtin plugins should offer the possibility 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 to dispose instances, filter by content, set QoS, and so forth. While it may be useful to offer ways to provide access controls to this as well, it was considered of lesser priority and potentially conflicting with the goal of ease of configurability and maintainability. The semantics of DDS communications require that individual samples can be consumed independently of each other. Depending on the QoS policy settings samples written by a single DataWriter may be received and processed out of order relative to the order sent, or may be received with intermediate 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 sample should be able to be processed in isolation, without requiring the receiver to maintain a specific context reconstructed from previous samples. 9.2.4 Leverage and Reuse of Existing Security Infrastructure and Technologies To the extent possible, it is desirable that the builtin plugins leverage and reuse existing IA technology and tools. This not only reduces the barrier of entry for implementers of the specification, but also more importantly enhances the quality of the result by allowing the use of proven, peer-reviewed, and/or already certified approaches. The builtin plugins leverage existing standards and tools for PKI,
- 155. DDS Security v1.0 Beta 1 145 ciphers, hashing and digital signing. To the extent possible, ideas and approaches from existing protocols for key management and secure multicast are also leveraged, although where appropriate they have been adapted to the data-centric communications model of DDS and the DDS-RTPS wire protocol. 9.2.5 Ease-of-Use while Supporting Common Application Requirements It is anticipated that specialized applications may need to develop their own security plugins to either integrate existing security infrastructure or meet specialized requirements. Therefore the primary consumers of the builtin plugins will be users who want to secure their systems but not have complex needs or significant legacy components. Under these conditions, ease-of-use is essential. A security infrastructure that is too hard to configure or too complex to understand or maintain is less likely to be used, or may be used wrongly, resulting in systems that are less secure overall. The builtin plugins balance rich functionality and ease-of-use, providing for the most common use cases, in a manner that is easy to understand and use correctly. 9.3 Builtin Authentication: DDS:Auth:PKI-RSA/DSA-DH This builtin 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 trusted Certificate Authority (CA). It performs mutual authentication between discovered participants using the Digital Signature Algorithm (DSA) [11] and establishes a shared secret using Diffie-Hellman (D-H) Key Agreement Method [12]. The CA could be an existing one. Or a new one could be created for the purpose of deploying applications on a DDS Domain. The nature or manner in which the CA is selected is not important because the way it is used enforces a shared recognition by all participating applications. Prior to a DomainParticipant being enabled the DDS:Auth:PKI-RSA/DSA-DH plugin associated with the DomainParticipant must be configured with three things: 1. The X.509 Certificate that defines the Shared CA. This certificate contains the 2048- bit RSA Public Key of the CA. 2. The 2048-bit RSA Private Key of the DomainParticipant. 3. An X.509 Certificate that chains up to the Shared CA , that binds the 2048-bit RSA Public Key of the DomainParticipant to the Distinguished Name (subject name) for the DomainParticipant and any intermediate CA certificates required to build the chain. 9.3.1 Configuration The specific format of the root CA certificate, the private key of the DomainParticipant, and the certificate for the DomainParticipant are not dictated by this specification. Implementations may use standard formats for certificates and keys and configure them using an API, an extended QoS Policy, or some other implementation-specific mechanism. Leaving the details of the DDS:Auth:PKI-RSA/DSA-DH plugin configuration unspecified does not affect interoperability and might be required to accommodate different security concerns and
- 156. 146 DDS Security v1.0 Beta1 platforms. For example, some platforms may provide specialized secure storage for holding private keys, others may not support a file system, etc. DomainParticipant entities should use Certificate Revocation Lists (CRLs) and/or OCSP to check for revoked certificates. 9.3.2 DDS:Auth:PKI-RSA/DSA-DH Types This sub clause specifies the content and format of the Credential and Token objects used by the DDS:Auth:PKI-RSA/DSA-DH plugin. Credential and Token attributes left unspecified in this specification shall be understood to not have any required values in this specification. These attributes shall be handled according to the following rules: Plugin implementations may place data in these attributes as long as they also include a property attribute that allows the implementation to unambiguously detect the presence and interpret these attributes. Attributes that are not understood shall be ignored. Property and BinaryProperty names shall comply with the rules defined in 7.2.1 and 7.2.2, respectively. The content of the Handle objects is not specified as it represents references to internal state that is only understood by the plugin itself. The DDS Implementation only needs to hold a reference to the retuned Handle objects returned by the plugin operations and pass these Handle references to other operations. 9.3.2.1 DDS:Auth:PKI-RSA/DSA-DH IdentityCredential The DDS:Auth:PKI-RSA/DSA-DH plugin shall set the attributes of the IdentityCredential objects as specified in the table below. Table 29 – IdentityCredential class for the builtin Authentication plugin Attribute name Attribute value class_id binary_value1 DomainParticipant binary_value2 binary_value1 9.3.2.2 DDS:Auth:PKI-RSA/DSA-DH IdentityToken The DDS:Auth:PKI-RSA/DSA-DH plugin shall set the attributes of the IdentityToken object as specified in the table below: Table 30 – IdentityToken class for the builtin Authentication plugin
- 157. DDS Security v1.0 Beta 1 147 Attribute name Attribute value class_id binary_value1 binary_value1 IdentityCredential 9.3.2.3 DDS:Auth:PKI-RSA/DSA-DH HandshakeMessageToken The DDS:Auth:PKI-RSA/DSA-DH plugin uses several HandshakeMessageToken object formats: HandshakeRequestMessageToken objects HandshakeReplyMessgeToken objects HandshakeFinalMessageToken objects 9.3.2.3.1 HandshakeRequestMessageToken objects The attributes in HandshakeRequestMessageToken objects shall be set as specified in the table below. References to the DomainParticipant within the table refer to the DomainParticipant that is sending the message that embeds the HandshakeRequestMessageToken. Table 31 – HandshakeRequestMessageToken for the builtin Authentication plugin Attribute name Attribute value class_id properties name dds.sec.identity value value IdentityCredential IdentityCredential value name dds.sec.permissions value binary_value1 PersimissionsCredential DomainParticipant PermissionsCredential binary_value1 binary_value1
- 158. 148 DDS Security v1.0 Beta1 9.3.2.3.2 HandshakeReplyMessageToken The attributes in the HandshakeReplyMessageToken objects are set as specified in the table below. References to the DomainParticipant within the table refer to the DomainParticipant that is sending the message that embeds the HandshakeReplyMessageToken. Table 32 – HandshakeReplyMessageToken for the builtin Authentication plugin Attribute name Attribute value class_id properties HandshakeRequestMessageToken DomainParticipant HandshakeRequestMessageToken binary_value1 binary_value2 binary_value1 HandshakeRequestMessageToken DomainParticipant HandshakeReplyMessageToken 9.3.2.3.3 HandshakeFinalMessageToken HandshakeFinalMessageToken objects are used to finish an authentication handshake and communicate a SharedSecret. The SharedSecret shall be a 256-bit random number generated using a cryptographically-strong random number generator. Each created HandshakeFinalMessageToken shall have associated a unique SharedSecret. The attributes in the HandshakeFinalMessageToken objects shall be set as specified in the table below. Table 33 – HandshakeFinalMessageToken for the builtin Authentication plugin Attribute name Attribute value class_id binary_value1 SharedSecret DomainParticipant HandshakeFinalMessageToken binary_value2
- 159. DDS Security v1.0 Beta 1 149 binary_value1 HandshakeReplyMessageToken binary_value1 HandshakeFinalMessageToken DomainParticipant HandshakeFinalMessageToken 9.3.3 DDS:Auth:PKI-RSA/DSA-DH plugin behavior The table below describes the actions that the DDS:Auth:PKI-RSA/DSA-DH plugin performs when each of the plugin operations is invoked. Table 34 – Actions undertaken by the operations of the bultin Authentication plugin validate_local_ide ntity This operation shall receive the participant_key associated with the local DomainParticipant whose identity is being validated. This operation shall receive the identity_credential containing an the IdentityCredential object with the contents described in 9.3.2.1. The operation shall verify the validity of the identity_credential 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. The operation shall return the 16-byte effective_participant_key computed as follows: The first bit (bit 0) shall be set to 1. The 47 bits following the first bit (bits 1 to 47) shall be set to the 47 first bits of the SHA-256 hash of the SubjectName appearing on the identity_credential The following 48 bits (bits 48 to 96) shall be set to the first 48 bits of the SHA-256 hash of the candidate_participant_key The remaining 32 bits (bits 97 to 127) shall be set identical to
- 160. 150 DDS Security v1.0 Beta1 the corresponding bits in the candidate_participant_key If successful, the operation shall return VALIDATION_OK. 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 9.3.2.2. set_permissions_cr edential_and_token This operation shall store the PermissionsCredentialToken and the PermissionsToken internally to the plugin and associate them with the DomainPartipant represented by the IdentityHandle. validate_remote_id entity The operation shall receive the 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 Authentication plugin of the remote DomainParticipant associated with the remote_participant_key. 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 the remote participant and associates it to the remote_identity_token and any additional information requied for the challenge protocol.
- 161. DDS Security v1.0 Beta 1 151 begin_handshake_re quest The operation shall receive the 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 9.3.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_MESSAGE. begin_handshake_re ply The operation shall receive the 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 to 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 verify the validity of the IdentityCredential contained in the property named “dds.sec.identity” found in the handshake_message_in HandshakeMessageToken. This verification shall be done using the locally configured CA in the same manner as the validate_local_identity operation. If the handshake_message_in does not contain the aforementioned property or the verification fails then the operation shall fail und return ValidationResult_Fail. The operation shall verify that the first bit of the participant_key is set to 1 and that the following 47 bits match the first 47 bits of
- 162. 152 DDS Security v1.0 Beta1 the SHA-256 hash of the SubjectName appearing in the IdentityCredential. If this verification fails the operation shall fail und return ValidationResult_Fail. The operation shall fill the handshake_message_out with a HandshakeReplyMessageToken object with the content specified in 9.3.2.3.2. 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 4. The property with name “dds.sec.permissions” found within the handshake_message_in if present The operation shall return VALIDATION_PENDING_CHALLENGE_MESSAGE. process_handshake on a handshake_handle created by begin_handshake_re quest The operation shall be called with the handshake_handle returned by a previous call to begin_handshake_request that returned VALIDATION_PENDING_CHALLENGE_MESSAGE. The handshake_message_in shall correspond to a HandshakeReplyMessageToken object received 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 in 9.3.2.3.2. The operation shall verify the validity of the IdentityCredential contained in the property named “dds.sec.identity” found in the handshake_message_in HandshakeMessageToken. This verification shall be done using the locally configured CA in the same manner as the validate_local_identity operation. If the handshake_message_in does not contain the aforementioned property or the verification fails, then the operation shall fail und return ValidationResult_Fail. The operation shall decrypt the contents of the binary_value2 using the Public Key of the remote participant associated with the
- 163. DDS Security v1.0 Beta 1 153 handshake_handle. The operation shall verify that the result of this decryption correspond the SHA256 of the binary_value1 attribute in the HandshakeRequestMessageToken associated with the handshake_handle. If the specified verification on the binary_value2 does not succeed, the operation shall return VALIDATION_FAILED. If the specified verification on the binary_value2 succeeds, then the operation shall generate a 256-bit random number to be used as a SharedSecret using a cryptographycally-strong random number generator. The operation shall create a HandshakeFinalMessageToken object with an associated SharedSecret as described in 9.3.2.3.3. The operation shall fill the handshake_message_out with the created HandshakeFinalMessageToken object. The operation shall store the value of property with name “dds.sec.permissions” found within the handshake_message_in, if present and associate it with the handshake_handle as the PermissionsCertificate of remote DomainParticipant. The operation shall save the SharedSecret in the hansdhake_handle and return VALIDATION_OK_WITH_FINAL_MESSAGE. process_handshake on a handshake_handle created by begin_handshake_re ply The operation shall be called with the handshake_handle returned by a previous call to begin_handshake_reply that retuned VALIDATION_PENDING_HANDSHAKE_MESSAGE. The handshake_message_in shall correspond to the one received as a reply to the handshake_message_out associated with the handshake_handle. If any of the above conditions 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 9.3.2.3.3. The contents of the handshake_message_in binary_value1 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. The contents of the handshake_message_in binary_value2 attribute shall be decrypted with the public key of the remote
- 164. 154 DDS Security v1.0 Beta1 participant and the operation shall verify that it contains the expected SHA-256 hash as described in 9.3.2.3.3. If the specified verification on the binary_value2 does not succeed the operation shall return VALIDATION_FAIL If specified verification on the binary_value2 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 a SharedSecretHandle that is internally associated with the SharedSecret stablished as part of the handshake. On failure the operation shall return nil. get_peer_permissio ns_credential_toke n 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 the PermissionsCredentialToken of the peer DomainParticipant associated with the handshake_handle. If the DomainParticipant initiated the handshake, then the peer PermissionsCredentialToken was received in the HandshakeReplyMessageToken, otherwise it was received in the HandshakeRequestMessageToken. In both cases the PermissionsCredentialToken appeared as the value of the property named “dds.sec.permissions”. On failure the operation shall return nil. set_listener This operation shall save a reference to the listener object and associate it with the specified IdentityHandle. return_identity_to ken This operation shall behave as specified in 8.3.2.9.13.
- 165. DDS Security v1.0 Beta 1 155 return_peer_permis sions_credential_t oken This operation shall behave as specified in 8.3.2.9.14. return_handshake_h andle This operation shall behave as specified in 8.3.2.9.15. return_identity_ha ndle This operation shall behave as specified in 8.3.2.9.16. return_sharedsecre t_handle This operation shall behave as specified in 8.3.2.9.17. 9.3.4 DDS:Auth:PKI-RSA/DSA-DH plugin authentication protocol The operations the Secure DDS implementation executes on the Authentication plugin combined with the behavior of the DDS:Auth:PKI-RSA/DSA-DH result in an efficient 3-message protocol that performs mutual authentication and establishes a shared secret. The rest of this sub clause describes the resulting protocol. The authentication protocol is symmetric, that is there are no client and server roles. But only one DomainParticipant should initiate the protocol. To determine which of the two DomainParticipant entities shall initiate the protocol, each DomainParticipant compares its own GUID with that of the other DomainParticipant. The DomainParticipant with the lower GUID (using lexicographical order) initiates the protocol. 9.3.4.1 Terms and notation The table below summarizes the terms used in the description of the protocol Table 35 – Terms used in the description of the builtin authentication protocol Term Meaning DomainParticipant begin_handshake_request HandshakeRequestMessageToken HandshakeReplyMessageToken HandshakeFinalMessageToken . begin_handshake_reply HandshakeRequestMessageToken HandshakeReplyMessageToken HandshakeFinalMessageToken
- 166. 156 DDS Security v1.0 Beta1 IdentityCertificate IdentityCertificate begin_handshake_request Authentication begin_handshake_reply Authentication The table below summarizes the notation and transformation functions used in the description of the protocol: Table 36 – Notation of the operations/transformations used in the description of the builtin authentication protocol Function / notation meaning . . 9.3.4.2 Protocol description The table below describes the resulting 3-way protocol that establishes authentication and a shared secret between Participant_A and Participant_B. Table 37 – Description of built-in authentication protocol HandshakeRequestMessageToken: (Cert_A, Challenge_A) HandshakeRequestMessageToken containing Cert_A, Challenge_A
- 167. DDS Security v1.0 Beta 1 157 HandshakeReplyMessageToken: ( Cert_B, Sign(Challenge_A), Challenge_B) HandshakeReplyMessageToken Sign(challenge_A) SharedSecret Encrypt(PubK_B, SharedSecret) SharedSecret HandshakeFinalMessageToken: ( Encrypt(PubK_B, SharedSecret), Sign( Hash( Challenge_B # Encrypt(PubK_B, SharedSecret)))) HandshakeFinalMessageToken Sign( Hash( Challenge_B # Encrypt(PubK_B, SharedSecret)))) PubK_A SharedSecret 9.4 Builtin Access Control: DDS:Access:PKI-Signed-XML-Permissions This builtin AccessControl plugin is referred to as the “DDS:Access:PKI-Signed-XML- Permissions” plugin.
- 168. 158 DDS Security v1.0 Beta1 The DDS:Access:PKI-Signed-XML-Permissions implements the AccessControl plugin API using a permissions 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 DDS Domain. The nature or manner in which the CA is selected is not important because the way it is used enforces a shared recognition by all participating applications. Each DomainParticipant has an associated instance of the DDS:Access:PKI-Signed-XML- Permissions plugin. 9.4.1 Configuration The DDS:Access:PKI-Signed-XML-Permissions plugin is configured with three documents: The Permissions CA certificate The Domain governance signed by the Permissions CA The DomainParticipant permissions signed by the Permissions CA 9.4.1.1 Permissions CA Certificate This is a self-signed x.509 certificate that contains the Public Key of the CA that will be used to sign the Domain Governance and Domain Permissions document. The way the Permissions CA certificate is provided to the plugins is not specified. It may be done in an implementation-dependent way. The fact that this is not specified does not affect interoperability. 9.4.1.2 Domain Governance Document The domain governance document is an XML document that specifies how the domain should be secured. The document specifies which DDS domain IDs shall be protected and the details of the protection. Specifically this document configures the following aspects that apply to the whole domain: Whether the discovery information should be protected and the kind of protection: only message authentication codes (MACs) or encryption followed by MAC. Whether the whole RTPS message should be protected and the kind of protection. This is in addition to any protection that may occur for individual submessages and for submessage data payloads. Whether the liveliness messages should be protected. Whether a discovered DomainParticipants that cannot authenticate or fail the authentication should be allowed to join the domain and see any discovery data that are configured as ‘unprotected’ and any Topics that are configured as ‘unprotected’. Whether any discovered DomainParticipant that authenticates successfully should be allowed to join the domain and see the discovery data without checking the access control policies. In addition, the domain governance document specifies how the information on specific Topics within the domain should be treated. Specifically: Whether the discovery information on specific Topics should be sent using the secure (protected) discovery writers or using the regular (unprotected) discovery writers.
- 169. DDS Security v1.0 Beta 1 159 Whether read access to the Topic should be open to all or restricted to the DomainParticipants that have the proper permissions. Whether write access to the Topic should be open to all or restricted to the DomainParticipants that have the proper permissions. Whether the metadata information sent on the Topic (sequence numbers, heartbeats, key hashes, gaps, acknowledgment messages, etc.) should be protected and the kind of protection (MAC or Encrypt+MAC). Whether the payload data sent on the Topic (serialized application level data) should be protected and the kind of protection (MAC or Encrypt+MAC). 9.4.1.2.1 Protection Kinds The domain governance document provides a means for the application to configure the kinds of cryptographic transformation applied to the complete RTPS Message, certain RTPS SubMessages, and the SerializedPayload RTPS submessage element that appears within the Data and DataFrag submessages. The configuration allows specification of three protection levels: NONE, SIGN, ENCRYPT. NONE indicates no cryptographic transformation is applied. When referring to the whole RTPS message, it means that the encode_rtps message operation on the CryptoTransform interface shall either not be called, or if it is called it shall behave as a No-Op by returning the same cleartext bytes that were its input. In other words it shall not enclose the RTPS message inside the SecureSubMsg. When referring to a concrete RTPS SubMessage originating on a DataWriter (Data, DataFrag, Gap, Heartbeat) it means that the encode_datawriter_submessage operation on the CryptoTransform interface shall either not be called, or if it is called it shall behave as a No-Op by returning the same cleartext bytes that were its input. In other words it shall not envelope the submessage inside a SecureSubMsg. When referring to a concrete RTPS SubMessage originating on a DataReader (AckNack, NackFrag) it means that the encode_datareader_submessage operation on the CryptoTransform interface shall either not be called, or if it is called it shall behave as a No-Op by returning the same cleartext bytes that were its input. In other words it shall not enclose the submessage inside a SecureSubMsg. When referring to a concrete SerializedPayload sub message element inside the DataWriter Data and DataFrag submessages, it means that the encode_serialized_data operation on the CryptoTransform interface shall either not be called, or if it is called it shall behave as a No-Op by returning the same cleartext bytes that were its input. In other words it shall not enclose the SerializedData submessage element inside a SecuredPayload submessage element. SIGN indicates the cryptographic transformation shall be purely a hash-based message authentication code (HMAC), that is, no encryption is performed. When referring to the whole RTPS message, it means that the encode_rtps message operation on the CryptoTransform interface shall be called and its return shall be enclosed inside a SecureSubMsg. The encode_rtps message operation shall only sign the message
- 170. 160 DDS Security v1.0 Beta1 using the HMAC algorithm. Therefore the resulting CryptoTransformIdentifier for the SecureSubMsg shall be either HMAC_SHA1 or HMAC_SHA256. When referring to a concrete RTPS SubMessage originating on a DataWriter (Data, DataFrag, Gap, Heartbeat), it means that the encode_datawriter_submessage operation on the CryptoTransform interface shall be called and its return shall be enclosed inside a SecureSubMsg. The encode_datawriter_submessage operation shall only sign the message using the HMAC algorithm. Therefore the resulting CryptoTransformIdentifier for the SecureSubMsg shall be either HMAC_SHA1 or HMAC_SHA256. When referring to a concrete RTPS SubMessage originating on a DataReader (AckNack, NackFrag), it means that the encode_datareader_submessage operation on the CryptoTransform interface it means that the encode_datareader_submessage operation on the CryptoTransform interface shall be called and its return shall be enclosed inside a SecureSubMsg. The encode_datareader_submessage operation shall only sign the message using the HMAC algorithm. Therefore the resulting CryptoTransformIdentifier for the SecureSubMsg shall be either HMAC_SHA1 or HMAC_SHA256. When referring to a concrete SerializedPayload sub message element inside the DataWriter Data and DataFrag submessages, it means that the encode_serialized_data operation on the CryptoTransform interface shall be called and its return shall be enclosed inside a SecureData submessage element. The encode_ serialized_data operation shall only sign the message using the HMAC algorithm. Therefore, the resulting CryptoTransformIdentifier for the SecureData shall be either HMAC_SHA1 or HMAC_SHA256. ENCRYPT indicates the cryptographic transformation shall be an encryption followed by a hash- based message authentication code (HMAC) computed on the ciphertext, also known as Encrypt-then- MAC. When referring to the whole RTPS message, it means that the encode_rtps message operation on the CryptoTransform interface shall be called and its return shall be enclosed inside a SecureSubMsg. The encode_rtps message operation shall first encrypt the RTPS message, prepend the SecureSubMsg headers and then compute the HMAC over the result. Therefore the resulting CryptoTransformIdentifier for the SecureSubMsg shall be either AES128_HMAC_SHA1 or AES256_HMAC_SHA256. When referring to a concrete RTPS SubMessage originating on a DataWriter (Data, DataFrag, Gap, Heartbeat), it means that the encode_datawriter_submessage operation on the CryptoTransform interface shall be called and its return shall be enclosed inside a SecureSubMsg. The encode_datawriter_submessage operation shall first encrypt the RTPS message, prepend the SecureSubMsg headers and then compute the HMAC over the result. Therefore the resulting CryptoTransformIdentifier for the SecureSubMsg shall be either AES128_HMAC_SHA1 or AES256_HMAC_SHA256. When referring to a concrete RTPS Sub Messages originating on a DataReader (AckNack, NackFrag), it means that the encode_datareader_submessage operation on the CryptoTransform interface shall be called and its return shall be enclosed inside a SecureSubMsg. The encode_datareader_submessage operation shall first encrypt the
- 171. DDS Security v1.0 Beta 1 161 RTPS message, prepend the SecureSubMsg headers, and then compute the HMAC over the result. Therefore the resulting CryptoTransformIdentifier for the SecureSubMsg shall be either HMAC_SHA1 or HMAC_SHA256. When referring to a concrete SerializedPayload sub message element inside the DataWriter Data and DataFrag submessages, it means that the encode_serialized_data operation on the CryptoTransform interface shall be called and its return shall be enclosed inside a SecureData submessage element. The encode_ serialized_data operation shall first encrypt the RTPS message, prepend the SecureData headers and then compute the HMAC over the result. Therefore the resulting CryptoTransformIdentifier for the SecureData shall be either HMAC_SHA1 or HMAC_SHA256. 9.4.1.2.2 Domain Governance document format The format of this document defined using the following XSD: <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="dds" type="DomainAccessRulesNode" /> <xs:complexType name="DomainAccessRulesNode"> <xs:sequence minOccurs="1" maxOccurs="1"> <xs:element name="domain_access_rules" type="DomainAccessRules" /> </xs:sequence> </xs:complexType> <xs:complexType name="DomainAccessRules"> <xs:sequence minOccurs="1" maxOccurs="unbounded"> <xs:element name="domain_rule" type="DomainRule" /> </xs:sequence> </xs:complexType> <xs:complexType name="DomainRule"> <xs:sequence minOccurs="1" maxOccurs="1"> <xs:element name="domain_id" type="xs:string" /> <xs:element name="allow_unauthenticated_join" type="BooleanKind" /> <xs:element name="enable_join_access_control" type="BooleanKind" /> <xs:element name="discovery_protection_kind" type="ProtectionKind" /> <xs:element name="liveliness_protection_kind" type="ProtectionKind" /> <xs:element name="rtps_protection_kind" type="ProtectionKind" /> <xs:element name="topic_access_rules" type="TopicAccessRules" /> </xs:sequence> </xs:complexType>
- 172. 162 DDS Security v1.0 Beta1 <xs:simpleType name="ProtectionKind"> <xs:restriction base="xs:string"> <xs:enumeration value="ENCRYPT" /> <xs:enumeration value="SIGN" /> <xs:enumeration value="NONE" /> </xs:restriction> </xs:simpleType> <xs:simpleType name="BooleanKind"> <xs:restriction base="xs:string"> <xs:enumeration value="TRUE" /> <xs:enumeration value="FALSE" /> </xs:restriction> </xs:simpleType> <xs:complexType name="TopicAccessRules"> <xs:sequence minOccurs="1" maxOccurs="unbounded"> <xs:element name="topic_rule" type="TopicRule" /> </xs:sequence> </xs:complexType> <xs:complexType name="TopicRule"> <xs:sequence minOccurs="1" maxOccurs="1"> <xs:element name="topic_expression" type="TopicExpression" /> <xs:element name="enable_discovery_protection" type="BooleanKind" /> <xs:element name="enable_read_access_control" type="BooleanKind" /> <xs:element name="enable_write_access_control" type="BooleanKind" /> <xs:element name="metadata_protection_kind" type="ProtectionKind" /> <xs:element name="data_protection_kind" type="ProtectionKind" /> </xs:sequence> </xs:complexType> <xs:simpleType name="TopicExpression"> <xs:restriction base="xs:string" /> </xs:simpleType> </xs:schema> 9.4.1.2.3 Domain Access Rules Section The XML domain governance document is delimited by the <dds> XML element tag and contains a single domain access rules Section delimited by the <domain_access_rules> XML element tag. The domain access rules Section contains a set of domain rules each delimited by the <domain_rule> XML element tag.
- 173. DDS Security v1.0 Beta 1 163 9.4.1.2.4 Domain Rules Each domain rule appears within the domain access rules Section delimited by the <domain_rule> XML element tag. Each domain rule contains the following elements and sections: 1. Domain id element 2. Discovery Protection Kind element 3. Liveliness Protection Kind element 4. Allow Unauthenticated Join element 5. Enable Join Access Control element 6. Topic Access Rules Section, containing topic rules The contents and delimiters of each Section are described below. The domain rules shall be evaluated in the same order as they appear in the document. A rule only applies to a particular DomainParticipant if the domain Section matches the DDS domain_id to which the DomainParticipant belongs. If multiple rules match, the first rule that matches is the only one that applies. 9.4.1.2.4.1 Domain Id element This element is delimited by the XML element <domain_id>. The value in this element identifies the DDS domain_id to which the rule applies. 9.4.1.2.4.2 Allow Unauthenticated Join element This element is delimited by the XML element <allow_unauthenticated_join>. This element may take the binary values TRUE or FALSE. If the value is set to FALSE, the ParticipantSecurityAttributes returned by the get_participant_sec_attributes operation on the AccessControl shall have the allow_unauthenticated_participants member set to FALSE. If the value is set to TRUE, the ParticipantSecurityAttributes returned by the get_participant_sec_attributes operation on the AccessControl shall have the allow_unauthenticated_participants member set to TRUE. 9.4.1.2.4.3 Enable Join Access Control element This element is delimited by the XML element <enable_join_access_control>. This element may take the binary values TRUE or FALSE. If the value is set to FALSE, the ParticipantSecurityAttributes returned by the get_participant_sec_attributes operation on the AccessControl shall have the is_access_protected member set to FALSE. If the value is set to TRUE, the ParticipantSecurityAttributes returned by the get_participant_sec_attributes operation on the AccessControl shall have the is_access_protected member set to TRUE.
- 174. 164 DDS Security v1.0 Beta1 9.4.1.2.4.4 Discovery Protection Kind element This element is delimited by the XML element <discovery_protection_kind>. The discovery protection element specifies the protection kind (see 9.4.1.2.1) used for the secure builtin DataWriter and DataReader entities used for discovery: SEDPbuiltinPublicationsSecureWriter, SEDPbuiltinSubscriptionsSecureWriter, SEDPbuiltinPublicationsSecureReader, SEDPbuiltinSubscriptionsSecureReader. The discovery protection kind element may take three possible values: NONE, SIGN, or ENCRYPT. The resulting behavior for the aforementioned builtin discovery secure entities shall be as specified in 9.4.1.2.1 with regards to the RTPS SubMessages. The builtin endpoints shall never apply cryptographic transformations to the SecuredPayload submessage element. 9.4.1.2.4.5 Liveliness Protection Kind element This element is delimited by the XML element <liveliness_protection_kind>. The liveliness protection element specifies the protection kind (see 9.4.1.2.1) used for builtin DataWriter and DataReader associated with the ParticipantMessageSecure builtin Topic (see 7.4.2): BuiltinParticipantMessageSecureWriter and BuiltinParticipantMessageSecureWriter. The discovery protection kind element may take three possible values: NONE, SIGN, or ENCRYPT. The resulting behavior for the aforementioned builtin secure entities shall be as specified in 9.4.1.2.1. 9.4.1.2.4.6 RTPS Protection Kind element This element is delimited by the XML element <rtps_protection_kind>. The liveliness protection element specifies the protection kind (see 9.4.1.2.1) used for the whole RTPS message. The discovery protection kind element may take three possible values: NONE, SIGN, or ENCRYPT. The resulting behavior for the RTPS message cryptographic transformation shall be as specified in 9.4.1.2.1. 9.4.1.2.4.7 Topic Access Rules Section This element is delimited by the XML element <topic_access_rules> and contains a sequence of topic rule elements. 9.4.1.2.5 Topic Rule Section This element is delimited by the XML element <topic_rules> and appears within the domain rule Section. Each topic rule Section contains the following elements: 1. Topic expression 2. Enable Discovery protection 3. Enable Read Access Control element 4. Enable Write Access Control element 5. Metadata protection Kind
- 175. DDS Security v1.0 Beta 1 165 6. Data protection Kind The contents and delimiters of each Section are described below. The topic expression element within the rules selects a set of Topic names. The rule applies to apply to any DataReader or DataWriter associated with a Topic whose name matches the Topic expression name. The topic access rules shall be evaluated in the same order as they appear within the <topic_access_rules> Section. If multiple rules match the first rule that matches is the only one that applies. 9.4.1.2.5.1 Topic expression element This element is delimited by the XML element <topic_expression>. The value in this element identifies the set of DDS Topic names to which the rule applies. The rule will apply to any DataReader or DataWriter associated with a Topic whose name matches the value. 9.4.1.2.5.2 Enable Discovery protection element This element is delimited by the XML element <enable_discovery_protection>. This element may take the binary values TRUE or FALSE. The setting controls the contents of the EndpointSecurityAttributes returned by the AccessControl::get_endpoint_sec_attributes operation on any DataWriter or DataReader entity whose associated Topic name matches the rule’s topic expression. Specifically the is_discovery_protected attribute in the EndpointSecurityAttributes shall be set to the binary value specified in the “enable discovery protection" element. 9.4.1.2.5.3 Enable Read Access Control element This element is delimited by the XML element <enable_read_access_control>. This element may take the binary values TRUE or FALSE. The setting shall control the contents of the EndpointSecurityAttributes returned by the AccessControl::get_endpoint_sec_attributes operation on any DataWriter entity whose associated Topic name matches the rule’s topic expression. Specifically the is_access_protected attribute in the EndpointSecurityAttributes shall be set to the binary value specified in the “enable read access protection" element. In addition, this element shall control the AccessControl::check_create_datareader operation on any DataReader entity whose associated Topic name matches the rule’s topic expression. Specifically: If the value of “enable_read_access_control” element is FALSE, the operation check_create_datareader shall return TRUE without further checking the Permissions document. If the value of “enable_read_access_control” element is TRUE, the operation check_create_datareader shall return a value according to what is specified in the Permissions document, see 9.4.1.3. 9.4.1.2.5.4 Enable Write Access Control element This element is delimited by the XML element <enable_write_access_control>.
- 176. 166 DDS Security v1.0 Beta1 This element may take the binary values TRUE or FALSE. The setting controls the contents of the EndpointSecurityAttributes returned by the AccessControl::get_endpoint_sec_attributes operation on any DataReader entity whose associated Topic name matches the rule’s topic expression. Specifically the is_access_protected attribute in the EndpointSecurityAttributes shall be set to the binary value specified in the “enable write access protection" element. In addition, this element shall control the AccessControl::check_create_datawriter operation on any DataWriter entity whose associated Topic name matches the rule’s topic expression. Specifically: If the value of “enable_write_access_control” element is FALSE, the operation check_create_datawriter shall return TRUE without further checking the Permissions document. If the value of “enable_write_access_control” element is TRUE, the operation check_create_datareader shall return a value according to what is specified in the Permissions document, see 9.4.1.3. 9.4.1.2.5.5 Metadata Protection Kind element This element is delimited by the XML element <metadata_protection_kind>. This element may take the binary values TRUE or FALSE. The setting of this element shall specify the protection kind (see 9.4.1.2.1) used for the RTPS SubMessages sent by any DataWriter and DataReader whose associated Topic name matches the rule’s topic expression. The setting of this element shall also control the contents of the EndpointSecurityAttributes returned by the AccessControl::get_endpoint_sec_attributes operation on any DataWriter or DataReader entity whose associated Topic name matches the rule’s topic expression. Specifically the is_submessage_protected attribute in the EndpointSecurityAttributes shall be set to the binary value specified in the “data protection kind" element. 9.4.1.2.5.6 Data Protection Kind element This element is delimited by the XML element <data_protection_kind>. This element may take the binary values TRUE or FALSE. The setting of this element shall specify the protection kind (see 9.4.1.2.1) used for the RTPS SerializedPayload submessage element sent by any DataWriter whose associated Topic name matches the rule’s topic expression. The setting shall control the contents of the EndpointSecurityAttributes returned by the AccessControl::get_endpoint_sec_attributes operation on any DataWriter entity whose associated Topic name matches the rule’s topic expression. Specifically the is_payload_protected attribute in the EndpointSecurityAttributes shall be set to the binary value specified in the “data protection kind" element.
- 177. DDS Security v1.0 Beta 1 167 9.4.1.2.6 Example Domain Governance document (non normative) Following is an example permissions document that is written according to the XSD described in the previous sections. <?xml version="1.0" encoding="utf-16"?> <dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="omg_shared_ca_domain_governance.xsd"> <domain_access_rules> <domain_rule> <domain_id>0</domain_id> <allow_unauthenticated_participants>FALSE </allow_unauthenticated_participants> <enable_join_access_control>TRUE </enable_join_access_control> <rtps_protection_kind>SIGN </rtps_protection_kind> <discovery_protection_kind>ENCRYPT </discovery_protection_kind> <liveliness_protection_kind>SIGN </liveliness_protection_kind> <topic_access_rules> <topic_rule> <topic_expression>Square* </topic_expression> <enable_discovery_protection>TRUE </enable_discovery_protection> <enable_read_access_control>TRUE </enable_read_access_control> <enable_write_access_control>TRUE </enable_write_access_control> <metadata_protection_kind>ENCRYPT </metadata_protection_kind> <data_protection_kind>ENCRYPT </data_protection_kind> </topic_rule> <topic_rule> <topic_expression>Circle</topic_expression> <enable_discovery_protection>TRUE </enable_discovery_protection> <enable_read_access_control>FALSE </enable_read_access_control> <enable_write_access_control>TRUE </enable_write_access_control> <metadata_protection_kind>ENCRYPT </metadata_protection_kind> <data_protection_kind>ENCRYPT </data_protection_kind> </topic_rule> <topic_rule> <topic_expression>Triangle </topic_expression>
- 178. 168 DDS Security v1.0 Beta1 <enable_discovery_protection>FALSE </enable_discovery_protection> <enable_read_access_control>FALSE </enable_read_access_control> <enable_write_access_control>TRUE </enable_write_access_control> <metadata_protection_kind>NONE </metadata_protection_kind> <data_protection_kind>NONE </data_protection_kind> </topic_rule> <topic_rule> <topic_expression>*</topic_expression> <enable_discovery_protection>TRUE </enable_discovery_protection> <enable_read_access_control>TRUE </enable_read_access_control> <enable_write_access_control>TRUE </enable_write_access_control> <metadata_protection_kind>ENCRYPT </metadata_protection_kind> <data_protection_kind>ENCRYPT </data_protection_kind> </topic_rule> </topic_access_rules> </domain_rule> </domain_access_rules> </dds> 9.4.1.3 DomainParticipant permissions document The permissions document is an XML document containing the permissions of the domain participant and binding them to the distinguished name of the DomainParticipant as defined in the DDS:Auth:PKI-RSA/DSA-DH authentication plugin. The format of this document defined using the following XSD. <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="permissions" type="Permissions"/> <xs:complexType name="Permissions"> <xs:sequence minOccurs="1" maxOccurs="unbounded"> <xs:element name="grant" type="Grant" /> </xs:sequence> </xs:complexType>
- 179. DDS Security v1.0 Beta 1 169 <xs:complexType name="Grant"> <xs:sequence minOccurs="1" maxOccurs="1"> <xs:element name="subject_name" type="xs:string" /> <xs:element name="validity" type="Validity" /> <xs:sequence minOccurs="1" maxOccurs="unbounded"> <xs:choice minOccurs="1" maxOccurs="1"> <xs:element name="allow_rule" minOccurs="0" type="Rule" /> <xs:element name="deny_rule" minOccurs="0" type="Rule" /> </xs:choice> </xs:sequence> <xs:element name="default" type="DefaultAction"/> </xs:sequence> <xs:attribute name="name" type="xs:string" use="required"/> </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="Rule"> <xs:sequence minOccurs="1" maxOccurs="1"> <xs:element name="domain_id" type="xs:string" /> <xs:sequence minOccurs="1" maxOccurs="unbounded"> <xs:element name="publish" type="Criteria" /> </xs:sequence> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <xs:element name="subscribe" type="Criteria" /> </xs:sequence> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <xs:element name="relay" type="Criteria" /> </xs:sequence> </xs:sequence> </xs:complexType> <xs:complexType name="Criteria"> <xs:sequence minOccurs="1" maxOccurs="unbounded"> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="topic" minOccurs="0" type="TopicExpression"/> <xs:element name="partition" minOccurs="0" type="PartitionExpression"/> <xs:element name="data_tags" minOccurs="0" type="DataTags"/> </xs:choice> </xs:sequence> </xs:complexType>
- 180. 170 DDS Security v1.0 Beta1 <xs:simpleType name="TopicExpression"> <xs:restriction base="xs:string"/> </xs:simpleType> <xs:simpleType name="PartitionExpression"> <xs:restriction base="xs:string"/> </xs:simpleType> <xs:complexType name="DataTags"> <xs:sequence minOccurs="1" maxOccurs="unbounded"> <xs:element name="tag" type="TagNameValuePair"/> </xs:sequence> </xs:complexType> <xs:complexType name="TagNameValuePair"> <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:simpleType name="DefaultAction"> <xs:restriction base="xs:string"> <xs:enumeration value="ALLOW"/> <xs:enumeration value="DENY"/> </xs:restriction> </xs:simpleType> </xs:schema> 9.4.1.3.1 Permissions Section The XML permissions document contains a permissions Section. This is the portion of the XML document delimited by the <permissions> XML element tag. The permissions Section contains a set of grant sections. 9.4.1.3.2 Grant Section The grant sections appear within the permissions Section delimited by the <grant> XML element tag. Each grant Section contains three sections: 1. Subject name Section (subject_name element) 2. Validity Section (validity element) 3. Rules Section (allow, deny and default elements) The contents and delimiters of each Section are described below. 9.4.1.3.2.1 Subject name Section This Section is delimited by the XML element <subject_name>.
- 181. DDS Security v1.0 Beta 1 171 The subject name Section identifies the DomainParticipant to which the permissions apply. Each subject name can only appear in a single <permissions> Section within the XML Permissions document. The contents of the <subject_name> element shall be the x.509 subject name for the DomainParticipant as is given in its Authorization Certificate. A permissions Section with a subject name that does not match the subject name given in the corresponding Authorization certificate shall be ignored. The x.509 subject name is a set of name-value pairs. The format of x.509 subject name shall use a single string containing the sequence of names-value pairs. Each name shall be separated from the corresponding value by the ‘=’ character and each pair shall be separated from the next by the forward slash character ‘/’. This representation is the same used by openssl package to print subject names. For example: <subject_name>/C=US/ST=CA/L=Sunnyvale/O=ACME Inc./OU=CTO Office/CN=DDS Shapes Demo/emailAddress=cto@acme.com</subject_name> 9.4.1.3.2.2 Validity Section This Section is delimited by the XML element <validity>. The contents of this element reflect the valid dates for the permissions. It contains both the starting date and the end date in GMT formatted as YYYYMMDDHH. A permissions Section with a validity date that falls outside the current date at which the permissions are being evaluated shall be ignored. 9.4.1.3.2.3 Rules Section This Section contains the permissions assigned to the DomainParticipant. It is described as a set of rules. The rules are applied in the same order that appear in the document. If the criteria for the rule matches the domain_id join and/or publish or subscribe operation that is being attempted then the allow or deny decision is applied. If the criteria for a rule does not match the operation being attempted the evaluation shall proceed to the next rule. If all rules have been examined without a match then the decision specified by the “default” rule is applied. The default rule, if present, must appear after all allow and deny rules. If the default rule is not present the implied default decision is DENY. The matching criteria for the rules specifies the domain_id, topics (published and subscribed), the partitions (published and subscribed), and the data-tags associated with the DataWriter and DataReader. 9.4.1.3.2.3.1 Format of the allow rules Allow rules appear inside the <allow_rule> XML Element. Each rule contains the domain IDs to which the rule applies, and the topic names that are allowed to be published and subscribed within those domains. 9.4.1.3.2.3.1.1 Domain Id Section
- 182. 172 DDS Security v1.0 Beta1 This Section is delimited by the XML element <domain_id>. The contents of this element shall be an expression defining the set of DDS Domain Id values to which the allow rule applies. The expression syntax and matching shall use the syntax and rules of the POSIX fnmatch() function as specified in POSIX 1003.2-1992, Section B.6 [38]. For example: <domain_id>0</domain_id> 9.4.1.3.2.3.1.2 Publish Section This Section defines the Topic names that the rule allows to be published. The publish Section shall be delimited by the <publish> XML Element. The topic names appear in the Section delimited by the <topics> XML element. Topic names may be given explicitly or by means of Topic name expressions. The Topic name expression syntax and matching shall use the syntax and rules of the POSIX fnmatch() function as specified in POSIX 1003.2-1992, Section B.6 [38]. The publish Section may also include one or more sections delimited by the <partitions> XML Element. The <partition> XML Elements contain the DDS Partition names where it is allowed to publish the specified Topic names. Partition names may be given explicitly or by means of Partition name expressions. The Partition name expression syntax and matching shall use the syntax and rules of the POSIX fnmatch() function as specified in POSIX 1003.2-1992, Section B.6 [38]. If there is no <partitions> Section then the rule allows publishing on any partition. The publish Section may also include one or more sections delimited by the <data_tags> XML Element. The <data_tags> XML Elements contain a set of tags that shall be associated with the DataWriter that publishes the data on the Topic names allowed by the rule. Example1: <publish> <topic>Circle1</topic> </publish> Example2: <publish> <topic>Square</topic> <partition>A_partition</partition> </publish> Example3: <publish> <topic>Cir*</topic> <data_tags> <tag> <name>aTagName1</name> <value>aTagValue1</value> </tag> </data_tags> </publish> 9.4.1.3.2.3.1.3 Subscribe Section
- 183. DDS Security v1.0 Beta 1 173 This Section defines the Topic names that the rule allows to be subscribed. The publish Section shall be delimited by the <subscribe> XML Element. The topic names appear in the Section delimited by the <topics> XML element. Topic names may be given explicitly or by means of Topic name expressions. The Topic name expression syntax and matching shall use the syntax and rules of the POSIX fnmatch() function as specified in POSIX 1003.2-1992, Section B.6 [38]. The subscribe Section may also include one or more sections delimited by the <partitions> XML Element. The <partition> XML Elements contain the DDS Partition names where it is allowed to subscribe to the specified Topic names. Partition names may be given explicitly or by means of Partition name expressions. The Partition name expression syntax and matching shall use the syntax and rules of the POSIX fnmatch() function as specified in POSIX 1003.2-1992, Section B.6 [38]. If there is no <partitions> Section then the rule allows subscribing on any partition. The subscribe Section may also include one or more sections delimited by the <data_tags> XML Element. The <data_tags> XML Elements contain a set of tags that shall be associated with the DataReader that subscribes the data on the Topic names allowed by the rule. Example1: <subscribe> <topic>Circle1</topic> </subscribe> Example2: <subscribe> <topic>Square</topic> <partition>A_partition</partition> </subscribe> Example3: <subscribe> <topic>Cir*</topic> <data_tags> <tag> <name>aTagName1</name> <value>aTagValue1</value> </tag> </data_tags> </subscribe> 9.4.1.3.2.3.1.4 Example allow rule <allow_rule> <domain_id>0</domain_id> <publish> <topic>Cir*</topic> <data_tags> <tag> <name>aTagName1</name> <value>aTagValue1</value> </tag>
- 184. 174 DDS Security v1.0 Beta1 </data_tags> </publish> <subscribe> <topic>Sq*</topic> <data_tags> <tag> <name>aTagName1</name> <value>aTagValue1</value> </tag> <tag> <name>aTagName2</name> <value>aTagValue2</value> </tag> </data_tags> </subscribe> <subscribe> <topic>Triangle</topic> <partition>P*</partition> </subscribe> </allow_rule> 9.4.1.3.2.3.2 Format for deny rules Deny rules appear inside the <deny_rule> XML Element. Each rule contains the domain IDs to which the rule applies, and the topic names that are denied to be published and subscribed within those domains. Deny rules have the same format as the allow rules. The only difference is how they are interpreted. If the criteria in the deny rule matches the operation being performed then the decision is to deny the operation. 9.4.1.3.2.3.2.1 Example deny rule <deny_rule> <domain_id>0</domain_id> <publish> <topic>Circle1</topic> </publish> <publish> <topic>Square</topic> <partition>A_partition</partition> </publish> <subscribe> <topic>Square1</topic> </subscribe> <subscribe> <topic>Tr*</topic> <partition>P1*</partition> </subscribe> </deny_rule>
- 185. DDS Security v1.0 Beta 1 175 9.4.1.4 DomainParticipant example permissions document (non normative) Following is an example permissions document that is written according to the XSD described in the previous sections. <?xml version="1.0" encoding="utf-16"?> <permissions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="omg_shared_ca_permissions.xsd"> <grant name="ShapesPermission"> <subject_name>/C=US/ST=CA/L=Sunnyvale/O=ACME Inc./OU=CTO Office/CN=DDS Shapes Demo/emailAddress=cto@acme.com</subject_name> <validity> <!-- Format is YYYYMMDDHH in GMT --> <not_before>2013060113</not_before> <not_after>2014060113</not_after> </validity> <deny_rule> <domain_id>0</domain_id> <publish> <topic>Circle1</topic> </publish> <publish> <topic>Square</topic> <partition>A_partition</partition> </publish> <subscribe> <topic>Square1</topic> </subscribe> <subscribe> <topic>Tr*</topic> <partition>P1*</partition> </subscribe> </deny_rule> <allow_rule> <domain_id>0</domain_id> <publish> <topic>Cir*</topic> <data_tags> <tag> <name>aTagName1</name> <value>aTagValue1</value> </tag> </data_tags> </publish> <subscribe> <topic>Sq*</topic> <data_tags> <tag> <name>aTagName1</name>
- 186. 176 DDS Security v1.0 Beta1 <value>aTagValue1</value> </tag> <tag> <name>aTagName2</name> <value>aTagValue2</value> </tag> </data_tags> </subscribe> <subscribe> <topic>Triangle</topic> <partition>P*</partition> </subscribe> <relay> <topic>*</topic> <partition>aPartitionName</partition> </relay> </allow_rule> <default>DENY</default> </grant> </permissions> 9.4.2 DDS:Access:PKI-Signed-XML-Permissions Types This sub clause specifies the content and format of the Credential and Token objects used by the DDS:Access:PKI-Signed-XML-Permissions plugin. 9.4.2.1 DDS:Access:PKI-Signed-XML-Permissions PermissionsCredential The DDS:Access:PKI-Signed-XML-Permissions plugin shall set the attributes of the PermissionsCredential objects as specified in the table below: Table 38 – PermissionsCredential class for the builtin AccessControl plugin Attribute name Attribute value class_id binary_value1 XML permissions document DomainParticipant signed data signed data 9.4.2.2 DDS:Access:PKI-Signed-XML-Permissions PermissionsCredentialToken The DDS:Access:PKI-Signed-XML-Permissions plugin shall set the attributes of the PermissionsCredentialToken objects identically to the PermissionsCredential object.
- 187. DDS Security v1.0 Beta 1 177 9.4.2.3 DDS:Access:PKI-Signed-XML-Permissions PermissionsToken The DDS:Access:PKI-Signed-XML-Permissions plugin shall set the attributes of the PermissionsToken object as specified in the table below: Table 39 PermissionsToken class for the builtin AccessControl plugin Attribute name Attribute value class_id binary_value1 binary_value1 PermissionsCredential 9.4.3 DDS:Access:PKI-Signed-XML-Permissions plugin behavior The DDS:Access:PKI-Signed-XML-Permissions shall be initialized to have access to the Permissions CA 2048-bit RSA public key. As this is a builtin plugin the mechanism for initialization is implementation dependent. The table below describes the actions that the DDS:Access:PKI-Signed-XML-Permissions plugin performs when each of the plugin operations is invoked. Table 40 – Actions undertaken by the operations of the bultin AccessControl plugin check_create_participant This operation shall use the permissions_handle to retrieve the cached Permissions Section. The operation shall verify that the Permissions Section allows creating a DomainParticipant in the specified domain_id. check_create_datawriter This operation shall use the permissions_handle to retrieve the cached Permissions Section. The operation shall verify that the Permissions Section allows publishing the Topic with specified topic_name on the specified domain_id. check_create_datareader This operation shall use the permissions_handle to retrieve the cached Permissions Section. The operation shall verify that the Permissions Section allows subscribing to the Topic with specified topic_name on the specified domain_id. check_create_topic This operation shall use the permissions_handle to retrieve the cached Permissions Section. The operation shall verify that the Permissions Section allows publishing or subscribing to the Topic with specified topic_name on the specified domain_id.
- 188. 178 DDS Security v1.0 Beta1 check_local_datawriter_re gister_instance This operation shall return TRUE. check_local_datawriter_di spose_instance This operation shall return TRUE. check_remote_participant This operation shall use the permissions_handle to retrieve the cached Permissions Section. The operation shall verify that the Permissions Section allows creating a DomainParticipant in the specified domain_id. check_remote_datawriter This operation shall use the permissions_handle to retrieve the cached Permissions Section. The operation will verify that the Permissions Section allows publishing a the Topic with 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 Topic with specified topic_name on the specified domain_id. If the permissions Section specifies that the DomainParticipant can ‘subscribe’ to the Topic the operation shall return TRUE and also set the ‘allow_relay_only’ output parameter to FALSE. If the permissions Section specifies that the DomainParticipant can ‘relay’ the Topic the operation shall return TRUE and also set the ‘allow_relay_only’ output parameter to TRUE. Otherwise the operation shall return FALSE. 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 Topic with specified topic_name on the specified domain_id. check_local_datawriter_ma tch This operation shall return TRUE. check_local_datareader_ma tch This operation shall return TRUE.
- 189. DDS Security v1.0 Beta 1 179 check_remote_datawriter_r egister_instance This operation shall return TRUE. check_remote_datawriter_d ispose_instance This operation shall return TRUE. get_permissions_token This operation shall return the PermissionsToken formatted as described in 9.4.2.3. get_permissions_credentia l_token This operation shall return the PermissionsToken formatted as described in 9.4.2.2 set_listener This operation shall save a reference to the listener object and associate it with the specified PermissionsHandle. return_permissions_token This operation shall behave as specified in 8.4.2.7.20 return_permissions_creden tial_token This operation shall behave as specified in 8.4.2.7.21 validate_local_permission s This operation shall invoke the operation 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 DomainParticipant. The operation shall receive the PermissionsCredential formatted as described in 9.4.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 Permissions (see 9.4.1.3.1) 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 ns This operation shall invoke the operation 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.
- 190. 180 DDS Security v1.0 Beta1 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. 9.5 Builtin Crypto: DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH The builtin 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 Advanced Encryption Standard (AES) in counter (CTR) mode. It supports two AES key sizes: 128 bits and 256 bits. It also provides hash-based message authentication (HMAC) services with two different hashing functions: SHA256 and SHA1. The approach followed is conceptually similar to that used for SRTP [20]. However it has been enhanced to be able to support additional scenarios, such as the presence of services like a DDS persistence service or a data relay service, which are present in DDS-RTPS systems and not supported by SRTP. The algorithm used for data confidentiality is AES in CTR mode. While AES is a block cipher, the use of counter mode effectively turns it into a stream cipher. It generates key-stream blocks that are XORed with the plaintext blocks to get the ciphertext. Since the XOR operation is symmetric the decryption operation is exactly the same. It is called counter mode because the key-stream blocks are generated encrypting successive values of a "counter" with the key. This mode of operation requires the SessionKey to be kept secret, however the counter does not need to be protected and can be any function that creates a sequence that does not repeat in a long time, in particular it can be a simple incrementing integer. Figure 35 – User of AES encryption in counter-mode
- 191. DDS Security v1.0 Beta 1 181 The use of counter mode allows decryption of blocks in arbitrary order. All that is needed to decrypt a block are the SessionKey and the counter. This is very important for DDS because a DataReader may not receive all the samples written by a matched DataWriter. The use of DDS ContentFilteredTopics as well as DDS QoS policies such as History (with KEEP_LAST kind), Reliability (with BEST_EFFORTS kind), Lifespan, and TimeBasedFilter, among others, can result in a DataReader receiving 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-based Message Authentication Code (HMAC). The plugin supports two hashing algorithms to use with HMAC-SHA256 and HMAC-SHA1. HMAC is defined by IETF RFC 2014 [27]. HMAC keys must be at least as long as the block size of the underlying hash algorithm. The MAC may be computed over the entire RTPS message, which can include multiple submessages, encrypted using different AES keys or may be over particular submessages. 9.5.1 Configuration The configuration of the DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH plugin is not dictated by this specification and therefore is implementation specific. Implementations may provide, for example, an API, an extended QoS Policy, or some other mechanism. The requirement is that the different modes of operation should all be supported and configurable. 9.5.2 DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH Types The Cryptographic plugin defines a set of generic data types to be used to initialize the plugin and to externalize the properties and material that must be shared with the applications that need to decode the cipher material, verify signatures, etc. Each plugin implementation defines the contents of these types in a manner appropriate for the algorithms it uses. All “Handle” types are local opaque handles that are only understood by the local plugin object that creates them. The remaining types shall be fully specified so that independent implementations of DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH can interoperate. 9.5.2.1 DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH CryptoToken The DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH plugin shall set the attributes of the CryptoToken object as specified in the table below: Table 41 – CryptoToken class for the builtin AccessControl plugin Attribute name Attribute value KeyMaterial_AES_CTR_HMAC KxKey binary_value1 KxMacKey
- 192. 182 DDS Security v1.0 Beta1 9.5.2.1.1 KeyMaterial_AES_CTR_HMAC structure The contents and serialization of the KeyMaterial_AES_CTR_HMAC structure are described by the Extended IDL below: enum CipherKind { NONE = 0, AES128 = 1, AES256 = 2 }; enum HashKind { NONE = 0, SHA1 = 1, SHA256 = 2 }; struct KeyMaterial_AES_CTR_HMAC { CipherKind cipher_kind; HashKind hash_kind; long master_key_id; sequence<octet, 32> master_key; sequence<octet, 32> initilization_vector; sequence<octet, 32> hmac_key_id; }; //@Extensibility EXTENSIBLE_EXTENSIBILITY 9.5.2.1.2 Key material used by the BuiltinParticipantVolatileMessageSecureWriter and BuiltinParticipantVolatileMessageSecureReader The KxKey and KxMacKey are derived from the SharedSecret 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: Table 42 – Terms used in KxKey and KxMacKey derivation formula for the builtin Cryptographic plugin Term Meaning HandshakeRequestMessageToken HandshakeReplyMessageToken HandshakeFinalMessageToken
- 193. DDS Security v1.0 Beta 1 183 SharedSecret DomainParticipant HandshakeFinalMessageToken SharedSecret 9.5.2.2 DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH CryptoTransformIdentifier The DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH shall set the CryptoTransformIdentifier attributes as specified in the table below: Table 43 – CryptoTransformIdentifier class for the builtin Cryptographic plugin Attribute Value transformation_kind_id transformation_key_id
- 194. 184 DDS Security v1.0 Beta1 9.5.2.3 DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH SecureDataHeader The DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH CryptoTransform interface has several operations that transform clear text into cipher text. The cipher-text created by these “encode” operations contains a SecureDataHeader that is interpreted by the corresponding “decode” operations on the receiving size. The SecureDataHeader structure is described by the Extended IDL below: @Extensibility(FINAL_EXTENSIBILITY) struct SecureDataHeader_AES_CTR_HMAC { CryptoTranformIdentifier transform_id; long session_id; long session_counter; }; 9.5.3 DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH plugin behavior This plugin implements three interfaces: CryptoKeyFactory, CryptoKeyExchange, and CryptoTransform. Each is described separately. 9.5.3.1 CryptoKeyFactory for DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH The table below describes the actions that the DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH when each of the CryptoKeyFactory plugin operations is invoked. Table 44 – Actions undertaken by the operations of the bultin Cryptographic CryptoKeyFactory plugin register_local_pa rticipant KeyMaterial_AES_CTR_HMAC object and return a handle that can the plugin can use to access the created 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_ remote_participan t SharedSecret ParticipantCryptoHandle. 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 Participant2ParticipantKeyMaterial object shall be NONE. The HashKind shall be configurable but the configuration mechanism is not specified. The Participant2ParticipantKeyMaterial shall be used
- 195. DDS Security v1.0 Beta 1 185 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 tawriter KeyMaterial_AES_CTR_HMAC object and returns a handle that can the plugin can use to access the created object. We will refer to this object by the name: WriterKeyMaterial. The CipherKind and HashKind for the WriterKeyMaterial object shall be configurable but the configuration mechanism is not specified. register_matched_ remote_datareader KeyMaterial_AES_CTR_HMAC object and associate it with the local DatawriterCryptoHandle and remote DatareaderCryptoHandle pair. We will refer to this object by the name: Writer2ReaderKeyMaterial. The CipherKind for the Writer2ReaderKeyMaterial object shall be NONE. The HashKind 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 tareader KeyMaterial_AES_CTR_HMAC object and return a handle that can the plugin can use to access the created 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_ remote_datawriter KeyMaterial_AES_CTR_HMAC object and associate it with the local DatareaderCryptoHandle and remote DatawriterCryptoHandle pair. We will refer to this object by the name: Reader2WriterKeyMaterial. The CipherKind for the Reader2WriterKeyMaterial object shall be NONE. The HashKind shall be configurable but the configuration mechanism is not specified. The Reader2WriterKeyMaterial shall be used when the local
- 196. 186 DDS Security v1.0 Beta1 DataReader needs to produce a MAC that can only be verified by that one matched remote DataWriter. unregister_partic ipant register_local_participant register_matched_remote_participant. unregister_datawr iter register_local_datawriter register_matched_remote_datawriter. unregister_datare ader register_local_datareader register_matched_remote_datareader. 9.5.3.2 CryptoKeyExchange for DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH The table below describes the actions that the DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH when each of the CryptoKeyExchange plugin operations is invoked. Table 45 – Actions undertaken by the operations of the bultin Cryptographic CryptoKeyExchange plugin create_local_partic ipant_crypto_tokens CryptoToken ParticipantKeyMaterial register_local_participant CryptoToken Participant2ParticipantKeyMaterial register_matched_remote_participant remote_participant_crypto. CryptoToken Participant2ParticipantKxKey Participant2ParticipantKxMacKey. set_remote_particip ant_crypto_tokens CryptoToken create_local_participant_crypto_tokens Participant2ParticipantKxKey Participant2ParticipantKxMacKey ParticipantCryptoHandle CryptoHandle RemoteParticipantKeyMaterial RemoteParticipant2ParticipantKeyMaterial create_local_datawr iter_crypto_tokens CryptoToken CryptoToken DatawriterKeyMaterial register_local_datawriter
- 197. DDS Security v1.0 Beta 1 187 CryptoToken Writer2ReaderKeyMaterial register_matched_remote_datareader remote_datareader_crypto. CryptoToken Participant2ParticipantKxKey Participant2ParticipantKxMacKey. set_remote_datawrit er_crypto_tokens CryptoToken create_local_datawriter_crypto_tokens Participant2ParticipantKxKey Participant2ParticipantKxMacKey ParticipantCryptoHandle CryptoHandle RemoteDatawriterKeyMaterial RemoteWriter2ReaderKeyMaterial create_local_datare ader_crypto_tokens CryptoToken CryptoToken DatareaderKeyMaterial register_local_datareader CryptoToken Reader2WriterKeyMaterial register_matched_remote_datawriter remote_datawriter_crypto. CryptoToken Participant2ParticipantKxKey Participant2ParticipantKxMacKey. set_remote_dataread er_crypto_tokens CryptoToken create_local_datareader_crypto_tokens Participant2ParticipantKxKey Participant2ParticipantKxMacKey ParticipantCryptoHandle CryptoHandle RemoteDatareaderKeyMaterial RemoteReader2WriterKeyMaterial return_crypto_token s CryptoToken
- 198. 188 DDS Security v1.0 Beta1 9.5.3.3 CryptoKeyTransform for DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH 9.5.3.3.1 Overview The table below describes the actions that the DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH when each of the CryptoKeyTransform plugin operations is invoked. Table 46 – Actions undertaken by the operations of the bultin Cryptographic CryptoKeyTransform plugin encode_serialized_d ata WriterKeyMaterial sending_datawriter_crypto encode_datawriter_s ubmessage WriterKeyMaterial sending_datawriter_crypto Writer2ReaderKeyMaterial sending_datawriter_crypto receiving_datareader_crypto WriterKeyMaterial sending_datawriter_crypto. WriterKeyMaterial sending_datawriter_crypto. Writer2ReaderKeyMaterial sending_datawriter_crypto receiving_datareader_crypto encode_datareader_s ubmessage ReaderKeyMaterial sending_datareader_crypto Reader2WriterKeyMaterial sending_datareader_crypto receiving_datareader_crypto ReaderKeyMaterial sending_datareader_crypto.
- 199. DDS Security v1.0 Beta 1 189 ReaderKeyMaterial sending_datareader_crypto. Reader2WriterKeyMaterial sending_datareader_crypto receiving_datawriter_crypto encode_rtps_message ParticipantKeyMaterial sending_participant_crypto Participant2ParticipantKeyMaterial sending_participant_crypto receiving_ articipant_crypto ParticipantKeyMaterial sending_participant_crypto. ParticipantKeyMaterial sending_participant_crypto. Participant2ParticipantKeyMaterial sending_participant_crypto receiving_participant_crypto decode_rtps_message CryptoTranformIdentifier CryptoTranformIdentifier RemoteParticipantKeyMaterial RemoteParticipant2ParticopantKeyMaterial RemoteParticipantKeyMaterial
- 200. 190 DDS Security v1.0 Beta1 RemoteParticopant2ParticipantKeyMaterial preprocess_secure_s ubmsg CryptoTranformIdentifier 3. CryptoTranformIdentifier decode_datawriter_s ubmessage RemoteDatawriterKeyMaterial RemoteDatawriter2DatareaderKeyMaterial RemoteDatawriterKeyMaterial RemoteDatawriter2DatareaderKeyMaterial decode_datareader_s ubmessage RemoteDatareaderKeyMaterial RemoteDatareader2DatawriterKeyMaterial
- 201. DDS Security v1.0 Beta 1 191 RemoteDatareaderKeyMaterial RemoteDatareader2DatawriterKeyMaterial decode_serialized_d ata CryptoTranformIdentifier RemoteDatawriterKeyMaterial RemoteDatawriterKeyMaterial 9.5.3.3.2 Encode/decode operation virtual machine The logical operation of the DDS:Crypto:AES-CTR-HMAC-RSA/DSA-DH is described in terms of a virtual machine as it performs the encrypt message digest operations. This is not intended to mandate implementations should follow this approach literally, simply that the observable results for any plaintext are the same as the virtual machine described here. For any given cryptographic session the operation of the DDS:Crypto:AES-CTR-HMAC-RSA/DSA- DH transforms plaintext into ciphertext can be described in terms of a virtual machine that maintains the following state: Table 47 – Terms used in Key Computation and cryptographic transformations formulas for the builtin cryptographic plugin State variable Type Meaning
- 202. 192 DDS Security v1.0 Beta1
- 203. DDS Security v1.0 Beta 1 193 All the key material with a name that starts with “Master” corresponds to the KeyMaterial_AES_CTR_HMAC objects that were created by the CryptoKeyFactory operations. This key material is not used directly to encrypt or compute MAC of the plaintext. Rather it is used to create “Session” Key material by means of the algorithms described below. This has the benefit that the ‘session’ keys used to secure the date stream data can be modified as needed to maintain 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 are limiting the potential deployment scenarios in that if an application needs to receive data and validate the digest to ensure it has not been tampered with, it has to also be given the key necessary to understand 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 privileges to understand its contents. To avoid this situation it would be necessary to separate the digest of the data from the digest of the RTPS Submessage so that it becomes possible to give access to the keys necessary to verify complete submessage integrity to a service without simultaneously giving access to the keys necessary to verify data integrity and understand the data itself.
- 204. 194 DDS Security v1.0 Beta1 9.5.3.3.3 Computation of Session Keys and Salts The SessionKey, SessionSalt, and SessionHMACKey are computed from the MasterKey, MasterSalt and the SessionId: SessionSalt := HMAC(MasterKey,"SessionSalt" + MasterSessionSalt + SessionId) Truncated to 128 bits SessionKey := HMAC(MasterKey,"SessionKey" + MasterSalt + SessionId) SessionHMACKey := HMAC(MasterKey,"SessionHMACKey" + MasterHMACSalt + SessionId) In the above expressions the symbol ‘+’ indicates concatenation. 9.5.3.3.4 Computation of ciphertext from plaintext The 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 operation using the AES algorithm in counter mode using the SessionKeys associated with the specified KeyHandle. The encryption transformation is described in detail in the sections that follow. The encryption operation increments the session counter associated with the KeyHandle by one for each encrypted block. This operation may change the session key. This decision should be taken at the beginning as all ciphertext returned by an invocation of the operation must be encrypted with the same session key. If a new session key is changed the SessionId must be changed in correspondence and session counter is reset accordingly. The resulting ciphertext is enclosed inside a SecureDataHeader that indicates the sessionId and stating value for the counter. The resulting block of bytes from the “encode” operations (encode_serialized_data, encode_datawriter_submessage, encode_datareader_submessage, and encode_rtps_message) is the Extended CDR encoding of the IDL for the EncodeOperationOutputData below: struct DigestResult { SecureDataHeader_AES_CTR_HMAC digest_header; sequence<octet> digest; }; //@Extensibility FINAL_EXTENSIBILITY struct EncodeOperationOutputData { SecureDataHeader_AES_CTR_HMAC secure_data_header; sequence<octet> ciphertext; sequence<octet> common_digest; sequence<Digest> additional_digests; }; //@Extensibility FINAL_EXTENSIBILITY 9.5.3.3.5 Computation of plaintext from ciphertext The decrypt operation first checks that the CryptoTransformIdentifier attribute in the SecureDataHeader_AES_CTR_HMAC has the proper transformation_kind_id and also uses the CryptoTransformIdentifier transformation_key_id to locate MasterKey
- 205. DDS Security v1.0 Beta 1 195 and MasterSalt. In case of a re-key the CryptographicSessionHandle may be associated with multiple MasterKeyId and this parameter allows selection of the correct one. If the MasterKeyId is not found associated with the CryptographicSessionHandle the operation shall fail. The session_id attribute within the SecureDataHeader_AES_CTR_HMAC is used to obtain the proper SessionSalt and SessionKey. Note that this only requires a re-computation if it has changed from the previously received SessionId for that CryptographicSessionHandle. Given the SessionSalt and SessionKey the transformation performed to recover the plaintext from the ciphertext is identical to the one performed to go plaintext to ciphertext. 9.5.3.3.6 Computation of the message digest The message digest is computed on the secure_data_header and the ciphertext. 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 SecureDataHeader_AES_CTR_HMAC which appear explicitly in the DigestResult digest_header. These digests use keys that are only shared with some of the receivers of the EncodeOperationOutputData. In general each receiver will only have the keys necessary to verify one of these additional_digests. The key material for these digest is derived from the RemoteParticipant2ParticipantKeyMaterial, the RemoteWriter2ReaderKeyMaterial, or the RemoteReader2WriterKeyMaterial. Depending on the selected algorithm the digest is computed as an HMAC-SHA256 or HMAC-SHA1. 9.6 Builtin Logging Plugin The builtin Logging Plugin is known as the DDS:Logging:DDS_LogTopic. The DDS:Logging:DDS_LogTopic implements logging by publishing information to a DDS Topic BuiltinLoggingTopic defined below. The BuiltinLoggingTopic shall have the Topic name “DDS:Security:LogTopic”. The BuiltinLoggingTopic shall have the Type BuiltinLoggingType defined in the IDL below: enum BuiltinLoggingLogLevel { FATAL_LEVEL, SEVERE_LEVEL, ERROR_LEVEL, WARNING_LEVEL, NOTICE_LEVEL, INFO_LEVEL, DEBUG_LEVEL, TRACE_LEVEL };
- 206. 196 DDS Security v1.0 Beta1 struct BuiltinLoggingType { BuiltinTopicKey_t source_guid; long log_level; string message; string category; }; Knowledge of the BuiltinLoggingTopic shall be builtin into the DDS:Auth:PKI-RSA/DSA-DH AccessControl plugin and it shall be treated according to the folowing topic rule: <topic_rule> <topic_expression> DDS:Security:LogTopic</topic_expression> <enable_discovery_protection>FALSE</enable_discovery_protection> <enable_read_access_control>TRUE</enable_read_access_control> <enable_write_access_control>FALSE</enable_write_access_control> <metadata_protection_kind>SIGN</metadata_protection_kind> <data_protection_kind>ENCRYPT</data_protection_kind> </topic_rule> The above rule means implies that any DomainParticipant with permission necessary to join the DDS Domain shall be allowed to write the BuiltinLoggingTopic but in order to read the BuiltinLoggingTopic the DomainParticipant needs to have a grant for the BuiltinLoggingTopic in its permissions document. 9.6.1 DDS:Logging:DDS_LogTopic plugin behavior The table below describes the actions that the DDS:Logging:DDS_LogTopic plugin performs when each of the plugin operations is invoked. Table 48 – Actions undertaken by the operations of the bultin Logging plugin set_log_options Controls the configurtion of the plugin. The LogOptions parameter shall be used to take the actions described below: If the distribute parameter is set to TRUE, the DDS:Logging:DDS_LogTopic shall create a DataWriter to send the BuiltinLoggingTopic if it is FALSE, it shall not. The plugin shall open a file with the name indicated in the log_file parameter. The plugin shall remember the value of the log_level so that it can be used during the log operation. log This operation shall check if logging was enabled by a prior call to enable_logging and if not it shall return without performing any action. If logging was enabled, it shall behave as described below: The operation shall compare the value of the the log_level parameter with the value saved during the set_log_options operation.
- 207. DDS Security v1.0 Beta 1 197 If the log_level parameter value is greater than the one saved by the set_log_options operation, the operation shall return without performing any action. If the log_level parameter value is less than or equal to the one saved, the log operation shall perform two actions: It shall append a string representation of the parameters passed to the log operation to the end of the file opened by the set_log_options operation. If the value of the distribute option was set on the call to set_log_options, the plugin shall fill an object of type BuiltinLoggingType with the values passed as arguments to the log operation and publish it using the DataWriter associated with the BuiltinLoggingTopic created by the set_log_options operation. enable_logging This operation shall save the fact that logging was enabled such that the information can be used by the log operation.
- 208. 198 DDS Security v1.0 Beta1 10Plugin Language Bindings 10.1Introduction Clause 8 defines the plugin interfaces in a programming-language independent manner using UML. Using the terminology of the DDS specification this UML definition could be considered a Platform Independent Model (PIM) for the plugin interfaces. The mapping to each specific programming languages platform could therefore be considered a Platform Specific Model (PSM) for that programming language. The mapping of the plugin interfaces to specific programming languages is defined by first defining the interfaces using OMG-IDL version 3.5 with the additional syntax defined in the DDS-XTYPES specification and subsequently applying the IDL to language mapping to the target language. IDL Types lacking the DDS-XTYPES @Entensibility annotation shall be interpreted as having the extensibility kind EXTENSIBLE_EXTENSIBILITY. This matches the DDS-XTYPES specification implied extensibility of un-annotated types. For consistency with the DDS specification, the DDS security specification defines language bindings to each of the language PSMs specified for DDS, namely: C as derived from the IDL to C mapping C++ classic, as derived from the IDL to C++ mapping Java classic, as derived from the IDL to Java mapping C++ modern, aligned with the DDS-STDC++ specification, this is derived from the IDL to C++11 mapping Java modern with the DDS-JAVA5+ specification 10.2IDL representation of the plugin interfaces For consistency in the resulting APIs, the mapping from the plugin interfaces defined in clause 8 and the OMG IDL follows the same PIM to PSM mapping rules as the OMG DDS specification (see sub clause 7.2.2 of the DDS specification version 1.2 [1]). A relevant subset of these rules is repeated here. In this rules “PIM” refers to the UML description of the interfaces in clause 8 and PSM refers to the OMG-IDL description of the interfaces that appears in the associated file: dds_security.idl The PIM to PSM mapping maps the UML interfaces and classes into IDL interfaces. Plain data types are mapped into structures. ‘Out’ parameters in the PIM are conventionally mapped to ‘inout’ parameters in the PSM in order to minimize the memory allocation performed by the Service and allow for more efficient implementations. The intended meaning is that the caller of such an operation should provide an object to serve as a “container” and that the operation will then “fill in” the state of that objects appropriately. The resulting IDL representation of the plugin interfaces appears in the file dds_security.idl which shall be considered part of the DDS Security specification.
- 209. DDS Security v1.0 Beta 1 199 10.3C language representation of the plugin interfaces The C language representation of the plugin interfaces shall be obtained applying the IDL to C mapping [5] to the dds_security.idl file. 10.4C++ classic representation of the plugin interfaces The C++ classic (without the use of the C++ standard library) language representation of the plugin interfaces shall be obtained using the IDL2C++ mapping [7] to the dds_security.idl file. 10.5Java classic The Java classic language representation of the plugin interfaces shall be obtained using the IDL2Java mapping [6] to the dds_security.idl file. 10.6C++11 representation of the plugin interfaces This representation is aligned with the DDS-STDC++ PSM. The C++ classic language representation of the plugin interfaces shall be obtained using the IDL2C++11 mapping [8] to the dds_security.idl file with the following exceptions: 1. The IDL module DDS shall be mapped to the C++ namespace dds so it matches the namespace used by the DDS-STD-C++ PSM. 2. The mapping shall not use any C++11-only feature of the language or the library (e.g., move constructors, noexcept, override, std::array). 3. Arrays shall map to the dds::core::array template defined in the DDS-STD-C++ PSM. 4. The enumerations shall map to the dds::core::safe_enum template defined in the DDS-STD- C++ PSM. 5. The IDL DynamicData native type shall be mapped to the C++ type dds::code::xtypes::DynamicData defined in the DDS-STDC++ PSM. 10.7Java modern aligned with the DDS-JAVA5+ PSM The Java classic language representation of the plugin interfaces shall be obtained using the IDL2Java mapping [6] to the dds_security.idl file with the following exceptions: 1. The IDL module DDS shall be mapped to the Java namespace org.omg.dds so it matches the namespace used by the DDS-JAVA5+ PSM. 2. The IDL DynamicData native type shall be mapped to the type org.omg.dds.type.dynamic.DynamicData defined in the DDS-JAVA5+ PSM.
- 210. 200 DDS Security v1.0 Beta1 Annex A - References [1] DDS: Data-Distribution Service for Real-Time Systems version 1,2. http://www.omg.org/spec/DDS/1.2 [2] DDS-RTPS: Data-Distribution Service Interoperability Wire Protocol version 2.1, http://www.omg.org/spec/DDS-RTPS/2.1/ [3] DDS-XTYPES: Extensible and Dynamic Topic-Types for DDS version 1.0 http://www.omg.org/spec/DDS-XTypes/1.0 [4] OMG-IDL: Interface Definition Language (IDL) version 3.5 http://www.omg.org/spec/IDL35/ [5] IDL2C: IDL to C Language Mapping, Version 1.0. http://www.omg.org/spec/C/1.0/ [6] IDL2Java: IDL To Java Language Mapping, Version 1.3 http://www.omg.org/spec/I2JAV/1.3/ [7] IDL2C++: IDL to C++ Language Mapping (CPP), Version 1.3 http://www.omg.org/spec/CPP/1.3/PDF [8] IDL2C++11: IDL To C++11 Language Mapping http://www.omg.org/spec/CPP11/ [9] Transport Layer Security, http://en.wikipedia.org/wiki/Transport_Layer_Security [10] IPSec, http://en.wikipedia.org/wiki/IPsec [11] DSA, FIPS PUB 186-3 Digital Signature Standard (DSS). http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf [12] Diffie-Hellman (D-H) Key Agreement Method. IETF RFC 2631. http://tools.ietf.org/html/rfc2631 [13] 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 [14] Erramilli, S.; Gadgil, S.; Natarajan, N., “Efficient assignment of multicast groups to publish- subscribe information topics in tactical networks”, MILCOM 2008 [15] “RFC 2094 - Group Key Management Protocol (GKMP) Architecture”, http://www.faqs.org/rfcs/rfc2094.html [16] Raghav Bhaskar, Daniel Augot, Cedric Adjih, Paul Muhlethaler and Saadi Boudjit, “AGDH (Asymmetric Group Diffie Hellman): An Efficient and Dynamic Group Key Agreement Protocol for Ad hoc Networks”, Proceedings of New Technologies, Mobility and Security (NTMS) conference, Paris, France, May 2007 [17] Qianhong Wu, Yi Mu, Willy Susilo, Bo Qin and Josep Domingo-Ferrer “Asymmetric Group Key Agreement”, EUROCRYPT 2009 [18] “Secure IP Multicast”, http://www.cisco.com/en/US/prod/collateral/iosswrel/ps6537/ps6552/prod_presentation0900ae cd80473105.pdf [19] 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 [20] M. Baugher, D. McGrew, M. Naslund, E. Carrara, K. Norrman, “The Secure Real-time Transport Protocol (SRTP)” IETF RFC 3711, http://tools.ietf.org/html/rfc3711 [21] Baugher, M., Weis, B., Hardjono, T. and H. Harney, "The Group Domain of Interpretation,” IETF RFC 3547, http://tools.ietf.org/html/rfc3547, July 2003. [22] P. Zimmerman, A. Johnston, and J. Callas, “ZRTP: Media Path Key Agreement for Secure RTP”, Internet-Draft, March 2009 [23] F. Andreason, M. Baugher, and D. Wing, “Session description protocol (SDP) security description for media streams,” IETF RFC 4568, July 2006
- 211. DDS Security v1.0 Beta 1 201 [24] D. Ignjatic, L. Dondeti, F. Audet, P. Lin, “MIKEY-RSA-R: An Additional Mode of Key Distribution in Multimedia Internet KEYing (MIKEY)”, RFC 4738, November 2006. [25] 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. [26] Bruce Schneier (August 2005). "SHA-1 Broken". Retrieved 2009-01-09. " [27] H. Krawczyk, M. Bellare, and R.Canetti, “HMAC: Keyed-Hashing for Message Authentication” IETF RFC 2104, http://tools.ietf.org/html/rfc2104 [28] Bellare, Mihir (June 2006). "New Proofs for NMAC and HMAC: Security without Collision- Resistance". In Dwork, Cynthia. Advances in Cryptology – Crypto 2006 Proceedings. Lecture Notes in Computer Science 4117. Springer-Verlag. [29] 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 [30] 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_whit e_paper0900aecd804c363f.html [31] CiscoIOS Secure Multicast, http://www.cisco.com/en/US/prod/collateral/iosswrel/ps6537/ps6552/prod_white_paper0900ae cd8047191e.html [32] A. Mason. IPSec Overview Part Two: Modes and Transforms. http://www.ciscopress.com/articles/article.asp?p=25477 [33] 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 Network and Distributed Systems Security Symposium, San Diego, CA, 2000 [34] T. Aurisch, and C. Karg, “Using the IPSec architecture for secure multicast communications,” 8th International Command and Control Research and Technology Symposium (ICCRTS), Washington D.C., 2003 [35] J. Zhang and C. Gunter. Application-aware secure multicast for power grid communications, International Journal of Security and Networks, Vol 6, No 1, 2011 [36] List of reserved RTPS Vendor Ids. http://portals.omg.org/dds/content/page/dds-rtps-vendor- and-product-ids [37] PKCS #7: Cryptographic Message Syntax Version 1.5. IETF RFC 2315. http://tools.ietf.org/html/rfc2315 [38] File expression matching syntax for fnmatch() ; POSIX fnmatch API (IEEE 1003.2-1992 Section B.6)