forked from onvif/specs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathUplink.xml
358 lines (358 loc) · 18.1 KB
/
Uplink.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
<?xml version="1.0"?>
<?xml-stylesheet href="docbook.xsl" type="text/xsl" ?>
<book xmlns="http://docbook.org/ns/docbook" version="5.0">
<info>
<title>Uplink Specification</title>
<titleabbrev>Uplink</titleabbrev>
<releaseinfo>23.06</releaseinfo>
<author>
<orgname>ONVIF™</orgname>
<uri>www.onvif.org</uri>
</author>
<pubdate> June, 2023</pubdate>
<mediaobject>
<imageobject>
<imagedata fileref="media/logo.png" contentwidth="60mm" />
</imageobject>
</mediaobject>
<copyright>
<year>2008-2023</year>
<holder>ONVIF™ All rights reserved.</holder>
</copyright>
<legalnotice>
<para>Recipients of this document may copy, distribute, publish, or display this document so long as this copyright notice, license and disclaimer are retained with all copies of the document. No license is granted to modify this document.</para>
<para>THIS DOCUMENT IS PROVIDED "AS IS," AND THE CORPORATION AND ITS MEMBERS AND THEIR AFFILIATES, MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THIS DOCUMENT ARE SUITABLE FOR ANY PURPOSE; OR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.</para>
<para>IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES, ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS DOCUMENT, WHETHER OR NOT (1) THE CORPORATION, MEMBERS OR THEIR AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR (2) SUCH DAMAGES WERE REASONABLY FORESEEABLE, AND ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS DOCUMENT. THE FOREGOING DISCLAIMER AND LIMITATION ON LIABILITY DO NOT APPLY TO, INVALIDATE, OR LIMIT REPRESENTATIONS AND WARRANTIES MADE BY THE MEMBERS AND THEIR RESPECTIVE AFFILIATES TO THE CORPORATION AND OTHER MEMBERS IN CERTAIN WRITTEN POLICIES OF THE CORPORATION.</para>
</legalnotice>
<revhistory>
<revision>
<revnumber>18.12</revnumber>
<date>Dec 2018</date>
<author>
<personname>Hans Busch</personname>
</author>
<revremark>First release</revremark>
</revision>
<revision>
<revnumber>22.06</revnumber>
<date>June 2022</date>
<author>
<personname>Hans Busch</personname>
</author>
<revremark>Add section on media streaming</revremark>
</revision>
<revision>
<revnumber>23.06</revnumber>
<date>June 2023</date>
<author>
<personname>Hans Busch</personname>
</author>
<revremark>Clarify authentication within the established tunnel.</revremark>
</revision>
</revhistory>
</info>
<chapter>
<title>Scope </title>
<para>This document defines the connection protocol for connecting a web service behind a firewall to a client reachable in the internet.</para>
</chapter>
<chapter>
<title>Normative references</title>
<para>IETF RFC 5246 - The Transport Layer Security (TLS) Protocol, Version 1.2</para>
<para role="reference"><<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc5246"></link>></para>
<para>IETF RFC 6125 - Representation and Verification of Domain-Based Application Service</para>
<para> Identity within Internet Public Key Infrastructure Using X.509 (PKIX)</para>
<para> Certificates in the Context of Transport Layer Security (TLS)</para>
<para role="reference"><<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tools.ietf.org/html/rfc6125"></link>> </para>
<para>IETF RFC 7540 - Hypertext Transfer Protocol Version 2 (HTTP/2)</para>
<para role="reference"><<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tools.ietf.org/html/rfc7540"></link>> </para>
<para>IETF RFC 8441 - Bootstrapping WebSockets with HTTP/2</para>
<para role="reference"><<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://tools.ietf.org/html/rfc8441"></link>> </para>
<para>ONVIF Core Specification</para>
<para role="reference"><<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.onvif.org/onvif/specs/core/ONVIF-Core-Specification.pdf"></link>></para>
<para>ONVIF Media2 Service Specification</para>
<para role="reference"><<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.onvif.org/specs/srv/media/ONVIF-Media2-Service-Spec.pdf"></link>></para>
<para>ONVIF Streaming Specification</para>
<para role="reference"><<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.onvif.org/specs/stream/ONVIF-Streaming-Spec.pdf"></link>></para>
<para>Apple Computer Inc. RTSP over HTTP, Tunneling QuickTime RTSP and RTP over HTTP</para>
<para role="reference"><<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://opensource.apple.com/source/QuickTimeStreamingServer/QuickTimeStreamingServer-412.42/Documentation/RTSP_Over_HTTP.pdf"></link>></para>
</chapter>
<chapter>
<title>Terms and Definitions</title>
<section>
<title>Definitions</title>
<informaltable>
<tgroup cols="2">
<colspec colname="c1" colwidth="24*" />
<colspec colname="c2" colwidth="76*" />
<tbody valign="top">
<row>
<entry align="left">
<para>
<emphasis role="bold">Local Service</emphasis>
</para>
</entry>
<entry align="left">
<para>A service to be used by a client behind a firewall.</para>
</entry>
</row>
<row>
<entry align="left">
<para>
<emphasis role="bold">Remote Client</emphasis>
</para>
</entry>
<entry align="left">
<para>A client that wants to access a service that is located behind a firewall.</para>
</entry>
</row>
<row>
<entry align="left">
<para>
<emphasis role="bold">Uplink</emphasis>
</para>
</entry>
<entry align="left">
<para>The connection establish by the local service to the remote client.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section>
<title>Abbreviations</title>
<informaltable>
<tgroup cols="2">
<colspec colname="c1" colwidth="24*" />
<colspec colname="c2" colwidth="76*" />
<tbody valign="top">
<row>
<entry valign="middle">
<para>HTTP</para>
</entry>
<entry valign="middle">
<para>Hypertext Transfer Protocol</para>
</entry>
</row>
<row>
<entry valign="middle">
<para>TLS</para>
</entry>
<entry valign="middle">
<para>Transport Layer Security</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
</chapter>
<chapter>
<title>Overview</title>
<para>The ONVIF connection protocols base on the standard web service model where the client initiates a connection to a device as depicted in <xref linkend="_Ref493258796" />..</para>
<figure xml:id="_Ref493258796">
<title>Standard connection initiated from the client</title>
<mediaobject>
<imageobject>
<imagedata fileref="media/Uplink/image2.svg" contentwidth="94.13mm" />
</imageobject>
</mediaobject>
</figure>
<figure xml:id="_Ref486253450">
<title>Connection initiation from the device</title>
<mediaobject>
<imageobject>
<imagedata fileref="media/Uplink/image3.svg" contentwidth="124.27mm" />
</imageobject>
</mediaobject>
</figure>
<para>This document specifies a solution that allows a camera to use an uplink to facilitate existing web server and RTSP server functionality using the http/2 protocol.</para>
</chapter>
<chapter>
<title>Uplink</title>
<section>
<title>Connection Establishment</title>
<para>The device initiates the connection to the cloud service. <xref linkend="_Ref505091745" /> shows the three phases. In the first phase the device acts as TLS client that connects to the cloud service. Please note that the figure only shows the most relevant packets. Details of the TCP and TLS exchange are out of scope of this specification. The second phase includes the connection upgrade to HTTP/2 which is confirmed by the cloud service with a 101 HTTP response. The third phase of the connection than fully complies to an HTTP2 connection as if it were initiated from the cloud service.</para>
<figure xml:id="_Ref505091745">
<title>Connection initiation from the device</title>
<mediaobject>
<imageobject>
<imagedata fileref="media/Uplink/image4.svg" contentwidth="128mm" />
</imageobject>
</mediaobject>
</figure>
</section>
<section>
<title>Connection Management</title>
<para>A local service that is offered to a remote client for utilization is responsible for maintaining an operational communication channel. Since the connection needs to be established from the service to the remote client this connection is called uplink. The uplink shall be secured via TLS. </para>
<para>The service shall monitor whether the remote client is able to communicate via the uplink. It may use the HTTP/2 ping mechanism to check whether a link is still operational if no packets have been received for a longer period of time.</para>
<para>A local service shall close and reconnect the uplink whenever no packets have been received from the remote client for more than 30 seconds. Each camera shall use an individual ascending interval strategy to avoid that all cameras connect at the same time.</para>
<para>The following example shows patterns chosen by two cameras A and B:</para>
<itemizedlist>
<listitem>
<para>Camera A: 3s, 6s, 12s, 24s, 30s, 30s, 30s ...</para>
</listitem>
<listitem>
<para>Camera B: 2s, 4s, 8s, 16s, 30s, 30s, 30s ...</para>
</listitem>
</itemizedlist>
<para>If the uplink list contains multiple entries the device shall try to establish all connections in parallel. </para>
<para>Note that this specification assumes that scenarios with multiple clients are designed such that they do not interfere with each other. The coordination between such multiple clients is outside of the scope of the specification.</para>
</section>
<section>
<title>Authentication</title>
<para>Note that for the following discussion the roles of client and server are swapped.</para>
<para>The remote client shall authenticate itself using a valid server certificate. The service shall verify the validity of the remote certificate according to RFC 6125. </para>
<para>The service shall authenticate itself at the remote client using TLS client authentication according to RFC 5246 or subsequent specifications.</para>
<para>To uniquely identify local service on remote client, it is recommended to have a unique client certificate installed on each local service. For example, CN field or Serial number of installed certificate could be used to uniquely identify the local service.</para>
<para>The device shall assign any tunneled HTTP or RTSP request the UserLevel that is
configured for the configuration without the need of further authentication request headers. </para>
</section>
<section>
<title>HTTP/2 Frames</title>
<para>Once an http/2 connection has been established the communication parameters are negotiated as specified by RFC 7540 so that the uplink can be used to exchange frames between the remote client and the local service.</para>
</section>
<section>
<title>HTTP Transactions</title>
<para>The uplink shall be used in reverse direction for http requests and responses. The remote client shall send requests that are served in a standard http manner by the local service.</para>
</section>
<section>
<title>Media Streaming</title>
<section>
<title>Introduction</title>
<para>The ONVIF Media Service Specification and the ONVIF Streaming Specification define
various mechanism for streaming Video, Audio and Metadata. This specification defines how
to apply streaming over http. Usage of other communication mechanism like UDP unicast and
multicast are outside of the scope of this specification.</para>
</section>
<section>
<title>RTSP over HTTP</title>
<para>The underlying RTSP over HTTP specification requires to open separate communication
channels for continously sending and receiving data. For sending media from RTSP server to
client the communication channel is opened with a GET request and a response without
content-length. For sending media to the server a POST request is used. The specification
notes that a content-length must be sent. Most applications use the value 32767 from the
example given in the specification. Since http/2 streams may be closed by either side when
the content-length has been reached clients shall use a value large enough for the
connection life time.</para>
</section>
<section>
<title>RTSP over WebSockets</title>
<para>A device signaling support for websockets over RTSP via its capabilities shall support
RFC 8441 on the uplink.</para>
</section>
</section>
</chapter>
<chapter>
<title>Configuration Interface</title>
<section>
<title>Configuration parameters</title>
<itemizedlist>
<listitem>
<para>RemoteAddress Uniform resource locator by which the remote client can be reached.</para>
</listitem>
<listitem>
<para>CertificateID ID of the certificate to be used for client authentication.</para>
</listitem>
<listitem>
<para>UserLevel Authorization level that will be assigned to the uplink connection</para>
</listitem>
<listitem>
<para>Status Current connection status</para>
</listitem>
<listitem>
<para>CertPathValidationPolicyID ID of Certificate Validation policy to validate the remote uplink server certficate. If not configured, server certificate shall not be validated. </para>
</listitem>
</itemizedlist>
<para>Field RemoteAddress is used as key of the list of uplink configurations.</para>
</section>
<section>
<title>GetUplinks</title>
<para>A device supporting uplinks shall support this command to retrieve the configured uplink configurations. The Status field shall signal whether a connection is Offline, Connecting or Online.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
<listitem>
<para role="text">This message is empty</para>
</listitem>
</varlistentry>
<varlistentry>
<term>response</term>
<listitem>
<para role="param">Configuration – optional, unbounded [Configuration]</para>
<para role="text">List of configurations.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>access class</term>
<listitem>
<para role="access">READ_SYSTEM</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>SetUplink</title>
<para>A device supporting uplinks shall support this command to add or modify an uplink configuration. The Status property of the UplinkConfiguration shall be ignored by the device. A device shall use the field RemoteAddress to decide whether to update an existing entry or create a new entry.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
<listitem>
<para role="param">Configuration – [UplinkConfiguration]</para>
<para role="text">Configuration to be added or modified.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>response</term>
<listitem>
<para role="text">This message is empty</para>
</listitem>
</varlistentry>
<varlistentry>
<term>access class</term>
<listitem>
<para role="access">WRITE_SYSTEM</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>DeleteUplink</title>
<para>A device supporting uplinks shall support this command to remove an uplink configuration. </para>
<variablelist role="op">
<varlistentry>
<term>request</term>
<listitem>
<para role="param">RemoteAddress – [xs:anyURI]</para>
<para role="text">Configuration to be deleted.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>response</term>
<listitem>
<para role="text">This message is empty</para>
</listitem>
</varlistentry>
<varlistentry>
<term>access class</term>
<listitem>
<para role="access">WRITE_SYSTEM</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Capabilities</title>
<variablelist>
<varlistentry>
<term>MaxUplinks</term>
<listitem><para>Maximum number of uplink connections that can be configured</para></listitem>
</varlistentry>
</variablelist>
</section>
</chapter>
<appendix role="revhistory">
<title>Revision History</title>
<para />
</appendix>
</book>