Lightweight Machine to Machine Technical Specification: Core

Candidate Version: 1.1 - 12 Jun 2018

Open Mobile Alliance

OMA-TS-LightweightM2M_Core-V1_1-20180612-C

master: 18 Jun 2018 19:20:00 rev: 11d8925

Unless this document is clearly designated as an approved specification, this document is a work in process, is not an approved Open Mobile Alliance™ specification, and is subject to revision or removal without notice.

You may use this document or any part of the document for internal or educational purposes only, provided you do not modify, edit or take out of context the information in this document in any manner. Information contained in this document may be used, at your sole risk, for any purposes. You may not use this document in any other manner without the prior written permission of the Open Mobile Alliance. The Open Mobile Alliance authorizes you to copy this document, provided that you retain all copyright and other proprietary notices contained in the original materials on any copies of the materials and that you comply strictly with these terms. This copyright permission does not constitute an endorsement of the products or services. The Open Mobile Alliance assumes no responsibility for errors or omissions in this document.

Each Open Mobile Alliance member has agreed to use reasonable endeavors to inform the Open Mobile Alliance in a timely manner of Essential IPR as it becomes aware that the Essential IPR is related to the prepared or published specification. However, the members do not have an obligation to conduct IPR searches. The declared Essential IPR is publicly available to members and non-members of the Open Mobile Alliance and may be found on the “OMA IPR Declarations” list at https://www.omaspecworks.org/about/intellectual-property-rights/. The Open Mobile Alliance has not conducted an independent IPR review of this document and the information contained herein, and makes no representations or warranties regarding third party IPR, including without limitation patents, copyrights or trade secret rights. This document may contain inventions for which you must obtain licenses from third parties before making, using or selling the inventions. Defined terms above are set forth in the schedule to the Open Mobile Alliance Application Form.

NO REPRESENTATIONS OR WARRANTIES (WHETHER EXPRESS OR IMPLIED) ARE MADE BY THE OPEN MOBILE ALLIANCE OR ANY OPEN MOBILE ALLIANCE MEMBER OR ITS AFFILIATES REGARDING ANY OF THE IPR’S REPRESENTED ON THE “OMA IPR DECLARATIONS” LIST, INCLUDING, BUT NOT LIMITED TO THE ACCURACY, COMPLETENESS, VALIDITY OR RELEVANCE OF THE INFORMATION OR WHETHER OR NOT SUCH RIGHTS ARE ESSENTIAL OR NON-ESSENTIAL.

THE OPEN MOBILE ALLIANCE IS NOT LIABLE FOR AND HEREBY DISCLAIMS ANY DIRECT, INDIRECT, PUNITIVE, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES ARISING OUT OF OR IN CONNECTION WITH THE USE OF DOCUMENTS AND THE INFORMATION CONTAINED IN THE DOCUMENTS.

© 2018 Open Mobile Alliance All Rights Reserved. Used with the permission of the Open Mobile Alliance under the terms set forth above.

1. Scope

This document, the LwM2M CORE technical specification, describes the LwM2M messaging layer. The LwM2M TRANSPORT specification [LwM2M-TRANSPORT], a companion specification, details the mapping of the messaging layer to selected transports. The separation between transport and messaging layer improves readability and simplify extending LwM2M to further transports in the future. The LwM2M messaging layer uses a RESTful design with several interfaces and a simple data model.

1.1. LwM2M version 1.1

This specification defines version 1.1 of the LwM2M protocol with the following new features:

• Enhancement of the LwM2M bootstrapping capabilities allowing for incremental upgrades.

• Improved support for Public Key Infrastructure (PKI) deployments.

• Introduction of enhanced registration sequence mechanisms by the LwM2M Client to LwM2M Server(s).

• Support for LwM2M over TCP/TLS to better support firewall and NAT traversal.

• Support for application layer security for LwM2M based on OSCORE

• Better support of LwM2M over Low Power WANs, including 3GPP CIoT & LoRaWAN.

• Extended LwM2M commands to enable Resource Instance level access.

• Performance improvement for retrieving and updating Resources of multiple objects.

• Support for JSON using SenML with CBOR serialization for compressed payload with highly efficient transmission.

• Addition of new data types.

For additional transport & security enhancements in LwM2M v1.1 please refer to [LwM2M-TRANSPORT].

1.2. LwM2M version 1.0

This document augments LwM2M version 1.0. Version 1.1 is backwards compatible to v1.0 with respect to mandatory features. LwM2M v1.0 offers the following features:

• Simple resource model with the core set of objects and resources defined in this specification. The full list of registered objects can be found at OMNA.

• Operations for creation, update, deletion, and retrieval of resources.

• Asynchronous notifications of resource changes.

• Support for several serialization formats, namely TLV, JSON, Plain Text and binary data formats and the core set of LightweightM2M Objects.

• UDP and SMS transport support.

• Communication security based on the DTLS protocol supporting different types of credentials.

• Queue Mode offers functionality for a LwM2M Client to inform the LwM2M Server that it may be disconnected for an extended period and when it becomes reachable again.

• Support for use of multiple LwM2M Servers.

• Provisioning of security credentials and access control lists by a dedicated LwM2M bootstrap-server.

2. References

2.1. Normative References

2.2. Informative References

3. Terminology and Conventions

3.1. Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

All sections and appendixes, except "Scope" and "Introduction", are normative, unless they are explicitly indicated to be informative.

3.2. Definitions

Note that wherever there is a LwM2M Security Object Instance there is potentially an associated LwM2M OSCORE Object Instance. Kindly consult [OMADICT] for more definitions used in this document.

3.3. Abbreviations

4. Introduction

This enabler defines the application layer communication protocol between a LwM2M Server and a LwM2M Client as well as between the LwM2M Bootstrap-Server and the LwM2M Client. The LwM2M Device includes a LwM2M Client component. The OMA Lightweight M2M enabler includes device management and service enablement for LwM2M Devices. The target LwM2M Devices for this enabler are mainly resource constrained devices. Therefore, this enabler makes use of lightweight and compact protocol mechanisms, as well as an efficient resource data model.

Four interfaces are designed between the three entities, as shown in the architecutre in Figure: 4.-1 The overall architecture of the LwM2M Enabler:

• Bootstrap

• Client Registration

• Device Management and Service Enablement

• Information Reporting

4.1. Version 1.1

Version 1.1 of LwM2M introduced the following objects, which are part of core specification:

21. OSCORE Object

Version 1.1 of LwM2M modified the following objects, which are part of core specification:

0. Security Object

1. Server Object

4.2. Version 1.0

Version 1.0 of LwM2M introduced the following objects, which are part of core specification:

0. Security Object

1. Server Object

2. Access Control Object

3. Device Object

4. Connectivity Monitoring Object

5. Firmware Update Object

6. Location Object

7. Connectivity Statistics Object

5. Fundamental Considerations

5.1. Attributes

5.1.1. Attributes Definitions and Rules

Attributes are metadata which can be attached to an Object, an Object Instance, or a Resource. The value of an Attribute is LwM2M Server specific. These attributes can fulfil various roles, from carrying information only (e.g. Discover) to carrying parameters for setting up certain actions on the LwM2M Client (e.g. Notifications).

Attributes attached to Objects, Object Instances, Resources are respectively named O-Attribute, OI-Attribute, R-Attribute.

These Attributes MAY be carried in the message payload of Registration and Discover operations; they also MAY be updated - when writable - through the "Write-Attributes" operation.

Regardless to the LwM2M entity a given Attribute is attached to, the value of such an Attribute can be assigned at various levels: Object, Object Instance, Resource levels. Additionally, precedence rules apply when the same Attribute receives a value at different levels.

The rules below govern the usage of LwM2M Attributes,

• The value of an O-Attribute MAY only be set at the Object level.

• The value of an OI-Attribute MAY be set at the Object Instance level, and at the Object level.

  precedence rules:

  • Rule 1: When set at both levels, the value of the OI-Attribute set at Object Instance level will prevail.
  • Rule 2: When the Attribute value is set at the Object level, the scope of the OI-Attribute value extends to all the Instances of that Object, as long as the Rule 1 is respected.

• An R-Attribute MAY be set at 4 different levels: the Resource Instance level, the Resource level, the Object Instance level and the Object level. Typically, an R-Attribute attached to a Multiple-Instance resource, can be set with an individual value to any Instance of such a Multiple-Instance Resource.

  precedence rules:

  • Rule 3: When set at the Resource level, the value of an R-Attribute prevails for that Resource whatever a value for this R-Attribute is also specified at an upper level (Object or Object Instance level).
    • Rule 3a: in the particular case this Resource is a Multiple-Instance Resource, the value of the R-Attribute set at the Resource Instance level will prevail over the value of the same Attribute set at the Resource level.
  • Rule 4: When set at the Object Instance level, the scope of an R-Attribute value extends to all the Resources of that Object Instance as long as the Rule 3 is respected.
  • Rule 5: When set at the Object level, the scope of an R-Attribute value extends to all the resources of any Instance of that Object, as long as the Rule 4 is respected.

Some Attributes MAY be exposed to the LwM2M Server in the payload response to a "Discover" command (Section 6.3.2. Discover).

The value of some Attributes MAY be changed by the LwM2M Server in using the "Write-Attributes" command (Section 6.3.4. Write-Attributes ); which Attribute are concerned are marked as "W" (writable) in the table of the next section.

Note: A payload response to a "Discover" command is a list of application/link-format CoRE Links [RFC6690] which will include the LwM2M Attributes.

5.1.2. Attributes Classification

<PROPERTIES> Class Attributes

The role of these Attributes is to provide metadata which may communicate helpful information to the LwM2M Server for example easing data management.

The LwM2M Server and LwM2M Client SHOULD support Table: 5.1.2.-1 Class Attributes, except when specifically mentioned as not required.

<NOTIFICATION> Class Attributes

The role of these R-Attributes is to provide parameters to the "Notify" operation; any readable Resource can have such R-attributes.

Note : for readability reason in the remaining part of this section, the term "Resource" will be used to designate either a Single-Instance Resource or an Instance of a Multiple-Instance Resource, according to the nature of the considered Resource (i.e. Single- or Multiple-Instance Resource).

In the message sent by a LwM2M Client in response to an "Observe" operation, the current Resource value is reported; this event can be considered as the initial notification.

Each time a Resource notification is sent, the "Minimum Period" and "Maximum Period" timers associated to this Resource are restarted.

Notification Conditions: the notification of a Resource value will be sent when:

• a valid Change Value Condition ("Greater Than", "Less Than", OR "Step") - if any is defined - AND the "Minimum Period" Timing Conditions are both fulfilled for that Resource OR
• the "Maximum Period" Timing Condition is fulfilled.

Additionally the following rules MUST be considered:

• a "Maximum Period" (pmax) applied to a Resource, that is smaller than "the Minimum Period" applied to the same Resource MUST be ignored for that Resource,
• Change Value Conditions are considered as "valid", if the 2 following rules related to the Attributes defined in the table below ("Greater Than", "Less Than", "Step") are respected:
  • ("lt" value < "gt" value)
  • ("lt" value + 2*"st" values <"gt" value)

When the "Change Value Conditions" Attributes are set in a single WRITE-ATTRIBUTES command, a coherency check of the 2 rules above MUST lead to reject that command if these rules are violated.

The "Minimum Evaluation Period" (epmin) and "Maximum Evaluation Period" (epmax) values can be used to configure the device to perform reporting evaluations. After the expiry of epmin, the device MAY immediately perform an evaluation per the "Notification Conditions" above. After the expiry of epmax, the device MUST perform an evaluation per the "Notification Conditions". If both the epmin and epmax attributes are defined, the epmin must be less than the epmax.

The LwM2M Server MUST support and LwM2M Client SHOULD support all the <NOTIFICATION> Class Attributes listed in Table: 5.1.2.-2 class Attributes.

Examples illustrating Attributes setting are provided in Section Device Management & Service Enablement Interface.

6. Interfaces

According to Figure: 4.-1 The overall architecture of the LwM2M Enabler there are four interfaces: 1) Bootstrap, 2) Client Registration, 3) Device Management and Service Enablement, and 4) Information Reporting. The operations for the four interfaces can be classified into uplink operations and downlink operations. The operations for each interface are defined in this section, and then mapped to protocol mechanisms in the LwM2M Transport specification [LwM2M-TRANSPORT].

Figure: 6.-1 Bootstrap Interface shows the operation model for the "Bootstrap" interface. For this interface, the operations are an uplink operation named "Bootstrap-Request" and downlink operations named "Discover", "Write", "Read (restricted)","Delete" and "Bootstrap-Finish". These operations are used to initialize the needed Object(s) for the LwM2M Client to register with one or more LwM2M Server(s). Once a "Write" operation initiated on the "Bootstrap" interface by the LwM2M Server, the LwM2M Client MUST write the value included in the payload regardless of an existence of the targeting Object Instance(s) or Resource(s) and access rights. In the mode where the LwM2M Bootstrap-Server is addressing the Bootstrap Information to the LwM2M Client, the LwM2M Bootstrap-Server MUST inform the LwM2M Client when this transfer is over by sending a "Bootstrap-Finish" command.

In addition to the bootstrapping interface the required information for the LwM2M Client to function with LwM2M Server(s) may also be configured during manufacturing (so-called Factory Bootstrap) or via a smartcard (so-called Smartcard Bootstrap).

Figure: 6.-2 Client Registration shows the operation model for the interface "Client Registration". For this interface, the operations are uplink operations named "Registration", "Update" and "De-register".

Figure: 6.-3 Device Management and Service Enablement shows the operational model for the "Device Management and Service Enablement" interface. For this interface, the operations are downlink operations are "Read", "Create", "Delete", "Write", "Execute", "Write-Attributes", and "Discover". These operations are used to interact with Resources, Resource Instances, Objects, Object Instances and/or their attributes exposed by the LwM2M Client. The "Read" operation is used to read the current values. The "Discover" operation is used to discover attributes and to discover which Resources are implemented in a certain Object. The "Write" operation is used to update values. The "Write-Attributes" operation is used to change attribute values. The "Execute" operation is used to initiate an action. The "Create" and "Delete" operations are used to create and delete Instances, respectively.

The "Device Management and Service Enablement" interface also contains an uplink operation called "Send". The "Send" operation is used by the LwM2M Client to send data to the LwM2M Server.

Figure: 6.-4 Information Reporting shows the operational model for the "Information Reporting" interface. For this interface, the operations are downlink operations are "Observe", and "Cancel Observation". The "Notify" is the uplink operation, which is used to send a new value of a Resource from the LwM2M Client to the LwM2M Server.

The relationship between operations and interfaces is listed in Table: 6.-1 Relationship of operations and interfaces.

6.1. Bootstrap Interface

The Bootstrap Interface is used to provision essential information into the LwM2M Client to enable the LwM2M Client to perform the "Register" operation with one or more LwM2M Servers.

There are four bootstrap modes supported by the LwM2M Enabler:

• Factory Bootstrap

• Bootstrap from Smartcard

• Client Initiated Bootstrap

• Server Initiated Bootstrap

The last two Bootstrap modes require the help of a LwM2M Bootstrap-Server to achieve the ultimate goal to connect a LwM2M Client to their LwM2M Server(s). As specified in Section 6.1.3.4. Server Initiated Bootstrap, the "Server Initiated Bootstrap" mode is a method to invoke the "Client Initiated Bootstrap" mode.

The LwM2M Client MUST support at least one bootstrap mode specified in the Bootstrap Interface.

The LwM2M Bootstrap-Server MUST support the "Client Initiated Bootstrap" mode specified in the Bootstrap Interface.

This section describes what information is conveyed across the Bootstrap Interface, where the LwM2M Client puts that information and how to provision the Bootstrap Information for each of these bootstrap modes. The LwM2M TRANSPORT specification [LwM2M-TRANSPORT] provides further security-relevant information concerning the bootstrap techniques.

6.1.1. LwM2M Bootstrap-Server

The LwM2M Bootstrap-Server is used to provision the LwM2M Client with the information required to contact the LwM2M Server(s).

In order for the LwM2M Client and the LwM2M Bootstrap-Server to establish a connection on the Bootstrap Interface, either in Client Initiated Bootstrap mode or in Server Initiated Bootstrap mode, the LwM2M Client MUST have a LwM2M Bootstrap-Server Account pre-provisioned.

Note: During the Bootstrap Phase the LwM2M Client MAY ignore requests and flush all pending responses not related to the Bootstrap sequence.

6.1.2. Bootstrap Information

This section specifies the information that needs to be configured for a LwM2M Client to connect to LwM2M Server(s) or to the LwM2M Bootstrap-Server. This Bootstrap Information can be available before performing the Bootstrap Sequence described in Section 6.1.4. Bootstrap Sequence or obtained as a result of the Bootstrap Sequence.

Bootstrap Information can be categorized into two types:

• LwM2M Server Bootstrap Information

• LwM2M Bootstrap-Server Bootstrap Information

The LwM2M Client MUST have the LwM2M Server Bootstrap Information after the bootstrap sequence specified in Section 6.1.4. Bootstrap Sequence. The LwM2M Server Bootstrap Information is used by the LwM2M Client to register and connect to the LwM2M Server.

The LwM2M Client SHOULD have the LwM2M Bootstrap-Server Bootstrap Information. The LwM2M Server Bootstrap Information MUST contain at least one LwM2M Server Account.

Note that according to the LwM2M Server Account definition, a usual LwM2M Server Account is composed of a Security Object Instance and a Server Object Instance which are paired by sharing (respectively in Resource 10 and Resource 0 of that Objects) the same Short Server ID; a Short Server ID being unique in the LwM2M Client. Note also that a Security Object Instance may potentially be associated to an OSCORE Object Instance by means of an Object Link (Resource 17 of the Security Object Instance).

The LwM2M Server Bootstrap Information MAY additionally contain further Object Instances (e.g. Access Control, Connectivity Monitoring Object).

The LwM2M Client MAY be configured to use one or more LwM2M Server Account(s).

The LwM2M Client MUST have at most one LwM2M Bootstrap-Server Account.

The LwM2M Bootstrap-Server Bootstrap Information is used by the LwM2M Client to contact the LwM2M Bootstrap-Server to get the LwM2M Server Bootstrap Information.

The LwM2M Bootstrap-Server Bootstrap Information MUST be a LwM2M Bootstrap-Server Account.

The LwM2M Client MUST have at least one LwM2M Server Account after completion of Bootstrap Sequence specified in Section 6.1.4. Bootstrap Sequence.

Please note that the LwM2M Client MUST accept Bootstrap Information sent via Bootstrap Interface without applying access control, as specified in Section 8.2. Authorization.

6.1.3. Bootstrap Modes

The following sub-section provide further information for the four Bootstrap modes.

6.1.3.1. Factory Bootstrap

In this mode, the LwM2M Client has been configured with the necessary bootstrap information prior to deployment of the device. The configured information may be the LwM2M Bootstrap-Server Bootstrap Information and/or the LwM2M Server Bootstrap Information.

6.1.3.2. Bootstrap from Smartcard

When the Device supports a Smartcard, the LwM2M Client MUST retrieve and process the bootstrap data contained in the Smartcard as described in Appendix G. When the bootstrap data retrieval is successful, the LwM2M Client MUST process the bootstrap data from the Smartcard and SHOULD apply the Bootstrap Information to its configuration to enhance security benefits.

Due to the sensitive nature of the Bootstrap Information, a secure channel SHOULD be established between the Smartcard and the LwM2M Device.

When such a secure channel is established between the Smartcard and the LwM2M Device, this secure channel MUST be based on [GLOBALPLATFORM] procedure, mainly described in Appendix H.

In this Bootstrap mode, the LwM2M Client MUST also ensure that the bootstrap data previously retrieved from the Smartcard is unchanged within the Smartcard. If bootstrap data is changed, and if the previous Bootstrap Information was applied from Smartcard, this previous Bootstrap Information MUST be disabled in the LwM2M Client and the LwM2M Client SHOULD apply the new Bootstrap Information from Smartcard to its configuration.

If the Smartcard is disabled (e.g. removing the Smartcard) then the Bootstrap Information created from the bootstrap data of the previous Smartcard MUST be deleted.

Checking for Smartcard change and disabling MUST be performed by the LwM2M Client, each time a "Register" or "Update" operation take place, with a LwM2M Server provisioned from Smartcard. As usual, the Bootstrap security rules (Section 6.1.5. Bootstrap Security) then apply.

NOTE: Bootstrap Information in Smartcard can be updated by using Smartcard OTA protocol as specified in [ETSI TS 102.225] / [ETSI TS 102 226] and extensions such as [3GPP TS 31.115] / [3GPP TS 31.116] and [3GPP2 C.S0078-0] / [3GPP2 C.S0079-0].

6.1.3.3. Client Initiated Bootstrap

The "Client Initiated Bootstrap" mode provides a mechanism for the LwM2M Client to retrieve Bootstrap Information from a LwM2M Bootstrap-Server. The "Client Initiated Bootstrap" mode requires a LwM2M Bootstrap-Server Account preloaded in the LwM2M Client.

At a minimum a LwM2M Client needs to have DTLS/TLS or OSCORE security credentials preploaded to authenticate to a LwM2M Bootstrap-Server.

Figure: 6.1.3.3.-1 Client Initiated Bootstrap depicts protocol exchange graphically.

Step #0: Bootstrap-Request to bootstrap URI

The LwM2M Client sends a "Bootstrap-Request" operation to LwM2M Bootstrap-Server URI, which has been pre-provisioned. When requesting the bootstrap, the LwM2M Client SHOULD send the LwM2M Client's "Endpoint Client Name" as a parameter to allow the LwM2M Bootstrap-Server to provision the proper bootstrap information for the LwM2M Client. The LwM2M Client MAY omit "Endpoint Client Name" if it is equal to the identifier utilized in the security protocol.

Step #1: Configure Bootstrap Information

The LwM2M Bootstrap-Server configures the LwM2M Client with the Bootstrap Information using the "Write" and/or "Delete" operations.

This Bootstrap mode MAY be used to configure some Resources of the Bootstrap Information in the LwM2M Client after initial bootstrap to update Bootstrap Information. In this case, all Bootstrap Information is OPTIONAL.

Step #2: Bootstrap-Finish

When the LwM2M Server has finished sending the Bootstrap Information to the LwM2M Client, the Server MUST send the "Bootstrap-Finish" operation to the Client to properly end this phase.

The bootstrap procedure failed when the LwM2M Client did not receive the "Bootstrap-Finish" operation after the EXCHANGE_LIFETIME time period expired. The EXCHANGE_LIFETIME parameter is defined in RFC 7252 [CoAP].

Step #3: Clean-up after successful Bootstrapping

Successful Bootstrapping means that the Bootstrap-Finish operation has been received by the LwM2M Client and the loaded configuration is considered consistent by the LwM2M Client. In this case the Bootstrap-Finish response code sent to the LwM2M Bootstrap-Server is 2.04 (Changed). If Bootstrapping was unsuccessful, the Bootstrap-Server Account MUST retain the values it had before the unsuccessful Bootstrapping sequence started and further statements below in Step #3 do not apply.

If the Bootstrap-Server Account Timeout Resource is instantiated in the Security Object Instance of the Bootstrap-Server, the LwM2M Client MUST purge the LwM2M Bootstrap-Server Account after the expiration time provided by the value of this Resource. If this Resource is not instantiated or its value is set to 0, the Bootstrap-Server Account lifetime is infinite (Section E.1 LwM2M Object: LwM2M Security).

High entropy keys that are unique per device SHOULD be used for the LwM2M Bootstrap-Server Account. In that case the LwM2M Bootstrap-Server Account SHOULD be kept after bootstrapping i.e. the Bootstrap-Server Account Timeout Resource may be set to 0, or may stay not instantiated.

In case the Bootstrap-Server Account has to be replaced, the replacement and the purge of the previous Bootstrap-Server Account MUST properly take place before the Client sends the Bootstrap-Finish response message back to the Bootstrap-Server; otherwise a "4.06 Not Acceptable" Response code MUST be returned, and the previous Bootstrap-Server Account is still the only one active.

Note: If the original LwM2M Bootstrap-Server Account is purged from the device, and a new LwM2M Bootstrap-Server Account has not been created, further adding or removing of LwM2M Server Accounts will no longer be possible. Furthermore, updating security credentials e.g. X.509 certificates will also no longer be possible.

6.1.3.4. Server Initiated Bootstrap

In this mode the decision to trigger a Bootstrap Sequence is made by an authorized LwM2M Server. The LwM2M Server triggers the LwM2M Client to enter the "Client Initiated Bootstrap" mode rather than initiating a different protocol for configuring the Bootstrap Information in the LwM2M Client.

The trigger mechanism is performed through the execution of the "Bootstrap-Request Trigger" Resource available from the related Server Object Instance. A connection between a LwM2M Client and a LwM2M Server must already exist to enter this "Server Initiated Bootstrap" mode.

Note: proprietary mechanisms can be used to cause a LwM2M Client to enter the standard "Client Initiated Bootstrap" mode, but that is outside the scope of this specification.

The figure below depicts the "Server Initiated Bootstrap" flow initiated by an authorized LwM2M Server.

6.1.4. Bootstrap Sequence

The LwM2M Client MUST respect step by step the procedural sequence specified below when attempting to bootstrap a LwM2M Device:

1. If the LwM2M Device has Smartcard, the LwM2M Client tries to obtain Bootstrap Information from the Smartcard using the Bootstrap from Smartcard mode. Any Server Initiated Bootstrap attempt MUST be ignored by the LwM2M Client until it has tried to bootstrap via Smartcard or Factory Bootstrap mode.

2. If the LwM2M Client is not configured using the Bootstrap from Smartcard mode, the LwM2M Client tries to obtain the Bootstrap Information by using Factory Bootstrap mode. Any Server Initiated Bootstrap attempt MUST be ignored by the LwM2M Client until it has tried to bootstrap via Smartcard or Factory Bootstrap mode.

3. If the LwM2M Client has any LwM2M Server Object Instances from the previous steps, the LwM2M Client tries to register to the LwM2M Server(s) configured in the LwM2M Server Object Instance(s).

4. If the LwM2M Client fails to register to all the LwM2M Servers or the Client doesn't have any LwM2M Server Object Instances, the LwM2M Client performs the Client Initiated Bootstrap.

5. A Server Initiated Bootstrap attempt (e.g. for updating a LwM2M Server Account) remains possible, but only if the LwM2M Client retains the corresponding LwM2M Bootstrap-Server Account.

6.1.5. Bootstrap Security

The information conveyed through the Bootstrap Interface is sensitive and requires that communication session, security mechanisms and/or keys MUST be different instances from the one that is used for the other LwM2M Interfaces.

If the LwM2M Client or the LwM2M Bootstrap-Server needs to convey Bootstrap Information across the Bootstrap Interface, the LwM2M Client or the LwM2M Bootstrap-Server MUST establish a new secure communication session.

If security materials (e.g. LwM2M Server URI, Security Mode, and Security Key), are changed in the LwM2M Client, the LwM2M Client MUST disconnect the existing communication session between the LwM2M Server and LwM2M Client and establish a new secure communication session between the LwM2M Server and LwM2M Client using the security mechanism and/or keys which have been configured by Bootstrap Interface.

6.1.6. Bootstrap and Configuration Consistency

When a Bootstrap Information is loaded in the LwM2M Client, any detected inconsistency MUST be reported in sending an error response code to the BOOTSTRAP-FINISH command.

As an example, during a Bootstrap phase, a Multi-Servers Configuration is loaded in a LwM2M Client with the associated Instances of the Access Control Object, while this particular LwM2M Client is not supporting the Access Control Object itself (Single Server context support only). In that case, the client is not able to find a satisfactory consistent configuration by itself, so that the Bootstrap sequence cannot be ended successfully.

On receipt of the error response code to the BOOTSTRAP-FINISH command, the Bootstrap-Server MAY take corrective actions before issuing a new BOOTSTRAP-FINISH command.

As specified in Section 6.1.3. Bootstrap Modes, the LwM2M Client MUST consider the Bootstrap procedure is failed when the LwM2M Client didn't receive a BOOTSTRAP-FINISH command in a certain period (EXCHANGE_LIFETIME).

6.1.7. Bootstrap Commands

The mapping to underlying transports is detailed in [LwM2M-TRANSPORT].

The Bootstrap Commands are used to help the Bootstrap-Server of setting a proper configuration in a LwM2M Client especially in the case of an incremental Bootstrap procedure for which a particular care must be observed to preserve the Client consistency (e.g. adding a new Server Account without breaking the Access Rights already in place in the targeted LwM2M Client).

6.1.7.1. BOOTSTRAP-REQUEST

The Bootstrap-Request operation is only performed to initiate the Bootstrap Sequence in the "Client Initiated Bootstrap" mode.

The Bootstrap-Request operation has the following parameter:

6.1.7.2. BOOTSTRAP-FINISH

The Bootstrap-Finish operation is performed to terminate the Bootstrap Sequence previously initiated in "Client Initiated Bootstrap" mode (or in "Server Initiated Bootstrap" mode by extension).

This command informs the LwM2M Client, that all the Bootstrap Information have been provided by the LwM2M Bootstrap-Server.

6.1.7.3. BOOTSTRAP DISCOVER

The "Discover" operation in Bootstrap Interface is different from the "Discover" operation in Device Management and Service Enablement interface.

The "Discover" operation on the Bootstrap Interface is used to discover which LwM2M Objects and Object Instances are supported by a certain LwM2M Client. In particular, the list of Security Object Instances (ID:0) is reported, while it is not accessible in Device Management and Service Enablement Interface. If OSCORE is supported on the client, a list of OSCORE Objects (ID:21) is also reported, since this is not reported in Device Management and Service Enablement Interface either. This operation is useful to clean-up or to update a LwM2M Client configuration (e.g. adding (removing) a LwM2M Server Account to (from) the LwM2M Client configuration).

The returned payload is a list of application/link-format CoRE Links [RFC6690] containing the LwM2M Enabler Version and for each targeted Object - in addition to the Object Version (see Section 7.2. Object Versioning and Table: 5.1.2.-1 Class Attributes - a sub-list of the Instances of such an Object Instance. In order to fully identify the Server Accounts supported by the Client, each element of the Instances list of the Security Object (Object ID:0) includes the associated Short Server ID and LwM2M Server URI in its parameters list while the elements of the Instances list of the Server Object (Object ID:1) also report the associated Short Server ID in their parameters list.

The Bootstrap-Server Security Object Instance doesn't include a Short Server ID in its parameter list (none is defined); therefore the LwM2M Server URI for the Bootstrap Server can also be omitted in such a parameters list.

In "Discover" command the targeted path '/' is accepted in place of the Object ID, for informing the Client to report all existing Object Instances.

The "Discover" operation has the following parameters:

For example:

• when the "Discover" operation targets an Object with Object ID of 0 (Security Object), the response to the operation could be:

  lwm2m="1.0",</0/0>;ssid=101;uri="coaps://server_1.example.com", </0/1/>, </0/2>;ssid=102;uri="coaps://server_2.example.com" with the meaning 3 LwM2M Servers are supported in that Client (that supports the LwM2M Enabler in version 1.0), while the Instance ID:1 of the Security Object ID:0 contains the credentials for the LwM2M Bootstrap-Server.

• when the "Discover" operation targets an Object with '/' the response to the operation could be:

  lwm2m="1.0",</0/0>;ssid=101;uri="coaps://server_1.example.com", </0/1>, </1/0/>;ssid=101, </3/0>,</5>,</4> with the meaning the Client is supporting (in LwM2M version 1.0) a Bootstrap-Server Account (/0/1), a Server Account (/0/0, /1/0) with a Short Server ID=101, A Device Object Instance (/3/0) and 2 other Objects which are not instantiated yet (Firmware Update /5, and Connectivity Monitory Object /4).

• when the "Discover" addresses a LwM2M Client supporting the LwM2M Enabler in release 1.1, and containing a configuration with Objects with Object ID of 0 (Security Object) and Object ID of 21 (OSCORE Object):

lwm2m="1.1",</0/0>;ssid=101;uri="coaps://server_1.example.com",</21/0>;ssid=101;uri="coap://server_1.example.com",</0/1>,</21/1/>" with the meaning 2 LwM2M Servers are supported in that Client (that supports the LwM2M Enabler in version 1.1), the Instance ID:0 of the Security Object ID:0 and the Instance ID:0 of the OSCORE Object ID:21 contains the DTLS and OSCORE credentials, respectively, of the the LwM2M server with ssid=101, while the Instance ID:1 of the OSCORE Object ID:21 contains the OSCORE credentials for the LwM2M Bootstrap-Server.

• when the "Discover" addresses a LwM2M Client supporting the LwM2M Enabler in release 1.1, and containing a configuration with an hypothetical LwM2M Object ID:55 in Version 1.9, with one Instance (/55/0):

  lwm2m="1.1",</0/0>,</0/1>;ssid=101;uri="coaps://server_1.example.com", </1/0/>;ssid=101, </3/0>,</5>,</4>,</55>;ver="1.9",</55/0>

6.1.7.4. BOOTSTRAP READ

The "Read" operation in Bootstrap Interface is a restricted form of the "Read" operation in Device Management and Service Enablement interface, and MUST be limited to target Objects which are strictly necessary to setup a proper configuration in a LwM2M Client; typically in LwM2M 1.1, the only acceptable targets for the Bootstrap "Read" is the LwM2M Server Object (Object ID: 1) and the Access Control Object (Object ID:2). This operation will allow the Bootstrap-Server to query the existing Server Account(s) to determine validity and to add new Server Account(s) without breaking the Access Rights already in place in the targeted LwM2M Client.

The Bootstrap "Read" operation is used to access a single Instance or all the Instances of the Server Object (ID:1) and the Access Control Object (ID:2).

The "Read" operation has the following parameters:

As a simple illustration based on the second example of section 7.4.2.2. Multiple Object Instance Request Examples: the Bootstrap "Read /2" command with JSON requested format could provide the following answer:

6.1.7.5. BOOTSTRAP WRITE

The "Write" operation in Bootstrap Interface is different from the "Write" Operation in Device Management and Service Enablement interface; the LwM2M Client MUST write the value included in the payload regardless of an existence of the targeted Object Instance(s) or Resource(s).

When the "Write" operation targets an Object or an Object Instance, the LwM2M Client MUST ignore optional resources it does not support in the payload. If the LwM2M Client supports optional resources not present in the payload, it MUST NOT instantiate these optional resources.

The Write operation can be sent multiple times.

Only in Bootstrap Interface, the "Write" MAY target just an Object ID, which will allow a Bootstrap-Server in using a TLV, CBOR or JSON formatted payload, to populate a LwM2M Client in a single message containing several Instances of the same Object.

The Bootstrap "Write" operation has the following parameters:

6.1.7.6. BOOTSTRAP DELETE

The Delete operation targets one or several Object Instances and can be sent multiple times.

Only in Bootstrap Interface, the Delete operation MAY target any Instance or all Instances of any Object including the Security Object (ID:0), supported by the LwM2M Client. The two exceptions are the LwM2M Bootstrap-Server Account, potentially including an associated Instance of an OSCORE Object ID:21, and the single Instance of the Mandatory Device Object (ID:3) which are not affected by any Delete operation.

When the Delete operation is used without any parameter (i.e. without Object ID parameter), all Instances of all Objects in the LwM2M Client MUST be removed (except for the two cases mentioned above); this functionality could be used for initialization purpose before LwM2M Bootstrap-Server sends Write operation(s) to the LwM2M Client.

The Delete operation has the following parameters:

6.2. Client Registration Interface

The LwM2M Server MUST support all operations in this interface. The LwM2M Client MUST support the "Register" and the "Update" operations. The LwM2M Client SHOULD support the "De-register" operation.

The Client Registration Interface is used by a LwM2M Client to register with one or more LwM2M Servers, maintain each registration, and de-register from a LwM2M Server. The registration is based on the Resource Model and Identifiers defined in Section 7. Identifiers and Resources. When registering, the LwM2M Client performs the "Register" operation and provides the properties required by the LwM2M Server (e.g. the supported Objects and existing Object Instances) as well as optional parameters (e.g. Endpoint Client Name). The LwM2M Client maintains the registration and communications session(s) with each LwM2M Server based upon the configured parameters (e.g. Lifetime, Queue Mode). The LwM2M Client periodically performs an update of its registration information to the registered LwM2M Server(s) by performing the "Update" operation.

If the lifetime of a registration expires without receiving an update from the LwM2M Client the LwM2M Server will consider it a de-registration:

• The LwM2M Server MUST remove the registration of that LwM2M Client and existing observations. If the LwM2M Client is unaware of the expiration, when the LwM2M Client performs a registration update the LwM2M Server will respond with an error.

• Upon receipt of the error message, the LwM2M Client SHOULD reset its state and register again. The LwM2M Client MUST re-register ("Update" is not sufficient) to the LwM2M Server in order to be connected again, before initiating any further communication.

If the LwM2M Server or the LwM2M Client set a value to the Lifetime Resource of the Server Object Instance, this value becomes the new lifetime of the Registration.

During "Register" or "Update" operations, the parameter Lifetime – if present – MUST match the current value of the Mandatory Lifetime Resource of the LwM2M Server Object Instance.

Finally, when shutting down or discontinuing use of a LwM2M Server, the LwM2M Client performs a "De-register" operation.

The Binding Resource of the LwM2M Server Object informs the LwM2M Client of the transport protocol preferences of the LwM2M Server for the communication session between the LwM2M Client and LwM2M Server. The LwM2M Client SHOULD perform the operations with the modes indicated by the Binding Resource of the LwM2M Server Object Instance.

The mapping to underlying transports is detailed in [LwM2M-TRANSPORT].

6.2.1. Register

Registration is performed when a LwM2M Client sends a "Register" operation to the LwM2M Server. After the LwM2M Device is turned on and the bootstrap procedure has been completed, the LwM2M Client MUST perform a "Register" operation to each LwM2M Server that the LwM2M Client has a Server Object Instance. Table: 6.2.1.-1 Registration parameters describes the parameters used for the "Register" operation.

The "Register" operation SHOULD include the Endpoint Client Name parameter along with other parameters listed in Table: 6.2.1.-1 Registration parameters. When the Endpoint Client Name parameter is provided in the "Register" operation then it MUST contain a value for the Endpoint Client Name parameter that is unique on that LwM2M Server.

Upon receiving a "Register" operation from the LwM2M Client, the LwM2M Server records the connection information of the registration message (e.g. source IP address and port or MSISDN) and uses this information for all future interactions with that LwM2M Client.

If the LwM2M Client sends a "Register" operation to the LwM2M Server even though the LwM2M Server has registration information of the LwM2M Client, the LwM2M Server removes the existing registration information and performs the new "Register" operation. This situation happens when the LwM2M Client forgets the state of the LwM2M Server (e.g. factory reset).

The LwM2M Server MUST support all the parameters listed at Table: 6.2.1.-1 Registration parameters and the LwM2M Client MUST support LwM2M Version, Lifetime, Object and Object Instances and MAY support Binding Mode and SMS Number. With LwM2M v1.1, the Endpoint Client Name becomes an optional parameter for the LwM2M Client, but MUST be supported by the LwM2M Server.

A LwM2M Server MUST refuse a Client's Registration request, if it doesn't support the LwM2M Enabler version indicated by the Client (i.e. major digit of the LwM2M versions in Client and Server are different, or the LwM2M version supported by the Client – e.g. 1.1 - is superior to the LwM2M version supported by the Server – e.g. 1.0.1 -).

The list of Objects and Object Instances is included in the payload of the registration message. Except the Security Object (ID:0), all the mandatory Objects defined in the LwM2M Enabler (i.e. Server Object ID:1 and the Device Object ID:3) MUST be part of the registration payload list. The Security Object ID:0, and OSCORE Object ID:21, if present, MUST NOT be part of the Registration Objects and Object Instances list.

When an Object defined outside of a LwM2M Enabler has to-be-registered by the Client, but is not supported by the Server (unknown Object or unsupported Object version) it MUST be silently ignored by this Server and will not prevent the Client's Registration request to be accepted.

The payload Media-Type of that registration message MUST be the CoRE Link Format (application/link-format) defined in [RFC6690], so that each Object is described as a Link according to that format. The Target component of the link is required, and consists of the Object path augmented of the Object Version CoRE link parameters "ver" if required as it is defined in section 7.2. Object Versioning of this document. Any other parameters included in the link MUST be silently ignored, unless specified for use by the LwM2M Enabler.

The payload for a LwM2M Client supporting LwM2M Server, Access Control, Device, Connectivity Monitoring and Firmware Update Objects from Appendix E would simply be:

</1>, </2>, </3>, </4>, </5>

If Objects Instances are already available on the LwM2M Client at the time of registration, then the format would be (for the example client of Appendix F):

</1/0>,</1/1>,</2/0>,</2/1>,</2/2>,</2/3>,</2/4>,</3/0>,</4/0>,</5>

If the LwM2M Client supports the JSON data format for all the Objects it SHOULD inform the LwM2M Server by including the content type in the root path link using the ct= link attribute. An example is as follows (note that the content type value 110 is the value assigned in the CoAP Content-Format Registry for the SenML JSON format used by LwM2M).

</>;ct=110, </1/0>,</1/1>,</2/0>,</2/1>,</2/2>,</2/3>,</2/4>,</3/0>,</4/0>,</5>

6.2.1.1. Bootstrap and LwM2M Server Registration Mechanisms

In order to provide robust mechanisms for LwM2M Server registrations, resources have been defined in the LwM2M Server Object to configure the order of LwM2M Server registrations, registration retry behavior and the ability for the LwM2M Client to react during registration failure conditions. These resources are optional, so the behavior is only enabled when these resources are defined. If these resources are not defined, default values in Table: 6.2.1.1.-1 Registration Procedures Default Values or a manufacturer defined implementation may be used.

The first step is for the LwM2M Client to determine the registration order when multiple LwM2M Servers are defined (i.e. multiple instances of LwM2M Server Objects). The LwM2M Client orders the LwM2M Server registrations in ascending order of the "Registration Priority Order" value. It is recommended that each ordered LwM2M Server has a unique priority, so it is implementation dependent how to order those LwM2M Servers with the same priority. If this value is not defined for a LwM2M Server, registration attempts to that LwM2M Server are managed independently and do not impact other LwM2M Server registrations.

For each LwM2M Server that is defined in the registration order, the "Registration Failure Block" resource indicates the behavior of the LwM2M Client upon registration failure to that LwM2M Server. When the "Registration Failure Block" value is set to true and registration to the LwM2M server fails, the LwM2M Client performs additional registration retry sequences and blocks registration to other LwM2M Servers in the priority order. When the "Registration Failure Block" value is set to false, the LwM2M Client proceeds with registration to the next LwM2M Server in the priority order whether the current LwM2M Server is successfully registered or not.

The procedure to manage the registration to LwM2M Servers that have a "Registration Priority Order" resource included is defined here:

When registration fails to non-blocking LwM2M Servers in the "Ordered Servers Procedure", it is not specified how the LwM2M Client retries registration with those LwM2M Servers. One solution could be to execute the "Single Unordered Servers Procedure" for all failed non-blocking LwM2M Servers.

The "Communication Retry Count", "Communication Retry Timer", "Communication Sequence Delay Timer" and "Communication Sequence Retry Count" resources indicate to the LwM2M Client the retry mechanism to be used for registration attempts to a single LwM2M Server. The registration mechanism to a LwM2M Server consists of a sequence of "Communication Retry Count" attempts within a retry sequence. The "Communication Retry Timer" value is multiplied by two to the power of the current attempt minus one (2^(Current Attempt-1)) to create an exponential back-off between attempts within a single retry sequence to a LwM2M Server. If one retry sequence of attempts to a LwM2M Server fails, then a new sequence of attempts may be retried after "Communication Sequence Delay Timer." The maximum number of retry sequences to a LwM2M Server is set by the "Communication Sequence Retry Count."

How these values are applied to those LwM2M Servers that are part of the ordered registration is defined in the "Single Ordered Server Procedure" here:

How these values are applied to those LwM2M Servers that are NOT part of the ordered registration is defined in the "Single Unordered Server Procedure" here:

Note: Current Attempt and Current Sequence start at 1 to represent the first attempt or sequence in the "Single Ordered Server Procedure" and "Single Unordered Server Procedure". These values should be reset to 1 at the start of each sequence and between sequences.

The "Initial Registration Delay Timer" defines the delay before the single registration procedure (ordered or unordered) is attempted for a LwM2M Server.

The "Bootstrap on Registration Failure" resource indicates to the LwM2M Client whether to re-bootstrap in case of a registration failure to the LwM2M Server. The exact behavior in case of bootstrap registration success, triggered by a server registration failure, is implementation dependent. For example, already successful LwM2M Server registrations may be maintained.

Note: It is recommended to set the "Bootstrap on Registration Failure" resource to true only for critical LwM2M Servers.

The registration retry mechanisms for the Bootstrap Server are implementation dependent.

The following table represents the recommended default values to use when the resources are not defined in the LwM2M Server Object:

6.2.1.2. Behaviour with Current Transport Binding and Modes

Behaviour of the LwM2M Server and the LwM2M Client is differentiated by Current Transport Binding and Modes. Current Transport Bindings are decided by "Binding" Resource set by the LwM2M Server. The "Binding" resource contains a combination of supported transports e.g. SMS, UDP etc.

Table: 6.2.1.2.-1 Behaviour with Current Transport Bindings describes the behaviour of the LwM2M Server and the LwM2M Client for each Current Transport Bindings.

• While multiple transports are supported, only one transport binding can be used during the entire session. As an example, when UDP and SMS are both supported, the LwM2M Client and Server can choose to communicate either over UDP or SMS during the entire session.
  

• Queue Mode and Trigger Mode can be enabled independently and can be used in conjuction with one or more transports. Queue Mode is useful when the LwM2M Device is not reachable by the LwM2M Server at all times and it could help the LwM2M Client preserve its resources by sleeping longer. Using the Trigger Mode, the LwM2M Server MAY request the LwM2M Client to perform operations such as "Update" operation by sending "Execute" operation on "Registration Update Trigger" Resource via SMS. No SMS response is expected for a Trigger message.

• "Preferred Transport" is an optional resource in the LwM2M Server Object. If this resource is undefined, the default mode is implementation specific. If this resource is defined, the device MAY use this to initiate a connection over the specified transport. This resource can also be used to switch between multiple transports e.g. a non-IP device can switch to UDP transport to perform firmware updates.

6.2.2. Update

Periodically or based on certain events within the LwM2M Client or initiated by the LwM2M Server, the LwM2M Client updates its registration information with a LwM2M Server by sending an "Update" operation to the LwM2M Server.

The "Update" operation can be initiated by the LwM2M Server via an "Execute" operation on the "Registration Update Trigger" Resource of the LwM2M Server Object. The LwM2M Client can perform an "Update" operation to refresh the lifetime of its registration to a LwM2M Server.

When any of the parameters listed in Table: 6.2.2.-1 Update parameters changes, the LwM2M Client MUST send an "Update" operation to the LwM2M Server. This "Update" operation MUST contain only the parameters listed in Table: 6.2.2.-1 Update parameters which have changed compared to the last registration parameters sent to the LwM2M Server.

When present,the Objects and Object Instance list MUST contain all the supported Objects and Object Instances available on the LwM2M Client. The Security Object ID:0, and the OSCORE Object ID:21, if present, MUST NOT be part of Update Objects and Object Instances list.

The payload Media-Type of that "Update" message is the same as the one of the "Registration" message section 6.2.1. Register.

When an Object defined outside of a LwM2M Enabler is part of the LwM2M Client update registration list, but is not supported by the LwM2M Server (unknown Object or unsupported Object version), it MUST be silently ignored by this LwM2M Server and will not prevent the LwM2M Client's "Update" operation to be accepted.

Two common operations are:

1. Extending the lifetime of a registration

In this case the LwM2M Client sends an "Update" operation with no parameters.

Figure: 6.2.2.-1 Update Example Flow #1 shows an example exchange where the LwM2M Client sends an "Update" operation that only refreshes the registration, i.e. the message does not contain any parameters. With the second "Update" the Client changes the lifetime field to 6000 (seconds) and hence the lt parameter is included in the message.

2. Adding and removing Objects and Object Instances

In this case the LwM2M Client sends an "Update" with a body listing the complete list of objects and object instances.

Figure: 6.2.2.-2 Update Example Flow #2 shows an example exchange whereby the LwM2M Client starts with an initial registration of two instances for a LwM2M Object with ID 12. Later, the LwM2M Server adds a third instance and subsequently deletes the second. With the "Update" operation the LwM2M Client includes the new list of Objects and Object Instances.

6.2.3. De-register

When a LwM2M Client determines that it no longer requires to be available to a LwM2M Server (e.g. LwM2M Device factory reset), the LwM2M Client SHOULD send a "De-register" operation to the LwM2M Server. Upon receiving this message, the LwM2M Server removes the registration information from the LwM2M Server.

6.3. Device Management and Service Enablement Interface

The LwM2M Server and the LwM2M Client MUST support all the operations on this interface unless clearly stated otherwise. Support for some of the non-mandatory operations may also be dependent on the choice of transport layer and the services it provides.

The Device Management and Service Enable Interface is used by the LwM2M Server to access Object Instances and Resources available from a registered LwM2M Client. The interface provides this access through the use of "Create", "Read", "Read-Composite", "Write", "Write-Composite", "Delete", "Execute", "Write-Attributes", or "Discover" operations. The operations that a Resource supports are defined in the Object definition using the Object Template. The Object Template is described in Appendix D.1 Object Template. The Normative Objects defined by the LwM2M Enabler are described in Appendix E.

The LwM2M Client MUST ignore LwM2M Server operations on this interface during a Server Initiated Bootstrap.

The LwM2M Client MUST ignore LwM2M Server operations on this interface until it received its Registration acknowledgement.

The LwM2M Client MUST reject with an "4.01 Unauthorized" response code any LwM2M Server operation on the Security Object (ID: 0).

The LwM2M Client MUST reject with an "4.01 Unauthorized" response code any LwM2M Server operation on an OSCORE Object (ID: 21).

The LwM2M Server SHOULD NOT perform any operation on this interface before replying to the registration of this LwM2M Client.

Note : The mapping of CoAP Methods of the LwM2M Client Registration Interface operations specified in this section, is detailed in [LwM2M-Transport]

6.3.1. Read

The "Read" operation is used to access the value of a Resource, a Resource Instance, an array of Resource Instances, an Object Instance or all the Object Instances of an Object. The "Read" operation has the following parameters:

6.3.2. Discover

The "Discover" operation is used to discover LwM2M Attributes attached to an Object, Object Instances, and Resources. This operation can be used to discover which Resources are instantiated in a given Object Instance. The returned payload is a list of application/link-format CoRE Links [RFC6690] for each targeted Object, Object Instance, or Resource, along with their assigned or attached Attributes including the Object Version attribute if required (see Section 7.2. Object Versioning and Table: 5.1.2.-1 Class Attributes ).

The "Discover" operation has the following parameters:

• If Object ID is only specified, the LwM2M Client MUST respond to the "Discover" operation with the list of Object Instances and the list of their respective instantiated Resources. In addition, the list of Attributes which have been assigned to this Object level, are also returned, see Section Attribute Classification.

  For example: when the "Discover" operation targets an Object with Object ID of 3, the response to the operation could be:

  </3>;pmin=10,</3/0>,</3/0/1>, </3/0/2>, </3/0/3>, </3/0/4>, </3/0/6>,</3/0/7>,</3/0/8>,</3/0/11>,</3/0/16> which means that the LwM2M Client supports the Device Info Object (Instance 0) Resources with IDs 1,2,3,4 6,7,8,11, and 16 among the Resources of Device Info Object, with an R-Attributes assigned to the Object level.

• If Object ID and Object Instance ID are only specified, the list of Attributes assigned to that Object Instance MUST be reported, and the list of instantiated Resources and their assigned Attributes MUST be returned in the response as well.

  For example: if Object ID is 3 and Object Instance ID is 0, then

  </3/0>;pmax=60, </3/0/1>, </3/0/2>, </3/0/3>, </3/0/4>, </3/0/6>;dim=2,</3/0/7>;dim=2;gt=50;lt=42.2,</3/0/8>;dim=2,</3/0/11>,</3/0/16>

  means that regarding the Device Info Object Instance, an R-Attribute has been assigned to this Instance level; the LwM2M Client supports the Multiple-Instance Resources 6, 7, and 8 with a dimension of 2 and has 2 additional Notification parameters assigned to Resource 7.

• If Object ID, Object Instance ID and Resource ID are specified, the attached Attributes of that Resource MUST be returned (includes the assigned R-Attributes and the R-Attributes inherited from the Object and Object Instance) as well as the list of the Resource Instances in case of a Multiple-Instance Resource (includes the assigned R-Attribute(s) if any).

  For example: if Object ID is 3, Object Instance ID is 0, and Resource ID is 7, then

  </3/0/7>;dim=2;pmin=10;pmax=60;gt=50;lt=42.2, </3/0/7/0> </3/0/7/1>;lt=45 with pmin assigned at the Object level, pmax assigned at the Object Instance level, and "lt" Attribute explicitly set at a Resource Instance level (/3/0/7/1)..

• If a Resource, an Object Instance, or an Object have attributes for multiple LwM2M Servers, then the Attributes returned in the link, MUST only be related to the Server which performed the DISCOVER request. As example, for the Device Object (ID:3) having the Resource ID:7 with two Observe operations from two Servers 1 & 2, then the answers to DISCOVER command on both Servers will be differentiated e.g.

  from Server 1: DISCOVER /3/0/7 could provide the answer: </3/0/7>;dim=2;gt=50;lt=42.2, </3/0/7/0> </3/0/7/1>

  from Server 2: DISCOVER /3/0/7 could provide the answer: </3/0/7>;dim=2;pmax=300;gt=80;lt=65.5, </3/0/7/0> </3/0/7/1>

6.3.3. Write

The "Write" operation is used to change the value of a Resource, the value of a Resource Instance, the values of an array of Resources Instances or the values of multiple Resources from an Object Instance. The "Write" operation can also be used to request the deletion or the allocation of specific Instances of a Multiple-Instance Resource

The request includes the value to be written encoded in one of the data format defined in section 7.4. Data Formats for Transferring Resource Information.

The TLV, CBOR or JSON data format MUST be used in a "Write" request:

• when more than a single value of a Resource has to be changed
• when one or several Instances of a Multiple-Instance Resource have to be deleted or allocated.

The Write request MUST be rejected:

• if the specified data format is not supported by the LwM2M Client
• or if, checking the value of the incoming Resource against its data type, at least one of the following conditions is not met:
  • the value matches the expected format
  • the value is in the range specified in the Object definition
  • if the value is an Objlnk value, it must either point to an Object actually present in the LwM2M Client (the value will then be ObjectID:MAX_ID), or point to an Object Instance actually present in the LwM2M Client, or contain the null pointer (the value will then be MAX_ID:MAX_ID)
• or if the deletion or allocation of an Instance of a Multiple-Instance Resource is not allowed by the LwM2M Client.

The LwM2M Client and LwM2M Server MUST support the following mechanisms to change multiple Resources or an array of Resource Instances:

• Replace: replaces the Object Instance or the Resource(s) with the new value provided in the "Write" operation. When the Resource is a Multiple-Instance Resource, the existing array of Resource Instances is replaced to the condition the LwM2M Client authorizes that operation.

• Partial Update: updates Resources provided in the new value and leaves other existing Resources unchanged. When the Resource is a Multiple-Instance Resource, the existing array of Resource Instances is updated meaning some Instances may be created or deleted to the condition the LwM2M Client authorizes such operations

The "Write" operation has the following parameters:

6.3.4. Write-Attributes

In LwM2M 1.x, only Attributes from the <NOTIFICATION> class MAY be changed in using the "Write-Attributes" operation.

The general rules for Attributes which are specified in Section 5.1.1. Attributes Definitions and Rules fully apply here. Table: 5.1.2.-1 Class Attributes in Section 5.1.2. Attributes Classification provides explanation on the Attributes supported by the "Write-Attributes" operation: Minimum Period, Maximum Period, Greater Than, Less Than, Step, Minimum Evaluation Period and Maximum Evaluation Period.

The operation permits multiple Attributes to be modified within the same operation.

Including <NOTIFICATION> class Attributes specified in Table: 5.1.2.-1 Class Attributes Section 6.2.1. Register, the "Write-Attributes" operation has the following parameters:

Note: How to indicate the Attributes in the message payload is specified in [CoRE_Interface].

6.3.5. Execute

The "Execute" operation is used by the LwM2M Server to initiate some action, and can only be performed on individual Resources. A LwM2M Client MUST return an error when the "Execute" operation is received for an Object Instance(s) or Resource Instance(s).

Resource which supports "Execute" operation MAY have arguments.

In using ABNF, the syntax of the arguments, and arguments list is given as follows:

Examples of valid lists of arguments

1. 5

2. 2='10.3'

3. 7, 0=' https://www.omaspecworks.org'

4. 0,1,2,3,4

6.3.6. Create

The "Create" operation is used by the LwM2M Server to create Object Instance(s) within the LwM2M Client. The "Create" operation MUST target an Object, and MUST follow the rules specified in section 8. Access Control and its sub-sections. If any error occurs, nothing MUST be created.

The Object Instance created in the LwM2M Client by the LwM2M Server MUST be an Object type supported by the LwM2M Client and announced to the LwM2M Server using the "Register" and "Update" operations of the LwM2M Client Registration Interface.

Object Instance whose Object supports at most one Object Instance MUST be assigned an Object Instance ID of 0 when the Object Instance is Created.

The "Create" operation has the following parameters:

The new value included in the payload MUST follow the TLV, CBOR or JSON data format according to section 7.4. Data Formats for Transferring Resource Information.

The LwM2M Client MUST ignore optional resources it does not support in the payload. If the LwM2M Client supports optional resources not present in the payload, it MUST NOT instantiate these optional resources.

When there is no reference to Object Instance in the TLV/CBOR/JSON payload of the "Create" command, the LwM2M Client MUST assigns the ID of the created Object Instance. If a new Object Instance is created through that operation and the LwM2M Client has more than one LwM2M Server Account, then the LwM2M Client creates an Access Control Object Instance for the created Object Instance (section 8. Access Control)

• Access Control Owner MUST be the LwM2M Server

• The LwM2M Server MUST have full access rights

6.3.7. Delete

The "Delete" operation is used for LwM2M Server to delete an Object Instance within the LwM2M Client.

The Object Instance that is deleted in the LwM2M Client by the LwM2M Server MUST be an Object Instance that is announced by the LwM2M Client to the LwM2M Server using the "Register" and "Update" operations of the Client Registration Interface.

The only exception concerns the single Instance of the mandatory Device Object (ID:3) which SHALL NOT be affected by any Delete operation.

The Delete operation has the following parameters:

6.3.8. Read-Composite

If supported by the client, the "Read-Composite" operation can be used by the LwM2M Server to selectively read a number of Resources, and/or Resource Instances of different Objects in a single request. The list of elements to be read are provided as separate parameters to the operation in JSON/CBOR format. The format is similar to JSON/CBOR reply format, but without values for the resources. The Read-Composite operation is treated as non-atomic and handled as best effort by the client. That is, if any of the requested resources do not have a valid value to return, they will not be included in the response. The section 7.4.3. JSON shows examples of Read-Composite use.

6.3.9. Write-Composite

In contrast to Write operation, the scope of which is limited to a Resource(s) of a single Instance of a single Object, the "Write-Composite" operation can be used by the Server to update values of a number of different Resources across different Instances of one or more Objects. Similar to Read-Composite the Write-Composite operation provides a list of all resources to be updated, and their new values, using the JSON/CBOR format. Unlike for Write operation, the Resources that are not provided are not impacted by the operation. See the section on 7.4.3. JSON for examples.

The Write-Composite operation is atomic and cannot have partial success. That is, if the client supports this operation, it MUST reject a Server request where it cannot successfully write all the requested values to the requested list of Resources. Therefore, before processing Write-Composite, the client MUST ensure that all addressed objects exist and that the Server has write access to those Objects and Resources.

6.3.10. Send

The "Send" operation is used by the LwM2M Client to send data to the LwM2M Server without explicit request by that Server. More specifically, it is used by the Client to report values for Resources and Resource Instances of LwM2M Object Instance(s) to the LwM2M Server.

The reported LwM2M Object Instances (potentially different Object types) MUST have been registered by the LwM2M Client to the LwM2M Server. That LwM2M Server MUST have Read access right granted on the Object Instances of the reportable Resources which MUST support the Read operation (see Section 8.2. Authorization). If these criteria are not met for some Resources, the LwM2M Client MUST NOT include those Resources in the Send command.

In addition, if any of the rules mentioned below is violated, the Server MUST respond with an error in reply to the "Send" operation.

The value included in the payload MUST be either JSON or CBOR format described in section 7.4. Data Formats for Transferring Resource Information. As example:

Reporting the location of the LwM2M Client and the radio signal strength in a JSON payload:

Send
New Value:
[
  {"n":"/6/0/0", "v":43.61092},
  {"n":"/6/0/1", "v":3.87723},
  {"n":"/4/0/2", "v":-49}
]

6.4. Information Reporting Interface

The LwM2M Server and the LwM2M Client MUST support all the operations on this interface. Support for some of the non-mandatory operations may also be dependent on the choice of transport layer and the services it provides.

The Information Reporting Interface is used by a LwM2M Server to observe any changes in a Resource on a registered LwM2M Client, receiving notifications when new values are available. This observation relationship is initiated by sending an "Observe" or "Observe-Composite" operation to the L2M2M Client for an Object, an Object Instance or a Resource. An observation ends when a "Cancel Observation" or "Cancel Observation-Composite" operation is performed.

The LwM2M Client MUST ignore LwM2M Server operations on this interface during a Server Initiated Bootstrap.

The LwM2M Client MUST ignore LwM2M Server operations on this interface until it received its Registration acknowledgement.

The LwM2M Server SHOULD NOT perform any operation on this interface before replying to the registration of this LwM2M Client.

The LwM2M Client MUST reject with an "4.01 Unauthorized" response code any LwM2M Server operation on the Security Object (ID: 0).

The LwM2M Client MUST reject with an "4.01 Unauthorized" response code any LwM2M Server operation on an OSCORE Object (ID: 21).

The mapping to underlying transports is detailed in [LwM2M-TRANSPORT].

6.4.1. Observe

The LwM2M Server initiates an observation request for changes of a specific Resource, Resources within an Object Instance or for all the Object Instances of an Object within the LwM2M Client.

Related parameters for "Observe" operation are described in Section 6.3.4. Write-Attributes and those parameters are configured by "Write-Attributes" operation.

The Observe operation includes the following parameters:

Until the LwM2M Client sends a new registration, the LwM2M Server expects the LwM2M Client to remember the observation requests. If a LwM2M Client forgets the observation requests (e.g. device factory reset) it MUST perform a new "Register" operation. The LwM2M Server MUST re-initiate observation requests whenever the LwM2M Client registers.

In order to avoid network traffic increase, the LwM2M Client SHOULD maintain previous observation states in case of reboot, power cycle.

It has to be noted that an "Observe" operation containing only Object ID, will produce the report of all Object Instances information.

Note: When a LwM2M Client deregisters, the LwM2M Server should assume past states are nullified including the previous observations.

6.4.2. Notify

The "Notify" operation is sent from the LwM2M Client to the LwM2M Server during a valid observation on an Object Instance or Resource. This operation includes the new value of the Object Instance or Resource. The "Notify" operation SHOULD be sent when all the conditions (i.e. Minimum Period, Maximum Period, Greater Than, Less Than, Step) configured by "Write-Attributes" operation for "Observe" operation are met.

The following example shows how the Minimum and Maximum period parameters work as shown in Section 6.3.4. Write-Attributes. A LwM2M Server makes an observation for a Temperature Resource that is updated inside the LwM2M Client at irregular periods (based on change). The LwM2M Server makes an observation when the Minimum Period = 10 Seconds and Maximum Period = 60 Seconds have been set for that Resource. The LwM2M Client will wait at least 10 Seconds before sending a "Notify" operation to the LwM2M Server (even if the Resource has changed before that), and no longer than 60 Seconds before sending a "Notify" operation (even if the Resource has not changed yet). The "Notify" operation is sent anywhere between 10-60 seconds upon change.

Note: In case an "Observe" operation is initiated on a Resource, an Object Instance or an Object without any conditions previously configured, and with the "Default Minimum Period" in the LwM2M Server Object set to 0 (possibly by default), the "Notify" operation will be sent upon any change of, respectively, the observed Resource value, any Resource value of the observed Object Instance or any Resource value of any Instance of the observed Object. As specified in Section 6.4.1. Observe and in Table: 6.4.1.-1 Observe parameters, in case of an "Observe" operation on a certain Object the "Notify" operation includes all Resources of all Instances of the observed Object.

In this example the Minimum Period has been set to 10 and the Maximum Period set to 60 for the Resource /4/0/2 before making the observation.

6.4.3. Cancel Observation

The "Cancel Observation" operation is sent from the LwM2M Server to the LwM2M Client to end an observation relationship that was previously created with an "Observe" operation.

6.4.4. Observe-Composite

If supported by the client, the LwM2M Server can use the "Observe-Composite" operation to initiate observations for a group of resources and/or resource instances across multiple object instances within the client. As with the "Read-Composite" operation, the list of elements to be observed is provided as a separate parameter to the operation in JSON/CBOR format.

The Notification class attributes for each resource that is observed through the "Observe-Composite" operation are individually configured by the LwM2M server using the "Write-Attribute". Each resource can have multiple observe conditions attached. If any of the conditions attached to one or more resources under observation meets the notification criteria a notify will be generated by the LwM2m client, which will include the value for each of the resources listed in the "Observe-Composite" operation. Hence, the resources that have not met the notify condition will still be included in the notification message.

6.4.5. Cancel Observation-Composite

The "Cancel Observation-Composite" operation is sent from the LwM2M Server to the LwM2M Client to end previously set up composite observation relationship.

7. Identifiers and Resources

This section defines the identifiers and resource model for the LwM2M Enabler.

7.1. Resource Model

The LwM2M Enabler defines a simple resource model where each piece of information made available by the LwM2M Client is a Resource. Resources are logically organized into Objects. Each Resource is given a unique identifier within that Object and a data type among those defined in Appendix C. Data Types (Normative).

Figure: 7.1.-1 Relationship between LwM2M Client, Object, and Resources illustrates this structure, and the relationship between Resources, Objects, and the LwM2M Client. The LwM2M Client may have any number of Resources, each of which belongs to an Object; for example the Firmware Update Object contains all the Resources used for firmware update purposes.

Each Object, defined for the LwM2M Enabler, is assigned an unique OMA LwM2M Object identifier allocated and maintained by the OMA Naming Authority [OMNA]. The LwM2M Enabler defines standard Objects and Resources Appendix LwM2M Objects defined by OMA (Normative). Further Objects may be added by OMA or other organizations to enable additional M2M Services.

As an Object only specifies a grouping of Resources, an Object MUST first be instantiated so that the LwM2M Client can use the Resources of such an Object and the associated functionalities.

When an Object is instantiated – either by the LwM2M Server or the LwM2M Client – an Object Instance is created with a subset of the Resources defined in the Object specification; a LwM2M Server can then access that Object Instance and its set of instantiated Resources.

A Resource which is instantiated within an Object Instance is a Resource which can either:

• contain a value (if the Resource is Readable and/or Writeable)

• or can be addressed by a LwM2M Server to trigger an action in the LwM2M Client (if the Resource is Executable)

Data Type checking on a Resource value MUST be performed:

• by the Client when the Server tries to set such a Resource,
• by the Server when the Server retrieves such a Resource

The Client MUST reject a request, if an error is detected when checking an incoming Resource value against its data type.

The Object specification defines the operations (Read, Write, Execute) which are individually supported by the Resources belonging to that Object; this specification also defines the Mandatory or Optional characteristics of such Resources.

A Resource specified as Mandatory within an Object MUST be instantiated in any Instance of that Object.

A Resource specified as Optional within an Object MAY be omitted from some or even all Instances of that Object.

As illustration, the following example using the DISCOVER command on the Server Object, exposes a configuration in which the Server Object (ID:1) has 2 Instances (ID:0, ID:1): the Optional Resources ID:2, ID:4 are only instantiated in the Instance 1 of the Object, while the Optional Resources ID:3 and ID:5 are not instantiated in either of the Server Object Instances. In Server Object ID:1, the Resources 0,1, and 6,7,8 are Mandatory Resources.

According to the DISCOVER /1 request, the following payload is returned:

</1/0/0>,</1/0/1>,</1/0/6>,</1/0/7>, </1/0/8>, </1/1/0>,</1/1/1>,</1/1/2>,</1/1/4>,</1/1/6>,</1/1/7>, </1/1/8>

Objects and Resources have the capability to have multiple instances. Multiple-Instance Resources can be instantiated by LwM2M Server operations in using JSON, CBOR or TLV formats (Section 7.4. Data Formats for Transferring Resource Information). The LwM2M Client also has the capability to instantiate Single or Multiple-Instance Resources.

The LwM2M Server performs operations on an Object, Object Instance and Resources as described in section 6. Interfaces. These operations are conveyed as described in [LwM2M-TRANSPORT] and how to convey the Operation data is defined in section 7.4. Data Formats for Transferring Resource Information.

The LwM2M Enabler defines an access control mechanism per Object Instance. Object Instances SHOULD have an associated Access Control Object Instance. An Access Control Object Instances contains Access Control Lists (ACLs) that define which operations on a given Object Instance are allowed for which LwM2M Server(s).

Figure: 7.1.-2 Example of Supported operations and Associated Access Control Object Instance shows an example of the operations the Resources support and how Object Instances and Resources are associated with Access Control Object Instance. In the example, Object Instance 0 for Object 1 has 2 Resources. Resource 1 supports the "Read", "Write" operations, while Resource 0 supports only the "Read" operation. The associated Access Control Object Instance has ACL of Object Instance 0 for Object 1. Server1 is authorized to perform "Read" and "Write" operations to the Object Instance 0 for Object 1 and Resources of the Object Instance. However, due to the supported operations of each Resource, Server1 can perform the "Read" operation on Resource 1 and 0, and also can perform the "Write" operations on Resource 1, but Server1 cannot perform the "Write" operation on Resource 0. The detailed access control mechanism is defined in section 8. Access Control.

7.2. Object Versioning

7.2.1. General Policy

A LwM2M Object specification is tightly coupled with the LwM2M Enabler which is supporting it. However, a LwM2M Object that is not directly specified in the LwM2M Enabler but in a "companion specification", MAY evolve (e.g. to fix one Object Resource characteristic issue).

For example:

• a Resource may be added or removed in the Object

• a Resource characteristic (mandatory nature, data type, operation mode …) may be changed in the Object

A LwM2M Server MUST be able to determine without ambiguity the specification of the Objects intended to be registered by the LwM2M Client:

• it is the case for the LwM2M Objects which are specified within the LwM2M

• for LwM2M Objects specified outside of a LwM2M Enabler, the Server has to be informed if the initial set of Resources characteristics have been modified/fixed, so that the Server can refer to the proper Object Specification

Object versioning aims at identifying the LwM2M Object modifications which can be categorized in 2 types defined below:

• Evolution of type I: representing non-backward-compatible ("breaking") evolutions, namely:

  • a Resource characteristic (optional vs mandatory, data type, supported operations) is changed in the Object
  • a mandatory Resource is added to or removed from the Object.
  • a feature which is only defined by a new LwM2M Enabler, is added to the Object.

• Evolution of type II: representing backward-compatible ("non-breaking") evolutions

  • an optional Resource is added or removed in the Object

In this document, the term "Initial Version" represents:

• the version 1.0 of the LwM2M Enabler
• the version 1.0 of any Object registered for the first time in [OMNA]

With Object versioning, the Object Identifier is not changed but a new URN identifying that particular version of the Object specification MUST be registered according to the following format

"urn:oma:lwm2m:{oma, ext, x}:ObjectID[:{version}]" where 'version' is the Object Version as defined in the following section

7.2.2. Object Version format

The Object Version of an Object is composed of 2 digits separated by a dot '.':

• the first digit represents the Major Version of the Object: this digit marks the non-backward compatible evolution of such an Object (Object evolution of type I: section 7.2.1. General Policy)

• the second digit represents the Minor Version of the Object: this digit marks the backward compatible evolution of such an Object (Object evolution of type II: section 7.2.1. General Policy)

By convention when an Object is in its Initial Version, the Object Version MAY be omitted in the URN.

To be more precise, two separate URNs are accepted as valid for the corresponding version of the object specification:

• the URN where the Object Version is mentioned explicitly: "urn:oma:lwm2m:{oma, ext, x}:ObjectID:1.0"

• the URN where the Object Version is absent: "urn:oma:lwm2m:{oma, ext, x}:ObjectID" (and supposed to be 1.0).

Example: "urn:oma:lwm2m:oma:44:2.2"

This URN uniquely identifies Object ID:44 in its version "2.2". Registered Objects are available on the OMNA portal (see Section 7.3. Identifiers and the Appendix J. LwM2M Schema and Object Definition File (Informative) on Object Definition File for further information.

7.2.3. Object Definition and Object Version Usage

The rules governing in which circumstances the Object Version is provided by the LwM2M Client to the LwM2M Server during the "Register" and "Discover" operations, are synthesized in the following table:

In "Register" and "Discover" operations, when the Object Version of a given Object must be communicated, the LwM2M Client MUST use the "ver" (object version) <PROPERTIES> Class attribute associated to that Object.

Few examples:

a) URN: "urn:oma:lwm2m:oma:44:2.2" Object 44 in version 2.2

Details:

• on the [OMNA] portal the Object ID:44 will be registered at least twice

  • with the URN "urn:oma:lwm2m:oma:44" (Initial Version)
  • with the URN "urn:oma:lwm2m:oma:44:2.2" (or the latest release of the major Version 2, the LwM2M Server ignores minor releases)

• the Object definition contains the minimal version of the LwM2M Enabler supporting that Object (which can be omitted if this LwM2M version is the "Initial Version" one)

• LwM2M Client "Register" operation: ep=nodename,</1/0>,</1/1>,</3/0>,</44>;ver="2.2",</44/0>

b) URN: "urn:oma:lwm2m:oma:3"

Details: LwM2M Client "Register" operation: ep=nodename,</1/0>,</1/1>,</3/0>

c) URN: "urn:oma:lwm2m:oma:44"

Details: LwM2M Client "Register" operation: ep=nodename,</1/0>,</1/1>,</3/0>,</44/0>

d) URN: "urn:oma:lwm2m:oma:3" in LwM2M Client supporting LwM2M Enabler version 2.0

Details:

• the minimal version of the LwM2M Enabler supporting that Object "3" (Device) is still LwM2M 1.0; this information may be omitted in the Device (ID:3) Object Definition file

• LwM2M Client "Register" operation: lwm2m="2.0",ep=nodename,</1/0>,</1/1>,</3/0>

e) URN: "urn:oma:lwm2m:oma:4:3.1"

Context:

• the LwM2M Client supports LwM2M Enabler version 2.0

• Object ID: 4 supports a specific feature of LwM2M 2.0 not supported by the LwM2M Enabler Initial Version, and the Object Version 3 is part of the LwM2M Enabler Version 2.0

Details:

• the minimal version of the LwM2M Enabler supporting that Object "4" (Device) must be indicated in the Object 4 version 3.1 Definition file: LwM2MVersion="2.0" and ObjectVersion="3.1"

• LwM2M Client "Register" operation: lwm2m="2.0",ep=nodename,</1/0>,</1/1>,</3/0>,</4/0>

7.3. Identifiers

The LwM2M Enabler defines specific identifiers for entities used within the LwM2M Protocol. These identifiers are defined in Table: 7.3.-1 LwM2M Identifiers.

7.3.1. Endpoint Client Name

The Endpoint Client Name is a string. URIs and URNs are RECOMMENDED formats for this identifier. The Endpoint Client Name identifier MUST be unique at the server or servers it is being used with. Note that the Endpoint Client Name is unauthenticated and can be set to arbitrary value by a misconfigured or malicious client and hence MUST NOT be used alone for any decision making without prior matching the Endpoint Client Name against the identifier used with the security protocol protecting LwM2M communication. This parameter MAY be omitted when the security protocol provides to the server an authenticated identifier that is identical to this parameter. For more discussion consult the security consideration section in the [LwM2M-TRANSPORT] specification. This security consideration section also provides a description of the privacy implications of re-using the same identifiers across multiple servers.

This specification RECOMMENDS the Endpoint Client Name to be in a URI or a URN format for uniqueness reasons. The following table lists recommended formats. Other URI and URN formats MAY also be used. In particular, URN formats defined in [DMREPPRO] Section 6.4. Information Reporting Interface can be used. Note: Implementations need to be careful when using the Endpoint Client Name to perform database lookups due to the risk of SQL injection attacks.

If a URN identifier from the above table is used, it MUST adhere to the specified format.

Other URN formats MAY be used. In particular, URN formats defined in Section 5.5 of [DMREPPRO] can be used.

7.3.2. Reusable Resources

When Objects are designed for a similar purpose, for example Objects for use in network management, or Objects for use in embedded device automation, similar Resources are useful in more than one Object. For example in embedded device automation, Objects for different purposes may contain common Resource types such as digital input, digital output, analogue input, analogue output, dimmer value, unit, min measurement, max measurement, value range etc.

If a Resource can feasibly be re-used with the same meaning in multiple Object definitions, it can be defined as a Reusable Resource ID and registered with [OMNA]. Other Objects may then make use of this Reusable Resource ID in another Object definition.

The definition of a Reusable Resource and its usage when hosted in an Object specification MUST follow several rules:

• the Name, ID, Operation, Type, Range and Units are frozen characteristics when the Reusable Resource is registered at [OMNA] and cannot not be changed when such a Resource is specified in the definition of a hosting Object.

• the registered Description field of a Reusable Resource is also a frozen characteristic; when extension is required to fit the real need of the Object hosting such a Resource, that extension must be mentioned in the Object specification but outside of the Description field itself; furthermore any extension MUST be compatible with the content of the registered Description field.

• a Reusable Resource is registered without defining "Multiple-Resource", or "Mandatory" characteristics; both characteristics will be determined when such a Resource is specified in the definition of a hosting Object.

Note: If the operators/vendors want to extend the Resources in a non-standard way, it is advisable to refer [OMNA] and use the private resource range. This action of using private range, would ensure backward compatibility in case the Resource(s) is getting extended in future releases of LwM2M TS, by OMA DM WG.

7.4. Data Formats for Transferring Resource Information

The following data formats are defined by the LwM2M Enabler in this section: plain text, opaque, TLV, JSON, CoRE Link, SenML JSON, and SenML CBOR.

The LwM2M Server MUST support all data formats, including TLV that was mandatory to support for LwM2M TS 1.0 Clients.

The LwM2M Client MUST support plain text, opaque, and CoRE Link data formats and it SHOULD support at least one of SenML CBOR or SenML JSON data formats. In addition, a LwM2M Client MAY choose to support other data formats. LwM2M Clients supporting LwM2M TS 1.1 or newer SHOULD NOT use the legacy TLV or JSON formats.

Messages containing data MUST specify the payload encoding by using one of the supported data formats.

A LwM2M Server data request MAY contain an option specifying the data formats the Server would prefer to receive for the payload; if this data format is not accepted by the LwM2M Client, the request is rejected; if the LwM2M Client doesn't support that option or if the LwM2M Server expresses no data format preference, the LwM2M Client will use its own preferred data format.

The IANA registered Media Types supported in LwM2M TS 1.0 are listed in the table below.

In addition, the LwM2M TS 1.1 adds support for the following standardized media types.

The plain text format is used for "Read" and "Write" operations on singular Resources where the value of the Resource is represented as described in Appendix C. Data Types (Normative).

For example a request to the example client's Device Object Instance, Manufacturer Resource would return the following plain text payload:

This data format has a Media Type of text/plain.

7.4.1. Opaque

The opaque format is used for "Read" and "Write" operations on singular Resources where the value of the Resource is an opaque sequence of binary octets. This data format is used for binary Resources such as firmware images or application specific binary formats.

This data format has a Media Type of application/octet-stream.

7.4.2. TLV

For "Read" and "Write" operations, the binary TLV (Type-Length-Value) format can be used to represent an array of values or a singular value using a compact binary representation, which is easy to process on simple embedded devices. The format has a minimum overhead per value of just 2 bytes and a maximum overhead of 5 bytes depending on the type of Identifier and length of the value. The maximum size of an Object Instance or Resource in this format is 16.7 MB. The format is self-describing, thus a parser can skip TLVs for which the Resource is not known.

This data format has a Media Type of application/vnd.oma.lwm2m+tlv.

Each TLV entry starts with a Type byte that indicates if the TLV contains an Object Instance, a Resource, multiple Resources, or a Resource Instance. Object Instance and Resource with Resource Instance TLVs contains other TLVs in their value. The hierarchy is as follows and may be up to 3 levels deep.

• Object Instance TLV, which contains

  • Resource TLVs or

  • multiple Resource TLVs, which contains

    • Resource Instance TLVs

For simplicity and to prevent any ambiguity on Object Instance Identity, when the Object Instance ID is not specified in the request, the Object Instance TLV MUST be used, whatever the number of Object Instances (1 or more) to return to the LwM2M Server.

When a Multiple Resource has to be returned to the LwM2M Server, the Multiple Resource TLV MUST be used whatever the number of Instances (0, 1 or more) of that resource.

The following figure illustrates the possible nesting of Object Instance, Resource, multiple Resources, and Resource Instance TLVs. One or several Resource TLVs, and/or one or several multiple Resource TLVs MAY be nested in an Object Instance TLV. A multiple Resource TLV contains one or several Resource Instance TLVs.

7.4.2.1. Single Object Instance Request Example

In this example, a request for the Device Object Instance (ID:3) of a LwM2M client is made (Read /3/0). The client responds with a TLV payload including all of the readable Resources. This TLV payload would have the following format. The total payload size with the TLV encoding is 121 bytes:

C8 00 14 4F 70 65 6E 20 4D 6F 62 69 6C 65 20 41 6C 6C 69 61 6E 63 65
C8 01 16 4C 69 67 68 74 77 65 69 67 74 20 4D 32 4D 20 43 6C 69 65 6E 74
C8 02 09 33 34 35 30 30 30 31 32 33
C3 03 31 2E 30
86 06
   41 00 01
   41 01 05
88 07 08
   42 00 0E D8
   42 01 13 88
87 08
   41 00 7D
   42 01 03 84
C1 09 64
C1 0A 0F
83 0B
   41 00 00
C4 0D 51 82 42 8F
C6 0E 2B 30 32 3A 30 30
C1 10 55

7.4.2.2. Multiple Object Instance Request Examples

A) Request on Single-Instance Object

In this example, a request for the Device Object Instance (ID:3) of a LwM2M client is made (Read /3). The Device Object is a Single-Instance Object, but the Object Instance TLV is used (to be compared with the example of the previous section).

The client responds with a TLV payload including the Object Instance ID and all its readable Resources. This TLV payload would have the following value (indented for readability) and format. The total payload size with the TLV encoding is 124 bytes:

08 00 79
   C8 00 14 4F 70 65 6E 20 4D 6F 62 69 6C 65 20 41 6C 6C 69 61 6E 63 65
   C8 01 16 4C 69 67 68 74 77 65 69 67 74 20 4D 32 4D 20 43 6C 69 65 6E 74
   C8 02 09 33 34 35 30 30 30 31 32 33
   C3 03 31 2E 30
   86 06
      41 00 01
      41 01 05
88 07 08
   42 00 0E D8
   42 01 13 88
87 08
   41 00 7D
   42 01 03 84
C1 09 64
C1 0A 0F
83 0B
   41 00 00
C4 0D 51 82 42 8F
C6 0E 2B 30 32 3A 30 30
C1 10 55

B) Request on Multiple-Instance Object having 2 instances

In this example, a request on the Access Control Object (ID:2) of a LwM2M client is made (Read /2). The Access Control Object is a Multiple-Instance Object. In this simplified example, it has only 2 instances describing the access rights of two LwM2M Servers with Short IDs 127 and 310 on Objects Instances /1/0 and /3/0.

The client responds with a TLV payload including the 2 Object Instances (ID:0 and ID:2) and their Resources. This TLV payload would have the following value (indented for readability) and format. The total payload size with the TLV encoding is 38 bytes:

08 00 0E
   C1 00 01
   C1 01 00
   83 02
      41 7F 07
   C1 03 7F
08 02 12
   C1 00 03
   C1 01 00
   86 02 41 7F 07 61 01 36 01
   C1 03 7F

C) Request on Multiple-Instance Object having 1 instance only

In this example, a request to the Server Object Instances of a LwM2M client is performed (Read /1). The Server Object is a Multiple-Instances Object. The client has only one Server Object instance and will respond with a TLV payload including the single Object Instance (0) and their Resources. This TLV payload would have the following value (indented for readability) and format. The total payload size with the TLV encoding is 18 bytes:

08 00 0D
   C1 00 01
   C4 01 00 01 51 80
   C1 06 01
   C1 07 55

7.4.2.3. Example of Request on an Object Instance containing an Object Link Resource

Examples are based on the LwM2M Object Tree illustration presented in Figure: C.-1 Object link Resource simple illustration. The TLV format doesn't report the object hierarchy.

Example 1) request to Object 65 Instance 0: Read /65/0

88 00 0C
   44 00 00 42 00 00
   44 01 00 42 00 01
C8 01 0D 38 36 31 33 38 30 30 37 35 35 35 30 30
C4 02 12 34 56 78

Example 2) request to Object 66: Read /66: TLV payload will contain 2 Object Instances

08 00 23
   C8 00 0B 6D 79 53 65 72 76 69 63 65 20 31
   C8 01 0F 49 6E 74 65 72 6E 65 74 2E 31 35 2E 32 33 34
   C4 02 00 43 00 00
08 01 23
   C8 00 0B 6D 79 53 65 72 76 69 63 65 20 32
   C8 01 0F 49 6E 74 65 72 6E 65 74 2E 31 35 2E 32 33 35
   C4 02 FF FF FF FF

7.4.3. JSON

When a LwM2M Client is supporting the JSON data format and the format is used to transport Object Instance(s), multiple resource and single resource values for both "Read" and "Write" operations, JSON payload MUST use the format defined in this section. This format MAY be used also for transporting a single value of a Resource.

The format MUST comply to [SENML] JSON representation extended for supporting LwM2M Object Link data type and MUST support all attributes defined in Table: 7.4.3.-1 JSON format and description.

According to [SENML] semantics, the JSON data format is composed of an array of entries (SenML Records) with optional and mandatory fields.

Each entry of the JSON format is a Resource Instance, where the Name attribute need to be prepended by the Base Name attribute to form the unique identifier of this Resource instance.

The Name attribute in an entry is a URI path relative to the Base Name; namely the Name attribute could simply be the full URI path of a requested Resource Instance when Base Name is absent.

The JSON format is useful for transporting multiple Resource Instances for example when transporting all Instances of an Object with all Resources, and Resource Instances within a single LwM2M Client response.

In particular, when Base Name is set to the LwM2M Object root (e.g. "/"), the JSON format may support to return a hierarchy of Object Instances when Object Link datatype resources are reported (example given below). The resource instances tree report is performed in using a Breadth-First traversal strategy (see JSON second example below); a given Object Instance MUST appear at most once in that report. The JSON format also includes optional time fields, which allows for multiple versions of representations to be sent in the same payload. The time fields MUST only be used when sending notifications.

Note: SenML time values (Base Time and Time) are represented in floating point as seconds and a missing time attribute is considered to have a value of zero. Base time and time are added together. In general, positive time values represent an absolute time relative to the Unix epoch, while negative values represent a relative time in the past from the current time. For details see [SENML].

Historical version of notifications are typically generated when "Notification Storing When Disabled or Offline" resource of the LwM2M Server Object is set to true (see Appendix E. LwM2M Objects defined by OMA (Normative)) and when the Device comes on line after having been disabled for a period of time.

The JSON data format has a Media Type application/senml+json.

The [LwM2M-TS_1.0] defined the format for application/vnd.oma.lwm2m+json based on an early draft version of SenML. The LwM2M TS 1.1 aligns the JSON format with the final version of the SenML specification.

For backward compatibility, server implementations of LwM2M TS 1.1 MUST support both application/senml+json and application/vnd.oma.lwm2m+json. Client implementations of LwM2M TS 1.1 and later MUST NOT use the application/vnd.oma.lwm2m+json format.

For example a request to Device Object of the LwM2M example client (Read /3/0) would return the following JSON payload. This example has a size of 399 bytes.

For example, a notification about a Resource containing multiple historical representations of a Temperature Resource (ID:2) (e.g. Instance ID:1 of hypothetical Object ID 72) could result in the following JSON payload:

For example, a request to Object 65 of the LwM2M example seen in Figure: C.-1 Object link Resource simple illustration (Read /65/0) would return the following JSON payload.

Because the Base Name is specified, the full hierarchy linked to the Instance 0 of Object 65 can be reported in a single response (Object 66 Instance 0 & 1, and Instance 0 of Object 67 are part of the payload). This example has a size of 412 bytes.

For example, a request to Device Object on Resource 0 of the LwM2M example client (Read /3/0/0) could return the following JSON payload.

For example a server Read-Composite request to the client to read manufacturer name and battery level from device object together with registration lifetime from the server object will look like

In response to the above Read-Composite request the client will return a JSON payload similar to the following

For example a server Write-Composite to switch off 2 light sources, dim a 3rd to 20% and set the thermostat to 18 degrees will have a JSON payload as shown in table below. Lights are all controlled by instances of IPSO Light Control Object (Object ID 3311), while thermostat is controlled by an instance of IPSO object Set Point (Object ID 3308).

7.4.3.1. LwM2M TS 1.0 JSON format

The JSON format used by the LwM2M TS 1.0 with media type application/vnd.oma.lwm2m+json is formally defined in [LwM2M-TS_1.0]. The JSON payload shown below is an example reply to a request to the Device Object of the LwM2M example Client ("Read /3/0").

7.4.4. CBOR

When a LwM2M Client is supporting the CBOR data format and that format is used to transport Object Instance(s), multiple resource and single resource values for both "Read" and "Write" operations, the CBOR payload MUST use the format defined in Section 6 of [SENML]. The same format MAY be used for transporting a single value of a Resource. The object links use a string map key "vlo" also in CBOR representation.

The example from Table: 7.4.3.-2 Return JSON payload from example request to Device Object of the LwM2M example client (Read /3/0) is shown below in the CBOR format.

90 a3 21 65 2f 33 2f 30 2f 00 61 30 03 74 4f 70
65 6e 20 4d 6f 62 69 6c 65 20 41 6c 6c 69 61 6e
63 65 a2 00 61 31 03 76 4c 69 67 68 74 77 65 69
67 68 74 20 4d 32 4d 20 43 6c 69 65 6e 74 a2 00
61 32 03 69 33 34 35 30 30 30 31 32 33 a2 00 61
33 03 63 31 2e 30 a2 00 63 36 2f 30 02 01 a2 00
63 36 2f 31 02 05 a2 00 63 37 2f 30 02 19 0e d8
a2 00 63 37 2f 31 02 19 13 88 a2 00 63 38 2f 30
02 18 7d a2 00 63 38 2f 31 02 19 03 84 a2 00 61
39 02 18 64 a2 00 62 31 30 02 0f a2 00 64 31 31
2f 30 02 00 a2 00 62 31 33 02 1a 51 82 42 8f a2
00 62 31 34 03 66 2b 30 32 3a 30 30 a2 00 62 31
36 03 61 55 

For details see Appendix M. CBOR Example (Informative).

The same example using the CBOR diagnostic notation is shown below.

[{-2: "/3/0/", 0: "0", 3: "Open Mobile Alliance"}, 
{0: "1", 3: "Lightweight M2M Client"}, 
{0: "2", 3: "345000123"}, 
{0: "3", 3: "1.0"}, 
{0: "6/0", 2: 1}, 
{0: "6/1", 2: 5}, 
{0: "7/0", 2: 3800}, 
{0: "7/1", 2: 5000}, 
{0: "8/0", 2: 125}, 
{0: "8/1", 2: 900}, 
{0: "9", 2: 100}, 
{0: "10", 2: 15}, 
{0: "11/0", 2: 0}, 
{0: "13", 2: 1367491215}, 
{0: "14", 3: "+02:00"}, 
{0: "16", 3: "U"}]

8. Access Control

The LwM2M Client MUST support the procedures described in this section.

As the LwM2M Client MAY support one or more LwM2M Servers, there is a need to determine which operation on a certain Object or Object Instance is authorized for which LwM2M Server. Access Control Object is designed for supporting that capability. However, when a single LwM2M Server Account exists in the LwM2M Client, the Access Control Object MAY not be instantiated.

A LwM2M Client can be configured to evolve in an "Access Control-Enabled" context in which the Client is capable of granting access rights on Resources to one or several LwM2M Servers; in this configuration the Access Control Object MUST have been instantiated. On the other side, a LwM2M Client can also be configured to evolve in an "Access Control-Disabled" context, where such a Client is only able to interact with a single Server, since the capability to manage access rights for LwM2M Resources is not supported (the Access Control Object has not been instantiated); in that context the Server MUST have full access rights on all the Objects and Object Instances in the LwM2M Client. For further reading, the following sections will simply mention "Access Control-Enabled" context and "Access Control-Disabled" context for referring to such a context notion. Note: in an "Access Control-Enabled" context, it is fully acceptable of a having a LwM2M Client connected to one Server only.

The section 8.2. Authorization applies to both "Access Control-Enabled" and "Access Control-Disabled" contexts.

8.1. Access Control Object

8.1.1. Access Control Object overview

In the presence of several LwM2M Servers, there is a need to determine if a certain LwM2M Server is authorized to instantiate a supported Object in the LwM2M Client. This kind of authorization can only be managed during a Bootstrap Phase.

Furthermore, the LwM2M Client needs to determine - per supported Object Instance - who the "Access Control Owner" of that Object Instance is and which access rights have been granted to other LwM2M Servers likely to interact with that LwM2M Client on such Object Instance.

The Access Control Object is specified in E.3 LwM2M Object: Access Control and Examples of Access Control Object Instances are presented in Appendix F. Example LwM2M Client (Informative).

8.1.2. Access Control Object Management

8.1.2.1. Access Control on Object

To authorize a LwM2M Server to instantiate a certain Object supported by the LwM2M Client, not only an Access Control Object Instance - as defined in the table below - MUST be associated to such an Object, but this AC Object Instance MUST also contained an ACL Resource Instance targeting the authorized LwM2M Server.

This kind of Access Control Object Instance associated with a certain Object, MUST only be created or updated during a Bootstrap Phase. The absence of such an association for a certain Object, prevents this Object to be instantiated by any LwM2M Server.

When such an Access Control Object Instance already exists for a certain Object, this Access Control Object Instance MAY be updated for supporting additional LwM2M Servers; in that case a new ACL Instance per Server is created in that Access Control Object Instance with the Short Server ID of the LwM2M Server as index of this new ACL Instance, and with the "Create" ("C") access right as ACL Resource value.

8.1.2.2. Access Control on Object Instance

For being able to register which operations MAY be performed on an Object Instance by a certain LwM2M Server, this Object Instance MUST be associated to an Access Control Object Instance as defined in the table below.

This kind of Access Control Object Instance associated with a certain Object Instance, MAY be created or updated either during a Bootstrap Phase or through the Device Management and Service Enablement Interface.

In particular:

• when a LwM2M Server creates under authorization an Object Instance (see section 8.2. Authorization) in the LwM2M Client, an Access Control Object Instance MUST be created in the LwM2M Client with the Resources values which MUST be set as given in the table just below. The Access Control Owner Resource is configured with the Short Server ID of the LwM2M Server.

• when this Access Control Object Instance is created during the Bootstrap Phase, ACL(s) and Access Control Owner MUST be set with values respecting the consistency of the LwM2M Client configuration.

• through the Device Management and Service Enablement Interface, an Access Control Object Instance MUST only be managed by the LwM2M Server declared as the "Access Control Owner" in it.

• when the LwM2M Server - which is the "Access Control Owner" - adds or modifies (using "Write" operation) access right on the Object Instance for a certain LwM2M Server,

  1. an ACL Resource having the targeted Short Server ID as ACL Resource Instance ID, has to be instantiated by the LwM2M Client if ACL Resource Instance for the LwM2M Server doesn't exist yet

  2. the appropriate access right (R,W,D,E) for that targeted Server on the Object Instance has to be set as ACL Resource Instance value

• A specific ACL Resource Instance MAY be used to grant access rights to LwM2M Servers (except the one defined as the Access Control Owner) which don't have their own ACL Resource Instance. The ID of this ACL Resource Instance containing the default access rights MUST be 0.

• when an Object Instance is removed via "Delete" operation performed by the LwM2M Server which is the "Access Control Owner", the associated Access Control Object Instance MUST be removed by the LwM2M Client.

The Figure: 8.1.2.2.-1 Illustration of the relations between the LwM2M Access Control Object and the other LwM2M Objects illustrates the Access Control Management of an Object Instance (/X/2) supported by a LwM2M Client. An Access Control Object Instance (/2/Y) is declared in ② which defines the Access Rights applicable to the Instance 2 of the Object X pointed in ①.

In this Access Control Object Instance ②, 4 Instances of the ACL Resource are defined:

• ACL Instance 101 contains the operations granted to the Server having 101 as Short ID (Instance ID:2 of the Server Object ID:1 as pointed in ③)

• ACL Instance 22 contains the operations granted to the Server having 22 as Short ID

• ACL Instance 31 contains the operations granted to the Server having 31 as Short ID

• ACL Instance 0 contains the operations granted by default to any Server for which a specific ACL Instance is not defined in this Instance of the Access Control Object (default Access Rights).

This Access Control Object Instance ② also contains a reference to a Server (Access Control Owner) which is the only one Server authorized to manage that Instance of the Access Control Object.

8.1.3. LwM2M Access Control Context Switch

In an "Access Control-Disabled" context, the Access Control Object is not instantiated. In that case, adding a new LwM2M Server Account, requires the LwM2M Client to switch from the current "Access Control-Disabled" context to an "Access Control-Enabled" context which means the Access Control Object MUST be instantiated. This context switch must be managed in a Bootstrap Phase.

Note: The Bootstrap Discover command allows to retrieve data regarding the configuration of the initial "Access Control-Disabled" context (list of Objects, Object Instances and Short Server IDs). The Bootstrap-Server has then all information to setup a proper "Access Control-Enabled" context from the initial context one.

8.2. Authorization

For authorizing an operation to proceed on Object Instance(s) or Resource(s), the LwM2M Client MUST:

1. obtain the access rights for the involved Object Instances:

• in "Access Control-Disabled" context, full access rights are granted to the LwM2M Server
• in "Access Control-Enabled" context, access rights MUST be granted to the LwM2M Server according to the section 8.2.1. Obtaining Access Right

2. check if that access rights granted to the Server are sufficient for the requested operation according to the Table: 8.2.-1 Authorization below
3. verify –when the check in 2. on access rights is successful– if the requested operation is supported by the targeted Resource(s) (details are provided in Sections 8.2.2. Operation on Resource(s) and Object Instance(s), and 8.2.3. Operation on Object).

The LwM2M Object specification defines which operations are allowed to be performed on Resource within an Object Instance (Refer to Supported Operations in [LwM2M Object Template and Guidelines]. The operations allowed on a given Resource MUST apply to all the Resource Instances of that Resource.

8.2.1. Obtaining Access Right

In "Access Control-Disabled" context, the LwM2M Server get full access rights.

In "Access Control-Enabled" context:

• for "Create" operation sent by the LwM2M Server, the LwM2M Client MUST get the access right from the ACL Resource Instance corresponding to this LwM2M Server and located in the Access Control Object Instance associated to the targeted Object. Such an Access Control Object Instance – if it exists – has been provisioned during a Bootstrap Phase (Access Control Owner is MAX_ID=65535). If this access right does not have the "Create" value, or cannot be obtained, the LwM2M Server has no access right.

• For operations, except the "Create" operation, the LwM2M Client MUST retrieve the Access Control Object Instance associated with the Object Instance the LwM2M Server has requested access to, and MUST proceed according to the sequence below:

  1. If the LwM2M Server is declared as the Access Control Owner of this Object Instance and there is no ACL Resource Instance for that LwM2M Server, then the LwM2M Client gets full access right.

  2. If the LwM2M Client has an ACL Resource Instance for the LwM2M Server, the LwM2M Client gets the access right from that ACL Resource Instance.

  3. If the LwM2M Server is not declared as the Access Control Owner of this Object Instance and the LwM2M Client does not have the ACL Resource Instance for that Server, the LwM2M Client gets the access right from the ACL Resource Instance (ID:0) containing the default access rights if it exists (Section 8.1.2.2. Access Control on Object Instance).

  4. If the LwM2M Client does not have the ACL Resource Instance ID:0 containing the default access rights, then the LwM2M Server has no access rights.

  5. In case of a Composite operation (Read-Composite, Write-Composite, Observe-Composite), the previous four conditions apply to determine the access right for any Object Instance targeted by the Composite Operation. Composite operations have additional characteristics to determine the final access right granted to the LwM2M Server:

  • due to the atomic nature of the Write-Composite operation, all Object Instances involved in that command MUST have the "Write" access right granted to the requesting LwM2M Server to establish that the "Write" access right is globally granted to such a LwM2M Server for that operation; otherwise, the LwM2M Server has no access right granted.
  • due to the non-atomic nature of the Read-Composite and Observe-Composite operations, any Object Instance involved in the requested operation which has no "Read" access right granted to the requesting LwM2M Server MUST be ignored. If at least one of the Object Instances involved in the requested operation has a "Read" access right granted to the LwM2M Server, the "Read" access right is globally granted to such a LwM2M Server for that operation; otherwise the LwM2M Server has no access right granted.

8.2.2. Operation on Resource(s) and Object Instance(s)

When the LwM2M Server targets Resource(s) or Object Instance(s) in a command, the LwM2M Client MUST obtain an access right for that Server on the Object Instance(s) involved in that operation according to Section 8.2.1. Obtaining Access Right. The LwM2M Client MUST then check if the access right is granted prior to performing the requested operation.

• If the operation is not permitted, the LwM2M Client MUST send an "Unauthorized" error code to the LwM2M Server.

• If the operation is permitted, the following cases apply, according to the requested operation:

• for the "Write" and "Write-Composite" operations, the LwM2M Client MUST perform the operation, only if all the Resources conveyed in the operation are allowed to support the "Write" operation. If any Resource does not support the "Write" operation, the LwM2M Client MUST inform the LwM2M Server that the Object Instance cannot perform the requested operation by sending a "Method not allowed" error code.

• for the "Read" and "Observe" operations, the LwM2M Client MUST retrieve all the Resources except the Resource(s) which doesn't support the "Read" operation and sends the retrieved Resource(s) information to the LwM2M Server.

• for the "Read-Composite" and "Observe-Composite" operations, and for all Object Instances which have not been ignored during the access right determination (Section 8.2.1. Obtaining Access Right), the LwM2M Client MUST retrieve all the requested Resources supporting the "Read" operation and sends such retrieved Resource(s) information to the LwM2M Server.

• for the "Execute" operation, the LwM2M Client MUST NOT perform the operation, and MUST send an "Operation is not supported" error code to the LwM2M Server.

• for the "Delete", "Write-Attributes", and "Discover" operations, the LwM2M Client MUST perform the operation.

8.2.3. Operation on Object

If a given LwM2M Server targets an Object with a "Write", "Execute", or "Delete" operation, the LwM2M Client MUST NOT perform such an operation and MUST send a "Method Not Allowed" error code to the LwM2M Server.

• When the LwM2M Server targets an Object for the "Create" operation, the LwM2M Client MUST obtain an access right for the LwM2M Server on Object according to Section 8.2.1. Obtaining Access Right and MUST check if the access right is granted prior to perform the requested operation.

  If the "Create" operation is permitted, the LwM2M Client MUST perform the instantiation on the Object only if all the mandatory Resources are present in the "New Value" parameter (see Section 6. Interfaces). If all the mandatory Resources are not present, the LwM2M Client MUST send a "Bad Request" error code to the LwM2M Server.

  Optional Resources MAY be conveyed in the "New Value" parameter as well; the LwM2M Client MAY ignore the optional resources it doesn't support. The values of the Read-only Resources MUST be setup by the LwM2M Client only; if a value of such a Read-only Resource is present in the "New Value" parameter, this value MUST simply be ignored. If the payload (New Value) conveys an Object Instance ID in conflict with one already present in the LwM2M Client, the complete request MUST be rejected and a "Bad Request" error code MUST be sent back.

• The "Discover" operation on Object is specific in the sense, that no access right is needed; the LwM2M Client MUST perform the operation.

• For the "Read" and "Observe" operations, the LwM2M Client MUST obtain the access right for the LwM2M Server on each Object Instance according to Section 8.2.1. Obtaining Access Right and the LwM2M Client MUST retrieve all the Object Instances for which the LwM2M Server has "Read" access right; for each of these qualified Object Instances, the LwM2M Client MUST retrieve all the Resources except the Resources which do not support the "Read" operation. The LwM2M Client MUST then aggregate all the information individually produced by the operation on each of these Object Instances and send that to the LwM2M Server.

• For the "Write-Attributes" operation, the LwM2M Client MUST perform the operation.

8.2.4. Notify Operation Consideration

If the LwM2M Client needs to send a "Notify" operation containing an Object Instance or a Resource to the LwM2M Server, the LwM2M Client MUST check if the LwM2M Server is authorized for the "Read" operation. If the LwM2M Server is not authorized, the Client MUST NOT send the "Notify" operation.

Appendix A. Change History (Informative)

A.1 Approved Version History

Appendix B. Static Conformance Requirements (Normative)

Static Conformance Requirements are addressed in the LwM2M ETS.

Appendix C. Data Types (Normative)

This appendix defines the data types that a Resource can be defined to be.

Appendix D. LwM2M Object Template and Guidelines (Normative)

This Appendix provides the template to be used for the specification of LwM2M Objects. Furthermore, guidelines for the creation of LwM2M Objects are provided.

The XML versions of LwM2M Objects MUST comply with the XML schema which can be found here: http://openmobilealliance.org/tech/profiles/LWM2M.xsd

D.1 Object Template

Appendix LwM2M Object: <LwM2M object name>

Description

Object definition:

• Name: specifies the Object name.

• Object ID: specifies the Object ID.

• Instances: indicates whether this Object supports multiple Object Instances or not. If this field is “Multiple” then the number of Object Instance can be from 0 to many. If this field is “Single” then the number of Object Instance can be from 0 to 1. If the Object field “Mandatory” is “Mandatory” and the Object field “Instances” is “Single” then, the number of Object Instance MUST be 1.

• Mandatory: if this field is “Mandatory”, then the LwM2M Client MUST support this Object. If this field is “Optional”, then the LwM2M Client SHOULD support this Object.

• Object URN: specifies the Object URN. The format of the Object URN is “urn:oma:lwm2m:{oma,ext,x}:{Object ID}[:{version}]” and {} part means that those values are variable and filled with real value. For example, Object URN of LwM2M Server Object is “urn:oma:lwm2m:oma:1”. The “version” field, follows the rules specified in Section 6.2 related to Object Versioning Policy.

Resource definition:

• ID: specifies the Resource ID which is unique within Object.

• Name: specifies the Resource name.

• Operations: indicates which operations the Resource supports in the “Device Management & Service Enablement” Interface. This field can be set to a combination of R (Read, Observe, Discover, Write-Attributes), and W (Write), or can be set to E (Execute); Executable Operation is exclusive regarding the two others (R, W). This field may also have an empty value, which means that this field is not allowed to be accessed via “Device Management & Service Enablement” Interface but allowed to be accessed via “Bootstrap” Interface.

• Instances: indicates whether this Resource supports multiple Resource Instances or not. If this field is “Multiple” then the number of Resource Instance can be from 0 to many. If this field is “Single” then the number of Resource Instance can be from 0 to 1. If the Resource field “Mandatory” is “Mandatory” and the field “Instances” of the Resource is “Single” then, the number of Resource Instance MUST be 1. Resource which supports “Execute” operation MUST have “Single” as value of the “Instances” field.

• Mandatory: if this field is “Mandatory”, then any Instance of the Object that Resource belongs to, MUST instantiate such a Resource (refer Section 6.1, Resource Model). If this field is “Optional”, then this Resource MAY be omitted from some - or even all - Instances of the Object that Resource belongs to.

• Type: Data Type indicates the type of Resource value. Data Types used in this enabler are described in Appendix C Data Types. Resource which supports “Execute” operation MUST have no associated Data Type (none) encoded as an empty value in Object DDF file.

• Range or Enumeration: this field limits the value of Resource.

• Units: specifies the unit of the Resource value.

• Description: specifies the Resource description.

In addition to the object and resource definition tables, an object containing Executable Resource(s) is specified in third Table, gathering the definition of the arguments of all the Executable Resources of that Object.

This table provides the properties of arguments

Example of an Executable Resource Arguments Definition Table for an Object having 3 Executable Resource

D.2 Open Mobile Naming Authority (OMNA) Guidelines

This appendix defines guidelines for OMNA regarding registries and protocol ID ranges to be maintained.

D.2.1 Object Registry

LwM2M Objects must be registered with the OMNA Lightweight Object registry. The rules for Object registry are documented at: http://www.openmobilealliance.org/wp/OMNA/LwM2M/LwM2MRegistry.html

The URN format for an Object is automatically built from the class of Object, the Object ID and potentially the Object Version (see Section 6.2 Object Versioning) as follows:

urn:oma:lwm2m:{oma,ext,x}:{Object ID}[:{version}].

D.2.2 Resource Registry

LwM2M Objects are specified as being composed of Resources, each identified by a Resource ID. Resources can either be specific to each Object with meaning only when used in that Object, or Reusable Resources can be registered, assigned an ID from the OMNA range and re-used in any Object.

The rules for registering Resource are documented at: http://www.openmobilealliance.org/wp/OMNA/LwM2M/LwM2MRegistry.html

Appendix E. LwM2M Objects defined by OMA (Normative)

This appendix provides LwM2M Objects defined by OMA SpecWorks that are a core part of the LwM2M specification. Other organizations and companies may define additional LwM2M Objects according to the guidelines provided in Appendix Appendix D. LwM2M Object Template and Guidelines (Normative).

The following LwM2M Object descriptions are contained in this appendix of the LwM2M v1.1 specification. Other objects can also be used with this version of LwM2M v1.1 and can be found in the OMNA registry.

The LwM2M Server MUST support the Security, Server, and Device Objects. The LwM2M Server SHOULD support the Access Control, Connectivity, Firmware Update, Location, and Connectivity Statistics Objects.

E.1 LwM2M Object: LwM2M Security

Description

This LwM2M Object provides the keying material of a LwM2M Client appropriate to access a specified LwM2M Server. One Object Instance SHOULD address a LwM2M Bootstrap-Server. These LwM2M Object Resources MUST only be changed by a LwM2M Bootstrap-Server or Bootstrap from Smartcard and MUST NOT be accessible by any other LwM2M Server.

Object definition

Resource definitions

E.2 LwM2M Object: LwM2M Server

Description

This LwM2M Objects provides the data related to a LwM2M Server. A Bootstrap-Server has no such an Object Instance associated to it.

Object definition

Resource definitions

E.3 LwM2M Object: Access Control

Description

Access Control Object is used to check whether the LwM2M Server has access right for performing an operation.

Object definition

Resource definitions

E.4 LwM2M Object: Device

Description

This LwM2M Object provides a range of device related information which can be queried by the LwM2M Server, and a device reboot and factory reset function.

Object definition

Resource definitions

E.5 LwM2M Object: Connectivity Monitoring

Description

This LwM2M Object enables monitoring of parameters related to network connectivity. In this general connectivity Object, the Resources are limited to the most general cases common to most network bearers. It is recommended to read the description, which refers to relevant standard development organizations (e.g. 3GPP, IEEE). The goal of the Connectivity Monitoring Object is to carry information reflecting the more up to date values of the current connection for monitoring purposes. Resources such as Link Quality, Radio Signal Strength, Cell ID are retrieved during connected mode at least for cellular networks.

Object definition

Resource definitions

E.6 LwM2M Object: Firmware Update

Description

This LwM2M Object enables management of firmware which is to be updated. This Object includes installing a firmware package, updating firmware, and performing actions after updating firmware. The firmware update MAY require to reboot the device; it will depend on a number of factors, such as the operating system architecture and the extent of the updated software. The envisioned functionality is to allow a LwM2M Client to connect to any LwM2M Server to obtain a firmware image using the object and resource structure defined in this section experiencing communication security protection using TLS/DTLS. There are, however, other design decisions that need to be taken into account to allow a manufacturer of a device to securely install firmware on a device. Examples for such design decisions are how to manage the firmware update repository at the server side (which may include user interface considerations), the techniques to provide additional application layer security protection of the firmware image, how many versions of firmware images to store on the device, and how to execute the firmware update process considering the hardware specific details of a given IoT hardware product. These aspects are considered to be outside the scope of this version of the specification. A LwM2M Server may also instruct a LwM2M Client to fetch a firmware image from a dedicated server (instead of pushing firmware images to the LwM2M Client). The Package URI resource is contained in the Firmware object and can be used for this purpose. A LwM2M Client MUST support block-wise transfer [CoAP_Blockwise] if it implements the Firmware Update object. A LwM2M Server MUST support block-wise transfer. Other protocols, such as HTTP/HTTPs, MAY also be used for downloading firmware updates (via the Package URI resource). For constrained devices it is, however, RECOMMENDED to use CoAP for firmware downloads to avoid the need for additional protocol implementations.

Object definition

Resource definitions

E.6.1 Firmware Update State Machine

Figure: E.6.1-1 Firmware Update Mechanisms shows a possible implementation of the firmware update mechanism, described as a UML 2.0 state diagram. The state diagram consists of states, drawn as rounded rectangles, and transitions, drawn as arrows connecting the states. The syntax of the transition is trigger [guard] / behaviour. A trigger is an event that may cause a transition, guard is a condition and behaviour is an activity that executes while the transition takes place. The states additionally contain a compartment that includes assertions and variable assignments. For example, the assertion in the IDLE state indicates the value of the “Update Result” resource (abbreviated as “Res”) must be between 0 and 9. The State resource is set to zero (0) when the program is in this IDLE state.

Errors during the Firmware Update process MUST be reported only by the “Update Result” resource. For instance, when the LwM2M Server performs a Write operation on resource “Package URI”, the LwM2M Client returns a Success or Failure for the Write operation. Then if the URI is invalid, it changes its “Update Result” resource value to 7.

E.6.2 Examples

The example depicted in Figure: E.6.2-1 Example of a LwM2M Server pushing a firmware image to a LwM2M client illustrates a successful message exchange where a LwM2M Server pushes a firmware image to a LwM2M Client using the block-wise transfer. In this example the LwM2M Server indicates a block size of 128 bytes and the firmware image of 80 KiB (=81920 bytes) will be sent to the LwM2M Client in 640 messages with each 128 bytes payload. Since the LwM2M Server-provided block size matches the preferences of the LwM2M Client the exchange proceeds until the full firmware image is downloaded. In this example, no messages are lost during transmission.

The second example shown in Figure: E.6.2-2 Example of a client fetching a firmware image illustrates the case where the client was provided with a URI by the LwM2M Server (using the Package URI resource) and therefore fetches the firmware image from the indicated server. Note that only the retrieval of the firmware image from the LwM2M Server is shown in Figure: E.6.2-2 Example of a client fetching a firmware image and not the initial configuration of the Package URI.

E.6.3 Firmware Update Consideration

If some Objects are not supported after firmware update, the LwM2M Client MUST delete all Object Instances of the Objects that are not supported.

E.7 LwM2M Object: Location

Description

This LwM2M Objects provide a range of device related information which can be queried by the LwM2M Server, and a device reboot and factory reset function.

Object definition

Resource definitions

E.8 LwM2M Object: Connectivity Statistics

Description

This LwM2M Objects enables client to collect statistical information and enables the LwM2M Server to retrieve these information, set the collection duration and reset the statistical parameters.

Object definition

Resource definitions

Note: When reporting the Tx Data or Rx Data, the LwM2M Client reports the total KB transmitted/received over IP bearer(s), including all protocol header bytes up to and including the IP header. This does not include lower level retransmissions/optimizations (e.g. RAN, header compression) or SMS messages.

E.9 LwM2M Object: OSCORE

Description

This LwM2M Object provides the keying material and related information of a LwM2M Client appropriate to access a specified LwM2M Server using OSCORE. One Object Instance MAY address a LwM2M Bootstrap-Server. These LwM2M Object Resources MUST only be changed by a LwM2M Bootstrap-Server or Bootstrap from Smartcard and MUST NOT be accessible by any other LwM2M Server. Instances of this Object are linked from Instances of Object 0 using the OSCORE Security Mode Resource of Object 0. Instances of this Object MUST NOT be linked from more than one Instance of Object 0.

Object definition

Resource definitions

Appendix F. Example LwM2M Client (Informative)

This appendix defines an example LwM2M Client for a simple imaginary device with a cellular interface including instantiated Objects and their values, which are used throughout this specification in examples. The example client uses no Endpoint Client Name at the LwM2M messaging layer since the underlying security mechanisms already provide an authenticated identity.

The example device has two Server Objects (it is configured to register with two different LwM2M Servers), five accompanying Access Control Object Instances for those servers, a Device Object, a Connectivity Monitoring Object for a Cellular interface and a Firmware Update Object with no instance. The first Server controls the access control rights for both servers.

The Short Server ID 101 & 102, are respectively associated to the Server 1 and Server 2;

*: The client public key in text representation:

   0  89: SEQUENCE {
  2  19:   SEQUENCE {
  4   7:     OBJECT IDENTIFIER ecPublicKey (1 2 840 10045 2 1)
 13   8:     OBJECT IDENTIFIER prime256v1 (1 2 840 10045 3 1 7)
       :     }
 23  66:   BIT STRING
       :     04 A0 9D CB 1B C7 39 E7 F1 9A FA 9A DC B1 94 49
       :     68 BF BA 73 EF CE C2 9B 50 48 6E B4 4D 1B 29 C1
       :     93 44 99 70 A3 73 68 30 CB 2B D5 D7 EC 05 D2 BD
       :     1F C0 7B 6D F5 E4 8B 54 CE 77 A6 A7 22 9C 3A 91
       :     C2
       :   }

**: The server public key in text representation:

 0  89: SEQUENCE {
  2  19:   SEQUENCE {
  4   7:     OBJECT IDENTIFIER ecPublicKey (1 2 840 10045 2 1)
 13   8:     OBJECT IDENTIFIER prime256v1 (1 2 840 10045 3 1 7)
       :     }

 23  66:   BIT STRING
       :     04 82 C7 73 F3 78 D3 0C 27 83 A4 8E B8 11 B9 6C
       :     F6 A9 06 94 A8 56 4F 1E 7F 6D 36 61 52 F1 16 98
       :     95 0F 6F 7C 40 CD A5 85 33 4F 83 77 50 A1 02 F5
       :     BF 25 50 8C EB 9E 55 DF C0 F1 2A 45 51 99 A4 C9
       :     60
       :   }

***: The client private key in text representation:

 0 119: SEQUENCE {
  2   1:   INTEGER 1
  5  32:   OCTET STRING
       :     9F 35 2D A1 64 95 74 8E 14 6F CB 53 70 B8 E9 6D
       :     29 2C ED 55 67 A8 FA E5 5A 22 BB 67 D9 16 51 B8
 39  10:   [0] {
 41   8:     OBJECT IDENTIFIER prime256v1 (1 2 840 10045 3 1 7)
       :     }
 51  68:   [1] {
 53  66:     BIT STRING
       :       04 A0 9D CB 1B C7 39 E7 F1 9A FA 9A DC B1 94 49
       :       68 BF BA 73 EF CE C2 9B 50 48 6E B4 4D 1B 29 C1
       :       93 44 99 70 A3 73 68 30 CB 2B D5 D7 EC 05 D2 BD
       :       1F C0 7B 6D F5 E4 8B 54 CE 77 A6 A7 22 9C 3A 91
       :       C2
       :     }
       :   }

The example above has been created as follows, as illustrated using the Server Public Key resource example. If the hex sequence of the Server Public Key resource is pasted into a text file with the name example.hex. Here is the content of example.hex: '3059301306072a8648ce3d020106082a8648ce3d0301070342000482c773f378d30c2783a48eb811b96cf6a90694a8564f1e7f6d366152f11698950f6f7c40cda585334f837750a102f5bf25508ceb9e55dfc0f12a455199a4c960'

Then, the hex data needs to be convered into a binary using the Linux xxd command:

xxd -r -p example.hex >public-key.pub

Finally, the binary needs to be interpreted as a public key using the Linux dumpasn1 command:

dumpasn1 public-key.pub

Appendix G. Storage of LwM2M Bootstrap Information on the Smartcard (Normative)

This appendix aims at specifying the storage of the LwM2M Bootstrap Information in a PKCS#15 file structure within an UICC Smartcard platform [ETSI TS 102.221].

G.1 File structure

The information format is based on [PKCS#15] specification. The Bootstrap data is located under the PKCS#15 directory allowing the card issuer to decide the identifiers and the file locations.

The [PKCS#15] specification defines a set of files.

MF (3F00)
|-EF DIR (2F00) --> reference PKCS\#15 Application & DF PKCS\#15
|-DF PKCS-15 
|-ODF           --> ref to DODF            (Default:5031)
|-DODF          --> ref EF LwM2M Bootstrap (Default:6030)
|-EF LwM2M Bootstrap --> Contains LwM2M Bootstrap Data 

Within the PKCS#15 application, the starting point to access the PKCS#15 files is the Object Directory File (ODF). The EF (ODF) contains pointers to other files,each one containing a directory over PKCS#15 objects of a particular class. (authentication objects, data objects, keys, certificates...). For the purpose of LwM2M Bootstrap capability, the EF(ODF) MUST contain an EF Record describing a DODF(Data Object Directory Files) in which is found the reference pointing to the LwM2M Bootstrap data.

• The EF (ODF) is described in G.3.2 Object Directory File, EF(ODF) and [PKCS#15].
• The EF (DODF-bootstrap) is described in G.3.3 Data Object Directory File, EF(DODF-bootstrap) and [PKCS#15].
• The EF (LwM2M Bootstrap data) is described in G.3.4 EF (LwM2M_Bootstrap).

G.2 Bootstrap Information on UICC

G.2.1 Access to the file structure

The selection of the PKCS#15 file structure or application is not within the scope of the specification and can be managed in different ways by the devices (Direct File Access using PKCS#15 AID , Indirect Access using EF Dir information).

However, the following sequence is a recommended way to perform the selection of the PKCS#15 application:

1. With only one PKCS#15 application present in the UICC, the device may send a SELECT command with the PKCS#15 AID (A0 00 00 00 63 50 4B 43 53 2D 31 35) as parameter (Direct Access). If the selection is successful, the device can start reading PKCS#15 files (ODF, DODF ..).
2. If the previous selection fails (or if it might have several PKCS#15 applications present in UICC), the device sends SELECT commands to access EFdir to locate an entry with the PKCS#15 AID. If only one matching entry is found, the device MUST select the PKCS#15 DF path from that entry, and then can start reading PKCS#15 files (ODF, DODF…). If several entries are matching, the device MUST look for the entry containing the OID related to LwM2M "2.23.43.9" see G.3 Files Description) and MUST then select the associated DODF where it will find the path for the searched EF(LwM2M Bootstrap).

G.2.2 Files Overview (example)

G.2.3 Access Method

UICC Commands Read Binary and Update Binary, as defined in [ETSI TS 102.221], are used to access bootstrap data.

G.2.4 Access Conditions

The Device is informed of the access conditions of provisioning files by evaluating the “private” and “modifiable” flags in the corresponding DODF-bootstrap files structure [PKCS#15].

For the M2M context, the flags mentionned above can be unset to prevent cardholder verification step through pin code. When more control is needed, the Secure Channel SHOULD be used Appendix H. Secure channel between Smartcard and LwM2M Device Storage for secure Bootstrap Data provisioning (Normative).

G.2.5 Requirements on the Device

To retrieve the Bootstrap Information from the UICC, the Device MUST perform the following steps:

• Select PKCS#15 file structure as recommended in G.2.1 Access to the file structure.
• if needed (single PKCS#15 application case) Read EF(ODF) to locate the EF(DODF-bootstrap),
• Read EF(DODF) and look for the OMA-LwM2M OID to locate the file containing the LwM2M_Bootstrap data,
• Read the LwM2M_Bootstrap file

G.3 Files Description

All PKCS#15 files defined, are binary files as specified in [ETSI TS 102.221] and encoded in DER Format [PKCS#15]. These files are read and updated using UICC Commands related to the application they belong to.

G.3.1 EF(DIR) - optional

When the optional EF (DIR) is used to locate the PKCS#15 files structure, one of its logical record MUST be of the following ASN.1 type with the specified [PKCS#15] tags :

• Application template Tag 0x61
• Application Identifier Tag 0x4F
• Path Tag 0x51
• Application label Tag 0x50
• data Object Tag 0x73 (Multiple PKCS#15 Application case)

DIREcord ::= [APPLICATION 1]  SEQUENCE {
   aid   [APPLICATION 15] OCTET STRING,
   label [APPLICATION 16] UTF8STRING OPTIONAL
   path  [APPLICATION 17] OCTET STRING
   ddo   [APPLICATION 19] DDO OPTIONAL // used in multiple PKCS\#15 Applications case and containing
                                       // OID & associated DODF path (see [Requirements on the Device]() & \[PKCS#15\])
}

Coding  example :
aid PKCS#15  =  A0 00 00 00 63 50 4B 43 53 2D 31 35    (Tag : 0x4F)
label                = “BOOTSTRAP”                     (Tag : 0x50)
path                 = 3F00/7F50                       (Tag : 0x51)

         61 22
              4F 0C A0 00 00 00 63 50 4B 43 53 2D 31 35
              50 08  42  4F 4F 54 53 54 52 41 50
              51 04  3F  00 7F 50

G.3.2 Object Directory File, EF(ODF)

The mandatory Object Directory File (ODF) ([PKCS#15], Section 5.5.1) contains pointers to other EFs, each one containing a directory of PKCS#15 objects of a particular class (Keys, Authentication, Data ..). The EF(ODF) File ID is specified in [PKCS#15](0x5031). The card issuer decides the file size. The EF (ODF) can be read but it MUST NOT be modifiable by the user.

The EF (ODF) is described below:

G.3.3 Data Object Directory File, EF(DODF-bootstrap)

This Data Object Directory File used as the entry point to the LwM2M Bootstrap data, MUST contains an oidDO entry [PKCS#15] with an OID that MUST be in the OMA-LwM2M scope.

The registered OID for this specification is: {joint-isu-itu-t(2) international-organizations(23) oma(43) oma-lwm2m(9) lwm2m_bootstrap(1)} (2.23.43.9.1).

According to [PKCS#15], the DODF MUST include a DataType with the oidDO entry. The DataType oidDO entry is defined as PKCS15Object {CommonDataObjectAttributes, NULL, OidDO}.

• The CommonDataObjectAttributes structure of the DODF DataType oidDO entry MAY contain an applicationName or an applicationOID. The applicationName and the applicationOID are informative in this specification (may be omitted).
• The OidDO structure of the DODF DataType oidDO entry MUST be present and MUST contain an id value set to the registered OID defined above and a value that is a path structure to the EF (LwM2M Bootstrap data).

This path structure is defined with the following ASN.1 syntax [PKCS#15]: Path ::= SEQUENCE { path OCTET STRING, index INTEGER (0..65535) OPTIONAL, length [0] INTEGER (0..65535) OPTIONAL } ( WITH COMPONENTS {..., index PRESENT, length PRESENT} | WITH COMPONENTS {..., index ABSENT, length ABSENT}) with “path” being the path to the EF (LwM2M Bootstrap data)

The File ID is described in the EF (ODF). The file size depends on the number of provisioning objects stored in the smartcard. Thus, the card issuer decides the file size.

G.3.4 EF (LwM2M_Bootstrap)

Only the card issuer can modify EF LwM2M_Bootstrap

This file size is limited to 32KB; the effective file size, in Bytes, is accessible from the File header.

In this file, the Bootstrap data relies on LwM2M TLV Data format specification.

The LwM2M specification already describes the TLV format for coding multiples instances and Resources of a given Object (7.4.2. TLV), this section will only detailed how to store a collection of LwM2M Objects in this EF LwM2M_Bootstrap file; each Object is coded with a header containing a LwM2M Object ID and its Object Version coded in one or 2 Bytes, a LwM2M-TLV coding the Object Instances as payload, and a length being the size in bytes of this payload (LwM2M-TLV of the Object Instances). Data are represented in network byte order (big endian).

Additionally, this Bootstrap data will have a 2 Byte header indicating the number of Objects contained in that file and another 2 Bytes for indicating the size of the full payload (size of the collection of LwM2M Objects).

Using a BNF-like description:

<bootstrap_data> ::= <number of objects> <size> <collection_of_lwm2m_objects>

<number of Objects> ::= HWORD

<size> ::= HWORD

<collection_of_lwm2m_objects> ::= <single_lwm2m_object>*

<single_lwm2m_object> ::= <lwm2m_object_ID> <object_version> <length_of_object> <lwm2m_object_instances>

<lwm2m_object_ID> ::= HWORD

<object_version> ::= IMPLICIT_VERSION | <other_version>

<other_version> ::= MAJOR_VERSION MINOR_VERSION ; value %x0205 means version 2.5

<length_of_object> ::= HWORD

<lwm2m_object_instances> ::= TLV data format as described in 7.4.2. TLV

HWORD ::= %x00-FFFF

IMPLICIT_VERSION ::= %x00 ; means version 1.0 or the Object is defined in the LwM2M Enabler

MAJOR_VERSION ::= %x01-FF

MINOR VERSION ::= %x00-FF

In reading and processing the data of this file, the LwM2M Client is then able to be configured with the Bootstrap Information and thus to access the LwM2M Server(s).

Appendix H. Secure channel between Smartcard and LwM2M Device Storage for secure Bootstrap Data provisioning (Normative)

During LwM2M Bootstrap procedure, sensitive data have to be provisioned in LwM2M Device.

When Bootstrap information comes from Smartcard, a Secure Channel SHOULD be established between the Smartcard and the LwM2M Client. When required this Secure Channel MUST follow the following recommendations provided by [GLOBALPLATFORM] [GP SCP03] which are illustrated below. The Bootstrap information will be retrieved from Smartcard as described in Appendix F. Example LwM2M Client (Informative) of this document with the modification the usage of introducing a secured transfer between the Smartcard and the Device: instead of using PKCS#15 application, a specific OMA-LwM2M Bootstrap application MUST be selected in the Smartcard (SELECT command). The File Structure where the LwM2M Bootstrap Data is located, MUST only be accessible if the Mutual Authentication of the GP SCP03 process has been satisfied.

The AID (0xA00000041200020000000000) of the OMA-LwM2M Bootstrap Application is composed of the OMA RID code (0xA000000412), and the OMA PIX code containing the LwM2M Application code (0x0002) and a specific code used by the application; this specific code is relative to the Bootstrap data retrieval (00 00 00 00 00)

Pre-requisite: the Smartcard and the LwM2M device have to share the same static Keys KEY_ENC, KEY_MAC, KEY_DEK as specified in [GLOBALPLATFORM] [GP SCP03]

These keys are provisioned in the Devices in using out-of-band methods.

The steps for the secured transfer are the following and are illustrated below Figure: H.-1 Bootstrap Information transfer from Smartcard to LwM2M Device using Secure Channel according to [GLOBALPLATFORM] [GP SCP03] [GP AMD_A]:

• The OMA-LwM2M Bootstrap application used for transferring the Bootstrap information is selected

• Secure Channel (mutual authentication) is established

• PKCS#15 flow as described in Appendix F. Example LwM2M Client (Informative) takes place for selecting and transferring the Bootstrap file from Smartcard to the Device: the sensitive Bootstrap data are transferred encrypted using the GP SCP03 Secure Channel. When the Mutual Authentication is not satisfied, access to the file structure will return an error code 6982 to the Device (Security status not satisfied).

As a general recommendation, in the process for retrieving the Bootstrap data from the Smartcard, the Device SHOULD firstly try to select the OMA-LwM2M Bootstrap application to activate the [GP SCP03] Secure Channel procedure; if such an application is not present, the Device SHOULD then try to get this Bootstrap Data by selecting the PCKS#15 application as described in Appendix G. Storage of LwM2M Bootstrap Information on the Smartcard (Normative).

The OMA-LwM2M Bootstrap application (AID : (0xA00000041200020000000000) MUST support the following commands : As specified in [GLOBALPLATFORM]:

• INITIALIZE UPDATE
• EXTERNAL AUTHENTICATE with P1=0x33 (C-DECRYPTION, R-ENCRYPTION, C-MAC and R-MAC)

As defined in [ETSI TS 102.221]:

• SELECT with P1=0x00 (select by file ID)
• READ BINARY Any other command is optional.

I Media types

This enabler doesn't request any new media types from IANA.

I.1 Media-Type application/vnd.oma.lwm2m+tlv Registration

application/vnd.oma.lwm2m+tlv has been registered with IANA in version 1.0.

I.2 Media-Type application/vnd.oma.lwm2m+json Registration

application/vnd.oma.lwm2m+json has been registered with IANA in version 1.0.

Appendix J. LwM2M Schema and Object Definition File (Informative)

For supporting the LwM2M Enabler version and the Object Version in the Definition file (.xml) of a LwM2M Object, the LwM2M schema (URL: ="http://openmobilealliance.org/tech/profiles/LWM2M.xsd") contains 2 optional elements: LwM2MVersion and ObjectVersion, see Appendix LwM2M Schema.

The Object definition file (.xml), which describes the resources of a particular Object may contain these two elements:

1. the “LwM2MVersion” element indicates the minimum version of the LwM2M Enabler supporting that Object,

2. the “ObjectVersion” element indicates the version of the Object as defined in Section 7.2. Object Versioning of this document.

In addition:

• when the minimum LwM2M version supporting the Object is the Initial Version of the LwM2M Enabler (1.0), this information may be omitted.

• when the Object version is the Initial Version of that Object (1.0), the Object Version information may be omitted.

• when the Object definition is part of any LwM2M Enabler, the Object Version information may be omitted.

For example: an Object ID:44 in Version 2.4 for which the minimum LwM2M version supporting this Object Version is 1.1, will have an URN defined as “urn:oma:lwm2m:oma:44:2.4” used to name the associate Object definition (.xml) file on the OMNA portal:

<?xml version="1.0" encoding="UTF-8"?> 
<LWM2M xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://openmobilealliance.org/tech/profiles/LWM2M.xsd" > 
                <Object ObjectType="MODefinition"> 
                                <Name>MyDevice</Name> 
                                <Description1>< ![CDATA[This LWM2M Object is my device]]></Description1> 
                                <ObjectID>44</ObjectID> 
                                <LWM2MVersion>1.1</LWM2MVersion> 
                                <ObjectVersion>2.4</ObjectVersion> 
                                <ObjectURN>urn:oma:lwm2m:oma:44:2.4</ObjectURN> 
                                <MultipleInstances>Single</MultipleInstances> 
                                <Mandatory>Mandatory</Mandatory> 
                                <Resources>   
                                        . 
                                       . 
                               </Resources> 
                               </Description2> 
                               </Resources> 
               </Object> 
</LWM2M> 

Appendix K. LwM2M Schema

This appendix provides the content of the LightweightM2M schema.

The schema was created to support the LwM2M Editor Tool. The following elements and attributes are used by the LwM2M Editor Tool](http://devtoolkit.openmobilealliance.org/OEditor/Default) but are not part of the LwM2M protocol:

• Description1, it is used to insert the definition of the Object

• Description2, it is used to insert any extra information at the end of the table that contains the Resources

• ObjectType, used to identify if the file contains an Object and Resources or only Resources

Appendix L. Example of Trigger Message from Server (Informative)

Example WAP Push over SMS containing the trigger information:

Appendix M. CBOR Example (Informative)

The example from Table: 7.4.3.-2 Return JSON payload from example request to Device Object of the LwM2M example client (Read /3/0) is shown below using the CBOR format with comments.

90                                      # array(16)
   A3                                   # map(3)
      21                                # negative(1)
      65                                # text(5)
         2F332F302F                     # "/3/0/"
      00                                # unsigned(0)
      61                                # text(1)
         30                             # "0"
      03                                # unsigned(3)
      74                                # text(20)
         4F70656E204D6F62696C6520416C6C69616E6365 # "Open Mobile Alliance"
   A2                                   # map(2)
      00                                # unsigned(0)
      61                                # text(1)
         31                             # "1"
      03                                # unsigned(3)
      76                                # text(22)
         4C69676874776569676874204D324D20436C69656E74 # "Lightweight M2M Client"
   A2                                   # map(2)
      00                                # unsigned(0)
      61                                # text(1)
         32                             # "2"
      03                                # unsigned(3)
      69                                # text(9)
         333435303030313233             # "345000123"
   A2                                   # map(2)
      00                                # unsigned(0)
      61                                # text(1)
         33                             # "3"
      03                                # unsigned(3)
      63                                # text(3)
         312E30                         # "1.0"
   A2                                   # map(2)
      00                                # unsigned(0)
      63                                # text(3)
         362F30                         # "6/0"
      02                                # unsigned(2)
      01                                # unsigned(1)
   A2                                   # map(2)
      00                                # unsigned(0)
      63                                # text(3)
         362F31                         # "6/1"
      02                                # unsigned(2)
      05                                # unsigned(5)
   A2                                   # map(2)
      00                                # unsigned(0)
      63                                # text(3)
         372F30                         # "7/0"
      02                                # unsigned(2)
      19 0ED8                           # unsigned(3800)
   A2                                   # map(2)
      00                                # unsigned(0)
      63                                # text(3)
         372F31                         # "7/1"
      02                                # unsigned(2)
      19 1388                           # unsigned(5000)
   A2                                   # map(2)
      00                                # unsigned(0)
      63                                # text(3)
         382F30                         # "8/0"
      02                                # unsigned(2)
      18 7D                             # unsigned(125)
   A2                                   # map(2)
      00                                # unsigned(0)
      63                                # text(3)
         382F31                         # "8/1"
      02                                # unsigned(2)
      19 0384                           # unsigned(900)
   A2                                   # map(2)
      00                                # unsigned(0)
      61                                # text(1)
         39                             # "9"
      02                                # unsigned(2)
      18 64                             # unsigned(100)
   A2                                   # map(2)
      00                                # unsigned(0)
      62                                # text(2)
         3130                           # "10"
      02                                # unsigned(2)
      0F                                # unsigned(15)
   A2                                   # map(2)
      00                                # unsigned(0)
      64                                # text(4)
         31312F30                       # "11/0"
      02                                # unsigned(2)
      00                                # unsigned(0)
   A2                                   # map(2)
      00                                # unsigned(0)
      62                                # text(2)
         3133                           # "13"
      02                                # unsigned(2)
      1A 5182428F                       # unsigned(1367491215)
   A2                                   # map(2)
      00                                # unsigned(0)
      62                                # text(2)
         3134                           # "14"
      03                                # unsigned(3)
      66                                # text(6)
         2B30323A3030                   # "+02:00"
   A2                                   # map(2)
      00                                # unsigned(0)
      62                                # text(2)
         3136                           # "16"
      03                                # unsigned(3)
      61                                # text(1)
         55                             # "U"