Open Communication Interface for Road Traffic Control Systems Offene Schnittstellen fr die Straenverkehrstechnik

OCIT-C Center to Center Transportation Protocol

OCIT-C_Protocol_V1_R1

OCIT Developer Group (ODG)&Partner

OCIT Registered trade mark of Dambach, Siemens, Signalbau Huber, Stoye, Sthrenberg

OCIT-C Center to Center Transportation Protocol

Document: OCIT-C_Protocol_V1_R1 Author: OCIT Developer Group (ODG) & Partner (Schlothauer&Wauer, PTV) www.ocit.org
Copyright 2010 ODG & Partner. All rights reserved. Documents with versions or issue conditions with newer date replace all contents of preceding versions.

OCIT-C_Protocol_V1_R1

Page 2 of 38

Contents
1 Introduction .....................................................................................................................5 1.1 History of Change .....................................................................................................5 1.2 Definitions.................................................................................................................5 1.3 Abbrevations .............................................................................................................5 2 Transfer Protocol Soap ....................................................................................................6 2.1 Technology ...............................................................................................................6 2.2 Protocol Requirements ..............................................................................................6 2.3 Concept and Security ................................................................................................6 2.4 Protocol functions .....................................................................................................7 2.4.1 2.4.2 Reading data by a Client ..............................................................................7 Send data to server ......................................................................................9

Page

2.5 Sequence Control ....................................................................................................10 2.5.1 2.5.2 2.5.3 2.5.4 2.5.5 2.5.6 2.5.7 2.5.7.1 Data Buffering and position handling .........................................................11 Too long transaction time ..........................................................................11 Too long inquiriesl.....................................................................................12 Handle historical data access ......................................................................13 Multi client capability.................................................................................13 Resynchronisation......................................................................................14 Bidirectional communication......................................................................16 Bidirectional communication sequences with Client&Server pair ................16

2.5.7.1.1 Switching a sign (sequences) ................................................................16 2.5.7.2 Bidirectional communication sequences polling current state ......................20

2.5.7.2.1 Switching a sign (sequence) ..................................................................20 2.6 OSI Layering........................................................................................................21 2.7 Protocol Functions in Detail ....................................................................................22 2.7.1 getContentInfo ..........................................................................................24
Page 3 of 38

OCIT-C_Protocol_V1_R1

2.7.2 2.7.3 2.7.4 2.7.5 2.7.6 3 4

get .............................................................................................................24 inquireAll...................................................................................................27 put .............................................................................................................29 delete.........................................................................................................30 Parameters.................................................................................................31

Data structures...............................................................................................................32 How to Use .............................................................. Fehler! Textmarke nicht definiert. 4.1 Data delivery interface / one or more Consumer ......................................................32 4.2 Configuration Interface ...........................................................................................33 4.3 Interface between Central Units to update its data (unidirectional) ...........................34 4.4 Interface between Central Units to update its data (bidirectional) .............................35

OCIT-C_Protocol_V1_R1

Page 4 of 38

Introduction

The communication between Central Units and communication interfaces to these Central Units should be implemented unique in all Central Units. As an approach the communication interface Soap can be used. The Soap protocol is the common communication interface over them all communications are done. This communication interface is called OCIT-C. These interfaces are declared to be open. Therefore they can be used by external systems. The task of this document is to describe this open protocol and its usage. It is not the task of this document to describe data structures of the particular data.

1. 1

History of Change

Version State

Date

Recipients

Name

Change

V1.0 E01 03.03.2010

ODG&Partner DKE 713.3.4

M. Senninger

Draft

V1.0 A01 02.06.2010 V1 R1 02.09.2010

PUBLIC PUBLIC

M. Senninger M.Senninger

Preliminary version First version

1. 2

Definitions

Statement
SOAP Protocolmanager SoapServerInterface SoapClientInterface

Definition
Simple Object Access Protocol. Transfers commands with the means of XML by using httpIt is described within http://www.w3.org/TR/SOAP. Protocollayer which implements commands and the buffer. Includes Soap and ProtocolManager at the server site Includes Soap and ProtocolManager at the client site

1. 3

Abbrevations

Abbrevation
SSL

Description
Secure Socket Layer.

OCIT-C_Protocol_V1_R1

Page 5 of 38

Transfer Protocol Soap

This chapter describes the Soap interface.

2. 1

Technology

Data is encoded with XML. This includes the following advantages: usable protocol for all components (no dependency on used data) tracable plattform independency. easy expandable.

The protocol includes easy commands like write, get or delete. FTP is not sufficient. As transfer media SOAP on the base of http is used

Soap itself uses XML to build its data.

2. 2

Protocol Requirements

data are represented as XML data at the output interface. data are accepted as XML at the input interface (configuration) commands are embedded within XML. (e.g. post,get) objects are identified by external identifiers. one cannot mix different object types within one request protocol is stateless within the server. This means that the server does not know anything about the client.

2. 3

Concept and Security

Security will be implemented by using username and password in plain text. Three classes of unintended foreign accesses:

The protocol is a client server protocol.

The aggressor uses the transmission link to intrude into the computer (client or server), for example to steal or modify data. This scenario is the most frequent (and the most severe in terms of the consequences). To put a stop to this under TCP/IP, it is necessary for only one
OCIT-C_Protocol_V1_R1 Page 6 of 38

port at most to be enabled towards the outside and for this port not to be a default port. In the protocol described above (with http as the underlying layer), a firewall for the client can be made so restrictive that no connections can be opened towards the clients and only one specific port is opened out to the control centre. The best possible protection for the client is provided with a suitably configured firewall. In this case, SOAP is not configured to port 80, but to a project-specific port number. The control centre can also be fairly reliably protected by i) not installing SOAP to port 80 in the specific project and ii) by implementing SOAP via its own classes and not via the IIS. The aggressor attempts to gain access to SOAP to execute OCIT commands there as an OCIT client. (This scenario does not call for a particularly trained aggressor.) In this scenario, the aggressor does not even attempt to reach default ports and is not even able to steal data or to manipulate files. Such an attack is also only suitable for the server (and not for the client). Such an attack is relatively simple, but is made practically impossible by the user name and the password, provided the attacker is not aware of a valid pair. The (professional) aggressor intercepts a TCP connection and determines a user name and password (professionals only). This scenario does not permit any theft either and also no file manipulation, but does allow the aggressor to pretend to be an OCIT client without knowing a password and user name. You have to do a cost/benefit calculation here. As it is not quite easy, except for specialists, to intercept and read a TCP connection, the data really ought to be interesting enough to make such a break-in worthwhile. To circumvent this, an HTTPS connection can be used with moderate effort instead of an http connection (this entails additional programming effort because SSL libraries have to be incorporated) and, when using Verisign, for example, a public key has to be requested for the control centre and has to be paid for, unless communication partners agree on a self-generating key and enter it manually. In such a case, it is practically no longer possible to intercept and read a connection between the client and the control centre. In my opinion, though, such a changeover is not worth the effort. The server saves a list of user names and their associated passwords. The server also stores details of which operations are permitted by which user. Access from more than one client is possible with the same name, with the result that not all clients have to be made known in the server.

2. 4

Protocol functions

With the protocol you are able to read and configure data. Besides it is possible evaluate objects and instances concerning availability and structure dynamicly during runtime. Every command consists of a request and a response. Executing a request a XML structure is transfered from Client to the Server, The result of the call is put into a Result (also called a response structure) and sent back to the client.

2.4.1

Reading data by a Client

All protocol functions to read data include a filter as parameter. This filter is a field of objects which are to be read. In case the filter is empty all objects will be returned in any other case only those objects included in the filter list.
OCIT-C_Protocol_V1_R1 Page 7 of 38

In order to ease the resynchronisation a last start information is added to each response of a read access With this information the client is able to decide when to resynchronise (in case of changed start string). The server offers all readable data at its outer interface. The server offers data of several object types. The Client is able to query all available object types with the command getContentInfo. Those objecttypes which are contained in the answere can be read by the Client (if the client has read access to it). either by the protocol function get or inquireAll The difference between inquireAll and get is as follows: .InquireAll delivers all objects of the requested object type with the last state/contents of the objects. It has to be used in any case of resynchronisation (e.g. restart of the server or the client). The function get delivers changes since last time having requested the server. This mechanism is described in detail within chapter 2.5.1 Data Buffering and position handling.
The following sequences shows how data is requested from server periodicly with the help of the protocol functions inquireAll (resynchronisation function) and get (function to read deltas since last having requested).

OCIT-C_Protocol_V1_R1

Page 8 of 38

SoapClient-I

SoapServer-I
Data

DataBase

inquireAll
Data

Now the client knows all objects of the requested object type

inquireAllResponse get

Data

Data

getResponse
Now the client knows all changes since last request

get getResponse

Data

Data

get SoapClient-I SoapServer-I

Data

DataBase

Figure 1: Usual Sequence to Read Data From SoapserverInterface

2.4.2

Send data to server

It is possible to send data to the server. The protocol function put is to be used for this purpose. The behaviour of the Server depends on the object type, In case of unknown objects in the put command, either the object will be created or an error will be returned. To delete objects the command delete is required

The configuration interface is rather simple using the command put. The configuration data can be placed into it and is to be sent towards the server. The server accepts it or rejects all unconfigurable objects in the putResult-list.

OCIT-C_Protocol_V1_R1

Page 9 of 38

SoapClient-I put

SoapServer-I

DataBase

Data
Now the client knows about successfull configured objects and errors

putResponse put
Data

putResponse
Now the client knows about successfull configured objects and errors

SoapClient-I

SoapServer-I

DataBase

Figure 2: Usual Sequence to Write/Configure Data to the SoapserverInterface

2. 5

Sequence Control

The protocol is connection less. To achieve sequence control it is sufficient to wait for the response of the according request. This is achieved by http. So no additional sequence control is required. Nevertheless some special hints should be obeyed. Those sequences are described in the following chapters.

OCIT-C_Protocol_V1_R1

Page 10 of 38

2.5.1

Data Buffering and position handling

Figure 3: Data buffering at server side and position handling at client side

The server buffer provides data in a data buffer. The buffer is a short term buffer. This buffer should be organised as a ring buffer supplying client requests from its data base. After executing an inquireAll the client knows the last state from the data base. Besides the inquireAll-Response the client receives the last position number, indicating the last information from server (pointer to last received data in the data buffer). With the help of this position number the client issues the next server request (get). With the help of the position number, the server knows which date has to be provided to obtain all changes, occurred since last clients request. The get response includes the data and a new position number, which is to be used for the next get request of the client.

2.5.2

Too long transaction time

Usually the response carries the requested data. In case the server requires longer than acceptabable (rec. > 60s), an empty response will be returned to the client. The exceeded transaction time will be indicated by an own error code. However the server continues to obtain the data from its data base (or archive).
OCIT-C_Protocol_V1_R1 Page 11 of 38

The client will repeat its request after a certain time. After this time the server is able to supply the data (because organised in background). If not the server indicates the too long transaction time again.

SoapClient-I inquireAll

SoapServer-I

DataBase

data access

inquireAllResponse (error=too long time)

data access requires time

SoapClient-I

Figure 4: Handle long transaction time (similar sequence for get requests)

2.5.3

The server returns an error code, in case the contents of a response exceeds a threshold. This may happen, in case Too many historical data is requested (time range too big) Too many deltas since last requested Too many objects requested

The client has to reduce its request accordingly.

OCIT-C_Protocol_V1_R1

waiting time

data access returns data

inquireAll inquireAllResponse (data, pos. number) SoapServer-I DataBase

Too long inquiriesl

Page 12 of 38

2.5.4

Handle historical data access

The command get is used, in case access to historical data is required. The element storetime is used to define the start in the historical store. The element endstore is used to define the end in the historical storage.

The get-response will contain date from storetime to endStore in consequence.

It is recommended to Keep time ranges as small as possible (chapter 2.5.3 Too long inquiriesl) React on possible to long reaction time (chapter 2.5.3 Too long inquiriesl) Use object filters (limit amount of objects)

2.5.5

Multi client capability

The server works sessionless. The position number avoids building up any knowledge about the client at the server side.

Implementing OCIT-C, just obey that the used lower layer libraries should allow multiple client access.

OCIT-C_Protocol_V1_R1

Page 13 of 38

2.5.6

Resynchronisation

There might be different reasons for resynchronisation: Client restart client knows about his start client has to resynchronise data with inquireAll server possibly recognises client restart with the help of the watch dog (watchdog is optional !)

OCIT-C_Protocol_V1_R1

Page 14 of 38

Server restart client possibly recognises unavailable server (socket timeout) or server responds any protocol function (inquireAll, get or put) including lastStart, which indicates the time whe server started last time the client has to resynchronise with inquireAll in case this lastStart differs from previously responded lastStart

SoapClient-I get get-Response get

Client recognises server restart with socket error

SoapServer-I

Serverrestart

get get-Response
The client recognises server restart with modified lastStat in get response

Soap::inquireAll inquireAll-Response get get-Response get get-Response

SoapClient-I

SoapServer-I

OCIT-C_Protocol_V1_R1

Page 15 of 38

2.5.7

Bidirectional communication

The following use cases require communication in both directions: Intersection control: - switch command is transferred from central 1 to central 2 - current state (not the requested command !) is send in the other direction and asynchronously from central 2 to central 1

CCTV - PTZ (pan/til/zoom) command is transferred from central 1 to central 2 - current state (not the requested command !) is send in the other direction and asynchronously from central 2 to central 1

Sign control - sign switch command is transferred from central 1 to central 2 - current state and content (not the requested content !) is send in the other direction and asynchronously from central 2 to central 1

The following chapters describe possible approaches. Sign control is used as an example. Bidirectional communication for other use cases work in a similar way. 2.5.7.1 2.5.7.1.1 Bidirectional communication sequences with Client&Server pair Switching a sign (sequences)

The following transmission is used for signs. 2.5.7.1.1.1 Switching a sign (good case)

The following image describes the sequence to issue put commands (good case):

OCIT-C_Protocol_V1_R1

Page 16 of 38

central system SoapServer-I SoapClient-I

sign SoapServer-I SoapClient-I

switch command to the interface

put (Sign Switch Command) Soap::putResult

forward switch to application

c s S e r v e r change state A to o.k. p p l

put (Sign Switch State-o.k./content information) Soap::putResult

S i g n S e r change state v to e o.k.(successful r switch command) A p p l

SoapServer-I

SoapClient-I

SoapServer-I

SoapServer-I

OCIT-C_Protocol_V1_R1

Page 17 of 38

2.5.7.1.1.2

Switching a sign (error case)

The following image describes the sequence to issue put commands (error case):
central system SoapServer-I
switch command to the interface

sign SoapServer-I SoapClient-I

forward switch to application change state to n.o.k( not accepted switch command)

SoapClient-I

put (Sign Switch Command) Soap::putResult

c s change state put n.o.k. S e r switch command to the v interface again (repeat after e delay max. 3 times) r A p p l

(Sign Switch State-n.o.k.) Soap::putResult put (Sign Switch Command) Soap::putResult

Sequence continues depending on the following answeres of the sign server.

forward switch to application

S i g n S e r v e r A p p l

SoapServer-I

SoapClient-I

SoapServer-I

SoapServer-I

In case of a not received answer the switch commands are repeated after a (configurable) delay.

The same applies for failures on the LAN (no response from SignServer) or not finally confirmed sign switches, wherever the error occurs (no state transition to state busy or no state transition to state o.k.). The repeating will be stopped after three tries, which have been not successful. Then the sign state at the central system side changes to n.o.k.

OCIT-C_Protocol_V1_R1

Page 18 of 38

2.5.7.1.1.3

Sign states/content transmission/Connection Supervision

The following image describes the sequence to exchange state and contents information:
central system SoapServer-I SoapClient-I sign SoapServer-I SoapClient-I
change state to n.o.k(any errer detcted on sign)

change state n.o.k.

put (Sign Switch State-n.o.k.) Soap::putResult put (Sign Switch State-o.k.) Soap::putResult
The signserver updates the central system periodicly. (Lifecycle telegramm). In case of non reachable serverTMS the sign falls back to default.

c s S change state o.k. e r v e r A p p l

change state o.k.

change state to o.k(sign becomes o.k.)

put (Sign Switch State-o.k.) Soap::putResult

change state to o.k(sign becomes o.k.)

S i g n S e r v e r A p p l

SoapServer-I

SoapClient-I

SoapServer-I

SoapServer-I

The sign server updates the central system periodicly, although the state does not changed. Therefore central system gets notice - in case a sign connected to the signserver changes its state - in case a sign changes its contents (e.g. local control) - in case the sign server is unreachable (detected time out at the central system side)

Therefore the Sign Server gets notice - in case central system is unreachable. Under this circumstance the SignServer switches all signs to default text.

OCIT-C_Protocol_V1_R1

Page 19 of 38

2.5.7.2 2.5.7.2.1

Bidirectional communication sequences polling current state Switching a sign (sequence)

central system SoapClient-I

sign SoapServer-I

switch command to the interface

put (Sign Switch Command) Soap::putResult get (Sign Switch State) get-response

forward switch to application

c s S e r v e r A p p l

change state to o.k.(successful switch command)

get (Sign Switch State)

change state to o.k.

get-response get (Sign Switch State) get-response

S i g n S e r v e r A p p l

SoapClient-I

SoapServer-I

OCIT-C_Protocol_V1_R1

Page 20 of 38

central system SoapClient-I

sign SoapServer-I

switch command to the interface

put (Sign Switch Command) Soap::putResult get (Sign Switch State) get-response

forward switch to application

c s S e r v e r A p p l

change state to o.k.(successful switch command)

get (Sign Switch State)

change state to o.k.

get-response get (Sign Switch State) get-response

S i g n S e r v e r A p p l

SoapClient-I

SoapServer-I

2. 6

OSI Layering

The server is divided into different parts. First we have the Soap functionality which is covered by the Soap component. In addition to the Soap a protocol manager is used, whose task it is to implement all commands including the required data buffer for server functionality. Finally a data access layer is required to link from XML to the used database (e.g. Object Manager). The following image describes this in a layer modelling.

OCIT-C_Protocol_V1_R1

Page 21 of 38

Data/ Application PM-Client Soap-Client http

Data/ Application ProtokollManager WebServer (Soap) http

Figure 5: Layers

The client covers similar layers.

2. 7

Protocol Functions in Detail

Available protocol functions getContentInfo get inquireAll, put delete.

OCIT-C_Protocol_V1_R1

Page 22 of 38

element Protokoll

Figure 6: Available Commands

OCIT-C_Protocol_V1_R1

Page 23 of 38

2.7.1

getContentInfo

getContentInfo has no parameters, besides name of the client and the password and optional the watchdog.

As response you receive a list of all available object types including access rights and recommended update cycle to them.

2.7.2

ge t

get has besides the standard parameters either start and endtime to get all values within this time range or it includes the position number from where the request is related to. Usualy the

OCIT-C_Protocol_V1_R1

Page 24 of 38

position number is the positionnumber returned by the latest inquireAllResponse or getResponse.

So the inquiry returns all values since last request. This is the recommended way how to use this interface.

OCIT-C_Protocol_V1_R1

Page 25 of 38

OCIT-C_Protocol_V1_R1

Page 26 of 38

2.7.3

inquireAll

Inquire all includes only standard parameters.

OCIT-C_Protocol_V1_R1

Page 27 of 38

As response all topical values will be returned.

OCIT-C_Protocol_V1_R1

Page 28 of 38

2.7.4

put

put includes all data instances which should be configured.

As response you get unconfigurable data instances (usually none).

OCIT-C_Protocol_V1_R1

Page 29 of 38

2.7.5

delete

delete removes data ion case this is possible, Data instances to delete have to be added to the filterList.

As response you get the data instances, which could not be deleted.

OCIT-C_Protocol_V1_R1

Page 30 of 38

2.7.6

Parameters

There are standard parameters mentioned above and defined here: Inputparameter UserName and and UserPasswd authentifies the user UserName and and UserPasswd are transferred in plain text. Authentification should not be used for security purposes in consequence. Watchdog is a structure with which the client tells the server when the server can expect the next call of the client. Watchdog time can be used for timeout supervision of the client at the server side. storeTime indicates the start of the requested (or responded) data It is only used for historical data access. end_store indicates the end of the requested (or responded) data. It is only used for historical data access. position indicates a pointer in the servers buffer. The position is responded in an inquireAll- or get-Response and used for the next get request to incicate the next read position in the servers data buffer ( refer to chapter 2.5.1 Data Buffering and position handling) filterlist List of objects, which are to be read With the help of the filter list the amount of read data can be restricted (to those mentioned in the filter list)

Outputparameter LastStart is the date/time stamp of the last server start. In case of a change of lastStart (from one server response to next server response) the client has to resynchronise by using the command inquireAll. Changed Last start has to be used as an indicator for resynchronisation of data. Errorcode is an error code, in case of an error executing a command. In case of wrong XML-Structures errorcode will not be used, SOAP-Fault will be returned instead. Errortxt is a human readable description of the error code. position Position of last data accessed. Is to be used for following get access. Datalist returned data container
Page 31 of 38

OCIT-C_Protocol_V1_R1

Data structures

Data structures embedded in the protocol (e.g. the mentioned commands put, inquireAllResponse ) are defined in own scheme definitions. They are not scope of this document (...).

How to use

This chapter describes how to use server and client depending on different use cases. This can be only a recommendation. The real architecture has to be decided on each certain case.

4. 1

Data delivery interface / one or more Consumer

In case there are several consumers requiring data from time to time and not under real time requirements the following architecture is recommended. The data source includes the SoapServerInterface, which implements functionality like data buffering. The data consumers include the SoapClientInterface, which implement the access to the soap server in case the data is required (commands inquire and get).

This includes the following advantages: - reduces costs because the client can access the server on demand - improves the acceptance of the protocol because the SoapClientInterface is easier to implement - there is no need that the data source knows anything about the consumers. - only one communication interface at the data source In any case of internet providing the data source has to be server and the internet service is client.

OCIT-C_Protocol_V1_R1

Page 32 of 38

Data

further use of data

SoapServerInterface

SoapClientInterface Data Sink Data Sink

Data Source

4. 2

Configuration Interface

In case a system (data source) requires a configuration interface at the data sink, the following architecture is recommended: The data source is client The data sink is server

This includes the following advantages: transmission on demand realtime configuration (no polling required) more than one configuration interface at one Data Sink with the same communication interface

OCIT-C_Protocol_V1_R1

Page 33 of 38

Data Data

further use of data

SoapClientSoapClientInterface Interface Data Source Data Source

SoapServerInterface Data Sink

This interface is used in the following applications: in case a subsystem likes to get rid of measured data like roadwork management systems or subsystems with a kind of data forwarding interface, then it uses the client as a simple way to forward data to the data sink. It should only be used for a view object types to avoid overload situations.

4. 3

Interface between Central Units to update its data (unidirectional)

In case of data exchange between Central units the following interface is recommended. Data source is Server Data sink is client

OCIT-C_Protocol_V1_R1

Page 34 of 38

Data

further use of data

SoapServerInterface CentralUnit as Data Source

SoapClientInterface Central Unit(s) as Consumer

In fact we have the same configuration as mentioned within chapter Data delivery interface / one or more Consumer.

4. 4

Interface between Central Units to update its data (bidirectional)

In case an interface in two directions is required it is clear to implement the interface twice, because the Central unit is server and client at the same time.

OCIT-C_Protocol_V1_R1

Page 35 of 38

Data

Data

SoapSoapServer Client-Interface Interface

SoapSoapServer Client-Interface Interface

CentralUnit 1

CentralUnit2

OCIT-C_Protocol_V1_R1

Page 36 of 38

OCIT-C_Protocol_V1_R1

Page 37 of 38

OCIT-C_Protocol_V1_R1 Copyright 2010 ODG & Partner