Contents, Parts 4-9

Part 4: Request-Reply Communication Pattern

22	Introduction to the Request-Reply Communication Pattern ......				22-1
	22.1	The Request-Reply Pattern .................................................................................................................			22-2
		22.1.1	Request-Reply Correlation....................................................................................................		22-3
	22.2	Single-Request, Multiple-Replies ......................................................................................................			22-3
	22.3	Multiple Repliers..................................................................................................................................			22-4
	22.4	Combining Request-Reply and Publish-Subscribe .........................................................................			22-4
23	Using the Request-Reply Communication Pattern ......................				23-1
	23.1	Requesters .............................................................................................................................................			23-2
		23.1.1	Creating a Requester ..............................................................................................................		23-2
		23.1.2	Destroying a Requester..........................................................................................................		23-3
		23.1.3	Setting Requester Parameters ...............................................................................................		23-3
		23.1.4 Summary of Requester Operations......................................................................................			23-4
		23.1.5	Sending Requests....................................................................................................................		23-5
		23.1.6 Processing Incoming Replies with a Requester .................................................................			23-5
			23.1.6.1	Waiting for Replies ..................................................................................................	23-6
			23.1.6.2	Getting Replies .........................................................................................................	23-6
			23.1.6.3	Receiving Replies.....................................................................................................	23-8
	23.2	Repliers..................................................................................................................................................			23-8
		23.2.1	Creating a Replier...................................................................................................................		23-9
		23.2.2	Destroying a Replier ..............................................................................................................		23-9
		23.2.3	Setting Replier Parameters....................................................................................................		23-9
		23.2.4 Summary of Replier Operations.........................................................................................			23-10
		23.2.5 Processing Incoming Requests with a Replier ..................................................................			23-11
			23.2.5.1	Waiting for Requests ..............................................................................................	23-11
			23.2.5.2	Reading and Taking Requests...............................................................................	23-11
			23.2.5.3	Receiving Requests ................................................................................................	23-12
		23.2.6	Sending Replies ....................................................................................................................		23-13
	23.3	SimpleRepliers....................................................................................................................................			23-13
		23.3.1	Creating a SimpleReplier.....................................................................................................		23-13
		23.3.2	Destroying a SimpleReplier ................................................................................................		23-13
		23.3.3	Setting SimpleReplier Parameters......................................................................................		23-14
		23.3.4 Getting Requests and Sending Replies with a SimpleReplierListener .........................			23-14

iii

23.4 Accessing Underlying DataWriters and DataReaders..................................................................

23-14

Part 5: RTI Secure WAN Transport

24 Secure WAN Transport ....................................................................			24-1
24.1	WAN Traversal via UDP Hole-Punching .........................................................................................		24-2
	24.1.1	Protocol Details.......................................................................................................................	24-2
24.2	WAN Locators ......................................................................................................................................		24-5
24.3	Datagram Transport-Layer Security (DTLS)....................................................................................		24-6
	24.3.1	Security Model........................................................................................................................	24-6
	24.3.2	Liveliness Mechanism............................................................................................................	24-7
24.4	Certificate Support...............................................................................................................................		24-7
24.5	License Issues .......................................................................................................................................		24-8

25 Configuring RTI Secure WAN Transport .........................................			25-1
25.1	Example Applications .........................................................................................................................		25-1
25.2	Setting Up a Transport with the Property QoS................................................................................		25-2
25.3	WAN Transport Properties .................................................................................................................		25-3
25.4	Secure Transport Properties................................................................................................................		25-8
25.5	Explicitly Instantiating a WAN or Secure Transport Plugin.........................................................		25-11
	25.5.1 Additional Header Files and Include Directories.............................................................		25-11
	25.5.2	Additional Libraries..............................................................................................................	25-11
	25.5.3	Compiler Flags.......................................................................................................................	25-11

Part 6: RTI Persistence Service

26	Introduction to RTI Persistence Service.........................................				26-1
27	Configuring Persistence Service....................................................				27-1
	27.1	How to Load the XML Configuration...............................................................................................			27-1
	27.2	XML Configuration File ......................................................................................................................			27-2
		27.2.1	Configuration File Syntax .....................................................................................................		27-3
		27.2.2	XML Validation.......................................................................................................................		27-4
			27.2.2.1	Validation at Run Time ...........................................................................................	27-4
			27.2.2.2	Validation During Editing ......................................................................................	27-4
	27.3	QoS Configuration...............................................................................................................................			27-5
	27.4	Configuring the Persistence Service Application............................................................................			27-6
	27.5	Configuring Remote Administration................................................................................................			27-7
	27.6	Configuring Persistent Storage ..........................................................................................................			27-7
	27.7	Configuring Participants....................................................................................................................			27-11
	27.8	Creating Persistence Groups ............................................................................................................			27-12
		27.8.1	QoSs........................................................................................................................................		27-15

iv

		27.8.2	DurabilityService QoS Policy..............................................................................................	27-16
		27.8.3	Sharing a Publisher/Subscriber .........................................................................................	27-16
		27.8.4	Sharing a Database Connection..........................................................................................	27-16
		27.8.5	Memory Management .........................................................................................................	27-17
	27.9	Configuring Durable Subscriptions in Persistence Service .........................................................		27-18
		27.9.1	Sample Memory Management With Durable Subscriptions .........................................	27-18
	27.10	Synchronizing of Persistence Service Instances ............................................................................		27-19
	27.11	Enabling RTI Distributed Logger in Persistence Service .............................................................		27-19
	27.12	Enabling RTI Monitoring Library in Persistence Service.............................................................		27-20
	27.13	Support for Extensible Types ...........................................................................................................		27-20
		27.13.1 Type Version Discrimination...............................................................................................		27-21
28	Running RTI Persistence Service ....................................................			28-1
	28.1	Starting Persistence Service ................................................................................................................		28-1
	28.2	Stopping Persistence Service..............................................................................................................		28-2
29	Administering Persistence Service from a Remote Location......			29-1
	29.1	Enabling Remote Administration......................................................................................................		29-1
	29.2	Remote Commands .............................................................................................................................		29-1
		29.2.1	start ...........................................................................................................................................	29-2
		29.2.2	stop ...........................................................................................................................................	29-2
		29.2.3	shutdown.................................................................................................................................	29-2
		29.2.4	status.........................................................................................................................................	29-2
	29.3	Accessing Persistence Service from a Connext Application..........................................................		29-2
30	Advanced Persistence Service Scenarios ...................................			30-1
	30.1	Scenario: Load-balanced Persistence Services .................................................................................		30-1
	30.2	Scenario: Delegated Reliability .........................................................................................................		30-2
	30.3	Scenario: Slow Consumer ...................................................................................................................		30-3

Part 7: RTI CORBA Compatibility Kit

31	Introduction to RTI CORBA Compatibility Kit ................................		31-1
32	Generating CORBA-Compatible Code with rtiddsgen...............		32-1
	32.1	Generating C++ Code..........................................................................................................................	32-2
	32.2	Generating Java Code..........................................................................................................................	32-2

v

33 Supported IDL Types .......................................................................

33-1

Part 8: RTI RTSJ Extension Kit

34	Introduction to RTI RTSJ Extension Kit.............................................	34-1
35	Using RTI RTSJ Extension Kit ............................................................	35-1

Part 9: RTI TCP Transport

36 Configuring the RTI TCP Transport..................................................		36-1
36.1 TCP Communication Scenarios .........................................................................................................		36-1
36.1.1 Communication Within a Single LAN ................................................................................		36-1
36.1.2 Symmetric Communication Across NATs ..........................................................................		36-2
36.1.3 Asymmetric Communication Across NATs .......................................................................		36-3
36.2 Configuring the TCP Transport .........................................................................................................		36-4
36.2.1 Choosing a Transport Mode .................................................................................................		36-4
36.2.2 Explicitly Instantiating the TCP Transport Plugin ............................................................		36-5
36.2.2.1	Additional Header Files and Include Directories ...............................................	36-5
36.2.2.2	Additional Libraries and Compiler Flags ............................................................	36-6
36.2.3 Configuring the TCP Transport with the Property QosPolicy.........................................		36-6
36.2.4 Setting the Initial Peers ..........................................................................................................		36-7
36.2.5 TCP/TLS Transport Properties.............................................................................................		36-8

vi

Chapter 22 Introduction to the Request-Reply Communication Pattern

Important! This chapter describes the Request-Reply communication pattern, which is only available with RTI Connext Messaging.

The fundamental communication pattern provided by Connext is known as DDS data-centric publish-subscribe. The data-centric publish-subscribe pattern is particularly well-suited in situations where the same data must flow from one producer to many consumers, or when data is streaming continuously from producers to consumers. For example, the values produced by a temperature sensor may be observed by multiple applications, such as control applications, UI applications, supervisory applications, historians, etc.

Figure 22.1 Publish-Subscribe Overview

Sending temperature updates using the publish-subscribe pattern

The publish-subscribe pattern supports multicast, which allows efficient distribution from a single source to multiple applications, devices, or subscribers simultaneously. But even with a single subscriber, the publish-subscribe pattern is still advantageous, because the publisher can push new updates to a subscriber as soon as they happen. That way the subscriber always has

22-1

access to the latest data, with minimum delays, and without incurring the overhead of periodically polling what may be stale data. This efficient, low-latency access to the most current information is important for real-time applications.

22.1The Request-Reply Pattern

As applications become more complex, it often becomes necessary to use other communication patterns in addition to publish-subscribe. Sometimes an application needs to get a one-time snapshot of information; for example, to make a query into a database or retrieve configuration parameters that never change. Other times an application needs to ask a remote application to perform an action on its behalf; for example, to invoke a remote procedure call or a service.

To support these scenarios, Connext includes support for the request-reply communication pattern.

Figure 22.2 Request-Reply Overview

Request-Reply communication pattern using a Requester and a Replier

The request-reply pattern has two roles: The requester (service consumer or client) sends a request message and waits for a reply message. The replier (service provider) receives the request message and responds with a reply message.

Using the request-reply pattern with a Replier is straightforward. Connext provides two Entities: the Requester and the Replier manage all the interactions on behalf of the application. The Requester and Replier automatically discover each other based on an application-specified service name. When the application invokes a request, the Requester sends a message (on an automatically-created request Topic) to the Replier, which notifies the receiving application. The application, in turn, uses the Replier to receive the request and send the reply message. The reply message is sent by Connext back to the original Requester (using a different automatically created reply Topic).

Connext supports both blocking and non-blocking request-reply interactions:

❏In a blocking (a.k.a. synchronous) interaction, the requesting application blocks while waiting for the reply. This is typical of applications desiring remote-procedure-call or remote-method-invocation interactions.

❏In a non-blocking (a.k.a. asynchronous) interaction, the requesting application can proceed with other work and gets notified when a reply is available.

Later this chapter explains how an application can use the methods provided by the Requester and the Replier to perform both blocking and non-blocking request-reply interactions.

The implementation of request-reply in Connext is highly scalable. A Replier can receive requests from thousands of Requesters at the same time. Connext will efficiently deliver each reply only to

22-2

the original Requester, allowing the number of Requesters to grow without significantly impacting each other.

22.1.1Request-Reply Correlation

An application might have multiple outstanding requests, all originating from the same Requester. This can be as a result of using a non-blocking request-reply interaction, or as a result of having multiple application threads using the same Requester. Because of this, Connext provides a way for the application to correlate a reply with the request it is associated with. This meta-data is provided as part of a SampleInfo structure that accompanies the reply.

When using a blocking request operation, Connext provides an easy-to-use API that automatically does the correlation for you.

22.2Single-Request, Multiple-Replies

Connext also supports the single-request multiple-reply pattern. This pattern is an extension of the basic request-reply pattern in which multiple reply messages can flow back as a result of a single request.

The single-request multiple-reply pattern is very useful when getting large amounts of data as a reply, such as when querying a system for all data that matches a certain criteria. Another common use-case is invoking a service that goes through multiple stages and provides updates on each: service commencement, progress reports, and final completion.

Figure 22.3 Single Request, Multiple Replies

Request/Reply communication pattern with multiple replies resulting from a single request

For example, a mobile asset management system may need to locate a particular asset (truck, locomotive, etc.). The system sends out the request. The first reply that comes back will read “locating.” The service has not yet determined the position, but it notifies the requester that the search operation has started. The second reply might provide a status update on the search, perhaps including a rough area of location. The third and final reply will have the exact location of the asset.

22-3

22.3Multiple Repliers

Connext directly supports applications that obtain results from multiple providers in parallel instead of in sequence, basically implementing functional parallelism.

To illustrate, consider a system managing a fleet of drones, like unmanned aerial vehicles (UAVs). Using the single request-multiple reply pattern, the application can use a Requester to send a single ‘DroneInfo’ request to all the drones to query for their current mission and status. Each drone replies with the information on its own status and the Requester aggregates all the responses for the application.

As another example, consider a system that would like to locate the best printer to perform a particular job. The application can use a Requester to query all the printers that are on-line for their characteristics and load. The Requester receives the replies and accumulates them until an application-specified number of replies is received (or a timeout elapses). The application can then use the Requester to access all the replies, examine their contents, and select the best printer for the job.

Figure 22.4 Multiple Repliers

Request/Reply communication pattern with a single Requester and multiple Repliers

22.4Combining Request-Reply and Publish-Subscribe

Under the hood Connext implements request-reply using the DDS data-centric publish- subscribe pattern. This has a key benefit in that the two patterns can be combined, and mapped without interference.

For example, a pair of applications may be involved in a two-way conversation using request- reply. For debugging purposes or regulatory compliance, you want to inspect those request- reply messages, but without disrupting the conversation.

22-4

Figure 22.5 Combining Patterns

Combining Request-Reply and Publish-Subscribe patterns

Since Connext implements requests and replies using DDS data-centric publish subscribe, others can simply subscribe to the request and reply messages. You can introduce a subscriber to the reply Topic, without interfering with the two-way conversation between the Requester and the Replier. This pattern is also known as a Wire Tap. For example, you can use RTI Recording Service to non-intrusively capture request-reply traffic.

22-5

Chapter 23 Using the Request-Reply Communication

Pattern

Important! This chapter explains how to use and configure the Request-Reply communication pattern, which is only available with RTI Connext Messaging.

There are two basic Connext entities used by the Request-Reply communication pattern:

Requester and Replier.

❏A Requester publishes a request Topic and subscribes to a reply Topic. See Requesters (Section 23.1).

❏A Replier subscribes to the request Topic and publishes the reply Topic. See Repliers (Section 23.2).

There is an alternate type of replier known as a SimpleReplier:

•A SimpleReplier is useful for cases where there is a single reply to each request and the reply can be generated quickly, such as looking up some data from memory.

•A SimpleReplier is used in combination with a user-provided SimpleReplierListener. Requests are passed to a callback in the SimpleReplierListener, which returns the reply.

•The SimpleReplier is not suitable if the replier needs to generate more than one reply for a single request or if generating the reply can take significant time or needs to occur asynchronously. For more information, see SimpleRepliers (Section 23.3).

Additional resources. In addition to the information in this chapter, you can find more information and example code at the following locations:

❏The Connext API Reference HTML documentation1 contains example code that will show you how to use API: From the Modules tab, navigate to Programming How To’s, Request-Reply Examples.

❏The Connext API Reference HTML documentation also contains the full API documentation for the Requester, Replier, and SimpleReplier. Under the Modules tab, navigate to RTI Connext Request-Reply API Reference.

1. The API Reference documentation is available for all supported programming languages. Open <installation direc- tory>/ReadMe.html.

23-1

23.1Requesters

A Requester is an entity with two associated DDS Entities: a DDS DataWriter bound to a request Topic and a DDS DataReader bound to a reply Topic. A Requester sends requests by publishing samples of the request Topic, and receives replies for those requests by subscribing to the reply

Topic.

Valid types for request and reply Topics can be:

❏For the C API:

•DDS types generated by rtiddsgen

❏For all other APIs:

•DDS types generated by rtiddsgen

•Built-in types, such as, String, KeyedString, Octets, and KeyedOctets

•DDS DynamicData Types

To communicate, a Requester and Replier must use the same request Topic name, the same reply Topic name, and be associated with the same DDS domain_id.

A Requester has an associated DomainParticipant, which can be shared with other requesters or Connext entities. All the other entities required for request-reply interaction, including the request and reply Topics, the DataWriter for writing requests, and a DataReader for reading replies, are automatically created when the Requester is constructed.

Connext guarantees that a Requester will only receive replies associated with the requests it sends.

The Requester uses the underlying DataReader not only to receive the replies, but also as a cache that can hold replies to multiple outstanding requests or even multiple replies to a single request. Depending on the HistoryQoSPolicy configuration of the DataReader, the Requester may allow replies to replace previous replies based on the reply data having the same value for the Key fields (see Samples, Instances, and Keys (Section 2.2.2)). The default configuration of the Requester does not allow replacing.

You can configure the QoS for the underlying DataWriter and DataReader in a QoS profile. By default, the DataWriter and DataReader are created with default values (DDS_DATAWRITER_QOS_DEFAULT and DDS_DATAREADER_QOS_DEFAULT, respectively) except for the following:

❏RELIABILITY QosPolicy (Section 6.5.19): kind is set to RELIABLE.

❏HISTORY QosPolicy (Section 6.5.10): kind is set to KEEP_ALL.

❏Several other protocol-related settings for Requesters (see the API Reference HTML documentation: select Modules, Programming How To’s, Request-Reply Examples; then scroll down to the section on Configuring Request-Reply QoS profiles).

23.1.1Creating a Requester

Before you can create a Requester, you need a DomainParticipant and a service name.

Note: The example code snippets in this section use the C++ API. You can find more complete examples in all the supported programming languages (C, C++, Java, C#) in the Connext API Reference HTML documentation and in the “example” directory found in your Connext installation.

To create a Requester with the minimum set of parameters, you can use the basic constructor that receives only an existing DDS DomainParticipant and the name of the service:

23-2

Requester <MyRequestType, MyReplyType> *requester =

new Requester <MyRequestType,MyReplyType> (participant, “ServiceName”);

To create a Requester with specific parameters, you may use a different constructor that receives a RequesterParams structure (described in Section 23.1.3):

Requester (const RequesterParams ¶ms)

The ServiceName parameter is used to generate the names of the request and reply Topics that the Requester and Replier will use to communicate. For example, if the service name is “MyService”, the topic names for the Requester and Replier will be “MyServiceRequest” and “MyServiceReply”, respectively. Therefore, for communication to occur, you must use the same service name when creating the Requester and the Replier entities.

If you want to use topic names different from the ones that would be derived from the ServiceName, you can override the default names by setting the actual request and reply Topic names using the request_topic_name() and reply_topic_name() accessors to the RequesterParams structure prior to creating the Requester.

Example: To create a Requester with default QoS and topic names derived from the service name, you may use the following code:

Requester<Foo, Bar> * requester =

new Requester<Foo, Bar>(participant,"MyService");

Example: To create a Requester with a specific QoS profile with library name “MyLibrary” and profile “MyProfile” defined inside USER_QOS_PROFILES.xml in the current working directory, you may use the following code:

Requester<Foo, Bar> * requester = new Requester<Foo, Bar>( RequesterParams(participant).service_name("MyService")

.qos_profile("MyLibrary", "MyProfile"));

Once you have created a Requester, you can use it to perform the operations in Table 23.2, “Requester Operations”.

23.1.2Destroying a Requester

To destroy a Requester and free its underlying entities you may use the destructor:

virtual ~Requester ()

23.1.3Setting Requester Parameters

To change the RequesterParams that can be used when creating a Requester, you can use the operations listed in Table 23.1, “Operations to Set Requester Parameters”.

Table 23.1 Operations to Set Requester Parameters

Operation	Description
datareader_qos	Sets the QoS of the reply DataReader.
datawriter_qos	Sets the QoS of the request DataWriter.
publisher	Sets a specific Publisher.
qos_profile	Sets a QoS profile for the DDS entities in this requester.
	Sets the name of the Topic used for the request. If this parameter is set, then you
request_topic_name	must also set the reply_topic_name parameter and you should not set the
	service_name parameter.
	Sets the name of the Topic used for the reply. If this parameter is set, then you
reply_topic_name	must also set the request_topic_name parameter and you should not set the
	service_name parameter.
reply_type_support	Sets the type support for the reply type.

23-3

Table 23.1 Operations to Set Requester Parameters

Operation	Description
request_type_support	Sets the type support for the request type.
	Sets the service name. This will automatically set the name of the request Topic
service_name	and the reply Topic. If this parameter is set you should not set the
	request_topic_name or the reply_topic_name.
subscriber	Sets a specific Subscriber.

23.1.4Summary of Requester Operations

There are several kinds of operations an application can perform using the Requester:

❏Sending requests (i.e., publishing request samples on the request Topic)

❏Waiting for replies to be received back.

❏Taking the reply data. This gets the reply data from the Requester and removes from the

Requester cache.

❏Reading the reply data. This gets the reply data from the Requester but leaves it in the Requester cache so it remain accessible to future operations on the Requester.

❏Receiving replies (a convenience operation that is a combination of ‘waiting’ and ‘taking’ the data in a single operation)

These operations are summarized in Requester Operations (Table 23.2)

Table 23.2 Requester Operations

		Operation	Description	Reference
	Sending	send_request	Sends a request.	Section 23.1.5
	Requests
	Waiting for	wait_for_replies	Waits for replies to any request or to a specific	Section 23.1.6.1
	Replies		request.
			Copies a single reply into a Sample container.
			There are variants that allow getting the next reply
		take_reply	available or the next reply to a specific request.
			This operation removes the reply from the
			Requester cache. So subsequent calls to take or read
			replies will not get the same reply again.
	Taking
			Returns a LoanedSamples container with the	Section 23.2
	Reply Data
			collection of replies received by the Requester.
			There are variants that allow accessing all the
		take_replies	replies available or only the replies to a specific
			request.
			This operation removes the returned replies from
			the Requester cache. So subsequent calls to take or
			read replies will not get the same replies again.

23-4

Table 23.2 Requester Operations

		Operation			Description					Reference
			Copies a single reply into a Sample container.
			There are variants that allow getting the next reply
		read_reply	available or the next reply to a specific request.
			This operation leaves the reply on the Requester
			cache. So subsequent calls to take or read replies
			can get the same reply again.
	Reading
			Returns	a	LoanedSamples	container	with		the	Section 23.2
	Reply Data
			collection of replies received by the Requester.
			There are variants that allow accessing all the
		read_replies	replies available or only the replies to a specific
			request.
			This operation leaves the returned replies in the
			Requester cache. So subsequent calls to take or read
			replies can get the same replies again.
		receive_reply	Convenience		function that	combines	a	call	to
	Receiving		wait_for_replies with a call to take_reply.
										Section 23.1.6.3
	Replies	receive_replies	Convenience		function that	combines	a	call	to
			wait_for_replies with a call to take_replies.
	Getting	get_request_datawriter	Retrieves the underlying DataWriter that writes
	Underlying		requests.							Section 23.4
			Retrieves	the underlying DataReader			that reads
	Entities	get_reply_datareader
			replies.

23.1.5Sending Requests

To send a request, use the send_request() operation on the Requester. There are three variants of this operation, depending on the parameters that are passed in:

1.send_request (const TRequest &request)

2.send_request (WriteSample<TRequest> &request)

3.send_request (WriteSampleRef<TRequest> &request)

The first way simply sends a request.

The second way sends a request and gets back information about the request in a WriteSample container. This information can be used to correlate the request with future replies.

The third way is just like the second, but puts the information in a WriteSampleRef, which holds references to the data and parameters. Both WriteSample and WriteSampleRef provide information about the request that can be used to correlate the request with future replies.

23.1.6Processing Incoming Replies with a Requester

The Requester provides several operations that can be used to wait for and access replies:

❏wait_for_replies(), see Waiting for Replies (Section 23.1.6.1)

❏take_reply(), take_replies(), read_reply() and read_replies(), see Getting Replies (Section 23.1.6.2)

❏receive_reply() and receive_replies(), see Receiving Replies (Section 23.1.6.3)

The wait_for_replies operations are used to wait until the replies arrive.

The take_reply, take_replies, read_reply, and read_replies() operations access the replies once they have arrived.

23-5

The receive_reply and receive_replies are convenience functions that combine waiting and accessing the replies and are equivalent to calling the ‘wait’ operation followed by the corresponding take_reply or take_replies operations.

Each of these operations has several variants, depending on the parameters that are passed in.

23.1.6.1Waiting for Replies

Use the wait_for_replies() operation on the Requester to wait for the replies to previously sent requests. There are three variants of this operation, depending on the parameters that are passed in. All these variants block the calling thread until either there are replies or a timeout occurs.

1.wait_for_replies (const DDS_Duration_t &max_wait)

2.wait_for_replies (int min_count,

const DDS_Duration_t &max_wait)

3. wait_for_replies (int min_count,

const DDS_Duration_t &max_wait,

const SampleIdentity_t &related_request_id)

The first variant (only passing in max_wait) blocks until a reply is available or until max_wait time has elapsed, whichever comes first. The reply can be to any of the requests made by the

Requester.

The second variant (passing in min_count and max_wait) blocks until at least min_count replies are available or until max_wait time has elapsed, whichever comes first. These replies may all be to the same request or to different requests made by the Requester.

The third variant (passing in min_count, max_wait, and related_request_id) blocks until at least min_count replies to the request identified by the related_request_id are available, or until max_wait time has passed, whichever comes first. Note that unlike the previous variants, the replies must all be to the same single request (identified by the related_request_id) made by the

Requester.

Typically after waiting for replies, you will call take_reply, take_replies, read_reply, or read_replies(), see Repliers (Section 23.2).

If you call wait_for_replies() several times without ‘taking’ the replies (using the take_reply or take_replies operation), future calls to wait_for_replies() will return immediately and will not wait for new replies.

23.1.6.2Getting Replies

You can use the following operations to access replies: take_reply, take_replies, read_reply, and read_replies().

As mentioned in Summary of Requester Operations (Section 23.1.4), the difference between the ‘take’ operations (take_reply, take_replies) and the ‘read’ operations (read_reply, read_replies) is that ‘take’ operations remove the replies from the Requester cache. This means that future calls to take_reply, read_reply, read_reply, and read_reply will not get the same reply again.

The take_reply and read_reply operations access a single reply, whereas the take_replies and read_replies can access a collection of replies.

There are four variants of the take_reply and read_reply operations, depending on the parameters that are passed in:

1.take_reply (Sample<TReply> &reply) read_reply (Sample<TReply> &reply)

2.take_reply (SampleRef<TReply> reply) read_reply (SampleRef<TReply> reply)

23-6

3.	take_reply	(Sample<TReply> &reply,
		const SampleIdentity_t &related_request_id)
	read_reply	(Sample<TReply> &reply,
		const SampleIdentity_t &related_request_id)
4.	take_reply	(SampleRef<TReply> reply,
		const SampleIdentity_t &related_request_id)
	read_reply	(SampleRef<TReply> reply,
		const SampleIdentity_t &related_request_id)

The first two variants provide access to the next reply in the Requester cache. This is the earliest reply to any previous requests sent by the Requester that has not been ‘taken’ from the Requester cache. The remaining two variants provide access to the earliest non-previously ‘taken’ reply to the request specified by the related_request_id.

Notice that some of these variants use a Sample, while other use a SampleRef. A SampleRef can be used much like a Sample, but it holds references to the reply data and DDS SampleInfo, so there is no additional copy. In contrast using the Sample obtains a copy of both the data and DDS SampleInfo.

The take_replies and read_replies operations access a collection of (one or more) replies to previously sent requests. These operations are convenient when you expect multiple replies to a single request, or when issuing multiple requests concurrently without waiting for intervening replies.

The take_replies and read_replies operations return a LoanedSamples container that holds the replies. To increase performance, the LoanedSamples does not copy the reply data. Instead it ‘loans’ the necessary resources from the Requester. The resources loaned by the LoanedSamples container must be eventually returned, either explicitly calling the return_loan() operation on the LoanedSamples or through the destructor of the LoanedSamples.

There are three variants of the take_replies and read_replies operations, depending on the parameters that are passed in:

1.take_replies (int max_count=DDS_LENGTH_UNLIMITED) read_replies (int max_count=DDS_LENGTH_UNLIMITED)

2.take_replies (int max_count,

const SampleIdentity_t &related_request_id) read_replies (int max_count,

const SampleIdentity_t &related_request_id)

3.take_replies (const SampleIdentity_t &related_request_id) read_replies (const SampleIdentity_t &related_request_id)

The first variant (only passing in max_count) returns a container holding up to max_count replies.

The second variant (passing in max_count and related_request_id) returns a LoanedSamples container holding up to max_count replies that correspond to the request identified by the related_request_id.

The third variant (only passing in related_request_id) returns a LoanedSamples container holding an unbounded number of replies that correspond to the request identified by the related_request_id. This is equivalent to the second variant with max_count = DDS_LENGTH_UNLIMITED.

The resources for the LoanedSamples container must be eventually be returned, either by calling the return_loan() operation on the LoanedSamples or through the LoanedSamples destructor.

23-7

23.1.6.3Receiving Replies

The receive_reply() operation is a shortcut that combines calls to wait_for_replies() and to take_reply(). Similarly the receive_replies() operation combines wait_for_replies() and take_replies().

There is only one variant of the receive_reply() operation:

1.receive_reply (Sample<TReply> &reply, const DDS_Duration_t &timeout)

This operation blocks until either a reply is received or a timeout occurs. The contents of the reply are copied into the provided sample (reply).

There are two variants of the receive_replies() operation, depending on the parameters that are passed in:

1.receive_replies (const DDS_Duration_t &max_wait)

2.receive_replies (int min_count, int max_count,

const DDS_Duration_t &max_wait)

These two variants block until multiple replies are available or a timeout occurs.

The first variant (only passing in max_wait) blocks until at least one reply is available or until max_wait time has passed, whichever comes first. The operation returns a LoanedSamples container holding the replies. Note that there could be more than one reply. This can occur if, for example, there were already replies available in the Requester from previous requests that were not processed. This operation does not limit the number of replies that can be returned on the

LoanedSamples container.

The second variant (passing in min_count, max_count, and max_wait) will block until min_count replies are available or until max_wait time has passed, whichever comes first. Up to max_count replies will be stored into the LoanedSamples container which is returned to the caller.

The resources held in the LoanedSamples container must eventually be returned, either with an explicit call to return_loan() on the LoanedSamples or through the LoanedSamples destructor.

23.2Repliers

A Replier is an entity with two associated DDS Entities: a DDS DataReader bound to a request Topic and a DDS DataWriter bound to a reply Topic. The Replier receives requests by subscribing to the request Topic and sends replies to those requests by publishing on the reply Topic.

Valid data types for these topics are the same as specified for the Requester, see Requesters (Section 23.1).

Much like a Requester, a Replier has an associated DDS DomainParticipant which can be shared with other Connext entities. All the other entities required for the request-reply interaction, including a DataWriter for writing replies and a DataReader for reading requests, are automatically created when the Replier is constructed.

You can configure the QoS for the underlying DataWriter and DataReader in a QoS profile. By default, the DataWriter and DataReader are created with default QoS values (using DDS_DATAWRITER_QOS_DEFAULT and DDS_DATAREADER_QOS_DEFAULT, respectively) except for the following:

❏RELIABILITY QosPolicy (Section 6.5.19): kind is set to RELIABLE

❏HISTORY QosPolicy (Section 6.5.10): kind is set to KEEP_ALL

23-8

The Replier API supports several ways in which the application can be notified of, and process requests:

❏Blocking: The application thread blocks waiting for requests, processes them, and dispatches the reply. In this situation, if the computation necessary to process the request and produce the reply is small, you may consider using the SimpleReplier, which offers a simplified API.

❏Polling: The application thread checks (polls) for request periodically but does not block to wait for them.

❏Asynchronous notification: The application installs a ReplierListener to receive notifications whenever a request is received.

23.2.1Creating a Replier

To create a Replier with the minimum set of parameters you can use the basic constructor that receives only an existing DDS DomainParticipant and the name of the service:

Replier (DDSDomainParticipant * participant, const std::string & service_name)

Example:

Replier<Foo, Bar> * replier =

new Replier<Foo, Bar>(participant, "MyService");

To create a Replier with specific parameters you may use a different constructor that receives a

ReplierParams structure:

Replier (const ReplierParams<TRequest, TReply> ¶ms)

Example:

Replier<Foo, Bar> * replier = new Replier<Foo, Bar>( ReplierParams(participant).service_name("MyService")

.qos_profile("MyLibrary", "MyProfile"));

The service_name is used to generate the names of the request and reply Topics that the Requester and Replier will use to communicate. For example, if the service name is “MyService”, the topic names for the Requester and Replier will be “MyServiceRequest” and “MyServiceReply”, respectively. Therefore it is important to use the same service_name when creating the Requester and the Replier.

If you need to specify different Topic names, you can override the default names by setting the actual request and reply Topic names using request_topic_name() and reply_topic_name() accessors to the ReplierParams structure prior to creating the Replier.

23.2.2Destroying a Replier

To destroy a Replier and free its underlying entities:

virtual ~Replier ()

23.2.3Setting Replier Parameters

To change the ReplierParams that are used to create a Replier, use the operations listed in Table 23.3, “Operations to Set Replier Parameters”.

Table 23.3 Operations to Set Replier Parameters

Operation	Description
datareader_qos	Sets the quality of service of the request DataReader.
datawriter_qos	Sets the quality of service of the reply DataWriter.

23-9

Table 23.3 Operations to Set Replier Parameters

Operation	Description
publisher	Sets a specific Publisher.
qos_profile	Sets a QoS profile for the entities in this replier.
replier_listener	Sets a listener that is called when requests are available.
reply_topic_name	Sets a specific reply topic name.
reply_type_support	Sets the type support for the reply type.
request_topic_name	Sets a specific request topic name.
request_type_support	Sets the type support for the request type.
service_name	Sets the service name the Replier offers and Requesters use to match.
subscriber	Sets a specific Subscriber.

23.2.4Summary of Replier Operations

There are four kinds of operations an application can perform using the Replier:

❏Waiting for requests to be received

❏Reading/taking the request data and associated information

❏Receiving requests (a convenience operation that combines waiting and getting the data into a single operation)

❏Sending a reply for received request (i.e., publishing a reply sample on the reply Topic with special meta-data so that the original Requester can identify it).

The Replier operations are summarized in Table 23.4, “Replier Operations”.

Table 23.4 Replier Operations

		Operation	Description		Reference
	Waiting for	wait_for_requests	Waits for requests.		Section 23.2.5.1
	Requests
		take_request	Copies the contents of a single request into a
			Sample and removes it from the Replier cache.
	Taking
			Returns a LoanedSamples to access	multiple
	Requests
		take_requests	requests and removes the requests from the
			Replier cache.		Section 23.2.5.2
		read_request	Copies the contents of a single request into a
	Reading		Sample, leaving it in the Replier cache
	Requests	read_requests	Returns a LoanedSamples to access	multiple
			requests, leaving them in the Replier cache.
		receive_request	Waits for a single request and copies its contents
	Receiving		into a Sample container.
					Section 23.2.5.3
	Requests	receive_requests	Waits for multiple requests and provides a
			LoanedSamples container to access them.
	Sending	send_reply	Sends a reply for a previous request.		Section 23.2.6
	Replies
	Getting	get_request_datareader	Retrieves the underlying DataReader.
	Underlying				Section 23.4
		get_reply_datawriter	Retrieves the underlying DataWriter.
	Entities

23-10

23.2.5Processing Incoming Requests with a Replier

The Replier provides several operations that can be used to wait for and access the requests:

❏wait_for_requests(), see Waiting for Requests (Section 23.2.5.1)

❏take_request(), take_requests(), read_request(), and read_requests(), see Reading and Taking Requests (Section 23.2.5.2)

❏receive_request() and receive_requests(), see Receiving Requests (Section 23.2.5.3)

The wait_for_requests() operations are used to wait until requests arrive.

The take_request(), take_requests(), read_request(), and read_requests() operations access the requests, once they have arrived.

The receive_request() and receive_requests() operations are convenience functions that combine waiting for and accessing requests and are equivalent to calling the ‘wait’ operation followed by the corresponding take_request() or take_requests() operations.

Each of these operations has several variants, depending on the parameters that are passed in.

23.2.5.1Waiting for Requests

Use the wait_for_requests() operation on the Replier to wait for requests. There are two variants of this operation, depending on the parameters that are passed in. All these variants block the calling thread until either there are replies or a timeout occurs.:

1.wait_for_requests (const DDS_Duration_t &max_wait)

2.wait_for_requests (int min_count, const DDS_Duration_t &max_wait)

The first variant (only passing in max_wait) blocks until one request is available or until max_wait time has passed, whichever comes first.

The second variant blocks until min_count number of requests are available or until max_wait time has passed.

Typically after waiting for requests, you will call take_request, take_requests, read_request, or read_requests, see Sending Replies (Section 23.2.6).

23.2.5.2Reading and Taking Requests

You can use the following four operations to access requests: take_request, take_requests, read_request, or read_requests.

As mentioned in Summary of Replier Operations (Section 23.2.4), the difference between the ‘take’ operations (take_request, take_requests) and the ‘read’ operations (read_request, read_requests) is that ‘take’ operations remove the requests from the Replier cache. This means that future calls to take_request, take_requests, read_request, or read_requests will not get the same request again.

The take_request and read_request operations access a single reply, whereas the take_requests and read_requests can access a collection of replies.

There are two variants of the take_request and read_request operations, depending on the parameters that are passed in:

1.take_request (connext::Sample<TRequest> & request) read_request (connext::Sample<TRequest> & request)

2.take_request (connext::SampleRef<TRequest request) read_request (connext::SampleRef<TRequest request)

The first variant returns the request using a Sample container. The second variant uses a SampleRef container instead. A SampleRef can be used much like a Sample, but it holds references to the request data and DDS SampleInfo, so there is no additional copy. In contrast, using the Sample makes a copy of both the data and DDS SampleInfo.

23-11

The take_requests and read_requests operations access a collection of (one or more) requests in the Replier cache. These operations are convenient when you want to batch-process a set of requests.

The take_requests and read_requests operations return a LoanedSamples container that holds the requests. To increase performance, the LoanedSamples does not copy the request data. Instead it ‘loans’ the necessary resources from the Replier. The resources loaned by the LoanedSamples container must be eventually returned, either explicitly by calling the return_loan() operation on the LoanedSamples or through the destructor of the LoanedSamples.

There is only one variant of these operations:

1.take_requests (int max_samples = DDS_LENGTH_UNLIMITED) read_requests (int max_samples = DDS_LENGTH_UNLIMITED)

The returned container may contain up to max_samples number of requests.

23.2.5.3Receiving Requests

The receive_request() operation is a shortcut that combines calls to wait_for_requests() and take_request(). Similarly, the receive_requests() operation combines wait_for_requests() and take_requests().

There are two variants of the receive_request() operation:

1. receive_request (connext::Sample<TRequest> & request, const DDS_Duration_t & max_wait)

2. receive_request (connext::SampleRef<TRequest> request, const DDS_Duration_t & max_wait)

The receive_request operation blocks until either a request is received or a timeout occurs. The contents of the request are copied into the provided container (request). The first variant uses a Sample container, whereas the second variant uses a SamepleRef container. A SampleRef can be used much like a Sample, but it holds references to the request data and DDS SampleInfo, so there is no additional copy. In contrast, using the Sample obtains a copy of both the data and the DDS SampleInfo.

There are two variants of the receive_requests() operation, depending on the parameters that are passed in:

1.receive_requests (const DDS_Duration_t & max_wait)

2.receive_requests (int min_request_count,

int max_request_count,

const DDS_Duration_t & max_wait)

The receive_requests operation blocks until one or more requests are available, or a timeout occurs.

The first variant (only passing in max_wait) blocks until one request is available or until max_wait time has passed, whichever comes first. The contents of the request are copied into a LoanedSamples container which is returned to the caller. An unlimited number of replies can be copied into the container.

The second variant blocks until min_request_count number of requests are available or until max_wait time has passed, whichever comes first. Up to max_request_count number of requests will be copied into a LoanedSamples container which is returned to the caller.

The resources for the LoanedSamples container must eventually be returned, either with return_loan() or through the LoanedSamples destructor.

23-12

23.2.6Sending Replies

There are three variants for send_reply(), depending on the parameters that are passed in:

1. send_reply (const TReply & reply,

const SampleIdentity_t & related_request_id)

2. send_reply (WriteSample<TReply> & reply,

const SampleIdentity_t & related_request_id)

3. send_reply (WriteSampleRef<TReply> & reply,

const SampleIdentity_t & related_request_id)

This operation sends a reply for a previous request. The related request ID can be retrieved from an existing request Sample.

The first variant is recommended if you do not need to change any of the default write parameters.

The other two variants allow you to set custom parameters for writing a reply. Unlike the Requester, where retrieving the sample ID for correlation is common, on the Replier side using a WriteSample or WriteSampleRef is only necessary when you need to overwrite the default write parameters. If that’s not the case, use the first variant.

23.3SimpleRepliers

The SimpleReplier offers a simplified API to receive and process requests. The API is based on a user-provided object that implements the SimpleReplierListener interface. Requests are passed to the listener operation implemented by the user-provided object, which processes the request and returns a reply.

The SimpleReplier is recommended if each request generates a single reply and computing the reply can be done quickly with very little CPU resources and without calling any operations that may block the processing thread. For example, looking something up in an internal memory- based data structure would be a good use case for using a SimpleReplier.

23.3.1Creating a SimpleReplier

To create a SimpleReplier with the minimum set of parameters, you can use the basic constructor:

SimpleReplier (DDSDomainParticipant *participant, const std::string &service_name,

SimpleReplierListener<TRequest, TReply> &listener)

To create a SimpleReplier with specific parameters, you may use a different constructor that receives a SimpleReplierParams structure:

SimpleReplier (const SimpleReplierParams<TRequest, TReply> ¶ms)

23.3.2Destroying a SimpleReplier

To destroy a SimpleReplier and free its resources use the destructor:

virtual ~SimpleReplier ()

23-13

23.3.3Setting SimpleReplier Parameters

To change the SimpleReplierParams used to create a SimpleReplier, use the operations in Table 23.5, “Operations to Set SimpleReplier Parameters”.

Table 23.5 Operations to Set SimpleReplier Parameters

Operation	Description
datareader_qos	Sets the quality of service of the reply DataReader.
datawriter_qos	Sets the quality of service of the reply DataWriter.
publisher	Sets a specific Publisher.
qos_profile	Sets a QoS profile for the entities in this replier.
reply_topic_name	Sets a specific reply topic name.
reply_type_support	Sets the type support for the reply type.
request_topic_name	Sets a specific request topic name.
request_type_support	Sets the type support for the request type.
service_name	Sets the service name the Replier offers and Requesters use to match.
subscriber	Sets a specific Subscriber.

23.3.4Getting Requests and Sending Replies with a SimpleReplierListener

The on_request_available() operation on the SimpleReplierListener receives a request and returns a reply.

on_request_available(TRequest &request)

This operation gets called when a request is available. It should immediately return a reply. After calling on_request_available(), Connext will call the operation return_loan() on the SimpleReplierListener; this gives the application-defined listener an opportunity to release any resources related to computing the previous reply.

retun_loan(TReply &reply)

23.4Accessing Underlying DataWriters and DataReaders

Both Requester and Replier entities have underlying DDS DataWriter and DataReader entities. These are created automatically when the Requester and Replier are constructed.

Accessing the DataWriter used by a Requester may be useful for a number of advanced use cases, such as:

❏Finding matching subscriptions (e.g., Replier entities), see Finding Matching Subscriptions (Section 6.3.16.1)

❏Setting a DataWriterListener, see Setting Up DataWriterListeners (Section 6.3.4)

❏Getting DataWriter protocol or cache statuses, see Statuses for DataWriters (Section 6.3.6)

❏Flushing a data batch after sending a number of request samples, see Flushing Batches of Data Samples (Section 6.3.9)

❏Modifying the QoS.

Accessing the reply DataReader may be useful for a number of advanced use cases, such as:

❏Finding matching publications (e.g., Requester entities), see Navigating Relationships Among Entities (Section 7.3.9)

23-14

❏Getting DataReader protocol or cache statuses, see Checking DataReader Status and StatusConditions (Section 7.3.5) and Statuses for DataReaders (Section 7.3.7).

❏Modifying the QoS.

To access these underlying objects:

RequestDataWriter * get_request_datawriter()

RequestDataReader * get_request_datareader()

ReplyDataWriter * get_reply_datawriter()

ReplyDataReader * get_reply_datareader()

23-15

Chapter 24 Secure WAN Transport

Secure WAN Transport provides transport plugins that can be used by developers of Connext applications. These transport plugins allow Connext applications running on private networks to communicate securely over a Wide-Area Network (WAN), such the internet. There are two primary components in the package which may be used independently or together: communication over Wide-Area Networks that involve Network Address Translators (NATs), and secure communication with support for peer authentication and encrypted data transport.

The Connext core is transport-agnostic. Connext offers three built-in transports: UDP/IPv4, UDP/IPv6, and inter-process shared memory. The implementation of NAT traversal and secure communication is done at the transport level so that the Connext core is not affected and does not need to be changed, although there is additional on-the-wire traffic.

The basic problem to overcome in a WAN environment is that messages sent from an application on a private local-area network (LAN) appear to come from the LAN's router address, not from the internal IP address of the host running the application. This is due to the existence of a Network Address Translator (NAT) at the gateway. This does not cause problems for client/server systems because only the server needs to be globally addressable; it is only a problem for systems with peer-to-peer communication models, such as Connext. Secure WAN Transport solves this problem, allowing communication between peers that are in separate LAN networks, using a UDP hole-punching mechanism based on the STUN protocol (IETF RFC 3489bis) for NAT traversal. This requires the use of an additional rendezvous server application, the RTI WAN Server.

Once the transport has enabled traffic to cross the NAT gateway to the WAN, it is flowing on network hardware that is shared (in some cases, over the public internet). In this context, it is important to consider the security of data transmission. There are three primary issues involved:

❏Authenticating the communication peer (source or destination) as a trusted partner;

❏Encrypting the data to hide it from other parties that may have access to the network;

❏Validating the received data to ensure that it was not modified in transmission.

Secure WAN Transport addresses these problems by wrapping all RTPS-encoded data using the DTLS protocol (IETF RFC 4347), which is a variant of SSL/TLS that can be used over a datagram network-layer transport such as UDP. The security features of the WAN Transport may also be used on an untrusted local-area network with the Secure Transport.

In summary, the package includes two transports:

❏The WAN Transport is for use on a WAN and includes security. It must be used with the WAN Server, a rendezvous server that provides the ability to discover public addresses and to register and look up peer addresses based on a unique WAN ID. The WAN Server is based on the STUN (Session Traversal Utilities for NAT) protocol [draft-ietfbehave- rfc3489bis], with some extensions. Once information about public addresses for the

24-1

application and its peers has been obtained and connections have been initiated, the server is no longer required to maintain communication with a peer. (Note: security is disabled by default.)

❏The Secure Transport is an alternate transport that provides security on an untrusted LAN. Use of the RTI WAN Server is not required.

Multicast communication is not supported by either of these transports.

This chapter provides a technical overview of:

❏WAN Traversal via UDP Hole-Punching (Section 24.1)

❏WAN Locators (Section 24.2)

❏Datagram Transport-Layer Security (DTLS) (Section 24.3)

❏Certificate Support (Section 24.4)

For information on how to use Secure WAN Transport with your Connext application, see Chapter 25: Configuring RTI Secure WAN Transport.

24.1WAN Traversal via UDP Hole-Punching

In order to resolve the problem of communication across NAT boundaries, the WAN Transport implements a UDP hole-punching solution for NAT traversal [draft-ietf-behave-p2p-state]. This solution uses a rendezvous server, which provides the ability to discover public addresses, and to register and lookup peer addresses based on a unique WAN ID. This server is based on the STUN (Session Traversal Utilities for NAT) protocol [draft-ietf-behave-rfc3489bis], with some extensions. This protocol is a part of the solution used for standards-based voice over IP applications; similar technology has be used by systems such as Skype and has proven to be highly reliable. A key advantage of STUN is that it is based on UDP and therefore is able to preserve the real-time characteristics of the DDS Interoperability Wire Protocol.

Once information about public addresses for the application and its peers has been obtained, and connections have been initiated, the server is no longer required to maintain communication with a peer. However, if communication fails, possibly due to changes in dynamically-allocated addresses, the server will be needed to reopen new public channels.

Figure 24.1 shows the RTI WAN transport architecture.

24.1.1Protocol Details

The UDP hole-punching algorithm implemented by the WAN transport has two different phases: registration and connection. This algorithm only works with cone or asymmetric NATs where the same public address/port is assigned to all the sessions with the same private address/port address.

❏Registration Phase

The RTI WAN Server application runs on a machine that resides on the WAN network (i.e., not in a private LAN). It has to be globally accessible to LAN applications. It is started by a script and acts as a rendezvous point for LAN applications. During the registration phase, each transport locator is registered with the RTI WAN Server using a STUN binding request message.

The RTI WAN Server associates RTPS locators with their corresponding public IPv4 transport addresses (a combination of IP address and port) and stores that information in an internal table. Figure 24.2 illustrates the registration phase.

24-2

Figure 24.1 RTI WAN Transport Architecture

	RTI WAN Rendezvous Server
STUN traffic
		DomainParticipant 1	Server	DomainParticipant 2
	STUN traffic		Register
	DTLS traffic			Register
NAT		Connect to DP 2
		NAT
		DP 2 public address		DP 1 public address
			Connect
STUN		STUN	DTLS handshaking
DTLS	DTLS handshaking	DTLS	RTPS discovery
	Encrypted RTPS
			RTPS user traffic
Connext	RTPS Discovery Traffic	Connext
	RTPS User Traffic
Application 1		Application 2

Figure 24.2 Registration Phase

RTI WAN Server

(18.181.0.31)

(2) From server to locator A		(2) From server to locator B
BIND RESPONSE			BIND RESPONSE
Mapped Address Attribute:		Mapped Address Attribute:
155.99.25.11:8001			138.76.29.7:7001
	NAT	NAT
	(155.99.25.11)	(138.76.29.7)
(1) From locator A to server			(1) From locator B to server
BIND REQUEST			BIND REQUEST
Src Locator Attribute:			Src Locator Attribute:
other.com#192.168.15.100:8000			rti.com#192.168.1.100:7000
Liveliness Period:			Liveliness Period:
60000			60000
Locator A	NAT	NAT	Locator B
other.com#192.168.15.100:8000	Transport	Transport	rti.com#192.168.1.100:700
	Plugin	Plugin	0
		RTPS
	Connext	Connext

❏Connection Phase

The connection phase starts when locator A wants to establish a connection with locator B. Locator A obtains information about locator B via Connext discovery traffic or the initial NDDS_DISCOVERY_PEERS list. To establish a connection with locator B, locator A sends a STUN connect request to the RTI WAN server. The server sends a STUN connect response to locator A, including information about the public IP transport

24-3

address (IP address and port) of locator B. In parallel, the RTI WAN server contacts locator B using another STUN connect request to let it know that locator A wants to establish a connection with it.

When locator A receives the public IP address of locator B, it will try to contact B using two STUN binding request messages. The first message is sent to the public address of B and the second message is sent to the private address of B. The private address was obtained using the last 32 bits of the locator address of B. The STUN binding request message directed to the public transport address of B sent by locator A will open a hole in A's NAT to receive messages from B.

When locator B receives the public address of locator A, it will try to contact A sending a STUN binding request message to that public address. This message will open a hole in B's NAT to receive messages from A. When locator A receives the first STUN binding response from locator B, it starts sending RTPS traffic.

The connection phase includes two processes: the connect process (Figure 24.3 on page 24-4) and the NAT hole punching process (Figure 24.4 on page 24-5).

Figure 24.3 Connect Process

	RTI WAN Server
	(18.181.0.31)
(2) From server to locator A	(3) From server to locator B
	CONNECT REQUEST
CONNECT RESPONSE	Src Locator Attribute:
Mapped Address Attribute:	rti.com#192.168.1.100:7000
138.76.29.7:7001	Dst Locator Attribute
	other.com#192.168.15.100:8000
	Mapped Address Attribute:
	155.99.25.11:8001
NAT	NAT
(155.99.25.11)	(138.76.29.7)

(1)From locator A to server CONNECT REQUEST

Src Locator Attribute:			(4) From locator B to server
other.com#192.168.15.100:8000			CONNECT RESPONSE
Dst Locator Attribute
rti.com#192.168.1.100:7000
Locator A	WAN	WAN	Locator B
other.com#192.168.15.100:8000	Transport	Transport	rti.com#192.168.1.100:7000
	Plugin	Plugin
		RTPS
	Connext	Connext

❏STUN Liveliness

Finally, since bindings allocated by NAT expire unless refreshed, the clients (locators) must generate binding request messages for the server and other clients to refresh the bindings. The RTI STUN protocol implementation uses the attribute LIVELINESS- PERIOD in the STUN binding request to indicate the period in milliseconds at which a client will assert its liveliness. The WAN Server will remove a locator from its mapping table when the liveliness contract is not met. Likewise, a transport instance will remove a STUN connection with a locator when this locator does not assert its liveliness as indicated in the last binding request.

24-4

Figure 24.4 NAT Hole Punching Process

RTI WAN Server

(18.181.0.31)

NAT	NAT
(155.99.25.11)	(138.76.29.7)

24.2WAN Locators

The WAN transport does not use simple IP addresses to locate peers. A WAN transport locator consists of a WAN ID, which is an arbitrary 12-byte value, and a bottom 4-byte value that specifies a fallback local IPv4 address. Your peers list (NDDS_DISCOVERY_PEERS) must be configured to look for peers with locators of the form:

24-5

❏The address is a 128-bit address in IPv6 notation.

❏The "wan://" part specifies that the address is for the WAN transport.

❏The next part, "::1", specifies the top 12 bytes of the address to be 11 zero bytes, followed by a byte with value 1 (this corresponds to the peer's WAN ID).

❏The last part, "10.10.1.150" refers to the peers local IPv4 address, which will be used if the peers are on the same local network.

A DomainParticipant using the WAN transport will have to initialize the DDS_DiscoveryQosPolicy’s initial_peers field with the WAN locator addresses corresponding to the peers to which it wants to connect to. The value of initial_peers can be set using the environment variable NDDS_DISCOVERY_PEERS or the NDDS_DISCOVERY_PEERS configuration file. (See Configuring the Peers List Used in Discovery (Section 14.2).)

24.3Datagram Transport-Layer Security (DTLS)

Data security is provided by wrapping all Connext network traffic with the Datagram Transport Layer Security (DTLS) protocol (IETF RFC 4347). DTLS is a relatively recent variant of the mature SSL/TLS family of protocols which adds the capability to secure communication over a connectionless network-layer transport such as UDP. UDP is the preferred network layer transport for the DDS wire protocol RTPS, as well as for NAT traversal. Like SSL/TLS, the DTLS protocol provides capabilities for certificate-based authentication, data encryption, and message integrity. The protocol specifies a number of standard cryptographic algorithms that must be available; the base set is listed in the TLS 1.1 specification (IETF RFC 4346).

Secure protocol support is provided by the open source OpenSSL library, which has supported the DTLS protocol since the release of OpenSSL 0.9.8. Note however that many critical issues in DTLS were resolved by the OpenSSL 0.9.8f release. For more detailed information about available ciphers, certificate support, etc. please refer to the OpenSSL documentation. The DTLS protocol securely authenticates with each individual peer; as such, multicast communication is not supported by the Secure Transport. There is also a FIPS security-certified version of OpenSSL (OpenSSL-FIPS 1.1.1), but this does not yet support DTLS.

The Secure Transport protocol stack is similar to the Secure WAN transport stack, but without the STUN layer and server. See Figure 24.1 on page 24-3.

24.3.1Security Model

In order to communicate securely, an instance of the secure plugin requires: 1) a certificate authority (shared with all peers), 2) an identifying certificate which has been signed by the authority, 3) the private key associated with the public key contained in the certificate.

The Certificate Authority (CA) is specified by using a PEM format file containing its public key or by using a directory of PEM files following standard OpenSSL naming conventions. If a single CA file is used, it may contain multiple CA keys. In order to successfully communicate with a peer, the CA keys that are supplied must include the CA that has signed that peer's identifying certificate.

The identifying certificate is specified by using a PEM format file containing the chain of CAs used to authenticate the certificate. The identifying certificate must be signed by a CA. It will either be directly signed by a root CA (one of the CAs supplied above), by an authority whose certificate has been signed by the root CA, or by a longer chain of certificate authorities. The file must be sorted starting with the certificate to the highest level (root CA). If the certificate is directly signed by a root CA, then this file will only contain the root CA certificate followed by the identity certificate.

24-6

Finally, a private key is required. In order to avoid impersonation of an identity, this should be kept private. It can be stored in its own PEM file specified in one of the private key properties, or it can be appended to the certificate chain file.

One complication in the use of DTLS for communication by Connext is that even though DTLS is a connectionless protocol, it still has client/server semantics. The RTI Secure Transport maps a bidirectional communication channel between two peer applications into a pair of unidirectional encrypted channels. Both peers are playing the part of a client (when sending data) and a server (when receiving).

24.3.2Liveliness Mechanism

When a peer shuts down cleanly, the DTLS protocol ensures that resources are released. If a peer crashes or otherwise stops responding, a liveliness mechanism in the DTLS transport cleans up resources. You can configure the DTLS handshake retransmission interval and the connection liveliness interval.

24.4Certificate Support

Cryptographic certificates are required to use the security features of the WAN transport. This section describes a mechanism to use the OpenSSL command line tool to generate a simple private certificate authority. For more information, see the manual page for the openssl tool (http://www.openssl.org/docs/apps/openssl.html) or the book, "Network Security with OpenSSL" by Viega, Messier, & Chandra (O'Reilly 2002), or other references on Public Key Infrastructure.

1.Initialize the Certificate Authority:

a.Create a copy of the openssl.cnf file and edit fields to specify the proper default names and paths.

b.Create the required CA directory structure:

mkdir myCA

mkdir myCA/certs mkdir myCA/private mkdir myCA/newcerts mkdir myCA/crl

touch myCA/index.txt

c. Create a self-signed certificate and CA private key:

openssl req -nodes -x509 -days 1095 -newkey rsa:2048 \ -keyout myCA/private/cakey.pem -out myCA/cacert.pem \ -config openssl.cnf

2.For each identifying certificate:

a.You may want to create a copy of your customized openssl.cnf file with default identi- fying information to be used as a template for certificate request creation; the com- mands below refer to this file as template.cnf.

b.Generate a certificate request and private key:

openssl req -nodes -new -newkey rsa:2048 -config template.cnf \ -keyout peer1key.pem -out peer1req.pem

c. Use the CA to sign the certificate request to generate certificate:

openssl ca -create_serial -config openssl.cnf -days 365 \ -in peer1req.pem -out myCA/newcerts/peer1cert.pem

24-7

*

*/

Original SSLeay License

-----------------------

/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)

*All rights reserved.

*This package is an SSL implementation written

*by Eric Young (eay@cryptsoft.com).

*The implementation was written so as to conform with Netscapes SSL.

*This library is free for commercial and non-commercial use as long as

*the following conditions are aheared to. The following conditions

*apply to all code found in this distribution, be it the RC4, RSA,

*lhash, DES, etc., code; not just the SSL code. The SSL documentation

*included with this distribution is covered by the same copyright terms

*except that the holder is Tim Hudson (tjh@cryptsoft.com).

*

*Copyright remains Eric Young's, and as such any Copyright notices in

*the code are not to be removed.

*If this package is used in a product, Eric Young should be given

*attribution

*as the author of the parts of the library used.

*This can be in the form of a textual message at program startup or

*in documentation (online or textual) provided with the package.

*

*Redistribution and use in source and binary forms, with or without

*modification, are permitted provided that the following conditions

*are met:

*1. Redistributions of source code must retain the copyright

*notice, this list of conditions and the following disclaimer.

*2. Redistributions in binary form must reproduce the above copyright

*notice, this list of conditions and the following disclaimer in the

*documentation and/or other materials provided with the distribution.

*3. All advertising materials mentioning features or use of this software

*must display the following acknowledgement:

*"This product includes cryptographic software written by

*Eric Young (eay@cryptsoft.com)"

*The word 'cryptographic' can be left out if the routines from the

*library

*being used are not cryptographic related :-).

*4. If you include any Windows specific code (or a derivative thereof)

*from

*the apps directory (application code) you must include an

*acknowledgement:

*"This product includes software written by Tim Hudson

*(tjh@cryptsoft.com)"

*

*THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND

*ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

*IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR

*PURPOSE

*ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE

*FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

*CONSEQUENTIAL

*DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

*OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

*HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,

*STRICT

*LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

*OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

*SUCH DAMAGE.

*

*The licence and distribution terms for any publicly available

*version or

*derivative of this code cannot be changed. i.e. this code cannot

24-9

*simply be

*copied and put under another distribution licence

*[including the GNU Public Licence.]

*/

24-10

Chapter 25 Configuring RTI Secure WAN Transport

The Secure WAN Transport package includes two transports:

❏The WAN Transport is for use on a WAN and includes security.1 It must be used with the WAN Server, a separate application that provides additional services needed for Connext applications to communicate with each other over a WAN.

❏The Secure Transport is an alternate transport that provides security on an untrusted LAN. Use of the RTI WAN Server is not required.

There are two ways in which these transports can be configured:

❏By setting up predefined strings in the Property QoS Policy of the DomainParticipant (on UNIX, Solaris and Windows systems only). This process is described in Setting Up a Transport with the Property QoS (Section 25.2).

❏By instantiating a new transport (Section 25.5) and then registering it with the DomainParticipant, see Section 15.7 (not available in Java API).

Refer to the API Reference HTML documentation for details on these two approaches.

25.1Example Applications

A simple example is available to show how to configure the WAN transport. It includes example settings to enable communication over WAN, and optional settings to enable security (along with example certificate files to use for secure communication). The example is located in <Connext installation directory>/example/<language>/HelloWorldWAN.

As seen in the example, you can configure the properties of either transport by setting the appropriate name/value pairs in the DomainParticipant’s PropertyQoS, as described in Section 25.2. This will cause Connext to dynamically load the WAN or Secure Transport libraries at run time and then implicitly create and register the transport plugin.

Another way to use the WAN or Secure transports is to explicitly create the plugin and use register_transport() to register the transport with Connext (see Section 15.7). This way is not shown in the example. See Explicitly Instantiating a WAN or Secure Transport Plugin (Section 25.5).

1. Security is disabled by default.

25-1

25.2Setting Up a Transport with the Property QoS

The PROPERTY QosPolicy (DDS Extension) (Section 6.5.17) allows you to set up name/value pairs of data and attach them to an entity, such as a DomainParticipant. This will cause Connext to dynamically load the WAN or Secure Transport libraries at run time and then implicitly create and register the transport plugin.

Please refer to Setting Builtin Transport Properties with the PropertyQosPolicy (Section 15.6).

To assign properties, use the add_property() operation:

DDS_ReturnCode_t DDSPropertyQosPolicyHelper::add_property (DDS_PropertyQosPolicy policy,

const char * name, const char * value, DDS_Boolean propagate)

For more information on add_property() and the other operations in the DDSPropertyQosPolicyHelper class, please see Table 6.56, “PropertyQoSPolicyHelper Operations,” on page 6-114, as well as the API Reference HTML documentation.

The ‘name’ part of the name/value pairs is a predefined string, described in WAN Transport Properties (Section 25.3) and Secure Transport Properties (Section 25.4).

Here are the basic steps, taken from the example Hello World application (for details, please see the example application.)

1. Get the default DomainParticipant QoS from the DomainParticipantFactory.

DDSDomainParticipantFactory::get_instance()->get_default_participant_qos(

participant_qos);

2. Disable the builtin transports.

participant_qos.transport_builtin.mask = DDS_TRANSPORTBUILTIN_MASK_NONE;

3. Set up the DomainParticipant’s Property QoS.

a. Load the plugin.

DDSPropertyQosPolicyHelper::add_property (participant_qos.property, "dds.transport.load_plugins", "dds.transport.wan_plugin.wan", DDS_BOOLEAN_FALSE);

b. Specify the transport plugin library.

DDSPropertyQosPolicyHelper::add_property (participant_qos.property, "dds.transport.wan_plugin.wan.library", "libnddstransportwan.so",

DDS_BOOLEAN_FALSE);

c. Specify the transport’s ‘create’ function.

DDSPropertyQosPolicyHelper::add_property (participant_qos.property, "dds.transport.wan_plugin.wan.create_function",

"NDDS_Transport_WAN_create",

DDS_BOOLEAN_FALSE);

d. Specify the WAN Server and instance ID.

DDSPropertyQosPolicyHelper::add_property (participant_qos.property, "dds.transport.wan_plugin.wan.server", "192.168.1.1", DDS_BOOLEAN_FALSE);

DDSPropertyQosPolicyHelper::add_property (participant_qos.property, "dds.transport.wan_plugin.wan.transport_instance_id", 1, DDS_BOOLEAN_FALSE);

25-2

e. Specify any other properties, as needed.

4.Create the DomainParticipant, using the modified QoS.

participant = DDSTheParticipantFactory->create_participant (domainId, participant_qos, NULL /* listener */, DDS_STATUS_MASK_NONE);

Important! Property changes should be made before the transport is loaded: either before the DomainParticipant is enabled, before the first DataWriter/DataReader is created, or before the builtin topic reader is looked up, whichever one happens first.

25.3WAN Transport Properties

Table 25.1 lists the properties that you can set for the WAN Transport.

Table 25.1 Properties for NDDS_Transport_WAN_Property_t

	Property Name
	(prefix with			Property Value Description
	‘dds.transport.WAN.wan1.’)a
		Required Comma-separated strings indicating the prefix names of all
	dds.transport.load_plugins	plugins that will be loaded by Connext. For example:
	(note: this does not take a prefix)	“dds.transport.WAN.wan1". You will use this string as the prefix to the
		property names. See a. Note: You can load up to 8 plugins.
		Required	Must set to "libnddstransportwan.so"						(for	UNIX/Solaris
		systems) or "nddstransportwan.dll" (for Windows system).
	library	This library and the dependent OpenSSL libraries need to be in the path
		during run time for use by Connext (in the LD_LIBRARY_PATH
		environment variable on UNIX/Solaris systems, in Path for Windows
		systems).
	create_function	Required	Must be "NDDS_Transport_WAN_create"
		Used	to	register	the	transport		plugin		returned	by
		NDDS_Transport_WAN_create()					(as		specified		by
	aliases	<WAN_prefix>.create_function) to the DomainParticipant. Aliases should
		be specified as a comma-separated string, with each comma delimiting an
		alias. If it is not specified, the prefixa is used as the default alias for the
		plugin.
		Specifies the verbosity of log messages from the transport.
		Possible values:
	verbosity	-1: silent
		0 (default): errors only
		1: errors and warnings
		2: local status
		5 or higher: all messages
		Number of bits in a 16-byte address that are used by the transport. Should
	parent.parent.address_bit_count	be between 0 and 128. For example, for an address range of 0-255, the
		address_bit_count should be set to 8.
		A bitmap that defines various properties of the transport to the Connext
	parent.parent.properties_bitmap	core. Currently, the only			property		supported is		whether or not		the
		transport plugin will always loan a buffer when Connext tries to receive a
		message using the plugin. This is in support of a zero-copy interface.

25-3

Table 25.1 Properties for NDDS_Transport_WAN_Property_t

	Property Name
	(prefix with			Property Value Description
	‘dds.transport.WAN.wan1.’)a
		Specifies the maximum number of buffers that Connext can pass to the
		send() function of the transport plugin.
		The transport plugin send() API supports a gather-send concept, where
		the send() call can take several discontiguous buffers, assemble and send
		them in a single message. This enables Connext to send a message from
		parts obtained from different sources without first having to copy the parts
		into a single contiguous buffer.
	parent.parent.gather_send_	However, most transports that support a gather-send concept have an
	buffer_count_max	upper limit on the number of buffers that can be gathered and sent. Setting
		this value will prevent Connext from trying to gather too many buffers into
		a send call for the transport plugin.
		Connext requires all transport-plugin implementations to support a gather-
		send of least a minimum number of buffers. This minimum number is
		defined as
		NDDS_TRANSPORT_PROPERTY_GATHER_SEND_BUFFER_COUNT_
		MIN.
		The maximum size of a message in bytes that can be sent or received by
		the transport plugin.
		This value must be set before the transport plugin is registered, so that
	parent.parent.message_size_max	Connext can properly use the plugin.
		If you set this higher than the default, the DomainParticipant’s buffer_size
		(in the RECEIVER_POOL QosPolicy (DDS Extension) (Section 8.5.6))
		should also be changed.
		A list of strings, each identifying a range of interface addresses.
		Interfaces must be specified as comma-separated strings, with each
		comma delimiting an interface.
		If the list is non-empty, this "white" list is applied before the
		parent.parent.deny_interfaces list.
	parent.parent.allow_interfaces	It is up to the transport plugin to interpret the list of strings passed in.
		Usually	this	interpretation	will	be	consistent	with
		NDDS_Transport_String_To_Address_Fcn_cEA().
		This property is not interpreted by the Connext core; it is provided merely
		as a convenient and standardized way to specify the interfaces for the
		benefit of the transport plugin developer and user.
		You must manage the memory of the list. The memory may be freed after
		the DomainParticipant is enabled.
		A list of strings, each identifying a range of interface addresses. If the list is
		non-empty, deny the use of these interfaces.
		Interfaces must be specified as comma-separated strings, with each
		comma delimiting an interface.
		This "black" list is applied after the parent.parent.allow_interfaces list and
		filters out the interfaces that should not be used.
	parent.parent.deny_interfaces	It is up to the transport plugin to interpret the list of strings passed in.
		Usually	this	interpretation	will	be	consistent	with
		NDDS_Transport_String_To_Address_Fcn_cEA().
		This property is not interpreted by the Connext core; it is provided merely
		as a convenient and standardized way to specify the interfaces for the
		benefit of the transport plugin developer and user.
		You must manage the memory of the list. The memory may be freed after
		the DomainParticipant is enabled.

25-4

Table 25.1 Properties for NDDS_Transport_WAN_Property_t

Property Name
(prefix with	Property Value Description

‘dds.transport.WAN.wan1.’)a

Size in bytes of the send buffer of a socket used for sending. On most operating systems, setsockopt() will be called to set the SENDBUF to the value of this parameter.

		This value must be greater than or equal to
	parent.send_socket_buffer_size	parent.parent.message_size_max.
		The maximum value is operating system-dependent.
		If NDDS_TRANSPORT_UDPV4_SOCKET_BUFFER_SIZE_OS_DEFAULT,
		then setsockopt() (or equivalent) will not be called to size the send buffer
		of the socket.
		Size in bytes of the receive buffer of a socket used for receiving.
		On most operating systems, setsockopt() will be called to set the
		RECVBUF to the value of this parameter.
	parent.recv_socket_buffer_size	This	value	must	be	greater	than	or	equal	to
		parent.parent.message_size_max. The maximum value is operating
		system-dependent.
		If NDDS_TRANSPORT_UDPV4_SOCKET_BUFFER_SIZE_OS_DEFAULT,
		then setsockopt() (or equivalent) will not be called to size the receive
		buffer of the socket.
		Allows the transport plugin to use unicast UDP for sending and receiving.
	parent.unicast_enabled	By default, it will be turned on. Also by default, it will use all the allowed
		network interfaces that it finds up and running when the plugin is
		instanced.
		Prevents the transport plugin from using the IP loopback interface. Three
		values are allowed:
		0: Enable local traffic via this plugin. This plugin will only use and report
		the IP loopback interface only if there are no other network interfaces
		(NICs) up on the system.
	parent.ignore_loopback_interface	1: Disable local traffic via this plugin. Do not use the IP loopback interface
		even if no NICs are discovered. This is useful when you want
		applications running on the same node to use a more efficient plugin
		like Shared Memory instead of the IP loopback.
		-1:Automatic. Lets Connext decide among the above two choices. If a
		shared memory transport plugin is available for local traffic, the
		effective value is 1 (i.e., disable UDPv4 local traffic). Otherwise, the
		effective value is 0, i.e., use UDPv4 for local traffic also.
		Prevents the transport plugin from using a network interface that is not
		reported as RUNNING by the operating system.
		The transport checks the flags reported by the operating system for each
		network interface upon initialization. An interface which is not reported as
		UP will not be used. This property allows the same check to be extended to
		the IFF_RUNNING flag implemented by some operating systems. The
	parent.ignore_nonrunning_	RUNNING flag is defined to mean that "all resources are allocated", and
		may be off if there is no link detected, e.g., the network cable is unplugged.
	interfaces
		Two values are allowed:
		0: Do not check the RUNNING flag when enumerating interfaces, just
		make sure the interface is UP.
		1: Check the flag when enumerating interfaces, and ignore those that are
		not reported as RUNNING. This can be used on some operating
		systems to cause the transport to ignore interfaces that are enabled but
		not connected to the network.

25-5

Table 25.1 Properties for NDDS_Transport_WAN_Property_t

	Property Name
	(prefix with	Property Value Description
	‘dds.transport.WAN.wan1.’)a
		Prevents the transport plugin from doing a zero copy.
		By default, this plugin will use the zero copy on OSs that offer it. While
		this is good for performance, it may sometime tax the OS resources in a
		manner that cannot be overcome by the application.
		The best example is if the hardware/device driver lends the buffer to the
	parent.no_zero_copy	application itself. If the application does not return the loaned buffers soon
		enough, the node may error or malfunction. In case you cannot
		reconfigure the H/W, device driver, or the OS to allow the zero copy
		feature to work for your application, you may have no choice but to turn
		off zero copy use.
		By default this is set to 0, so Connext will use the zero-copy API if offered
		by the OS.
		Controls the blocking behavior of send sockets. CHANGING THIS
		FROM THE DEFAULT CAN CAUSE SIGNIFICANT PERFORMANCE
		PROBLEMS.
		Currently two values are defined:
	parent.send_blocking	NDDS_TRANSPORT_UDPV4_BLOCKING_ALWAYS:			Sockets	are
		blocking (default socket options for Operating System).
		NDDS_TRANSPORT_UDPV4_BLOCKING_NEVER: Sockets are modified
		to make them non-blocking. THIS IS NOT A SUPPORTED
		CONFIGURATION	AND MAY	CAUSE	SIGNIFICANT
		PERFORMANCE PROBLEMS.
		Mask for the transport priority field. This is used in conjunction with
		transport_priority_mapping_low/high to define the mapping from DDS
		transport priority to the IPv4 TOS field. Defines a contiguous region of bits
		in the 32-bit transport priority value that is used to generate values for the
	parent.transport_priority_mask	IPv4 TOS field on an outgoing socket.
		For example, the value 0x0000ff00 causes bits 9-16 (8 bits) to be used in the
		mapping. The value will be scaled from the mask range (0x0000 - 0xff00 in
		this case) to the range specified by low and high.
		If the mask is set to zero, then the transport will not set IPv4 TOS for send
		sockets.
	parent.transport_priority_	Sets the low and high values of the output range to IPv4 TOS.
	mapping_low	These values are used in conjunction with transport_priority_mask to
	parent.transport_priority_	define the mapping from DDS transport priority to the IPv4 TOS field.
		Defines the low and high values of the output range for scaling.
	mapping_high
		Note that IPv4 TOS is generally an 8-bit value.
	enable_security	Required if you want to use security.
	recv_decode_buffer_size	Size of buffer for decoding packets from wire. An extra buffer is required
		for storage of encrypted data.
	port_offset	Port offset to allow coexistence with non-secure UDP transport.
	dtls_handshake_resend_interval	DTLS handshake retransmission interval in milliseconds
		A string that specifies the name of file containing Certificate Authority
		certificates. File should be in PEM format. See the OpenSSL manual page
	tls.verify.ca_file	for SSL_load_verify_locations for more information.
		If you want to use security, ca_file or ca_path must be specified; both may
		be specified.

25-6

Table 25.1 Properties for NDDS_Transport_WAN_Property_t

	Property Name
	(prefix with		Property Value Description
	‘dds.transport.WAN.wan1.’)a
		A string that specifies paths to directories containing Certificate Authority
		certificates. Files should be in PEM format, and follow the OpenSSL-
	tls.verify.ca_path	required naming	conventions.	See the	OpenSSL manual	page for
		SSL_CTX_load_verify_locations for more information.
		If you want to use security, ca_file or ca_path must be specified; both may
		be specified.
	tls.verify.verify_depth	Maximum certificate chain length for verification.
		If non-zero, use mutual authentication when performing TLS hand- shake
	tls.verify.verify_peer	(default). If zero, only the reader side will present a certificate, which will
		be verified by the writer side.
		This can be set to one of three values:
		"default"	selects	the	default	callback
	tls.verify.verify_callback	NDDS_Transport_TLS_default_verify_callback()
		verbose"	selects	the	verbose	callback
		NDDS_Transport_TLS_verbose_verify_callback()
		"none" requests no callback be registered
	tls.cipher.cipher_list	List of available	(D)TLS ciphers. See the		OpenSSL manual	page for
		SSL_set_cipher_list for more information on the format of this string.
		List of available Diffie-Hellman (DH) key files. For example:
		"foo.h:512,bar.h:256" means:
	tls.cipher.dh_param_files	dh_param_files[0].file = foo.pem,
		dh_param_files[0].bits = 512,
		dh_param_files[1].file = bar.pem,
		dh_param_files[1].bits = 256
	tls.cipher.engine_id	String ID of OpenSSL cipher engine to request.
		Required if you want to use security. A string that specifies the name of a
		file containing an identifying certificate chain (in PEM format). An
	tls.identity.certificate_chain_file	identifying certificate is required for secure communication. The file must
		be sorted starting with the certificate to the highest level (root CA). If no
		private key is specified, this file will be used to load a non-RSA private
		key.
	tls.identity.private_key_password	A string that specifies the password for private key.
		A string that specifies that name of a file containing private key (in PEM
	tls.identity.private_key_file	format). If no private key is specified (all values are NULL), this value will
		default to the same file as the specified certificate chain file.
	tls.identity.rsa_private_key_file	A string that specifies that name of a file containing an RSA private key (in
		PEM format).
		Required A set of comma-separated values to specify the elements of the
	transport_instance_id[0] to	array. This value must be unique for all transport instances
	[NDDS_TRANSPORT_	communicating with the same WAN Rendezvous Server.
	WAN_TRANSPORT_	If less than the full array is specified, it will be right-aligned. For example,
	INSTANCE_ID_LENGTH]	the string "01,02" results in the array being set to:
		{0,0,0,0,0,0,0,0,0,0,1,2}
	interface_address	Locator, as a string
	server	Required Server locator, as a string.
	server_port	Server port number.
	stun_retransmission_interval	STUN request messages requiring a response are resent with this interval.
		The interval is doubled after each retransmission. Specified in msec.