Independant Submission P. Duffy (ed) Internet-Draft Cisco Systems, Inc. Intended status: Informational 24 October 2022 Expires: 27 April 2023 Cisco's CoAP Simple Management Protocol draft-duffy-csmp-03 Abstract CoAP Simple Management Protocol (CSMP) is purpose-built to provide lifecycle management for resource constrained IoT devices deployed within large-scale, bandwidth constrained IoT networks. CSMP offers an efficient transport and message encoding supporting classic NMS functions such as device on-boarding, device configuration, device status reporting, securing the network, etc. This document describes the design and operation of CSMP. This document does not represent an IETF consensus. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 27 April 2023. Copyright Notice Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components Duffy (ed) Expires 27 April 2023 [Page 1] Internet-Draft CoAP Simple Management Protocol October 2022 extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 3. Protocol Specification . . . . . . . . . . . . . . . . . . . 4 3.1. CoAP Usage Profile . . . . . . . . . . . . . . . . . . . 4 3.2. Interface Specification . . . . . . . . . . . . . . . . . 5 3.2.1. CSMP Device Interface . . . . . . . . . . . . . . . . 5 3.2.2. CSMP NMS Interface . . . . . . . . . . . . . . . . . 9 3.2.3. CSMP Common Components. . . . . . . . . . . . . . . . 11 3.3. Resources . . . . . . . . . . . . . . . . . . . . . . . . 18 3.3.1. Base URL . . . . . . . . . . . . . . . . . . . . . . 18 3.3.2. Resource Encoding . . . . . . . . . . . . . . . . . . 19 3.3.3. Large Requests . . . . . . . . . . . . . . . . . . . 53 3.4. CSMP Security Model . . . . . . . . . . . . . . . . . . . 53 3.4.1. Signature Exemption . . . . . . . . . . . . . . . . . 54 3.5. Device Groups . . . . . . . . . . . . . . . . . . . . . . 54 3.5.1. Reserved Group Types . . . . . . . . . . . . . . . . 55 3.6. Device TLV Processing Order . . . . . . . . . . . . . . . 56 4. Functional Description . . . . . . . . . . . . . . . . . . . 56 4.1. Device Lifecyle States . . . . . . . . . . . . . . . . . 56 4.2. NMS Discovery . . . . . . . . . . . . . . . . . . . . . . 57 4.3. Device Registration and Configuration . . . . . . . . . . 57 4.3.1. Device Registration Request . . . . . . . . . . . . . 60 4.3.2. Registration POST Payload . . . . . . . . . . . . . . 61 4.3.3. NMS Registration Response . . . . . . . . . . . . . . 61 4.3.4. Registration Complete . . . . . . . . . . . . . . . . 63 4.4. Device Metrics Reporting . . . . . . . . . . . . . . . . 63 4.5. Device Firmware Update . . . . . . . . . . . . . . . . . 65 4.5.1. Firmware Image Format . . . . . . . . . . . . . . . . 66 4.5.2. Firmware Download . . . . . . . . . . . . . . . . . . 68 4.5.3. Image Activation . . . . . . . . . . . . . . . . . . 70 4.5.4. Set Backup Image . . . . . . . . . . . . . . . . . . 71 4.6. Device Commands . . . . . . . . . . . . . . . . . . . . . 73 5. Security Considerations . . . . . . . . . . . . . . . . . . . 74 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 74 8. Appendix A Registration Retry Example . . . . . . . . . . . . 75 9. Appendix B Change Log . . . . . . . . . . . . . . . . . . . . 76 9.1. draft 00 to 01 . . . . . . . . . . . . . . . . . . . . . 76 9.2. draft 01 to 02 . . . . . . . . . . . . . . . . . . . . . 76 9.3. draft 02 to 03 . . . . . . . . . . . . . . . . . . . . . 76 10. Normative References . . . . . . . . . . . . . . . . . . . . 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 77 Duffy (ed) Expires 27 April 2023 [Page 2] Internet-Draft CoAP Simple Management Protocol October 2022 1. Introduction Low Power Wide Area Network (LPWAN) technologies provide long range, low power connectivity for Internet of Things (IoT) applications. LPWANs typically operate over distances of several kilometers with link bandwidths as low as 10s of Kbps. LPWAN devices are often compute, storage and power constrained (often optimized to operate for years on a single battery charge). This specification describes the design and operation of CSMP which today is in-field managing approximately 25 million LPWAN devices deployed by a number of vendors. These devices are supporting a variety of critical infrastructure use cases for electric, water, and gas utilities along with a variety of smart cities use cases (municipal lighting, etc.). There is industry demand that CSMP managed devices be more quickly and widely available for an ever expanding set of use cases. This specification in intended to promote development of interoperable CSMP device and management system implementations. It is anticipated that this specification will be referenced by several industry fora. CSMP features include: 1. Onboarding. Device startup registration and capabilities announcement with an NMS. 2. Configuration management. Device acquisition of configuration from the NMS. Subsequent NMS configuration reads and updates to the device. 3. Metrics reporting. Periodic device metrics reporting to the NMS. NMS on-demand metrics requests to a device. 4. NMS commanded device operations. NMS command issuance to a single device or group of devices. 5. Secure device firmware update. 2. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. Duffy (ed) Expires 27 April 2023 [Page 3] Internet-Draft CoAP Simple Management Protocol October 2022 3. Protocol Specification CSMP is a usage profile of the Constrained Application Protocol [RFC7252], which is designed for implementing RESTful messaging for resource constrained devices. It is fair to view CoAP as a binary encoded functional subset of HTTP operating over UDP which also supports multicast messaging. Resources (addressable objects) transported within CSMP message payloads are implemented using the Protocol Buffers compact binary encoding [PB]. It is assumed the reader is familiar with: 1. The basic concepts of RESTful architecture. 2. The operation, message formats, and terminology of CoAP [RFC7252]. 3. Protocol Buffers [PB], which is used to describe and encode CSMP message payloads. 4. OpenAPI [OPENAPI] is the interface definition language used to define CSMP Device and NMS interfaces. 3.1. CoAP Usage Profile The NMS and devices communicate directly using CoAP. Acting as a CoAP client, a device issues RESTful requests to read or modify specific resources (objects) exposed by the NMS server. Likewise, the device serves requests from the NMS to manipulate resources exposed by the device. CSMP specializes the usage of CoAP in the following ways: 1. CSMP does not use the Token capabilities described in [RFC7252]. Request/response messaging MUST be implemented using the "synchronous" form of a CON request with response piggybacked in the subsequent ACK. A client MUST elide the Token field from the request message. The server SHOULD ignore the Token if received from a client request. 2. Due to high latencies typical of LPWAN technologies, a client MUST NOT use the CoAP retransmission model when sending a CON message to a server. After sending a CON message, the client MUST accept a response from the server at any time up until the device sends its next CON message (containing a new CoAP Message ID). Duffy (ed) Expires 27 April 2023 [Page 4] Internet-Draft CoAP Simple Management Protocol October 2022 3.2. Interface Specification CSMP defines a CSMP Device interface and a CSMP NMS interface. Each of these interfaces defines a set of resources (objects), the addresses at which these resources exist (URLs), and the methods (GET, PUT, POST, DELETE) which may be used to manipulate the resources to implement device management operations. The CSMP Device and CSMP NMS interfaces are expressed using the OpenAPI interface definition language. OpenAPI's heritage is the expression of interfaces typically constructed with HTTP and JSON. This document defines a few conventions required to express a CoAP interface in OpenAPI: 1. The generic RESTful verb designators GET, PUT, POST, and DELETE are used along with the text presentation of a resource's URL. This is done for developer readability. An actual implementation must properly encode the CoAP message Code field along with the Uri-Host, Uri-Port, Uri-Path, and Uri-Query options as described in [RFC7252]. 2. CoAP Response codes of the form X.YZ are expressed in the OpenAPI as XYZ (the actual response code is scaled by 100 in the OpenAPI rendering). 3. Placeholder objects are defined in OpenAPI to represent the Protocol Buffer binary objects which will be transported in CoAP messaging payloads. The actual binary objects are defined in a separate Protocol Buffer file Section 3.3.2.2. 4. CoAP supports the NON messaging pattern. OpenAPI syntax always requires a response be defined. The CSMP interface definitions will note when a response is for a COAP NON request and not an actual CoAP response (no response is sent). 3.2.1. CSMP Device Interface A CSMP device MUST implement the interface described below. The interface definition is also available at [CSMPDEV] which is directly importable into development tooling. Various forms of the GET method are used for retrieving registration information, device information, and monitoring information from the devices. Various forms of the POST method are used to deliver configuration and commands to devices. Usage of this interface is detailed in the sections which follow. Duffy (ed) Expires 27 April 2023 [Page 5] Internet-Draft CoAP Simple Management Protocol October 2022 openapi: 3.0.0 info: description: | CSMP Device Interface. RFC 2119 language is used to indicate normative statements. version: 1.0.1 title: CSMP Device Interface servers: # # Placeholder for the actual device-url # - url: 'https://virtserver.swaggerhub.com/woobagooba/CsmpDevice/1.0.1' paths: /c: get: description: | Retrieve TlvIndex TLV or specific list of TLVs from a device. parameters: - $ref: '#/components/parameters/qOption' - $ref: '#/components/parameters/aOption' - $ref: '#/components/parameters/rOption' responses: '205': description: | Successful return of requested TLVs or TlvIndex. Device MUST return the requested specific TLVs when the "q" param is included (full tables are allowed). Device MUST return only TlvIndex when the "q" param is omitted. content: application/octet-stream: schema: oneOf: - $ref: 'https://api.swaggerhub.com/domains/woobagooba/CSMPComponents/1.0#/components/schemas/TLVsGETFromDevice' - $ref: 'https://api.swaggerhub.com/domains/woobagooba/CSMPComponents/1.0#/components/schemas/TlvIndex' '400': description: Bad Request. '401': description: Unauthorized. '402': description: Bad option. '403': description: TLV not found, response won't fit in MTU. '404': description: Not found. '405': description: Method not allowed. post: description: Process TLV updates from the NMS. The q option MUST NOT be used. A device MUST process the following TLVs (if present and in order) ... 1. Signature – verify the message signature. Duffy (ed) Expires 27 April 2023 [Page 6] Internet-Draft CoAP Simple Management Protocol October 2022 2. SignatureValidity – verify if the signature is still valid. 3. GroupMatch – check if the device belongs to the group for which the packet is intended. 4. The TLVs to be updated. parameters: - $ref: '#/components/parameters/aOption' - $ref: '#/components/parameters/rOption' requestBody: description: One or more TLVs to be POSTed to the device. required: true content: application/octet-stream: schema: $ref: 'https://api.swaggerhub.com/domains/woobagooba/CSMPComponents/1.0#/components/schemas/TLVsPOSTableToDevice' responses: '201': description: TLVs have been updated. '400': description: Bad Request. '401': description: Unauthorized. '402': description: Bad option. '403': description: Forbidden. '404': description: Not found. '405': description: Method not allowed. /c/{tlvIdPath}: get: description: | Retrieve single TLV from a device. parameters: - $ref: '#/components/parameters/tlvIdPath' - $ref: '#/components/parameters/aOption' - $ref: '#/components/parameters/rOption' responses: '205': description: Return the requested TLV. Full table retreival is allowed. content: application/octet-stream: schema: $ref: 'https://api.swaggerhub.com/domains/woobagooba/CSMPComponents/1.0#/components/schemas/TLVsGETFromDevice' '400': description: Bad Request. Duffy (ed) Expires 27 April 2023 [Page 7] Internet-Draft CoAP Simple Management Protocol October 2022 '401': description: Unauthorized. '402': description: Bad option. '403': description: TLV not found, response won't fit in MTU. '404': description: Not found. '405': description: Method not allowed. # # Note that POST is not permitted on this URL. # # # Query parameters used for device requests. # components: parameters: qOption: description: | Q option for request to device for one or more specific TLVs. When present in a request, the response payload MUST contain the requested TLVs. If a TLV does not exist on the device, it MUST NOT be returned in the response and no error should be indicated. in: query name: q required: false schema: type: string description: Format is +++... aOption: description: | A option. When omitted, the request MUST be CON. When present, request MUST be NON and the device MUST wait random interval from time of receipt up to "a" seconds before responding with a NON POST to /c. This form is often used with multicast requests to devices, but may also be used for unicast requests to devices. in: query name: a required: false schema: type: integer description: The device will wait random interval from receipt up to "a" seconds before sending rOption: description: | R option MAY be used with the A option to indicate device MUST respond with a NON POST to specified URL (overriding /c). in: query name: r required: false schema: type: string tlvIdPath: description: Path param specifying TLV ID. in: path Duffy (ed) Expires 27 April 2023 [Page 8] Internet-Draft CoAP Simple Management Protocol October 2022 name: tlvIdPath required: true schema: type: integer 3.2.2. CSMP NMS Interface A CSMP NMS MUST implement the interface described below. The interface definition is also available at [CSMPNMS] which is directly importable into development tooling. Various forms of the POST method are used for device registration, device metrics reporting, and asynchronous GET responses (resulting from a request including the "a" option and default response URL). Usage of this interface is detailed in the sections which follow. Duffy (ed) Expires 27 April 2023 [Page 9] Internet-Draft CoAP Simple Management Protocol October 2022 openapi: 3.0.0 info: description: CSMP NMS Interface. RFC 2119 language is used to indicate normative statements. version: 1.0.1 title: CSMP NMS Interface servers: # # Placeholder for the actual nms-url. # - url: 'https://virtserver.swaggerhub.com/woobagooba/CsmpNms/1.0.0' paths: /r: post: description: Device registration POST to the NMS. RequestBody MAY include any of the RegistrationRequest TLVs (see CsmpComponents). RequestBody MUST include DeviceID and CurrentTime TLVs. POSTs to this address MUST be CON (acknowledged). requestBody: required: true content: application/octet-stream: schema: $ref: 'https://api.swaggerhub.com/domains/woobagooba/CSMPComponents/1.0#/components/schemas/RegistrationRequestTLVs' responses: '203': description: Successful registration response to device. The response MAY include any of the RegistrationResponse TLVs (see CsmpComponents). content: application/octet-stream: schema: $ref: 'https://api.swaggerhub.com/domains/woobagooba/CSMPComponents/1.0#/components/schemas/RegistrationResponseTLVs' '403': description: Duplicate DeviceID was received or DeviceID was not recognized or authorized by the NMS. There is no payload in this response. '404': description: Multiple Session IDs were found for the device. There is no payload for this response. /c: post: description: Devices POST periodic metrics, command responses, events, and asychronous GET responses to the NMS. A POST to this address MUST be NON (non acknowledged ... to avoid excessive acknowledgement, 4.03 or 4.04 conditions are handled silently by the NMS). RequestBody MAY include any of TLVsPOSTAbleToNms TLVs (see CsmpComponents). The RequestBody MUST include the CurrentTime and SessionID TLVs (see CsmpComponents). requestBody: required: true content: application/octet-stream: schema: $ref: 'https://api.swaggerhub.com/domains/woobagooba/CSMPComponents/1.0#/components/schemas/TLVsPostAbleToNMS' responses: '100': description: There is no response to this (NON) request (100 is used to indicate no response). Duffy (ed) Expires 27 April 2023 [Page 10] Internet-Draft CoAP Simple Management Protocol October 2022 3.2.3. CSMP Common Components. This section contains definitions common to both the CSMP Device and NMS interfaces. The definitions are also available at [CSMPCOMP] which is directly importable into development tooling. # OpenAPI version identifier - required for OpenAPI 3.0 domains openapi: 3.0.0 info: title: CSMP Components description: Common components for CSMP APIs version: '1.0' components: schemas: TLVsGetAbleFromDevice: description: | TLVs which are GET-able from a /c. Metrics and settings. anyOf: - $ref: '#/components/schemas/TlvIndex' - $ref: '#/components/schemas/HardwareDesc' - $ref: '#/components/schemas/InterfaceDesc' - $ref: '#/components/schemas/ReportSubscribe' - $ref: '#/components/schemas/IPAddress' - $ref: '#/components/schemas/IPRoute' - $ref: '#/components/schemas/CurrentTime' - $ref: '#/components/schemas/RPLSettings' - $ref: '#/components/schemas/Uptime' - $ref: '#/components/schemas/InterfaceMetrics' - $ref: '#/components/schemas/IPRouteRPLMetrics' - $ref: '#/components/schemas/Ieee8021xStatus' - $ref: '#/components/schemas/Ieee80211iStatus' - $ref: '#/components/schemas/WPANStatus' - $ref: '#/components/schemas/DHCP6ClientStatus' - $ref: '#/components/schemas/NMSSettings' - $ref: '#/components/schemas/NMSStatus' - $ref: '#/components/schemas/Ieee8021xSettings' - $ref: '#/components/schemas/Ieee802154BeaconStats' - $ref: '#/components/schemas/RPLInstance' - $ref: '#/components/schemas/FirmwareImageInfo' - $ref: '#/components/schemas/SysResetStats' - $ref: '#/components/schemas/MplStats' - $ref: '#/components/schemas/RPLStats' - $ref: '#/components/schemas/DHCP6Stats' - $ref: '#/components/schemas/EventReport' - $ref: '#/components/schemas/EventIndex' Duffy (ed) Expires 27 April 2023 [Page 11] Internet-Draft CoAP Simple Management Protocol October 2022 - $ref: '#/components/schemas/EventSubscribe' - $ref: '#/components/schemas/EventStats' - $ref: '#/components/schemas/NetworkRole' - $ref: '#/components/schemas/NetStat' RegistrationRequestTLVs: description: | TLVs which may be contained in a registration POST request to the NMS. anyOf: - $ref: '#/components/schemas/DeviceID' - $ref: '#/components/schemas/CurrentTime' - $ref: '#/components/schemas/HardwareDesc' - $ref: '#/components/schemas/InterfaceDesc' - $ref: '#/components/schemas/IPAddress' - $ref: '#/components/schemas/NMSStatus' - $ref: '#/components/schemas/WPANStatus' - $ref: '#/components/schemas/RPLSettings' - $ref: '#/components/schemas/SessionID' - $ref: '#/components/schemas/GroupInfo' - $ref: '#/components/schemas/ReportSubscribe' RegistrationResponseTLVs: description: | TLVs which may be contained in a registration response from the NMS. anyOf: - $ref: '#/components/schemas/SessionID' - $ref: '#/components/schemas/GroupAssign' - $ref: '#/components/schemas/ReportSubscribe' - $ref: '#/components/schemas/DescriptionRequest' - $ref: '#/components/schemas/NMSRedirectRequest' TLVsPostAbleToNMS: description: | TLVs which may be POSTed to /c There are several situations under which this can occur ... 1. Periodic metrics reports from a device. 2. Command responses from a device. 3. Asynchronous events reported by a device. 4. Asynchronous GET responses from a device. anyOf: - $ref: '#/components/schemas/TlvIndex' - $ref: '#/components/schemas/DeviceID' - $ref: '#/components/schemas/NMSRedirectRequest' - $ref: '#/components/schemas/SessionID' - $ref: '#/components/schemas/HardwareDesc' - $ref: '#/components/schemas/InterfaceDesc' Duffy (ed) Expires 27 April 2023 [Page 12] Internet-Draft CoAP Simple Management Protocol October 2022 - $ref: '#/components/schemas/ReportSubscribe' - $ref: '#/components/schemas/IPAddress' - $ref: '#/components/schemas/IPRoute' - $ref: '#/components/schemas/CurrentTime' - $ref: '#/components/schemas/RPLSettings' - $ref: '#/components/schemas/Uptime' - $ref: '#/components/schemas/InterfaceMetrics' - $ref: '#/components/schemas/IPRouteRPLMetrics' - $ref: '#/components/schemas/PingResponse' - $ref: '#/components/schemas/Ieee8021xStatus' - $ref: '#/components/schemas/Ieee80211iStatus' - $ref: '#/components/schemas/WPANStatus' - $ref: '#/components/schemas/DHCP6ClientStatus' - $ref: '#/components/schemas/NMSSettings' - $ref: '#/components/schemas/NMSStatus' - $ref: '#/components/schemas/Ieee8021xSettings' - $ref: '#/components/schemas/Ieee802154BeaconStats' - $ref: '#/components/schemas/RPLInstance' - $ref: '#/components/schemas/GroupInfo' - $ref: '#/components/schemas/LowpanMacStats' - $ref: '#/components/schemas/LowpanPhySettings' - $ref: '#/components/schemas/TransferResponse' - $ref: '#/components/schemas/LoadResponse' - $ref: '#/components/schemas/CancelLoadResponse' - $ref: '#/components/schemas/SetBackupResponse' - $ref: '#/components/schemas/FirmwareImageInfo' - $ref: '#/components/schemas/SysResetStats' - $ref: '#/components/schemas/MplStats' - $ref: '#/components/schemas/RPLStats' - $ref: '#/components/schemas/DHCP6Stats' - $ref: '#/components/schemas/EventReport' - $ref: '#/components/schemas/EventIndex' - $ref: '#/components/schemas/EventStats' TLVsPostAbleToDevice: description: | TLVs which may be POSTed to /c. Commands and settings. anyOf: - $ref: '#/components/schemas/NMSRedirectRequest' - $ref: '#/components/schemas/RPLSettings' - $ref: '#/components/schemas/PingRequest' - $ref: '#/components/schemas/RebootRequest' - $ref: '#/components/schemas/NMSSettings' - $ref: '#/components/schemas/Ieee8021xSettings' - $ref: '#/components/schemas/GroupMatch' - $ref: '#/components/schemas/LowpanPhySettings' - $ref: '#/components/schemas/TransferRequest' Duffy (ed) Expires 27 April 2023 [Page 13] Internet-Draft CoAP Simple Management Protocol October 2022 - $ref: '#/components/schemas/ImageBlock' - $ref: '#/components/schemas/LoadRequest' - $ref: '#/components/schemas/CancelLoadRequest' - $ref: '#/components/schemas/SetBackupRequest' - $ref: '#/components/schemas/SignatureValidity' - $ref: '#/components/schemas/Signature' - $ref: '#/components/schemas/SignatureSettings' - $ref: '#/components/schemas/NetworkRole' - $ref: '#/components/schemas/MplReset' - $ref: '#/components/schemas/EventSubscribe' TableTLVs: description: | Table TLVs. anyOf: - $ref: '#/components/schemas/HardwareDesc' - $ref: '#/components/schemas/InterfaceDesc' - $ref: '#/components/schemas/IPAddress' - $ref: '#/components/schemas/IPRoute' - $ref: '#/components/schemas/InterfaceMetrics' - $ref: '#/components/schemas/IPRouteRPLMetrics' - $ref: '#/components/schemas/Ieee802154BeaconStats' - $ref: '#/components/schemas/RPLInstance' - $ref: '#/components/schemas/FirmwareImageInfo' - $ref: '#/components/schemas/NetStat' - $ref: '#/components/schemas/CertBundle' AllTLVs: description: | All CSMP defined TLVs. This is used as an editorial starting point for the other TLV collections defined within. anyOf: - $ref: '#/components/schemas/TlvIndex' - $ref: '#/components/schemas/DeviceID' - $ref: '#/components/schemas/NMSRedirectRequest' - $ref: '#/components/schemas/SessionID' - $ref: '#/components/schemas/DescriptionRequest' - $ref: '#/components/schemas/HardwareDesc' - $ref: '#/components/schemas/InterfaceDesc' - $ref: '#/components/schemas/ReportSubscribe' - $ref: '#/components/schemas/IPAddress' - $ref: '#/components/schemas/IPRoute' - $ref: '#/components/schemas/CurrentTime' - $ref: '#/components/schemas/RPLSettings' - $ref: '#/components/schemas/Uptime' - $ref: '#/components/schemas/InterfaceMetrics' - $ref: '#/components/schemas/IPRouteRPLMetrics' Duffy (ed) Expires 27 April 2023 [Page 14] Internet-Draft CoAP Simple Management Protocol October 2022 - $ref: '#/components/schemas/PingRequest' - $ref: '#/components/schemas/PingResponse' - $ref: '#/components/schemas/RebootRequest' - $ref: '#/components/schemas/Ieee8021xStatus' - $ref: '#/components/schemas/Ieee80211iStatus' - $ref: '#/components/schemas/WPANStatus' - $ref: '#/components/schemas/DHCP6ClientStatus' - $ref: '#/components/schemas/NMSSettings' - $ref: '#/components/schemas/NMSStatus' - $ref: '#/components/schemas/Ieee8021xSettings' - $ref: '#/components/schemas/Ieee802154BeaconStats' - $ref: '#/components/schemas/RPLInstance' - $ref: '#/components/schemas/GroupAssign' - $ref: '#/components/schemas/GroupEvict' - $ref: '#/components/schemas/GroupMatch' - $ref: '#/components/schemas/GroupInfo' - $ref: '#/components/schemas/LowpanMacStats' - $ref: '#/components/schemas/LowpanPhySettings' - $ref: '#/components/schemas/TransferRequest' - $ref: '#/components/schemas/ImageBlock' - $ref: '#/components/schemas/LoadRequest' - $ref: '#/components/schemas/CancelLoadRequest' - $ref: '#/components/schemas/SetBackupRequest' - $ref: '#/components/schemas/TransferResponse' - $ref: '#/components/schemas/LoadResponse' - $ref: '#/components/schemas/CancelLoadResponse' - $ref: '#/components/schemas/SetBackupResponse' - $ref: '#/components/schemas/FirmwareImageInfo' - $ref: '#/components/schemas/SignatureValidity' - $ref: '#/components/schemas/Signature' - $ref: '#/components/schemas/SignatureSettings' - $ref: '#/components/schemas/SysResetStats' - $ref: '#/components/schemas/NetStat' - $ref: '#/components/schemas/NetworkRole' - $ref: '#/components/schemas/CertBundle' - $ref: '#/components/schemas/MplStats' - $ref: '#/components/schemas/MplReset' - $ref: '#/components/schemas/RPLStats' - $ref: '#/components/schemas/DHCP6Stats' - $ref: '#/components/schemas/EventReport' - $ref: '#/components/schemas/EventIndex' - $ref: '#/components/schemas/EventSubscribe' - $ref: '#/components/schemas/EventStats' # # Object (TLV) placeholders to allow OpenAPI to compile. # Each of these is authoritatively defined in # the CSMP TLV definitions. Duffy (ed) Expires 27 April 2023 [Page 15] Internet-Draft CoAP Simple Management Protocol October 2022 # TlvIndex: type: object DeviceID: type: object NMSRedirectRequest: type: object SessionID: type: object DescriptionRequest: type: object HardwareDesc: type: object InterfaceDesc: type: object ReportSubscribe: type: object IPAddress: type: object IPRoute: type: object CurrentTime: type: object RPLSettings: type: object Uptime: type: object InterfaceMetrics: type: object IPRouteRPLMetrics: type: object PingRequest: type: object PingResponse: type: object RebootRequest: type: object Ieee8021xStatus: type: object Ieee80211iStatus: type: object WPANStatus: type: object DHCP6ClientStatus: type: object NMSSettings: type: object NMSStatus: Duffy (ed) Expires 27 April 2023 [Page 16] Internet-Draft CoAP Simple Management Protocol October 2022 type: object Ieee8021xSettings: type: object Ieee802154BeaconStats: type: object RPLInstance: type: object GroupAssign: type: object GroupEvict: type: object GroupMatch: type: object GroupInfo: type: object LowpanMacStats: type: object LowpanPhySettings: type: object TransferRequest: type: object ImageBlock: type: object LoadRequest: type: object CancelLoadRequest: type: object SetBackupRequest: type: object TransferResponse: type: object LoadResponse: type: object CancelLoadResponse: type: object SetBackupResponse: type: object FirmwareImageInfo: type: object SignatureValidity: type: object Signature: type: object SignatureSettings: type: object SysResetStats: type: object NetStat: Duffy (ed) Expires 27 April 2023 [Page 17] Internet-Draft CoAP Simple Management Protocol October 2022 type: object NetworkRole: type: object CertBundle: type: object MplStats: type: object MplReset: type: object RPLStats: type: object DHCP6Stats: type: object EventReport: type: object EventIndex: type: object EventSubscribe: type: object EventStats: type: object 3.3. Resources CSMP devices and CSMP NMS use the CoAP GET, POST, and DELETE methods to manipulate the resources specified in Section 3.3.2.2, which are the Protocol Buffer object payloads contained in the various CoAP requests and responses. Usage of these payloads is detailed in the sections which follow. 3.3.1. Base URL A CSMP server is located at a of the form coap://hostname:port/ The for all CSMP resources at a particular hostname:port MUST be identical. It is RECOMMENDED that a default of "/." be used. Because an NMS CSMP request message may be multicast to a large number of devices, all CSMP devices within a multicast domain MUST have identical port and . The following are reserved for future use: 1. /o Duffy (ed) Expires 27 April 2023 [Page 18] Internet-Draft CoAP Simple Management Protocol October 2022 Full details of the Device and NMS service URLs are defined in Section 3.2.1 and Section 3.2.2. 3.3.2. Resource Encoding 3.3.2.1. Standard TLVs The message payloads of CSMP requests and responses MUST be formatted as a sequence of Type-Length-Value objects. Each TLV object has the following format: | Type | Length | Value | The Type field is an unsigned integer identifying a specific CSMP TLV ID and MUST be encoded as a Protocol Buffers varint. The Length field is an unsigned integer containing the number of octets occupied by the Value field. The Length field MUST be encoded as a Protocol Buffers varint. The Value field MUST contain the Protocol Buffers encoded TLV corresponding to the indicated Type. The set of objects defined by CSMP and their Type (TLV ID) are specified in Section 3.3.2.2. 3.3.2.2. CSMP TLV Definitions This section contains the CSMP TLV definitions (defined using [PB]). The definitions are also available at [CSMPMSG] which is directly importable into development tooling. syntax = "proto3"; /* The definitions for CSMP TLVs. This file is directly consumable by the Protocol Buffer tool chain. Requirements are specified using the terminology and conventions as referenced in [RFC2119]. Requirements key words referenced in [RFC2119] must be capitalized. Full details re: Protocol Buffers are accessible at https://developers.google.com/protocol-buffers */ /* CSMP TLV ID Mapping to Protocol Buffer messages. A unique TLV ID MUST be assigned to each CSMP Protocol Buffer message (defined within). An unused TLV ID MAY be assigned to a new message. The new TLV ID assignment MUST be recorded within, along with the defintion of the new message. A Reserved TLV ID MUST NOT be assigned to a message. An existing TLV ID assignment MUST NOT be re-assigned to a new message. Duffy (ed) Expires 27 April 2023 [Page 19] Internet-Draft CoAP Simple Management Protocol October 2022 NOTE the legend. - Unused: available for assignment. - Reserved: not available for assignment. - All other named messages are currently used by CSMP for generic and RF Mesh device management. All TLV assignments MUST be recorded in the table below. Take care to maintain the numbering. TLVID Message 1 TlvIndex 2 DeviceID 3 Reserved 4 Unused 5 Unused 6 NMSRedirectRequest 7 SessionID 8 DescriptionRequest 9 Unused 10 Reserved 11 HardwareDesc 12 InterfaceDesc 13 ReportSubscribe 14 Reserved 15 Reserved 16 IPAddress 17 IPRoute 18 CurrentTime 19 Reserved 20 Reserved 21 RPLSettings 22 Uptime 23 InterfaceMetrics 24 Reserved 25 IPRouteRPLMetrics 26 Unused 27-29 Reserved 30 PingRequest 31 PingResponse 32 RebootRequest 33 Ieee8021xStatus 34 Ieee80211iStatus 35 WPANStatus 36 DHCP6ClientStatus 37-41 Reserved 42 NMSSettings 43 NMSStatus 44-46 Reserved 47 Ieee8021xSettings 48 Ieee802154BeaconStats 49-52 Reserved 53 RPLInstance Duffy (ed) Expires 27 April 2023 [Page 20] Internet-Draft CoAP Simple Management Protocol October 2022 54 Reserved 55 GroupAssign 56 GroupEvict 57 GroupMatch 58 GroupInfo 59 Unused 60 Unused 61 Reserved 62 LowpanMacStats 63 LowpanPhySettings 64 Unused 65 TransferRequest 66 Reserved 67 ImageBlock 68 LoadRequest 69 CancelLoadRequest 70 SetBackupRequest 71 TransferResponse 72 LoadResponse 73 CancelLoadResponse 74 SetBackupResponse 75 FirmwareImageInfo 76 SignatureValidity 77 Signature 78 Reserved 79 SignatureSettings 80 Reserved 81 Reserved 82 Unused 83 Unused 84 Reserved 85 Unused 86 SysResetStats 87 Unused 88 Reserved 89 Unused 90 Unused 91-97 Reserved 98 Unused 99 Unused 100 Reserved 101 Unused 102 Unused 103 Unused 104 Unused 105 Unused 106 Unused 107 Reserved Duffy (ed) Expires 27 April 2023 [Page 21] Internet-Draft CoAP Simple Management Protocol October 2022 108 Reserved 109 Unused 110-112 Reserved 113 Unused 114 Unused 115-117 Reserved 118 Unused 119 Unused 120-122 Reserved 123 Unused 124 NetStat 125 Reserved 126 Reserved 127 Vendor Defined TLV 128-131 Reserved 132-139 Unused 140 Reserved 141 NetworkRole 142-151 Reserved 152-154 Unused 155-157 Reserved 158-159 Unused 160-165 Reserved 166-169 Unused 170-171 Reserved 172 CertBundle 173-179 Unused 180 Reserved 181-199 Unused 200-202 Reserved 203-209 Unused 210 Reserved 211 Reserved 212-216 Unused 217-220 Reserved 221-239 Unused 240 Reserved 241 MplStats 242 MplReset 243-299 Unused 301-303 Reserved 304 Unused 305-307 Reserved 308-309 Unused 310-312 Reserved 313 RPLStats 314 DHCP6Stats 315 Reserved Duffy (ed) Expires 27 April 2023 [Page 22] Internet-Draft CoAP Simple Management Protocol October 2022 316 Reserved 317-324 Unused 325-337 Reserved 338-339 Unused 340-399 Reserved 400-499 Unused 500 Reserved 501 Reserved 502 Reserved 503-509 Unused 510 Reserved 511 Reserved 512-519 Unused 520 Reserved 521 Reserved 522-529 Unused 530 Reserved 531 Reserved 532-539 Unused 540 Reserved 541-599 Unused 600-607 Reserved 608 ... Unused */ /* Message definitions follow. Tag notation used within ... Class:: designates class of device for which the TLV is relevant. Generic (any IP addressable device) Mesh (Wi-SUN mesh devices) Others TBD. */ package csmp.tlvs; // TLV 1 // A list of zero or more TLV IDs // Class:: Generic // message TlvIndex { repeated string tlvid = 1; // list of TLV IDs (string encoded) supported by the device. } // TLV 2 // Primary identifier for a specific device. // Class:: Generic Duffy (ed) Expires 27 April 2023 [Page 23] Internet-Draft CoAP Simple Management Protocol October 2022 // message DeviceID { oneof type_present { uint32 type = 1; // Set to 1 to indicate EUI-64 format. } oneof id_present { string id = 2; // The unique identifier of the device in EUI-64 format } } // TLV 6 // Used by NMS to force a device to intitiate registration to a specific NMS. // Class:: Generic // message NMSRedirectRequest { oneof url_present { string url = 1; // NMS to which the device registration will be directed. MUST be formatted per section 6 of RFC 7252. } oneof immediate_present { bool immediate = 2; // True == device should immediately send registration request to the specificed NMS url. } } // TLV 7 // Session ID used by NMS to track device CSMP messaging. // Assigned by the NMS, and used in all subsequent Device to NMS messaging. // Class:: Generic // message SessionID { oneof id_present { string id = 1; // session ID } } // TLV 8 // List of zero or more TLVs requested by the NMS from a Device. // The values of the requested TLVs will be sent to the NMS asynchronously. // Class:: Generic // message DescriptionRequest { repeated string tlvid = 1; // list of TLV IDs in string format. } // A list of hardware modules with their firmware versions. Duffy (ed) Expires 27 April 2023 [Page 24] Internet-Draft CoAP Simple Management Protocol October 2022 // message HardwareModule { oneof moduleType_present { uint32 moduleType = 1; // hardware module type. Rf Dsp=1, PLC Dsp=2, CPU=3, FPGA=4 } oneof firmwareRev_present { string firmwareRev = 2; // firmware version of the hardware module } } // TLV 11 // This TLV contains hardware description information for the device. // The contents of the fields are defined by the equivalently-named fields in the entry of the SNMP MIB object entPhysicalTable. // Class:: Generic // message HardwareDesc { oneof entPhysicalIndex_present { int32 entPhysicalIndex = 1; // index of this hardware being described } oneof entPhysicalDescr_present { string entPhysicalDescr = 2; // A textual description of physical entity } oneof entPhysicalVendorType_present { bytes entPhysicalVendorType = 3; // An indication of the vendor-specific hardware type of the physical entity } oneof entPhysicalContainedIn_present { int32 entPhysicalContainedIn = 4; // The value of entPhysicalIndex for the physical entity which 'contains' this physical entity } oneof entPhysicalClass_present { int32 entPhysicalClass = 5; // An indication of the general hardware type of the physical entity } oneof entPhysicalParentRelPos_present { int32 entPhysicalParentRelPos = 6; // An indication of the relative position of this 'child' component among all its 'sibling' components } oneof entPhysicalName_present { string entPhysicalName = 7; // The textual name of the physical entity } oneof entPhysicalHardwareRev_present { string entPhysicalHardwareRev = 8; // The vendor-specific hardware revision string for the physical entity } oneof entPhysicalFirmwareRev_present { string entPhysicalFirmwareRev = 9; // The vendor-specific firmware revision string for the physical entity } oneof entPhysicalSoftwareRev_present { string entPhysicalSoftwareRev = 10; // The vendor-specific software revision string for the physical entity } oneof entPhysicalSerialNum_present { Duffy (ed) Expires 27 April 2023 [Page 25] Internet-Draft CoAP Simple Management Protocol October 2022 string entPhysicalSerialNum = 11; // The vendor-specific serial number string for the physical entity } oneof entPhysicalMfgName_present { string entPhysicalMfgName = 12; // The name of the manufacturer of this physical component } oneof entPhysicalModelName_present { string entPhysicalModelName = 13; // The vendor-specific model name identifier string associated with this physical component } oneof entPhysicalAssetID_present { string entPhysicalAssetID = 14; // This object is a user-assigned asset tracking identifier for the physical entity and provides non-volatile storage of this information } oneof entPhysicalMfgDate_present { uint32 entPhysicalMfgDate = 15; // This object contains the date of manufacturing of the managed entity } oneof entPhysicalURIs_present { string entPhysicalURIs = 16; // This object contains additional identification information about the physical entity } oneof entPhysicalFunction_present { uint32 entPhysicalFunction = 17; // The entPhysicalFunction field can take the following values: METER = 1, RANGE_EXTENDER = 2, DA_GATEWAY = 3, CGE = 4, ROOT = 5, CONTROLLER = 6, SENSOR. = 7, NETWORKNODE = 8 } oneof entPhysicalOUI_present { bytes entPhysicalOUI = 18; // uniquely identifies a vendor } repeated HardwareModule hwModule = 19; // This defines a list of hardware modules with their firmware versions } // TLV 12 // This TLV contains description information for an interface on the device. // The contents of these fields are defined by the equivalently-named fields in the SNMP MIB object ifTable // Class:: Generic // message InterfaceDesc { oneof ifIndex_present { int32 ifIndex = 1; // A unique value, greater than zero, for each interface } oneof ifName_present { string ifName = 2; // The textual name of the interface } oneof ifDescr_present { string ifDescr = 3; // A textual string containing information about the interface } oneof ifType_present { int32 ifType = 4; // The type of interface } oneof ifMtu_present { int32 ifMtu = 5; // The size of the largest packet which can be sent/received on the interface, specified in octets } Duffy (ed) Expires 27 April 2023 [Page 26] Internet-Draft CoAP Simple Management Protocol October 2022 oneof ifPhysAddress_present { bytes ifPhysAddress = 6; // The interface's address at its protocol sub-layer } } // TLV 13 // This TLV specifies the periodic reporting of a set of TLVs. // Class:: Generic // message ReportSubscribe { oneof interval_present { uint32 interval = 1; // The periodic time interval (in seconds) at which the device sends the tlvid set of tlvs. } repeated string tlvid = 2; // The tlvs to be sent on the interval. oneof intervalHeartBeat_present { uint32 intervalHeartBeat = 3; // The periodic time interval at which the device sends the tlvidHeartBeat set of tlvs. } repeated string tlvidHeartBeat = 4; // The tlvs to be sent on the heartbeat interval. } // TLV 16 // Describes a particular IP address (identified by the index) attached to an interface. // Class:: Generic // message IPAddress { oneof ipAddressIndex_present { int32 ipAddressIndex = 1; // A unique value, greater than zero, for each IP address } oneof ipAddressAddrType_present { uint32 ipAddressAddrType = 2; // Address type defined as integers : ipv4=1, ipvv6=2, ipv4z=3, ipv6z=4, ipv6am=5 } oneof ipAddressAddr_present { bytes ipAddressAddr = 3; // The IP address } oneof ipAddressIfIndex_present { int32 ipAddressIfIndex = 4; // Index of the associated interface } oneof ipAddressType_present { uint32 ipAddressType = 5; // IP type defined as integers : unicast=1, anycast=2, broadcast=3 } oneof ipAddressOrigin_present { uint32 ipAddressOrigin = 6; // Address origin defined as integers : other=1, manual=2, dhcp=4, linklayer=5, random=6 } oneof ipAddressStatus_present { uint32 ipAddressStatus = 7; // status defined as integers : preferred=1, deprecated=2, invalid=3, inaccessible=4, unknown=5, tentative=6, duplicate=7, optimistic=8 } Duffy (ed) Expires 27 April 2023 [Page 27] Internet-Draft CoAP Simple Management Protocol October 2022 reserved 8; // oneof ipAddressCreated reserved 9; // oneof ipAddressLastChanged oneof ipAddressPfxLen_present { uint32 ipAddressPfxLen = 10; // The prefix length associated with the IP address. } } // TLV 17 // Describes a particular IP route (identified by the index) attached to an interface. // Class:: Generic // message IPRoute { oneof inetCidrRouteIndex_present { int32 inetCidrRouteIndex = 1; // A unique value, greater than zero, for each route } oneof inetCidrRouteDestType_present { uint32 inetCidrRouteDestType = 2; // Destination Addresss type defined as integers : ipv4=1, ipvv6=2, ipv4z=3, ipv6z=4, ipv6am=5 } oneof inetCidrRouteDest_present { bytes inetCidrRouteDest = 3; // IP address of the destination of the route } oneof inetCidrRoutePfxLen_present { uint32 inetCidrRoutePfxLen = 4; // Associated prefix length of the route destination } oneof inetCidrRouteNextHopType_present { uint32 inetCidrRouteNextHopType = 5; // Next hop Addresss type defined as integers : ipv4=1, ipvv6=2, ipv4z=3, ipv6z=4, ipv6am=5 } oneof inetCidrRouteNextHop_present { bytes inetCidrRouteNextHop = 6; // IP address of the next hop of the route (device parent). } oneof inetCidrRouteIfIndex_present { int32 inetCidrRouteIfIndex = 7; // Index of the associated interface } reserved 8; // oneof inetCidrRouteType reserved 9; // oneof inetCidrRouteProto reserved 10; // oneof inetCidrRouteAge } // TLV 18 // Contains the current time as maintainced on the device. // For time stamping purposes, this tlvid MUST also be sent along with every periodic metric report. // It MAY contain a POSIX timestamp or an ISO 8601 timestamp. // Class:: Generic // message CurrentTime { oneof posix_present { Duffy (ed) Expires 27 April 2023 [Page 28] Internet-Draft CoAP Simple Management Protocol October 2022 uint32 posix = 1; // posix timestamp } oneof iso8601_present { string iso8601 = 2; // iso 8601 timestamp } oneof source_present { uint32 source = 3; // time service from. 1: local; 2: admin; 3: network } } // TLV 21 // For retrieving the RPL Settings on the device. // Class:: Mesh // message RPLSettings { oneof ifIndex_present { int32 ifIndex = 1; // interface id } oneof enabled_present { bool enabled = 2; // whether RPL feature is enabled } oneof dioIntervalMin_present { uint32 dioIntervalMin = 3; // min interval of DIO trickle timer in milliseconds } oneof dioIntervalMax_present { uint32 dioIntervalMax = 4; // max interval of DIO trickle timer in milliseconds } oneof daoIntervalMin_present { uint32 daoIntervalMin = 5; // min interval of DAO trickle timer in milliseconds } oneof daoIntervalMax_present { uint32 daoIntervalMax = 6; // max interval of DAO trickle timer in milliseconds } oneof mopType_present { uint32 mopType = 7; // mode of operation for RPL. 1: non-storing mode; 2: storing mode } } // TLV 22 // Contains the total system uptime of the device (seconds). // Class:: Generic // message Uptime { oneof sysUpTime_present { uint32 sysUpTime = 1; // uptime info in seconds } Duffy (ed) Expires 27 April 2023 [Page 29] Internet-Draft CoAP Simple Management Protocol October 2022 } // TLV 23 // The statistics of an interface // Class:: Generic // message InterfaceMetrics { oneof ifIndex_present { int32 ifIndex = 1; // A unique value, greater than zero, for each interface. Is same as in InterfaceDesc's ifIndex for the same interface } oneof ifInSpeed_present { uint32 ifInSpeed = 2; // The speed at which the incoming packets are received on the interface } oneof ifOutSpeed_present { uint32 ifOutSpeed = 3; // The speed at which the outgoing packets are transmitted on the interface } oneof ifAdminStatus_present { uint32 ifAdminStatus = 4; // The desired state of the interface } oneof ifOperStatus_present { uint32 ifOperStatus = 5; // The current operational state of the interface } oneof ifLastChange_present { uint32 ifLastChange = 6; // The value of sysUpTime at the time the interface entered its current operational state } oneof ifInOctets_present { uint32 ifInOctets = 7; // The total number of octets received on the interface, including framing characters } oneof ifOutOctets_present { uint32 ifOutOctets = 8; // The total number of octets transmitted out of the interface, including framing characters } oneof ifInDiscards_present { uint32 ifInDiscards = 9; // The number of inbound packets which were chosen to be discarded even though no errors had been detected to prevent their being deliverable to a higher-layer protocol (application dependant). } oneof ifInErrors_present { uint32 ifInErrors = 10; // For packet-oriented interfaces, the number of inbound packets that contained errors preventing them from being deliverable to a higher-layer protocol (subset of ifInDiscards). } oneof ifOutDiscards_present { uint32 ifOutDiscards = 11; // The number of outbound packets which were chosen to be discarded even though no errors had been detected to prevent their being transmitted } oneof ifOutErrors_present { uint32 ifOutErrors = 12; // For packet-oriented interfaces, the number of outbound packets that could not be transmitted because of errors } } // TLV 25 // Describes status of each RPL router Duffy (ed) Expires 27 April 2023 [Page 30] Internet-Draft CoAP Simple Management Protocol October 2022 // Class:: Mesh // message IPRouteRPLMetrics { oneof inetCidrRouteIndex_present { int32 inetCidrRouteIndex = 1; // refers to a particular index in the IPRoute table } oneof instanceIndex_present { int32 instanceIndex = 2; // Corresponding RPL instance of this route } oneof rank_present { int32 rank = 3; // advertised rank } oneof hops_present { int32 hops = 4; // not necessary now, but here so we can easily add later once we're propagating hops as a metric } oneof pathEtx_present { int32 pathEtx = 5; // advertised path ethx } oneof linkEtx_present { int32 linkEtx = 6; // next-hop link ETX } oneof rssiForward_present { sint32 rssiForward = 7; // forward RSSI value (relative to the device) } oneof rssiReverse_present { sint32 rssiReverse = 8; // reverse RSSI value (relative to the device) } oneof lqiForward_present { int32 lqiForward = 9; // forward LQI value } oneof lqiReverse_present { int32 lqiReverse = 10; // reverse LQI value } oneof dagSize_present { uint32 dagSize = 11; // nodes count of this pan (number of joined devices) } reserved 12 to 17; // Used by Itron. PhyModeInfo phyModeForward = 18; // forward phy mode value PhyModeInfo phyModeReverse = 19; // reverse phy mode value } // TLV 30 // Requesting the device to perform a ping operation to a destination address. // Class:: Generic // message PingRequest { Duffy (ed) Expires 27 April 2023 [Page 31] Internet-Draft CoAP Simple Management Protocol October 2022 oneof dest_present { string dest = 1; // IP address to be pinged from the device. } oneof count_present { uint32 count = 2; // number of times to ping. } oneof delay_present { uint32 delay = 3; // delay between ping in seconds. } } // TLV 31 // Acquire the current status of the last PingRequest. // Class:: Generic // message PingResponse { oneof sent_present { uint32 sent = 1; // number of packets sent } oneof received_present { uint32 received = 2; // number of packets received } oneof minRtt_present { uint32 minRtt = 3; // min round trip time } oneof meanRtt_present { uint32 meanRtt = 4; // mean round trip time } oneof maxRtt_present { uint32 maxRtt = 5; // max round trip time } oneof stdevRtt_present { uint32 stdevRtt = 6; // standard deviation of the round trip time } oneof src_present { string src = 7; // source IP address for the ping } } // TLV 32 // Request a device to reboot. // Class:: Generic // message RebootRequest { oneof flag_present { uint32 flag = 1; // 0 : reboot and transfer to designated running image; 1 : reboot and stop at bootloader CLI. Duffy (ed) Expires 27 April 2023 [Page 32] Internet-Draft CoAP Simple Management Protocol October 2022 } } // TLV 33 // 802.1x status // Class:: Mesh // message Ieee8021xStatus { oneof ifIndex_present { int32 ifIndex = 1; // It is RECOMMENDED this be set to 2 for the 6LowPAN interface. } oneof enabled_present { bool enabled = 2; // 802.1x enabled or not? } oneof identity_present { string identity = 3; // subject name of certificate, max len 32 } oneof state_present { uint32 state = 4; // state of tls handshake } oneof pmKId_present { bytes pmkId = 5; // hash value of pmk, len 16 } oneof clientCertValid_present { bool clientCertValid = 6; // whether client cert is valid } oneof caCertValid_present { bool caCertValid = 7; // whether ca cert is valid } oneof privateKeyValid_present { bool privateKeyValid = 8; // whether private key of client cert is valid } oneof rlyPanid_present { uint32 rlyPanid = 9; // panid of relay node } oneof rlyAddress_present { bytes rlyAddress = 10; // eui64 address of relay node, len 8 } oneof rlyLastHeard_present { uint32 rlyLastHeard = 11; // last heard from relay node in seconds } } // TLV 34 // 802.11i status // Class:: Mesh // Duffy (ed) Expires 27 April 2023 [Page 33] Internet-Draft CoAP Simple Management Protocol October 2022 message Ieee80211iStatus { oneof ifIndex_present { int32 ifIndex = 1; // It is RECOMMENDED this be set to 2 for the 6LowPAN interface. } oneof enabled_present { bool enabled = 2; // 802.11i is eabled or not } oneof pmkId_present { bytes pmkId = 3; // hash value of pmk, len 16 } oneof ptkId_present { bytes ptkId = 4; // hash value of ptk, len 16 } oneof gtkIndex_present { int32 gtkIndex = 5; // index of gtk } oneof gtkAllFresh_present { bool gtkAllFresh = 6; // whether all gtk are fresh } repeated bytes gtkList = 7; // list of hash value for each gtk, hash len 8, max repeat 4 repeated uint32 gtkLifetimes = 8; // list of lifetime for each gtk, hash len 8, max repeat 4 oneof authAddress_present { bytes authAddress = 9; // eui64 address of authenticate node } } message PhyModeInfo { oneof phyMode_present { uint32 phyMode = 1; // phy operating mode value (as defined in section 5.2 of PHYWG Wi-SUN PHY Technical Specification - Amendment 1VA8) } oneof txPower_present { int32 txPower = 2; // transmit power value in dbm. } } // TLV 35 // Configuration of WPAN-specific interface settings // Class:: Mesh // // message WPANStatus { oneof ifIndex_present { int32 ifIndex = 1; // It is RECOMMENDED this be set to 2 for the 6LowPAN interface. } oneof SSID_present { bytes SSID = 2; // max len 32 (Wi-SUN NetName). } Duffy (ed) Expires 27 April 2023 [Page 34] Internet-Draft CoAP Simple Management Protocol October 2022 oneof panid_present { uint32 panid = 3; } reserved 4; oneof dot1xEnabled_present { bool dot1xEnabled = 5; // Is dot1x enabled? } oneof securityLevel_present { uint32 securityLevel = 6; // security level } oneof rank_present { uint32 rank = 7; } oneof beaconValid_present { bool beaconValid = 8; // Is beacon valid (where invalid means receipt has timed-out/contact with PAN was lost)? (PC frame for Wi-SUN) } oneof beaconVersion_present { uint32 beaconVersion = 9; // beacon version (Wi-SUN PAN version). } oneof beaconAge_present { uint32 beaconAge = 10; // last heard beacon message in seconds (PC frame for Wi-SUN). } oneof txPower_present { int32 txPower = 11; // transmit power value in dbm } oneof dagSize_present { uint32 dagSize = 12; // count of nodes joined to this PAN } oneof metric_present { uint32 metric = 13; // metric to border router (Wi-SUN Routing Cost) } oneof lastChanged_present { uint32 lastChanged = 14; // seconds since last PAN change (PAN ID change). } oneof lastChangedReason_present { uint32 lastChangedReason = 15; // reason for last PAN change: -1 == unknown, 0 == mesh initializing, 1 == mesh connectivity lost, 2 == GTK timeout, 3 == default route lost, 4 == migrated to better PAN, 5 == reserved. } oneof demoModeEnabled_present { bool demoModeEnabled = 16; // Is demo mode enabled? } oneof txFec_present { bool txFec = 17; // Is FEC enabled? } oneof phyMode_present { uint32 phyMode = 18; // phy operating mode value (as defined in section 5.2 of PHYWG Wi-SUN PHY Technical Specification - Amendment 1VA8) } reserved 19; Duffy (ed) Expires 27 April 2023 [Page 35] Internet-Draft CoAP Simple Management Protocol October 2022 repeated PhyModeInfo phyModeList = 20; // multi phy mode and transmit power value for adaptive modulation } // TLV 36 // Status of DHCP6 client // Class:: Generic // message DHCP6ClientStatus { oneof ifIndex_present { int32 ifIndex = 1; // It is RECOMMENDED this be set to 2 for the 6LowPAN interface. } oneof ianaIAID_present { uint32 ianaIAID = 2; // TA ID value } oneof ianaT1_present { uint32 ianaT1 = 3; // T1 value } oneof ianaT2_present { uint32 ianaT2 = 4; // T2 value } } // TLV 42 // Configure device reporting settings. // Class:: Generic // message NMSSettings { oneof regIntervalMin_present { uint32 regIntervalMin = 1; // min interval of register trickle timer in seconds } oneof regIntervalMax_present { uint32 regIntervalMax = 2; // max interval of register trickle timer in seconds } // reserved = 3; // reserved = 4; // reserved = 5; // reserved = 6; } // TLV 43 // Registration status to NMS. // NMS uses this TLV to record the reason for the registration operation as recorded in the lastRegReason field of the TLV. // Class:: Generic // message NMSStatus { Duffy (ed) Expires 27 April 2023 [Page 36] Internet-Draft CoAP Simple Management Protocol October 2022 oneof registered_present { bool registered = 1; // True of device is registerd with NMS } oneof NMSAddr_present { bytes NMSAddr = 2; // IPv6 address of NMS } oneof NMSAddrOrigin_present { uint32 NMSAddrOrigin = 3; // Mechanims used to get NMS's IPv6 address (fixed/DHCPv6/redirect by TLV6 ... values). } oneof lastReg_present { uint32 lastReg = 4; // time since last succesful registration in seconds } oneof lastRegReason_present { uint32 lastRegReason = 5; // reason for last registration. 1: coldstart 2: administrative 3: IP address changed 4: NMS changed 5: NMS redirect 6: NMS error 7: IDevID, LDevID, or NMS certificate changed 8: outage recovery. } oneof nextReg_present { uint32 nextReg = 6; // time to next registration attempt in seconds. } oneof NMSCertValid_present { bool NMSCertValid = 7; // True if NMS certificate is valid. } } // TLV 47 // Device settings for 802.1x // Class:: Mesh // message Ieee8021xSettings { oneof ifIndex_present { int32 ifIndex = 1; // It is RECOMMENDED this be set to 2 for the 6LowPAN interface. } oneof secMode_present { uint32 secMode = 2; // security mode, non-security or security (Security Level from Aux Security Header of IEEE 802.15.4-2020) } oneof authIntervalMin_present { uint32 authIntervalMin = 3; // min interval of 802.1x trickle timer in seconds } oneof authIntervalMax_present { uint32 authIntervalMax = 4; // max interval of 802.1x trickle timer in seconds } oneof immediate_present { bool immediate = 5; // True == do 802.1x authentication immediately, False == do 802.1x authentication at next authentication interval. } } // TLV 48 // Statistic of 802.15.4 beacon packets Duffy (ed) Expires 27 April 2023 [Page 37] Internet-Draft CoAP Simple Management Protocol October 2022 // Class:: Mesh // message Ieee802154BeaconStats { oneof ifIndex_present { int32 ifIndex = 1; // It is RECOMMENDED this be set to 2 for the 6LowPAN interface. } oneof inFrames_present { uint32 inFrames = 10; // count for all received beacon } oneof inFramesBeaconPAS_present { uint32 inFramesBeaconPAS = 11; // count for received PAS beacon } oneof inFramesBeaconPA_present { uint32 inFramesBeaconPA = 12; // count for received PA beacon } oneof inFramesBeaconPCS_present { uint32 inFramesBeaconPCS = 13; // count for received PCS beacon } oneof inFramesBeaconPC_present { uint32 inFramesBeaconPC = 14; // count for received PC beacon } oneof outFrames_present { uint32 outFrames = 20; // count for all sent out beacon } oneof outFramesBeaconPAS_present { uint32 outFramesBeaconPAS = 21; // count for sent out PAS beacon } oneof outFramesBeaconPA_present { uint32 outFramesBeaconPA = 22; // count for sent out PA beacon } oneof outFramesBeaconPCS_present { uint32 outFramesBeaconPCS = 23; // count for sent out PCS beacon } oneof outFramesBeaconPC_present { uint32 outFramesBeaconPC = 24; // count for sent out PC beacon } } // TLV 53 // Indicates RPL instance information // Class:: Mesh // message RPLInstance { oneof instanceIndex_present { int32 instanceIndex = 1; // index for instance } Duffy (ed) Expires 27 April 2023 [Page 38] Internet-Draft CoAP Simple Management Protocol October 2022 oneof instanceId_present { int32 instanceId = 2; // instance id } oneof doDagId_present { bytes doDagId = 3; // dodag id, len 16 } oneof doDagVersionNumber_present { int32 doDagVersionNumber = 4; // dodag version number of instance } oneof rank_present { int32 rank = 5; // rank value } oneof parentCount_present { int32 parentCount = 6; // Count of available parents (Wi-SUN candidate parent set). } oneof dagSize_present { uint32 dagSize = 7; // nodes count of this dodag } repeated RPLParent parents = 8; // max repeat 3 repeated RPLParent candidates = 9; // max repeat 3 } message RPLParent { oneof parentIndex_present { int32 parentIndex = 1; // this parent's index in the RPLParent table } oneof instanceIndex_present { int32 instanceIndex = 2; // a particular index in the RPLInstance table that this parent underlies. } oneof routeIndex_present { int32 routeIndex = 3; // a particular index in the IPRoute table that this parent underlies } oneof ipv6AddressLocal_present { bytes ipv6AddressLocal = 4; // IPv6 linklocal address } oneof ipv6AddressGlobal_present { bytes ipv6AddressGlobal = 5; // IPv6 global address } oneof doDagVersionNumber_present { uint32 doDagVersionNumber = 6; // dodag version number if RPL parent } oneof pathEtx_present { int32 pathEtx = 7; // the parent's ETX back to the root. } oneof linkEtx_present { int32 linkEtx = 8; // the node's ETX to its next-hop } oneof rssiForward_present { Duffy (ed) Expires 27 April 2023 [Page 39] Internet-Draft CoAP Simple Management Protocol October 2022 sint32 rssiForward = 9; // forward RSSI value } oneof rssiReverse_present { sint32 rssiReverse = 10; // reverse RSSI value } oneof lqiForward_present { int32 lqiForward = 11; // forward LQI value } oneof lqiReverse_present { int32 lqiReverse = 12; // reverse LQI value } oneof hops_present { int32 hops = 13; // parent's hop value } } // Groups in CSMP provide a mechanism to realize application layer multicast in the network. // A group is uniquely defined by a type, id pair. Membership within a group type is exclusive, // i.e., a device can be a member of only one group-id within a group-type. // However, a device can be a member of more than one group of different group-types. // A device is informed about its membership to a group using a GroupAssign TLV. // On their very first boot, devices do not belong to any group. A device is added to a group by sending a GroupAssign TLV to the device. // Receipt of a GroupAssign TLV replaces any existing group assignments. // GroupAssign may occur either by direct unicast to a device or in the registration response from the NSM to the device. // Note that a GroupAssign should not be sent over a multicast, because it would possibly cause some group members to change and some group members not to change. // Group membership information MUST be stored in persistent storage so that once a device has been assigned any group it is remembered across reboots. // A device will only process multicast messages containing a GroupMatch TLV if the device belongs to a group specified by the GroupMatch TLV. // TLV 55 // Class:: Generic // message GroupAssign { oneof type_present { uint32 type = 1; } oneof id_present { uint32 id = 2; } } // TLV 57 // Class:: Generic // Duffy (ed) Expires 27 April 2023 [Page 40] Internet-Draft CoAP Simple Management Protocol October 2022 message GroupMatch { oneof type_present { uint32 type = 1; } oneof id_present { uint32 id = 2; } } // TLV 58 // Class:: Generic // GET to a device for this TLV MAY illicit a response with one or more GroupInfo TLVs. // message GroupInfo { oneof type_present { uint32 type = 1; } oneof id_present { uint32 id = 2; } } message LowpanMacCounters { oneof inFrames_present { uint32 inFrames = 1; // count for all received frames } oneof inFramesBeacon_present { uint32 inFramesBeacon = 2; // count for received beacon frames (Note: Wi-SUN does not use Beacon frames). } oneof inFramesData_present { uint32 inFramesData = 3; // count for received data frames } oneof inFramesAck_present { uint32 inFramesAck = 4; // count for received ack frames } oneof inFramesCmd_present { uint32 inFramesCmd = 5; // count for received command frames } oneof inFramesAsync_present { uint32 inFramesAsync = 6; // count for received async frames } oneof inFramesBcast_present { uint32 inFramesBcast = 7; // count for received broadcast frames } oneof inFramesUcast_present { uint32 inFramesUcast = 8; // count for received unicast frames } Duffy (ed) Expires 27 April 2023 [Page 41] Internet-Draft CoAP Simple Management Protocol October 2022 oneof outFrames_present { uint32 outFrames = 9; // count for all sent out frames } oneof outFramesBeacon_present { uint32 outFramesBeacon = 10; // count for sent out beacon frames } oneof outFramesData_present { uint32 outFramesData = 11; // count for sent out data frames } oneof outFramesAck_present { uint32 outFramesAck = 12; // count for sent out ack frames } oneof outFramesCmd_present { uint32 outFramesCmd = 13; // count for sent out command frames } oneof outFramesAsync_present { uint32 outFramesAsync = 14; // count for sent out async frames } oneof outFramesBcast_present { uint32 outFramesBcast = 15; // count for recesent outived broadcast frames } oneof outFramesUcast_present { uint32 outFramesUcast = 16; // count for sent out unicast frames } } // TLV 62 // Statistic of lowpan mac layer // Class:: Mesh // message LowpanMacStats { LowpanMacCounters total = 1; // total counter for lowpan mac layer LowpanMacCounters rf = 2; // rf counter for lowpan mac layer reserved 3; // optional LowpanMacCounters plc = 3; } // TLV 63 // Configuration of RF PHY // Class:: Mesh // message LowpanPhySettings { oneof lowpanRF_present { uint32 lowpanRF = 1; // 1 == enable lowpan rf, 0 == disable. } reserved 2; // optional uint32 lowpanPLC = 2; } Duffy (ed) Expires 27 April 2023 [Page 42] Internet-Draft CoAP Simple Management Protocol October 2022 // TLV 65 - 75 are for firmware upgrade, detailed in CSMP specification. // message HardwareInfo { oneof hwId_present { string hwId = 1; // hardware information, max len 32 } oneof vendorHwId_present { string vendorHwId = 2; // sub hardware information, max len 32 } } // TLV 65 // Start to transfer firmware // Class:: Generic // message TransferRequest { HardwareInfo hwInfo = 1; // hardware information oneof fileHash_present { bytes fileHash = 2; // SHA256 hash value of image file, len 32 } oneof fileName_present { string fileName = 3; // name of image file, max len 128 } oneof version_present { string version = 4; // version number, man len 32 } oneof fileSize_present { uint32 fileSize = 5; // total size of image file } oneof blockSize_present { uint32 blockSize = 6; // block size of image file } // reserved = 7; // reserved = 8; // reserved = 9; // reserved = 10; // reserved = 11; } // TLV 67 // Class:: Generic // message ImageBlock { oneof fileHash_present{ bytes fileHash = 1; // SHA256 hash value of image file, len 32 } Duffy (ed) Expires 27 April 2023 [Page 43] Internet-Draft CoAP Simple Management Protocol October 2022 oneof blockNum_present { uint32 blockNum = 2; // block number 0, 1, 2, etc. } oneof blockData_present { bytes blockData = 4; // block context, max len 1024 } } // TLV 68 // Firmware load request // Class:: Generic // message LoadRequest { oneof fileHash_present { bytes fileHash = 1; // SHA256 hash value of image file, len 32 } oneof loadTime_present { uint32 loadTime = 2; // UTC time to load image, set to 1 to load immeditealy. } } // TLV 69 // Firmware cancel load request // Class:: Generic // message CancelLoadRequest { oneof fileHash_present { bytes fileHash = 1; // SHA256 hash value of image file, len 32 } } // TLV 70 // Set firmware to backup slot // Class:: Generic // message SetBackupRequest { oneof fileHash_present { bytes fileHash = 1; // SHA256 hash value of image file, len 32 } } /* ResponseCodes enum { OK = 0; // The request was successfully processed. INCOMPATIBLE_HW = 1; // Device hardware type does not match the request's hardware type. Duffy (ed) Expires 27 April 2023 [Page 44] Internet-Draft CoAP Simple Management Protocol October 2022 IMAGE_INCOMPLETE = 2; // Image operation cannot be completed, device only has partial image. UNKNOWN_HASH = 3; // File hash does not match any image available on the device. FILE_SIZE_TOO_BIG = 4; // Image download is denied, filesize of the new image is too large. SIGNATURE_FAILED = 5; // Image signature check failed. INVALID_REQ = 6; // Invalid request. INVALID_BLOCK_SIZE = 7; // Invalid image block size. PENDING_REBOOT = 8; // Request cannot be processed, conflict with a pending device reboot. IMAGE_RUNNING = 9; // Cancel reboot request cannot be processed, image is already running. } */ // TLV 71 // Response for TLV 65 TransferRequest // Class:: Generic // message TransferResponse { oneof fileHash_present { bytes fileHash = 1; // SHA256 hash value of image file, len 32 } oneof response_present { uint32 response = 2; // refer to ResponseCodes } } // TLV 72 // Response for TLV 68 LoadRequest // Class:: Generic // message LoadResponse { oneof fileHash_present { bytes fileHash = 1; // SHA256 hash value of image file, len 32 } oneof response_present { uint32 response = 2; // refer to ResponseCodes } oneof loadTime_present { uint32 loadTime = 3; // UTC time to load image } } // TLV 73 // Response for TLV 69 CancelLoadRequest // Class:: Generic // message CancelLoadResponse { Duffy (ed) Expires 27 April 2023 [Page 45] Internet-Draft CoAP Simple Management Protocol October 2022 oneof fileHash_present { bytes fileHash = 1; // SHA256 hash value of image file, len 32 } oneof response_present { uint32 response = 2; // refer to ResponseCodes } } // TLV 74 // Class:: Generic // message SetBackupResponse { oneof fileHash_present { bytes fileHash = 1; // SHA256 hash value of image file, len 32 } oneof response_present { uint32 response = 2; // refer to ResponseCodes } } // TLV 75 // Image information // Class:: Generic // message FirmwareImageInfo { oneof index_present { uint32 index = 1; } oneof fileHash_present { bytes fileHash = 2; // SAH256 hash value of image file, len 32 } oneof fileName_present { string fileName = 3; // name of image file, max len 128 } oneof version_present { string version = 4; // version number, man len 32 } oneof fileSize_present { uint32 fileSize = 5; // total size of image file } oneof blockSize_present { uint32 blockSize = 6; // block size of image file } oneof bitmap_present { bytes bitmap = 7; // bitmap of image file, max len 128. Big endian. 1 means block was received, 0 means block was not received. } Duffy (ed) Expires 27 April 2023 [Page 46] Internet-Draft CoAP Simple Management Protocol October 2022 oneof isDefault_present { bool isDefault = 8; // True if default image } oneof isRunning_present { bool isRunning = 9; // True if running image } oneof loadTime_present { uint32 loadTime = 10; // UTC time to load. 1 means load immediately. } HardwareInfo hwInfo = 11; // hardware information oneof bitmapOffset_present { uint32 bitmapOffset = 12; // When present, MUST be set to indicate the start block number of bitmap. Block numbering is 0 based. } // reserved = 13; // reserved = 14; // reserved = 15; } // TLV 76 // Class:: Generic // message SignatureValidity { oneof notBefore_present { uint32 notBefore = 1; // posix time } oneof notAfter_present { uint32 notAfter = 2; // posix time } } // TLV 77 // Class:: Generic // message Signature { oneof value_present { bytes value = 1; } } // TLV 79 // Configuration of signature check settings about message from NMS // Class:: Generic // message SignatureSettings { oneof reqSignedPost_present { Duffy (ed) Expires 27 April 2023 [Page 47] Internet-Draft CoAP Simple Management Protocol October 2022 bool reqSignedPost = 1; // check signature in POST message from NMS? } oneof reqValidCheckPost_present { bool reqValidCheckPost = 2; // time valid check in POST message from NMS? } oneof reqTimeSyncPost_present { bool reqTimeSyncPost = 3; // return fail when node doesn't have global time in POST message from NMS? } oneof reqSecLocalPost_present { bool reqSecLocalPost = 4; // check signature in POST message from console? } oneof reqSignedResp_present { bool reqSignedResp = 5; // check signature in response message from NMS during registation? } oneof reqValidCheckResp_present { bool reqValidCheckResp = 6; // time valid check in response message from NMS during registation? } oneof reqTimeSyncResp_present { bool reqTimeSyncResp = 7; // return fail when node doesn't have global time in response message from NMS during registation? } oneof reqSecLocalResp_present { bool reqSecLocalResp = 8; // check signature in response message from console during registation? } oneof cert_present { bytes cert = 9; // cert context, used to change NMS's certificate, max len 512 } } message HardwareResetCount { oneof total_present { uint32 total = 1; } oneof externalReset_present { uint32 externalReset = 2; // external reset reason. } oneof powerOnReset_present { uint32 powerOnReset = 3; // power on reset reason. } } message SoftwareResetCount { oneof total_present { uint32 total = 1; } oneof FWLoadReset_present { uint32 FWLoadReset = 2; // firmware reload } oneof CSMPRebootReset_present { Duffy (ed) Expires 27 April 2023 [Page 48] Internet-Draft CoAP Simple Management Protocol October 2022 uint32 CSMPRebootReset = 3; // reload by csmp TLV } oneof vendorProgramReset_present { uint32 vendorProgramReset = 4; // reload by vendor's APP } oneof cfgLoadReset_present { uint32 cfgLoadReset = 5; // reload config file } } message ExceptionResetCount { oneof total_present { uint32 total = 1; } oneof IWDGReset_present { uint32 IWDGReset = 2; // watchdog reset } oneof cstackOverflowReset_present { uint32 cstackOverflowReset = 3; // stack over flow reset } oneof EPFReset_present { uint32 EPFReset = 4; // GPIO reset } } // TLV 86 // Count of all types of reset in the system, include hardware reset, software reset and exception reset // Class:: Generic // message SysResetStats { oneof total_present { uint32 total = 1; // reset count } HardwareResetCount hardwareReset = 2; SoftwareResetCount softwareReset = 3; ExceptionResetCount exceptionReset = 4; } // TLV 124 // Status of device network module, similar as netstat command in linux // Class:: Generic // message NetStat { oneof sessionIndex_present { int32 sessionIndex = 1; // session index } Duffy (ed) Expires 27 April 2023 [Page 49] Internet-Draft CoAP Simple Management Protocol October 2022 oneof protocol_present { uint32 protocol = 2; // 6 - TCP, 17 - UDP } oneof localAddress_present { bytes localAddress = 3; // ipv4 or ipv6 local address } oneof localPort_present { uint32 localPort = 4; // local port } oneof peerAddress_present { bytes peerAddress = 5; // ipv4 or ipv6 peer address } oneof peerPort_present { uint32 peerPort = 6; // peer port } oneof state_present { uint32 state = 7; } oneof role_present { uint32 role = 8; // 1 - server/incoming, 2 - client/outgoing } } // TLV 141 // Indicate the network role of device // Class:: Generic // message NetworkRole { uint32 preference = 1; // 0 - SYSTEM_DEFAULT, 1 - TRANSIT_NODE, 2 - LEAF_NODE } message CertInfoEntry { oneof type_present { uint32 type = 1; // 1: FND public key; 2: 802.1x CA; 3: 802.1x public key; 4: iDevID public key; } oneof certSubj_present { string certSubj = 2; // certificate subject name, max length 128 } oneof certValidNotBefore_present { string certValidNotBefore = 3; // not before of valid time, max length 16 } oneof certValidNotAfter_present { string certValidNotAfter = 4; // not after of valid time, max length 16 } oneof certFingerprint_present { bytes certFingerprint = 5; // certificate finger print, max length 20 } Duffy (ed) Expires 27 April 2023 [Page 50] Internet-Draft CoAP Simple Management Protocol October 2022 } // TLV 172 // Device Certificate Bundle TLV. // message CertBundle { repeated CertInfoEntry certInfo = 1; // max repeat is 5 } // TLV 241 // Statistic of MPL packet // Class:: Mesh // message MplStats { oneof dataSent_present { uint32 dataSent = 1; // count for send out data packet } oneof dataReceived_present { uint32 dataReceived = 2; // count for received data packet } oneof dataError_present { uint32 dataError = 3; // count for error data packet } oneof dataSentDuplicate_present { uint32 dataSentDuplicate = 4; // count for duplicate sent out data packet } oneof dataReceivedDuplicate_present { uint32 dataReceivedDuplicate = 5; // count for duplicate received data packet } oneof controlSent_present { uint32 controlSent = 6; // count for send out control packet } oneof controlReceived_present { uint32 controlReceived = 7; // count for received control packet } oneof controlError_present { uint32 controlError = 8; // count for error control packet } } // TLV 242 // Reset statistic of MPL packet // Class:: Mesh // message MplReset { oneof stats_present { Duffy (ed) Expires 27 April 2023 [Page 51] Internet-Draft CoAP Simple Management Protocol October 2022 bool stats = 8; // True == reset statistics of MPL packet } } // TLV 313 // Statistics for RPL messages // Class:: Mesh // message RPLStats { oneof inFramesDIS_present { uint32 inFramesDIS = 1; // count for received DIS packets } oneof inFramesDIO_present { uint32 inFramesDIO = 2; // count for received DIO packets } oneof inFramesDAO_present { uint32 inFramesDAO = 3; // count for received DAO packets } oneof outFramesDIS_present { uint32 outFramesDIS = 4; // count for send out DIS packets } oneof outFramesDIO_present { uint32 outFramesDIO = 5; // count for send out DIO packets } oneof outFramesDAO_present { uint32 outFramesDAO = 6; // count for send out DAO packets } oneof outFramesNoPathDAO_present { uint32 outFramesNoPathDAO = 7; // count for send out no-path DAO packets } oneof outFramesNS_present { uint32 outFramesNS = 8; // count for send out neighbor solicit packets } } // TLV 314 // Statistics for DHCPv6 messages // Class:: Generic // message DHCP6Stats { oneof clientFramesSolicit_present { uint32 clientFramesSolicit = 1; // count for send out solicit packets } oneof clientFramesAdvertise_present { uint32 clientFramesAdvertise = 2; // count for send out advertise packets } Duffy (ed) Expires 27 April 2023 [Page 52] Internet-Draft CoAP Simple Management Protocol October 2022 oneof clientFramesRequest_present { uint32 clientFramesRequest = 3; // count for send out request packets } oneof clientFramesReply_present { uint32 clientFramesReply = 4; // count for send out reply packets } oneof relayFramesForward_present { uint32 relayFramesForward = 5; // count for DHCP relay packet which is forwarded by node } oneof relayFramesReply_present { uint32 relayFramesReply = 6; // count for DHCP relay packet which is relaied by node } } 3.3.3. Large Requests A single CSMP TLV MUST NOT be larger than the space available in a single CoAP request message payload, minus the space occupied by mandatory TLVs. CSMP requests containing large TLVs or many TLVs may exceed available space within a CoAP request / UDP datagram. If a POST request is larger than the UDP MTU, the request MUST be split into multiple POST requests with the TLVs spread across the message bodies. The server MUST be prepared to handle the TLVs in any order. If a GET request exceeds the UDP MTU because the max length of the "q" option is exceeded, the request MUST be split into multiple GET requests, each with a subset of the query option. The GET response from a server may not be able to fit all requested TLVs into the response. The server will respond with only the TLVs it is able to fit within the message body. A client SHOULD issue additional GET requests to obtain the missing TLVs. Recommended network MTU will be deployment / technology dependent. For example, an MTU of 1024 is often used for large scale IEEE 802.15.4 mesh networks. 3.4. CSMP Security Model The NMS signs outgoing device messaging. Devices verify the signature to confirm source and integrity of incoming NMS messages. NMS-Device trust is established with an NMS certificate/public key programmed into the device at time of manufacture. Signing TLVs included in the message payload enable signature verification by a device. The Signing TLVs are: Duffy (ed) Expires 27 April 2023 [Page 53] Internet-Draft CoAP Simple Management Protocol October 2022 1. Signature TLV. When included, the Signature TLV MUST be the last TLV in a message payload. The signature is calculated over the first byte of the message payload up to but not including the Signature TLV itself. Unless otherwise specified, the signature MUST be calculated as ECDSA with SHA-256 signature cipher using the signer's (NMS) private key. If the message signature is incorrect, the device MUST ignore the message. 2. SignatureValidity TLV. The SignatureValidity TLV defines the validity period for the message. The SignatureValidity TLV MUST be included when the Signature TLV is included. If the message is received outside the defined validity period, the device MUST ignore the message. If either of the Signing TLVs are missing from a message payload, the device MUST ignore the message. Additional layer 2, 3, or 4 security mechanisms may be utilized to meet the requirements of specific deployment models (Wi-SUN layer 2 security, VPN at layer 3, DTLS at layer 4, etc.). Details of these additional security mechanisms are out of scope of this specification. 3.4.1. Signature Exemption For situations in which a request payload signature adds overhead without improving security, the Signing TLVs may be elided for certain payloads. For example, the overhead of signing each block of a firmware update may be unnecessary as a full image integrity check is performed over the entire file and reported to the NMS. The signature exemptible TLVs are: 1. ImageBlock 2. DescriptionRequest The NMS MAY elide the Signing TLVs provided the request body contains only exemptible TLVs. Otherwise, the Signing TLVs MUST be included. A device MAY accept incoming message payloads without Signing TLVs provided the payload contains only exemptible TLVs. 3.5. Device Groups CSMP groups are used to support multicast messaging to devices. Duffy (ed) Expires 27 April 2023 [Page 54] Internet-Draft CoAP Simple Management Protocol October 2022 A group is uniquely defined by a group-type/group-id pair. A device MAY be a member of multiple group-types, but MUST be a member of only one group-id within a group-type. A device MUST support membership in at least two group types. The NMS assigns a device to a group using the GroupAssign TLV. On initial boot, a device has no group assignments. To be assigned to a device group, a GroupAssign TLV MUST be sent to the device either by a POST request from the NMS or within the response to the device's registration request to the NMS. The NMS removes a device from a group by POST-ing a GroupEvict TLV to the device. If a device's group assignment is changed at the NMS, upon receipt of the next metrics report from the device, the NMS MUST POST a new GroupAssign TLV to the device. Group assignments are not additive. Assignments MUST be replaced upon receipt of a subsequent GroupAssign TLV. A GroupAssign TLV MUST NOT be sent within a multicast message. A GroupEvict TLV MUST NOT be sent within a multicast message. Devices MUST maintain group assignments in durable storage (across power cyclings / reboots). CSMP multicast messages MUST contain a GroupMatch TLV. Upon receipt of a multicast CSMP message: 1. A device MUST process the message if the contained GroupMatch TLV matches a group to which the device is assigned. 2. A device MUST ignore the message if the message does not contain a GroupMatch TLV. 3. A device MUST ignore the message if the GroupMatch TLV does not match a device group assignment. 3.5.1. Reserved Group Types Group type 1 is reserved for configuration. Group type 2 is reserved for firmware. Duffy (ed) Expires 27 April 2023 [Page 55] Internet-Draft CoAP Simple Management Protocol October 2022 3.6. Device TLV Processing Order A device processes message payload TLVs in the following order: 1. If present, the Signature and SignatureValidity TLVs MUST be processed first. 2. If present, the GroupMatch TLV MUST be processed next. 3. The remaining payload TLVs MUST be processed in the order they appear in the payload. 4. TLVs within a payload SHOULD NOT be duplicated. In the case of a duplicate TLV, the last payload instance of TLV MUST be used. 5. The index field of a TLV table entry is used to determine uniqueness of the TLV. TLVs with identical index values MUST be considered to be duplicates (table entry TLVs are identified in Section 3.2.3. 6. TLV specific error handling is described in the OpenAPI definitions. 4. Functional Description This section describes the major operational flows of the CSMP protocol. 4.1. Device Lifecyle States For understanding of CSMP device behavior, it is helpful to consider the NMS' view of device states and state transitions (presented below). The NMS views a device as transitioning through the following states: Figure only available as SVG (PDF and HTML) Figure 1: NMS View of Device State 1. Devices pre-populated into the NMS prior to deployment exist in the Unheard state. 2. Upon receipt of a device registration request, the NMS records the device's presence on the network and the device enters the Registering state. Duffy (ed) Expires 27 April 2023 [Page 56] Internet-Draft CoAP Simple Management Protocol October 2022 3. NMS responds with a registration ACK payload containing configuration for the device. 4. The device transitions to the Up state upon NMS receipt of a device metrics report. 5. If subsequent metrics reports are lost (poor network conditions), the device transitions to the Down state. NMS receipt of a new metrics report transitions the device back to Up state. 4.2. NMS Discovery A device requires the of its NMS. Acquisition of the NMS URL may be accomplished via a variety of means including a DHCP option, pre-deployment administrative configuration setting, etc. The specific mechanism to be used is beyond the scope of this specification. For devices using DHCPv6 address assignment, a device MAY request DHCPv6 option 26484 sub-option 1 to obtain the URL of its NMS. 4.3. Device Registration and Configuration Registration is the messaging flow via which a device announces its entry onto the network and provides a means for the NMS to push configuration information to the device. A device registers with an NMS by issuing a registration request to an NMS. The NMS subsequently responds to reject or accept the registration, with device configuration included in a successful registration response. A device issues a registration request for a variety of reasons: 1. A device MUST register when the device reboots (power cycled or receipt of RebootRequest TLV from the NMS). 2. A device MUST register when its IP address has changed (usually indicating a network re-join). 3. A device MUST register if its mesh parent has changed (mesh networks only). 4. A device MUST register if it detects the NMS IP address has changed. Duffy (ed) Expires 27 April 2023 [Page 57] Internet-Draft CoAP Simple Management Protocol October 2022 5. A device MUST register upon receipt of NMSRedirectRequest TLV from the NMS. This can be caused by the removal of a device from the NMS inventory but the device continues to communicate with a Session ID now unknown to the NMS. A device and NMS implement the registration messaging flow depicted in Figure 2. ┌──────┐ ┌───┐ │Device│ │NMS│ └──┬───┘ └─┬─┘ ╔══╧════════════════════════════════════════════════════════════════════════════╧═══╗ ║Registration Begin ░║ ╚══╤════════════════════════════════════════════════════════════════════════════╤═══╝ │ │ ╔═══════╤══════════════╪════════════════════════════════════════════════════════════════════════════╪═════════════════════╗ ║ LOOP │ │ │ ║ ╟───────┘ │ │ ║ ║ │────┐ │ ║ ║ │ │ [1] Wait random time tBackoff between 0 and tInterval │ ║ ║ │<───┘ │ ║ ║ │ │ ║ ║ │ [2] CON POST msgId = X++ to /r ... │ ║ ║ │ 1. MUST contain DeviceID TLV │ ║ ║ │ 2. MUST contain CurrentTime TLV │ ║ ║ │ 3. MUST contain Device Information TLVs │ ║ ║ │ 4. MAY contain SessionID TLV │ ║ ║ │ 5. MAY contain GroupInfo TLV │ ║ ║ │ 6. MAY contains ReportSubscribe TLV │ ║ ║ │ │ ║ ║ │ ───────────────────────────────────────────────────────────────────────────> ║ ║ │ │ ║ ║ │────┐ │ ║ ║ │ │ [3] Wait remaining time between tBackoff and tInterval │ ║ ║ │<───┘ Double tInterval up to tIntervalMax │ ║ ║ │ │ ║ ║ │ │ ║ ║ │ ╔═════════════════════════════════════════════════════════╗ │ ║ ║ │ ║Continue loop until ACK receipt success and no redirect ░║ │ ║ ║ │ ╚═════════════════════════════════════════════════════════╝ │ ║ ║ │ │ ║ ║ ╔══════╤═════╪════════════════════════════════════════════════════════════════════════════╪═══════════╗ ║ ║ ║ ALT │ NMS redirects │ ║ ║ ║ ╟──────┘ │ │ ║ ║ ║ ║ │ [4] ACK msgID = X ... │ ║ ║ ║ ║ │ 1 Contains NMSRedirectRequest TLV. │ ║ ║ ║ ║ │ 2 MUST contain Signing TLVs. │ ║ ║ ║ ║ │ <─────────────────────────────────────────────────────────────────────────── ║ ║ Duffy (ed) Expires 27 April 2023 [Page 58] Internet-Draft CoAP Simple Management Protocol October 2022 ║ ║ │ │ ║ ║ ║ ║ │ ╔═══════════════╗ │ ║ ║ ║ ║ │ ║Continue loop ░║ │ ║ ║ ║ ╠════════════╪════════════════════════════════════════════════════════════════════════════╪═══════════╣ ║ ║ ║ [NMS no redirect] │ ║ ║ ║ ║ │ [5] ACK msgID = X ... │ ║ ║ ║ ║ │ 1. MAY contain SessionID TLV │ ║ ║ ║ ║ │ 2. MAY contain GroupAssign TLV │ ║ ║ ║ ║ │ 3. MAY contain ReportSubscribe TLV. │ ║ ║ ║ ║ │ 4. MUST contain the Signing TLVs. │ ║ ║ ║ ║ │ <─────────────────────────────────────────────────────────────────────────── ║ ║ ║ ║ │ │ ║ ║ ║ ║ │ ╔════════════════════╗ │ ║ ║ ║ ║ │ ║Break out of loop. ░║ │ ║ ║ ║ ╚════════════╪══╚════════════════════╝════════════════════════════════════════════════════╪═══════════╝ ║ ╚══════════════════════╪════════════════════════════════════════════════════════════════════════════╪═════════════════════╝ │ │ ╔══╧════════════════════════════════════════════════════════════════════════════╧═══╗ ║First Metrics Report ░║ ╚══╤════════════════════════════════════════════════════════════════════════════╤═══╝ │ [6] NON POST msgID = X++ to /c ... │ │ 1. MUST contain SessionID TLV. │ │ 2. MUST contain CurrentTime TLV. │ │ 3. MUST contain list of TLVs speficied by ReportSubscribe TLV │ │ ───────────────────────────────────────────────────────────────────────────> │ │ ╔══╧════════════════════════════════════════════════════════════════════════════╧═══╗ ║Registration Complete ░║ ╚══╤════════════════════════════════════════════════════════════════════════════╤═══╝ ╔══╧════════════════════════════════════════════════════════════════════════════╧═══╗ ║Continuing Metrics Reports ░║ ╚══╤════════════════════════════════════════════════════════════════════════════╤═══╝ │ │ ╔═══════╤════╪════════════════════════════════════════════════════════════════════════════╪═══════════╗ ║ LOOP │ │ │ ║ ╟───────┘ │ │ ║ ║ │────┐ │ ║ ║ │ │ [7] Wait random time tMetricsBackoff between 0 and │ ║ ║ │<───┘ tMetricsInterval defined by ReportSubscribe │ ║ ║ │ │ ║ ║ │ │ ║ ║ │ [8] NON POST msgId = X++ to /c ... │ ║ ║ │ 1. MUST contain Session ID TLV │ ║ ║ │ 2. MUST contain CurrentTime TLV │ ║ ║ │ 3. MUST contain the list of TLVS specified by previous ReportSubscribe TLV.│ ║ ║ │ ───────────────────────────────────────────────────────────────────────────> ║ ║ │ │ ║ ║ │────┐ │ ║ Duffy (ed) Expires 27 April 2023 [Page 59] Internet-Draft CoAP Simple Management Protocol October 2022 ║ │ │ [9] Wait remaining time between tMetricsBackoff and │ ║ ║ │<───┘ tMetrics Interval │ ║ ║ │ │ ║ ╚════════════╪════════════════════════════════════════════════════════════════════════════╪═══════════╝ ┌──┴───┐ ┌─┴─┐ │Device│ │NMS│ └──────┘ └───┘ Figure 2: Device Registration, Configuration, and Metrics 4.3.1. Device Registration Request A device MUST implement two configurable parameters used to control the registration process, initially set at manufacture time, and MUST be maintained in durable storage. 1. tIntervalMin defaults to 300 seconds (5 minutes). Also configurable via TLV 42/regIntervalMin field. 2. tIntervalMax defaults to 3600 seconds (1 hour). Also configurable via TLV 42/regIntervalMax field. A device MUST issue registration requests using the following algorithm. Set tInterval = tIntervalMin. Wait an initial period between 0 and tInterval seconds. Do { 1. Wait tBackoff seconds, where tBackoff is a random interval between tInterval/2 and tInterval seconds. A tBackoff value in the latter half of the interval ensures a minimum time between successive registration attempts. 2. Send a new CoAP CON POST request message to NMS /r. The message payload MUST contain the registration TLVs described in section 3.3.1.2. 3. Wait the remaining (tInterval – tBackoff) seconds. 4. Set tInterval to 2 * tInterval. If tInterval is greater than tIntervalMax, set tInterval to tIntervalMax. } While the device has not received an ACK to its registration POST. An example execution of a full registration POST retry sequence is presented in Section 8. If the device receives an ACK message with CoAP response code 2.03 (valid) from the NMS at any time before the device's next registration POST, the TLVs within the ACK message MUST be processed. Duffy (ed) Expires 27 April 2023 [Page 60] Internet-Draft CoAP Simple Management Protocol October 2022 4.3.2. Registration POST Payload The following TLVs MUST be included in the device registration POST to the NMS: 1. DeviceID (primary identifier of the device). 2. CurrentTime (used to validate device local time). Previously registered devices SHOULD already have (durably stored) values for the Session ID, GroupInfo,and ReportSubscribe TLVs and MUST include these TLVs in the device registration POST to the NMS: 1. SessionID 2. GroupInfo (one per group) 3. ReportSubscribe The following Device Information TLVs MUST be included in the registration POST: 1. HardwareDesc 2. InterfaceDesc (one per interface) 3. IPAddress (one per address) 4. NMSStatus (reason for the registration operation) 5. WPANStatus 6. RPLSettings Note that the SessionID, GroupAssign, and ReportSubscribe TLV set is considered to be generic device Configuration. The Configuration TLV set is technology specific and MAY be extended with additional technology specific TLVs (beyond the scope of this specification). 4.3.3. NMS Registration Response Upon receipt of a registration request, the NMS looks up the information for the device identified by DeviceID to confirm correctness of the request. See Section 3.2.2 for details of DeviceID and SessionID validation and related error response codes. Duffy (ed) Expires 27 April 2023 [Page 61] Internet-Draft CoAP Simple Management Protocol October 2022 If the device is found in inventory, authorized to register, and all other registration request content is confirmed to be valid, the NMS MUST send an ACK response message with response code 2.03(Valid)to the device. The ACK takes one of two forms, depending upon whether or not the NMS will redirect the device to another NMS. In the case where the NMS is not redirecting, the response body to a valid registration request contains the following TLVs: 1. SessionID MUST be elided from the ACK if the SessionID contained in the registration request is correct, otherwise the correct SessionID TLV MUST be included in the ACK. 2. GroupAssign MUST be elided from the ACK if the GroupAssign contained in the registration request is correct, otherwise the correct GroupAssign TLV MUST be included in the ACK. 3. ReportSubscribe MUST be elided from the ACK if the ReportSubscribe contained in the registration request is correct, otherwise the correct ReportSubscribe TLV MUST be included in the ACK. 4. Signing TLVs MUST be included. In the case where the NMS is redirecting, the response body to a valid registration request contains the following TLVs: 1. NMSRedirectRequest MUST be included. 2. Signing TLVs MUST be included. When the response contains a SessionID TLV, the device MUST durably store this TLV and SessionID TLV MUST be included in all future CSMP requests to the NMS. When the response contains a GroupAssign TLV, the device MUST durably store the group-id (overwriting any other stored group-id for the same group-type) and MUST use the new GroupAssign values for comparison with all future receipt of GroupMatch TLVs. When the response contains a ReportSubscribe TLV, the device MUST begin reporting the indicated metrics TLVs (ignoring any TLVs requested by the ReportSubscribe which are unknown to the device). The NMS includes the NMSRedirectRequest TLV in a registration response to request the device register with an alternate NMS instance (load balancing, etc.). Upon receipt of this TLV, the device MUST cease registration attempts with the original NMS and Duffy (ed) Expires 27 April 2023 [Page 62] Internet-Draft CoAP Simple Management Protocol October 2022 start the registration process with the NMS indicated in the NMSRedirectRequest TLV. If registration succeeds with this new NMS, all subsequent device CSMP messaging MUST be directed to this new NMS. Note that device receipt of NMSRedirectRequest TLV is a one- time redirect and not persisted across device restarts. 4.3.4. Registration Complete The NMS considers device registration to be complete when all of the following conditions are met: 1. The registration ACK to the device indicates code 2.03 (Valid) and message ID match is confirmed as described in CoAP. 2. The ACK response body does not contain an NMSRedirectRequest TLV. 3. The first metrics report from the device is received by the NMS. 4.4. Device Metrics Reporting Upon receipt of a ReportSubscribe TLV, a device configures as many as two metrics reports: 1. A primary metrics report using the interval and TLV ID set. 2. A secondary metrics report using the heartbeat interval and heartbeat TLV ID set. The primary metrics report MUST be used for mains powered devices (with the secondary report disabled). To conserve power, metrics reporting for low power devices MAY be split across primary and secondary reports, with the primary report configured to provide TLVs needed at more frequent interval and the secondary configured for TLVs required at a more relaxed interval. A device configures metrics parameters to control the device's primary metrics report as follows: 1. tMetricsInterval (how often a device MUST report its metrics) is typically set between 5 minutes and 8 hours (depends on application requirements). Designated by the interval field of the ReportSubscribe TLV. 2. tlvList (the list of TLVs the device MUST report) is designated by the tlvId field of the ReportSubscribe TLV. A device configures metrics parameters to control a device's secondary metrics report as follows: Duffy (ed) Expires 27 April 2023 [Page 63] Internet-Draft CoAP Simple Management Protocol October 2022 1. tMetricsInterval is designated by the intervalHeartBeat field of the ReportSubscribe TLV. 2. tlvList is designated by the tlvIdHeartBeat field of the ReportSubscribe TLV. The TLV content of the primary and secondary metrics reports are deployment and application specific. For example, the primary metrics report for a 6LoWPAN, mains-powered mesh node might be configured as: 1. InterfaceMetrics 2. GroupInfo 3. FirmwareImageInfo 4. Uptime 5. LowpanPhyStats 6. DifServMetrics 7. ReportSubscribe TLV content of the secondary metrics report is similarly application specific and beyond the scope of this specification. For each configured metrics report, a device MUST commence reporting immediately after receipt of a successful registration ACK by sending a NON POST to /c containing the following TLVs: 1. SessionID 2. CurrentTime 3. The TLVs from tlvList. The entirety of all table entries MUST be included. Following the initial metrics report, the device MUST implement the following algorithm for subsequent metric reports (for both primary and secondary report): Duffy (ed) Expires 27 April 2023 [Page 64] Internet-Draft CoAP Simple Management Protocol October 2022 Send a new CoAP NON POST to /c with the required metrics TLVs. Wait an initial random interval between 0 and tMetricsInterval seconds. Do { 1. Wait tMetricsBackoff seconds, where tMetricsBackoff is random value between tMetricsInterval/2 and tMetricsInterval seconds. 2. Send a new CoAP NON POST message to /c with the required metrics TLVs 3. Wait the remaining (tMetricsInterval – tMetricsBackoff) seconds so that the full tMetricsInterval has expired. } While the device has a valid IP address. 4.5. Device Firmware Update CSMP defines a device firmware update process optimized for LPWANs. A key aspect of this process is the separation of image placement on a device from activation (execution) of the image on the device. The device firmware update process consists of three sub-flows: 1. Firmware download. A new image is placed on one or more members of a device group. 2. Image load. Activate an image on one or more members of a device group at a scheduled time. 3. Set backup image. Optional designation of an image to be used when load of all other images fails. A device should implement the following mechanisms in support of firmware update: 1. It is RECOMMENDED that vendors implement digital signing of images prior to image release to production. 2. It is RECOMMENDED that a device implement a secure bootloader which (upon device receipt of a LoadRequest TLV or at device power-up) validates the activated image's signature, loads the image from durable storage into operating memory, and transfers execution to the image. Specific details of image signing and the secure bootloader are left to the vendor beyond the scope of this specification. 3. A device MUST be capable of storing at least two firmware images: the running image and at least one additional image. 4. It is RECOMMENDED that a device also support a backup image. A device boots into the backup image when the device is unable to boot into any other image. Duffy (ed) Expires 27 April 2023 [Page 65] Internet-Draft CoAP Simple Management Protocol October 2022 5. A device MUST be capable of scheduling an image load (activation) at a specific future time (i.e. the device must maintain a time source). 4.5.1. Firmware Image Format A CSMP firmware image file consists of three main parts: a CSMP defined image header, the vendor defined image binary, and the vendor defined image signature (as depicted below). +================+============+=====================================+ | Field | Size | Description | | | (octets) | | +================+============+=====================================+ | | | Begin Header | +----------------+------------+-------------------------------------+ | Header Version | 4 | 32 bit unsigned integer which | | | | MUST be set to 2. | +----------------+------------+-------------------------------------+ | Header Length | 4 | 32 bit unsigned integer which | | | | MUST be set to 256. | +----------------+------------+-------------------------------------+ | App Rev Major | 4 | Vendor specific 32 bit unsigned | | | | integer which is set to indicate | | | | the major revision number of the | | | | application image. | +----------------+------------+-------------------------------------+ | App Rev Minor | 4 | Vendor specific 32 bit unsigned | | | | integer which is set to indicate | | | | the minor revision number of the | | | | application image. | +----------------+------------+-------------------------------------+ | App Build | 4 | Vendor specific 32 bit unsigned | | | | integer which is set to indicate | | | | the build of the application | | | | image. | +----------------+------------+-------------------------------------+ | App Length | 4 | 32 bit unsigned integer which | | | | MUST be set to the octet length | | | | of the Header + Image Binary | | | | field. | +----------------+------------+-------------------------------------+ | App Name | 32 | Vendor specific 32 octet string | | | | which is set to indicate the | | | | name of the application. | +----------------+------------+-------------------------------------+ | App SCC Branch | 32 | Vendor specific 32 octet string | | | | which is set to indicate the | Duffy (ed) Expires 27 April 2023 [Page 66] Internet-Draft CoAP Simple Management Protocol October 2022 | | | source code control system | | | | branch ID. | +----------------+------------+-------------------------------------+ | App SCC Commit | 8 | Vendor specific 8 octet string | | | | which is set to indicate the | | | | source code control system | | | | commit ID. | +----------------+------------+-------------------------------------+ | App SCC Flags | 4 | Vendor specific 32 bit unsigned | | | | integer which is set to indicate | | | | the source code control system | | | | build flags. | +----------------+------------+-------------------------------------+ | App Build Date | 16 | Vendor specific 16 octet string | | | | which is set to indicate the | | | | build date and time of the | | | | application image. | +----------------+------------+-------------------------------------+ | hwid | 32 | 32 octet field which is | | | | RECOMMENDED to be set to a | | | | concatenation of a unique | | | | manufacturer ID and product | | | | model identifier. | +----------------+------------+-------------------------------------+ | sub_hwid | 32 | 32 octet field which MAY be set | | | | for a manufacturer specific | | | | purpose, or functionally elided | | | | by filling with 0x20 (ASCII | | | | space character). | +----------------+------------+-------------------------------------+ | kernel_rev | 16 | 16 octet field which MAY be set | | | | for a manufacturer specific | | | | purpose, or functionally elided | | | | by filling with 0x20 (ASCII | | | | space character). | +----------------+------------+-------------------------------------+ | sub_kernel_rev | 16 | 16 octet field which MAY be set | | | | for a manufacturer specific | | | | purpose, or functionally elided | | | | by filling with 0x20 (ASCII | | | | space character). | +----------------+------------+-------------------------------------+ | Reserved | 44 | Pad to 256 octets, octets MUST | | | | be set to 0. | +----------------+------------+-------------------------------------+ | | | End Header, Begin Image | +----------------+------------+-------------------------------------+ | Image Binary | Variable | Vendor specific image data. | Duffy (ed) Expires 27 April 2023 [Page 67] Internet-Draft CoAP Simple Management Protocol October 2022 +----------------+------------+-------------------------------------+ | | | End Image, Begin Signature | +----------------+------------+-------------------------------------+ | Signature | Vendor | Calculated over entire content | | Variable | specific | of this structure except the | | | image | signature and pad fields. | | | signature. | | +----------------+------------+-------------------------------------+ | | | End Signature, Begin Pad | +----------------+------------+-------------------------------------+ | Pad | Variable | Optional pad field to enable | | | | image to fill vendor specific | | | | flash memory boundary. When | | | | present, octets MUST be set to | | | | 0xFF. | +----------------+------------+-------------------------------------+ Table 1: Firmware Image Format All multi-octet fields are encoded as little-endian. 4.5.2. Firmware Download An NMS implements the messaging flow depicted in Figure 3 and Figure 4 to download an image to a group of devices. Unicast distribution is also supported, with the difference being use of unicast addresses, omission of the GroupMatch TLV and omission of the 'a' query option. Figure only available as SVG (PDF and HTML) Figure 3: Firmware Download Figure only available as SVG (PDF and HTML) Figure 4: Firmware Download (cont) A firmware download begins with the NMS informing the device group of the meta-data of an image the NMS wishes to download, and the devices subsequently informing the NMS of the images already loaded on the devices. The NMS MUST issue a NON POST to /c configured as follows: 1. A GroupMatch TLV MUST be included for the desired group. Duffy (ed) Expires 27 April 2023 [Page 68] Internet-Draft CoAP Simple Management Protocol October 2022 2. The 'a' option MUST be specified to randomize subsequent device responses. 3. The request MAY contain an 'r' option to redirect the subsequent TransferResponse. 4. The request MUST contain a TranferRequest TLV (meta-data for the file to be downloaded) 5. The request MUST contain the Signing TLVs. Devices receiving a TransferRequest message: 1. MUST process the Signing TLVs and the GroupMatch TLV as described in section 2.6. 2. MUST wait the specified period when the 'a" option is included. 3. MUST issue a NON POST request to /c which MUST contain the TransferResponse TLV. The MUST be overridden by the 'r' option if specified. The NMS MUST proceed with image block transfer when at least one member of the target device group indicates Response Code of OK in the TransferResponse TLV. Otherwise, the transfer MUST be aborted. Images are often multiple 100s of Kilobytes in size and likely require fragmentation into multiple blocks (N) to be transferred to a device. For the transfer of each image block, the NMS MUST issue a NON POST to /c configured as follows: 1. The request MUST contain the GroupMatch TLV for the desired group. 2. The request MUST contain an ImageBlock TLV 3. The request MAY contain the Signing TLVs. To determine image download progress, the NMS MUST periodically include a DescriptionRequest TLV, requesting the FirmwareImageInfo TLV, in the image block request. It is RECOMMENDED that the NMS request the FirmwareImageInfo TLV at 10% increments of the image download. The NMS MUST request the FirmwareImageInfo TLV with the transfer of the last block of the image. Devices receiving the image block request message: Duffy (ed) Expires 27 April 2023 [Page 69] Internet-Draft CoAP Simple Management Protocol October 2022 1. MUST process the Signing TLVs and GroupMatch TLVs as described in section 2.6. 2. MUST cache the image block for final image assembly. 3. When the FirmwareImageInfo TLV is requested, the device MUST wait the specified period when the 'a' option is included and MUST issue a NON POST request to /c which MUST contain the FirmwareImageInfo TLV (meta-data for files loaded on the device). The MUST be overridden by the 'r' option if specified. Receipt of the final FirmwareImageInfo TLV enables the NMS to confirm the integrity of the completely downloaded image. 4.5.3. Image Activation The messaging flow for scheduling image activation across a group of devices and cancelling a scheduled image activation are depicted in Figure 5 and described below. Unicast activation is also supported, with the difference being use of unicast addresses, omission of the GroupMatch TLV and omission of the 'a' query option. Figure only available as SVG (PDF and HTML) Figure 5: Image Activation 4.5.3.1. Image Load An NMS implements the following message flow to command devices to designate an image as the active executable and the time at which the image is to be activated. The NMS MUST issue a NON POST to /c configured as follows: 1. A GroupMatch TLV MUST be included for the desired group. 2. The 'a' option MUST be specified to randomize subsequent device responses. 3. The request MAY contain an 'r' option to redirect the subsequent LoadResponse. 4. The request MUST contain a LoadRequest TLV (designating the image and time at which the image is to be activated). 5. The request MUST contain the Signing TLVs. Duffy (ed) Expires 27 April 2023 [Page 70] Internet-Draft CoAP Simple Management Protocol October 2022 Devices receiving a LoadRequest message: 1. MUST process the Signing TLVs and GroupMatch TLVs as described in section 2.6. 2. MUST wait the specified period when the 'a" option is included. 3. MUST issue a NON POST request to /c which MUST contain the LoadResponse TLV (indicating success or reason for failure). The MUST be overridden by the 'r' option if specified. 4.5.3.2. Cancel Image Load An NMS implements the following message flow to cancel a previously scheduled image activation. The NMS MUST issue a NON POST to /c configured as follows: 1. A GroupMatch TLV MUST be included for the desired group. 2. The 'a' option MUST be specified to randomize subsequent device responses. 3. The request MAY contain an 'r' option to redirect the subsequent CancelLoadResponse. 4. The request MUST contain a CancelLoadRequest TLV (designating the image load to be cancelled). 5. The request MUST contain the Signing TLVs. Devices receiving a CancelLoadRequest message: 1. MUST process the Signing TLVs and GroupMatch TLVs as described in section 2.6. 2. MUST wait the specified period when the 'a" option is included. 3. MUST issue a NON POST request to /c which MUST contain the CancelLoadResponse TLV (indicating success or reason for failure). The MUST be overridden by the 'r' option if specified. 4.5.4. Set Backup Image An NMS implements the following message flow to command a device to designate a stored image as the backup image. Duffy (ed) Expires 27 April 2023 [Page 71] Internet-Draft CoAP Simple Management Protocol October 2022 ┌───────┐ ┌───────┐ ┌───┐ │Device1│ │Device2│ │NMS│ └───┬───┘ └───┬───┘ └─┬─┘ │ │[1] NON POST to /c with options a, r │ │ │1. MUST contain GroupMatch TLV │ │ │2. MUST contain SetBackupRequest TLV │ │ │3. MUST contain Signing TLVs │ │ │<─────────────────────────────────────│ │ │ │ ────┐ │ │ │ [2] Set the specified image│ │ <───┘ as the backup image │ │ │ │ │ │ │ │ ────┐ │ │ │ [3] Set the specified image │ │ <───┘ as the backup image │ │ │ │ │ │ ╔═════╧════════════════════════════════╧═════╗ │ ║Wait random delay based on the "a" option. ░║ │ ╚═════╤════════════════════════════════╤═════╝ │ │ │[4] NON POST to /c │ │ │1. MUST contain SetBackupResponse TLV │ │ │─────────────────────────────────────>│ │ │ │ │ [5] NON POST to /c │ │ 1. MUST contain SetBackupResponse TLV │ │──────────────────────────────────────────────────────────────────────>│ ┌───┴───┐ ┌───┴───┐ ┌─┴─┐ │Device1│ │Device2│ │NMS│ └───────┘ └───────┘ └───┘ Figure 6: Set Backup Image The NMS MUST issue a NON POST to /c configured as follows: 1. A GroupMatch TLV MUST be included for the desired group. 2. The 'a' option MUST be specified to randomize subsequent device responses. 3. The request MAY contain an 'r' option to redirect the subsequent SetBackupResponse. 4. The request MUST contain a SetBackupRequest TLV (designating the image load to be cancelled). Duffy (ed) Expires 27 April 2023 [Page 72] Internet-Draft CoAP Simple Management Protocol October 2022 5. The request MUST contain the Signing TLVs. Devices receiving a SetBackupRequest message: 1. MUST process the Signing TLVs and GroupMatch TLVs as described in section 2.6. 2. MUST wait the specified period when the 'a" option is included. 3. MUST issue a NON POST request to /c which MUST contain the SetBackupResponse TLV (indicating success or reason for failure). The MUST be overridden by the 'r' option if specified. 4.6. Device Commands Many TLVs served by a device are used by the NMS to interrogate the device for configuration state and operational status. There are, however, several TLVs which direct a device to execute internal actions. Examples of these TLVs are PingRequest and RebootRequest. Usage of a command TLVs is illustrated with the following PingRequest example directed at a single device. The NMS MUST issue a NON POST to /c configured as follows: 1. A GroupMatch TLV MUST NOT be included for the designed device. 2. The request MAY contain an 'r' option to redirect the subsequent PingResponse. 3. The request MUST contain a PingRequest TLV (describing the Ping action to be performed). 4. The request MUST contain the Signing TLVs. Devices receiving a PingRequest message: 1. MUST process the Signing TLVs as described in section 2.6. 2. MUST begin the requested Ping operation. The NMS will subsequently interrogate the device with one or more GET requests to the device for the PingResponse TLV. Note the specific messaging exchanges vary per the definition of each commands. Details are provided within Section 3.3.2.2. Duffy (ed) Expires 27 April 2023 [Page 73] Internet-Draft CoAP Simple Management Protocol October 2022 5. Security Considerations Threat models and appropriate mitigations are highly specific to individual CSMP/LPWAN deployments. CSMP defines only the NMS signing of outgoing Device messaging using an NMS private key (for Device commands and firmware load). Signing TLVs included in the message payload enable signature verification by a Device using an NMS signing certificate\public key. The verified signature provides source authentication integrity check of the message incoming to the Device. Lifecycle management of the public/ private keypair is out of scope of the specification. Where additional security mechanisms are needed (source and integrity checking of Device to NMS communication, confidentially of CSMP messaging, authentication and authorization of CSMP actors, replay protection), additional layer 2, 3, or 4 security mechanisms are utilized to meet security requirements of a specific deployment. Examples include: 1. Layer 2 802.1X/EAP-TLS is used to provide mutual authentication of Device and NMS as well as distribution of key material to be used with IEEE 802.15.4 frame security (providing confidentially, source authentication, and replay protection). 2. Layer 3 VPN may be used to provide confidentially, source authentication, and message integrity for messaging between Device and NMS. 3. Layer 4 DTLS may be used to provide confidentially, source authentication, and message integrity for messaging between Device and NMS. Specific usage profile details for these additional security mechanisms are out of scope of this specification. 6. IANA Considerations This document requires no IANA actions. 7. Contributors This work is based upon the considerable efforts of CSMP's original designer Gilman Tolle (with contributions from Phil Buonadonna, and Sumit Rangwala). The Editor further acknowledges the contributions made to the content of this document by the following individuals: 1. Jasvinder Bhasin, Cisco Systems, Inc. (jassi@cisco.com) Duffy (ed) Expires 27 April 2023 [Page 74] Internet-Draft CoAP Simple Management Protocol October 2022 2. Chris Hett, Landis+Gyr (Chris.Hett@landisgyr.com) 3. Johannes van der Horst, MMB Networks (johannes.vanderhorst@mmbresearch.com) 4. Klaus Hueske, Renesas (Klaus.Hueske@renesas.com). 5. Hideyuki Kuribayashi, ROHM Semiconductor (Hideyuki.Kuribayashi@mnf.rohm.co.jp) 6. Kit-Mui Leung, Cisco Systems, Inc. (kml@cisco.com) 7. Huimin She, Cisco Systems, Inc. (hushe@cisco.com) 8. Li Zhao, Cisco Systems, Inc. (liz3@cisco.com) 8. Appendix A Registration Retry Example 1. Device powers up. 2. Device sets interval for 0 to 5 minutes. 3. Device wait a random time between 2.5 and 5 minutes. 4. Device sends a confirmable registration POST message. 5. Device waits the rest of the interval until 5 minutes have passed. 6. Device waits a random time between 5 and 10 minutes. 7. Device sends the registration message again, with a new CoAP message ID. 8. Device waits the rest of the interval until 10 minutes have passed. 9. Device waits a random time between 10 and 20 minutes. 10. Device sends the registration message again, with a new CoAP message ID. 11. Device waits the rest of the interval until 20 minutes have passed. 12. Device waits a random time between 20 and 40 minutes. Duffy (ed) Expires 27 April 2023 [Page 75] Internet-Draft CoAP Simple Management Protocol October 2022 13. Device sends the registration message again, with a new CoAP message ID. 14. Device waits the rest of the interval until 40 minutes have passed. 15. Device waits a random time between 40 and 60 minutes. 16. Device sends the registration message again, with a new CoAP message ID. 17. Device waits the rest of the interval until 60 minutes have passed. 18. Repeat steps 15, 16, and 17 forever. 9. Appendix B Change Log 9.1. draft 00 to 01 1. Abstract reworded to clarify multi-vendor aspects of CSMP. 2. Introduction reworded to clarify multi-vendor aspects of CSMP. 3. OpenAPI definitions are placed in-line. 4. Protocol Buffer Definitions are placed in-line. 5. Due to IETF author limits, all authors except the Editor have been credited in the Contributors section. 9.2. draft 01 to 02 1. "Cisco" added to title as requested. 2. There are no IP disclosures to be made for this work. This point has been confirmed by Cisco legal. 9.3. draft 02 to 03 1. Trial attempt to convert Figures 2 and 6 to ASCII Art using PlantUML. 10. Normative References Duffy (ed) Expires 27 April 2023 [Page 76] Internet-Draft CoAP Simple Management Protocol October 2022 [CSMPCOMP] "CSMP Components", n.d., . [CSMPDEV] "CSMP Device Interface", n.d., . [CSMPMSG] "CSMP Payload Definitions", n.d., . [CSMPNMS] "CSMP NMS Interface", n.d., . [OPENAPI] "OpenAPI Specification v3.0.0", n.d., . [PB] "Protocol Buffers Version 3", n.d., . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . Author's Address Paul Duffy Cisco Systems, Inc. Email: paduffy@cisco.com Duffy (ed) Expires 27 April 2023 [Page 77]