Lightweight Machine to Machine Technical Specification: Transport Bindings
Approved Version: 1.2.1 - 2022-12-09
Open Mobile Alliance
OMA-TS-LightweightM2M_Transport-V1_2_1-20221209-A
master: 12 Dec 2022 18:40:00 rev: 0abdbd4

Use of this document is subject to all of the terms and conditions of the Use Agreement located at https://www.omaspecworks.org/about/policies-and-terms-of-use/.

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.

THIS DOCUMENT IS PROVIDED ON AN "AS IS" "AS AVAILABLE" AND "WITH ALL FAULTS" BASIS.

Copyright 2022 Open Mobile Alliance.

Used with the permission of the Open Mobile Alliance under the terms set forth above.

Table of Contents

Table of Figures

Table of Tables

1. Scope

This document specifies the transport bindings of the Lightweight Machine-to-Machine (LwM2M) protocol version 1.2. The split between the LwM2M core [LwM2M-CORE] and the transport binding specification improves readability, allows a cleaner separation between the LwM2M messaging layer and the underlying protocols for conveying these messages, and ultimately better extensibility.

LwM2M version 1.0 supported the CoAP over UDP and CoAP over SMS transport bindings. The UDP and SMS transports can be used with or without DTLS.

LwM2M version 1.1 added support for CoAP over TCP and CoAP over Non-IP transport bindings. The TCP transport can be used with or without TLS. The Non-IP transport is applicable to 3GPP CIoT and LoRaWAN. CoAP over TCP, as defined in [CoAP_TCP], offers better firewall traversal, as explained in Section 1 of [CoAP_TCP].

LwM2M version 1.1 also supports the application layer security protocol OSCORE [OSCORE], which enables support for proxy operations and end-to-end security independently of transport layer protocol.

LwM2M version 1.2 added support for HTTP and MQTT transport bindings.

1.1. Version 1.2.1

This revision of the specification includes the following fixes or clarifications:

2. References

2.1. Normative References

Table: 2.1.-1 Normative References
[LwM2M-ConnMgmt] Open Mobile Alliance, Lightweight M2M – Connectivity Management Object (LwM2M Object – ConnMgmt)
[LwM2M-CORE] Open Mobile Alliance, "Lightweight Machine to Machine Technical Specification: Core Layer"
[3GPP 23.003] 3GPP TS 23.003 "Numbering, addressing and identification", URL:http://www.3gpp.org/
[3GPP 23.038] 3GPP TS 23.038 "Alphabets and language-specific information", URL:http://www.3gpp.org/
[3GPP 23.040] 3GPP TS 23.040 "Technical realization of the Short Message Service (SMS)", URL:http://www.3gpp.org/
[3GPP 23.060] 3GPP TS 23.060 "General Packet Radio Service (GPRS); Service description; Stage 2", URL:http://www.3gpp.org/
[3GPP 31.102] 3GPP TS 31.102 "Characteristics of the Universal Subscriber Identity Module (USIM) application", URL:http://www.3gpp.org/
[3GPP 31.115] 3GPP TS 31.115 "Secured packet structure for (Universal) Subscriber Identity Module (U)SIM Toolkit applications", URL:http://www.3gpp.org/
[ETSI 102 220] ETSI TS 102 220 "Smart Cards; ETSI numbering system for telecommunication application providers", URL:http://www.etsi.org/
[ETSI 102 221] ETSI TS 102 221 "Smart Cards; UICC-Terminal interface; Physical and logical characteristics", URL:http://www.etsi.org/
[ETSI 102 223] ETSI TS 102 223 "Smart Cards; Card Applications Toolkit (CAT)", URL:http://www.etsi.org/
[ETSI 102 225] ETSI TS 102 225 "Smart Cards; Secured packet structure for UICC based applications", URL:http://www.etsi.org/
[CoAP] Z. Shelby, K. Hartke, C. Bormann, B. Frank, "The Constrained Application Protocol (CoAP)", June 2014, URL:https://www.ietf.org/rfc/rfc7252.txt
[CoAP_Blockwise] C. Bormann, Z. Shelby, "Block-wise transfers in CoAP", August 2016, URL:https://www.ietf.org/rfc/rfc7959.txt
[CoAP_ERT] C. Amsuess, J. Mattsson, G. Selander, "Constrained Application Protocol (CoAP): Echo, Request-Tag, and Token Processing", February 2022, URL:https://www.ietf.org/rfc/rfc9175.txt
[CoAP-EST] P. van der Stok, P. Kampanakis, S. Kumar, M. Richardson, M. Furuhed, S. Raza, "EST-coaps: Enrollment over Secure Transport with the Secure Constrained Application Protocol", April 2022, URL:https://www.ietf.org/rfc/rfc9148.txt
[CoAP_TCP] C. Bormann, S. Lemay, H. Tschofenig, K. Hartke, B. Silverajan, B. Raymor, "CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets", February 2018, URL:https://www.ietf.org/rfc/rfc8323.txt
[DTLS-1.2-CID] E. Rescorla, H. Tschofenig, T. Fossati, "Connection Identifiers for DTLS 1.2", March 2022, URL:https://www.ietf.org/rfc/rfc9146.txt
[DTLS-1.3] E. Rescorla, H. Tschofenig, N. Modadugu, "The Datagram Transport Layer Security (DTLS) Protocol Version 1.3", April 2022, URL:https://www.ietf.org/rfc/rfc9147.txt
[GLOBALPLATFORM] GlobalPlatform Card Specification V2.3.1 (GPC_SPE_034), URL:http://www.globalplatform.org/
[LoRaWAN] The LoRa Alliance, "LoRaWAN 1.1 Specification", available at https://www.lora-alliance.org/lorawan-for-developers
[MQTT] OASIS Message Queuing Telemetry Transport (MQTT), Version 3.1.1, December 2015, URL:http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
[MQTT5] OASIS Message Queuing Telemetry Transport (MQTT), Version 5, March 2019, URL:https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html
[OBSERVE] K. Hartke, "Observing Resources in the Constrained Application Protocol (CoAP)", September 2015, URL:https://www.ietf.org/rfc/rfc7641.txt
[OSCORE] G. Selander, J. Mattsson, F. Palombini, L. Seitz, “Object Security for Constrained RESTful Environments (OSCORE)”, July 2019, URL:https://www.ietf.org/rfc/rfc8613.txt
[RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", March 1997, URL:https://www.ietf.org/rfc/rfc2119.txt
[RFC2616] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", June 1999, URL:https://www.ietf.org/rfc/rfc2616.txt
[RFC3629] F. Yergeau, “UTF- UTF-8, a transformation format of ISO 10646”, November 2003,URL:https://www.rfc-editor.org/rfc/rfc3629.html
[RFC4279] P. Eronen, H. Tschoenig, “Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)“, December 2005, URL, URL:https://tools.ietf.org/html/rfc4279
[RFC5246] T. Dierks, E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", August 2008, URL:https://www.ietf.org/rfc/rfc5246.txt
[RFC5280] D. Cooper, S. Santesson, S. Farrell, S. Boeyen, R. Housley, W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", May 2008, URL:https://www.ietf.org/rfc/rfc5280.txt
[RFC5289] E. Rescorla, "TLS Elliptic Curve Cipher Suites with SHA-256/384 and AES Galois Counter Mode (GCM)", August 2008, URL:https://www.ietf.org/rfc/rfc5289.txt
[RFC5487] M. Badra, "Pre-Shared Key Cipher Suites for TLS with SHA-256/384 and AES Galois Counter Mode", March 2009, URL:https://www.ietf.org/rfc/rfc5487.txt
[RFC5869] H. Krawczyk, P. Eronen, "HMAC-based Extract-and-Expand Key Derivation Function (HKDF)", May 2010, URL:https://www.ietf.org/rfc/rfc5869.txt
[RFC5958] S. Turner, "Asymmetric Key Packages", August 2010, URL:https://www.ietf.org/rfc/rfc5958.txt
[RFC6066] D. Eastlake 3rd, “Transport Layer Security (TLS) Extensions: Extension Definitions”, January 2011, URL:https://www.rfc-editor.org/rfc/rfc6066.html
[RFC6125] F. Yergeau, “P. Saint-Andre, J. Hodges, “Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)”, March 2011, URL:https://https://tools.ietf.org/html/rfc6125
[RFC6347] E. Rescorla, N. Modadugu, "Datagram Transport Layer Security Version 1.2", January 2012, URL:https://www.ietf.org/rfc/rfc6347.txt
[RFC6655] D. McGrew, D. Bailey, "AES-CCM Cipher Suites for TLS", July 2012, URL:https://www.ietf.org/rfc/rfc6655.txt
[RFC6690] Z. Shelby, "Constrained RESTful Environments (CoRE) Link Format", August 2012, URL:https://www.ietf.org/rfc/rfc6690.txt
[RFC6698] P. Hoffman, J. Schlyter, “The DNS-Based Authentication of Named Entities (DANE) Transport Layer Security (TLS) Protocol: TLSA”, August 2012, URL:https://www.rfc-editor.org/rfc/rfc6698.html
[RFC6961] Y. Pettersen, "The Transport Layer Security (TLS) Multiple Certificate Status Request Extension", June 2013, URL:https://www.ietf.org/rfc/rfc6961.txt
[RFC7250] P. Wouters, H. Tschofenig, J. Gilmore, S. Weiler, T. Kivinen, “Using Raw Public Keys in Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)”, June 2014,URL:https://tools.ietf.org/html/rfc7250
[RFC7251] D. McGrew, D. Bailey, M. Campagna, R. Dugal, “AES-CCM Elliptic Curve Cryptography (ECC) Cipher Suites for TLS”, June 2014, URL:https://tools.ietf.org/html/rfc7251
[RFC7457] Y. Sheffer, R. Holz, P. Saint-Andre, "Summarizing Known Attacks on Transport Layer Security (TLS) and Datagram TLS (DTLS)", February 2015, URL:https://www.ietf.org/rfc/rfc7457.txt
[RFC7540] M. Belshe, R. Peon, M. Thomson, "Hypertext Transfer Protocol Version 2 (HTTP/2)", May 2015, URL:https://www.ietf.org/rfc/rfc7540.txt
[RFC7925] H. Tschofenig, T. Fossati, "Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS) Profiles for the Internet of Things", July 2016, URL:https://www.ietf.org/rfc/rfc7925.txt
[RFC8075] A. Castellani, S. Loreto, A. Rahman, T. Fossati, E. Dijk, "Guidelines for Mapping Implementations: HTTP to the Constrained Application Protocol (CoAP)", February 2017, URL:https://www.ietf.org/rfc/rfc8075.txt
[RFC8132] P. van der Stok, C. Bormann, A. Sehgal, "PATCH and FETCH Methods for the Constrained Application Protocol (CoAP)", April 2017, URL:https://www.ietf.org/rfc/rfc8132.txt
[RFC8152] J. Schaad, "CBOR Object Signing and Encryption (COSE)", July 2017, URL:https://www.ietf.org/rfc/rfc8152.txt
[RFC8288] M. Nottingham, "Web Linking", October 2017, URL:https://www.ietf.org/rfc/rfc8288.txt
[RFC8446] E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.3", August 2018, URL:https://www.ietf.org/rfc/rfc8446.txt
[RFC8610] E. Rescorla, H. Tschofenig, N. Modadugu, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", June 2019, URL:https://www.ietf.org/rfc/rfc8610.txt

2.2. Informative References

    <tr>
        <td><strong>[3GPP 24.301]</strong></td>
        <td>3GPP TS 24.301 " Non-Access-Stratum (NAS) protocol for Evolved Packet System (EPS); Stage 3", <a href="http://www.3gpp.org/">URL:http://www.3gpp.org/</a></td>
    </tr>

    <tr>
        <td><strong>[3GPP 29.122]</strong></td>
        <td>3GPP TS 29.122 "T8 reference point for Northbound APIs", <a href="http://www.3gpp.org/">URL:http://www.3gpp.org/</a></td>
    </tr>

    <tr>
        <td><strong>[3GPP 24.250]</strong></td>
        <td>3GPP TS 24.250 "Protocol for Reliable Data Service", <a href="http://www.3gpp.org/">URL:http://www.3gpp.org/</a></td>
    </tr>

    <tr>
        <td><strong>[3GPP 24.008]</strong></td>
        <td>3GPP TS 24.008 "Mobile radio interface Layer 3 specification; Core network protocols; Stage 3", <a href="http://www.3gpp.org/">URL:http://www.3gpp.org/</a></td>
    </tr>

    <tr>
        <td><strong>[3GPP 27.060]</strong></td>
        <td>3GPP TS 27.060 "Packet domain; Mobile Station (MS) supporting Packet Switched services", <a href="http://www.3gpp.org/">URL:http://www.3gpp.org/</a></td>
    </tr>
    <tr>
        <td><strong>[3GPP 23.720]</strong></td>
        <td>3GPP TR 23.720 "Study on architecture enhancements for Cellular Internet of Things (CIoT)", <a href="http://www.3gpp.org/">URL:http://www.3gpp.org/</a></td>
    </tr>
    <tr>
        <td><strong>[3GPP 29.061]</strong></td>
        <td>3GPP TS 29.061 "Interworking between the Public Land Mobile Network (PLMN) supporting packet based services and Packet Data Networks (PDN)", <a href="http://www.3gpp.org/">URL:http://www.3gpp.org/</a></td>
    </tr>
    <tr>
        <td><strong>[RFC5789]</strong></td>
        <td>L. Dusseault, J. Snell, "PATCH Method for HTTP", March 2010, <a href="https://www.ietf.org/rfc/rfc5789.txt">URL:https://www.ietf.org/rfc/rfc5789.txt</a></td>
    </tr>
    <tr>
        <td><strong>[RFC7468]</strong></td>
        <td>S. Josefsson, S. Leonard, "Textual Encodings of PKIX, PKCS, and CMS Structures", April 2015, <a href="https://www.ietf.org/rfc/rfc7468.txt">URL:https://www.ietf.org/rfc/rfc7468.txt</a></td>
    </tr>
    <tr>
        <td><strong>[SP800-90A]</strong></td>
        <td>Elaine Barker, John Kelsey, "Recommendation for Random Number Generation Using Deterministic Random Bit Generators, NIST Special Publication 800-90A", Revision 1, June 2015, available at <a href="http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf" class="uri">http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf</a></td>
    </tr>

    <tr>            
        <td><strong>[RFC4086]</strong></td>
        <td>D. Eastlake, J. Schiller, S. Crocker, "Randomness Requirements for Security", June 2005, <a href="https://www.ietf.org/rfc/rfc4086.txt">URL:https://www.ietf.org/rfc/rfc4086.txt</a></td>
    </tr>
            
</tbody>
Table: 2.2.-1 Informative References
[OMADICT] "Dictionary for OMA Specifications", Open Mobile Alliance™, OMA-ORG-Dictionary-V2_9, URL:http://www.openmobilealliance.org/
[3GPP 21.905] 3GPP TR 21.905 "Vocabulary for 3GPP Specifications", URL:http://www.3gpp.org/
[3GPP 23.401] 3GPP TS 23.401 "General Packet Radio Service (GPRS) enhancements for Evolved Universal Terrestrial Radio Access Network (E-UTRAN) access", URL:http://www.3gpp.org/
[3GPP 23.682] 3GPP TS 23.682 "Architecture enhancements to facilitate communications with packet data networks and applications", URL:http://www.3gpp.org/

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

Table: 3.2.-1 Definitions
LwM2M Bootstrap-Server Account LwM2M Security Object Instance with Bootstrap-Server Resource set to 'true'.
LwM2M Server Account LwM2M Security Object Instance with Bootstrap-Server Resource set to 'false' and associated LwM2M Server Object Instance.

Kindly consult [OMADICT] for more definitions used in this document.

3.3. Abbreviations

Table: 3.3.-1 Abbreviations
3GPP 3rd Generation Partnership Project
ABNF Augmented Backus-Naur Form
ACK Acknowledgement
ACL Access Control List
AEAD Authenticated Encryption with Additional Data
AES Advanced Encryption Standard
API Application Programming Interface
APN Access Point Name
AS Application Server
BER-TLV Basic Encoding Rules TLV
CA Certification Authority
CBC Cipher Block Chaining
CBOR Concise Binary Object Representation
CID Connection ID
CIoT Cellular Internet of Things
CMAC Cipher-based Message Authentication Code
CN Common Name
CoAP Constrained Application Protocol
DTLS Datagram Transport Layer Security
CON Confirmable (Message)
COSE CBOR Object Signing and Encryption
C-SGN CIoT Serving Gateway Node
CSR Certificate Signing Request
DER Distinguished Encoding Rules
DES Data Encryption Standard
DNS Domain Name Service/Domain Name Server
DoS Denial of Service
DRX Discontinuous Reception
DTLS Datagram Transport Layer Security
ECDHE Ephemeral Elliptic Curve Diffie-Hellman
ECDSA Elliptic Curve Digital Signature Algorithm
eMTC enhanced Machine Type Communication
EST Enrollment over Secure Transport
FQDN Fully Qualified DNS domain Name
HKDF HMAC-based Key Derivation Function
HMAC Hashed Message Authentication Code
HTTP Hypertext Transfer Protocol
IANA Internet Assigned Numbers Authority
ID Identity/Identifier
IP Internet Protocol
ISDN Integrated Services Digital Network
JSON JavaScript Object Notation
KiB Kilobyte
KIc Key and algorithm Identifier for ciphering
KID Key and algorithm IDentifier
LoRaWAN Long Range Wide Area Network
LSB Least Significant Bit
LTE-M Long Term Evolution, category M1
LwM2M Lightweight M2M
M2M Machine to Machine
MAC Message Authentication Code
MME Mobility Management Entity
MQTT Message Queuing Telemetry Transport
MSB Most Significant Bit
MSISDN Mobile Subscriber ISDN Number
MTU Maximum Transmission Unit
NAS Non-Access Stratum
NAT Network Address Translation
NB-IoT NarrowBand Internet of Things
NIDD Non-IP Data Delivery
non-CON non-Confirmable (Message)
OCSP Online Certificate Status Protocol
OSCORE Object Security for Constrained RESTful Environments
PCO Protocol Configurations Options
PDN Packet Data Network
P-GW PDN Gateway
PKCS Public Key Cryptography Standard
PKI Public Key Infrastructure
PKIX PKI for X.509 Certificates
PLMN Public Land Mobile Network
PoR Proof of Receipt
PP Point to Point
PSK Pre-Shared Key
PSM Power Saving Mode
PtP Point to Point
RAM Random Access Memory
RDS Reliable Data Service
RE Receiving Entity
SCEF Service Capability Exposure Function
SCR Static Conformance Requirements
SCS Services Capability Server
SenML Sensor Measurement Lists
S-GW Serving Gateway
SMS Short Message Service
SNI Server Name Indication
SPI SPI Security Parameters Indication
TAR Toolkit Application Reference
TAU Tracking Area Update
TCP Transmission Control Protocol
TLS Transport Layer Security
TLV Tag-Length-Value
TPDU Transaction Protocol Data Unit/Transfer Protocol Data Unit
TP-OA Transport Protocol-Originating Address
TP-PID Transport Protocol-Protocol Identifier
UDP User Datagram Protocol
UE User Equipment
UICC Universal Integrated Circuit Card
URI Uniform Resource Identifier
URN Uniform Resource Name
UTF Unicode Transformation Format

4. Introduction

This specification defines the transport bindings for the LwM2M messaging protocol used between LwM2M Clients, LwM2M Bootstrap Servers and LwM2M Servers. Figure: 4.-1 The Protocol Stack of the LwM2M Enabler shows the relationships between the transport bindings and the messaging protocol. In particular, this specification defines the following transport bindings:

The Protocol Stack of the LwM2M Enabler
Figure: 4.-1 The Protocol Stack of the LwM2M Enabler

OSCORE can be used with any of the CoAP transport bindings including UDP, SMS and TCP, with or without DTLS or TLS.

5. Security

The LwM2M protocol supports various transport bindings and credentials for securely communicating with LwM2M Servers. This configuration information can be provisioned through various forms of bootstrapping methods.

LwM2M supports three different types of credentials, namely

Since these credential types offer different properties, the LwM2M specification offers support for all of them. [RFC7925] provides the necessary details about the use of each of these credentials with TLS/DTLS. The LwM2M specification also supports application layer security based on OSCORE with pre-shared secrets. Which credential is best in a given deployment depends on a number of factors, including the threat model and IoT device constraints.

The LwM2M protocol specifies that authorization of LwM2M Servers to access Object Instances and Resources within the LwM2M Client is provided through Access Control Object Instances within the LwM2M Client.

Note: Almost all security protocols used by this specification rely on a high quality random number generator available on the IoT device. When generating random numbers (e.g. for creating an ephemeral public / private key pair or a nonce), it is recommended to rely on state-of-the-art designs, such as those described in [RFC4086] and [SP800-90A].

5.1. Security Requirements

LwM2M may under certain circumstances be deployed with security outside the scope of LwM2M TS, as specified in other parts of this section. However, for LwM2M security solutions the requirements specified in this section apply.

The LwM2M protocol requires that all LwM2M Clients, LwM2M Servers and LwM2M Bootstrap-Servers mutually authenticate prior to communicating. This means:

The LwM2M protocol also requires that all communication between LwM2M Clients and LwM2M Servers as well as between LwM2M Clients and LwM2M Bootstrap-Servers is encrypted and integrity protected. This means:

Additionally:

The security requirements applies also to communication via LwM2M aware and LwM2M unaware intermediate nodes.

In addition to communication security care must also be taken to ensure that data at rest, such as secrets and sensor data, are also secured against unauthorized access.

5.2. TLS/DTLS-based Security

5.2.1. TLS/DTLS Overview

CoAP over UDP [CoAP] is secured using the Datagram Transport Layer Security (DTLS) 1.2 protocol [RFC6347], as defined in Section 9 of [CoAP]. DTLS is a communication security solution for datagram based protocols (such as UDP). More recently support for CoAP over TCP / TLS has been defined in [CoAP_TCP]. TLS 1.2 is specified in [RFC5246]. TLS and DTLS provide mutual authentication, data integrity and confidentiality. This version of the specification MAY optionally use TLS 1.3 [RFC 8446] and/or DTLS 1.3 [DTLS-1.3].

This section provides information related to the use of CoAP over DTLS and CoAP over TLS. Section 5.3. SMS Channel Security provides additional information regarding the use of DTLS in an SMS context. Implementations SHOULD be conformant to [RFC7925], which includes not only ciphersuites but also recommendations for the use of TLS/DTLS-specific extensions.

The TLS/DTLS client and the TLS/DTLS server SHOULD keep security state, such as session keys, sequence numbers, and initialization vectors, and other security parameters, established with TLS/DTLS for as long a period as can be safely achieved without risking compromise of the security context. If such state persists across sleep cycles where the RAM is powered off, secure storage SHOULD be used for the security context.

The credentials used for authenticating the TLS/DTLS client and the TLS/DTLS server to secure the communication between the LwM2M Client and the LwM2M Server are obtained using one of the bootstrap modes defined in [LwM2M-CORE].

LwM2M Bootstrap-Servers, LwM2M Servers and LwM2M Clients MUST use different key pairs. LwM2M Clients MUST use keys, which are unique to each LwM2M Client. When a LwM2M Client is configured to utilize multiple LwM2M Servers then the LwM2M Bootstrap-Server may configure different credentials with these LwM2Ms Servers. Using different credentials with each LwM2M Server provides better unlinkability properties since each individual LwM2M Server cannot correlate requests made by the LwM2M Client to other LwM2M Servers. Deployment and application specific considerations dictate what approach to use, but using different credentials is generally recommended practice.

5.2.2. Ciphersuites

TLS/DTLS supports the concept of ciphersuites and they are securely negotiated during the handshake. This specification recommends support of a limited number of ciphersuites based on [RFC7925]. These ciphersuites have been chosen because of suitability for IoT devices, security reasons and to improve interoperability. Ciphersuites in TLS/DTLS 1.2 depend on the type of credential being used since the ciphersuite concept also indicates the authentication and key exchange mechanism. LwM2M Clients and LwM2M Servers MAY support additional ciphersuites that conform to the state-of-the-art security requirements.

5.2.3. Elliptic Curves

For ECDHE, the group secp256r1 SHALL be supported. For ECDSA the curve secp256r1 SHALL be supported. Elliptic curve groups of less than 255 bits SHALL NOT be supported.

5.2.4. Bootstrapping

The Resources in the LwM2M Security Object are used for

  1. providing TLS/DTLS communication security for "Client Registration", "Device Management & Service Enablement", and "Information Reporting" Interfaces if the LwM2M Security Object Instance relates to a LwM2M Server, or,

  2. providing channel security for the Bootstrap interface if the LwM2M Security Object instance relates to a LwM2M Bootstrap-Server.

  3. protecting the communication with a firmware repository when the LwM2M Client receives a URI in the Package URI of the Firmware Update object.

The content and the interpretation of the Resources in the LwM2M Security Object depends on the type of credential being used.

When bootstrapping from a Smartcard a secure channel between the Smartcard and the LwM2M Client SHOULD be established, as described in Appendix G of [LwM2M-CORE] and defined in [GLOBALPLATFORM]. Using a Smartcard with pre-shared secrets, with raw public keys, and with certificates needs no pre-existing trust relationship between LwM2M Server(s) and LwM2M Client(s): the pre-established trust relationship exists between the LwM2M Server(s) and the SmartCard.

LwM2M Clients MUST either be provisioned for use with a LwM2M Server or else be provisioned for use with a LwM2M Bootstrap-Server. Any LwM2M Client, which supports the client initiated bootstrap mode, MUST support at least one of the following secure methods:

  1. Bootstrapping with a strong (high-entropy) pre-shared secret, as described in Section Pre-Shared Keys. The ciphersuites defined in Section Pre-Shared Keys MUST NOT be used with a low-entropy secret or with a password.

  2. Bootstrapping with a raw public key or a certificate, as described in Section Raw Public Keys and Section X.509 Certificates.

LwM2M Clients MUST be provisioned with credentials that are unique to their device. For full interoperability in all deployment environments, a LwM2M Bootstrap-Server MUST support bootstrapping via pre-shared secrets, raw public keys, and certificates.

NOTE: The LwM2M Bootstrap-Server can also provision KIc and KID for the use of SMS Secured Packet Structure mode (see Section 5.3. SMS Channel Security).

Security credential dynamically provisioned to the LwM2M Client and the LwM2M Server MAY change at any time, even during the lifetime of an ongoing TLS/DTLS session. Since the TLS/DTLS protocol verifies the credentials only at the beginning of the session establishment (unless the re-negotiation feature is used) it is possible that a change in credential (for example, credentials for the use of a PSK-based ciphersuite) occurs after a TLS/DTLS handshake has already been completed. Hence, from a TLS/DTLS protocol point of view such credential change is not automatically recognized and the already established record layer security associations are in use. It is a policy decision for a TLS/DTLS client as well as a TLS/DTLS server implementation to close a connection when the credentials change. Such a decision will depend on various factors, such as the application domain in which LwM2M is used.

The Security Mode Resource in the Security Object determines what credentials are being used by the LwM2M Client and the LwM2M Server or LwM2M Bootstrap-Server, respectively. Currently five security modes are defined, namely

The choice of security mode determines what resources are populated with which values. A high-level summary is provided in the subsequent table with more details in the subsections below.

Table: 5.2.4.-1 Security Modes
Security Mode Public Key or Identity Secret Key Server Public Key
Pre-Shared Keys (0) PSK identity PSK N/A
Raw Public Keys (1) RPK Private Key PRK
X.509 Certificates (2) X.509 certificate Private Key X.509 certificate
NoSec (3) N/A N/A N/A
Certificate mode with EST (4) N/A N/A X.509 certificate

5.2.5. Unbootstrapping

The term 'unbootstrapping' refers to the process of deleting an instance of a LwM2M Security Object. If such an instance of a Security Object is to be deleted related resources and configurations need to be deleted or modified as well. This ensures that there is no orphan data, for example LwM2M Server Object instances with no security context. Therefore, when the Delete operation is sent via the Bootstrap Interface, the Client MUST execute the following procedure.

  1. The Server Object Instance, which the deleted Security Object referred to, MUST be deleted. The Client MAY send the "De-register" operation to the LwM2M Server.

  2. If there is an Object Instance that can be accessed only by a LwM2M Server of the Server Object Instance (i.e., the LwM2M Server is Access Control Owner and the LwM2M Server can access the Object Instance only in an Access Control Object Instance), the Object Instance and the corresponding Access Control Object Instance MUST be deleted.

  3. If an Object Instance can be accessed by multiple LwM2M Servers including the LwM2M Server which Security Object Instance is to be deleted, then

  1. Observation operations from the LwM2M Server Object Instance MUST be deleted.

Note: To monitor the change of the Access Control Owner the LwM2M Server MAY observe the Access Control Owner Resource.

5.2.6. Endpoint Client Name

This specification recommends, but does not mandate, transmission of the endpoint client name in the Bootstrap-Request, the Bootstrap-Pack-Request and the Register message. Since the endpoint client name is not authenticated at the application layer the LwM2M Server MUST compare the received endpoint client name identifier with the identifier used at the TLS/DTLS handshake. This comparison may either be an equality match or may involve a dedicated lookup table to ensure that LwM2M Clients cannot intentionally or due to misconfiguration impersonate other LwM2M Clients. The LwM2M Server MUST respond with a "4.00 Bad Request" to the LwM2M Client if these fields do not match.

5.2.7. LwM2M and TLS/DTLS Roles

In the LwM2M enabler, the LwM2M Client is always the TLS/DTLS client. The LwM2M Bootstrap-Server and the LwM2M Server are always acting as TLS/DTLS servers.

5.2.8. DTLS Connection ID

In DTLS 1.2, the IP address and port of the peer are used to identify the DTLS association. Unfortunately, in some cases, such as NAT rebinding, these values are insufficient. This is a particular issue when devices enter extended sleep periods to increase their battery lifetime. The NAT rebinding leads to connection failure, with the resulting cost of a new handshake.

[DTLS-1.3] and [DTLS-1.2-CID] define extensions to DTLS 1.3 and DTLS 1.2 to add a Connection ID (CID), an identifier carried in the record layer header that gives the recipient additional information for selecting the appropriate security association. The use of this extension allows LwM2M Clients to maintain an established DTLS security context for a longer period of time.

5.2.9. Security Modes and Credential Types

[RFC7925] gives recommendations for three types of credentials, namely pre-shared keys, raw public keys, and X.509 certificates. LwM2M works with all three types of credentials but the performance and security trade-offs for these three mechanisms are different. As a summary, the three credential types have the following properties:

The following sub-sections define the use of various resources in the LwM2M Security Object for the specific credential types. The "LwM2M Server URI", and the "Bootstrap Server" Resources are populated according to the description in [LwM2M-CORE].

5.2.9.1. Pre-Shared Key Mode

If a LwM2M Server supports the pre-shared key credentials it MUST support the following:

The LwM2M Client SHOULD NOT use the TLS_PSK_WITH_AES_128_CBC_SHA256 ciphersuite as [RFC7457] has identified security attacks against these TLS/DTLS ciphersuites.

A LwM2M v1.1 or v1.2 Client MUST support TLS_PSK_WITH_AES_128_CCM_8 and MAY support additional ciphersuites.

This mode requires the following resources of the Security Object to be populated:

5.2.9.2. Raw Public Key Mode

If a LwM2M Server supports the raw public key credentials it MUST support the following:

The LwM2M Client SHOULD NOT use the TLS_PSK_WITH_AES_128_CBC_SHA256 ciphersuite as [RFC7457] has identified security attacks against these TLS/DTLS ciphersuites.

A LwM2M v1.1 or v1.2 Client MUST support TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 and MAY support additional ciphersuites. Ciphersuites SHOULD have ECDSA authentication and SHOULD have ECDHE key exchange.

This mode requires the following resources of the Security Object to be populated:

This security mode is appropriate for LwM2M deployments where the benefits of asymmetric cryptography are needed but the PKI functionality is undesirable.

The TLS/DTLS client MUST check that the raw public key presented by the TLS/DTLS server matches this stored public key.

The TLS/DTLS server MUST store its own private and public keys, and MUST have a stored copy of the expected client public key. The TLS/DTLS server MUST check that the raw public key presented by the TLS/DTLS client exactly matches this stored public key.

5.2.9.3. X.509 Certificate Mode

The X.509 Certificate mode requires the use of X.509v3 certificates [RFC5280]. The X.509 certificates SHOULD be conformant with the profiling given in [RFC7925]. The curve secp256r1 SHALL be supported. Elliptic curve groups of less than 255 bits SHALL NOT be supported.

If a LwM2M Server supports X.509 Certificate mode it MUST support:

The LwM2M Client SHOULD NOT use the TLS_PSK_WITH_AES_128_CBC_SHA256 ciphersuite as [RFC7457] has identified security attacks against these TLS/DTLS ciphersuites.

A LwM2M v1.1 or v1.2 Client MUST support TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 and MAY support additional ciphersuites. Ciphersuites SHOULD have ECDSA authentication and SHOULD have ECDHE key exchange.

This mode requires the following resources of the Security Object to be populated:

When certificate-based authentication is used in TLS/DTLS to protect the LwM2M communication at least two types of certificates need to be distinguished, namely client (or device) certificates and certificates presented by the server. This distinction matters since the identifiers used in the certificates will be different and the procedure for identifier matching will be different as well.

Client certificates SHOULD contain the endpoint client name in the subject CN (Common Name) attribute. The LwM2M Server MUST perform the security checks outlined in 5.2.6. Endpoint Client Name.

The subsequent text talks about the certificates used by the server.

The algorithm for verifying the service identity, as described in Section 4.4.1 of [RFC7925] and in [RFC6125], is essential for ensuring proper security when certificates are used and MUST be implemented and used by the TLS/DTLS client. Terms like reference identifier and presented identifier are defined in [RFC6125].

Comparing the reference identifier against the presented identifier obtained from the certificate is required to ensure the TLS/DTLS client is communicating with the intended TLS/DTLS server. To cater for the case that the Server Public Key Resource directly contains the certificate of the TLS/DTLS server, TLS/DTLS client does not compare the reference identifier against the presented identifier if the certificate from the Server Public Key Resource matches the certificate provided by the TLS/DTLS server during the TLS/DTLS handshake. If that is not the case, the TLS/DTLS client MUST compare the reference identifier against the presented identifier as described below, and perform path validation.

The algorithm description from [RFC 6125] assumes that fully qualified DNS domain names (FQDN) are used. If a server node is provisioned with a FQDN, then the TLS/DTLS server certificate MUST contain this "FQDN" (i.e., presented identifier). This FQDN is stored in the SubjectAltName or in the Common Name (CN) component of the subject name, as explained in Section 9.1.3.3 of [CoAP], and this FQDN is used by the TLS/DTLS client to match it against the FQDN used during the lookup process (i.e., reference identifier) before contacting the LwM2M Server, as described in [RFC6125].

Note that the Server Name Indication (SNI) extension [RFC6066] allows a TLS/DTLS client to tell a TLS/DTLS server the name of the TLS/DTLS server it is trying to contact. This is an important feature when the server is part of a hosting solution where multiple virtual servers are using a single underlying network address. Section 3 of [RFC6066] only allows FQDN hostname of the TLS/DTLS server in the ServerName field. For the TLS/DTLS client running on a LwM2M Server the SNI extension allows the LwM2M Server to indicate what certificate it is expecting.

5.2.9.4. NoSec Mode

The LwM2M protocol MUST NOT be deployed without appropriate security. Because LwM2M may be deployed with security outside the scope of this specification (e.g. at lower layers), this may mean that neither transport-layer security (TLS/DTLS), nor application-layer security (OSCORE) is applied. In case communication security is not used at the LwM2M layer ("NoSec" mode), the deployment MUST use alternative security mechanisms.

The LwM2M Server MUST compare the endpoint client name identifier used during the Register, the Bootstrap-Request and the Bootstrap-Pack-Request message with the identifier used for network access authentication (typically used to setup link-layer security procedures).

In this mode the "Security Mode" Resource MUST be set to value 3. It is RECOMMENDED that the LwM2M Bootstrap-Server omits the "Public Key or Identity", the "Server Public Key" and the "Secret Key" Resources from a "Bootstrap-Write" operation. If a "Bootstrap-Write" operation contains these resources any values in these resources MUST be ignored by the LwM2M Client.

5.2.9.5. Certificate mode with EST

The Enrollment over Secure Transport (EST) bootstrap mode uses a certificate management protocol for provisioning certificates from the LwM2M Bootstrap-Server to the LwM2M Client. EST allows the LwM2M Client to generate the key pair locally on the LwM2M Device. The private key therefore never leaves the LwM2M Device. In order to use this mode, the "Security Mode" Resource MUST be set to value 4 and the certificate of the TLS/DTLS server MUST be provisioned to the "Server Public Key" Resource. This triggers the LwM2M Client to locally generate a public / private key pair and to initiate an EST over CoAP protocol exchange [CoAP-EST] to obtain a certificate. Once the certificate has been obtained it behaves like the Certificate mode. The EST over CoAP specification [CoAP-EST] profiles the use of EST for use in constrained environments.

Compared to the certificate mode with the "Security Mode" Resource set to value 2 additional over-the-air overhead is introduced by the SimpleEnroll and SimpleReEnroll functionality of EST since the LwM2M Client needs to convey the public key to the EST server and needs to demonstrate possession of the private key using the PKCS#10 defined mechanism, as explained in the EST specification [CoAP-EST]. Depending on the deployment environment this additional overhead needs to be compared against the added security benefit of not disclosing the private key to other parties. LwM2M Clients SHOULD use an existing key pair or generate the public/private key pair locally since this does not expose the private key to the LwM2M Bootstrap-Server or other parties, i.e., the private key pair SHOULD never leave the device.

Note: The "Secret Key" and the "Public Key or Identity" Resources are not used by the Certificate mode with EST. It is RECOMMENDED that the LwM2M Bootstrap-Server omits these resource in a "Bootstrap-Write" operation. If a "Bootstrap-Write" operation contains these resources any value provided MUST be ignored by the LwM2M Client.

Enrollment over Secure Transport (EST) offers multiple features, including

Simple PKI messages and CA certificate retrieval SHALL be supported when [CoAP-EST] is used for bootstrapping since the functionality for server-generated key requests is already covered as part of the security mode (1 - Raw Public Key mode and 2 - Certificate mode). CSR Attributes Request is also not required for this specification since the LwM2M Bootstrap Server is typically in possession of the required attributes for generating a certificate.

5.2.9.6. Additional Certificate Considerations
5.2.9.6.1. Deployments without DNS

In some deployment scenarios, DNS is not used and LwM2M Clients need to use the IP literal, such as coaps://[2001:db8::2:1]/, stored in the "LwM2M Server URI" Resource. To avoid having to use IP addresses also in the Common Name (CN) component of the server certificate or in a field of URI type in the SubjectAltName set this specification uses the Server Name Indication (SNI) Resource. For deployments without DNS, the TLS/DTLS client and server MUST support for the Server Name Indication (SNI) extension [RFC6066].

The procedure for a client is as follows:

5.2.9.6.2. Certificate Expiry

For the use of certificates devices need to be equipped with a real-time clock and need to be provisioned with a reference time since the certificate expiry field needs to be checked.

If the Bootstrap-Server certificate has an expiration time, then out-of-band mechanisms may be used to recover from an expired certificate. The [LwM2M-CORE] does not offer a way to recover from an expired Bootstrap-Server certificate. Out-of-band mechanism may include replacing the LwM2M Bootstrap-Server certificate via the firmware update mechanism or using a commissioning tool.

The LwM2M Bootstrap-Server or an authorized LwM2M Server MAY use the Current Time Resource of the LwM2M Device Object to provision a date/time reference value to the LwM2M Client. The LwM2M Client SHOULD verify the freshness of the request for setting the Current Time Resource. The LwM2M Client can use this reference value together with the current real-time clock setting to determine the current time to check the expiry date of a LwM2M Server certificate. The ability to modify the value of the Current Time Resource is security critical and therefore appropriate access control settings need to be applied.

5.2.9.6.3. Certificate Revocation

A LwM2M Client needs to determine when a LwM2M Server certificate has been revoked. Various approaches for dealing with expired LwM2M Server certificates are possible and the most promising candidates are:

  1. The LwM2M Client MAY use the error recovery procedures that will be invoked when a TLS / DTLS client encounters a problem verifying the LwM2M Server certificate during the handshake.

  2. The LwM2M Client MAY use the Online Certificate Status Protocol (OCSP) as part of the OCSP stapling mechanism [RFC6961]. This does, however, assume that the LwM2M Client and the LwM2M Server regularly execute the TLS / DTLS handshake, which may depend on the deployment. Note that the OCSP stapling comes with an extra cost of conveying the OCSP information inside the TLS / DTLS handshake.

  3. The server-initiated bootstrapping procedure is used by a LwM2M infrastructure operator to trigger a LwM2M Client to re-run the bootstrapping exchange to obtain new credentials for use with LwM2M Servers. The server-initiated bootstrapping procedure may not be usable by the LwM2M Server that has gotten its certificate revoked.

If the Bootstrap-Server certificate has been revoked then out-of-band mechanisms may be used to replace the revoked certificate. The LwM2M specification does not offer a way to recover from a revoked Bootstrap-Server certificate. Out-of-band mechanism may include replacing the LwM2M Bootstrap-Server certificate via the firmware update mechanism or using a commissioning tool.

5.2.9.6.4. Certificate Usage Field

The Certificate Usage Resource in the LwM2M Security Object specifies the semantics of the certificate or raw public key stored in the Server Public Key Resource, which is used to match the certificate presented in the TLS/DTLS handshake. [RFC 6698] defines for types, which are reused in this specification:

5.2.10. TLS / DTLS Error Handling

The TLS / DTLS specifications offer ways to report error situations via the Alert protocol. These errors may have multiple reasons and the process to recover from them is essential for a stable LwM2M implementation. Nevertheless, recovering from these errors may be challenging since many IoT devices are unattended and a failure in the establishment of a security association may result in a non-functioning device. Since a LwM2M Bootstrap-Server supervises the LwM2M Client it can support with the recovery of certain types of errors, i.e., the LwM2M Client is asked to fall back to the bootstrap mode in order to obtain new credentials.

This section provides default recommended error handling. LwM2M Server Object configuration provides additional capabilities via optional resources, such as the Bootstrap on Registration Failure Resource, to define the behavior in error conditions. There is no such fallback mechanism defined for the interaction between the LwM2M Client and the LwM2M Bootstrap-Server.

Table: 5.2.10.-1 TLS/DTLS Error Handling Recommendations
Value Alert Description RFC Recommendation
0 close_notify RFC 5246 Retry
10 unexpected_message RFC 5246 Retry
20 bad_record_mac RFC 5246 Retry
21 decryption_failed RFC 5246 Retry
22 record_overflow RFC 5246 Retry
30 decompression_failure RFC 5246 Ignore*
40 handshake_failure RFC 5246 Retry
41 no_certificate_RESERVED RFC 5246 Ignore*
42 bad_certificate RFC 5246 Fail
43 unsupported_certificate RFC 5246 Fail
44 certificate_revoked RFC 5246 Fail
45 certificate_expired RFC 5246 Fail
46 certificate_unknown RFC 5246 Fail
47 illegal_parameter RFC 5246 Retry
48 unknown_ca RFC 5246 Fail
49 access_denied RFC 5246 Fail
50 decode_error RFC 5246 Retry
51 decrypt_error RFC 5246 Retry
60 export_restriction_RESERVED RFC 5246 Ignore*
70 protocol_version RFC 5246 Retry
71 insufficient_security RFC 5246 Retry
86 internal_error RFC 7507 Retry
90 user_canceled RFC 5246 Retry
100 no_renegotiation RFC 5246 Retry**
110 unsupported_extension RFC 5246 Ignore.
111 certificate_unobtainable RFC 6066 Retry***
112 unrecognized_name RFC 6066 Fail***
113 bad_certificate_status_response RFC 6066 Fail***
114 bad_certificate_hash_value RFC 6066 Fail***
115 unknown_psk_identity RFC 4279 Fail

Legend:

The 'fail' recommendation in the table above indicates that the LwM2M Client MUST consider the handshake exchange failed and that it cannot by itself recover from the error situation. The 'retry' recommendation in the table above indicates that the LwM2M Client MUST consider the handshake failed but that the error situation MAY be transient and retrying the handshake protocol run may result in a successful completion. In both cases the LwM2M Client MUST follow the error handling procedures defined by resources in the LwM2M Server Object, if present.

An implementation may set a limit to the number of attempts to re-establish a TLS/DTLS connection and may decide to fall back to bootstrapping when a certain threshold is exceeded. Implementations should also use an exponential back-off between retransmissions. The number of retries and the retransmission timers MAY be set by resources in the LwM2M Server resources.

Note: Per [RFC 6347], DTLS implementations SHOULD silently discard records with bad MACs or that are otherwise invalid.

5.3. SMS Channel Security

This section defines the security modes for the transport of CoAP over SMS.

Channel security for [CoAP] has been defined for the UDP transport and is based on [RFC6347].

LwM2M Clients only supporting the SMS binding MAY support the NoSec mode when the SMS Channel is only used for debugging purposes otherwise they MUST support SMS Secured Mode. In any security mode except for debugging purposes, when an SMS message is received from an MSISDN that is not recorded in the LwM2M Server SMS Number resource of the LwM2M Server Access Security, the SMS message MUST be silently ignored.

LwM2M Clients supporting UDP and SMS bindings, when the SMS binding is only used for triggering, MUST support the adequate mechanism for securing CoAP over UDP. Those clients MAY use any SMS security mode. In particular SMS NoSec mode can be used for SMS triggering since all other communication will be secured by UDP channel security. Note: Using SMS NoSec for SMS triggering could introduce "Denial of Service" (DoS).

The "Secret Key" and "Public Key or Identity" Resources are used to configure the keying material that a Client uses with a particular LwM2M Server. The SMS key parameters are stored in the order KIc, KID, SPI, TAR (KIc is byte 0). Ordering of bits within bytes SHALL follow [ETSI 102 221], Section 3.4 "Coding Conventions" (b8 MSB, b1 LSB).

5.3.1. SMS "NoSec" Mode

It is RECOMMENDED to always use LwM2M with one of the security mechanisms described in this specification. However, there are few scenarios and use cases where security is provided by lower layers. For example, LwM2M devices in a controlled environment behind a gateway, or, tests focusing first on other functions before performing end-to-end tests including security.

The use of SMS "NoSec" Mode while the Resource "OSCORE Security Mode" is present indicates that the SMS Channel is protected with OSCORE.

This security profile is also useful to support SMS triggering when all other exchanges utilize CoAP over TLS or CoAP over DTLS.

5.3.2. SMS Secured Mode

The SMS Secured mode specified in this section MUST be supported when the SMS binding is used.

A LwM2M Client which uses the SMS binding MUST either be directly provisioned for use with a target LwM2M Server (Factory Bootstrap or Bootstrap from Smartcard) or else be able to bootstrap via the UDP binding.

The end-point for the SMS channel (delivery of mobile terminated SMS, and sending of mobile originated SMS) MAY be either on the Smartcard or on the Device. When the LwM2M Client device does not support a Smartcard, the end-point is on the LwM2M Client device.

A LwM2M Client, LwM2M Server or LwM2M Bootstrap-Server supporting the SMS binding MUST discard SMS messages not correctly protected using the expected parameters stored in the "SMS Binding Key Parameters" Resource and the expected keys stored in the "SMS Binding Secret Keys" Resource, and MUST NOT respond with an error message secured using the correct parameters and keys.

5.3.2.1. Device End-Point

The Secured Packet Structure is based on [3GPP 31.115] / [ETSI 102 225], which was originally designed for securing packet structures for UICC based applications. However, for LwM2M it is suitable for securing the SMS payload exchanged between the LwM2M Client and the LwM2M Server.

If the SMS channel end-point is on the Device, the Channel security for [CoAP] is based on [RFC6347]. For that reason the text in Section 5.2. TLS/DTLS-based Security concerning the DTLS binding to CoAP is also applicable to this section.

Appendix A of [RFC7925] describes how to bind CoAP/DTLS message to the SMS channel and specifies the restrictions on DTLS for fitting the SMS channel specific functioning and narrow bandwidth.

5.3.2.1.1. Header Definitions (for one SMS)

a) SMS Frame for basic Request/Response Interaction message (no Token field required)

SMS header definition (no token)
Figure: 5.3.2.1.1.-1 SMS header definition (no token)

Model calculation using these header definitions,

b) SMS Frame for messages of the Information Reporting Interface (Token field required)

SMS header definition
Figure: 5.3.2.1.1.-2 SMS header definition

Model calculation using these header definitions,

5.3.2.1.2. Smartcard End-Point

If the SMS channel end-point is on the smart card, a CoAP message as defined in [CoAP] MUST be encapsulated in [3GPP 31.115] Secured Packets, in implementing - for SMS Point to Point (SMS_PP) - the general [ETSI 102 225] specification for UICC based applications.

The following settings MUST be applied:

Class 2 SMS as specified in [3GPP 23.038]. The [3GPP 23.040] SMS header MUST be defined as below:

Secure SMS Transfer to UICC

A SMS Secured Packet encapsulating a CoAP request received by the LwM2M device, MUST be – according to [ETSI 102 225] / [3GPP 31.115] - addressed to the LwM2M UICC Application in the Smartcard where it will be decrypted, aggregated if needed, and checked for integrity.

If decryption and integrity verification succeed, the message contained in the SMS MUST be provided to the LwM2M Client.

If decryption or integrity verification failed, SMS MUST be discarded.

The mechanism for providing the decrypted CoAP Request to the LwM2M Client relies on basic GET_DATA commands of [GLOBALPLATFORM] .This data MUST follow the format as below:

data_rcv _ ::= <address> <coap_msg>

address ::= TP_OA ; originated address

coap_msg ::= CoAP_TAG <coap_request_length> <coap_request>

coap_request_length ::= 16BITS_VALUE

coap_request ::= CoAP message payload

NOTE: In current LwM2M release, the way the LwM2M Client Application is triggered for retrieving the available message from the Smartcard is device specific: i.e. a middle class LwM2M Device implementing [ETSI 102 223] ToolKit with class "e" and "k" support could be automatically triggered by Toolkit mechanisms, whereas a simpler LwM2M device could rely on a polling mechanisms on Smartcard for fetching data when available.

Secured SMS Transfer to LwM2M Server

For sending a CoAP message to the LwM2M Server, the LwM2M Client prepares a data containing the right TP-DA to use, concatenated with the CoAP message and MUST provide that data to the LwM2M UICC Application in using the [GLOBALPLATFORM] STORE-DATA command.

According to [ETSI 102 225] / [3GPP 31.115] the Smartcard will be in charge to prepare (encryption / concatenation) the CoAP message before sending it as a SMS Secure Packet ([ETSI 102 223] SEND_SMS command).

The SMS Secured Packet MUST be formatted as Secured Data specified in Section 5.3.2.1.3. SMS Secured Packet Binding for CoAP messages.

The Secure Channel as specified in Appendix H of [LwM2M-CORE] SHOULD be used to provide the prepared data to the Smartcard.

5.3.2.1.3. SMS Secured Packet Binding for CoAP messages

In SMS Secured Packet Structure mode, a CoAP message as defined in [CoAP] MUST be encapsulated in [3GPP 31.115] Secured Packets, in implementing - for SMS Point to Point (SMS_PP) - the general [ETSI 102 225] specification for UICC based applications.

5.4. OSCORE-based Security

5.4.1. OSCORE Overview

Object Security for Constrained RESTful Environments [OSCORE] is an application layer security protocol protecting CoAP message exchanges. OSCORE is applicable to protocol messages which can be mapped to CoAP or a subset of CoAP, including HTTP and LwM2M.

The use of OSCORE with LwM2M is optional. It MAY be used for protecting the communication between a LwM2M Client and the LwM2M Bootstrap-Server. It MAY be used between a LwM2M Client and a LwM2M Server.

OSCORE MAY also be used between LwM2M endpoint and non-LwM2M endpoint, e.g. between an Application Server and a LwM2M Client via a LwM2M server. Both the LwM2M endpoint and non-LwM2M endpoint MUST implement OSCORE and be provisioned with an OSCORE Security Context as defined in [OSCORE]. The bootstrapping of the non-LwM2M endpoint is out of scope for this specification. The intermediate LwM2M node needs to map the messages from non-LwM2M nodes to LwM2M operations and responses. That mapping is also out of scope for this specification.

The use of OSCORE in CoAP is indicated with the OSCORE Option present in the CoAP message [OSCORE]. It operates by transforming (encrypting etc.) an unprotected CoAP message into a protected CoAP message using the compact secure message format COSE [RFC8152]. The protected CoAP message is sent instead of the unprotected message, and is verified and transformed back to the original message at the receiving end.

OSCORE protects the Request/Response sublayer of CoAP, but leaves the binding to the transport layer protocol unprotected. As a consequence, OSCORE does not depend on the underlying layer and can therefore be applied to CoAP over UDP, TCP, SMS as well as Non-IP, directly over [IEEE802.15.4] or 3GPP CIoT (see Appendix D. LwM2M over 3GPP CIoT - NB-IoT and LTE-M (Informative)). OSCORE is invariant under proxy operations translating between different transport layer protocols, performing application layer forwarding (e.g. CoAP proxies), address translations, etc. and thus enables end-to-end security through these kinds of intermediate nodes.

Not only is OSCORE applicable to CoAP-mappable messages, but the protected messages can also be transported directly in CoAP-mappable protocols. For example, with the HTTP header field "OSCORE" [OSCORE], OSCORE protected messages can be transported in HTTP, providing end-to-end security for CoAP-mappable HTTP. OSCORE also supports proxies translating between HTTP and CoAP as defined in [RFC8075], allowing a mix of HTTP and CoAP along the end-to-end path, which is useful, e.g. for firewall traversals on the Internet.

OSCORE is based on a shared symmetric key and provides security context derivation, encryption, integrity and replay protection, and a secure binding of application layer responses to requests. OSCORE enables mutual authentication between LwM2M Client and LwM2M Bootstrap-Server, and between LwM2M Client and LwM2M Server.

OSCORE is independent of security protocols at other layers, such as DTLS/TLS. If OSCORE is applied with a "Security Mode" Resource value 0-2 (corresponding to DTLS with mode "Pre-Shared Key"/"Raw Public Key"/"Certificate") the message will be protected by both OSCORE and DTLS. When OSCORE is applied with "Security Mode" Resource value 3 (corresponding to DTLS with mode "NoSec"), the message is protected by OSCORE but not DTLS.

OSCORE can be used to secure multicast requests and responses, for example providing low latency in building automation scenarios (lighting, emergency etc.) and for efficient bandwidth usage during firmware updates.

5.4.2. Cryptographic Algorithms

OSCORE is defined for use with an Authenticated Encryption with Additional Data (AEAD) algorithm and a HMAC-based Key Derivation Function (HKDF) [RFC5869]. OSCORE mandates the implementation of the AEAD algorithm AES-CCM-16-64-128 (also known as CCM*) as defined in [RFC8152], and specifies the use of HMAC with SHA-256 as default. LwM2M Clients and LwM2M Servers MAY support additional algorithms that conform to the state-of-the-art security requirements.

5.4.3. Bootstrapping

The OSCORE related Resources in the LwM2M OSCORE Object are used analogously to DTLS/TLS when applied with pre-shared keys (see Section 5.2.4. Bootstrapping). The OSCORE related Resources in the LwM2M OSCORE Object are used for:

  1. providing OSCORE communication security in "Client Registration", "Device Management & Service Enablement", and "Information Reporting" Interfaces if the LwM2M Security Object Instance relates to a LwM2M Server;

  2. providing OSCORE communication security in the "Bootstrap" Interface if the LwM2M Security Object instance relates to a LwM2M Bootstrap-Server;

  3. providing OSCORE communication security with a firmware repository server when the LwM2M Client receives a URI in the Package URI of the Firmware Update object.

In case of Bootstrap from Smartcard, a secure channel between the Smartcard and the LwM2M Client SHOULD be established, as described in Appendix G of [LwM2M-CORE] and defined in [GLOBALPLATFORM]. Using Smartcard with the pre-shared key needs no pre-existing trust relationship between LwM2M Server(s) and LwM2M Client(s). The pre-established trust relationship exists between the LwM2M Server(s) and the SmartCard(s).

If OSCORE is used, then LwM2M Clients MUST either be provisioned for use with a LwM2M Server (manufacturer pre-configuration bootstrap mode) or else be provisioned for use with a LwM2M Bootstrap-Server. Any LwM2M Client, which supports client or server initiated bootstrap mode, MUST support bootstrapping with a strong (high-entropy) pre-shared key. The ciphersuites MUST NOT be used with a low-entropy pre-shared key or a password as pre-shared key. The LwM2M Client MUST be provisioned with a pre-shared key that is unique to a device and to the security protocol. For full interoperability a LwM2M Bootstrap-Server MUST support bootstrapping with pre-shared key.

The OSCORE security context is derived from a small set of input parameters (see Section 3.2 of [OSCORE]). With use of the OSCORE input parameters, the security contexts for sending and receiving OSCORE messages are derived as defined in [OSCORE]. The conditions for reuse of input parameters (see Section 3.3 of [OSCORE]) MUST be complied with. An implementation SHALL follow the procedure described in Appendix B2 of [OSCORE] when the OSCORE security context is used for the first time.

New OSCORE input parameters MAY be provisioned for use between endpoints having an existing OSCORE security context requiring the endpoints to derive new contexts. The Echo option MUST be used by the receiving endpoint when the OSCORE security context is used for the first time (e.g. Bootstrap-Request, Bootstrap-Pack-Request or Register) and SHOULD be used when the requested operation (e.g. Device Management Write) requires freshness that cannot be guaranteed by other means.

5.4.4. Unbootstrapping

The unbootstrapping procedure described in Section 5.2.5. Unbootstrapping applies also to OSCORE.

5.4.5. Endpoint Client Name

The same verification of Endpoint Client Name in the Bootstrap-Request, the Bootstrap-Pack-Request and in the Register messages as described in Section 5.2.6. Endpoint Client Name applies also to OSCORE. However, when using OSCORE, the Endpoint Client Name MAY be authenticated at the application layer, by setting the "OSCORE Sender ID" Resource value (see Section 5.4.7.1. OSCORE Related Resources) to the Endpoint Client Name.

If the OSCORE Sender ID is not set to Endpoint Client Name, then the LwM2M Server MUST compare the received Endpoint Client Name identifier with the OSCORE Sender ID of the LwM2M Client. This comparison may either be an equality match or may involve a dedicated lookup table to ensure that LwM2M Clients cannot intentionally or due to misconfiguration impersonate other LwM2M Clients. The LwM2M Server MUST respond with a "4.00 Bad Request" to the LwM2M Client if these fields do not match.

5.4.6. OSCORE Roles

The OSCORE roles (Client and Server) coincide with the CoAP roles.

[OSCORE] specifies that each endpoint has a Sender ID and a Recipient ID. The Sender ID is used when sending a message and recipient ID when receiving a message, independently of whether the endpoint has the role of an OSCORE Client or an OSCORE Server. Hence the Sender ID of the OSCORE Client has the same value as the Recipient ID of the OSCORE Server, and the Recipient ID of the OSCORE Client has the same value as the Sender ID of the OSCORE Server.

5.4.7. Credential Types

[OSCORE] requires that a shared secret key, called "OSCORE Master Secret", is established in the communicating endpoints. In LwM2M version 1.1 and thereafter, it is assumed that the Master Secret is pre-shared. When the Master Secret used with a LwM2M Server is provisioned to the LwM2M Client, the Master Secret is also known to the provisioning party, e.g. the LwM2M Bootstrapping Server. Applications need to ensure that this assumption is compliant with their trust model.

The use of OSCORE between LwM2M Client and LwM2M Server, or between LwM2M Client and LwM2M Bootstrap-Server is indicated with the optional "OSCORE Security Mode" Resource in the Security Object description.

The presence of the "OSCORE Security Mode" Resource in a Security Object Instance requires the following resources of the LwM2M OSCORE Object to be populated:

Additionally, the following resources of the LwM2M OSCORE Object MAY be populated:

5.5. Identification of Blockwise Requests

The specification of Blockwise [CoAP_Blockwise] is vulnerable to interchange of blocks between different requests to the same resource [CoAP_ERT]. The attack may be performed when the replay window size of the security protocol is greater than 1 even if the requests are not interleaved and the attack applies both to DTLS and OSCORE. The attack does not apply when a connection-oriented transport, like CoAP over TCP is used, or when a replay window size of 1 is selected with DTLS.

A solution is to use the CoAP Request-Tag Option [CoAP_ERT] for unique tagging of requests of a certain scope. The Request-Tag is analogous to the CoAP E-Tag Option, but tags requests instead of responses.

LwM2M Clients and LwM2M Servers supporting Blockwise SHOULD implement the CoAP Request-Tag Option.

5.6. Freshness

A LwM2M Client and LwM2M Server MUST be able to verify the freshness of certain LwM2M operations.

LwM2M operations may have freshness requirements that are not possible to guarantee by protecting individual messages such as with DTLS Record Layer or OSCORE. This is accentuated with unreliable transport. Since datagram transport does not provide reliable or in-order delivery of data, DTLS and OSCORE preserves this property. Although duplicate messages are rejected through the use of anti-replay mechanisms, unordered delivery is still allowed, e.g. using a sliding receive window. As a consequence, maliciously delayed message are accepted as long as they fall within the window.

For example, a Write operation, maliciously blocked from reaching the LwM2M Client at one time, may under these circumstances be successfully injected at a later time, potentially overwriting a more recent Write operation.

Operations protected by a security protocol with keys derived from a TLS/DTLS handshake are at least as fresh as the handshake. However, frequent use of the handshake protocols may be prohibitive in constrained environments. In order to avoid unnecessary processing, a more lightweight solution to verify freshness is provided by the CoAP Echo Option [CoAP_ERT], illustrated with the example above: The LwM2M Client, receiving a Write operation of uncertain freshness may respond with an error message containing an Echo option including a random nonce as value. The LwM2M Server receiving the error response to a valid Write operation retransmits the request with the Echo option and value included. The LwM2M Client receiving a request with an Echo option verifies that the nonce corresponds to a recent request, and only in that case performs the operation (for details, see Section 2 of [CoAP_ERT]).

Applications need to understand the freshness requirements of the operations both in LwM2M Client and LwM2M Server. The LwM2M implementation SHOULD enable timely freshness verifications to be performed without unnecessary overhead. For interoperability both LwM2M Client and LwM2M Server SHOULD implement the CoAP Echo option.

The attack does not apply when a connection-oriented transport, like CoAP over TCP is used, or when a replay window size of 1 is selected with DTLS.

6. CoAP Transport Binding

This section defines the CoAP transport binding used by LwM2M interfaces.

6.1. Features

The CoAP transport binding utilizes the following features:

6.2. Firewall Traversal

For a firewall to support LwM2M using CoAP over UDP and/or CoAP over DTLS it MUST at a minimum be configured to allow outgoing packets to destination port 5683 (for CoAP over UDP), and port 5684 (for CoAP over DTLS), and allow incoming UDP/DTLS packets back to the source address/port of the outgoing UDP packet for a period of at least 240 seconds.

While Queue Mode is not necessary for firewall configuration it should be noted that LwM2M Clients may enable Queue Mode for example to lower power consumption for a battery powered device.

For those deployments where changes to firewall configurations are not possible CoAP over TCP/TLS [CoAP_TCP] SHOULD be used instead. Firewall rule settings for CoAP over TCP/TLS are similar to those described above for CoAP over UDP/DTLS since the port numbers are equivalent, i.e., port 5683 (for CoAP over TCP), and port 5684 (for CoAP over TLS).

6.3. NAT Traversal

A NAT exhibits a behavior similar to a stateful packet filtering firewall where incoming packets are only allowed to traverse the NAT after the client behind the NAT initiated an outgoing connection first. The NAT creates a NAT binding based on the outgoing communication attempt, which is re-used for any packets from the device outside the NAT (i.e., typically the server).

Where NATs are present along the communication path, CoAP over TCP leads to different NAT traversal behavior than CoAP over UDP. NATs often calculate expiration timers based on the transport layer protocol being used by application protocols. Many NATs maintain TCP-based NAT bindings for longer periods based on the assumption that a transport layer protocol, such as TCP, offers additional information about the session lifecycle. UDP, on the other hand, does not provide such information to a NAT and timeouts tend to be much shorter, as described in [CoAP_TCP].

Queue Mode may help with NAT traversal by allowing a LwM2M Server to send messages to the LwM2M Client only after the LwM2M Client has initiated the communication to the LwM2M server first. This ensures that NAT bindings exist that allow incoming packets to the LwM2M Client.

6.4. URI Identifier & Operation Mapping

Although CoAP supports a URI in requests, it is not used in the same way as in HTTP. The URI in CoAP is broken down into binary parts, minimizing overhead and complexity. In LwM2M only path segment and query string URI components are needed. The URI path is used to simply identify the interface, Object Instance or Resource that the request is for, and is encoded in Uri-Path options. The LwM2M Registration interface also makes use of query string parameters to pass on meta-data with the request separately from the payload. Each query parameter is encoded in a Uri-Query Option. Likewise, the LwM2M operations for each interface are mapped to CoAP Methods.

6.4.1. Alternate Path

By default, the LwM2M Objects are located under the root path. However, devices might be hosting other CoAP Resources on an endpoint, and there may be the need to place LwM2M Objects under an alternate path.

When registering, or updating its registration, a LwM2M Client MAY include an OMA LwM2M link in addition to the Object links in the registration payload. The link is identified by [RFC6690] Resource Type parameter "oma.lwm2m".

This link MUST NOT contain numerical URI segment.

When using the Device Management & Service Enablement Interface and the Information Reporting Interface, the LwM2M Server MUST prepend the OMA LwM2M link to the path in the CoAP messages. Example: GET /lwm2m/3/0/0. When using the SenML JSON, SenML CBOR, SenML-ETCH JSON, or the SenML-ETCH CBOR encodings, the alternate path MUST be part of the entries names.

When using the Bootstrap Interface, the LwM2M Bootstrap-Server MUST use CoAP paths only in the form /{Object ID}/{Object Instance ID}/{Resource ID}. It is the responsibility of the LwM2M Client to map these paths to its alternate path. When using the SenML JSON or the SenML CBOR data encoding, the alternate path MUST NOT be part of the entries names.

The Resource Type value "oma.lwm2m" is part of IANA registry.

For instance, the Example Client from Appendix F of [LwM2M-CORE] may place Objects under the "/lwm2m" path. The registration payload would be as follows:

</lwm2m>;rt="oma.lwm2m", </lwm2m/1/0>,</lwm2m/1/1>,</lwm2m/2/0>,</lwm2m/2/1>,</lwm2m/2/2>,</lwm2m/2/3>,</lwm2m/2/4>,</lwm2m/3/0>,</lwm2m/4/0>,</lwm2m/5>

A Read operation on the Manufacturer Resource (ID: 0) of the Device Object (ID: 3) would map to a CoAP GET on /lwm2m/3/0/0. The response payload encoded in SenML JSON would be:

[
  { "n":"/lwm2m/3/0/0", "vs":"Open Mobile Alliance" }
]

A response to a Bootstrap-Pack-Request operation could be:

[{"bn":"/0/1/", "n":"0","vs":"coaps://server1.example.com"},
{"n":"1","vb":false},
{"n":"2","v":0},
{"n":"3","vd":"YjMxM2NjMjItZjk2OS00MmVjLWFkNDI"},
{"n":"4","vd":""},
{"n":"5","vd":"HKICjXGXx3jprvXvaQgr6g"},
{"n":"10","v":101},
{"bn":"/1/0/", "n":"0","v":101},
{"n":"1","v":86400},
{"n":"2","v":300},
{"n":"3","v":6000},
{"n":"5","v":86400},
{"n":"6","vb":true},
{"n":"7","vs":"U"}]

6.4.2. Bootstrap Interface

The Bootstrap Interface is used to optionally configure a LwM2M Client so that it can successfully register with a LwM2M Server. The client bootstrap operation is performed by sending a CoAP request to the LwM2M Bootstrap-Server at the path specified in Table: 6.4.2.-1 Operation to Method and URI Mapping (Bootstrap Interface) including the Endpoint Client Name as a query string parameter.

The Client Bootstrap operation is initiated by the LwM2M Client itself. In addition, this operation can be requested by an authorized LwM2M Server executing the "Bootstrap-Request Trigger" Resource of a Server Object Instance, or even by a proprietary mechanism (e.g. based on SMS). Note: the execution of a "Bootstrap-Request Trigger" Resource by a LwM2M Server in a LwM2M Client is performed through an already established registration and is therefore covered by the access rights mechanisms.

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

In "Client Initiated Bootstrap" mode, if the Bootstrap-Server receives the "Bootstrap-Request" operation, the Bootstrap-Server can perform the "Bootstrap-Write", "Bootstrap-Discover", "Bootstrap-Read" and the "Bootstrap-Delete" operations. The "Bootstrap-Delete" operation targets an Object or an Object Instance, the "Bootstrap-Discover" operation targets an Object, a "Bootstrap-Write" operation targets Object, Object Instance or a Resource, while the "Bootstrap-Read" operation is limited to read a single Instance or all Instances of the Server Object or the Access Control Object (an error is returned otherwise). The "Bootstrap-Write", "Bootstrap-Discover", "Bootstrap-Read" and the "Bootstrap-Delete" operations can be sent multiple times. Only in Bootstrap Interface, the "Bootstrap-Delete" operation MAY target to "/" URI to delete all the existing Object Instances - except LwM2M Bootstrap-Server Account and LwM2M Device object - in the LwM2M Client, for initialization purpose before LwM2M Bootstrap-Server sends "Bootstrap-Write" operation(s) to the LwM2M Client. Different from "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 targeting Object Instance(s) or Resource and access rights.

In "Client Initiated Bootstrap" mode, if the Bootstrap-Server receives the "Bootstrap-Pack-Request" operation, the Bootstrap-Server may respond with a "Bootstrap-Pack" to the LwM2M Client. The "Bootstrap-Pack-Request" operation is performed by sending a CoAP GET request to the LwM2M Bootstrap Server at the "/bspack" path.

Only in Bootstrap Interface, the "Bootstrap-Discover" operation MAY target to "/" URI to discover all Objects and Object Instances supported in the Device.

The Bootstrap-Server MUST send a "Bootstrap-Finish" operation after it has sent all object instances/resources or if the bootstrap operation is terminated. "Bootstrap-Finish" operation is not needed if the "Bootstrap-Pack" is used for bootstrapping. The "Bootstrap-Finish" operation is mapped to a CoAP POST to "/bs" location path with an empty payload.

If [OSCORE] is used to secure Client Bootstrap then the Bootstrap-Server receiving the "Bootstrap-Request" or "Bootstrap-Pack-Request" operation MUST use the Echo Option [CoAP_ERT].

Table: 6.4.2.-1 Operation to Method and URI Mapping (Bootstrap Interface)
Operation CoAP Method URI Payload
Bootstrap-Request POST /bs?ep={Endpoint Client Name}&pct={Preferred Content Format}
Bootstrap-Read GET Accept:Content Format ID: TLV, LwM2M CBOR, SenML CBOR or SenML JSON /{Object ID} in LwM2M 1.1 and thereafter, Object ID MUST be '1' (Server Object) or '2' (Access Control Object)
Bootstrap-Write PUT /{Object ID}
/{Object ID}/{Object Instance ID}
/{Object ID}/{Object Instance ID}/{Resource ID}
{New Value}
Bootstrap-Delete DELETE /{Object ID}/{Object Instance ID}
Bootstrap-Discover GET Accept: application/link-format /{Object ID}
Bootstrap-Finish POST /bs
Bootstrap-Pack-Request GET Accept:Content Format ID: SenML CBOR, SenML JSON, or LwM2M CBOR /bspack?ep={Endpoint Client Name}&acc={LwM2M Bootstrap-Server Account Object Instances}

Available CoAP response codes to the operations are given in Table: 6.7.-1 Response Codes: Bootstrap Interface

Example of Client initiated Bootstrap exchange
Figure: 6.4.2.-1 Example of Client initiated Bootstrap exchange
Example of Client initiated Bootstrap with Bootstrap-Pack exchange
Figure: 6.4.2.-2 Example of Client initiated Bootstrap with Bootstrap-Pack exchange
Example of Server initiated Bootstrap exchange
Figure: 6.4.2.-3 Example of Server initiated Bootstrap exchange

6.4.3. Registration Interface

The registration interface is used by a LwM2M Client to register with a LwM2M Server, identified by the LwM2M Server URI.

Registration is performed by sending a CoAP POST to the LwM2M Server URI /rd, with the LwM2M registration parameters passed as URI query strings as per Table: 6.4.3.-1 Registration Parameters to URI Query String Mapping and Table: 6.4.3.-2 Operation to Method and URI Mapping (Registration Interface). The response includes Location-Path Options, which indicate the path to use for updating or deleting the registration. The LwM2M Server MUST return a location under the /rd path segment.

When the LwM2M Client IP address changes in NoSec mode, the Client MUST register again to the LwM2M Server.

If [OSCORE] is used to secure the Registration, then the Echo Option [CoAP_ERT] MUST at least be used with the first operation.

Registration update is performed by sending a CoAP POST to the Location path returned to the LwM2M Client as a result of a successful registration.

De-registration is performed by sending a CoAP DELETE to the Location path returned to the LwM2M Client as a result of a successful registration.

Table: 6.4.3.-1 Registration Parameters to URI Query String Mapping
LwM2M Registration Parameter URI Query String
Endpoint Client Name ep
Lifetime lt
LwM2M Version lwm2m
Binding Mode b
Queue Mode Q
SMS Number sms
Profile ID pid
Table: 6.4.3.-2 Operation to Method and URI Mapping (Registration Interface)
Operation CoAP Method URI Payload
Register POST /rd?ep={Endpoint Client Name}&lt={Lifetime}&lwm2m={version}&b={binding}&Q&sms={MSISDN}&pid={ProfileID} {Objects and Object Instances}
Update POST /{location}?lt={Lifetime}&b={binding}&Q&sms={MSISDN} {Objects and Object Instances}
De-register DELETE /{location}

Available CoAP response codes to the operations are given in Table: 6.7.-2 Response Codes: Client Registration Interface

Note: Throughout the present document the format of the MSISDN must be as specified in [3GPP 23.003]. According to this definition "+" is not preceding the country code.

Example register, update and de-register operation exchanges (shorthand in \[CoAP\] example style, actual messages using CoAP binary headers
Figure: 6.4.3.-1 Example register, update and de-register operation exchanges (shorthand in [CoAP] example style, actual messages using CoAP binary headers)

6.4.4. Device Management & Service Enablement Interface

The Device Management & Service Enablement Interface is used to access a Resource, a Resource Instance, an array of Resource Instances, an Object Instance or all the Object Instances of an Object. An Object Instance is identified by the path /{Object ID}/{Object Instance ID}. If Object doesn't support multiple Object Instances, the Object Instance is identified by the path /{Object ID}/0. A Resource is identified by the path /{Object ID}/{Object Instance ID}/{Resource ID}. An Instance of a Multiple-Instance Resource is identified by the path /{Object ID}/{Object Instance ID}/{Resource ID}/{Resource Instance ID}. When the rules expressed in [LwM2M-CORE] and related to the path in the command on this LwM2M Interface, are not respected, the error code 4.05 MUST be returned as response code.

An Object Instance, a Resource or a Resource Instance are read by sending a CoAP GET to the corresponding path. The response includes the value in the corresponding format according to the specified Content-Format (see [LwM2M-CORE]). The request MAY specify an Accept option containing the preferred Content-Format to receive. When the specified Content-Format is not supported by the LwM2M Client, the request MUST be rejected (error code 4.06 as defined in [CoAP]).

Note that the response payload may be empty, for instance when performing a Read operation on an Object with no Object Instance. In this case the response code is still 2.05 Content.

An Object Instance, a Resource or a Resource Instance are written by sending a CoAP PUT request to the corresponding path. The request includes the value to be written in the corresponding Plain Text, Opaque, TLV, LwM2M CBOR, SenML CBOR, or SenML JSON format according to the Content-Format option which MUST be specified [CoAP]. In addition, an Object Instance can be written by sending a CoAP POST request; in that case the specified Content-Format MUST be one of the TLV, LwM2M CBOR, SenML CBOR or SenML JSON formats. CoAP PUT is used for Replace. CoAP POST or CoAP iPatch is used for Partial Update.

The Write request MUST be rejected:

A Resource is Executed by sending a CoAP POST to the corresponding path. The definition of the "Execute" operation is described in [LwM2M-CORE]. The "Execute" operation MAY contain a payload, if arguments are required. When a payload in plain text format is used then the ABNF syntax for the arguments described in [LwM2M-CORE] MUST be used.

Note that the behaviour of the "Execute" operation is specified in the Resource description of the Object.

An Object Instance is Created by sending a CoAP POST to the corresponding path. The request includes the value to be written in the corresponding TLV, LwM2M CBOR, SenML CBOR or SenML JSON format according to the Content-Format option which MUST be specified. The rules governing the creation of Resources in the targeted Object Instance are specified in [LwM2M-CORE]. If Object Instance is not listed at the request, the LwM2M Client MUST assign ID of that Object Instance and send back Object Instance ID with "2.01 Created" to the LwM2M Server when Object Instance is Created.

The Create request at object level cannot be distinguished from a Write request at object level as both are translated to a CoAP POST, thus the WRITE operation at object level is not supported for the CoAP binding.

An Object Instance is Deleted by sending a CoAP DELETE to the corresponding path.

When a Resource supports multiple instances, the Resource value is an array of Resource Instances.

<NOTIFICATION> Class Attributes MAY be set by a LwM2M Server using the "Write-Attributes" operation by sending a CoAP PUT on the corresponding path, and can be accessed using the "Discover" operation. The Discover operation (uses a CoAP GET on the corresponding path along with the application/link-format Content type, to retrieve a list of Objects, Object Instances, Resources and their attached or assigned attributes, from the LwM2M Client (see [LwM2M-CORE] for more details on "Discover" operation). With the "Write-Attributes" operation one or more Attributes can be written at a time. When several Attributes are specified in the same "Write-Attributes" operation, they MUST be consistent according to the rules defined in [LwM2M-CORE], otherwise the "Write-Attributes" operation MUST be rejected (4.00 Bad Request).The values of these Attributes are used by the Information Reporting interface to determine how often Notifications are sent regarding that Resource. A LwM2M Client MAY support a separate set of configured Attributes for each individual LwM2M Server.

A "Write-Attributes" operation specifies which value is set to which Attribute and at which level (Object / Object Instance / Resource / Resource Instance). In a similar way, the same operation without value for the specified Attribute, MUST be used to unset this Attribute for the given level; then the precedence rules applies when notification occurs (see [LwM2M-CORE]).

As example:

  1. Write-Attributes /3/0/9?pmin=1 means the Battery Level value will be notified to the Server with a minimum interval of 1sec; this value is set at the Resource level.

  2. Write-Attributes /3/0/9?pmin means the Battery Level will be notified to the Server with a minimum value (pmin) given by the default one (resource 2 of Object Server ID=1), or with another value if this Attribute has been set at another level (Object or Object Instance: see [LwM2M-CORE]).

  3. Write-Attributes /3/0?pmin=10 means that all Resources of Object Instance 0 of the Object ‘Device (ID:3)' will be notified to the Server with a minimum interval of 10 sec; this value is set at the Object Instance level.

  4. Write-Attributes /3/0/9?gt=45&st=10 means the Battery Level will be notified to the Server when:

    1. old value is 45 and new value is 50 due to gt condition

    2. old value is 38 and new value is 49 due to both gt and step conditions

    3. old value is 48 and new value is 42 due to gt condition

Note: if old value is 48 and new value is 55, it is not considered as satisfying any condition.

  1. Write-Attributes /3/0/9?lt=20&gt=85&st=10 means the Battery Level will be notified to the Server when:

    1. old value is 75 and new value is 90 due to both gt and step conditions

    2. old value is 50 and new value is 10 due to both lt and step conditions

    3. old value is 87 and new value is 99 due to step condition

    4. old value is 17 and new value is 24 due to lt condition

Note: if old value is 17 and new value is 12, it is not considered as satisfying any condition.

Table: 6.4.4.-1 Operation to Method and URI Mapping (Device Management & Service Enablement Interface)
Operation CoAP Method and Content Formats Path Payload
Read GET
Accept: see [LwM2M-CORE]
/{Object ID}
/{Object ID}/{Object Instance ID}
/{Object ID}/{Object Instance ID}/{Resource ID}
/{Object ID}/{Object Instance ID}/{Resource ID}/{Resource Instance ID}
Read-Composite FETCH
Content Format: SenML-ETCH JSON, SenML-ETCH CBOR, SenML CBOR or SenML JSON (see [LwM2M-CORE])
Accept: LwM2M CBOR, SenML CBOR, or SenML JSON (see [LwM2M-CORE])
/ {URI paths}
Discover GET
Accept: application/link-format
/{Object ID}<Depth>
/{Object ID}/{Object Instance ID}<Depth>
/{Object ID}/{Object Instance ID}/{Resource ID}<Depth>

Depth: ?depth={Value}
This parameter is optional.
Write (Replace) PUT
Content Format: see [LwM2M-CORE]
/{Object ID}/{Object Instance ID}
/{Object ID}/{Object Instance ID}/{Resource ID}
/{Object ID}/{Object Instance ID}/{Resource ID}/{Resource Instance ID}
{New Value}
Write (Partial Update) POST
Content Format: see [LwM2M-CORE]
/{Object ID}/{Object Instance ID}
/{Object ID}/{Object Instance ID}/{Resource ID} only for Multiple-Instance Resources
{New Value}
Write-Attributes PUT /{Object ID}?<Attributes>
/{Object ID}/{Object Instance ID}?<Attributes>
/{Object ID}/{Object Instance ID}/{Resource ID}?<Attributes>
/{Object ID}/{Object Instance ID}/{Resource ID}/{Resource Instance ID}?<Attributes>

Attributes: pmin={minimum period}&pmax={maximum period}&gt={greater than}&lt={less than}&st={step}&epmin={minimum evaluation period}&epmax={maximum evaluation period}&edge={0 or 1}&con={0 or 1}&hqmax={maximum historical queue}
Write-Composite iPATCH
Content Format: LwM2M CBOR, SenML CBOR, SenML JSON, SenML-ETCH CBOR, or SenML-ETCH JSON (see [LwM2M-CORE])
/ {URI path and a new value for each of resource to be written to}
Execute POST
Content Format: none, or text/plain (see [LwM2M-CORE])
/{Object ID}/{Object Instance ID}/{Resource ID} {Arguments}
Create POST
Content Format: LwM2M CBOR, SenML CBOR, SenML JSON, or TLV (see [LwM2M-CORE])
/{Object ID} {New Value}
Delete DELETE /{Object ID}/{Object Instance ID}
/{Object ID}/{Object Instance ID}/{Resource ID}/{Resource Instance ID}

Available CoAP response codes to the operations are given in Table: 6.7.-3 Response Codes: Device Management and Service Enablement Interface

Example of Device Management & Service Enablement interface exchanges
Figure: 6.4.4.-1 Example of Device Management & Service Enablement interface exchanges
Example of Object Creation and Deletion
Figure: 6.4.4.-2 Example of Object Creation and Deletion

6.4.5. Information Reporting Interface

Periodic and event-triggered reporting about Resource values from the LwM2M Client to the LwM2M Server is achieved through [OBSERVE]. The mechanism to configure and manage observations and notifications is specified in [OBSERVE]. The LwM2M Server may set the Observe attributes of a Resource to affect the behavior of its notifications using the "Write-Attributes" operation (see [LwM2M-CORE]).

The value for an Object, an Object Instance, a Resource or a Resource Instance can also be sent by a LwM2M Client in an unsolicited manner to the LwM2M Server by using the "Send" operation. That operation is carried out by sending a CoAP POST request to a predetermined path on the LwM2M Server. That path is /dp, standing for "data push". The "Content-Format" CoAP option (header) MUST be set to inform the LwM2M Server of the format of the payload sent in that CoAP POST request. The content format MUST be either SenML JSON, SenML CBOR, or LwM2M CBOR format described in [LwM2M-CORE].

As example:

Reporting the location of the LwM2M Client and the radio signal strength:

CoAP POST Uri-Path:"dp" Content-Format:application/senml+json
Payload:
[
  {"n":"/6/0/0", "v":43.61092},
  {"n":"/6/0/1", "v":3.87723},
  {"n":"/4/0/2", "v":-49}
]
Table: 6.4.5.-1 Operation to Method and URI Mapping (Information Reporting Interface)
Operation CoAP Method Path Payload
Observe GET with Observe option = 0 /{Object ID}<Attributes>
/{Object ID}/{Object Instance ID}<Attributes>
/{Object ID}/{Object Instance ID}/{Resource ID}<Attributes>
/{Object ID}/{Object Instance ID}/{Resource ID}/{Resource Instance ID}<Attributes>

Attributes: ?pmin={minimum period}&pmax={maximum period}&gt={greater than}&lt={less than}&st={step}&epmin={minimum evaluation period}&epmax={maximum evaluation period}&edge={0 or 1}&con={0 or 1}&hqmax={maximum historical queue}
Observe-Composite FETCH with Observe option = 0, Content Format ID: SenML-ETCH JSON, SenML-ETCH CBOR, SenML CBOR or SenML JSON, Accept: Content Format ID: LwM2M CBOR, SenML CBOR, or SenML JSON (see [LwM2M-CORE]) /?pmin={minimum period}&pmax={maximum period}&epmin={minimum evaluation period}&epmax={maximum evaluation period}&con={0 or 1} {URI paths for resources to be observed}
Cancel Observation GET with Observe option= 1 /{Object ID}
/{Object ID}/{Object Instance ID}
/{Object ID}/{Object Instance ID}/{Resource ID}
/{Object ID}/{Object Instance ID}/{Resource ID}/{Resource Instance ID}
Cancel Observation-Composite FETCH with Observe option= 1 {URI paths for exactly the same resources listed in the "Observe-Composite" operation that is being canceled}
Notify Asynchronous Response {Updated Value}
Send POST
Content Format: LwM2M CBOR, SenML CBOR, or SenML JSON (See [LwM2M-CORE])
/dp {New Value}

Available CoAP response codes to the operations are given in Table: 6.7.-4 Response Codes: Information Reporting Interface

Example of an Information Reporting exchange
Figure: 6.4.5.-1 Example of an Information Reporting exchange

6.5. Queue Mode Operation

The LwM2M Server MUST support Queue Mode and the LwM2M Client SHOULD support Queue Mode.

The LwM2M Client indicates support of Queue Mode in the registration to the LwM2M Server. When the LwM2M Client is not online, the LwM2M Server does not immediately send downlink requests, but instead waits until the LwM2M Client is online. As such, the Queue Mode offers functionality for a LwM2M Client to inform the LwM2M Server that it may be disconnected for an extended period of time. The LwM2M Server uses this information to adjust timers and relay messages from and to the LwM2M Client accordingly.

The LwM2M Client lets the LwM2M Server know it is awake by sending a registration update message as a Confirmable message. Absent any application specific profiles, it is RECOMMENDED that the LwM2M Client waits at least MAX_TRANSMIT_WAIT seconds [CoAP] from the last CoAP message it sent to the LwM2M Server before intentionally going offline.

In order to find out whether a message was successfully delivered from the LwM2M Server to the LwM2M Client the LwM2M Server has to rely on a response. This response tells the server that the message has been received and processed (regardless of what the result of the processing was). A response can be conveyed to the server in two ways:

If message delivery fails, for example, because the message got lost due to network connectivity issues or because the LMW2M Client was sleeping then CoAP re-transmission behaviour at the LwM2M Server will try to retransmit the message. The CoAP stack at the LwM2M Server will resend the message up to a certain number of attempts, as described in Section 4.2 of [CoAP]. If these retransmission attempts fail, the CoAP stack at the LwM2M Server will give up and inform the LwM2M layer. The LwM2M Server has to inform the application about this failed delivery but this API is outside the scope of the LwM2M specification.

Due to the congestion control approach used by CoAP the LwM2M Server has to wait for a response to a request before sending out the next request from the queue since [CoAP] limits the number of simultaneous outstanding interactions to 1.

Despite the title of the functionality, i.e. Queue Mode, this specification does not mandate an implementation to use queues nor does it specify where such a queue would exist (or any details of such queuing mechanism).

A typical Queue Mode sequence follows the following steps:

  1. The LwM2M Client registers to the LwM2M Server and requests the LwM2M Server to run in Queue mode by using the correct setting in the registration.

  2. The LwM2M Client is recommended to use the CoAP MAX_TRANSMIT_WAIT parameter to set a timer for how long it shall stay awake since last sent/received message to/from the LwM2M Server. After MAX_TRANSMIT_WAIT seconds without any messages from the LwM2M Server, the LwM2M Client enters a sleep mode.

  3. At some point in time the LwM2M Client wakes up again and transmits a registration update message. Note: During the time the LwM2M Client has been sleeping the IP address assigned to it may have been released and / or existing NAT bindings may have been released. If this is the case, then the client needs to re-run the TLS/DTLS handshake with the LwM2M Server since an IP address and/or port number change will destroy the existing security context. For performance and efficiency reasons it is RECOMMENDED to utilize the TLS/DTLS session resumption.

  4. When the LwM2M Server receives a message from the Client, it determines whether any messages need to be sent to the LwM2M Client, as instructed by the application server.

Below is an example flow for Queue Mode in relation to Device Management & Service Enablement Interface.

Example of Device Management & Service Enablement interface exchanges for Queue Mode
Figure: 6.5.-1 Example of Device Management & Service Enablement interface exchanges for Queue Mode

Below is an example flow for Queue Mode in relation to Information Reporting Interface

Example of an Information Reporting exchange for Queue Mode
Figure: 6.5.-2 Example of an Information Reporting exchange for Queue Mode

6.6. SMS Trigger Mechanism

When the LwM2M Client has registered with a Current Transport Binding different than "S", if the Trigger Resource in the matching Server Object Instance exists and is true, the LwM2M Server MAY send an Execute operation over SMS. The LwM2M Client MUST NOT send a response to the Execute operation.

The LwM2M Client MUST ignore any other LwM2M operation sent over SMS when the Current Transport Binding is different than "S".

The LwM2M Client informs the LwM2M Server of its capability to receive trigger messages over SMS by including the SMS Number parameter in its registration message as defined in [LwM2M-CORE].

6.6.1. Registration Update Trigger

When the LwM2M Client has registered to a LwM2M Server, the LwM2M Server can make the LwM2M Client update its registration by executing the Registration Update Trigger Resource in the matching Server Object Instance (see Appendix E of [LwM2M-CORE]).

Below is an example flow to trigger the LwM2M Client in Queue Mode to send Update message to the LwM2M Server regardless of expiration of Lifetime. Post /1/x/8 would bring the LwM2M Client online to connect to the LwM2M server, where "x" represents the right instance pointing to the server. Optionally, a transport can be included in the Registration Update Trigger. Upon receiving POST /1/x/8?0=U, the LwM2M Client MAY use this transport binding to reconnect with the LwM2M Server. In this example, U refers to the UDP Binding. The possible values for the Binding Resource are listed in [LwM2M-CORE].

Example of Device Management & Service Enablement interface exchanges for Queue Mode with SMS Registration Update Trigger
Figure: 6.6.1.-1 Example of Device Management & Service Enablement interface exchanges for Queue Mode with SMS Registration Update Trigger

6.6.2. Bootstrap Trigger

When the LwM2M Client has registered to a LwM2M Server, the LwM2M Server can make the LwM2M Client initiate a "Client Initiated Bootstrap" procedure by executing the Bootstrap-Request Trigger Resource in the matching Server Object Instance (see Appendix E of [LwM2M-CORE]).

6.7. Response Codes

This section lists available response codes of each operation. The codes are divided into each interface. These are the only valid response codes defined in the LwM2M Enabler.

Table: 6.7.-1 Response Codes: Bootstrap Interface
Operations Available CoAP Response Codes Reason Phrase
Bootstrap-Request 2.04 Changed Bootstrap-Request is completed successfully
4.00 Bad Request Unknown Endpoint Client Name
Endpoint Client Name does not match with CN field of X.509 Certificates
4.15 Unsupported content format The specified format is not supported
Bootstrap-Read 2.05 Content "Read" operation is completed successfully
4.00 Bad Request Undetermined error occurred
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of "Read" operation is not found
4.05 Method Not Allowed Target is not allowed for "Read" operation
4.06 Not Acceptable None of the preferred Content-Formats can be returned
Bootstrap-Write 2.04 Changed "Write" operation is completed successfully
4.00 Bad Request The format of data to be written is different
4.15 Unsupported content format The specified format is not supported
Bootstrap-Discover 2.05 Content "Discover" operation is completed successfully
4.00 Bad Request Undetermined error occurred
4.04 Not Found URI of "Discover" operation is not found
Bootstrap-Delete 2.02 Deleted "Delete" operation is completed successfully
4.00 Bad Request Bad or unknown URI provided
Bootstrap-Finish 2.04 Changed Bootstrap-Finished is completed successfully
4.00 Bad Request Bad URI provided
4.06 Not Acceptable Inconsistent loaded configuration
Bootstrap-Pack-Request 2.05 Content The response includes the Bootstrap-Pack.
4.00 Bad Request Undetermined error occurred
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of "Bootstrap-Pack-Request" operation is not found
4.05 Method Not Allowed The LwM2M Client is not allowed for "Bootstrap-Pack-Request" operation
4.06 Not Acceptable The specified Content-Format is not supported
5.01 Not Implemented The operation is not implemented.
Table: 6.7.-2 Response Codes: Client Registration Interface
Operations Available CoAP Response Codes Reason Phrase
Register 2.01 Created "Register" operation is completed successfully
4.00 Bad Request The mandatory parameter is not specified or unknown parameter is specified
Unknown Endpoint Client Name
Endpoint Client Name does not match with CN field of X.509 Certificates
4.01 Unauthorized The client is not authorized to perform the requested action. In the context of OSCORE, this error
code is used when a server rejects an initial request.
4.03 Forbidden The Endpoint Client Name registration in the LwM2M Server is not allowed.
4.09 Conflict The Client registration cannot be successfully used by the LwM2M Server to determine the list
of Objects supported and Object Instances available on the LwM2M Client.
4.12 Precondition Failed Supported LwM2M Versions of the Server and the Client are not compatible
Update 2.04 Changed "Update" operation is completed successfully
4.00 Bad Request The mandatory parameter is not specified or unknown parameter is specified
4.04 Not Found URI of "Update" operation is not found
De-register 2.02 Deleted "De-register" operation is completed successfully
4.00 Bad Request Undetermined error occurred
4.04 Not Found URI of "De-register" operation is not found
Table: 6.7.-3 Response Codes: Device Management and Service Enablement Interface
Operations Available CoAP Response Codes Reason Phrase
Create 2.01 Created "Create" operation is completed successfully
4.00 Bad Request Target (i.e., Object) already exists
Mandatory Resources are not specified
Content Format is not specified
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of "Create" operation is not found
4.05 Method Not Allowed Target is not allowed for "Create" operation
4.06 Not Acceptable The specified Content-Format is not supported
4.15 Unsupported content format The specified format is not supported
Read 2.05 Content "Read" operation is completed successfully
4.00 Bad Request Undetermined error occurred
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of "Read" operation is not found
4.05 Method Not Allowed Target is not allowed for "Read" operation
4.06 Not Acceptable None of the preferred Content-Formats can be returned
Read-Composite 2.05 Content "Read" operation is completed successfully
4.00 Bad Request Undetermined error occurred
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of "Read" operation is not found
4.05 Method Not Allowed Target is not allowed for "Read" operation
4.06 Not Acceptable None of the preferred Content-Formats can be returned
4.15 Unsupported Content-Format The specified format is not supported
Write 2.04 Changed "Write" operation is completed successfully
2.31 Continue
4.00 Bad Request The format of data to be written is different
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of "Write" operation is not found
4.05 Method Not Allowed Target is not allowed for "Write" operation
4.06 Not Acceptable The specified Content-Format is not supported
4.08 Request Entity Incomplete
4.13 Request entity too large
4.15 Unsupported content format The specified format is not supported
Write-Composite 2.04 Changed "Write" operation is completed successfully
4.00 Bad Request The format of data to be written is different
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of "Write" operation is not found
4.05 Method Not Allowed Target is not allowed for "Write" operation
4.06 Not Acceptable The specified Content-Format is not supported
Delete 2.02 Deleted "Delete" operation is completed successfully
4.00 Bad Request Undetermined error occurred
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of "Delete" operation is not found
4.05 Method Not Allowed Target is not allowed for "Delete" operation
Execute 2.04 Changed "Execute" operation is completed successfully
4.00 Bad Request The LwM2M Client doesn't understand the argument in the payload
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of "Execute" operation is not found
4.05 Method Not Allowed Target is not allowed for "Execute" operation
Write-Attributes 2.04 Changed "Write-Attributes" operation is completed successfully
4.00 Bad Request The format of attribute to be written is different
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of "Write-Attributes" operation is not found
4.05 Method Not Allowed Target is not allowed for Write-Attributes operation
Discover 2.05 Content "Discover" operation is completed successfully
4.00 Bad Request Undetermined error occurred
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of "Discover" operation is not found
4.05 Method Not Allowed Target is not allowed for Discover operation
Table: 6.7.-4 Response Codes: Information Reporting Interface
Operations Available CoAP Response Codes Reason Phrase
Observe
Cancel Observation
Cancel Observation-Composite
2.05 Content Operation is completed successfully
4.00 Bad Request Undetermined error occurred
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of Operation is not found or not supported
4.05 Method Not Allowed Target is not allowed for the Operation
4.06 Not Acceptable None of the preferred Content-Formats can be returned
Observe-Composite 2.05 Content Operation is completed successfully
4.00 Bad Request Undetermined error occurred
4.01 Unauthorized Access Right Permission Denied
4.04 Not Found URI of Operation is not found or not supported
4.05 Method Not Allowed Target is not allowed for the Operation
4.06 Not Acceptable None of the preferred Content-Formats can be returned
4.15 Unsupported Content-Format The specified format is not supported
Notify 2.05 Content "Notify" operation is completed successfully
Send 2.04 Changed "Send" operation completed successfully
4.00 Bad Request Undetermined error occurred
4.04 Not Found Reported Object was not registered to the LwM2M Server

If any operation cannot be completed in the client and the reason cannot be described by a 4.xx response code, then a response code from the "Server Error" list of 5.xx return codes MUST be returned.

6.8. CoAP Transport Bindings

The LwM2M Server MUST support and the LwM2M Client SHOULD support the UDP binding, as specified in Section 6.8.1. UDP Binding.

6.8.1. UDP Binding

The CoAP binding for UDP is defined in [CoAP]. The protocol has an IANA registered scheme of coap:// and a default port of 5683. The UDP binding is used in NoSec (no security) mode. The CoAP binding for DTLS is defined in [CoAP]. The URI scheme is coaps:// and the default port is 5684.

Reliability of CoAP messages over the DTLS transport is provided by the built-in retransmission mechanism of CoAP. All the LwM2M operations using CoAP layer MUST be Confirmable CoAP messages, except as follows:

6.8.2. TCP Binding

The CoAP binding for TCP is defined in [CoAP_TCP]. The protocol has an IANA registered scheme of coap+tcp:// and a default port of 5683. The TCP binding is used in NoSec (no security) mode. The CoAP binding for TLS is defined in [CoAP_TCP]. The URI scheme for CoAP over TLS is coaps+tcp:// and the default port is 5684.

6.8.3. SMS Binding

CoAP is used over SMS in this transport binding by placing a CoAP message in the SMS payload using 8-bit encoding. SMS concatenation MAY be used for messages larger than 140 characters. CoAP retransmission is disabled for this binding. A LwM2M Client indicates the use of this binding by including a parameter ("sms") in its registration to the LwM2M Server including the node's MSISDN number.

6.8.4. LoRaWAN Binding

When using LwM2M over LoRaWAN, the LoRaWAN Endpoint MUST be the LwM2M Client. The LwM2M Server and the LwM2M Bootstrap-Server MUST be LoRaWAN Application Servers as defined by [LoRaWAN].

The LoRaWAN binding is used in NoSec (no security) mode. Security is provided by the LoRaWAN transport.

The Server URI MUST be in the form "lorawan://{port}", port being the FPort between 1 and 255 as defined in [LoRaWAN].

Due the limited bandwidth of the LoRaWAN transport, the "register" operation has different parameter requirements on this transport.

Table: 6.8.4.-1 LoRaWAN binding registration parameters
Parameter Required Default Value Notes
Endpoint Client Name No DevEUI This parameter is omitted if the endpoint name is identical to the endpoint DevEUI
Lifetime No 2 592 000 (30 days)
LwM2M Version No 1.1 or 1.2 This parameter can be omitted if the LwM2M enabler version is 1.1
Binding Mode No By nature, the LoRaWAN network is equivalent to Queue Mode.
SMS Number No The value of this parameter is the MSISDN where the LwM2M Client can be reached for use with the SMS binding.
Objects and Object Instances No The list of Objects supported and Object Instances available on the LwM2M Client (Security Object ID:0 MUST not be part of this list).

The Objects and Object Instances list MAY be omitted in the first registration attempt. If the LwM2M Server cannot retrieve this list by out-of-band means (e.g. preconfiguration of the endpoint on the Application Server), it MUST reply to the registration message with a 4.09 (Conflict) code. In this case, the LwM2M Client SHOULD retry to register with a registration message that MUST include the Objects and Object Instances list.

CoAP is used over LoRaWAN in this transport binding by placing a CoAP message in the LoRaWAN packet payload. Piggybacked responses MUST be used.

Due to the high latency of the LoRaWAN network, its asymmetric nature and the intermittent availability of the LoRaWAN endpoints, CoAP retransmission is disabled for this binding and is replaced by the logic defined in Appendix C. CoAP over LoRaWAN (Normative).

6.8.5. CIoT Binding

CoAP can be used over 3GPP CIoT [3GPP 23.720] as part of IP and non-IP data transmissions over User Plane and Control Plane. This is described in more detail in Appendix D. LwM2M over 3GPP CIoT - NB-IoT and LTE-M (Informative).

6.8.6. WebSockets Binding

The CoAP binding for WebSockets is defined in [CoAP_TCP]. The protocol has an IANA registered scheme of coap+ws:// and a default port of 80. The WebSockets binding is used in NoSec (no security) mode. The CoAP binding for WebSockets secured by TLS is defined in [CoAP_TCP]. The URI scheme is coaps+ws:// and the default port is 443.

7. HTTP Transport Binding

This section defines the HTTP transport binding used by LwM2M interfaces. The HTTP transport binding places minimal demands on the version of the HTTP protocol. This transport binding is optional to implement and optional to use. When implemented, this transport binding SHOULD use HTTP/1.1 [RFC2616] and MAY use HTTP/2 [RFC8132]. If an implementation claims conformance to this transport binding it MUST support the features described in this section. For the Information Reporting Interface only a subset of the functionality is provided by this version of the specification, namely the Send operation.

HTTP communication is secured using TLS.

7.1. URI Identifier & Operation Mapping

The URI path is used to identify the interface, Object, Object Instance and Resource the request is for, and is encoded as described in Section 3.2 of [RFC2616].

7.1.1. Alternate Path

By default, the LwM2M Objects are located under the root path. However, devices might be hosting other HTTP Resources on an endpoint, and there may be the need to place LwM2M Objects under an alternate path.

When registering, or updating its registration, a LwM2M Client MAY include an OMA LwM2M link in addition to the Object links in the registration payload. The registration payload uses the CoRE Link Format, which extends the HTTP Link Header field specified in [RFC8288]. The link is identified Resource Type parameter "oma.lwm2m", as defined in [RFC6690].

This link MUST NOT contain numerical URI segment.

For instance, the Example Client from Appendix F of [LwM2M-CORE] may place Objects under the "/lwm2m" path. The registration payload would be as follows:

</lwm2m>;rt="oma.lwm2m", </lwm2m /1/0>,</lwm2m /1/1>,</lwm2m /2/0>,</lwm2m /2/1>,</lwm2m /2/2>,</lwm2m /2/3>,</lwm2m /2/4>,</lwm2m /3/0>,</lwm2m /4/0>,</lwm2m /5>

When using the Device Management & Service Enablement Interface and the Information Reporting Interface, the LwM2M Server MUST prepend the OMA LwM2M link to the path in the HTTP messages. Example: GET /lwm2m/3/0/0.

When using the Bootstrap Interface, the LwM2M Bootstrap-Server MUST use HTTP paths only in the form /{Object ID}/{Object Instance ID}/{Resource ID}. It is the responsibility of the LwM2M Client to map these paths to its alternate path.

The Resource Type value "oma.lwm2m" is part of IANA registry.

7.1.2. Bootstrap Interface

This section provides a mapping of the LwM2M Bootstrap operations to the underlying transport.

Table: 7.1.2.-1 Operation to Method and URI Mapping (Bootstrap Interface)
Operation HTTP Method URI Payload
Bootstrap-Request POST /bs?ep={Endpoint Client Name}&pct={Preferred Content Format}
Bootstrap-Read GET Accept:Content Format ID: TLV, LwM2M CBOR, SenML CBOR or SenML JSON /{Object ID} in LwM2M 1.1 and thereafter, Object ID MUST be '2' (Access Control Object)
Bootstrap-Write PUT /{Object ID}/{Object Instance ID}/{Resource ID} {New Value}
Bootstrap-Delete DELETE /{Object ID}/{Object Instance ID}
Bootstrap-Discover GET Accept: application/link-format /{Object ID}
Bootstrap-Finish POST /bs
Bootstrap-Pack-Request GET Accept:Content Format ID: SenML CBOR, SenML JSON, or LwM2M CBOR /bspack?ep={Endpoint Client Name}&acc={LwM2M Bootstrap-Server Account Object Instances}

Available HTTP response codes to the operations are given in Table: 6.7.-1 Response Codes: Bootstrap Interface

7.1.3. Registration Interface

The registration interface is used by a LwM2M Client to register with a LwM2M Server, identified by the LwM2M Server URI.

Registration is performed by sending a HTTP POST to the LwM2M Server URI /rd, with registration parameters passed as query string parameters as per Table: 6.4.3.-2 Operation to Method and URI Mapping (Registration Interface) and Object and Object Instances included in the payload as specified in [LwM2M-CORE]. The response includes the path to use for updating or deleting the registration. The LwM2M Server MUST return a location under the /rd path segment.

As the network connectivity may be limited or intermittent, it is advised to make several retries of the Registration if no reply is received from the LwM2M Server before considering the registration as failed.

When a new security context is created, the Client MUST register again to the LwM2M Server.

Registration update is performed by sending a HTTP POST to the path returned to the LwM2M Client as a result of a successful registration.

De-registration is performed by sending a HTTP DELETE to the path returned to the LwM2M Client as a result of a successful registration.

Table: 7.1.3.-1 Operation to Method and URI Mapping (Registration Interface)
Operation HTTP Method URI Payload
Register POST /rd?ep={Endpoint Client Name}&lt={Lifetime}&lwm2m={version}&b={binding}&Q&sms={MSISDN}&pid={ProfileID} {Objects and Object Instances}
Update POST /{location}?lt={Lifetime}&b={binding}&Q&sms={MSISDN} {Objects and Object Instances}
De-register DELETE /{location}

Available HTTP response codes to the operations are given in Table: 6.7.-2 Response Codes: Client Registration Interface

Note: Throughout the present document the format of the MSISDN must be as specified in [3GPP 23.003]. According to this definition "+" is not preceding the country code.

7.1.4. Device Management & Service Enablement Interface

The Device Management & Service Enablement Interface is used to access a Resource, a Resource Instance, an array of Resource Instances, an Object Instance or all the Object Instances of an Object.

An Object Instance, a Resource or a Resource Instance are read by sending a HTTP GET to the corresponding path. The response includes the value in the corresponding format according to the specified Content-Format (see [LwM2M-CORE]). The request MAY specify an Accept option containing the preferred Content-Format to receive. When the specified Content-Format is not supported by the LwM2M Client, the request MUST be rejected.

Note that the response payload may be empty, for instance when performing a Read operation on an Object with no Object Instance.

An Object Instance, a Resource or a Resource Instance are written by sending a HTTP PUT request to the corresponding path. The request includes the value to be written in the corresponding Plain Text, Opaque, TLV, CBOR, LwM2M CBOR, SenML CBOR, or SenML JSON format according to the Content-Format option, which MUST be specified [RFC7540]. In addition, an Object Instance can be written by sending a HTTP POST request; in that case the specified Content-Format MUST be one of the TLV, LwM2M CBOR, SenML CBOR or SenML JSON formats. HTTP PUT is used for Replace. HTTP POST is used for Partial Update.

The Write request MUST be rejected:

A Resource is Executed by sending a HTTP POST to the corresponding path. The definition of the "Execute" operation is described in [LwM2M-CORE]. The "Execute" operation MAY contain a payload, if arguments are required. When a payload in plain text format is used then the ABNF syntax for the arguments described in [LwM2M-CORE] MUST be used.

Note that the behaviour of the "Execute" operation is specified in the Resource description of the Object.

An Object Instance is Created by sending a HTTP POST to the corresponding path. The request includes the value to be written in the corresponding TLV, SenML CBOR or SenML JSON format according to the Content-Format option which MUST be specified. The rules governing the creation of Resources in the targeted Object Instance are specified in [LwM2M-CORE]. If Object Instance is not listed at the request, the LwM2M Client MUST assign ID of that Object Instance and send back Object Instance ID to the LwM2M Server when Object Instance is Created.

An Object Instance is Deleted by sending a HTTP DELETE to the corresponding path.

When a Resource supports multiple instances, the Resource value is an array of Resource Instances.

<NOTIFICATION> Class Attributes MAY be set by a LwM2M Server using the "Write-Attributes" operation by sending a HTTP PUT on the corresponding path, and can be accessed using the "Discover" operation. The Discover operation (uses a HTTP GET on the corresponding path along with the application/link-format Content type, to retrieve a list of Objects, Object Instances, Resources and their attached or assigned attributes, from the LwM2M Client (see [LwM2M-CORE] for more details on "Discover" operation). With the "Write-Attributes" operation one or more Attributes can be written at a time. When several Attributes are specified in the same "Write-Attributes" operation, they MUST be consistent according to the rules defined in [LwM2M-CORE], otherwise the "Write-Attributes" operation MUST be rejected. The values of these Attributes are used by the Information Reporting interface to determine how often Notifications are sent regarding that Resource. A LwM2M Client MAY support a separate set of configured Attributes for each individual LwM2M Server.

Note: Notifications in the Information Reporting interface are provided only via the Send operation; no further operations from the Information Reporting interface are supported by this version of the transport binding.

A "Write-Attributes" operation specifies which value is set to which Attribute and at which level (Object / Object Instance / Resource / Resource Instance). In a similar way, the same operation without value for the specified Attribute, MUST be used to unset this Attribute for the given level; then the precedence rules apply when notification occurs (see [LwM2M-CORE]).

Note: The HTTP transport binding does not support the Read-Composite and the Write-Composite operations.

Table: 7.1.4.-1 Operation to Method and URI Mapping (Device Management & Service Enablement Interface)
Operation HTTP Method and Content Formats Path Payload
Read GET
Accept: see [LwM2M-CORE]
/{Object ID}
/{Object ID}/{Object Instance ID}
/{Object ID}/{Object Instance ID}/{Resource ID}
/{Object ID}/{Object Instance ID}/{Resource ID}/{Resource Instance ID}
Discover GET
Accept: application/link-format
/{Object ID}<Depth>
/{Object ID}/{Object Instance ID}<Depth>
/{Object ID}/{Object Instance ID}/{Resource ID}<Depth>

Depth: ?depth={Depth}
This parameter is optional.
Write (Replace) PUT
Content Format: see [LwM2M-CORE]
/{Object ID}/{Object Instance ID}
/{Object ID}/{Object Instance ID}/{Resource ID}
/{Object ID}/{Object Instance ID}/{Resource ID}/{Resource Instance ID}
{New Value}
Write (Partial Update) POST
Content Format: see [LwM2M-CORE]
/{Object ID}/{Object Instance ID}
/{Object ID}/{Object Instance ID}/{Resource ID} only for Multiple-Instance Resources
{New Value}
Write-Attributes PUT /{Object ID}?<Attributes>
/{Object ID}/{Object Instance ID}?<Attributes>
/{Object ID}/{Object Instance ID}/{Resource ID}?<Attributes>
/{Object ID}/{Object Instance ID}/{Resource ID}/{Resource Instance ID}?<Attributes>

Atttibutes: pmin={minimum period}&pmax={maximum period}&gt={greater than}&lt={less than}&st={step}&epmin={minimum evaluation period}&epmax={maximum evaluation period}&edge={0 or 1}&con={0 or 1}&hqmax={maximum historical queue}
{New Value}
Execute POST
Content Format: none, or text/plain (see [LwM2M-CORE])
/{Object ID}/{Object Instance ID}/{Resource ID} {Arguments}
Create POST
Content Format: SenML CBOR, SenML JSON, LwM2M CBOR, or TLV (see [LwM2M-CORE])
/{Object ID} {New Value}
Delete DELETE /{Object ID}/{Object Instance ID}
/{Object ID}/{Object Instance ID}/{Resource ID}/{Resource Instance ID}

Available HTTP status codes to the operations are given in Table: 6.7.-3 Response Codes: Device Management and Service Enablement Interface

7.1.5. Information Reporting Interface

This version of the HTTP binding supports only a subset of the functionality of the Information Reporting interface: only the Send operation is supported. The value for an Object, an Object Instance, a Resource or a Resource Instance is thereby sent by a LwM2M Client to the LwM2M Server by using the "Send" operation. That operation is carried out by sending a HTTP POST request to a predetermined path on the LwM2M Server. That path is /dp, standing for "data push". The "Content-Format" HTTP option (header) MUST be set to inform the LwM2M Server of the format of the payload sent in that HTTP POST request. The content format MUST be either LwM2M CBOR, SenML JSON, or SenML CBOR format described in [LwM2M-CORE].

Table: 7.1.5.-1 Operation to Method and URI Mapping (Information Reporting Interface)
Operation HTTP Method Path Payload
Send POST
Content Format: LwM2M CBOR, SenML CBOR or SenML JSON (See [LwM2M-CORE])
/dp {New Value}

Available HTTP response codes to the operations are given in Table: 6.7.-4 Response Codes: Information Reporting Interface

7.2. Queue Mode Operation

The LwM2M Server MUST support Queue Mode and the LwM2M Client SHOULD support Queue Mode.

The LwM2M Client indicates support of Queue Mode in the registration to the LwM2M Server. When the LwM2M Client is not online, the LwM2M Server does not immediately send downlink requests, but instead waits until the LwM2M Client is online. As such, the Queue Mode offers functionality for a LwM2M Client to inform the LwM2M Server that it may be disconnected for an extended period of time. The LwM2M Server uses this information to adjust timers and relay messages from and to the LwM2M Client accordingly.

The LwM2M Client lets the LwM2M Server know it is awake by sending a registration update message.

7.3. Response Codes

This section lists available response codes of each operation. The codes are divided into each interface. These are the only valid response codes defined in for the LwM2M Enabler.

Table: 7.3.-1 Response Codes: Bootstrap Interface
Operations Available HTTP Status Codes Reason Phrase
Bootstrap-Request 200 OK Bootstrap-Request is completed successfully
400 Bad Request Unknown Endpoint Client Name
Endpoint Client Name does not match with CN field of X.509 Certificates
415 Unsupported Media Type The specified format is not supported
Bootstrap-Read 200 OK or 204 No Content "Read" operation is completed successfully
400 Bad Request Undetermined error occurred
401 Unauthorized or 403 Forbidden Access Right Permission Denied
404 Not Found URI of "Read" operation is not found
400 Bad Request or 405 Method Not Allowed Target is not allowed for "Read" operation
406 Not Acceptable None of the preferred Content-Formats can be returned
Bootstrap-Write 200 OK or 204 No Content "Write" operation is completed successfully
400 Bad Request The format of data to be written is different
415 Unsupported Media Type The specified format is not supported
Bootstrap-Discover 200 OK "Discover" operation is completed successfully
400 Bad Request Undetermined error occurred
404 Not Found URI of "Discover" operation is not found
Bootstrap-Delete 200 OK or 204 No Content "Delete" operation is completed successfully
400 Bad Request Bad or unknown URI provided
Bootstrap-Finish 200 OK or 204 No Content Bootstrap-Finished is completed successfully
400 Bad Request Bad URI provided
406 Not Acceptable Inconsistent loaded configuration
Bootstrap-Pack-Request 200 OK The response includes the Bootstrap-Pack.
400 Bad Request Undetermined error occurred
401 Unauthorized Access Right Permission Denied
404 Not Found URI of "Bootstrap-Pack-Request" operation is not found
405 Method Not Allowed The LwM2M Client is not allowed for "Bootstrap-Pack-Request" operation
406 Not Acceptable The specified Content-Format is not supported
501 Not Implemented The LwM2M Bootstrap-Server does not support "Bootstrap-Pack-Request"
Table: 7.3.-2 Response Codes: Client Registration Interface
Operations Available HTTP Response Codes Reason Phrase
Register 201 Created "Register" operation is completed successfully
400 Bad Request The mandatory parameter is not specified or unknown parameter is specified
Unknown Endpoint Client Name
Endpoint Client Name does not match with CN field of X.509 Certificates
401 Unauthorized or 403 Forbidden The Endpoint Client Name registration in the LwM2M Server is not allowed.
409 Conflict The Client registration conflicts with the LwM2M Server's configuration.
412 Precondition Failed Supported LwM2M Versions of the Server and the Client are not compatible
Update 200 OK or 204 No Content "Update" operation is completed successfully
400 Bad Request The mandatory parameter is not specified or unknown parameter is specified
404 Not Found URI of "Update" operation is not found
De-register 200 OK or 204 No Content "De-register" operation is completed successfully
400 Bad Request Undetermined error occurred
404 Not Found URI of "De-register" operation is not found
Table: 7.3.-3 Response Codes: Device Management and Service Enablement Interface
Operations Available HTTP Response Codes Reason Phrase
Create 200 OK or 204 No Content "Create" operation is completed successfully
400 Bad Request Target (i.e., Object) already exists
Mandatory Resources are not specified
Content Format is not specified
401 Unauthorized or 403 Forbidden Access Right Permission Denied
404 Not Found URI of "Create" operation is not found
405 Method Not Allowed Target is not allowed for "Create" operation
400 Bad Request
415 Unsupported Media Type The specified format is not supported
Read 200 OK "Read" operation is completed successfully
400 Bad Request Undetermined error occurred
401 Unauthorized Access Right Permission Denied
404 Not Found URI of "Read" operation is not found
405 Method Not Allowed Target is not allowed for "Read" operation
406 Bad Request None of the preferred Content-Formats can be returned
Read-Composite 200 OK "Read" operation is completed successfully
400 Bad Request Undetermined error occurred
401 Unauthorized or 403 Forbidden Access Right Permission Denied
404 Not Found URI of "Read" operation is not found
405 Method Not Allowed Target is not allowed for "Read" operation
406 Not Acceptable None of the preferred Content-Formats can be returned
415 Unsupported Media Type The specified format is not supported
Write 200 OK or 204 No Content "Write" operation is completed successfully
400 Bad Request The format of data to be written is different
401 Unauthorized or 403 Forbidden Access Right Permission Denied
404 Not Found URI of "Write" operation is not found
405 Method Not Allowed Target is not allowed for "Write" operation
406 Not Acceptable The specified Content-Format is not supported
413 Payload Too Large
415 Unsupported Media Type The specified format is not supported
Write-Composite 200 OK or 204 No Content "Write" operation is completed successfully
400 Bad Request The format of data to be written is different
401 Unauthorized or 403 Forbidden Access Right Permission Denied
404 Not Found URI of "Write" operation is not found
405 Method Not Allowed Target is not allowed for "Write" operation
406 Not Acceptable The specified Content-Format is not supported
Delete 200 OK or 204 Not Modified "Delete" operation is completed successfully
400 Bad Request Undetermined error occurred
401 Unauthorized or 403 Forbidden Access Right Permission Denied
404 Not Found URI of "Delete" operation is not found
405 Method Not Allowed Target is not allowed for "Delete" operation
Execute 200 OK "Execute" operation is completed successfully
400 Bad Request The LwM2M Client doesn't understand the argument in the payload
401 Unauthorized or 403 Forbidden Access Right Permission Denied
404 Not Found URI of "Execute" operation is not found
405 Method Not Allowed Target is not allowed for "Execute" operation
Write-Attributes 200 OK or 204 Not Modified "Write-Attributes" operation is completed successfully
400 Bad Request The format of attribute to be written is different
401 Unauthorized or 403 Forbidden Access Right Permission Denied
404 Not Found URI of "Write-Attributes" operation is not found
405 Method Not Allowed Target is not allowed for Write-Attributes operation
Discover 200 OK "Discover" operation is completed successfully
400 Bad Request Undetermined error occurred
401 Unauthorized or 403 Forbidden Access Right Permission Denied
404 Not Found URI of "Discover" operation is not found
405 Method Not Allowed Target is not allowed for Discover operation
Table: 7.3.-4 Response Codes: Information Reporting Interface
Operations Available HTTP Response Codes Reason Phrase
Send 200 OK or 204 No Content "Send" operation completed successfully
400 Bad Request Undetermined error occurred
404 Not Found Reported Object was not registered to the LwM2M Server

If any operation cannot be completed in the client and the reason cannot be described by a 4xx status code, then a status code from the "Server Error" list of 5xx return codes MUST be returned.

8. MQTT Transport Binding

This section defines the Message Queuing Telemetry Transport (MQTT) transport binding used by LwM2M interfaces.

To support LwM2M over MQTT this section

The transport of LwM2M over MQTT does not use any features introduced with MQTT v5 and therefore works with both versions, MQTT 3.1.1 [MQTT] and [MQTT5].

8.1. Communication Behavior

MQTT is a publish-subscribe-based messaging protocol. An MQTT system consists of MQTT clients communicating with an MQTT server. MQTT servers, as officially called in the MQTT specification, are also known as MQTT brokers. Message routing in MQTT is accomplished via topics. When a publisher has a new data item to distribute, it sends a control message to the connected MQTT server marked with a topic along with the data. The MQTT server then distributes the information to any MQTT clients that have subscribed to that topic. If an MQTT server receives a message addressed to a topic for which there are no current subscribers, it will discard the message unless the publisher indicates that the messages is to be retained. This allows new subscribers to a topic to receive the most current data rather than waiting for the next update from a publisher.

In some transport mappings of LwM2M, the endpoints have a direct connection. To exclude on-path adversaries from eavesdropping on the exchanged LwM2M messages, it was necessary to use communication security. The MQTT communication architecture also allows authorized MQTT clients to gain access to messages by subscribing to messages matching a specific topic; wildcards relax the exact matching requirement.

When LwM2M Clients belonging to different customers (tenants) are connected to the same MQTT server then the security concern is that a LwM2M Client from customer A can subscribe to messages sent and received by LwM2M Clients of another customer, customer B. This would allow customer A to learn about the number of devices deployed by customer B, and to see the message contents. There is also the risk that devices deployed by customer A inject messages targeted at the devices of customer B. In the worst case, any device connected to the MQTT server could impersonate a LwM2M Bootstrap-Server.

To provide security properties for LwM2M over MQTT that are comparable with LwM2M over other transports, such as CoAP over UDP and CoAP over TCP, this specification recommends three techniques:

There are different deployment strategies that impact the security characteristics of LwM2M over MQTT. We present two possible deployments here without restricting the deployment to other configurations.

In Figure: 8.1.-1 Colocated MQTT Server / LwM2M Server Deployment the MQTT server is co-located with the LwM2M Server and this approach closely reassembles the architecture of LwM2M.

Colocated MQTT Server / LwM2M Server Deployment
Figure: 8.1.-1 Colocated MQTT Server / LwM2M Server Deployment

In Figure: 8.1.-2 Independent MQTT Server Deployment a deployment is shown where the MQTT server is independently operated from the LwM2M Server and from the LwM2M Bootstrap-Server.

Independent MQTT Server Deployment
Figure: 8.1.-2 Independent MQTT Server Deployment

In both deployment cases, access control lists at the MQTT server can be used. Where access control lists are considered impractical, or insufficient to meet the security needs of a deployment, this specification also offers a technique for protecting the confidentiality and integrity of application data carried over MQTT.

8.2. Topic Structure

A structured MQTT topic format is used to allow LwM2M Clients and LwM2M Servers to subscribe to and obtain those messages they are interested in.

The structure of the topics, in ABNF format, is defined as follows. In MQTT the topic name is an UTF-8 encoded string where wildcard characters ('#', '*', and '$' have a special meaning). See Section 3.3.2.1 and Section 1.5.3 of [MQTT] for more details. The ABNF for UTF-8 encoded strings (and for UTF8-octets) is defined in [RFC3629].

ENDPOINT  = UTF8-octets
PREFIX    = UTF8-octets

topic = [ PREFIX "/" ] "lwm2m/" ( "bs" / "rd" ) "/" ENDPOINT 

The topic structure has to be read as follows:

8.3. Interface Mappings

Interfaces use messages transmitted to specific topics. The structure and content of the messages depend on the interface used. Table 6.-1 "Relationship of operations and interfaces" of [LwM2M-CORE] provides information about the direction of various messages. Many of the messages do, however, follow a regular pattern starting with the operation followed by a token value. The operation indicates the message type while the token is used for matching a response to a request. The value of the token needs to be chosen such that responses can be mapped unambiguously to a request. There are no randomness requirements for the token value.

Messages are encoded in CBOR. The sections below describe what payload content is used for each interface.

The publish / subscribe model used by the LwM2M interfaces is defined as follows:

Note: The parameters {ENDPOINT} and {PREFIX} have to be replaced with the respective string used in a given deployment.

The interaction with a LwM2M Bootstrap-Server is similar with the exception that the topic name includes the "bs" string (instead of "rd") to indicate the bootstrap interface.

8.3.1. Bootstrap Interface

The bootstrap interface uses the following operations (along with the code):

The bootstrap interface uses the following parameters:

The generic Bootstrap payload structure, expressed in CDDL from [RFC8610], is defined as follows:

Bootstrap_Payload = {
    operation => uint,
    token => uint,
    ? ct => uint,
    ? pct => uint,
    ? uri => tstr,
    ? payload => bstr,
    * $$extensions
}
Table: 8.3.1.-1 Operation to MQTT payload (Bootstrap Interface)
Operation Bootstrap_Payload
Bootstrap-Request {
  operation => 0,
  token => uint,
  ? pct => uint, ; Preferred Content Format
}
Bootstrap-Read {
  operation => 2,
  token => uint,
  uri => tstr, ; URI to read
}
Bootstrap-Write {
  operation => 1,
  token => uint,
  ? uri => tstr, ; URI to write
  ct => uint, ; TLV, LwM2M CBOR, SenML CBOR or SenML JSON
  payload => bstr, ; New Value
}
Bootstrap-Delete {
  operation => 3,
  token => uint,
  uri => tstr, ; URI to delete
}
Bootstrap-Discover {
  operation => 4,
  token => uint,
  uri => tstr, ; URI to discover
}
Bootstrap-Finish {
  operation => 5,
  token => uint
}
Bootstrap-Pack-Request {
  operation => 6,
  token => uint,
  ? payload => bstr ; LwM2M Bootstrap-Server Account Object Instances
}

The following example in commented CBOR diagnostic format shows a LwM2M Client posting a Bootstrap-Request to tenant-a/lwm2m/bs/b1cccdea-22ca-4448-bcf7-d07317ee0361 (whereby "tenant-a" is used as a prefix to indicate the name of a tenant, and "b1cccdea-22ca-4448-bcf7-d07317ee0361" is the endpoint name of the LwM2M Client).

{
  1 : 0,   // operation Bootstrap-Request
  2 : 42   // token
}

8.3.2. Registration Interface

The registration interface uses the following operations (along with the code)

The registration interface uses the following parameters:

The payload contains links, according to the definition of the registration interface, in CoRE Link format.

The generic Registration payload structure, expressed in CDDL from [RFC8610], is defined as follows:

Registration_Payload = {
    operation => uint,
    token => uint,
    ? lifetime => uint,
    ? version => tstr,
    ? b => tstr,
    ? sms => tstr,
    ? pid => tstr,
    ? payload => bstr,
    * $$extensions
}   
Table: 8.3.2.-1 Operation to MQTT payload (Registration Interface)
Operation Registration_Payload
Register {
  operation => 6,
  token => uint,
  lifetime => uint, ; Lifetime
  version => tstr, ; version
  ? b => tstr, ; binding
  ? sms => tstr, ; MSISDN
  ? pid => tstr, ; ProfileID
  ? payload => bstr, ; Objects and Object Instances
}
Update {
  operation => 7,
  token => uint,
  ? lifetime => uint, ; Lifetime
  ? b => tstr, ; binding
  ? sms => tstr, ; MSISDN
  ? pid => tstr, ; ProfileID
  ? payload => bstr, ; Objects and Object Instances
}
De-register {
  operation => 8,
  token => uint
}

The following example in commented CBOR diagnostic format shows a LwM2M Client posting a Register to tenant-a/lwm2m/rd/b1cccdea-22ca-4448-bcf7-d07317ee0361 (whereby "tenant-a" is used as a prefix to indicate the name of a tenant, and "b1cccdea-22ca-4448-bcf7-d07317ee0361" is the endpoint name of the LwM2M Client).

{
  1 : 6,                 // operation Register
  2 : 34,                // token
  9 : "1.2",             // version
  8 : 3600,              // lifetime
  7 : h'a8393..8aa8a',   // payload "</1/0>,</1/1>,</3/0>,</4/0>,</5/0>"
}

8.3.3. Device Management & Service Enablement Interface

The device management & service enablement interface uses the following operations:

The device management & service enablement interface uses the following parameters:

The paths parameter is used in the Read-Composite operation to encode the URI paths in SenML-ETCH CBOR format.

The generic Device Management & Service Enablement payload structure, expressed in CDDL from [RFC8610], is defined as follows:

DMSE_Payload = {
    operation => uint,
    token => uint,
    ? pmin =>  uint,
    ? pmax => uint,
    ? gt => float,
    ? lt => float,
    ? st => float,
    ? epmin => uint,
    ? epmax => uint,
    ? edge => 0 / 1,
    ? hqmax => uint,
    ? uri => tstr,
    ? paths => bstr,
    ? depth => 0..3,
    ? ct => uint,
    ? payload => bstr,
    * $$extensions
}
Table: 8.3.3.-1 Operation to MQTT payload (Device Management & Service Enablement Interface)
Operation DMSE_Payload
Read {
  operation => 9,
  token => uint,
  uri => tstr, ; URI to read
}
Read-Composite {
  operation => 10,
  token => uint,
  paths => bstr, ; Paths to read
}
Discover {
  operation => 11,
  token => uint,
  uri => tstr, ; URI to discover
  ? depth => 0..3
}
Write Replace {
  operation => 12,
  token => uint,
  uri => tstr, ; URI to write
  ct => uint, ; see [LwM2M-CORE]
  payload => bstr, ; New Value
}
Write Partial Update {
  operation => 13,
  token => uint,
  uri => tstr, ; URI to write
  ct => uint, ; see [LwM2M-CORE]
  payload => bstr, ; New Value
}
Write-Attributes {
  operation => 14,
  token => uint,
  uri => tstr, ; URI to write attribute
  ? pmin => uint, ; minimum period
  ? pmax => uint, ; maximum period
  ? gt => float, ; greater than
  ? lt => float, ; less than
  ? st => float, ; step
  ? epmin => uint, ; minimum evaluation period
  ? epmax => uint, ; maximum evaluation period
  ? edge => 0 / 1,
  ? hqmax => uint, ; maximum historical queue
}
Write-Composite {
  operation => 15,
  token => uint,
  ct => uint, ; TLV, LwM2M CBOR, SenML CBOR or SenML JSON
  payload => bstr, ; New Value
}
Execute {
  operation => 16,
  token => uint,
  uri => tstr, ; URI to execute
  ? payload => bstr, ; Arguments
}
Create {
  operation => 17,
  token => uint,
  uri => tstr, ; URI to Object
  ct => uint, ; TLV, LwM2M CBOR, SenML CBOR or SenML JSON
  payload => bstr, ; New Value
}
Delete {
  operation => 18,
  token => uint,
  uri => tstr, ; URI to delete
}

The following example in commented CBOR diagnostic format shows a LwM2M Server sending a Read operation to tenant-a/lwm2m/rd/b1cccdea-22ca-4448-bcf7-d07317ee0361 (whereby "tenant-a" is used as a prefix to indicate the name of a tenant, and "b1cccdea-22ca-4448-bcf7-d07317ee0361" is the endpoint name of the LwM2M Client).

{
  1 : 9,         // operation Read
  2 : 56,        // token
  5 : "/3/0/0"   // uri
}

8.3.4. Information Reporting Interface

The information reporting interface uses the following operations:

The information reporting interface uses the following parameters:

The generic Information Reporting payload structure, expressed in CDDL from [RFC8610], is defined as follows:

IR_Payload = {
    operation => uint,
    token => uint,
    ? uri => tstr,
    ? paths => bstr,
    ? ct => uint,
    ? payload => bstr,
    * $$extensions
}
Table: 8.3.4.-1 Operation to MQTT payload (Information Reporting Interface)
Operation IR_Payload
Observe {
  operation => 20,
  token => uint,
  uri => tstr, ; URI to observe
}
Observe-Composite {
  operation => 21,
  token => uint,
  paths => bstr, ; Paths to observe
}
Cancel-Observe {
  operation => 22,
  token => uint, ; token of the observation to cancel
}
Notify {
  operation => 23,
  token => uint, ; token of the observation
  ct => uint, ; see [LwM2M-CORE]
  payload => bstr, ; Updated Value
}
Send {
  operation => 24,
  token => uint,
  ct => uint, ; LwM2M CBOR, SenML CBOR or SenML JSON
  payload => bstr, ; Updated Value
}

The following example in commented CBOR diagnostic format shows a LwM2M Client sending a Send operation to tenant-a/lwm2m/rd/b1cccdea-22ca-4448-bcf7-d07317ee0361 (whereby "tenant-a" is used as a prefix to indicate the name of a tenant, and "b1cccdea-22ca-4448-bcf7-d07317ee0361" is the endpoint name of the LwM2M Client).

{
  1 : 23,                              // operation Send
  2 : 78,                              // token
  19 : 112,                            // content-type application/senml+cbor
  7 : h'82A321652F332F302F006139020F   // payload [{-2: "/3/0/", 0: "9", 2: 15},
        A200623230024'                 //          {0: "20", 2: 4}]
}

8.4. Generic Response Payload Structure

The response codes are contained in the result payload. The payload has the following structure:

Generic_Response_Payload = {
    result => uint,
    token => uint,
    ? ct => uint,
    ? payload => bstr,
    * $$extensions
}

The following example in commented CBOR diagnostic format shows a LwM2M Client sending a response message to tenant-a/lwm2m/rd/b1cccdea-22ca-4448-bcf7-d07317ee0361 (whereby "tenant-a" is used as a prefix to indicate the name of a tenant, and "b1cccdea-22ca-4448-bcf7-d07317ee0361" is the endpoint name of the LwM2M Client).

{
  18 : 205,                    // result
  2 : 56,                      // token
  19 : 0,                      // content-type text/plain
  7 : "Open Mobile Alliance"   // payload
}

8.5. Response Results

This section lists available response results of each operation. Note that they are loosely based on the CoAP response codes. The result values are divided into each interface. These are the only valid response results defined in for the LwM2M Enabler.

Table: 8.5.-1 Response Results: Bootstrap Interface
Operations Available MQTT Response Results Reason Phrase
Bootstrap-Request 204 Bootstrap-Request is completed successfully
400 Unknown Endpoint Client Name
415 The specified format is not supported
Bootstrap-Read 205 "Read" operation is completed successfully
400 Undetermined error occurred
401 Access Right Permission Denied
404 URI of "Read" operation is not found
405 Target is not allowed for "Read" operation
406 None of the preferred Content-Formats can be returned
Bootstrap-Write 204 "Write" operation is completed successfully
400 The format of data to be written is different
415 The specified format is not supported
Bootstrap-Discover 205 "Discover" operation is completed successfully
400 Undetermined error occurred
404 URI of "Discover" operation is not found
Bootstrap-Delete 202 "Delete" operation is completed successfully
400 Bad or unknown URI provided
Bootstrap-Finish 204 Bootstrap-Finished is completed successfully
400 Bad URI provided
406 Inconsistent loaded configuration
Bootstrap-Pack-Request 205 The response includes the Bootstrap-Pack.
400 Undetermined error occurred
401 Access Right Permission Denied
404 URI of "Bootstrap-Pack-Request" operation is not found
405 The LwM2M Client is not allowed for "Bootstrap-Pack-Request" operation
406 The specified Content-Format is not supported
501 The LwM2M Bootstrap-Server does not support "Bootstrap-Pack-Request"
Table: 8.5.-2 Response Results: Client Registration Interface
Operations Available MQTT Response Results Reason Phrase
Register 201 "Register" operation is completed successfully
400 The mandatory parameter is not specified or unknown parameter is specified
Unknown Endpoint Client Name
Endpoint Client Name does not match with CN field of X.509 Certificates
403 The Endpoint Client Name registration in the LwM2M Server is not allowed.
409 The Client registration cannot be successfully used by the LwM2M Server to determine the list of Objects supported and Object Instances available on the LwM2M Client.
412 Supported LwM2M Versions of the Server and the Client are not compatible
Update 204 "Update" operation is completed successfully
400 The mandatory parameter is not specified or unknown parameter is specified
404 URI of "Update" operation is not found
De-register 202 "De-register" operation is completed successfully
400 Undetermined error occurred
404 URI of "De-register" operation is not found
Table: 8.5.-3 Response Results: Device Management and Service Enablement Interface
Operations Available MQTT Response Results Reason Phrase
Create 201 "Create" operation is completed successfully
400 Target (i.e., Object) already exists
Mandatory Resources are not specified
Content Format is not specified
401 Access Right Permission Denied
404 URI of "Create" operation is not found
405 Target is not allowed for "Create" operation
406 The specified Content-Format is not supported
415 The specified format is not supported
Read 205 "Read" operation is completed successfully
400 Undetermined error occurred
401 Access Right Permission Denied
404 URI of "Read" operation is not found
405 Target is not allowed for "Read" operation
406 None of the preferred Content-Formats can be returned
Read-Composite 205 "Read" operation is completed successfully
400 Undetermined error occurred
401 Access Right Permission Denied
404 URI of "Read" operation is not found
405 Target is not allowed for "Read" operation
406 None of the preferred Content-Formats can be returned
415 The specified format is not supported
Write 204 "Write" operation is completed successfully
400 The format of data to be written is different
401 Access Right Permission Denied
404 URI of "Write" operation is not found
405 Target is not allowed for "Write" operation
406 Not Acceptable
408 Request Entity Incomplete
413 Request entity too large
415 The specified format is not supported
Write-Composite 204 "Write" operation is completed successfully
400 The format of data to be written is different
401 Access Right Permission Denied
404 URI of "Write" operation is not found
405 Target is not allowed for "Write" operation
406 The specified Content-Format is not supported
Delete 202 "Delete" operation is completed successfully
400 Undetermined error occurred
401 Access Right Permission Denied
404 URI of "Delete" operation is not found
405 Target is not allowed for "Delete" operation
Execute 204 "Execute" operation is completed successfully
400 The LwM2M Client doesn't understand the argument in the payload
401 Access Right Permission Denied
404 URI of "Execute" operation is not found
405 Target is not allowed for "Execute" operation
Write-Attributes 204 "Write-Attributes" operation is completed successfully
400 The format of attribute to be written is different
401 Access Right Permission Denied
404 URI of "Write-Attributes" operation is not found
405 Target is not allowed for Write-Attributes operation
Discover 205 "Discover" operation is completed successfully
400 Undetermined error occurred
401 Access Right Permission Denied
404 URI of "Discover" operation is not found
405 Target is not allowed for Discover operation
Table: 8.5.-4 Response Results: Information Reporting Interface
Operations Available MQTT Response Results Reason Phrase
Observe
Cancel Observation
Cancel Observation-Composite
205 Operation is completed successfully
400 Undetermined error occurred
401 Access Right Permission Denied
404 URI of Operation is not found or not supported
405 Target is not allowed for the Operation
406 None of the preferred Content-Formats can be returned
Observe-Composite 205 Operation is completed successfully
400 Undetermined error occurred
401 Access Right Permission Denied
404 URI of Operation is not found or not supported
405 Target is not allowed for the Operation
406 None of the preferred Content-Formats can be returned
415 The specified format is not supported
Notify 205 "Notify" operation is completed successfully
Send 204 "Send" operation completed successfully
400 Undetermined error occurred
404 Reported Object was not registered to the LwM2M Server

If any operation cannot be completed in the client and the reason cannot be described by one the response results above, then a response result from the "Generic Errors" list below MUST be returned.

Table: 8.5.-5 Response Results: Generic Errors
MQTT Response Results Reason Phrase
500 An internal error occurred while processing the operation
501 Operation is not implemented
503 Service is currently unavailable

8.6. Security Protection

MQTT exchanges are protected at the transport layer between MQTT clients and MQTT servers using TLS, as defined by [MQTT]. Confidentiality protection may be used to ensure that message exchanges between a LwM2M Client and a LwM2M Server as well as between a LwM2M Client and a LwM2M Bootstrap-Server are not visible to the MQTT server itself. MQTT application data payloads may be encrypted also to prevent MQTT clients other than the intended recipients from reading messages.

The following CDDL structure (from [RFC8610]) defines the payload structure for CBOR protection.

   Outer_Wrapper = {
       msg-wrapper         => bstr .cbor
                              Msg_AuthEnc_Wrapper / nil,
       lwm2m-message      => (Bootstrap_Payload /
                              Registration_Payload /
                              DMSE_Payload /                                       
                              IR_Payload /
                              Generic_Response_Payload ),
   }

   msg-wrapper = 1
   lwm2m-message = 2

   Msg_Wrapper = [ * (COSE_Encrypt / COSE_Encrypt0 )]

8.7. CBOR Mapping

The parameters used in the messages MUST be mapped to CBOR types as specified in the table below.

Table: 8.7.-1 CBOR Mapping
Name CBOR Key
operation 1
token 2
ep 3
pct 4
uri 5
paths 6
payload 7
lifetime 8
version 9
b 10
sms 11
pmin 12
pmax 13
gt 14
st 15
epmin 16
epmax 17
result 18
ct 19
edge 20
hqmax 21
depth 22

8.8. MQTT Configuration

An LwM2M Client needs to have security credential and configuration information to interact with an MQTT server. The LwM2M Security Object already contains the Server URI as well as various security options for use with TLS. When LwM2M is used over MQTT then the LwM2M Server URI MUST use the scheme "mqtts://" or "mqtt://". The MQTT CONNECT message may carry a Client Identifier (ClientId). Note that [MQTT] places a restriction on the length of the string (1..23 UTF-8 encoded bytes) and the allowed character set that MQTT servers must support. They may support longer strings with other character sets though. Please refer to Section 3.1.3.1 of [MQTT] for more details. The use of the Client Identifier Resource of the MQTT Server Object is a safe way to know about what functionality to use with an MQTT server.

The MQTT protocol can optionally be configured to support a certain behavior, for example different quality of service classes. These settings are provided by the newly defined MQTT Server object (ID: 24).

If COSE [RFC8152] is used to protect MQTT messages between MQTT clients then security credentials need to be available. This information is available through the newly defined LwM2M COSE object (ID: 23). If the LwM2M Security Object Instance for the LwM2M Server has a valid link to an Instance of the LwM2M COSE object (ID: 23), the LwM2M Client MUST use COSE [RFC8152] to protect the MQTT messages exchanged with this LwM2M Server.

Appendix A. Change History (Informative)

A.1 Approved Version History

Table: A.1-1 Approved Version History
Reference Date Description
OMA-TS-LightweightM2M_Transport-V1_1-20180710-A 10 Jul 2018 Status changed to Approved by DMSE WG on 10 Jul 2018.
OMA-TS-LightweightM2M_Transport-V1_1_1-20190617-A 17 Jun 2019 Status changed to Approved by DMSE WG on 17 Jun 2019.
OMA-TS-LightweightM2M_Transport-V1_2-20201110-A 10 Nov 2020 Status changed to Approved by DMSE WG on 10 Nov 2020.
OMA-TS-LightweightM2M_Transport-V1_2_1-20221209-A 09 Dec 2022 Status changed to Approved by DMSE WG on 09 Dec 2022.

Appendix B. Static Conformance Requirements

This appendix is voided.

Appendix C. CoAP over LoRaWAN (Normative)

This appendix defines the retransmission logic of CoAP CON messages over a LoRaWAN network.

C.1 LoRaWAN overview

A LoRaWAN network is composed of Endpoints communicating with Application Servers through a Network Server. The role of the Network Server is to dispatch messages from the Endpoints to the relevant Application Server and to buffer messages from the Application Server to the Endpoint until the Endpoint is available for reception. A "Class A" Endpoint can receive messages only during RX windows opened after transmitting a message. "Class B" and "Class C" Endpoints are able to receive at specified periodicity. As LoRaWAN uses frequency in an unlicensed spectrum, Endpoints must respect a duty cycle which varies from region to region.

A LoRaWAN network features two kind of messages:

C.2 Configuration

MAX_RETRANSMIT is set to 4.

ACK_TIMEOUT is set to 300 seconds.

C.3 Retransmission logic

C.3.1 Using LoRaWAN confirmable messages

C.3.1.1 Requests originating from the Endpoint
  1. The Endpoint sends a CoAP CON message. If the matching CoAP ACK or RST is received during its RX windows, the exchange is successful.
  2. Otherwise, when the Endpoint is available, it opens a RX window by sending a LoRaWAN packet. If the Endpoint has no data scheduled for transmission, it sends a CoAP Empty message instead.

The Endpoint repeats step 2. MAX_RETRANSMIT times until the matching CoAP ACK or RST is received.

The LwM2M Server MUST reply to CoAP CON messages as soon as possible.

Example of CoAP request from Endpoint using LoRaWAN confirmable messages
Figure: C.3.1.1-1 Example of CoAP request from Endpoint using LoRaWAN confirmable messages
C.3.1.2 Requests originating from the Application Server
  1. The Application Server sends a CoAP CON message.
  2. The Network Server notifies the Application Server when the CoAP message was sent to the Endpoint or when the sending failed.
  3. If the sending was successful, the Application server waits for the CoAP ACK or RST message from the Endpoint.
Example of CoAP request from Application Server using LoRaWAN confirmable messages
Figure: C.3.1.2-1 Example of CoAP request from Application Server using LoRaWAN confirmable messages

C.3.2 Using LoRaWAN unconfirmable messages

C.3.2.1 Requests originating from the Endpoint
  1. The Endpoint sends a CoAP CON message. If the matching CoAP ACK or RST is received during its RX windows, the exchange is successful.
  2. Otherwise, when the Endpoint is available, it opens a RX window by sending a LoRaWAN packet. If the Endpoint has no data scheduled for transmission, it sends a CoAP Empty message instead. If the matching CoAP ACK or RST is received during its RX windows, the exchange is successful.
  3. Otherwise, when the Endpoint is available, it resends the initial CoAP CON message. If the matching CoAP ACK or RST is received during its RX windows, the exchange is successful.

The Endpoint repeats steps 2. and 3. for MAX_RETRANSMIT times until the matching CoAP ACK or RST is received.

The Application Server MUST reply to CoAP CON messages as soon as possible.

Example of CoAP request from Endpoint using LoRaWAN unconfirmable messages
Figure: C.3.2.1-1 Example of CoAP request from Endpoint using LoRaWAN unconfirmable messages
C.3.2.2 Requests originating from the Application Server
  1. The Application Server sends a CoAP CON message.
  2. When the Network Server responds to the Application Server that the CoAP message was sent to the Endpoint, the Application Server waits for the CoAP ACK or RST message from the Endpoint during ACK_TIMEOUT seconds.
  3. If the CoAP ACK or RST message was not received after ACK_TIMEOUT seconds, the Application Server resends the initial CoAP CON message.

The Application Server repeats steps 2. and 3. for MAX_RETRANSMIT times until the matching CoAP ACK or RST is received.

When receiving a CoAP CON message in an unconfirmable LoRaWAN packet, the Endpoint MUST reply in the ACK_TIMEOUT timeframe.

Example of CoAP request from Application Server using LoRaWAN unconfirmable messages
Figure: C.3.2.2-1 Example of CoAP request from Application Server using LoRaWAN unconfirmable messages

Appendix D. LwM2M over 3GPP CIoT - NB-IoT and LTE-M (Informative)

D.1 Introduction

Note: The 3GPP vocabulary and abbreviations used in the Annex are explained in [3GPP 21.905].

3GPP has specified Narrow-Band IoT (NB-IoT) and eMTC enhancements (aka. LTE Cat M1), as part of their Release 13. NB-IoT and CAT-M1 include solutions for support of infrequent data transmission via user plane and via the control plane. The user plane solution includes IP data and SMS support. The control plane solution includes IP data, non-IP data and SMS support. The main focus of this annex is on considerations and current limitations when running CoAP over the non-IP mode. Figure: D.1-1 3GPP CIoT architecture and the LwM2M protocol stack shows the 3GPP CIoT architecture, as described in [3GPP 23.720] and the LwM2M protocol stack. The C-SGN combines the functionality of the MME, S-GW, and P-GW.

3GPP CIoT architecture and the LwM2M protocol stack
Figure: D.1-1 3GPP CIoT architecture and the LwM2M protocol stack

As can be seen from the above figure 3GPP defines two transmission paths for NIDD (Non-IP Data Delivery):

  1. via PtP IP SGi tunnel (see [3GPP 23.401])
  2. via Service Capability Exposure Function (SCEF) (see [3GPP 23.682])

When carrying LwM2M over non-IP mode some limitations and considerations apply which are explained in the following sub-sections.

D.2 NIDD via PtP IP SGi tunnel

As specified in [3GPP 23.401], for mobile originated traffic the P-GW is responsible for creating the IP-packets before sending them via the point-to-point tunnel to the AS. For this, the destination IP address and UDP port for PtP tunnelling based on UDP/IP need to be pre-configured on the P-GW.

As specified in [3GPP 23.401], for mobile terminated traffic, in case PtP tunnelling based on UDP/IP is used, the AS sends the data using UDP/IP encapsulation with the IP address of the UE and the 3GPP defined port for “Non-IP” data. The IP-address of the UE is assigned by the P-GW, however, the UE is not aware of its IP address. The P-GW removes the UDP/IP headers and the data is forwarded via the mobile network to the UE.

[3GPP 29.061] provides further information on how to carry NIDD via the SGi interface.

From the above, it can be seen that one limitation for the non-IP transport is the need to pre-configure the destination address in the P-GW so that payloads are correctly relayed. Thus, it is not possible to for a LwM2M client to selectively address more than one LwM2M server via its IP address. As a consequence, the LwM2M client cannot apply separate IP addresses for communicating with

  1. different LwM2M Servers
  2. separate LwM2M Server and separate LwM2M Bootstrap Server.

Client/Server initiated bootstrap could still be applied; however, for this, the LwM2M Server and LwM2M Bootstrap Server would need to be combined and have the same server URI. From a security perspective, it is advisable to keep LwM2M Server and LwM2M Bootstrap Server separate. Using factory bootstrap or smartcard bootstrap mode would remove the need of a LwM2M Bootstrap Server.

Another alternative would be to have an intermediary node between SGi and LwM2M server. Such a node could then inspect the CoAP messages for routing information such as URI-host and forward the messages accordingly to different LwM2M servers.

Further mechanisms to remove the above addressing limitation are for further consideration. E.g. a link-layer protocol on top of NAS could re-establish addressing capabilities.

Given the required pre-configuration of the destination IP address in the mobile network an IoT platform provider needs to contact the mobile operator to get device-platform connectivity pre-configured (IP address, port number, dedicated APN if desired).

D.3 NIDD via SCEF

[3GPP 23.682] specifies NIDD via SCEF.

[3GPP 23.682] also gives some guidelines how an AS can retrieve small data via the SCEF and suggests the message types “NIDD configuration request/response”, “NIDD submit request/response”, and “NIDD request/response” (see [3GPP 23.682, clause 5.13). [3GPP 29.122] defines the T8 Reference point between the SCEF and the SCS/AS and specifies the RESTful APIs that allow the SCS/AS to access the services and capabilities provided by 3GPP network entities and securely exposed by the SCEF.

Obviously in non-IP mode, the device is not able to address LwM2M server(s) via their IP address. If NIDD via SCEF is selected all data goes via the SCEF. Thus, the UE can only talk to one LwM2M server since there is no additional information available at the IP layer that allows to selectively address more than one LwM2M server. This information would for regular LwM2M be available in the IP header.

The LwM2M server needs to identify the UE towards the SCEF via its MSISDN or External Identifier (see [3GPP 23.682]).

An alternative would be to have an intermediary node between SCEF and LwM2M server. Such a node could then inspect the CoAP messages for routing information such as URI-host and forward the messages accordingly to different LwM2M servers.

Another alternative is to use the Reliable Data Service (RDS) protocol (see [3GPP 24.250]) to communicate with multiple LwM2M Server(s) and the Bootstrap Server through the SCEF. When using RDS, the LwM2M Client will first use the RDS Source Port and RDS Destination Port configured in the Security object. If those ports are not configured in the Security Object, the LwM2M Client can use the Application Id configured in the LwM2M Security Object to query the SCEF to retrieve the appropriate RDS Source Port and RDS Destination Port values. If the port query mechanism is not supported, the LwM2M Client can use the Application Id to determine the RDS Source Port and RDS Destination Port when configured in the APN Connection Profile object. To select the correct RDS Source Port and RDS Destination Port from the Port lists in the APN Connection Profile Object, the LwM2M Client uses the instance in the Application Id list as a reference into the RDS Source Port and RDS Destination Port lists.

D.4 NAS Transport

[3GPP 24.301] defines the transport of user data via the control plane procedure. Two dedicated NAS messages are specified for transferring small data via the MME, see CONTROL PLANE SERVICE REQUEST message and ESM DATA TRANSPORT message in [3GPP 24.301]. For initiation of user data transport via the control plane the CONTROL PLAN SERVICE REQUEST message is used which may include ESM DATA TRANSPORT message in its IE “ESM message container”. After the initiation of user data transport via control plane the separate ESM DATA TRANSPORT messages may be used for further transport of user data.

CoAP messages are placed into the IE “User data container” of the ESM DATA TRANSPORT message.

In case DTLS is used the same applies to the DTLS messages.

The user data container has a variable length and the maximum payload size is 32768 bytes. According to [3GPP 23.060] the network shall use a maximum packet size of at least 128 octets (this applies to both uplink and downlink). The maximum uplink packet size that the MS shall use can be provided by the network as a part of the session management configuration via the Protocol Configurations Options (PCO) (see [3GPP 24.008] and [3GPP 27.060]). According to [3GPP 24.301] clause 6.6.4.2, the maximum size for Non-IP link MTU is 1358 octets to prevent fragmentation in the backbone network. The maximum uplink packet size as indicated in the PCO may be retrieved by the LwM2M Server via the Communications Characteristics Object (urn:oma:lwm2m:oma:17).

It has to be noted that there is no segmentation mechanism available for NAS transport. Thus, the LwM2M Client must not exceed the maximum uplink packet size as indicated via the PCO.

Furthermore, the LwM2M Server must not exceed the maximum downlink packet size supported for NAS transport, else it may result in multiple retransmissions in the lower layers effectively undermining the expected results or performance.

The PCO is also used to covey a rate control instruction to the UE i.e. the maximum number of uplink/downlink messages per a specific time unit (see [3GPP 23.401]). This can lead to a delay of LwM2M message delivery in case the rate is exceeded. The LwM2M server can get the awareness of any applied rate control via the Serving PLMN Rate Control Resource in the Cellular Network Connectivity Object (urn:oma:lwm2m:oma:10) or via the APN Rate Control Resource in the APN Connection Profile Object (urn:oma:lwm2m:oma:11).

Serving PLMN Rate Control can make the LwM2M message blocked from the LwM2M Server-side after the limit of the value crosses. In these scenarios, LwM2M Client SHOULD stop expecting responses and wait to cross the period of silence enforced by the 3GPP network control on message flow from LwM2M Server to LwM2M Client.

According to [3GPP 24.301] the CONTROL PLANE SERVICE REQUEST message and the ESM DATA TRANSPORT message include an IE “Release assistance indication” to inform the network whether or not a downlink data transmission (e.g. acknowledgement or response) subsequent to the uplink data transmission is expected. For mobile originating LwM2M traffic this indicator SHOULD be set accordingly.

Note: Data transmission speed for uplink and downlink via NAS is expected to be around 300 bit/s, or more.

D.5 Large data transport with NB-IoT/CAT-M1

Even NB-IoT/CAT-M1 is mainly designed for small data delivery it does not preclude delivery of very infrequent large data (e.g. software update/software patches).

[3GPP 23.401] describes a control/user plane switch which could be used e.g. to switch the device communication from the control plane to user plane in case a software update is expected. However, there will be devices which do only support communication via the control plane, in which case these large data transport may not be feasible directly.

IETF has defined segmentation handling at the CoAP layer for large file transfer e.g. firmware updates. Blockwise transfers in [CoAP_Blockwise] and [LwM2M-CORE] captures the details in LwM2M Object Firmware Update (ID:5)

CoAP block transfer MAY be used with for carrying CoAP over NB-IoT/CAT-M1. This option can be used with IP-mode and non-IP-mode.

An alternative approach is the use of CoAP over TCP. Obviously, this option works only with the IP-mode.

D.6 Message buffering

NB-IoT/CAT-M1 devices are expected to be in a sleeping and power-saving mode much or most of the time to enable a battery lifetime of several years. In case a device is not reachable, like device in sleeping mode or for other reasons like applied mobile network controls, downlink messages need to be buffered. 3GPP has defined such buffering operation as “extended buffering” at the SCEF (see [3GPP 23.682]) and the S-GW (see [3GPP 23.401]).

It has to be noted that there is a potential issue with DTLS timeout and CoAP CON retransmission timer if the messages are buffered in the mobile network, this could lead to the buffer being filled up with retransmissions. Furthermore, in case LwM2M queue mode and network buffering are both applied then this could lead to the message being stored in each buffer resulting in duplicated delivery of the message after the device wakes up. One way for avoiding this would be to use only LWM2M queue mode for buffering messages while the device is not reachable due to sleeping mode or other reasons. In the case that LwM2M queue mode is planned to be used, “extended buffering” in the network should be deactivated. According to [3GPP 23.401] “extended buffering” can be de-activated per APN, or per subscriber.

Alternatively, the LwM2M server could be configured to only send messages when the device is awake. Obvious precondition for this would be the LwM2M server being aware of the device state.

Note: The device state info is available at the MME which informs the SCEF when the device has woken up from power-saving mode (see [3GPP 23.682]). A trigger mechanism from the SCEF to AS could be used, refer ENCap-M2M API from OMA ARC for such API availability.

It has to be noted that certain NB-IoT/CAT-M1 implementations need to support also time-critical use cases e.g. fire alarms.

D.7 NB-IoT/CAT-M1 transport configuration options

Various configuration options for NB-IoT/CAT-M1 transport are provided via the ConnMgmt enabler ([LwM2M-ConnMgmt]).

D.8 Timer considerations

D.8.1 Introduction

3GPP Rel-13 NB-IoT/CAT-M1 is aimed at constrained low power IoT devices which require infrequent small data transfer and have a battery life of ~10 years. To minimise power consumption these devices use certain features such as Power Save Mode and extended Idle Mode DRX (eDRX) which govern how often the device wakes up, stays up and reachable. Effective use of these parameters in conjunction with LwM2M Registration Life Time, min/max notify periods, and – if LwM2M queue mode operation is used - ACK_TIMEOUT will help the device to have synchronised set of activities that could optimise its power consumption by avoiding unnecessary wake-up and transmissions.

D.8.2 3GPP Parameters

Table: D.8.2-1 3GPP Parameters
Parameter Range Purpose/how it’s used by the device
PSM Timer, Extended T3412 10min-992 days1 Max interval between periodic TAU if there is no other transmission from the device. During this time the device is considered as unreachable and can thereby shut down/deactivate.
Active Timer, T3324 2sec-31 min The time the UE has to stay up and remain reachable after transitioning to idle state in case there is pending data from the NW to send out. At the end of T3324 UE can shut down and deactivate.
Extended DRX2 5.12sec- 174 min Extended Idle mode DRX
Higher Priority PLMN Search Timer Interval between periodic searches for higher priority PLMNs when camped on a visited PLMN, i.e. roaming scenario; based on SIM configuration, EFHPPLMN ([3GPP 31.102], section 4.2.6)
Rate Control Determines the number of allowed uplink PDU transmissions per deci-hour per APN as well as per serving PLMN

Note 1: Table 10.5.163a in [3GPP 24.008] specifies range N to 31*N in increments of one where the units of N can be 2 seconds, 30 seconds, 1 min, 10 min, 1 hour, 10 hour or 320 hours. In the context of NB-IoT units of 1 or 10 hours will probably be used in most scenarios

Note 2: Extended DRX and PSM can coexist and be configured together.

PSM Timer (Extended T3412), Active Timer (T3324) and Extended DRX can be requested by the device from the network by inclusion of requested values in Attach or TAU requests. On accepting the device request, the network will provide the device with values for these timers which the device should use.

The LwM2M server can configure the values on Resources which the device should request from the network. By observing this resource, the LwM2M also receives the finally applied timer in case the network has not accepted the device’s request.

D.8.3 LwM2M Parameters

Table: D.8.3-1 LwM2M Parameters
Parameter Range Purpose/how it’s used by the device
Registration Life Time Max. interval between client performing registration updates
Pmin Min. time in second between sending notifications for a resource if any of the notify conditions are met
Pmax Max. time in seconds between sending successive notifications for a resource if none of other notify conditions are satisfied
ACK_TIMEOUT CoAP timer used with LwM2M queue mode operation. The LwM2M Client MUST wait at least ACK_TIMEOUT seconds from the last CoAP message it sent to the LwM2M Server before intentionally going offline

D.8.4 Interactions between parameters

From the two tables above it is clear that how often the device wakes up, transmits data and stays awake, is controlled by a combination of parameters defined by 3GPP and OMA that need to be configured in unison to maximise device power efficiency. For example, in the absence of any service data transmission, the device still has to wake up on a regular basis to: a) update its registration with the LwM2M server to make sure its registration stays valid and b) carry out periodic TAU to meet 3GPP requirements. If parameters are configured such that Registration lifetime <= T3412, then the need to perform TAU will automatically be eliminated because when the registration update is performed by the device, the periodic TAU timer will automatically be reset. However, if T3412 < Registration lifetime, then the device either wakes up twice to carry out these procedures separately, or unilaterally decides to update its registration on expiry of T3412 which will result in the LwM2M server receiving updates more frequently than it had asked for.

Both Active Timer (T3324) and CoAP MAX_TRANSMIT_WAIT are aimed to achieve the same result, namely keeping the device awake long enough to allow queued messages to be sent to the device. Depending on where the queuing occurs, only one of these timers is actually required and can be meaningfully used. It’s also worth noting that these timers do not start at the same time, MAX_TRANSMIT_WAIT is started after the last transmission, while T3324 starts later when the device has released the connection and returned to an idle state.

From 3GPP perspective, eDRX determines how often the device needs to wake up and monitor its paging channel. From LwM2M perspective, a device that is monitoring a sensor at the minimum needs to wake up every Pmax to sample sensor data and transmit its value. It also does not need to wake up any more frequently than Pmin to read the sensor data, assuming no filtering and averaging. Pmin, Pmax and eDRX need to be configured such that a device can schedule its activities to minimise the number of times it needs to wake up and transmit data; this is also contingent on any configured Rate Control value being in line with Pmin and Pmax.

D.8.5 Timer implementation options

Effective use of 3GPP timers in conjunction with LwM2M timers will help the device to have a synchronised set of activities that could optimise its power consumption by avoiding unnecessary wake ups and transmissions.

The following recommendations apply:

A customer solution designer, will define the values of Pmin and Pmax, and the Infrastructure solution provider will define the values of Extended T3412, LwM2M Registration lifetime and eDRX.

For efficient interaction between mechanisms, the following relationships can be maintained between values of LwM2M and 3GPP parameters: