Heeft u vragen? U kunt ons ook bellen op tel: 0318-695315

iVRI specificaties
Deze tekst is gepubliceerd op 18-04-22

22 C-ITS-SUBJECT-SYSTEM

Datum besluit SC 09-09-2021
D3047-22 / Version 1.0.0
Disclaimer (NL):
Bij het gebruik en toepassen van de Landelijke iVRI standaarden is en blijft de gebruiker, te weten de wegbeheerder respectievelijk opdrachtnemer van de wegbeheerder, zelf aansprakelijk voor de mogelijke risicos die ontstaan of kunnen ontstaan uit het aanbieden of laten aanbieden van (combinaties van) diensten en producten die conform deze standaarden werken in de eigen organisatie of elders in de keten waarvoor de wegbeheerder verantwoordelijk is. Dit geldt in het bijzonder ten aanzien van het verzamelen, opslaan en delen van gegevens en meer specifiek indien daar waar al dan niet direct of indirect herleidbare persoonsgegevens worden verwerkt op grond van de AVG. Gebruikers zijn zelf verantwoordelijk om bij het gebruik van de standaarden telkens na te gaan of gebruik van standaarden, dan wel de combinatie van data vanuit de standaarden in de basis voldoet aan de wet- en regelgeving, in het bijzonder de AVG. Het gebruik conform de standaarden kan het risico op aansprakelijkheid van de wegbeheerder verkleinen, maar niet altijd wegnemen of geheel uitsluiten. Dit is mede afhankelijk van de wijze waarop de wegbeheerder zelf in haar eigen organisatie of bij gebruik van opdrachtnemers in de keten de data verwerkt en gebruikt. Het is dan ook een dringend advies zowel voorafgaand aan de implementatie en ingebruikname door de gebruiker van de standaarden als periodiek een risico-analyse (zoals Data Protection Impact Assessment (DPIA)) en controle van de keten op het gebruik van de standaarden en bijkomende individuele risico s bij de wegbeheerder en haar opdrachtnemers uit te laten voeren. Het doel van dergelijke analyses en controles is dat mogelijke risico s die onbedoeld kunnen optreden op voorhand gedentificeerd kunnen worden, zodat de wegbeheerder zelf de nodige beheersmaatregelen kan treffen om (alsnog) aan de wettelijke voorschriften te kunnen voldoen. CROW en de opstellers van de standaarden hebben deze documenten met de grootst mogelijke zorg en met aandacht opgesteld, maar kunnen geen aansprakelijkheid aanvaarden voor een mogelijke overtreding van wet- en regelgeving door de wegbeheerder respectievelijk opdrachtnemer van de wegbeheerder, door te verwijzen naar de standaarden als oorzaak van een mogelijke overtreding van de AVG of andere wettelijke voorschriften. CROW en de opstellers van de standaarden wijzen derhalve een aansprakelijkheid door gebruikers ten aanzien van het gebruik van de standaarden Landelijke iVRI standaarden van de hand.
Disclaimer (EN):
When using and applying the Landelijke iVRI standaarden the end user, being the road authority or its principal, remains solely responsible for the possible risks that emerge or can emerge from the provision of services and products that operate by these standards, either within the own organisation or elsewhere in the chain of the road authoritys responsibility. This especially applies to the activities where data is gathered, stored and shared, and more specifically in cases where, be it directly or by inference, private data of individuals are processed, based on the GDPR and/or its national implementation. The user of these standards are themselves responsible for ascertaining that either the use of these standards, or the combination of data that is processed from applying these standards, are legal, especially in terms of the GDPR and/or its national implementation. The use of these standards can reduce the risks for liability of road users, but they can not eliminate these risks; the beforementioned risks of violating privacy legislation are mainly dependent on the way in wicht the road authority uses and processes the data within the own organisation and in relation to contractors within the chain of responsibility. It is urgently advised that, not alone when preparing a project, but also when implementing and operating a service or product, the road authority performs a periodic risk analysis (like a Data Protection Impact Assessment (DPIA)) and a check on the whole chain of information in terms of compliance to standards and additional individual risks on behalf of the road authority and its contractors. The purpose of these analyses and checks is to identify the possible risks beforehand, in order to take preventive and controlling measures, so that the road authority (eventually) is compliant to the legal framework that is applicable. CROW and the authors of these standards have created this document with the utmost care, but will not accept liability for a possible violation of any legislation by the road authority or its contractors by referring to these standards as the root cause of a possible violation of the GDPR, its national implementation or any other legal prescription. CROW and the authors of the Landelijke iVRI standaarden therefore explicitly waive all responsibility for the use of these standards.
Referenced documents
ID
Reference
Version
Date
[1]
C-ITS-SUBJECT-ADMIN
1.0.0
23 Mar 2020

1 – Introduction
1.1 – Overview
2 – API
2.1 – Authentication and authorization
2.2 – API endpoints
2.2.1 – Sessions
3 – TCPStreaming protocol
3.1 – Transport Layer Security
3.2 – Protocol version establishment
3.3 – Protocol version 0x01
3.3.1 – Byte Order
3.3.2 – Datagram framing
3.3.3 – Communication modes
3.3.4 – Datagrams
1 Introduction
This document describes the technical interface with UDAP for TLC systems. The primary goal of this document is to track/version the interface specification for this explicit context so that the impact of future UDAP specification changes can be properly assessed.
1.1 Overview
TLC systems interface with UDAP on two levels:
  1. JSON-REST API; used for:
    1. requesting/creating TCPStreaming sessions;
    2. updating TCPStreaming sessions.
  2. TCPStreaming protocol: TCP protocol used for sending and receiving payloads to and from UDAP.
2 API
2.1 Authentication and authorization
The authentication of the Client will be based on a "authorization token". This "authorization token" needs to be passed as the "X-Authorization" request header value. The authorization token needs to belong to an "TLC_SYSTEM" authorization (for more details the "authorization model" chapter in the UDAP TLC - Part 3 of this document [1]).
2.2 API endpoints
End point
Method
URI
Description
sessions
POST
/sessions
Creates a new streaming session
sessions
PUT
/sessions/<token>
Updates one active streaming session
2.2.1 Sessions
2.2.1.1 POST /sessions
Creates a new streaming session.
Request
POST <API base URL>/sessions HTTP/1.1
Host: <hostname>
X-Authorization: <authorization token>
Content-Type: application/json
{
"domain": "<domain>",
"type": "<type>",
"protocol": "<protocol>",
"details": {
<protocol details>
}
}
Name
Description
domain
Sessions are created within a specific domain, identified by a single string
Only sessions created for the same domain will be able to stream data to each other
type
The session type; must be TLC
protocol
The session protocol; must be one of the predefined types:
  • TCPStreaming_Singleplex
  • TCPStreaming_Multiplex
  • VLOG
details
Session protocol specific details for creating the session
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"token": "<token>",
"domain": "<domain>",
"type": "<type>",
"protocol": "<protocol>",
"details": {
<protocol details>
}
}
Name
Description
token
The token for the created session
This token is unique and can only be used once for establishing a TCP connection; if the session expires or ends (TCP disconnect) a new session needs be created to obtain a new token
domain
See request
type
See request
protocol
See request
details
Session protocol specific details of the created session
Session type "TLC" with protocol "TCPStreaming_Singleplex"
TCP based singleplex streaming session for one specific TLC.
Payloads sent by the Client will be received by Broker" session Clients if the "TLC identifier" of this specific TLC is within their scope.
Payloads sent by "Broker" session clients having a payload "TLC identifier" that matches this specific TLC's identifier will be received.
Request details
{
"securityMode": "<security mode>",
"tlcIdentifier": "<TLC identifier>"
}
Name
Description
securityMode
Security mode of the streaming session
Must be one of the predefined values:
1. NONE
2. TLSv1.2
tlcIdentifier
The TLC identifier for the session
Since the session is for one specific TLC, payload data will be streamed without TLC identifier (see protocol datagram 0x04)
Response details
{
"securityMode": "<security mode>",
"tlcIdentifier": "<TLC identifier>",
"listener": {
"host": "<host address>",
"port": <port number>,
"expiration": "<ISO 8601 date time>"
},
"keepAliveTimeout": "<ISO 8601 duration>",
"clockDiffLimit": "<ISO 8601 duration>",
"clockDiffLimitDuration": "<ISO 8601 duration>",
"payloadRateLimit": <payload/second limit>,
"payloadRateLimitDuration": "<ISO 8601 duration>",
"payloadThroughputLimit": <KB/second limit>,
"payloadThroughputLimitDuration": "<ISO 8601 duration>"
}
Name
Description
securityMode
See request details
tlcIdentifier
See request details
listener
The Streaming Service Node listener details for establishing the TCP connection
listener.host
The host address of the Streaming Service Node
listener.port
The TCP port of the Streaming Service Node's session listener
listener.expiration
The expiration date time of the listener in ISO 8601 date time format
If the TCP connection has not been established before this time the listener will expire and the streaming session will no longer be available
The default listener expiration will be 5 seconds after creation
keepAliveTimeout
The keep alive timeout duration of the TCP connection in ISO 8601 duration format
If no TCP data is received during the specified duration, the TCP connection will be terminated by the Streaming Service
If a Client receives no TCP data during the specified duration, it must terminate the TCP connection
clockDiffLimit
The maximum clock difference, in ISO 8601 duration format, allowed for the streaming session
If the average clock difference during the duration (see clockDiffLimitDuration) exceeds the limit the Streaming Service will terminate the TCP connection
clockDiffLimitDuration
The period, in ISO 8601 duration format, during which the average clock difference should not exceed the clockDiffLimit
payloadRateLimit
The maximum amount of payloads per second allowed for the streaming session
If the average amount of received payloads per second during the duration (see payloadRateLimitDuration) exceeds the limit the Streaming Service will terminate the TCP connection
payloadRateLimitDuration
The period, in ISO 8601 duration format, during which the average amount of received payloads per second should not exceed the payloadRateLimit
payloadThroughputLimit
The maximum amount of payload kilobytes (KB) per second allowed for the streaming session
If the average amount of received payload kilobytes (KB) per second during the duration (see payloadThroughputLimitDuration) exceeds the limit the Streaming Service will terminate the TCP connection
payloadThroughputLimitDuration
The period, in ISO 8601 duration format, during which the average amount of received payload kilobytes (KB) per second should not exceed the payloadThroughputLimit
Example
POST api/v1/sessions HTTP/1.1
Host: api.udap.nl
X-Authorization: dtNB_vhvJ0wgTGf1N0DxN38_AmTL_4yiPRZdqZSuK3k
Content-Type: application/json
{
"domain": "test",
"type" : "TLC",
"protocol" : "TCPStreaming_Singleplex",
"details": {
"securityMode": "TLSv1.2",
"tlcIdentifier": "NLZH0023"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"token": "cXXrqTkrehOvLbuuYKKQQGAU1MTGGGBC1N1izwYaqu8",
"domain": "test",
"type": "TLC",
"protocol": "TCPStreaming_Singleplex",
"details": {
"securityMode": "TLSv1.2",
"tlcIdentifier": "NLZH0023",
"listener": {
"host": "n24.udap.nl",
"port": 58142,
"expiration": "2016-11-17T16:01:45Z"
},
"keepAliveTimeout": "PT5S",
"clockDiffLimit": "PT3S",
"clockDiffLimitDuration": "PT60S",
"payloadRateLimit": 15,
"payloadRateLimitDuration": "PT5S",
"payloadThroughputLimit": 15,
"payloadThroughputLimitDuration": "PT5S"
}
}
Session type "TLC" with protocol "TCPStreaming_Multiplex"
TCP based multiplex streaming session for one or more TLC's.
Payloads sent by the client will be received by "Broker" session clients if the payload "TLC identifier" is within their scope.
Payloads sent by "Broker" session clients having a payload "TLC identifier" that is within the scope of the session will be received.
Request details
{
"securityMode": "<security mode>",
"tlcIdentifiers": ["<TLC identifier>", "<TLC identifier>", ...]
}
The only difference in the request details is the tlcIdentifiers element which replace the tlcIdentifier element used in the "TCPStreaming_TLC_Singleplex" session type request details.
Name
Description
tlcIdentifiers
The TLC identifiers for the session
Since the session is for multiple TLC's, payload data will be streamed with TLC identifier (see protocol datagram 0x05)
Response details
{
"securityMode": "<security mode>",
"tlcIdentifiers": ["<TLC identifier>", "<TLC identifier>", ...]
"listener": {
"host": "<host address>",
"port": <port number>,
"expiration": "<ISO 8601 date time>"
},
"keepAliveTimeout": "<ISO 8601 duration>",
"clockDiffLimit": "<ISO 8601 duration>",
"clockDiffLimitDuration": "<ISO 8601 duration>",
"payloadRateLimit": <payload/second limit>,
"payloadRateLimitDuration": "<ISO 8601 duration>",
"payloadThroughputLimit": <KB/second limit>,
"payloadThroughputLimitDuration": "<ISO 8601 duration>"
}
The only difference in the response details is the tlcIdentifiers element which replace the tlcIdentifier element used in the "TCPStreaming_TLC_Singleplex" session type response details.
Example
POST api/v1/sessions HTTP/1.1
Host: api.udap.nl
X-Authorization: dtNB_vhvJ0wgTGf1N0DxN38_AmTL_4yiPRZdqZSuK3k
Content-Type: application/json
{
"domain": "test",
"type": "TLC",
"protocol": "TCPStreaming_Multiplex",
"details": {
"securityMode": "TLSv1.2",
"tlcIdentifiers": ["NLZH0023", "NLZH0024", "NLZH0025"]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"token": "dtNB_vhvJ0wgTGf1N0DxN38_AmTL_4yiPRZdqZSuK3k",
"domain": "test",
"type": "TLC",
"protocol": "TCPStreaming_Multiplex",
"details": {
"securityMode": "TLSv1.2",
"tlcIdentifiers": ["NLZH0023", "NLZH0024", "NLZH0025"],
"listener": {
"host": "n25.udap.nl",
"port": 51253,
"expiration": "2016-11-17T16:04:23Z"
},
"keepAliveTimeout": "PT5S",
"clockDiffLimit": "PT3S",
"clockDiffLimitDuration": "PT60S",
"payloadRateLimit": 45,
"payloadRateLimitDuration": "PT5S",
"payloadThroughputLimit": 45,
"payloadThroughputLimitDuration": "PT5S"
}
}
2.2.2.2 PUT /sessions/ token>
Updates the protocol details of the active streaming session with the given "token".
Intended to support the addition and removal of TLC identifiers for multiplex sessions.
Request
PUT <API base URL>/sessions/<session token> HTTP/1.1
Host: <hostname>
X-Authorization: <authorization token>
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json
<protocol details>
Example
PUT api/v1/sessions/cXXrqTkrehOvLbuuYKKQQGAU1MTGGGBC1N1izwYaqu8 HTTP/1.1
Host: api.udap.nl
X-Authorization: dtNB_vhvJ0wgTGf1N0DxN38_AmTL_4yiPRZdqZSuK3k
Content-Type: application/json
{
"securityMode": "NONE",
"tlcIdentifiers": ["NLZH0023", "NLZH0026"]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"token": "cXXrqTkrehOvLbuuYKKQQGAU1MTGGGBC1N1izwYaqu8",
"domain": "test",
"type": "TLC",
"protocol": "TCPStreaming_Multiplex",
"details": {
"securityMode": "NONE",
"tlcIdentifiers": ["NLZH0023", "NLZH0026"],
"listener": {
"host": "n44.udap.nl",
"port": 40344,
"expiration": "2016-11-17T16:07:56Z"
},
"keepAliveTimeout": "PT5S",
"clockDiffLimit": "PT3S",
"clockDiffLimitDuration": "PT60S",
"payloadRateLimit": 1200,
"payloadRateLimitDuration": "PT5S",
"payloadThroughputLimit": 120,
"payloadThroughputLimitDuration": "PT5S"
}
}
3 TCPStreaming protocol
The TCPStreaming protocol facilitates a continuous asynchronous bi-directional stream of datagrams.
3.1 Transport Layer Security
The Streaming Service optionally uses Transport Layer Security version 1.2 (TLSv1.2) to secure the TCP communication used for TCP streaming protocol sessions. The only supported cipher suite is "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256". Only server side authentication will be used.
3.2 Protocol version establishment
To support future protocol enhancement or replacement a one-byte version identifier is sent before the datagram streaming starts. When the peer does not support the protocol version the connection should be closed by the peer.
Protocol version (1 byte)
0x01
3.3 Protocol version 0x01
In protocol version 0x01 datagrams are streamed by using frames with a 4 byte header which is exists out of a 2 byte fixed prefix and a 2 byte frame data size. The header is followed by the frame data containing the actual datagram.
3.3.1 Byte Order
The byte order used by the protocol is "big-endian" also known as "network byte order": the byte containing the most significant bit (MSB) will be transmitted first.
3.3.2 Datagram framing
The datagrams are framed by having a 2 byte data size indication in the header. The header prefix, the fixed bytes 0xAA and 0xBB, has been added for "out of sync" detection and also to have 32 bit "aligned" header. By having the data size in the header no stream decoding is needed to read subsequent frames. Since the header data size is 2 bytes, one frame can hold a maximum of 63KB of data. The size of the frames should always by > 0; empty frames are not supported.
Version preamble
(1 byte)
Frame 1
Frame 2
Frame n
Header
Data
Header
Data
Header
Data
Prefix
Data size
Prefix
Data size
Prefix
Data size
0x01
0xAA BB
0x00 01
0x00
0xAA BB
0x00 04
0x04 01 03 23
0xAA BB
...
...
The fixed header prefix bytes should always be checked (asserted) since a mismatch would indicate a framing issue resulting in data corruption. When such a framing issue is detected the connection should be terminated as soon as possible.
3.3.3 Communication modes
3.3.3.1 TLC singleplex mode
This mode can be used by TLC systems. Streaming sessions of this type will receive all payloads from "Broker" sessions when the "TLC identifier" matches the "TLC identifier" specified in the "sessions" API call used for creating the streaming session. Only one session per "TLC identifier" will be allowed.
3.3.3.2 TLC multiplex mode
This mode can be used by TLC systems. Streaming session in this mode will receive all payloads from "Broker" sessions when the "TLC identifier" matches one of the "TLC identifiers" specified in the "sessions" API call used for creating the streaming session.
If one of the "TLC identifiers" in the "create session" call is already being used in an other active session, the API will refuse the "create session" call.
3.3.3.3 Broker mode
This mode will be used by the Broker systems. Streaming session in this mode will receive all payloads from "TLC singleplex" or "TLC multiplex" sessions when the "TLC identifier" matches one of the "TLC identifiers" specified in the "sessions" API call used for creating the streaming session.
If one of the "TLC identifiers" in the "create session" call is already being used in an other active session of the Broker account, the API will refuse the "create session" call.
3.3.3.4 Monitor mode
This mode will be used by governance organisations to facilitate analytics and diagnostics. Streaming session in this mode will receive all payloads from "TLC singleplex", "TLC multiplex" sessions and "Broker" sessions when the "TLC identifier" matches one of the "TLC identifiers" specified in the "sessions" API call used for creating the streaming session.
If one of the "TLC identifiers" in the "create session" call is already being used in an other active session of the organisation (account), the API will refuse the "create session" call.
Monitor sessions can only receive data.
3.3.4 Datagrams
The frame data contains the actual datagram which is identified by a one byte "datagram type" identifier. The following datagrams are defined:
3.3.4.1 KeepAlive (0x00)
This datagram can be used to prevent disconnects when no data is available to sent within the keep alive timeout.
Datagram type (1 byte)
0x00
3.3.4.2 Token (0x01)
The first datagram sent by the Client should be "Token" in order the properly authenticate the Client.
Datagram type (1 byte)
Token (ASCII encoded)
0x01
Token>
3.3.4.3 Bye (0x02)
This datagram can be used by either party to indicate that the connection will be closed. The reason (ASCII Encoded) is optional. It is the last datagram sent.
Datagram type (1 byte)
Disconnect reason (optional, ASCII encoded)
0x02
Reason>
3.3.4.4 Reconnect (0x03)
This datagram can be used by the Streaming Service to instruct the Client to reconnect as soon as possible.
A new session needs to be created using the API in order to reconnect.
Datagram type (1 byte)
0x03
3.3.4.5 Payload datagrams (0x04, 0x05)
The payload datagrams "carry" the actual payload which is being streamed by the Streaming Service. Both payload datagrams have an "Origin timestamp" field that should be filled with transmission time timestamp. This timestamp must be obtain from the same clock source as used to handle the "timestamps request" message. The payload type is identified by a single payload type byte. Payload type bytes 0xF0 to 0xFF are reserved for protocol use.
Protocol payload types
Payloiad type byte
Payload type
0xF0
Monitor Payload (see Monitor Payload Encoding below)
Payload without TLC identifier (0x04)
This datagram is in "TLC_Singleplex" communication mode to send and receive data and can only be used for singleplex sessions (session type "TCPStreaming_TLC_Singleplex").
Datagram type (1 byte)
Payload type byte (1 byte)
Origin timestamp (8 bytes)
Payload (n bytes)
0x04
<Payload type byte>
<UTC milliseconds>
<Payload>
If this datagram is used for a multiplex session, the session will be terminated by the Streaming Service.
Payload with TLC identifier (0x05)
This datagram is used in "TLC_Multiplex" and "Broker" communication modes to send and receive data in a multiplex session (session types "TCPStreaming_TLC_Multiplex" and "TCPStreaming_Broker").
Datagram type (1byte)
TLC identifier (8 bytes, ASCII encoded)
Payload type byte (1 byte)
Origin timestamp (8bytes)
Payload (nbytes)
0x05
<TLC identifier>
<Payload type byte>
<UTC milliseconds>
<Payload>
In communication modes "TLC_Multiplex" and "Broker" only datagrams with a "TLC identifier" requested for the streaming session are allowed. If a non-requested "TLC identifier" is used, the payload will be dropped by the Streaming Service.
Monitor Payload Encoding
Payload type 0xF0 indicates a special payload that adds a diagnostic header to the original payload with additional diagnostic information.
Publisher session token length (4 byte)
Publisher session token (n bytes, ASCII encoded)
Publishing timestamp (8bytes)
Sent timestamp (8 bytes)
Original payload type (1 byte)
Original payload (nbytes)
<length in bytes>
<Publisher session token>
<UTC milliseconds>
<UTC milliseconds>
<Payload type>
<Payload>
It is possible for the Publisher session token to have a "zero length". This indicates a payload that has been resent instead of being published by a publisher.
3.3.4.6Timestamp datagrams (0x06, 0x07)
The timestamp datagrams are used to determine connection latency and clock difference.
Timestamps request (0x06)
This datagram contains the transmission timestamp which will be "echo'd back" by the recipient using the "Timestamps response" datagram. The Streaming Service will send this datagram at a regular interval (15 seconds) to measure the connection latency and to calculate the clock difference between the Streaming Service and the connected party. The connection latency is used to evaluate the accuracy of the calculated clock difference.
Datagram type (1 byte)
t0: transmission timestamp (8 bytes)
0x06
<UTC milliseconds>
Timestamps response (0x07)
This datagram must be used as response to a received "Timestamps request" datagram and must contain the original "t0: transmission timestamp" of this datagram. The response should by prioritised to any other traffic; in other words: it should be sent as soon as possible after receiving the "Timestamps request" message. The "t1: request reception timestamp" field must be filled with the reception time timestamp and should be determined as soon as possible upon reception of the "Timestamps request" message. The "t2: response transmission timestamp" field must be filled with the transmission time timestamp and should be determined as late as possible in the transmission process.
Datagram type (1 byte)
t0: transmission timestamp from request (8 bytes)
t1: request reception timestamp (8 bytes)
t2: response transmission timestamp (8 bytes)
0x07
<UTC milliseconds>
<UTC milliseconds>
<UTC milliseconds>