ETSI TS 118 120 V2.1.2 (2020-03)

ETSI TS 118 120 V2.1.2 (2020-03)






TECHNICAL SPECIFICATION
oneM2M;
WebSocket Protocol Binding
(oneM2M TS-0020 version 2.1.2 Release 2A)

---------------------- Page: 1 ----------------------
oneM2M TS-0020 version 2.1.2 Release 2A 2 ETSI TS 118 120 V2.1.2 (2020-03)



Reference
RTS/oneM2M-000020v2A
Keywords
IoT, M2M, protocol

ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE

Tel.: +33 4 92 94 42 00  Fax: +33 4 93 65 47 16

Siret N° 348 623 562 00017 - NAF 742 C
Association à but non lucratif enregistrée à la
Sous-Préfecture de Grasse (06) N° 7803/88

Important notice
The present document can be downloaded from:
http://www.etsi.org/standards-search
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the prevailing version of an ETSI
deliverable is the one made publicly available in PDF format at www.etsi.org/deliver.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
https://portal.etsi.org/TB/ETSIDeliverableStatus.aspx
If you find errors in the present document, please send your comment to one of the following services:
https://portal.etsi.org/People/CommiteeSupportStaff.aspx
Copyright Notification
No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying
and microfilm except as authorized by written permission of ETSI.
The content of the PDF version shall not be modified without the written authorization of ETSI.
The copyright and the foregoing restriction extend to reproduction in all media.

© ETSI 2020.
All rights reserved.

DECT™, PLUGTESTS™, UMTS™ and the ETSI logo are trademarks of ETSI registered for the benefit of its Members.

3GPP™ and LTE™ are trademarks of ETSI registered for the benefit of its Members and
of the 3GPP Organizational Partners.
oneM2M™ logo is a trademark of ETSI registered for the benefit of its Members and
of the oneM2M Partners.
®
GSM and the GSM logo are trademarks registered and owned by the GSM Association.
ETSI

---------------------- Page: 2 ----------------------
oneM2M TS-0020 version 2.1.2 Release 2A 3 ETSI TS 118 120 V2.1.2 (2020-03)
Contents
Intellectual Property Rights . 4
Foreword . 4
1 Scope . 5
2 References . 5
2.1 Normative references . 5
2.2 Informative references . 5
3 Definition of terms, symbols and abbreviations . 6
3.1 Terms . 6
3.2 Symbols . 6
3.3 Abbreviations . 6
4 Conventions . 6
5 Overview on WebSocket Binding . 6
5.1 Use of WebSocket . 6
5.2 Binding Overview . 7
6 Protocol Binding . 10
6.1 Introduction . 10
6.2 WebSocket connection establishment . 10
6.2.1 General . 10
6.2.2 Client handshake . 10
6.2.2.1 Format of request-line . 10
6.2.2.2 Host header . 10
6.2.2.3 Upgrade header . 11
6.2.2.4 Connection header . 11
6.2.2.5 Sec-WebSocket-Key header . 11
6.2.2.6 Sec-WebSocket-Version header . 11
6.2.2.7 Sec-WebSocket-Protocol header . 11
6.2.2.8 Sec-WebSocket-Extensions header . 11
6.2.2.9 Subprotocol names and serialization formats . 12
6.2.3 Server handshake format . 12
6.2.3.1 Format of status-line . 12
6.2.3.2 Upgrade header . 12
6.2.3.3 Connection header . 12
6.2.3.4 Sec-WebSocket-Accept header . 12
6.2.3.5 Sec-WebSocket-Protocol header . 12
6.2.3.6 Sec-WebSocket-Extensions header . 13
6.3 Closing WebSocket connection . 13
6.4 Registration procedure . 13
6.5 Handling of Non-Registration Request . 13
6.6 Use of proxy servers . 13
7 Security Aspects . 14
Annex A (informative): Example Procedures . 15
A.1 AE Registration and creation of a Container child resource . 15
History . 18

ETSI

---------------------- Page: 3 ----------------------
oneM2M TS-0020 version 2.1.2 Release 2A 4 ETSI TS 118 120 V2.1.2 (2020-03)
Intellectual Property Rights
Essential patents
IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The information
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web
server (https://ipr.etsi.org/).
Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web
server) which are, or may be, or may become, essential to the present document.
Trademarks
The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners.
ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no
right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does
not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks.
Foreword
This Technical Specification (TS) has been produced by ETSI Partnership Project oneM2M (oneM2M).
ETSI

---------------------- Page: 4 ----------------------
oneM2M TS-0020 version 2.1.2 Release 2A 5 ETSI TS 118 120 V2.1.2 (2020-03)
1 Scope
The present document specifies the binding of Mca and Mcc primitives onto the WebSocket binding.
It specifies:
• Procedures and message formats for operating and closing of WebSocket connections.
• How request and response primitives are mapped into the payload of the WebSocket protocol.
2 References
2.1 Normative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
Referenced documents which are not found to be publicly available in the expected location might be found at
https://docbox.etsi.org/Reference/.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are necessary for the application of the present document.
[1] IETF RFC 6455 (December 2011): "The WebSocket Protocol".
[2] ETSI TS 118 101: "oneM2M; Functional Architecture (oneM2M TS-0001)".
[3] IETF RFC 7230 (June 2014): "Hypertext Transport Protocol (HTTP/1.1): Message Syntax and
Routing".
[4] ETSI TS 118 103: "oneM2M; Security solutions (oneM2M TS-0003)".
[5] ETSI TS 118 104: "oneM2M; Service Layer Core Protocol Specification (oneM2M TS-0004)".
[6] IETF RFC 7692 (December 2015): "Compression Extension for WebSocket".
2.2 Informative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are not necessary for the application of the present document but they assist the
user with regard to a particular subject area.
[i.1] oneM2M Drafting Rules.
NOTE: Available at http://www.onem2m.org/images/files/oneM2M-Drafting-Rules.pdf.
ETSI

---------------------- Page: 5 ----------------------
oneM2M TS-0020 version 2.1.2 Release 2A 6 ETSI TS 118 120 V2.1.2 (2020-03)
3 Definition of terms, symbols and abbreviations
3.1 Terms
For the purposes of the present document, the following terms apply:
oneM2M WebSocket Client (WS Client): WebSocket Client associated with an AE or a CSE capable of establishing
the WebSocket connections
oneM2M WebSocket Server (WS Server): WebSocket Server associated with a CSE which accepts requests to
establish WebSocket connections
3.2 Symbols
Void.
3.3 Abbreviations
For the purposes of the present document, the following abbreviations apply:
ADN Application Dedicated Node
AE Application Entity
ASN Application Service Node
CBOR Concise Binary Object Representation
CMDH Communication Management and Delivery Handling
CRUDN Create Retrieve Update Delete Notify
CSE Common Services Entity
FQDN Fully Qualified Domain Name
GUID Globally Unique IDentifier
HTTP Hypertext Transport Protocol
IETF Internet Engineering Task Force
IN-CSE Infrastructure Node Common Services Entity
IP Internet Protocol
JSON JavaScript Object Notation
MN Middle Node
MN-CSE Middle Node Common Services Entity
NAT Network Address Translator
RFC Request for Comments
SAEF Security Association Establishment Framework
TCP Transmission Control Protocol
TLS Transport Layer Security
URI Uniform Resource Identifier
WS WebSocket
WSS WebSocket Secure
XML eXtensible Markup Language
4 Conventions
The key words "Shall", "Shall not", "May", "Need not", "Should", "Should not" in the present document are to be
interpreted as described in the oneM2M Drafting Rules [i.1].
ETSI

---------------------- Page: 6 ----------------------
oneM2M TS-0020 version 2.1.2 Release 2A 7 ETSI TS 118 120 V2.1.2 (2020-03)
5 Overview on WebSocket Binding
5.1 Use of WebSocket
This binding makes use of the WebSocket protocol IETF RFC 6455 [1] to transport serialized representations of
oneM2M request and response primitives over the Mca or Mcc reference points.
Establishment of a WebSocket connection shall be initiated by a WebSocket client by sending a handshake to a
WebSocket server as specified in section 4 of IETF RFC 6455 [1]. Once the WebSocket connection is established, both
oneM2M request and response primitives can be exchanged bi-directionally between the two endpoints of the
connection. Serialized representations of the request and response primitives shall be mapped in the Payload Data field
of the WebSocket base framing protocol, as defined in section 5.2 of IETF RFC 6455 [1].
A WebSocket connection employs either a TCP/IP or a TLS over TCP/IP connection. The underlying TCP and TLS
connections are established as the first step of the WebSocket handshake.
5.2 Binding Overview
WebSocket binding may be employed for communication between any two endpoints which can be connected over the
Mca, Mcc or Mcc' interface reference points supported by the oneM2M Architecture as shown in figure 6.1-1 of ETSI
TS 118 101 [2].
When using the WebSocket protocol, one communication endpoint shall act as the WebSocket server. The WebSocket
server listens for inbound handshake messages arriving from any WebSocket client to which a WebSocket connection is
not yet established. Whether a communication endpoint takes the role of the client or the server shall depend on the
registration relationship between the communicating entities as follows: the registree shall always use a WebSocket
client, while the associated registrar shall always use a WebSocket server on the respective reference point.
This implies that ADN and ASN always take the role of a WebSocket client when WebSocket binding is employed. An
MN-CSE uses a WebSocket server to communicate with its registrees and a WebSocket client to communicate with its
own registrar (which can be another MN-CSE or an IN-CSE).
The IN-CSE provides a WebSocket server functionality to communicate with all its registrees, i.e. within a service
provider's domain. On the Mcc' reference points, i.e. for communication between IN-CSEs of different Service Provider
domains, the IN-CSE shall provide both WebSocket client and server functionality. This enables any IN-CSE to open a
WebSocket connection to any IN-CSE of another Service Provider's domain.
Figure 5.2-1 shows some applicable example system configuration.
ETSI

---------------------- Page: 7 ----------------------
WS
Client
WS
Server
WS
Client
WS
Server
WS
WS WS WS
Client
Client Client Client
oneM2M TS-0020 version 2.1.2 Release 2A 8 ETSI TS 118 120 V2.1.2 (2020-03)
ADN
Mca
AE
ADN
Mca
AE
IN
ASN MN MN
AE
AE AE
CSE
CSE
CSE
CSE WS WS
Server Client
Mcc
Mcc
ASN
Mcc’
AE
CSE
Mcc

Figure 5.2-1: Example scenarios of WebSocket client and server configurations
There exists a maximum of one WebSocket connection between two nodes. A WebSocket connection is established for
the first time when the initial registration procedure of an entity to its registrar is performed. On an established
WebSocket connection, request and response primitives can be exchanged in both directions. Any connection may be
closed by either the WebSocket client or the server, depending on the communication schedule of either entity.
However, the connection can be reopened from the client side only.
If the connection is closed temporarily, it shall be reopened when the next request primitive is sent from the client to the
server side, or when the time to become reachable configured at resource. If the WebSocket connection
with the next-hop entity is not opened, and the WebSocket connection cannot be established due to lack of
pointOfAccess address for the entity, a sending CSE may enable buffering of primitives which should be sent to the
entity until the connection is reopened or their expiration time is reached. See Annex H of ETSI TS 118 104 [5] about
buffering of primitives by CMDH functionality.
Figure 5.2-2 shows an example message flow for a scenario where an ADN-AE registers to its registrar MN-CSE using
an unsecured TCP connection without proxy and then continues exchanging non-registration request and response
primitives.
ETSI

---------------------- Page: 8 ----------------------
oneM2M TS-0020 version 2.1.2 Release 2A 9 ETSI TS 118 120 V2.1.2 (2020-03)
ADN MN
WS client WS server
AE CSE
1) AE wants to start registration
procedure and triggers WebSocket
connection establishment
2) Client handshake
3) Server handshake
4) Request primitive
5) WebSocket Binding
6) WebSocket message
7) Unpacking request primitive
8) Request primitive
9) Receiver side processing of
AE registration procedure
10) Response primitive
11) WebSocket Binding
12) WebSocket message
13) Unpacking response primitive
14) Response primitive
15) non-registration CRUDN operations

Figure 5.2-2: Example message flow with Websocket binding
1) The ADN-AE wants to register to its registrar MN-CSE. If a WebSocket connection does not exist, it is
established by the following steps 2) and 3). It is assumed that the ADN-AE knows the point of access
(i.e. WebSocket URI specified in IETF RFC 6455 [1]) under which the registrar CSE can be reached with
WebSocket binding.
2) The WebSocket client opens handshake to the server with subprotocol name 'oneM2M-pro-v1.0' following
IETF RFC 6455 [1].
If the server can be reached under the WebSocket URI ws://example.net:9000/, the client handshake may look
as follows:
GET / HTTP/1.1
Host: mncse1234.net:9000
Upgrade: WebSocket
Connection: Upgrade
Sec-WebSocket-Key: ud63env87LQLd4uIV20/oQ==
Sec-WebSocket-
...