6.2 WebSocket connection establishment
6.2.1 General
A WebSocket connection is opened by the client side as specified in section 4 of IETF RFC 6455 [1] with sending of a client handshake. The server responds with a server handshake.
The client handshake consists of an HTTP upgrade request, along with a list of required and optional header fields.
The handshake shall be a valid HTTP request as specified by IETF RFC 7230 [3]. The server handshake consists of a HTTP status-line and a list of header fields.
The applicable format of the request-line, status-line and the applicable header fields are specified in the following sub-clauses.
HTTP headers fields have case-insensitive field names.
CSEs capable to support WebSocket shall indicate the schemes ws and/or wss together with the applicable host name and port numbers in the pointOfAccess attribute of their <CSEBase> and in the <remoteCSE> resources, i.e. as ws://host:port1 and wss://host:port2, where host refers to either an IP address or an FQDN.
By default, the WebSocket Protocol [1] uses port 80 for regular WebSocket connections and port 443 for WebSocket connections over Transport Layer Security (TLS). If a WebSocket URI does not include an explicit port number, the default port number shall apply. Possible example representations of the pointOfAccess attribute <CSEBase> or <remoteCSE> resources associated with entities supporting a WebSocket server are the following:
-
ws://ws-server.example.com:80
-
ws://ws-server.example.com
-
wss://10.251.232.119:443
NOTE: ADN-AEs and ASN-CSEs do not need to support WebSocket servers and therefore do not require a WebSocket URI in the pointOfAccess attribute (see figure 5.2.1).
6.2.2 Client handshake
6.2.2.1 Format of request-line
The request-line of a client handshake shall begin with the method token "GET", followed by the request target "/" and the HTTP version set to "HTTP/1.1" as follows:
If the client is configured to use a proxy when using the WebSocket Protocol, a connection to the proxy server shall be established prior to sending the above client handshake. This is described in clause 6.6.
6.2.2.2 Host header
The Host header shall be present in each client handshake.
The Host header indicates the FQDN or IP address of the Receiver CSE of the next hop. If the originator of the client handshake is an oneM2M field entity, the host header represents the registrar CSE of the originator.
When no proxy is used, the Host header shall be set as one of the pointOfAccess attribute values associated with the Receiver. Selection of the appropriate Receiver is described in oneM2M TS-0004 [5].
If the client is configured to use a proxy when using the WebSocket Protocol, then the client should connect to that proxy and ask it to open a TCP connection to the host and port rather than to the next hop CSE.
6.2.2.3 Upgrade header
The Upgrade header shall be present in each client handshake message with value WebSocket as follows:
6.2.2.4 Connection header
The Connection header shall be present in each client handshake message with value Upgrade as follows:
6.2.2.5 Sec-WebSocket-Key header
The Sec-WebSocket-Key header shall be present in each client handshake message. The header field includes a base64-encoded representation of a random 16 bytes pattern, for example:
6.2.2.6 Sec-WebSocket-Version header
The Sec-WebSocket-Version header shall be present in each client handshake message with value 13 as follows:
6.2.2.7 Sec-WebSocket-Protocol header
The Sec-WebSocket-Protocol header shall be present in a client handshake message. It enables the client to indicate its supported application subprotocols on the server and be sure that the server agreed to support that subprotocol. It is used by the client to indicate the oneM2M Service Layer Protocol version and supported serialization formats to the server.
The value of the Sec-WebSocket-Protocol header shall be one or more of the registered names defined in clause 6.2.2.9. It shall also be allowed to include multiple Sec-WebSocket-Protocol headers with a value that includes one registered name each as defined in IETF RFC 6455 [1], for example:
and
are equivalent headers, expressing that the WebSocket client supports both application subprotocols, oneM2M.json and oneM2M.xml. The order of names indicated in the Sec-WebSocket-Protocol header specifies the client's preference.
6.2.2.8 Sec-WebSocket-Extensions header
The Sec-WebSocket-Extensions header may be used to negotiate the use of per-message compression as specified in IETF RFC 7692 [6].
If the client handshake includes the header, e.g.
it indicates to the server the client's preference to apply the compression mechanism defined in IETF RFC 7692 [6]. The header may include additional parameters as specified in IETF RFC 7692 [6].
When the server accepts use of message compression it responds with a Sec-WebSocket-Extensions header in the server handshake message as specified in clause 6.2.3.6, and in this case compression is applied in both transmission directions. If the server handshake message does not include a Sec-WebSocket-Extensions header, compression shall not be applied.
6.2.2.9 Subprotocol names and serialization formats
The Sec-WebSocket-Protocol header in the opening handshake is used to negotiate the application protocol layered on top of WebSocket. The application protocol addressed in this specification is the Release-2 version of the oneM2M Service Layer.
The oneM2M Service Layer Protocol consists of the exchange of serialized representations of request and response primitives as defined in oneM2M TS-0001 [2] and oneM2M TS-0004 [5]. This version of the specification allows use of the serialization formats listed in table 6.2.2.9-1. Both, protocol version and serialization format are associated with a specific subprotocol name.
Table 6.2.2.9-1 lists the serialization formats, associated subprotocols names and opcode setting of the WebSocket Frame protocol applicable for the present version of this specification.
Table 6.2.2.91: Applicable Subprotocol names
| Serialization Format | Subprotocol Name | WS opcode | Notes |
|---|---|---|---|
| JSON | oneM2M.json | x1 ("text frame") | See clause 8.4 in oneM2M TS-0004 [5] |
| XML | oneM2M.xml | x1 ("text frame") | See clause 8.3 in oneM2M TS-0004 [5] |
| CBOR | oneM2M.cbor | x2 ("binary frame") | See clause 8.5 in oneM2M TS-0004 [5] |
6.2.3 Server handshake format
6.2.3.1 Format of status-line
The status-line of a server handshake shall begin with the HTTP version set to "HTTP/1.1", followed by the status code and reason phrase as defined in IETF RFC 6455 [1]. When the WebSocket connection is established successfully, the status-line may look as follows:
For the unsuccessful connection establishment, any appropriate HTTP error status code shall be returned with optional addition of a corresponding reason phrase.
6.2.3.2 Upgrade header
The Upgrade header shall be present in each server handshake message with value WebSocket as follows:
6.2.3.3 Connection header
The Connection header shall be present in each server handshake message with value Upgrade as follows:
6.2.3.4 Sec-WebSocket-Accept header
The Sec-WebSocket-Accept header shall be present in each server handshake message. The header field shall be constructed from the Sec-WebSocket-Key value and the GUID as specified in section 4.2.2 of IETF RFC 6455 [1]. It may look e.g. as follows:
6.2.3.5 Sec-WebSocket-Protocol header
The Sec-WebSocket-Protocol header shall be present in a server handshake message. It indicates to the client that the server accepts (one of) the subprotocol(s) indicated by the client.
The server compliant with this specification shall select one of the subprotocol names indicated in the Sec-WebSocket-Protocol header of the client handshake message and set the value of the Sec-WebSocket-Protocol header of the server handshake message accordingly.
6.2.3.6 Sec-WebSocket-Extensions header
If the optional Sec-WebSocket-Extensions header with value "permessage-deflate" was included in the client handshake message, the Sec-WebSocket-Extensions header with same value shall also be included into the server handshake message, if the server accepts usage of message compression, and apply message compression in the transmit direction and message decompression in the receive direction as defined in IETF RFC 7692 [6].
If the server does not accept message compression, it shall not include the Sec-WebSocket-Extensions header.