Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found
Select Git revision
  • Initial-conversion
  • R4
  • R5
  • SDS-2024-0021-Corrections_for_WS_binding
  • SDS-2024-0043-Replace_mermaid_diagrams_with_images
  • SDS-2024-0043-Replace_mermaid_diagrams_with_images-patch-e578
  • gl-pages
  • main
  • v4.0.0
  • v4.1.0
  • v5.0.0
11 results

Target

Select target project
  • specifications/ts/ts-0020
1 result
Select Git revision
  • Initial-conversion
  • R4
  • R5
  • SDS-2024-0021-Corrections_for_WS_binding
  • SDS-2024-0043-Replace_mermaid_diagrams_with_images
  • SDS-2024-0043-Replace_mermaid_diagrams_with_images-patch-e578
  • gl-pages
  • main
  • v4.0.0
  • v4.1.0
  • v5.0.0
11 results
Show changes
Commits on Source (9)
![oneM2M logo](media/logo.png)
![](media/logo.png)
**oneM2M Technical Specification**
......@@ -130,11 +130,9 @@ A WebSocket connection employs either a TCP/IP or a TLS over TCP/IP connection.
## 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 oneM2M TS-0001 <a href="#_ref_2">[2]</a>.
The 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 oneM2M TS-0001 <a href="#_ref_2">[2]</a>.
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).
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 to establish a connection, while the associated registrar shall always use a WebSocket server on the respective reference point. Optionally, a registree may host a WebSocket server to receive notifications if no WebSocket connection has been established from the registree to the registrar.
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.
......@@ -144,20 +142,40 @@ Figure 5.2-1 shows some applicable example system configuration.
**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.
There exists a maximum of one WebSocket connection between a WebSocket client and a WebSocket server. 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 must 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 &lt;schedule> 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 oneM2M TS-0004 <a href="#_ref_5">[5]</a> about buffering of primitives by CMDH functionality.
An AE or CSE may optionally host a WebSocket server for situations when no WebSocket connection has been established to its registrar, and the registrar needs to send a request to this registree. In this case the registrar may open a WebSocket connection to the target WebSocket server to send the request and receive the response. The registrar or the registree may then close this WebSocket connection afterwards. This WebSocket connection is only intended as a fallback short-term communication channel between registrar and registree.
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.
![Example message flow with WebSocket binding](media/MessageFlow.png)
```mermaid
%%{init: { 'sequence': {'mirrorActors': false, 'actorFontSize': 2, 'noteFontSize':10} } }%%
sequenceDiagram
Note over ADN-AE, WS client: 1) AE wants to start registration<br/>procedure and triggers<br/>WebSocket connection<br/>establishment
WS client ->> WS server: 2) Client handshak
WS server ->> WS client: 3) Server handshake
ADN-AE ->> WS client: 4) Request primitive
Note over WS client: 5) Websocket binding
WS client ->> WS server: 6) WebSocket message
Note over WS server: 7) Unpacking request primitive
WS server ->> CSE: 8) Request primitive
Note over CSE: 9) Receiver side processing<br/>of AE registration procedure
CSE ->> WS server: 10) Response primitive
Note over WS server: 11) WebSocket Binding
WS server ->> WS client: 12) Websocket message
Note over WS client: 13) Unpacking response primitive
WS client ->> ADN-AE: 14) Response primitive
Note over ADN-AE, CSE: 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 <a href="#_ref_1">[1]</a>) under which the registrar CSE can be reached with WebSocket binding.
1. The WebSocket client opens handshake to the server with subprotocol name oneM2M.json following IETF RFC 6455 <a href="#_ref_1">[1]</a>.
2. The WebSocket client opens handshake to the server with subprotocol name oneM2M.json following IETF RFC 6455 <a href="#_ref_1">[1]</a>.
If the server can be reached under the WebSocket URI ws://example.net:9000/, the client handshake may look as follows:
```http
GET / HTTP/1.1
Host: mncse1234.net:9000
......@@ -168,7 +186,7 @@ If the server can be reached under the WebSocket URI ws://example.net:9000/, the
Sec-WebSocket-Version: 13
```
1. The WebSocket server replies with a handshake to the client. In the successful case, the status-line of this HTTP response may look as follow (note that text shown in brackets [...] is not sent explicitely):
3. The WebSocket server replies with a handshake to the client. In the successful case, the status-line of this HTTP response may look as follow (note that text shown in brackets [...] is not sent explicitely):
```http
[Request-Version:] HTTP/1.1
......@@ -180,7 +198,7 @@ If the server can be reached under the WebSocket URI ws://example.net:9000/, the
Sec-WebSocket-Accept: FuSSKANnI7C/6/FrPMt70mfBY8E=
```
1. The ADN-AE issue a registration request primitive. The request primitive may e.g. look as follows as JSON-serialized representation (note that only mandatory parameters of the request primitive are shown in this example; the message may include any optional primitive parameters in addition, e.g. "fr"):
4. The ADN-AE issue a registration request primitive. The request primitive may e.g. look as follows as JSON-serialized representation (note that only mandatory parameters of the request primitive are shown in this example; the message may include any optional primitive parameters in addition, e.g. "fr"):
```json
{
......@@ -197,17 +215,17 @@ If the server can be reached under the WebSocket URI ws://example.net:9000/, the
}
```
1. WebSocket Binding process, which transforms a single oneM2M primitive into one or more data frames of the WebSocket Framing protocol, as specified in IETF RFC 6455 <a href="#_ref_1">[1]</a>. When transmitting a JSON-serialized primitive in utf-8 text format, the 4-bit opcode in the WebSocket Base Framing Protocol of the first message fragment will be set to x1 ("text frame").
1. The WebSocket message (consisting of one or more frames) shall be sent to the WS server.
1. The original request primitive shall be unpacked from the WebSocket message by the WS server.
1. The request primitive is delivered to the MN-CSE.
1. The MN-CSE performs the receiver side operations of AE registration as specified in oneM2M TS-0001 <a href="#_ref_2">[2]</a>.
1. The response primitive is issued to the WebSocket server.
1. WebSocket binding process for the response primitive is performed.
1. The WebSocket message (consisting of one or more frames) is sent to the client.
1. The response primitive is unpacked.
1. The response primitive is to the ADN-AE.
1. After successful completion of AE registration any other CRUDN requests and response primitives can be exchanged over the existing WebSocket connection in both directions. If the ADN-AE has no other requests to send, the WebSocket connection may be closed temporarily. When the WebSocket connection is closed after registration and reopened later again, the registration procedure as outlined in steps 4 to 14 is omitted. In this case any non-registration request primitives can be sent directly.
5. WebSocket Binding process, which transforms a single oneM2M primitive into one or more data frames of the WebSocket Framing protocol, as specified in IETF RFC 6455 <a href="#_ref_1">[1]</a>. When transmitting a JSON-serialized primitive in utf-8 text format, the 4-bit opcode in the WebSocket Base Framing Protocol of the first message fragment will be set to x1 ("text frame").
6. The WebSocket message (consisting of one or more frames) shall be sent to the WS server.
7. The original request primitive shall be unpacked from the WebSocket message by the WS server.
8. The request primitive is delivered to the MN-CSE.
9. The MN-CSE performs the receiver side operations of AE registration as specified in oneM2M TS-0001 <a href="#_ref_2">[2]</a>.
10. The response primitive is issued to the WebSocket server.
11. WebSocket binding process for the response primitive is performed.
12. The WebSocket message (consisting of one or more frames) is sent to the client.
13. The response primitive is unpacked.
14. The response primitive is to the ADN-AE.
15. After successful completion of AE registration any other CRUDN requests and response primitives can be exchanged over the existing WebSocket connection in both directions. If the ADN-AE has no other requests to send, the WebSocket connection may be closed temporarily. When the WebSocket connection is closed after registration and reopened later again, the registration procedure as outlined in steps 4 to 14 is omitted. In this case any non-registration request primitives can be sent directly.
# 6 Protocol Binding
......@@ -233,7 +251,7 @@ 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 &lt;CSEBase> and in the &lt;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 <a href="#_ref_1">[1]</a> 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 &lt;CSEBase> or &lt;remoteCSE> resources associated with entities supporting a WebSocket server are the following:
By default, the WebSocket Protocol <a href="#_ref_1">[1]</a> 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 of &lt;CSEBase>, &lt;AE> or &lt;remoteCSE> resources associated with entities supporting a WebSocket server are the following:
- ws://ws-server.example.com:80
......@@ -241,8 +259,6 @@ By default, the WebSocket Protocol <a href="#_ref_1">[1]</a> uses port 80 for re
- 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
......@@ -261,7 +277,7 @@ 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 <a href="#_ref_5">[5]</a>.
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 <a href="#_ref_5">[5]</a>.
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.
......@@ -345,7 +361,7 @@ The oneM2M Service Layer Protocol consists of the exchange of serialized represe
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**<a name="table_6.2.2.91"></a>
**Table 6.2.2.9-1: Applicable Subprotocol names**
|Serialization Format |Subprotocol Name |WS opcode |Notes |
|-|-|-|-|
......@@ -353,6 +369,17 @@ Table 6.2.2.9-1 lists the serialization formats, associated subprotocols names a
|XML |oneM2M.xml |x1 ("text frame") |See clause 8.3 in oneM2M TS-0004 <a href="#_ref_5">[5]</a> |
|CBOR |oneM2M.cbor |x2 ("binary frame") |See clause 8.5 in oneM2M TS-0004 <a href="#_ref_5">[5]</a> |
#### 6.2.2.10 X-M2M-Origin header
The WebSocket server needs to associate a connection with an originator in order to use that connection for sending requests to the client. A registree may open a WebSocket connection without immediately sending a request, but without a request the registrar cannot determine the associated originator and the connection remains unassociated. For this the registree must provide additional information in the WebSocket client handshake.
Except in case of the AE registration procedure the client must include the additional `X-M2M-Origin` header field with the *from* request attribute (the request's originator). The registrar must then associate the connection with the provided originator.
For each originator only one associated WebSocket connection must be kept open by the registrar. If the registrar receives a new WebSocket handshake with an originator in the `X-M2M-Origin` header field for which an already existing established WebSocket connection exists, then the registrar must close the previous existing WebSocket connection.
If, after the WebSocket connection without a provided `X-M2M-Orgin` header is established, the registrar receives a request over this WebSocket connection and the request is not an AE registration request, then the registrar must return a response with the response status code **ORIGINATOR HAS NO PRIVILEGE**.
If, after the WebSocket connection with a provided `X-M2M-Origin` Header is established, the registrar receives a request over this WebSocket connection and the request has a value in the *from* request attribute that is different from the value of the `X-M2M-Orgin` header, and the registree is not a CSE, then the registrar must return a response with the response status code **ORIGINATOR HAS NO PRIVILEGE**.
### 6.2.3 Server handshake format
......@@ -414,12 +441,14 @@ Compliant with section 7 of IETF RFC 6455 <a href="#_ref_1">[1]</a> a WebSocket
WebSocket connections should be kept open for as long as possible considering any given constraints due to communication policies and power saving requirements. Unless communication policies enforce the closing of network access, it is left to implementation to decide when exactly the closing of a WebSocket shall be triggered.
In case that the registrar established a short-term WebSocket connection to a registree it may close the connection after a request / response exchange.
## 6.4 Registration procedure
A oneM2M entity (AE or CSE) not yet registered to its registrar CSE needs to be preconfigured with various parameters as specified in oneM2M TS-0001 <a href="#_ref_2">[2]</a> and oneM2M TS-0003 <a href="#_ref_4">[4]</a> in order to be able to send the registration request primitive (i.e. create _&lt;AE>_ or create _&lt;remoteCSE>_ request primitive). To establish a WebSocket connection, the WebSocket client shall be configured with an applicable point of access of its registrar CSE which includes FQDN or IP address and the port number.
After the Registration procedure has been successfully completed, the WebSocket Server (e.g. Registrar CSE for WebSocket Client) shall enable routing of any incoming oneM2M primitives to this registree.
After the Registration procedure has been successfully completed, the WebSocket Server (e.g. the registrar CSE) shall associate the WebSocket connection with the registree and enable routing of any incoming oneM2M primitives to this registree.
Before the Registration procedure is successfully completed, any incoming oneM2M primitives to the WebClient shall be rejected by the Receiver (e.g. registrar CSE).
......@@ -429,11 +458,16 @@ Closing of the WebSocket connection after registration does not impact the regis
## 6.5 Handling of Non-Registration Request
Registered entities (AE and CSE) are allowed to send and receive non-registration request primitives. A WebSocket connection should support any of the transfer modes defined in clause 8.2 of oneM2M TS-0001 <a href="#_ref_2">[2]</a>, i.e. blocking requests, and non-blocking requests for both synchronous and asynchronous cases.
When sending blocking requests, the WebSocket connection shall not be closed before the response is received, or before any configured timeout period has expired.
When sending blocking requests, the WebSocket connection shall not be closed by the registrar before the response is received, or before any configured timeout period has expired.
When sending non-blocking requests, the WebSocket connection shall not be closed by the registrar before the acknowledgment response is received, or before any configured timeout period has expired. If the entities' communication policies and power saving requirements allow, the connection should be kept open at least until an ongoing procedure has fully completed, i.e. requesting of the result in synchronous mode or completion of Notify procedure in asynchronous mode.
When sending non-blocking requests, the WebSocket connection shall not be closed before the acknowledgment response is received, or before any configured timeout period has expired. If the entities' communication policies and power saving requirements allow, the connection should be kept open at least until an ongoing procedure has fully completed, i.e. requesting of the result in synchronous mode or completion of Notify procedure in asynchronous mode.
If no associated WebSocket connection between a registree and a registrar exists when a request primitive for this registree becomes available at the registrar's side and the procedure for a *request reachable* target do apply, then the procedure described in TS-0004 [TODO], clause 7.3.3.9.1, shall be followed with the following additions:
If no WebSocket connection with a client exists when a Notify request primitive for this client becomes available at the server side, it should be stored and sent when the WebSocket connection is opened again by the client.
- If the processed *pointOfAccess* address is a WebSocket URL with the value *ws://default* and there is an established WebSocket connection between the registree and the registrar, then the registrar will handle the request and response via the established WebSocket connection. If there is no established WebSocket connection, then this URI is skipped and the iteration of the *pointOfAccess* attribute continues.
- If the process *pointOfAccess* address is a WebSocket URL other than the value *ws://default* then the registrar establishes a new WebSocket connection with the WebSocket server at that URL, if not already established, and, on success, handles the request and response via this WebSocket connection. After this the registrar may close the WebSocket connection.
In other words, a WebSocket URL address in the *pointOfContact* attribute with a value of *ws://default* means that a request reachable registree can only be reached via the WebSocket binding through an established WebSocket connection. If the *pointOfContact* attribute contains a WebSocket URL address other than *ws://default* then this means that a WebSocket server is supported by the registree and it can be reached by establishing a new WebSocket by the registrar.
## 6.6 Use of proxy servers
......@@ -459,7 +493,28 @@ In special deployment scenarios, e.g. when the communicating oneM2M entities usi
## A.1 AE Registration and creation of a container child resource
Figure A.1-1 illustrates a message flow for registration of an ADN-AE to an IN-CSE as described in clause 7.3.5.2.1 of oneM2M TS-0004 <a href="#_ref_5">[5]</a> with WebSocket mapping and subsequent creation of a &lt;container> child resource.
![Message flow for registration of an ADN-AE to an IN-CSE](media/MessageFlowAERegistration.png)
```mermaid
%%{init: { 'sequence': {'mirrorActors': false, 'actorFontSize': 2, 'noteFontSize':10} } }%%
sequenceDiagram
Participant ADNAE1 as ADN-AE1
Participant ADNAE2 as ADN-AE2
Participant MNAE as MN-AE
Participant MNCSE as MN-CSE
Participant INCSE as IN-CSE
Participant INAE as IN-AE
MNAE ->> MNCSE: 1) Group resource<br />creation for updating<br />and retrieval of the state<br />of a group of lights
Note right of MNCSE: Group resource is created<br />with a specific access<br />control policy under MN-CSE
ADNAE1 ->> MNCSE: 2-1) Container resource<br />creation of light_1
ADNAE2 ->> MNCSE: 2-2) Container resource<br />creation of light_2
Note right of MNCSE: Container resources are<br />created with a specific access<br />control policy under MN-CSE
ADNAE1 ->> MNCSE: 3-1) ContentInstance<br />resource creation<br />under container of light_1
ADNAE2 ->> MNCSE: 3-2) ContentInstance<br />resource creation<br />under container of light_2
Note right of MNCSE: ContentInstance resources are<br />created under the containers<br />in MN-CSE
ADNAE1 ->> MNCSE: 4-1) Subscription resource<br />creation to container of light_1
ADNAE2 ->> MNCSE: 4-2) Subscription resource<br />creation to container of light_2
Note right of MNCSE: Subscription resources to<br />containers in MN-CSE are<br />created for monitoring<br />contentInstance updates
```
**Figure A.1-1: Message flow for registration of an ADN-AE to an IN-CSE**
......@@ -546,6 +601,8 @@ The message flow may look as follows:
> NOTE: JSON serialized primitives are not encapsulated under member names "m2m:rqp" and "m2m:rsp" as in XML serialized representations, which allows differentiation between request and response primitives (see clause 8.4 of TS-0004 <a href="#_ref_5">[5]</a>). JSON serialized primitives can be differentiated by the presence of mandatory members such as "op" in request primitives (see step 4) above), and "rsc" in response primitives.
The above JSON object is mapped by the WS server into a data frame of the WebSocket Framing protocol in utf-8 text format, the 4-bit opcode in the WebSocket Base Framing Protocol of the first message fragment is set to x1 ("text frame").
The WebSocket connection is associate with the originator *S_SAH25*.
1. The AE sends in textual JSON serialized format the following request primitive to create a &lt;container> resource as child resource of the &lt;AE> created in Step 5:
``` json
......
media/WebsocketExampleScenario.png

53.4 KiB | W: 0px | H: 0px

media/WebsocketExampleScenario.png

50.4 KiB | W: 0px | H: 0px

media/WebsocketExampleScenario.png
media/WebsocketExampleScenario.png
media/WebsocketExampleScenario.png
media/WebsocketExampleScenario.png
  • 2-up
  • Swipe
  • Onion skin
This diff is collapsed.