oneM2M Service Layer Protocol Version Handling Group Name: PRO WG Source: Qualcomm Inc., Wolfgang Granzow, Nobu Uchida, Josef Blanz Meeting Date: TP#30, 2017-07-11 Agenda Item: Joint ARC/PRO/SEC

History of discussions Version handling is a really long-standing Action Item … Previous inputs for discussion and proposed solutions: ARC-2014-1592-REST_API_versioning (LAAS-CNRS), presented at TP#13 PRO-2014-0524-Versioning_Solution (Fujitsu), presented at PRO#13.2 PRO-2014-0597R02-CR_API_version_info (Fujitsu), CR to TS-0004v0_8_0 noted at PRO#14.1 ARC-2017-006 (QCOM) Presented as PRO-2016-0297 at TP#24, discussed at ARC/PRO#26.1 telco (2017-01-04) PRO-2017-0028R01 (QCOM) discussed in joint ARC/PRO at TP#27

Version Handling in oneM2M Entity A (Registree) Entity B (Registrar) System Management / Configuration oneM2M Application/SL Rxy parameters AE or CSE originator and receiver processing serialization Primitives protocol selection CoAP Binding HTTP Binding MQTT Binding WS Binding request SL version (WS only) CoAP HTTP MQTT WS V1 V1.1 V3.1.1 V13 response cipher suite(s), other params. DTLS TLS V1.2 V1.2 UDP TCP IP version/ address IP (IPv4, IPv6) setup IP connectivity ../LC/MAC/PHY

Notion of oneM2M Version oneM2M Application / Common Service Layer protocol version = “Release Version” of Mca or Mcc, e.g. R1, R2, R2A, R3 an indicator which identifies conformance with a specific set of requirements laid out in that version’s corresponding set of specifications “Release Version” is not equal to the version number of specifications The mapping between oneM2M “Release Version” and specification numbers/version needs to be defined (“oneM2M release control document”), but this is out of scope of this presentation

Notion of oneM2M Version App / SL Version needs to cover following features: Behavior of primitive processing at the originator and receiver Representation of a primitive “Control“ primitive parameters and their (XSD-) permitted values “Content” primitive parameter Global Elements permitted to appear in the primitive Content Core resource types defined in „m2m:“ namespace Specific resource types defined in other namespaces (e.g. „hd:“, „dcfg:“, „sec:“) Serialization formats of primitive parameters, including Content Binding scheme: mapping of primitive parameters to/from CoAP, HTTP, MQTT or WebSocket (WS)

Versions of protocols below oneM2M SL Application data transfer protocols: All protocols below oneM2M SL use the same fixed version for all current oneM2M Releases Version is indicated explicitly in every request and response for CoAP and HTTP MQTT: indication of version (“3”) used by a client in CONNECT message sent to the server. Server may refuse connection request indicating “unacceptable protocol version” in CONNACK response WS: HTTP/1.1 or higher used in opening handshake (negotiable), WebSocket version 13 must be used, version negotiable in future WS versions, no explicit indication in WS frames

Version of protocol using WebSocket WS: Allows negotiation of upper application protocol, including version and serialization format per WS connection Sec-WebSocket-Protocol: oneM2M.R2.0.json, oneM2M.R2.0.xml (NOTE: format may need to be changed when Release/Version scheme is fixed) This is not applicable to CoAP and HTTP, as these protocols have no concept of a session or connection These protocols may use different UDP or TCP port numbers to differentiate different applications using it

Versions of protocols below oneM2M SL DTLS and TLS Fixed versions v1.2 currently used Version is on principle negotiable in the handshake This feature may be used for future oneM2M releases supporting (D)TLS v1.3 UDP and TCP Have no versions; TCP has optional negotiable extensions IP IPv4 and IPv6, to be selected/configured at network connection configuration stage

SL Version indication or negotiation When? Each request/response transaction? At connection establishment? E.g. WS allows negotiation in opening handshake; then no version info in request/response primitive itself required At registration? SL version supported by registree and registrar is known to these two entities only May cause issues when forwarding primitives in MNs

SL Version indication How? Additional primitive parameter in every request and response New parameter needs to be mapped by binding protocol for HTTP and CoAP Resolves issues when forwarding primitives “Content-Type” header could be used for CoAP and HTTP By provisioning: Version supported by registrar provisioned to registree, as separate parameter, or as part of PoA parameter By indication in registration phase Registree indicates its supported release as part of <AE> or <remoteCSE> resource Release supported by registrar visible to registree in <CSEbase> resource of the registrar

„Levels“ of inter-release interworking No interworking between release versions All entities up to some level (e.g. IN-CSE) comply to the same release version An MN or IN-CSE higher up in the hierarchical topology of nodes may support “perfect” conversion to higher version if supported by upper level entity Higher release entities interwork with subordinate nodes of older releases (i.e. backward compatibility) This seems feasible if both, primitives and resource representations would be maintained strictly backward compatible This is not guaranteed between oneM2M R1 and R2 but can probably be ensured from some version R2.x into R3 Requires some extra “down-conversion” processing of response messages; notification request and response messages should be forward and backward compatible Entities of any release interwork with each other E.g. any unknown primitive parameters and elements of Content are ignored Requires forward and backward compatible primitives and resource representations. Doesn’t seem feasible

Requirements to support levels A) and B) Registrar should know the release version intended to be used by it’s registree(s) This information can be exchanged in the registration procedure The used release version is part of the context information between registree and registrar and therefore does not need to be exchanged with every request and response Suggested procedure: Registree includes its supported release in <AE> or <remoteCSE> in registration request message (i.e. create <AE> or create <remoteCSE> Registrar indicates its release in the <CSEBase> Registrar may explicitly reject the registration request if release versions don’t match. Successful registration response ensures the registree of matching release versions Release version in <CSEBase>, <AE> and <remoteCSE> could be indicated in reserved labels (instead of defining new attributes, to keep resource type compatibility)

Differences between Interwork levels A) and B) For interwork level A), registration is rejected if the release versions supported by Registree and Registrar differ For interwork level B), the registrar accepts registration of a registree supporting a „backward compatible“ (BC) release Support of B) has issues in following scenarios Forwarding of primitives Content primitive parameters returned from a higher release entity to the originator Node communicating with lower release entity should apply some conversion, even for forwarding of response primitives Aggregation of responses originating from Entities with mixed, possibly lower or higher SL versions Reception of Notify request messages from higher SL version entity

Potential Issues with B) op R2 Hosting CSE R3 Hosting CSE R2 orig C  No issue for BC resource R R3 entity should not add attributes unknown in R2 U No issue D R3 Unknown attributes to be rejected by hosting CSE BC = Backward Compatible

Possible solution for exchange of release version Registree indicates its own supported release version in <AE> or <remoteCSE>, e.g. label attribute Registree mandated to indicate the same or a lower version After successful registration, Registree can read release version supported by the registrar in <CSEBase>, e. g. label attribute For unsuccessful registration due to release version mismatch, the registrar should send a respective new RSC and could also include its supported release version in the Content para,meter of the response Any resource representation includes its version in the same way (i.e. in label) Release version vs. XSD version? Two labels, e.g. XSDv2_10 and Rel2.a

Proposal (1) Define reserved label attribute values to indicate Release versions Use key:value format Define reserved keys and values Supported release: e.g. REL:2A, REL:3 (values of key & label to be defined) XSD-version of resource representation on hosting CSE: e.g. XSD:2.12 Mandate that Registree indicates its release version label when creating <AE> and <remoteCSE> resources labels attribute of <CSEBase> indicates Release Version supported by a CSE labels attribute of <AE> indicates Release Version by an AE registree at its registrar labels attribute of <remoteCSE> indicates Release Version supported by a CSE registree to its registrar All other resource types which are created by entities other than the hosting CSE could also include release version label to indicate the version of the creator of the resource

Proposal (2) XSD representation label shall be added by hosting CSE Registrar must choose XSD version compatible with its own release version as well as the XSD associated with the release supported by the registree E.g. <remoteCSE> resource in registree and registrar may have different XSD version labels, but the higher version shall be „compatible“ with the lower version Compatible release versions must be specified in the specs, i.e. TS-0004 Registrar shall reject registration request of incompatible release New status code to be defined Update of labels attribute Release version should not change as long as there is no update of the supported release e.g. due to SW upgrade SW upgrade to a newer release of an entity shall trigger re-registration The respective elements of the labels attribute should be maintained by the hosting CSE as read-only information

Proposal (3) Initially, ensure that „inter-release interworking Level A)“ works appropriately Minor update of registration procedure required: Registrar shall check labels indicated by the registree Accept registration request for matching release version Reject registration request for non-matching release versions , with RSC to be defined More detailed work is needed to clarify under which conditions Level B) is feasible clarify how to deal with the issues listed on slides 13 and 14 above Also conformance testing procedures for inter-release interworking procedures would need to be defined