TR-369 – The User Services Platform
Issue: 1 Amendment 3
Issue Date: June 2023
List of Figures
- USP Agent and Controller Architecture
- Receiving a X.509 Certificate
- Example: USP Request/Response over the CoAP MTP
- WebSocket Session Handshake
- USP Request using a WebSocket Session
- USP over STOMP Architecture
- USP over MQTT Architecture
- MQTT Packets
- Unix Domain Socket Binding
- UNIX Domain Socket Frame with Handshake Message
- UNIX Domain Socket Frame with USP Record Message
- Processing of Received USP Records
- E2E Segmentation and Reassembly
- TLS Session Handshake
- A successful request/response sequence
- A failed request/response sequence
- Operate Message Flow for Synchronous Operations
- Operate Message Flow for Asynchronous Operations
- Receiving a USP Record
- USP Record without USP Layer Secure Message Exchange
- Sending a USP Record
- Checking a Certificate
- Determining the Role
- Trusted Broker with Received Record
- Trusted Broker Sending a Record
- Deployment Unit State Diagram
- Execution Unit State Diagram
- Possible Multi-Execution Environment Implementation
- Execution Environment State Diagram
- Example of MTP Proxy in LAN with WAN Controller
- CoAP-STOMP MTP Proxy Example Flow
- IoT Data Model
- IoT individual device models
- IoT proxied device model
- IoT threshold trigger sensitivity
- IoT threshold trigger hold time
- IoT threshold trigger rest time
- IoT threshold trigger minimum duration
- Software Modularization Use Cases
List of Tables
Notice
The Broadband Forum is a non-profit corporation organized to create guidelines for broadband network system development and deployment. This Technical Report has been approved by members of the Forum. This Technical Report is subject to change. This Technical Report is owned and copyrighted by the Broadband Forum, and all rights are reserved. Portions of this Technical Report may be owned and/or copyrighted by Broadband Forum members.
Intellectual Property
Recipients of this Technical Report are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of this Technical Report, or use of any software code normatively referenced in this Technical Report, and to provide supporting documentation.
Terms of Use
1. License
Broadband Forum hereby grants you the right, without charge, on a perpetual, non-exclusive and worldwide basis, to utilize the Technical Report for the purpose of developing, making, having made, using, marketing, importing, offering to sell or license, and selling or licensing, and to otherwise distribute, products complying with the Technical Report, in all cases subject to the conditions set forth in this notice and any relevant patent and other intellectual property rights of third parties (which may include members of Broadband Forum). This license grant does not include the right to sublicense, modify or create derivative works based upon the Technical Report except to the extent this Technical Report includes text implementable in computer code, in which case your right under this License to create and modify derivative works is limited to modifying and creating derivative works of such code. For the avoidance of doubt, except as qualified by the preceding sentence, products implementing this Technical Report are not deemed to be derivative works of the Technical Report.
2. NO WARRANTIES
THIS TECHNICAL REPORT IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT AND ANY IMPLIED WARRANTIES ARE EXPRESSLY DISCLAIMED.
3. THIRD PARTY RIGHTS
Without limiting the generality of Section 2 above, BROADBAND FORUM ASSUMES NO RESPONSIBILITY TO COMPILE, CONFIRM, UPDATE OR MAKE PUBLIC ANY THIRD PARTY ASSERTIONS OF PATENT OR OTHER INTELLECTUAL PROPERTY RIGHTS THAT MIGHT NOW OR IN THE FUTURE BE INFRINGED BY AN IMPLEMENTATION OF THE TECHNICAL REPORT IN ITS CURRENT, OR IN ANY FUTURE FORM.
All copies of this Technical Report (or any portion hereof) must include the notices, legends, and other provisions set forth on this page.
Issue History
| Issue Number | Changes |
|---|---|
Release contains specification for the User Services Platform 1.0 Corresponds to TR-181 Issue 2 Amendment 12 |
|
| Release 1.0.1 |
|
| Release 1.0.2 |
|
Release contains specification for the User Services Platform 1.1
Corresponds to TR-181 Issue 2 Amendment 13 |
|
| Release 1.1.1 | Regenerated data model HTML using fixed version of the BBF report tool |
| Release 1.1.2 | Clarifies several examples, requirements, and error types |
| Release 1.1.3 | Corresponds to TR-106 Amendment 10 and TR-181 Issue 2 Amendment 14 |
| Release 1.1.4 | Corresponds to TR-181 Issue 2 Amendment 14 Corrigendum 1 |
Release contains specification for the User Services Platform 1.2
Corresponds to TR-106 Amendment 11 and TR-181 Issue 2 Amendment 15 |
|
Release contains the specification for the User Services Platform 1.3
|
Editors
| Name | Company | Role | |
|---|---|---|---|
| Barbara Stark | AT&T |<EMAIL_ADDRESS>| Editor/USP Project Lead |
| Tim Spets | Assia |<EMAIL_ADDRESS>| Editor/USP Project Lead |
| Jason Walls | QA Cafe, LLC |<EMAIL_ADDRESS>| Editor/Broadband User Services Work Area Director |
| John Blackford | Commscope |<EMAIL_ADDRESS>| Editor/Broadband User Services Work Area Director |
Acknowledgments
| Name | Company | |
|---|---|---|
| Jean-Didier Ott | Orange |<EMAIL_ADDRESS>|
| Timothy Carey | Nokia |<EMAIL_ADDRESS>|
| Steven Nicolai | Arris |<EMAIL_ADDRESS>|
| Apostolos Papageorgiou | NEC |<EMAIL_ADDRESS>|
| Mark Tabry |<EMAIL_ADDRESS>| |
| Klaus Wich | Huawei |<EMAIL_ADDRESS>|
| Daniel Egger | Axiros |<EMAIL_ADDRESS>|
| Bahadir Danisik | Nokia |<EMAIL_ADDRESS>|
| William Lupton | Broadband Forum |<EMAIL_ADDRESS>|
| Matthieu Anne | Orange |<EMAIL_ADDRESS>|
| Thales Fragoso | Axiros |<EMAIL_ADDRESS>|
1 Introduction
1.1 Executive Summary
This document describes the architecture, protocol, and data model that build an intelligent User Services Platform. It is targeted towards application developers, application service providers, vendors, consumer electronics manufacturers, and broadband and mobile network providers who want to expand the value of the end user’s network connection and their connected devices.
The term “connected device” is a broad one, applying to the vast array of network connected devices, consumer electronics, and computing resources that today’s consumers are using at an increasing rate. With the advent of “smart” platforms (phones, tablets, and wearables) plus the emerging Internet of Things, the number of connected devices the average user or household contains is growing by several orders of magnitude.
In addition, users of the fixed and mobile broadband network are hungry for advanced broadband and intelligent cloud services. As this desire increases, users are turning towards over-the-top providers to consume the security, entertainment, productivity, and storage applications they want.
These realities have created an opportunity for consumer electronics vendors, application developers, and broadband and mobile network providers. These connected devices and services need to be managed, monitored, troubleshot, and controlled in an easy to develop and interoperable way. A unified framework for these is attractive if we want to enable providers, developers, and vendors to create value for the end user. The goal should be to create a system for developing, deploying, and supporting these services for end users on the platform created by their connectivity and components, that is, to be able to treat the connected user herself as a platform for applications.
To address this opportunity, use cases supported by USP include:
- Management of IoT devices through re-usable data model objects.
- Allowing the user to interact with their devices and services using customer portals or control points on their own smart devices.
- The ability to deploy and manage containerized microservices for end-users via software modulization and USP-enabled applications.”
- The ability to have both the application and network service provider manage, troubleshoot, and control different aspects of the services they are responsible for, and enabling provider partnerships.
- Providing a consistent user experience from mobile to home.
- Simple migration from the CPE WAN Management Protocol [37] (CWMP) – commonly known by its document number, “TR-069” – through use of the same data model and data modeling tools.
1.2 Purpose and Scope
1.2.1 Purpose
This document provides the normative requirements and operational description of the User Services Platform (USP). USP is designed for consumer electronics/IoT, home network/gateways, smart Wi-Fi systems, and deploying and managing other value-added services and applications. It is targeted towards developers, application providers, and network service providers looking to deploy those products.
1.2.2 Scope
This document identifies the USP:
- Architecture
- Data model interaction
- Record structure, syntax, and rules
- Message structure, syntax, and rules
- Bindings that allow specific protocols to carry USP Records in their payloads
- Discovery and advertisement mechanisms
- Extensions for proxying, software module management, device modularization, firmware lifecycle management, bulk data collection, device-agent association, and an IoT theory of operations.
- Security credentials and logic
- Encryption mechanisms
Lastly, USP makes use of and expands the Device:2 Data Model [39]. While particular Objects and Parameters necessary to the function of USP are mentioned here, their normative description can be found in that document.
1.3 References and Terminology
1.3.1 Conventions
In this specification, several words are used to signify the requirements of the specification. These words are always capitalized. More information can be found in RFC 2119 [10] for key words defined there. Additional key words defined in the context of this specification are DEPRECATED and OBSOLETED.
MUST
This word, or the term “REQUIRED”, means that the definition is an absolute requirement of the specification.
MUST NOT
This phrase means that the definition is an absolute prohibition of the specification.
SHOULD
This word, or the term “RECOMMENDED”, means that there could exist valid reasons in particular circumstances to ignore this item, but the full implications need to be understood and carefully weighed before choosing a different course.
SHOULD NOT
This phrase, or the phrase “NOT RECOMMENDED” means that there could exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications need to be understood and the case carefully weighed before implementing any behavior described with this label.
MAY
This word, or the term “OPTIONAL”, means that this item is one of an allowed set of alternatives. An implementation that does not include this option MUST be prepared to inter-operate with another implementation that does include the option.
DEPRECATED
This word refers to a requirement or section of this specification that is defined and valid in the current version of this specification but is not strictly necessary. This may be done for various reasons, such as irreparable problems being discovered or another more useful method being defined to accomplish the same purpose. When this word is applied to a requirement, it takes precedence over any normative language in the DEPRECATED requirement. DEPRECATED requirements SHOULD NOT be implemented. When this word is used on a section, it means the entirety of the section SHOULD NOT be implemented – but if it is implemented the requirements in the section are to be implemented as written. Note that DEPRECATED requirements and sections might be removed from the next major version of this specification.
OBSOLETED
This word refers to a requirement or section of this specification that meets the definition of DEPRECATED, but which has also been declared obsolete. Such requirements or entire sections MUST NOT be implemented; they might be removed from a later minor version of this specification.
1.3.2 References
The following references are of relevance to this Technical Report. At the time of publication, the editions indicated were valid. All references are subject to revision; users of this Technical Report are therefore encouraged to investigate the possibility of applying the most recent edition of the references listed below.
A list of currently valid Broadband Forum Technical Reports is published at www.broadband-forum.org.
1.4 Definitions
The following terminology is used throughout this specification.
Agent
An Agent is an Endpoint that exposes Service Elements to one or more Controllers.
Binding
A Binding is a means of sending Messages across an underlying Message Transfer Protocol.
Command
The term used to define and refer to an Object-specific Operation in the Agent’s Instantiated or Supported Data Model.
Connection Capabilities
Connection Capabilities are information related to an Endpoint that describe how to communicate with that Endpoint, and provide a very basic idea of what sort of function the Endpoint serves.
Controller
A Controller is an Endpoint that manipulates Service Elements through one or more Agents.
Discovery
Discovery is the process by which Controllers become aware of Agents and Agents become aware of Controllers.
Endpoint
An Endpoint is a termination point for a Message.
Endpoint Identifier
The Endpoint Identifier is a globally unique USP layer identifier of an Endpoint.
End to End Message Exchange
USP feature that allows for message integrity protection through the creation of a session context.
Error
An Error is a Message that contains failure information associated with a Request.
Event
An Event is a set of conditions that, when met, triggers the sending of a Notification.
Expression
See also Search Expression.
Expression Component
An Expression Component is the part of a Search Expression that gives the matching Parameter criteria for the search. It is comprised of an Expression Parameter followed by an Expression Operator followed by an Expression Constant.
Expression Constant
The Expression Constant is the value used to compare against the Expression Component to determine if a search matches a given Object.
Expression Operator
The Expression Operator is the operator used to determine how the Expression Component will be evaluated against the Expression Constant, i.e., equals (==), not equals (!=), contains (~=), less than (<), greater than (>), less than or equal (<=) and greater than or equal (>=).
Expression Parameter
The Expression Parameter is a Parameter relative to the Path Name where an Expression Variable occurs that will be used with the Expression Constant to evaluate the Expression Component.
Expression Variable
The Expression Variable is an identifier used to allow relative addressing when building an Expression Component.
Instantiated Data Model
The Instantiated Data Model of an Agent represents the current set of Service Elements (and their state) that are exposed to one or more Controllers.
Instance Identifier
A term used to identify an Instance of a Multi-Instance Object (also called a Row of a Table). While all Multi-Instance Objects have an Instance Number that can be used as an Instance Identifier, an Object Instance can also be referenced using any of that Object’s Unique Keys.
Instance Number
An Instance Number is a numeric Instance Identifier assigned by the Agent to instances of Multi-Instance Objects in an Agent’s Instantiated Data Model.
Message
A Message refers to the contents of a USP layer communication including exactly one Message Header and exactly one Message Body.
Message Body
The Message Body is the portion of a Message that contains one of the following: Request, Response, or Error.
Message Header
The portion of a Message that contains elements that provide information about the Message, including the Message type, and Message ID elements.
Message ID
A Message ID is an identifier used to associate a Response or Error with a Request.
Message Transfer Protocol
A Message Transfer Protocol (MTP) is the protocol at a layer below USP that carries a Message, e.g., WebSocket.
Multi-Instance Object
A Multi-Instance Object refers to an Object that can be created or deleted in the Agent’s Instantiated Data Model. Also called a Table.
Notification
A Notification is a Request from an Agent that conveys information about an Event to a Controller that has a Subscription to that event.
Object
An Object refers to a defined type that an Agent represents and exposes. A Service Element may be comprised of one or more Objects and Sub-Objects.
Object Instance
An Object Instance refers to a single instance Object of a type defined by a Multi-Instance Object in the Agent’s Instantiated Data Model. Also called a Row of a Table.
Object Instance Path
An Object Instance Path is a Path Name that addresses an Instance of a Multi-Instance Object (also called a Row of a Table). It includes the Object Path followed by an Instance Identifier. See Path Names.
Object Path
An Object Path is a Path Name that addresses an Object. In the case of Multi-Instance Objects, an Object Path addresses the Object type itself rather than instances of that Object, which are addressed by Object Instance Paths. See Path Names.
Operation
A method defined for a particular Service Element that can be invoked with the Operate Message.
Parameter
A Parameter is a variable or attribute of an Object. Parameters have both type and value.
Parameter Path
A Parameter Path is a Path Name that addresses a Parameter of an Object or Object Instance. See Path Names.
Path Name
A Path Name is a fully qualified reference to an Object, Object Instance, or Parameter in an Agent’s Instantiated or Supported Data Model. See Path Names.
Path Reference
A Path Reference is a Parameter data type that contains a Path Name to an Object or Parameter that may be automatically followed by using certain Path Name syntax.
Record
The Record is defined as the Message Transfer Protocol (MTP) payload, encapsulating a sequence of datagrams that comprise of the Message as well as essential protocol information such as the USP version, the source Endpoint ID, and the target Endpoint ID. It can also contain additional metadata needed for providing integrity protection, payload protection and delivery of fragmented Messages.
Register
To Register means to use the Register message to inform a Controller of Service Elements that this Agent represents.
Registered
Registered Service Elements are those elements represented by an Agent that have been the subject of a Register message.
Relative Path
A Relative Path is the remaining Path Name information necessary to form a Path Name given a parent Object Path. It is used for message efficiency when addressing Path Names.
Request
A Request is a type of Message that either requests the Agent perform some action (create, update, delete, operate, etc.), requests information about an Agent or one or more Service Elements, or acts as a means to deliver Notifications and Register Messages from the Agent to the Controller. A Request usually requires a Response.
Response
A Response is a type of Message that provides return information about the successful processing of a Request.
Role
A Role refers to the set of permissions (i.e., an access control list) that a Controller is granted by an Agent to interact with objects in its Instantiated Data Model.
Row
The term Row refers to an Instance of a Multi-Instance Object in the Agent’s Instantiated Data Model.
Search Expression
A Search Expression is used in a Search Path to apply specified search criteria to address a set of Multi-Instance Objects and/or their Parameters.
Search Path
A Search Path is a Path Name that contains search criteria for addressing a set of Multi-Instance Objects and/or their Parameters. A Search Path may contain a Search Expression or Wildcard.
Service Element
A Service Element represents a piece of service functionality that is exposed by an Agent, usually represented by one or more Objects.
Source Endpoint
The Endpoint that was the sender of a message.
Subscription
A Subscription is a set of logic that tells an Agent which Notifications to send to a particular Controller.
Supported Data Model
The Supported Data Model of an Agent represents the complete set of Service Elements it is capable of exposing to a Controller. It is defined by the union of all of the Device Type Definitions the Agent exposes to the Controller.
Table
The term Table refers to a Multi-Instance Object in an Agent’s Instantiated or Supported Data Model.
Target Endpoint
The Endpoint that was the intended receiver of a message.
Trusted Broker
An intermediary that either (1) ensures the Endpoint ID in all
brokered Endpoint’s USP Record from_id
matches the Endpoint
ID of those Endpoint’s certificates or credentials, before sending on a
USP Record to another Endpoint, or (2) is part of a closed ecosystem
that “knows” (certain) Endpoints can be trusted not to spoof the
Endpoint ID.
Unique Key
A Unique Key of a Multi-Instance Object is a set of one or more Parameters that uniquely identify the instance of an Object in the Agent’s Instantiated Data Model and can therefore be used as an Instance Identifier.
Unique Key Parameter
A Parameter that is a member of any of a Multi-Instance Object’s Unique Keys.
User Services Platform
The User Services Platform consists of a data model, architecture, and communications protocol to transform consumer broadband networks into a platform for the development, deployment, and support of broadband enabled applications and services.
USP Domain
The USP Domain is a set of all Controllers and Agents that are likely to communicate with each other in a given network or internetwork with the goal of supporting a specific application or set of applications.
USP Relationship
A Controller and Agent are considered to have a USP Relationship when they are capable of sending and accepting messages to/from each other. This usually means the Controller is added to the Agent’s Controller table in its Instantiated Data Model.
Wildcard
A Wildcard is used in a Search Path to address all Object Instances of a Multi-Instance Object.
1.5 Abbreviations
This specification uses the following abbreviations:
| abbreviation | term |
|---|---|
| ABNF | Augmented Backus-Naur Form |
| CID | Company Identifier |
| CSV | Comma-Separated Values |
| CWMP | CPE WAN Management Protocol |
| DNS | Domain Name Service |
| DNS-SD | Domain Name Service - Service Discovery |
| DU | Deployment Unit |
| E2E | End to End (Message Exchange) |
| EE | Execution Environment |
| EU | Execution Unit |
| FIFO | First-In-First-Out |
| FQDN | Fully-Qualified Domain Name |
| GSDM | Get Supported Data Model (informal of GetSupportedDM message) |
| HMAC | Hash Message Authentication Code |
| HTTP | Hypertext Transport Protocol |
| IPv4/v6 | Internet Protocol (version 4 or version 6) |
| JSON | Java Script Object Notation |
| LAN | Local Area Network |
| MAC | Message Authentication Code |
| mDNS | Multicast Domain Name Service |
| MTP | Message Transfer Protocol |
| MQTT | Message Queue Telemetry Transport |
| OUI | Organizationally Unique Identifier |
| PEN | Private Enterprise Number |
| Protobuf | Protocol Buffers |
| PSS | Probabilistic Signature Scheme |
| SAR | Segmentation And Reassembly |
| SMM | Software Module Management |
| SOAP | Simple Object Access Protocol |
| SSID | Service Set Identifier |
| STOMP | Simple Text-Oriented Messaging Protocol |
| TLS | Tranport Layer Security |
| TLV | Type-Length-Value |
| TOFU | Trust on First Use |
| TR | Technical Report |
| UDS | UNIX Domain Socket |
| URI | Uniform Resource Identifier |
| URL | Uniform Resource Locator |
| USP | User Services Platform |
| UUID | Universally Unique Identifier |
| WAN | Wide Area Network |
| XML | eXtensible Markup Language |
1.6 Specification Impact
1.6.1 Energy efficiency
The User Services Platform reaches into more and newer connected devices, and expands on the management of physical hardware, including power management. In addition, USP directly enables smart home, smart building, and other smart energy applications.
1.6.2 Security
Any solution that provides a mechanism to manage, monitor, diagnose, and control a connected user’s network, devices, and applications must prioritize security to protect user data and prevent malicious use of the system. This is especially important with certain high-risk smart applications like medicine or emergency services.
However reliable the security of communications protocols, in a platform that enables interoperable components that may or may not be connected with protocols outside the scope of the specification, security must be considered from end-to-end. To realize this, USP contains its own security mechanisms.
1.6.3 Privacy
Privacy is the right of an individual or group to control or influence what information related to them may be collected, processed, and stored and by whom, and to whom that information may be disclosed.
Assurance of privacy depends on whether stakeholders expect, or are legally required, to have information protected or controlled from certain uses. As with security, the ability for users to control who has access to their data is of primary importance in the world of the connected user, made clear by users as well as regulators.
USP contains rigorous access control and authorization mechanisms to ensure that data is only used by those that have been enabled by the user.
2 Architecture
The User Services Platform consists of a collection of Endpoints (Agents and Controllers) that allow applications to manipulate Service Elements. These Service Elements are made up of a set of Objects and Parameters that model a given service, such as network interfaces, software modules, device firmware, remote elements proxied through another interface, virtual elements, or other managed services.
USP is made up of several architectural components:
- Mechanisms for discovery and trust establishment
- A method for encoding messages for transport
- A system for end-to-end confidentiality, integrity and identity authentication
- Transport of messages over one or more Message Transfer Protocols (MTPs) with associated MTP security
- A set of standardized messages based on the CRUD model (create, read, update, delete), plus an Object defined operations mechanism and a notification mechanism (CRUD-ON)
- Authorization and access control on a per element basis
- A method for modeling service elements using a set of Objects, Parameters, operations, and events (supported and instantiated data models)
2.1 Endpoints
A USP Endpoint can act as Agent or a Controller.  A USP Endpoint communicates with other Endpoints over one or more Message Transfer Protocols (MTP). This communication is secured by the MTP, or by the use of a USP Session Context, or both.
2.1.1 Agents
A USP Agent exposes (to Controllers) one or more Service Elements that are represented in its data model. It contains or references both an Instantiated Data Model (representing the current state of Service Elements it represents) and a Supported Data Model.
2.1.2 Controllers
A USP Controller manipulates (through Agents) a set of Service Elements that are represented in Agent data models. It may maintain a database of Agents, their capabilities, and their states, in any combination. A Controller usually acts as an interface to a user application or policy engine that uses the User Services Platform to address particular use cases.
2.2 Endpoint Identifier
Endpoints are identified by an Endpoint Identifier.
The Endpoint Identifier is a locally or globally unique USP layer identifier of an Endpoint. Whether it is globally or locally unique depends on the scheme used for assignment.
The Endpoint Identifier (ID) is used in the USP Record and various Parameters in a USP Message to uniquely identify Controller and Agent Endpoints. It can be globally or locally unique, either among all Endpoints or among all Controllers or all Agents, depending on the scheme used for assignment.
The Endpoint ID is comprised of two mandatory and one optionally
mandatory components: authority-scheme
,
authority-id
, and instance-id
.
These three components are combined as:
authority-scheme ":" [authority-id] ":" instance-id
The format of the authority-id is dictated by the authority-scheme. The format of the instance-id is dictated either by the authority-scheme or by the entity identified by the authority-id.
When used in a certificate, an Endpoint ID is expressed as a urn in the bbf namespace as:
"urn:bbf:usp:id:" authority-scheme ":" [authority-id] ":" instance-id
When used anywhere else (e.g. in the to_id
and
from_id
of a USP Record), the namespace information is
omitted, and the Endpoint ID is expressed as:
authority-scheme ":" [authority-id] ":" instance-id
2.2.1 Use of authority-scheme and authority-id
The authority-scheme follows the following syntax:
authority-scheme = "oui" | "cid" | "pen" | "self" | "user" | "os" | "ops" | "uuid" | "imei" | "proto" | "doc" | "fqdn"
How these authority-scheme values impact the format and values of authority-id and instance-id is described below.
The authority defined by an OUI, CID, Private Enterprise Number (including OUI used in “ops” and “os” authority scheme), or fully qualified domain name is responsible for ensuring the uniqueness of the resulting Endpoint ID. Uniqueness can be global, local, unique across all Endpoints, or unique among all Controllers or all Agents. For the “user” authority scheme, the assigning user or machine is responsible for ensuring uniqueness. For the “self” authority scheme, the Endpoint is responsible for ensuring uniqueness.
R-ARC.0 - A Controller and Agent within the same USP Domain MAY use the same Endpoint ID.
R-ARC.1 - Endpoints MUST tolerate the same Endpoint ID being used by an Agent and a Controller in the same USP Domain.
R-ARC.2 - Endpoints that share the same Endpoint ID MUST NOT communicate with each other via USP.
No conflict identification or resolution process is defined in USP to deal with a situation where an Endpoint ID is not unique among either all Agents or all Controllers in whatever USP Domain it operates. Therefore, a non-unique Endpoint ID will result in unpredictable behavior. An Endpoint ID that changes after having been used to identify an Endpoint can also result in unpredictable behavior.
Unless the authority responsible for assigning an Endpoint ID assigns meaning to an Agent and Controller having the same Endpoint ID, no meaning can be construed. That is, unless the assigning authority specifically states that an Agent and Controller with the same Endpoint ID are somehow related, no relationship can be assumed to exist.
R-ARC.2a - Endpoints MUST follow the authority-scheme requirements outlined in the following table:
| authority-scheme | usage and rules for authority-id and instance-id |
|---|---|
oui |
authority-id MUST be an OUI
(now called “MAC Address Block Large” or “MA-L”) assigned and registered
by the IEEE Registration Authority [1] to the entity responsible for this
Endpoint. authority-id MUST use hex encoding of the 24-bit ID (resulting
in 6 hex characters). instance-id syntax is defined by this
entity, who is also responsible for determining instance-id assignment
mechanisms and for ensuring uniqueness of the instance-id within the
context of the OUI.
Example:oui:00256D:my-unique-bbf-id-42 |
cid |
authority-id MUST be a CID
assigned and registered by the IEEE Registration Authority [1] to the entity responsible for this
Endpoint. authority-id MUST use hex encoding of the 24-bit
ID (resulting in 6 hex characters).instance-id syntax is defined by this entity, who is also
responsible for determining instance-id assignment mechanisms and for
ensuring uniqueness of the instance-id within the context of the
CID.Example: cid:3AA3F8:my-unique-usp-id-42 |
pen |
authority-id MUST be a
Private Enterprise Number assigned and registered by IANA [4] to the entity responsible for this
Endpoint. authority-id MUST use decimal encoding of the
IANA-assigned number.instance-id syntax is defined by this entity, who is also
responsible for determining instance-id assignment mechanisms and for
ensuring uniqueness of the instance-id within the context of the Private
Enterprise Number.Example: pen:3561:my-unique-bbf-id-42 |
self |
When present, an authority-id
for “self ” MUST be between 1 and 6 non-reserved characters
in length. When present, it is generated by the Endpoint. It is not
required to have an authority-id for
“self ”.The Endpoint ID, including instance-id , is generated by the
Endpoint.The Endpoint MUST change its Endpoint ID if it ever encounters another Endpoint using the identical Endpoint ID. Example: self::my-Agent |
user |
An authority-id for
“user ” MUST be between 0 and 6 non-reserved characters in
length.The Endpoint ID, including instance-id , is assigned to the
Endpoint via a user or management interface. |
os |
authority-id MUST be
zero-length.instance-id is
<OUI> "-" <SerialNumber> , as defined in TR-069
[37] Section 3.4.4.Example: os::00256D-0123456789 |
ops |
authority-id MUST be
zero-length.instance-id is
<OUI> "-" <ProductClass> "-" <SerialNumber> ,
as defined in TR-069 [37] Section
3.4.4.Example: ops::00256D-STB-0123456789 |
uuid |
authority-id MUST be
zero-length.instance-id is a UUID [17]Example: uuid::f81d4fae-7dec-11d0-a765-00a0c91e6bf6 |
imei |
authority-id MUST be
zero-length.instance-id is an IMEI [5] as defined by GSMA.Example: imei::990000862471854 |
proto |
authority-id MUST be between
0 and 6 non-reserved characters (except “.”) in length.“ proto ” is used for prototyping purposes only. Any
authority-id and instance-id value (or scheme
for creating the value) is left to the prototyper.Example: proto::my-Agent |
doc |
authority-id MUST be between
0 and 6 non-reserved characters in length.“ doc ” is used for documentation purposes only (for creating
examples in slide decks, tutorials, and other explanatory documents).
Any authority-id and instance-id value (or
scheme for creating the value) is left to the document creator. |
fqdn |
authority-id MUST be
zero-length.instance-id is a valid fully qualified domain name,
wildcards are not permitted.Example: fqdn::www.example.org |
R-ARC.3 - BBF OUI
(00256D
) and Private Enterprise Number (3561
)
are reserved for use in BBF documentation and BBF prototyping and MUST
NOT be used by any entity other than BBF.
R-ARC.4 - The
“proto
” and “doc
” authority-scheme values MUST
NOT be used in production environments.
The “proto
” and “doc
” values are intended
only for prototyping and documentation (tutorials, examples, etc.),
respectively.
R-ARC.4a - If the
authority-scheme
fqdn
is specified, the TLS
certificates presented by this endpoint MUST contain a
subjectAltName
extension, allowing the use of the FQDN
specified by the instance-id
value.
2.2.2 Use of instance-id
R-ARC.5 -
instance-id
MUST be encoded using only the following
characters:
instance-id = unreserved / pct-encoded
unreserved = ALPHA / DIGIT / "-" / "." / "_"
pct-encoded = "%" HEXDIG HEXDIG
The above expression uses the Augmented Backus-Naur Form (ABNF) notation of RFC 2234 [12], including the following core ABNF syntax rules defined by that specification: ALPHA (letters), DIGIT (decimal digits), HEXDIG (hexadecimal). It is taken from RFC 3986 [16] as the set of unreserved characters and percent-encoded characters that are acceptable for all components of a URI. This set is also allowed for use in URNs RFC 2141 [11], and all MTP headers.
R-ARC.6 - An
instance-id
value MUST be no more than 50 characters in
length.
Shorter values are preferred, as end users could be exposed to Endpoint IDs. Long values tend to create a poor user experience when users are exposed to them.
2.3 Service Elements
“Service Element” is a general term referring to the set of Objects, Sub-Objects, Commands, Events, and Parameters that comprise a set of functionality that is manipulated by a Controller on an Agent. An Agent’s Service Elements are represented in a Data Model - the data model representing an Agent’s current state is referred to as its Instantiated Data Model, and the data model representing the Service Elements it supports is called its Supported Data Model. An Agent’s Data Model is referenced using Path Names.
2.4 Data Models
USP is designed to allow a Controller to manipulate Service Elements on an Agent using a standardized description of those Service Elements. This standardized description is known as an information model, and an information model that is further specified for use in a particular protocol is known as a “Data Model”.
Note: This should be understood by those familiar with CWMP. For those unfamiliar with that protocol, a Data Model is similar to a Management Information Base (MIB) used in the Simple Network Management Protocol (SNMP) or YANG definitions used in NETCONF.
This version of the specification defines support for the following Data Model(s):
- The Device:2 Data Model [39]
This Data Model is specified in XML. The schema and normative requirements for defining Objects, Parameters, Events, and Commands for the Device:2 Data Model [39] are defined in Broadband Forum TR-106 [38].
The use of USP with any of the above data models creates some dependencies on specific Objects and Parameters that must be included for base functionality.
2.4.1 Instantiated Data Model
An Agent’s Instantiated Data Model represents the Service Elements (and their state) that are currently represented by the Agent. The Instantiated Data Model includes a set of Objects, and the Sub-Objects (“children”), Parameters, Events, and Commands associated with those Objects.
2.4.2 Supported Data Model
An Agent’s Supported Data Model represents the Service Elements that an Agent understands. It includes references to the Data Model(s) that define the Objects, Parameters, Events, and Commands implemented by the Service Elements the Agent represents.
2.4.3 Objects
Objects are data structures that are defined by their Sub-Objects, Parameters, Events, Commands, and creation criteria. They are used to model resources represented by the Agent. Objects may be Single-Instance or Multi-Instance (also called a “Table”).
<IP_ADDRESS> Single-Instance Objects
Single-Instance Objects are not tables and do not have more than one instance of them in the Agent. They are usually used to group Service Element functionality together to allow for easy definition and addressing.
<IP_ADDRESS> Multi-Instance Objects
Multi-Instance” Objects are those Objects that can be the subject of “create” and “delete” operations (using the Add and Delete Messages, respectively), with each instance of the Object represented in the Instantiated Data Model with an Instance Identifier (see below). A Multi-Instance Object is also referred to as a “Table”, with each instance of the Object referred to as a “Row”. Multi-Instance Objects can be also the subject of a search.
2.4.4 Parameters
Parameters define the attributes or variables of an Object. They are retrieved by a Controller using the read operations of USP and configured using the update operations of USP (the Get and Set Messages, respectively). Parameters have data types and are used to store values.
2.4.5 Commands
Commands define Object specific methods within the Data Model. A Controller can invoke these methods using the Operate Message (see Defined Operations Mechanism. Commands have associated input and output arguments that are defined in the Data Model and used when the method is invoked and returned.
2.4.6 Events
Events define Object specific notifications within the Data Model. A Controller can subscribe to these events by creating instances of the Subscription table, which are then sent in a Notify request by the Agent (see Notifications and Subscription Mechanism). Events may also have information associated with them that are delivered in the Notify Request - this information is defined with the Event in the Data Model.
2.5 Path Names
A Path Name is a fully qualified reference to an Object, Object Instance, or Parameter in an Agent’s instantiated or Supported Data Model. The syntax for Path Names is defined in TR-106 [38].
R-ARC.7 - All USP Endpoints MUST support the Path Name syntax as defined in TR-106 [38].
Path Names are represented by a hierarchy of Objects (“parents”) and Sub-Objects (“children”), separated by the dot “.” character, ending with a Parameter if referencing a Parameter Path. There are six different types of Path Names used to address the data model of an Agent:
Object Path - This is a Path Name of either a Single-Instance Object, or the Path Name to a Multi-Instance Object (i.e., a Data Model Table). An Object Path ends in a “.” Character (as specified in TR-106 [38]), except when used in a reference Parameter (see Reference Following). When addressing a Table in the Agent’s Supported Data Model that contains one or more Multi-Instance Objects in the Path Name, the sequence “{i}” is used as a placeholder (see The GetSupportedDM Message).
Object Instance Path - This is a Path Name to a Row in a Table in the Agent’s Instantiated Data Model (i.e., an Instance of a Multi-Instance Object). It uses an Instance Identifier to address a particular Instance of the Object. An Object Instance Path ends in a “.” Character (as specified in TR-106 [38]), except when used in a reference Parameter (see Reference Following).
Parameter Path - This is a Path Name of a particular Parameter of an Object.
Command Path - This is a Path Name of an Object defined Operation.
Event Path - This is a Path Name of an Object defined Event.
Search Path - This is a Path Name that contains search criteria for addressing a set of Multi-Instance Objects and/or their Parameters. A Search Path may contain a Search Expression or Wildcard.
This creates two functions of Path Names: Addressing and Searching. The first five Path Names are used for addressing a particular Object, Parameter, Command, or Event. A Search Path uses Searching to return a set of Object Instances and/or their Parameters. When addressing, the expectation is that the Path Name will resolve to either 0 or 1 instance (and depending on the context, 0 instances could be an error). When searching, the expectation is that the Search Path will resolve to 0, 1, or many instances (and depending on the context, 0 instances is often not an error).
Note: When resolving a Path Name, the Agent is expected to use locally cached information and/or information that can be obtained rapidly and cheaply. Specifically, there is no expectation that the Agent would issue a network request in order to resolve a Path Name.
Note: Obviously only one form of addressing or searching can be used for a given Instance Identifier in a Path Name, but different forms of addressing can be used if more than one Instance Identifier needs to be specified in a Path Name.
For example, the following Path Name uses Unique Key Addressing for the Interface table but a Search Expression for the IPv4Address table to select Enabled IPv4 Addresses associated with the “eth0” IP Interface:
Device.IP.Interface.[Name=="eth0"].IPv4Address.[Status=="Enabled"].IPAddress
2.5.1 Relative Paths
Several USP Messages make use of Relative Paths to address Objects or Parameters. A Relative Path is used to address the child Objects and Parameters of a given Object Path or Object Instance Path. To build a Path Name using a Relative Path, a USP Endpoint uses a specified Object Path or Object Instance Path, and concatenates the Relative Path. This allows some efficiency in Requests and Responses when passing large numbers of repetitive Path Names. This Relative Path may include instance identifiers to Multi-Instance Objects.
For example, for an Object Path of:
Device.WiFi.Radio.1.
Relative Paths would include Parameters:
Status
SupportedStandards
OperatingStandards
Etc., as well as the following Sub-Object and its Parameters:
Stats.BytesSent
Stats.BytesReceived
Etc.
2.5.2 Using Instance Identifiers in Path Names
<IP_ADDRESS> Addressing by Instance Number
Instance Number Addressing allows an Object Instance to be addressed by using its Instance Number in the Path Name. An Instance Number is expressed in the Path Name as a positive integer (>=1) with no additional surrounding characters. The Instance Number assigned by the Agent is arbitrary.
R-ARC.8 - The assigned Instance Number MUST persist unchanged until the Object Instance is subsequently deleted (either by the USP Delete Message or through some external mechanism). This implies that the Instance Number MUST persist across a reboot of the Agent, and that the Agent MUST NOT allow the Instance Number of an existing Object Instance to be modified by an external source.
For example, the Device.IP.Interface
table entry with an
Instance Number of 3 would be addressed with the following Path Name:
Device.IP.Interface.3
.
<IP_ADDRESS> Addressing by Unique Key
Key-based addressing allows an Object Instance to be addressed by using a Unique Key (as defined in the Device:2 Data Model [39]) in the Path Name.
Note: Controller and Agent interoperability is greatly affected by an Agent’s implementation of Unique Keys. While this specification does not aim to overlap its requirements to those of TR-181 [39], it is imperative that an Agent implements Unique Keys for every Multi-Instance object in its Supported Data Model.
Unique Keys used for addressing are expressed in the Path Name by using square brackets surrounding a string that contains the name and value of the Unique Key Parameter using the equality operator (==).
For example, the Device.IP.Interface
table has two
separate unique keys: Name
and Alias
. It could
be addressed with the following Path Names:
Device.IP.Interface.[Name=="eth0"]
Device.IP.Interface.[Alias=="WAN"]
If an Object has a multi-parameter unique key, then the Instance Identifier specifies all of the key’s Parameters using the AND (&&) logical operator (the Parameter order is not significant).
For example, the Device.NAT.PortMapping
table has a
multi-parameter unique key consisting of RemoteHost, ExternalPort, and
Protocol. It could be addressed with the following Path Name:
Device.NAT.PortMapping.[RemoteHost==""&&ExternalPort==0&&Protocol=="TCP"].
Note: Addressing by Unique Key uses the same syntax as Searching with Expressions. If a multi-parameter unique key expression omits any of the key’s Parameters then it’s a search (which might match multiple instances) rather than an address (which can’t match multiple instances).
2.5.3 Searching
Searching is a means of matching 0, 1 or many instances of a Multi-Instance Object by using the properties of Object. Searching can be done with Expressions or Wildcards.
2.5.4 Searching with Expressions
Search Paths that use expressions are enclosed in square brackets as the Instance Identifier within a Path Name.
R-ARC.9 - An Agent MUST return Path Names that include all Object Instances that match the criteria of a given Search Path.
The basic format of a Search Path is:
Device.IP.Interface.[<expression>].Status
An Expression consists of one or more Expression Components that are concatenated by the AND (&&) logical operator (Note: the OR logical operator is not supported).
The basic format of a Search Path with the Expression element expanded is:
Device.IP.Interface.[<expression component>&&<expression component>].Status
An Expression Component is a combination of an Expression Parameter followed by an Expression Operator followed by an Expression Constant.
The basic format of a Search Path with the Expression Component element expanded is:
Device.IP.Interface.[<expression parameter><expression operator><expression constant>].Status
Further, this Relative Path can’t include any child tables. (Note: this is never necessary because any child tables that need to be referenced in the Search Path can and should have their own Expression)
An Expression Operator dictates how the Expression Component will be evaluated. The supported operators are equals (==), not equals (!=), contains (~=), less than (<), greater than (>), less than or equal (<=) and greater than or equal (>=).
An Expression Parameter will always be of the type defined in the data model. Expression operators will only evaluate for appropriate data types. The literal value representations for all data types are found in TR-106 [38]. For string and boolean types, and also the Unknown Time dateTime value (cf. TR-106 Section 3.2.1 [38]), only the ‘==’ and ‘!=’ operators are valid.
The ‘~=’ operator is only valid for comma-separated lists. It is used to check whether a list contains a certain element using an exact match of the element. The Expression Constant used in the Search Expression must be of the same type as the values in the list. For example, for a list of integers, the Expression Constant must also be an integer.
Note: Literal values are conceptually converted to a suitable
internal representation before comparison. For example, int
values 123
, +123
and 0123
all
represent the same value, and so do boolean
values
1
and true
.
The Expression Constant is the value that the Expression Parameter is being evaluated against; Expression Parameters must match the type as defined for the associated Parameter in the Device:2 Data Model [39].
Note: String values are enclosed in double quotes. In order to allow a string value to contain double quotes, quote characters can be percent-escaped as %22 (double quote). Therefore, a literal percent character has to be quoted as %25.
The use of whitespace on either side of an Expression Operator is
allowed, but its support is not required. Controllers cannot assume that
an Agent tolerates whitespace. An example of an Expression with
whitespace would be [Type == "Normal"]
(which would be
[Type=="Normal"]
without whitespace).
R-ARC.9a - Agents SHOULD tolerate whitespace on either side of an Expression Operator.
R-ARC.9b - Controllers SHOULD NOT include whitespace on either side of an Expression Operator.
<IP_ADDRESS>.1 Search Expression Examples
Valid Searches:
Status for all IP Interfaces with a “Normal” type:
Device.IP.Interface.[Type=="Normal"].Status
IPv4 Addresses for all IP Interfaces with a Normal type and a Static addressing type:
Device.IP.Interface.[Type=="Normal"].IPv4Address.[AddressingType=="Static"].IPAddress
IPv4 Addresses for all IP Interfaces with a Normal type and Static addressing type that have at least 1 Error Sent:
Device.IP.Interface.[Type=="Normal"&&Stats.ErrorsSent>0].IPv4Address.[AddressingType=="Static"].IPAddress
Current profiles used by all DSL lines which are enabled:
Device.DSL.Line.[Enable==true].CurrentProfile
or
Device.DSL.Line.[Enable==1].CurrentProfile
All IPv6 Addresses of all interfaces with a lifetime expiring before 2021-06-06 08:00 UTC:
Device.IP.Interface.*.IPv6Address.[ValidLifetime<2021-06-06T08:00:00Z].IPAddress
All Parameters of all connected USB devices of class 0x08 (Mass Storage Device):
Device.USB.USBHosts.Host.*.Device.[DeviceClass==08].
All Parameters of all PCP servers with IPv6Firewall capabilities:
Device.PCP.Client.*.Server.[Capabilities~="IPv6Firewall"].
All Parameters of all PeriodicStatistics SampleSets that collected data for 5 seconds:
Device.PeriodicStatistics.SampleSet.[SampleSeconds~=5].
Searches that are NOT VALID:
Invalid because the Expression is empty:
Device.IP.Interface.[].
Invalid because the Expression Component has an Expression Parameter that descends into a child table (always need to use a separate Expression Variable for each child table instance):
Device.IP.Interface.[Type=="Normal"&&IPv4Address.*.AddressingType=="Static"].Status
Invalid because the search expression uses curly brackets:
Device.IP.Interface.{Type=="Normal"}.Status
Invalid because the
Enable
Parameter is of typeboolean
and not astring
or derived fromstring
:Device.DSL.Line.[Enable=="true"].CurrentProfile
2.5.5 Searching by Wildcard
Wildcard-based searching is a means of matching all currently existing Instances (whether that be 0, 1 or many instances) of a Multi-Instance Object by using a wildcard character “*” in place of the Instance Identifier.
R-ARC.10 - An Agent MUST return Path Names that include all Object Instances that are matched by the use of a Wildcard.
Examples:
All Parameters for all IP Interfaces that currently exist
Device.IP.Interface.*.
Type of each IP Interface that currently exists
Device.IP.Interface.*.Type
2.6 Other Path Decorators
2.6.1 Reference Following
The Device:2 Data Model [39] contains Parameters that reference other Parameters or Objects. The Reference Following mechanism allows references to Objects (not Parameters) to be followed from inside a single Path Name. Reference Following is indicated by a “+” character after the Parameter Path, referencing the Object followed by a “.”, optionally followed by a Relative Object or Parameter Path that are children of the Referenced Object.
For example, Device.NAT.PortMapping.{i}.Interface
references an IP Interface Object
(Device.IP.Interface.{i}.
) and that Object has a Parameter
called “Name
”. With Reference Following, a Path Name of
Device.NAT.PortMapping.1.Interface+.Name
references the
“Name
” Parameter of the Interface
Object that
the PortMapping
is associated with (i.e. it is the
equivalent of using Device.IP.Interface.1.Name
as the Path
Name).
The steps that are executed by the Agent when following the reference in this example would be:
Retrieve the appropriate instance of the
PortMapping
Object based on the Instance Number Addressing informationRetrieve the value of the reference Parameter that contains the reference, Interface, which in this case has the value “
Device.IP.Interface.1
”Replace the preceding Path Name (
Device.NAT.PortMapping.1.Interface+
) with the value retrieved in Step 2Append the remainder of the Path Name (
.Name
), which builds the Path Name:Device.IP.Interface.1.Name
Use
Device.IP.Interface.1.Name
as the Path Name for the action
Note: It should be noted that according to the Device:2 Schema [38], reference Parameters:
- Always contain Path Names (not Search Expressions)
- When configured, can be configured using Path Names using Instance Number Addressing or Unique-Key Addressing, however:
- When the value of a reference Parameter is read, all Instance Identifiers are returned as Instance Numbers.
R-ARC.11 - A USP Agent MUST support the ability to use Key-based addressing in reference values.
For example, the following Path Names might illustrate a reference to
the same Object (defined as having the Parameter named
KeyParam
as unique key) instance using an Instance Number
and then a key value:
- Object.SomeReferenceParameter = “Object.FooObject.5”
- Object.SomeReferenceParameter = ‘Object.FooObject.[KeyParam==“KeyValueForInstance5”]’
In the first example, the reference points to the FooObject with
Instance Number 5. In the second example, the reference points to the
FooObject with a KeyParam
value of
“KeyValueForInstance5”.
R-ARC.12 - The following requirements relate to reference types and the associated Agent behavior:
- An Agent MUST reject an attempt to set a strong reference Parameter if the new value does not reference an existing Parameter or Object.
- An Agent MUST NOT reject an attempt to set a weak reference Parameter because the new value does not reference an existing Parameter or Object.
- An Agent MUST change the value of a non-list-valued strong reference Parameter to a null reference when a referenced Parameter or Object is deleted.
- An Agent MUST remove the corresponding list item from a list-valued strong reference Parameter when a referenced Parameter or Object is deleted.
- An Agent MUST NOT change the value of a weak reference Parameter when a referenced Parameter or Object is deleted.
<IP_ADDRESS> List of References
The USP data models have Parameters whose values contain a list of
references to other Parameters or Objects. This section explains how the
Reference Following mechanism allows those references to be followed
from inside a single Path Name. The Reference Following syntax as
defined above still applies, but the “+
” character is
preceded by a means of referencing a list item or items.
The additional syntax consists of a “
#
” character followed by a list item number (1-indexed), which is placed between the Parameter name and the “+
” character.- The “
#
” and list item number are optional. If they are omitted, the first list item is used, i.e., “ReferenceParameter+
” means the same as “ReferenceParameter#1+
”.
- The “
To follow all references in the list, use a wildcard (“
*
”) character instead of a list item number, i.e., “ReferenceParameter#*+
”.
For example, Device.WiFi.SSID.{i}.LowerLayers
references
a list of Wi-Fi Radio Object (defined as
Device.WiFi.Radio.{i}.
) Instances that are associated with
the SSID. This Object has a Name
Parameter; so when
following the first reference in the list of references a Path Name of
Device.WiFi.SSID.1.LowerLayers#1+.Name
references the Name
of the Wi-Fi Radio associated with this SSID Object Instance.
The steps that are executed by the Agent when following the reference in this example would be:
Retrieve the appropriate
Device.WiFi.SSID.{i}
instance based on the Instance Number Addressing informationRetrieve the value of the LowerLayers Parameter, which in this case has a value of “
Device.WiFi.Radio.1, Device.WiFi.Radio.2
”Retrieve the first list item within the value retrieved in Step 2 (i.e., “
Device.WiFi.Radio.1
”)Replace the preceding Path Name (
Device.WiFi.SSID.1.LowerLayers#1+
) with the value retrieved in Step 3Append the remainder of the Path Name (
.Name
), resulting in a Path Name of:Device.WiFi.Radio.1.Name
Use
Device.WiFi.Radio.1.Name
as the Path Name for the action
<IP_ADDRESS> Search Expressions and Reference Following
The Reference Following and Search Expression mechanisms can be combined.
For example, reference the Signal Strength of all Wi-Fi Associated Devices using the “ac” Operating Standard on the “MyHome” SSID, you would use the Path Name:
Device.WiFi.AccessPoint.[SSIDReference+.SSID=="MyHome"].AssociatedDevice.[OperatingStandard=="ac"].SignalStrength
2.6.2 Operations and Command Path Names
The Operate Message allows a USP Controller to execute Commands defined in the USP data models. Commands are synchronous or asynchronous operations that don’t fall into the typical REST-based concepts of CRUD-N that have been incorporated into the protocol as specific Messages. Commands are addressed like Parameter Paths that end with parentheses “()” to symbolize that it is a Command.
For example:
Device.IP.Interface.[Name=="eth0"].Reset()
2.6.3 Event Path Names
The Notify request allows a type of generic event (called Event) message that allows a USP Agent to emit events defined in the USP data models. Events are defined in and related to Objects in the USP data models like commands. Events are addressed like Parameter Paths that end with an exclamation point “!” to symbolize that it is an Event.
For example: Device.Boot!
2.7 Data Model Path Grammar
Expressed as a Backus-Naur Form (BNF) for context-free grammars, the Path Name lexical rules for referencing the Instantiated Data Model are:
idmpath ::= objpath | parampath | cmdpath | evntpath
objpath ::= name '.' (name (('.' inst)|(reffollow '.' name) )? '.')*
parampath ::= objpath name
cmdpath ::= objpath name '()'
evntpath ::= objpath name '!'
inst ::= posnum | expr | '*'
expr ::= '[' (exprcomp ( '&&' exprcomp )*) ']'
exprcomp ::= relpath oper value
relpath ::= name (reffollow? '.' name )*
reffollow ::= ( '#' (posnum | '*') '+' )| '+'
oper ::= '==' | '!=' | '~=' | '<' | '>' | '<=' | '>='
value ::= literal | number
name ::= [A-Za-z_] [A-Za-z_0-9]*
literal ::= '"' [^"]* '"'
posnum ::= [1-9] [0-9]*
number ::= '0' | ( '-'? posnum )
The Path Name lexical rules for referencing the Supported Data Model are:
sdmpath ::= name '.' ( name '.' ( ( posnum | '{i}' ) '.' )? )* name?
name ::= [A-Za-z_] [A-Za-z_0-9]*
posnum ::= [1-9] [0-9]*
2.7.1 BNF Diagrams for Instantiated Data Model
idmpath:
idmpath ::= objpath | parampath | cmdpath | evntpath
objpath:
objpath ::= name ‘.’ ( name ( ‘.’ inst | reffollow ‘.’ name)? ‘.’ )*
referenced by:
parampath:
parampath ::= objpath name
referenced by:
cmdpath:
cmdpath ::= objpath name ‘()’
referenced by:
evntpath:
evntpath ::= objpath name ‘!’
referenced by:
inst:
inst ::= posnum | expr | ’*’
referenced by:
expr:
expr ::= ‘[’ exprcomp ( ’&&’ exprcomp )* ’]’
referenced by:
exprcomp:
exprcomp ::= relpath oper value
referenced by:
relpath:
relpath ::= name ( reffollow? ‘.’ name )*
referenced by:
reffollow:
reffollow ::= ( ‘#’ ( posnum | ’*’ ) )? ‘+’
referenced by:
oper:
oper ::= ‘==’ | ‘!=’ | ‘~=’ | ‘<’ | ‘>’ | ‘<=’ | ‘>=’
referenced by:
value:
value ::= literal | number
referenced by:
name:
name ::= [A-Za-z_] [A-Za-z_0-9]*
referenced by:
literal:
literal ::= ‘“’ [^"]* ‘“’
referenced by:
number:
number ::= ‘0’ | ‘-’? posnum
referenced by:
posnum:
posnum ::= [1-9] [0-9]*
referenced by:
2.7.2 BNF Diagrams for Supported Data Model
sdmpath:
sdmpath ::= name ‘.’ ( name ‘.’ ( ( posnum | ‘{i}’ ) ‘.’ )? )* name?
name:
name ::= [A-Za-z_] [A-Za-z_0-9]*
referenced by:
posnum:
posnum ::= [1-9] [0-9]*
referenced by:
3 Discovery and Advertisement
Discovery is the process by which USP Endpoints learn the USP properties and MTP connection details of another Endpoint, either for sending USP Messages in the context of an existing relationship (where the Controller’s USP Endpoint Identifier, credentials, and authorized Role are all known to the Agent) or for the establishment of a new relationship.
Advertisement is the process by which USP Endpoints make their presence known (or USP Endpoint presence is made known) to other USP Endpoints.
3.1 Controller Information
An Agent that has a USP relationship with a Controller needs to know that Controller’s Endpoint Identifier, credentials, and authorized Role.
An Agent that has a USP relationship with a Controller needs to obtain information that allows it to determine at least one MTP, IP address, port, and resource path (if required by the MTP) of the Controller. This may be a URL with all of these components, a FQDN that resolves to provide all of these components via DNS-SD records, or mDNS discovery in the LAN.
Example mechanisms for configuration include but are not limited to:
- Pre-configured in firmware
- Configured by an already-known-and-trusted Controller
- Configured through a separate bootstrap mechanism such as a user interface or other management interface.
- DHCP, DNS, or mDNS.
R-DIS.0 - An Agent that supports
USP configuration of Controllers MUST implement the
Device.LocalAgent.Controller
Object as defined in the
Device:2 Data Model [39].
The Agent can be pre-configured with trusted root certificates or trusted certificates to allow authentication of Controllers. Other trust models are also possible, where an Agent without a current Controller association will trust the first discovered Controller, or where the Agent has a UI that allows a User to indicate whether a discovered Controller is authorized to configure that Agent.
3.2 Required Agent Information
A Controller that has a relationship with an Agent needs to know the Agent’s Endpoint Identifier, connectivity information for the Agent’s MTP(s), and credentials.
Controllers acquire this information upon initial connection by an Agent, though a LAN based Controller may acquire an Agent’s MTP information through mDNS Discovery. It is each Controller’s responsibility to maintain a record of known Agents.
3.3 Use of DHCP for Acquiring Controller Information
DHCP can be employed as a method for Agents to discover Controllers. The DHCPv4 Vendor-Identifying Vendor-Specific Information Option [15] (option code 125) and DHCPv6 Vendor-specific Information Option [14] (option code 17) can be used to provide information to Agents about a single Controller. The options that may be returned by DNS are shown below. Description of these options can be found in the Device:2 Data Model [39].
R-DIS.1 - If an Agent is
configured to request Controller DHCP information, the Agent MUST
include in its DHCPv4 requests a DHCPv4 V-I Vendor Class Option (option
124) and in its DHCPv6 requests a DHCPv6 Vendor Class (option 16). This
option MUST include the Broadband Forum Enterprise Number
(3561
decimal, 0x0DE9
hex) as an
enterprise-number, and the string “usp
” (all lower case) in
a vendor-class-data instance associated with this enterprise-number.
R-DIS.1a - The Agent MUST decode all received options as strings (provisioning code, wait interval, and interval multiplier are not decoded as numeric fields).
R-DIS.1b - The Agent MUST interpret a received URL or FQDN of the Controller as either an absolute URL or FQDN.
R-DIS.1c - If the Agent receives an encapsulated option value that is null terminated, the Agent MUST accept the value provided, and MUST NOT interpret the null character as part of the value.
The Role to associate with a DHCP-discovered Controller is programmatically determined (see Authentication and Authorization).
Note: Requirement R-DIS.2 was removed in USP 1.2.
See Using DNS for requirements on resolving URLs and FQDNs provided by DHCP.
ISPs are advised to limit the use of DHCP for configuration of a Controller to situations in which the security of the link between the DHCP server and the Agent can be assured by the service provider. Since DHCP does not itself incorporate a security mechanism, it is a good idea to use pre-configured certificates or other means of establishing trust between the Agent and a Controller discovered by DHCP.
3.3.1 DHCP Options for Controller Discovery
| Encapsulated Option | DHCPv4 Option 125 | DHCPv6 Option 17 | Parameter in the Device:2 Data Model [39] |
|---|---|---|---|
| URL or FQDN of the Controller | 25 |
25 |
Dependent on MTP |
| Provisioning code | 26 |
26 |
Device.LocalAgent.Controller.{i}.ProvisioningCode |
| USP retry minimum wait interval | 27 |
27 |
Device.LocalAgent.Controller.{i}.USPNotifRetryMinimumWaitInterval |
| USP retry interval multiplier | 28 |
28 |
Device.LocalAgent.Controller.{i}.USPNotifRetryIntervalMultiplier |
| Endpoint ID of the Controller | 29 |
29 |
Device.LocalAgent.Controller.{i}.EndpointID |
3.4 Use of DHCP for Exchanging GatewayInfo
This section contains a set of USP requirements related to a mechanism that was originally defined in the CPE WAN Management Protocol [37] (CWMP), which provides a way for a CWMP Gateway and an End Device to exchange information via DHCP options to populate data model objects with their reciprocal information. The purpose of populating this information is to provides an ACS or USP Controller with the ability to determine whether the Gateway and Device are on the same LAN. The USP requirements defined in this section identify what USP-enabled devices (Gateways and End Devices) need to do to interoperate with CWMP-enabled devices without changing any CWMP functionality, so it is mostly a replication of those CWMP requirements from a USP-enabled device perspective.
3.4.1 Exchanging DHCP Options
This section outlines the DHCP information USP Agents exchange to provide details about the devices on the LAN, as well as the Service Elements that are updated. This allows a USP Agent to recognize a CWMP Client that supports the Device-Gateway Association within the LAN, and a CWMP Client to recognize a USP Agent.
R-DIS.2a - When an Agent sends a DHCPv4 requests (DHCPDISCOVER, DHCPREQUEST, and DHCPINFORM) or DHCPv6 requests (SOLICIT, REQUEST, RENEW, and INFORMATION-REQUEST) it MUST include the Encapsulation Options for requests below.
3.4.2 DHCP Encapsulated Vendor-Specific Option-Data fields for DHCP requests
| Encapsulated Option | DHCPv4 Option 125 | DHCPv6 Option 17 | Parameter in the Device:2 Data Model [39] |
|---|---|---|---|
| DeviceManufacturerOUI | 1 |
11 |
Device.DeviceInfo.ManufacturerOUI |
| DeviceSerialNumber | 2 |
12 |
Device.DeviceInfo.SerialNumber |
| DeviceProductClass | 3 |
13 |
Device.DeviceInfo.ProductClass |
These Encapsulated Options are carried in DHCPv4 V-I Vendor Class Option (option 125) or DHCPv6 V-I Vendor Class Option (option 17) with an element identified with the IANA Enterprise Number for the Broadband Forum that follows the format defined below. The IANA Enterprise Number for the Broadband Forum is 3561 in decimal (the ADSL Forum entry in the IANA Private Enterprise Numbers registry).
R-DIS.2b - If an Agent recieves the encapsulation options for requests above, then it MUST respond with the Encapsulated Options for a response in the DHCPv4 responses (DHCPOFFER and DHCPACK) and DHCPv6 responses (ADVERTISE and REPLY) below. The responses are only included if the request options are recieved.
3.4.3 DHCP Encapsulated Vendor-Specific Option-Data fields for Agent
| Encapsulated Option | DHCPv4 Option 125 | DHCPv6 Option 17 | Parameter in the Device:2 Data Model [39] |
|---|---|---|---|
| DeviceManufacturerOUI | 4 |
14 |
Device.DeviceInfo.ManufacturerOUI |
| DeviceSerialNumber | 5 |
15 |
Device.DeviceInfo.SerialNumber |
| DeviceProductClass | 6 |
16 |
Device.DeviceInfo.ProductClass |
These Encapsulated Options are carried in DHCPv4 V-I Vendor Class Option (option 125) or DHCPv6 V-I Vendor Class Option (option 17) with an element identified with the IANA Enterprise Number for the Broadband Forum that follows the format defined below. The IANA Enterprise Number for the Broadband Forum is 3561 in decimal (the ADSL Forum entry in the IANA Private Enterprise Numbers registry).
R-DIS.2c - When an Agent receives
a DHCPv4 response (DHCPOFFER or DHCPACK) or a DHCPv6 response (ADVERTISE
or REPLY) with this information, it MUST populate the
Device.GatewayInfo
Object as defined in the Device:2 Data
Model [39]. Specifically, it MUST set the the
parameters ManufacturerOUI
, ProductClass
and
SerialNumber
, if present and
ManagementProtocol
MUST be set to “CWMP”. If any of the
parameters are not present then they MUST be set to an empty string. If
the DHCP release expires, or the USP Endpoint doesnt recieve this
information, the Parameters in the Device.GatewayInfo
Object MUST be set to an empty strings.
R-DIS.2d - When an Agent performs
mDNS discovery (see Discovery
and Advertisement) and recieves a PTR record (see DNS-SD Records) that
match the same IP address as the DHCP response from (R-DIS.2c), it MUST also set the
Device.GatewayInfo.ManagementProtocol
Parameter to “USP”,
and Device.GatewayInfo.EndpointID
Parameter to the USP
EndpointID received in the PTR record.
3.5 Using mDNS
R-DIS.3 - If mDNS discovery is supported by a USP Endpoint, the USP Endpoint MUST implement mDNS client and server functionality as defined in RFC 6762 [25].
R-DIS.4 - If mDNS advertisement for a MTP is enabled on an Endpoint, the Endpoint MUST listen for messages using that MTP from other Endpoints requesting establishment of USP communication over that MTP.
R-DIS.5 - If mDNS is enabled, a
USP Endpoint MUST use mDNS to resolve a FQDN with domain
“.local.
”.
In general, the expectation is that Agents will advertise themselves
so they will be discoverable by Controllers. Controllers are not
expected to advertise themselves, but are expected to discover Agents
and respond to applicable mDNS requests from Agents. Agents will use
mDNS to resolve a Controller “.local.
” FQDN (and get DNS-SD
records) when the Agent needs to send a Notification to that
Controller.
3.6 Using DNS
Requirements for implementation of a DNS client and configuration of the DNS client with DNS server address(es) (through static configuration, DHCPv4, DHCPv6, or Router Solicitation) are not provided. These are sufficiently well-known that they were not considered necessary for this specification. If the Agent knows of no DNS Server, it cannot do DNS resolution.
R-DIS.6 - If DNS is enabled, an Endpoint MUST use DNS to request IP address(es) (A and/or AAAA records, depending on confiured IP stacks) for a FQDN with domain other than ones used for mDNS (R-DIS.5).
If the Endpoint is programmatically set to request other resource records, it will request those, too.
R-DIS.7 - If the Agent is resolving an FQDN for a Controller, and the MTP or resource path are unknown, the Agent MUST request DNS-SD information (PTR, SRV and TXT resource records) in addition to A, AAAA or other resource records it is programmatically set to request.
3.7 DNS-SD Records
DNS Service Discovery (DNS-SD) RFC 6763 [26] is a mechanism for naming and structuring DNS resource records to facilitate service discovery. It can be used to create DNS records for USP Endpoints, so they can be discoverable via DNS PTR queries RFC 1035 [9] or Multicast DNS (mDNS) RFC 6762 [25]. DNS-SD uses DNS SRV and TXT records to express information about “services”, and DNS PTR records to help locate the SRV and TXT records. To discover these DNS records, DNS or mDNS queries can be used. RFC 6762 [25] recommends using the query type PTR to get both the SRV and TXT records. A and AAAA records will also be returned, for address resolution.
The format of a DNS-SD Service Instance Name (which is the resource
record (RR) Name of the DNS SRV and TXT records) is
“<Instance>.<Service>.<Domain>
”.
<Instance>
will be the USP Endpoint Identifier of the
USP Endpoint.
R-DIS.8 - USP Endpoint DNS-SD records MUST include the USP Endpoint Identifier of the USP Endpoint as the DNS-SD Service Instance Name.
Service Name values registered by BBF with
IANA used by USP are shown below. As described in RFC 6763 [26], the <Service>
part of a Service Instance Name is constructed from these values as
“_<Service Name>._<Transport Protocol>
” (e.g.,
“_usp-agt-ws._tcp
”).
3.7.1 IANA-Registered USP Service Names
| Service Name | Transport Protocol | MTP | Type of USP Endpoint |
|---|---|---|---|
usp-agt-coap |
udp | CoAP | Agent |
usp-agt-mqtt |
tcp | MQTT | Agent |
usp-agt-stomp |
tcp | STOMP | Agent |
usp-agt-ws |
tcp | WebSocket | Agent |
usp-ctr-coap |
udp | CoAP | Controller |
usp-ctr-mqtt |
tcp | MQTT | Controller |
usp-ctr-stomp |
tcp | STOMP | Controller |
usp-ctr-ws |
tcp | WebSocket | Controller |
DNS PTR records with a service subtype identifier (e.g.,
._<subtype>._usp-agt-ws._tcp.<Domain>
) in the
RR can be used to provide searchable simple (single layer) functional
groupings of USP Agents. The registry of subtypes for Service Names
registered by BBF is listed at www.broadband-forum.org/assignments.
DNS SRV and TXT records can be pointed to by multiple PTR records, which
allow a USP Endpoint to potentially be discoverable as belonging to
various functional groupings.
DNS TXT records allow for a small set of additional information to be included in the reply sent to the querier. This information cannot be used as search criteria. The registry of TXT record attributes for BBF Service Names are listed at www.broadband-forum.org/assignments.
R-DIS.9 - Agent DNS-SD records MUST include a TXT record with the “path” and “name” attributes.
R-DIS.10 - The “name” attribute
included in the Agent DNS-SD records MUST be identical to the
FriendlyName
Parameter defined in the Device:2 Data Model
[39], if the FriendlyName
Parameter is implemented.
R-DIS.11 - Controller DNS-SD records MUST include a TXT record with the “path” attribute.
The “path” attribute is dependent on each MTP.
R-DIS.11a - If a USP Endpoint requires MTP encryption to be used when connecting to its advertised service, it MUST include the “encrypt” parameter in the TXT record.
The “encrypt” parameter is Boolean and does not require a value to be specified. Its presence means MTP encryption is required when connecting to the advertised service. Its absence means MTP encryption is not required when connecting to the advertised service.
The TXT record can include other attributes defined in the TXT record attribute registry, as well.
Whether a particular USP Endpoint responds to DNS or mDNS queries or populates (through configuration or mDNS advertisement) their information in a local DNS-SD server can be a configured option that can be enabled/disabled, depending on the intended deployment usage scenario.
3.7.2 Example Controller Unicast DNS-SD Resource Records
; One PTR record for each supported MTP
_usp-ctr-ws._tcp.host.example.com PTR <USP ID>._usp-ctr-ws._tcp.example.com.
; One SRV+TXT (DNS-SD Service Instance) record for each supported MTP
<USP ID>._usp-ctr-ws._tcp.example.com. SRV 0 1 5684 host.example.com.
<USP ID>._usp-ctr-ws._tcp.example.com. TXT "<length byte>path=<pathname><length byte>encrypt"
; Controller A and AAAA records
host.example.com. A <IP_ADDRESS>
host.example.com. AAAA 2001:db8::200
3.7.3 Example Agent Multicast DNS-SD Resource Records
; One PTR record (DNS-SD Service) for each supported MTP
_usp-agt-ws._tcp PTR <USP ID>._usp-agt-ws._tcp.local.
; One PTR record (DNS-SD Service Subtype) for each supported MTP per device type
_iot-device._sub._usp-agt-ws._tcp PTR <USP ID>._usp-agt-ws._tcp.local.
_gateway._sub._usp-agt-ws._tcp PTR <USP ID>._usp-agt-ws._tcp.local.
; One SRV+TXT record (DNS-SD Service Instance) for each supported MTP
<USP ID>._usp-agt-ws._tcp.local. SRV 0 1 5684 <USP ID>.local.
<USP ID>._usp-agt-ws._tcp.local. TXT "<length byte>path=<pathname><length byte>name=kitchen light<length byte>encrypt"
; Agent A and AAAA records
<USP ID>.local. A <IP_ADDRESS>
<USP ID>.local. AAAA 2001:db8::100
3.7.4 Example Controller Multicast DNS-SD Resource Records
LAN Controllers do not need to have PTR records, as they will only be queried using the DNS-SD instance identifier of the Controller.
; One SRV+TXT record (DNS-SD Service Instance) for each supported MTP
<USP ID>._usp-ctr-ws._tcp.local. SRV 0 1 5683 <USP ID>.local.
<USP ID>._usp-ctr-ws._tcp.local. TXT "<length byte>path=<pathname>"
; Controller A and AAAA records
<USP ID>.local. A <IP_ADDRESS>
<USP ID>.local. AAAA 2001:db8::200
3.8 Using the SendOnBoardRequest() operation and OnBoardRequest notification
An “OnBoardRequest” notification can be sent by an Agent to a Controller to begin an on-boarding process (for example, when the Agent first comes online and discovers a Controller using DHCP). Its use is largely driven by policy, but there is a mechanism other Controllers can use to ask an Agent to send “OnBoardRequest” to another Controller: the SendOnBoardRequest() command is defined in the Device:2 Data Model [39]. See Notification Types for additional information about the OnBoardRequest notification.
4 Message Transfer Protocols
USP messages are sent between Endpoints over one or more Message Transfer Protocols.
Note: Message Transfer Protocol was a term adopted to avoid confusion with the term “Transport”, which is often overloaded to include both application layer (e.g. WebSocket) and the actual OSI Transport layer (e.g. TCP). Throughout this document, Message Transfer Protocol (MTP) refers to application layer transport.
4.1 Generic Requirements
The requirements in this section are common to all MTPs.
4.1.1 Supporting Multiple MTPs
Agents and Controllers may support more than one MTP. When an Agent supports multiple MTPs, the Agent may be configured with Parameters for reaching a particular Controller across more than one MTP. When an Agent needs to send a Notification to such a Controller, the Agent can be designed (or possibly configured) to select a particular MTP, to try sending the Notification to the Controller on all MTPs simultaneously, or to try MTPs sequentially. USP has been designed to allow Endpoints to recognize when they receive a duplicate Message and to discard any duplicates. Endpoints will always send responses on the same MTP where the Message was received.
4.1.2 Securing MTPs
This specification places the following requirement for encrypting MTP headers and payloads on USP implementations that are intended to be used in environments where USP Messages will be transported across the Internet:
R-MTP.0 – The Message Transfer Protocol MUST use secure transport when USP Messages cross inter-network boundaries.
For example, it may not be necessary to use MTP layer security when within an end-user’s local area network (LAN). It is necessary to secure transport to and from the Internet, however. If the device implementer can reasonably expect Messages to be transported across the Internet when the device is deployed, then the implementer needs to ensure the device supports encryption of all MTP protocols.
MTPs that operate over TCP will be expected to implement, at least, TLS 1.2 as defined in [19].
Specific requirements for implementing these are provided in the individual MTP sections.
R-MTP.1 – When TLS is used to secure an MTP, an Agent MUST require the MTP peer to provide an X.509 certificate.
R-MTP.2 - An Agent capable of obtaining absolute time SHOULD wait until it has accurate absolute time before establishing TLS encryption to secure MTP communication. If an Agent for any reason is unable to obtain absolute time, it can establish TLS without waiting for accurate absolute time. If an Agent chooses to establish TLS before it has accurate absolute time (or if it does not support absolute time), it MUST ignore those components of the received X.509 certificate that involve absolute time, e.g. not-valid-before and not-valid-after certificate restrictions.
R-MTP.3 - An Agent that has obtained an accurate absolute time MUST validate those components of the received X.509 certificate that involve absolute time.
R-MTP.4 - When an Agent receives an X.509 certificate while establishing TLS encryption of the MTP, the Agent MUST execute logic that achieves the same results as in the mandatory decision flow elements (identified with “MUST”) from Figure 2.
R-MTP.4a - When an Agent receives an X.509 certificate while establishing TLS encryption of the MTP, the Agent SHOULD execute logic that achieves the same results as in the optional decision flow elements (identified with “OPT”) from Figure 2.
Note: The .local and .home.arpa domains are defined by the IETF as “Special-Use Domains” for use inside any LAN. It is not possible for an external Certificate Authority (CA) to vouch for whether a LAN device “owns” a particular name in one of these domains (inside a particular LAN) and these LAN networks have no internal CA. Therefore, it is not possible to validate FQDNs within these domains. The Internet Assigned Numbers Authority (IANA) maintains a registry of Special Use Domains.
4.1.3 USP Record Encapsulation
The USP Record is defined as the Message Transfer Protocol (MTP) payload, encapsulating a sequence of datagrams that comprise the USP Message as well as providing additional metadata needed for integrity protection, payload protection and delivery of fragmented USP Messages. Additional metadata fields are used to identify the E2E session context, determine the state of the segmentation and reassembly function, acknowledge received datagrams, request retransmissions, and determine the type of encoding and security mechanism used to encode the USP Message.
When not explicitly set or included in a USP Record or USP Message, the fields have a default value based on the type of field:
- For strings, the default value is the empty string.
- For bytes, the default value is empty bytes.
- For bools, the default value is
false
. - For numeric types, the default value is zero.
- For enums, the default value is the first defined enum value, which must be 0.
- For a
oneof
field, none of the allowed values are assumed if the field is absent. repeated
fields can be included any number of times, including zero.
If there is no requirement stating a field must be present, it is not necessary to include the field in a sent Record or Message. The receiving Endpoint will use default values for fields not included in a received Record or Message.
R-MTP.4b - Any field that is noted as “Required” in its description MUST be sent.
A Record or Message without a required field will fail to be processed by a receiving Endpoint. For additional information, default values (when fields are missing) are described in the “Default Values” section of Protocol Buffers [8].
<IP_ADDRESS> Record Definition
Note: This version of the specification defines the USP Record in Protocol Buffers v3. This part of the specification may change to a more generic description (normative and non-normative) if further encodings are specified in future versions.
string version
Required. Version (Major.Minor) of the USP Protocol (e.g., “1.3”).
Note: The version field is used for USP Endpoints to set expectations about their behavior for other USP Endpoints. A USP Endpoint that receives a Record indicating a version higher than it supports can expect to receive messages it may not understand or encounter other unexpected behavior. USP Endpoints are expected to handle these inconsistencies gracefully (For example, using the 7001 Message Not Supported Error).
string to_id
Required. Receiving/Target USP Endpoint Identifier.
string from_id
Required. Originating/Source USP Endpoint Identifier.
enum PayloadSecurity payload_security
Optional. An enumeration of type PayloadSecurity. When the payload is
present, this indicates the protocol or mechanism used to secure the
payload (if any) of the USP Message. The value of TLS12
means TLS 1.2 or later (with backward compatibility to TLS 1.2) will be
used to secure the payload (see TLS Payload Encapsulation for more information).
Valid values are:
PLAINTEXT (0)
TLS12 (1)
bytes mac_signature
Optional. When integrity protection of non-payload fields is performed, this is the message authentication code or signature used to ensure the integrity of the non-payload fields of the USP Record.
bytes sender_cert
Optional. The PEM encoded certificate, or certificate chain, of the
sending USP Endpoint used to provide the signature in the
mac_signature
field, when integrity protection is used and
the payload security mechanism doesn’t provide the mechanism to generate
the mac_signature
.
oneof record_type
Required. This field contains one of the types given below:
NoSessionContextRecord no_session_context
SessionContextRecord session_context
WebSocketConnectRecord websocket_connect
MQTTConnectRecord mqtt_connect
STOMPConnectRecord stomp_connect
UDSConnectRecord uds_connect
DisconnectRecord disconnect
<IP_ADDRESS>.1 NoSessionContextRecord fields
The following describe the fields included if
record_type
is no_session_context
.
bytes payload
Required. The USP Message.
<IP_ADDRESS>.2 SessionContextRecord fields
The following describe the fields included if
record_type
is session_context
.
uint64 session_id
Required. This field is the Session Context identifier.
uint64 sequence_id
Required. Datagram sequence identifier. Used only for exchange of USP Records with an E2E Session Context. The field is initialized to 1 when starting a new Session Context and incremented after each sent USP Record.
Note: Endpoints maintain independent values for received and sent sequence_id for a Session Context, based respectively on the number of received and sent Records.
uint64 expected_id
Required. This field contains the next sequence_id
the
sender is expecting to receive, which implicitly acknowledges to the
recipient all transmitted datagrams less than expected_id
.
Used only for exchange of USP Records with an E2E Session Context.
uint64 retransmit_id
Optional. Used to request a USP Record retransmission by a USP
Endpoint to request a missing USP Record using the missing USP Record’s
anticipated sequence_id
. Used only for exchange of USP
Records with an E2E Session Context. Will be received as 0
when no retransmission is requested.
enum PayloadSARState payload_sar_state
Optional. An enumeration of type PayloadSARState. When payload is present, indicates the segmentation and reassembly state represented by the USP Record. Valid values are:
NONE (0)
BEGIN (1)
INPROCESS (2)
COMPLETE (3)
enum PayloadSARState payloadrec_sar_state
Optional. An enumeration of type PayloadSARState. When payload
segmentation is being performed, indicates the segmentation and
reassembly state represented by an instance of the payload datagram. If
payload_sar_state
= 0
(or is not included or
not set), then payloadrec_sar_state
will be 0
(or not included or not set). Valid values are:
NONE (0)
BEGIN (1)
INPROCESS (2)
COMPLETE (3)
repeated bytes payload
Optional. This repeated field is a sequence of zero, one, or multiple
datagrams. It contains the Message, in either PLAINTEXT
or
encrypted format. When using TLS12
payload security, this
contains the encrypted TLS records, either sequentially in a single
payload
field, or divided into multiple
payload
fields. When using PLAINTEXT
payload
security there will be a single payload
field for any
Message being sent.
<IP_ADDRESS>.3 WebSocketConnectRecord fields
This Record type has no fields.
<IP_ADDRESS>.4 MQTTConnectRecord fields
The following describe the fields included if
record_type
is mqtt_connect
.
enum MQTTVersion version
Required. The MQTT protocol version used by the USP Endpoint to send this Record. Valid values are:
V3_1_1 (0)
V5 (1)
string subscribed_topic
Required. A MQTT Topic where the USP Endpoint sending this Record can be reached (i.e. a non-wildcarded MQTT Topic it is subscribed to).
<IP_ADDRESS>.5 STOMPConnectRecord fields
The following describe the fields included if
record_type
is stomp_connect
.
enum STOMPVersion version
Required. The STOMP protocol version used by the USP Endpoint to send this Record. Valid values are:
V1_2 (0)
string subscribed_destination
Required. A STOMP Destination where the USP Endpoint sending this Record can be reached (i.e. a STOMP Destination it is subscribed to).
<IP_ADDRESS>.6 UDSConnectRecord fields
This Record type has no fields.
<IP_ADDRESS>.7 DisconnectRecord fields
The following describe the fields included if
record_type
is disconnect
.
fixed32 reason_code
Optional. A code identifying the reason of the disconnect.
string reason
Optional. A string describing the reason of the disconnect.
4.1.4 USP Record Errors
A variety of errors can occur while establishing and during a USP communication flow. In order to signal such problems to the other Endpoint while processing an incoming E2E Session Context Record or a Record containing a Message of the type Request, an Endpoint encountering such a problem can create a USP Record containing a Message of type Error and transmit it over the same MTP and connection which was used when the error was encountered.
For this mechanism to work and to prevent information leakage, the sender causing the problem needs to be able to create a valid USP Record containing a valid source Endpoint ID and a correct destination Endpoint ID. In addition a MTP specific return path needs to be known so the error can be delivered.
R-MTP.5 - A recipient of an erroneous USP Record MUST create a Record with a Message of type Error and deliver it to sender if the source Endpoint ID is valid, the destination Endpoint ID is its own, the Record contains a USP Message of type Request, the Message ID can be extracted, and a MTP-specific return path is known. If any of those criteria on the erroneous Record are not met, it MUST be ignored.
The following error codes (in the range 7100-7199) are defined to allow the Error to be more specifically indicated. Additional requirements for these error codes are included in the specific MTP definition, where appropriate.
| Code | Name | Description |
|---|---|---|
7100 |
Record could not be parsed | This error indicates the received USP Record could not be parsed. |
7101 |
Secure session required | This error indicates USP layer Secure Message Exchange is required. |
7102 |
Secure session not supported | This error indicates USP layer Secure Message Exchange was indicated in the received Record but is not supported by the receiving Endpoint. |
7103 |
Segmentation and reassembly not supported | This error indicates segmentation and reassembly was indicated in the received Record but is not supported by the receiving Endpoint. |
7104 |
Invalid Record value | This error indicates the value of at least one Record field was invalid. |
7105 |
Session Context terminated | This error indicates an existing Session Context Establishing an E2E Session Context is being terminated. |
7106 |
Session Context not allowed | This error indicates use of Session Context Establishing an E2E Session Context is not allowed or not supported. |
4.1.5 Connect and Disconnect Record Types
A Connect Record is a subgroup of Record types
(record_type
), there is one Record type per USP MTP in this
subgroup. These Records are used to assert the USP Agent presence and
exchange needed information for proper start of communication between
Agent and Controller, the presence information is specifically useful
when using brokered MTPs.
R-MTP.6 - If a USP Agent has the necessary information to create a Connect Record, it MUST send the associated Connect Record, specific for the MTP in use, after it has successfully established an MTP communications channel to a USP Controller.
The DisconnectRecord
is a Record type used by a USP
Agent to indicate it wishes to end an on-going communication with a USP
Controller. It can be used for presence information, for sending
supplemental information about the disconnect event and to force the
remote USP Endpoint to purge some cached information about the current
session.
R-MTP.7 - The USP Agent SHOULD
send a DisconnectRecord
to the USP Controller before
disconnecting from an MTP communications channel. Upon receiving a
DisconnectRecord
, a USP Controller MUST clear all cached
information relative to an existing E2E Session Context with that
Endpoint, including the information that a previous E2E Session Context
was established.
It is not mandatory for a USP Endpoint to close its MTP connection
after sending or receiving a DisconnectRecord
.
R-MTP.8 - After sending or
receiving a DisconnectRecord
and maintaining the underlying
MTP communications channel or after establishing a new MTP
communications channel, the USP Endpoint MUST send or receive the
correct Connect Record type before exchanging any other USP Records.
R-MTP.9 - A
DisconnectRecord
SHOULD include the
reason_code
and reason
fields with an
applicable code from USP Record Errors.
4.2 CoAP Binding (OBSOLETED)
Note: The CoAP MTP was deprecated in USP 1.2. Due to the way it is specified this MTP can only be used in local area networks under narrow conditions. Please see Section 4.3 for a suitable alternative.
Note: The CoAP MTP was obsoleted in USP 1.3 as a natural progression from being deprecated in USP 1.2.
The Constrained Application Protocol (CoAP) MTP transfers USP Records between USP Endpoints using the CoAP protocol as defined in RFC 7252 [30]. Messages that are transferred between CoAP clients and servers utilize a request/response messaging interaction based on RESTful architectural principles. The following figure depicts the transfer of the USP Records between USP Endpoints.
In this example, a USP Request is encoded within a USP Record and encapsulated within a CoAP request message. When a USP Endpoint receives the CoAP request message the USP Endpoint immediately sends a CoAP response message (with no USP Record) to indicate receipt of the message. A USP Response encoded within a USP Record is encapsulated in a new CoAP request message. When the USP Endpoint receives the USP Response, it sends a CoAP response message that indicates receipt of the message. Therefore, all Endpoints supporting CoAP will implement both CoAP client and server.
As noted in the definition of a USP Request, this USP Record either requests the Agent perform some action (create, update, delete, operate, etc.), requests information about an Agent or one or more Service Elements, or acts as a means to deliver Notifications from the Agent to the Controller. Notifications will only cause a USP Response to be generated if specified in the Notification Request. However, the CoAP response will always be sent.
4.2.1 Mapping USP Endpoints to CoAP URIs
Section 6 of RFC 7262 [30] discusses the URI schemes for identifying CoAP resources and provides a means of locating the resource. These resources are organized hierarchically and governed by a CoAP server listening for CoAP requests on a given port. USP Endpoints are one type of CoAP resource that is identified and discovered.
R-COAP.0 - As the USP Endpoint is a resource governed by a CoAP server, the CoAP server MUST also be identified as defined in section 6 of RFC 7262 [30].
R-COAP.1 - A USP Endpoint MUST be represented as a CoAP resource with the following resource attributes:
- Identifier within the CoAP server (uri-path)
- Resource type (rt): “
bbf.usp.endpoint
” - Interface (if): “
bbf.usp.c
” for USP Controller or “bbf.usp.a
” for USP Agent
The identifier within the CoAP server is used to deliver messages to the USP Endpoint. When this identifier is used to deliver messages to the USP Endpoint, this identifier is a uri-path that represents the USP Endpoint.
R-COAP.2 - A CoAP request message
MUST include a Uri-Query option that supplies the CoAP server URI of the
Endpoint that is the source of the CoAP request, formatted as
?reply-to=<coap or coaps uri>
. The coap and coaps
URIs are defined in sections 6.1 and 6.2 of RFC 7262 [30]. The URI MUST NOT include any
optional queries at the end.
R-COAP.2a - When a USP Endpoint receives a CoAP request message it MUST use the reply-to Uri-Query option included in the CoAP request as the CoAP URI for the USP Response (if a response is required by the incoming USP Request).
R-COAP.3 - When creating DNS-SD records (see DNS-SD Records), an Endpoint MUST set the DNS-SD TXT record “path” attribute equal to the value of the CoAP server identifier (uri-path).
4.2.2 Mapping USP Records to CoAP Messages
R-COAP.4 - In order for USP Records to be transferred between a USP Controller and Agent using CoAP, the USP Record MUST be encapsulated within the CoAP message as defined in RFC 7262 [30].
R-COAP.5 – USP Records that exceed the CoAP message size MUST be block encapsulated in accordance with [32].
USP Records are transferred using the CoAP resource that represents the receiving USP Endpoint using the CoAP POST method as defined in RFC 7252.
R-COAP.6 - The CoAP Content-Format for USP Records MUST be application/octet-stream (ID=42) for Message Encoding.
R-COAP.7 - Upon successful
reception of the CoAP message using POST, the CoAP server MUST respond
with a response code of 2.04 (Changed)
.
<IP_ADDRESS> Handling CoAP Request Failures
At times CoAP requests fail to complete due to problems in the underlying transport (e.g., timeout) or a failure response code received from the CoAP server due to problems in the CoAP request sent by the CoAP client (4.xx) or problems with the CoAP server implementation (5.xx).
R-COAP.8 - CoAP clients and servers MUST implement the required CoAP response codes defined in section 5.9 of RFC 7262 [30].
R-COAP.9 - When a CoAP client receives a failure indication (e.g., timeout) from the underlying transport layer, the CoAP client MUST indicate a timeout to the USP Endpoint.
R-COAP.10 - When a CoAP client receives a response code of 4.xx or 5.xx, the CoAP client MUST indicate a CoAP failure to the USP Endpoint.
When a CoAP client sends a CoAP request, the CoAP client can provide incorrect or missing information in the CoAP request. For example, a CoAP client can send a CoAP request with an:
- Invalid CoAP method: The CoAP server responds with a
4.05
- Invalid Content-Format options: The CoAP server responds with a
4.15
- Invalid or not understandable payload: The CoAP server responds with
a
4.00
R-COAP.11 - When a CoAP server
receives a CoAP request with an invalid CoAP method, the CoAP server
MUST respond with a 4.05
response code.
R-COAP.12 - When a CoAP server
receives a CoAP request with an invalid CoAP Content-Format option, the
CoAP server MUST respond with a 4.15
response code.
R-COAP.13 - When a CoAP server
receives a CoAP request and the receiving USP Endpoint cannot interpret
or decode the USP Record for processing, the CoAP server MUST respond
with a 4.00
response code.
4.2.3 MTP Message Encryption
CoAP MTP message encryption is provided using DTLS as described in Section 9 of RFC 7262 [30].
In section 9 of RFC 7262 [30], CoAP messages are secured using one of three modes:
- NoSec: DTLS is disabled
- PreSharedKey: DTLS is enabled and the MTP endpoint uses pre-shared keys that are used to validate the identity of CoAP endpoints involved in the message exchange
- RawPublicKey: DTLS is enabled and the MTP endpoint has an asymmetric key pair without a certificate. The MTP endpoint has an identity calculated from the public key and a list of other MTP endpoints to which it can communicate
- Certificate: DTLS is enabled and the MTP endpoint has an asymmetric key pair with an X.509 certificate.
R-COAP.14 - CoAP clients and servers MUST implement the NoSec and Certificate modes of CoAP security as defined in RFC 7262 [30].
While section 9 of RFC 7262 [30] provides guidance on securing CoAP, further guidance related to DTLS implementations for the Internet of Things is provided by RFC 7925 [31].
R-COAP.15 - CoAP clients and servers MUST implement the mandatory statements of RFC 7925 [31] with the exception that:
- Section 4.4.1 USP Controller certificates can contain domain names with wildcard characters per RFC 6125 [23] guidance.
- Section 4.4.2 Client certificate identifiers do not use EUI-64 identifier but instead use the identifier defined for Client certificates in this Working Text.
- Section 4.4.5 Client Certificate URLs are not required to be implemented.
As USP Endpoints play the role of both CoAP client and server; when the MTP is secured using the Certificate mode of CoAP Security, the USP Endpoint provides a X.509 certificate to the MTP peer.
R-COAP.16 – When the Certificate mode of CoAP is used to secure an MTP, a USP Endpoint MUST provide an X.509 certificate to the MTP peer.
Note that DTLS sessions established for an Endpoint’s CoAP client and CoAP server are distinct. Therefore, it is possible for CoAP to be encrypted in one direction and not the other. If this happens, the requirements and flows in Authentication and Authorization will dictate that Secure Message Exchange be used.
4.3 WebSocket Binding
The WebSockets MTP transfers USP Records between USP Endpoints using the WebSocket protocol as defined in RFC 6455 [24]. Messages that are transferred between WebSocket clients and servers utilize a request/response messaging interaction across an established WebSocket session.
4.3.1 Mapping USP Endpoints to WebSocket URIs
Section 3 of RFC 6455 discusses the URI schemes for identifying WebSocket origin servers and their target resources. These resources are organized hierarchically and governed by a WebSocket origin server listening for WebSocket messages on a given port. USP Endpoints are one type of WebSocket resource that is identified and discovered.
R-WS.1 - As the USP Endpoint is a resource governed by a WebSocket origin server, the WebSocket server MUST also be identified as defined in section 3 of RFC 6455 [24].
R-WS.2 - A USP Endpoint MUST be represented as a WebSocket resource using the path component as defined in section 3 of RFC 6455 [24].
R-WS.3 - When creating DNS-SD records (see Discovery), an Endpoint MUST set the DNS-SD TXT record “path” attribute equal to the value of the Websocket resource using the path component as defined in section 3 of RFC 6455 [24].
4.3.2 Handling of the WebSocket Session
When exchanging the USP Records across WebSockets MTPs, the two USP Endpoints establish a WebSocket session. These WebSocket sessions are expected to be long lived and are reused for subsequent USP Record exchange. A WebSocket session is established using a handshake procedure described in section 4 of RFC 6455. When a WebSocket connection is not longer necessary, the WebSocket connection is closed according to section 7 of RFC 6455. The following figure depicts a WebSocket session handshake that is originated by an Agent.
While WebSocket sessions can be established by either USP Controllers or USP Agents in many deployment scenarios (e.g. communication between USP Endpoints across the Internet), in general, USP Agents will establish the WebSocket session and not expose an open port toward the Internet for security reasons. Regardless of which entity establishes the WebSocket session, at most one (1) open WebSocket session is utilized between the USP Endpoints.
R-WS.4 - USP Endpoints that exchange USP Records MUST utilize at most one (1) open WebSocket session.
R-WS.5 - USP Agent MUST provide the capability to originate the establishment of a WebSocket session.
R-WS.6 - USP Agent MUST provide the capability to accept the establishment of a WebSocket session from a USP Controller.
Note: Requirement R-WS.6 was altered from a MAY to a MUST in USP 1.2 to ensure that the WebSocket MTP is suitable for the in-home communications use case.
R-WS.7 - A USP Endpoint MUST implement the WebSocket handshake protocol to establish a WebSocket connection as defined in section 4 of RFC 6455 [24].
R-WS.8 - A USP Endpoint MUST implement the procedures to close a WebSocket connection as defined in section 7 of RFC 6455 [24].
<IP_ADDRESS> Mapping USP Records to WebSocket Messages
During the establishment of the WebSocket session, the WebSocket
client informs the WebSocket server in the
Sec-WebSocket-Protocol
header about the type of USP Records
that will be exchanged across the established WebSocket connection. For
USP Records, the Sec-WebSocket-Protocol
header contains the
value v1.usp
. When presented with a
Sec-WebSocket-Protocol
header containing
v1.usp
, the WebSocket Server serving a USP Endpoint returns
v1.usp
in the response’s Sec-WebSocket-Protocol header. If
the WebSocket client doesn’t receive a
Sec-WebSocket-Protocol
header with a value of
v1.usp
, the WebSocket client does not establish the
WebSocket session.
When a WebSocket connection is being initiated with TLS, no USP
Record is sent until the TLS negotiation is complete. The WebSocket
server will be unable to identify the Endpoint ID of the client unless
it looks inside the certificate. To make it easier for the server to
identify the client, the request URI of the opening handshake contains a
key=value
pair in its query
component to
provide the Endpoint ID of the client. eid
is used as the
key to the pair, while the value is the Endpoint ID of the client,
e.g. eid=doc::agent
.
R-WS.9 - The WebSocket’s
handshake Sec-WebSocket-Protocol
header for exchange of USP
Records using the protocol-buffers encoding mechanism MUST be
v1.usp
.
R-WS.10 - A WebSocket client MUST
include the Sec-WebSocket-Protocol
header for exchange of
USP Records when initiating a WebSocket session.
R-WS.10a (DEPRECATED) - A
WebSocket client MUST include the Sec-WebSocket-Extensions
header with bbf-usp-protocol
WebSocket Extension and
extension parameter eid
equal to the client’s Endpoint ID
when initiating a WebSocket session.
Note: Requirement R-WS.10a was removed in USP 1.3, due to the impossibility of setting WebSocket Extensions in some environments.
R-WS.10b - A WebSocket client
MUST include its Endpoint ID, via a key=value
pair, in the
query component of the request URI in its opening handshake, defined in
section 1.3 of RFC 6455 [24]. The
key
part of the pair MUST have a value of eid
and the value
part MUST be the client’s Endpoint ID. This
pair MUST be separated from other query data by the &
character.
R-WS.11 - A WebSocket server that
supports USP Endpoints MUST include the
Sec-WebSocket-Protocol
header for exchange of USP Records
when responding to an initiation of a WebSocket session.
R-WS.11a - A WebSocket server
SHOULD include the Sec-WebSocket-Extensions
header with
bbf-usp-protocol
WebSocket Extension and extension
parameter eid
equal to the server’s Endpoint ID when
responding to an initiation of a WebSocket session that includes the
bbf-usp-protocol
extension.
R-WS.11b - WebSocket clients MUST
NOT consider WebSocket responses that do not include the
bbf-usp-protocol
WebSocket Extension to be an error.
R-WS.11c - WebSocket servers MUST
NOT consider WebSocket session initiation requests that do not include
the bbf-usp-protocol
WebSocket Extension to be an
error.
R-WS.12 - A WebSocket client MUST
NOT establish a WebSocket session if the response to a WebSocket session
initiation request does not include the
Sec-WebSocket-Protocol
header for exchange of USP Records
in response to an initiation of a WebSocket session.
R-WS.12a - A WebSocket server
MUST NOT establish a WebSocket session if the WebSocket session
initiation request does not include the
Sec-WebSocket-Protocol
header.
4.3.3 Handling of WebSocket Frames
RFC 6455 defines a number of type of WebSocket control frames (e.g., Ping, Pong, Close) and associated condition codes in order to maintain a WebSocket connection. In addition messages are transferred in WebSocket Data control frame.
R-WS.13 - A USP Endpoint MUST implement the WebSocket control frames defined in section 5.5 of RFC 6455 [24].
USP Records can be transferred between USP Controllers and USP Agents over an established WebSocket session. These USP Records are encapsulated within a binary WebSocket data frame as depicted by the figure below.
R-WS.14 - In order for USP Records to be transferred between a USP Controller and Agent using WebSockets MUST be encapsulated within as a binary WebSocket data frame as defined in section 5.6 of RFC 6455 [24].
R-WS.15 - USP Records are transferred between USP Endpoints using message body procedures as defined in section 6 of RFC 6455 [24].
<IP_ADDRESS> Handling Failures to Deliver USP Records
If a USP Endpoint receives a WebSocket frame containing a USP Record
that cannot be extracted for processing (e.g., text frame instead of a
binary frame, malformed USP Record or USP Record, bad encoding), the
receiving USP Endpoint notifies the originating USP Endpoint that an
error occurred by closing the WebSocket connection with a
1003
Status Code with the WebSocket Close frame.
R-WS.16 - A USP Endpoint that
receives a WebSocket frame containing a USP Record that cannot be
extracted for processing, the receiving USP Endpoint MUST terminate the
connection using a WebSocket Close frame with a Status Code of
1003
.
<IP_ADDRESS> Keeping the WebSocket Session Alive
Once a WebSocket session is established, the WebSocket session is expected to remain open for future exchanges of USP Records. The WebSocket protocol uses Ping and Pong control frames as a keep-alive session. Section 5.5 of RFC 6455 discusses the handling of Ping and Pong control frames.
R-WS.17 - A USP Agent MUST implement a WebSocket keep-alive mechanism by periodically sending Ping control frames and responding to received Ping control frames with Pong control frames as described in section 5.5 of RFC 6455 [24].
R-WS.18 - A USP Agent MUST provide the capability to assign a keep-alive interval in order to send Ping control frames to the remote USP Endpoint.
<IP_ADDRESS> WebSocket Session Retry
If for any reason a WebSocket Session is closed, the USP Endpoint will attempt to re-establish the WebSocket Session according to its session retry policy. For Controllers, this session retry policy is implementation specific.
R-WS.19 – When retrying to establish a WebSocket Session, the Agent MUST use the following retry algorithm to manage the WebSocket Session establishment procedure:
For Agents, the retry interval range is controlled by two variables (described in the table below): the minimum wait interval and the interval multiplier. The corresponding data model Parameter MAY be implemented to allow a USP Controller to change the values of these variables. The factory default values of these variables MUST be the default values listed in the Default column of the table below.
| Descriptive Name | Symbol | Default | Data Model Parameter Name |
|---|---|---|---|
| Minimum wait interval | m | 5 seconds | Device.LocalAgent.Controller.{i}.MTP.{i}.WebSocket.SessionRetryMinimumWaitInterval |
| Interval multiplier | k | 2000 | Device.LocalAgent.Controller.{i}.MTP.{i}.WebSocket.SessionRetryIntervalMultiplier |
| Retry Count | Default Wait Interval Range (min-max seconds) | Actual Wait Interval Range (min-max seconds) |
|---|---|---|
| #1 | 5-10 | m - m.(k/1000) |
| #2 | 10-20 | m.(k/1000) - m.(k/1000)^2 |
| #3 | 20-40 | m.(k/1000)^2 - m.(k/1000)^3 |
| #4 | 40-80 | m.(k/1000)^3 - m.(k/1000)^4 |
| #5 | 80-160 | m.(k/1000)^4 - m.(k/1000)^5 |
| #6 | 160-320 | m.(k/1000)^5 - m.(k/1000)^6 |
| #7 | 320-640 | m.(k/1000)^6 - m.(k/1000)^7 |
| #8 | 640-1280 | m.(k/1000)^7 - m.(k/1000)^8 |
| #9 | 1280-2560 | m.(k/1000)^8 - m.(k/1000)^9 |
| #10 and subsequent | 2560-5120 | m.(k/1000)^9 - m.(k/1000)^10 |
R-WS.20 – Once a WebSocket session is established between the Agent and the Controller, the Agent MUST reset the WebSocket MTP’s retry count to zero for the next WebSocket Session establishment.
R-WS.21 – If a reboot of the Agent occurs, the Agent MUST reset the WebSocket MTP’s retry count to zero for the next WebSocket Session establishment.
4.3.4 MTP Message Encryption
WebSocket MTP message encryption is provided using certificates in TLS as described in section 10.5 and section 10.6 of RFC 6455 [24].
R-WS.22 - USP Endpoints utilizing WebSockets clients and servers for message transport MUST implement the Certificate modes of TLS security as defined in sections 10.5 and 10.6 of RFC 6455 [24].
R-WS.23 - USP Endpoints capable of obtaining absolute time SHOULD wait until it has accurate absolute time before contacting the peer USP Endpoint. If a USP Endpoint for any reason is unable to obtain absolute time, it can contact the peer USP Endpoint without waiting for accurate absolute time. If a USP Endpoint chooses to contact the peer USP Endpoint before it has accurate absolute time (or if it does not support absolute time), it MUST ignore those components of the peer USP Endpoint’s WebScoket MTP certificate that involve absolute time, e.g. not-valid-before and not-valid-after certificate restrictions.
R-WS.24 - USP Controller certificates MAY contain domain names with wildcard characters per RFC 6125 [23] guidance.
4.4 STOMP Binding
The STOMP MTP transfers USP Records between USP endpoints using version 1.2 of the STOMP protocol [36], further referred to as “STOMP Specification”, or the Simple Text Oriented Message Protocol. Messages that are transferred between STOMP clients utilize a message bus interaction model where the STOMP server is the messaging broker that routes and delivers messages based on the destination included in the STOMP header.
The following figure depicts the transfer of the USP Records between USP Agents and Controllers.
The basic steps for any USP Endpoint that utilizes a STOMP MTP are:
- Negotiate TLS (if required/configured)
- Connect to the STOMP Server
- Maintain Heart Beats (if configured)
- Subscribe to a Destination
- Send USP Records
R-STOMP.0 - USP Agents utilizing
STOMP clients for message transport MUST support the
STOMPConn:1
and STOMPController:1
data model
profiles.
R-STOMP.1 - USP Agents utilizing
STOMP clients for message transport SHOULD support the
STOMPAgent:1
and STOMPHeartbeat:1
data model
profile.
4.4.1 Handling of the STOMP Session
When exchanging USP Records across STOMP MTPs, each USP Endpoint establishes a communications session with a STOMP server. These STOMP communications sessions are expected to be long lived and are reused for subsequent exchange of USP Records. A STOMP communications session is established using a handshake procedure as described in “Connecting a USP Endpoint to the STOMP Server” section below. A STOMP communications session is intended to be established as soon as the USP Endpoint becomes network-aware and is capable of sending TCP/IP messages.
When a STOMP communications session is no longer necessary, the STOMP
connection is closed by the STOMP client, preferably by sending a
DISCONNECT
frame (see “Handling Other STOMP Frames” section
below).
<IP_ADDRESS> Connecting a USP Endpoint to the STOMP Server
R-STOMP.2 - USP Endpoints
utilizing STOMP clients for message transport MUST send a
STOMP
frame to the STOMP server to initiate the STOMP
communications session as defined in the “Connecting” section of the
STOMP Specification.
R-STOMP.3 - USP Endpoints that DO
NOT utilize client certificate authentication MUST include the login and
passcode STOMP headers in the STOMP frame. For a USP Agent, if the
.STOMP.Connection.{i}.Username
Parameter is implemented
then its value will be the source for the login
STOMP
header, and if the .STOMP.Connection.{i}.Password
Parameter
is implemented then its value will be the source for the
passcode
STOMP header.
R-STOMP.4 - USP Endpoints sending
a STOMP
frame MUST include (in addition to other mandatory
STOMP headers) an endpoint-id
STOMP header containing the
Endpoint ID of the USP Endpoint sending the frame. Note: According
to the STOMP Specification, the STOMP
frame requires that
“C style literal escapes” need to be used to encode any carriage return,
line feed, or colon characters that are found within the UTF-8 encoded
headers, and R-STOMP.4
requires the Endpoint ID to be included in those headers. Since the
Endpoint ID always contains colon characters, those will need to be
escaped.
R-STOMP.5 - USP Endpoints sending
a STOMP frame MUST include a host STOMP header, if configured to do so.
For a USP Agent the value MUST contain the value from the appropriate
.STOMP.Connection.{i}.VirtualHost
Parameter if supported
and not empty.
R-STOMP.6 - If the USP Endpoint
receives a subscribe-dest
STOMP header in the
CONNECTED
frame, it MUST use the associated value when
Subscribing to its destination (see “Subscribing a USP Endpoint to a
STOMP Destination” section for more details).
R-STOMP.7 - If the connection to
the STOMP server is NOT successful then the USP Endpoint MUST enter a
connection retry state. For a USP Agent the retry mechanism is based on
the STOMP.Connection.{i}.
retry Parameters:
ServerRetryInitialInterval
,
ServerRetryIntervalMultiplier
, and
ServerRetryMaxInterval
.
<IP_ADDRESS> Handling the STOMP Heart Beat Mechanism
The STOMP Heart Beat mechanism can be used to periodically send data between a STOMP client and a STOMP server to ensure that the underlying TCP connection is still available. This is an optional STOMP mechanism and is negotiated when establishing the STOMP connection.
R-STOMP.8 - If the
STOMP.Connection
instance’s EnableHeartbeats
Parameter value is true then the USP Agent MUST negotiate the STOMP
Heart Beat mechanism within the STOMP
frame during the
process of establishing the STOMP connection as is defined in the
“Heart-beating” section of the STOMP Specification.
R-STOMP.9 - If the
STOMP.Connection
instance’s EnableHeartbeats
Parameter value is either false or not implemented then the USP Agent
MUST either not send the heart-beat
STOMP header in the
STOMP
frame or send “0,0” as the value of the
heart-beat
STOMP header in the STOMP
frame.
R-STOMP.10 - USP Agents
negotiating the STOMP Heart Beat mechanism MUST use the
STOMP.Connection.{i}.OutgoingHeartbeat
and
STOMP.Connection.{i}.IncomingHeartbeat
Parameter values
within the heart-beat
STOMP header as defined in the
“Heart-beating” section of the STOMP Specification.
R-STOMP.11 - USP Agents that have
negotiated a STOMP Heart Beat mechanism with a STOMP server MUST adhere
to the heart beat values (as defined in the “Heart-beating” section of
the STOMP Specification) as returned in the CONNECTED
frame.
4.4.2 Mapping USP Endpoints to STOMP Destinations
USP Agents will have one STOMP destination per STOMP MTP independent
of whether those STOMP MTPs use the same STOMP.Connection
instance or a different one. The STOMP destination is either configured
by the STOMP server via the USP custom subscribe-dest
STOMP
Header received in the CONNECTED
frame (exposed in the
Device.LocalAgent.MTP.{i}.STOMP.DestinationFromServer
Parameter) or taken from the
Device.LocalAgent.MTP.{i}.STOMP.Destination
Parameter if
there wasn’t a subscribe-dest
STOMP Header received in the
CONNECTED
frame. The USP custom subscribe-dest
STOMP Header is helpful in scenarios where the USP Agent doesn’t have a
pre-configured destination as it allows the USP Agent to discover the
destination.
A USP Controller will subscribe to a STOMP destination for each STOMP
server that it is associated with. The USP Controller’s STOMP
destination needs to be known by the USP Agent (this is configured in
the
Device.LocalAgent.Controller.{i}.MTP.{i}.STOMP.Destination
Parameter) as it is used when sending a USP Record containing a
Notification.
<IP_ADDRESS> Subscribing a USP Endpoint to a STOMP Destination
R-STOMP.12 - USP Endpoints
utilizing STOMP clients for message transport MUST subscribe to their
assigned STOMP destination by sending a SUBSCRIBE
frame to
the STOMP server as defined in the “SUBSCRIBE” section of the STOMP
Specification.
R-STOMP.13 - USP Endpoints
sending a SUBSCRIBE
frame MUST include (in addition to
other mandatory STOMP headers) a destination
STOMP header
containing the STOMP destination associated with the USP Endpoint
sending the frame.
R-STOMP.14 - USP Agents that
receive a subscribe-dest
STOMP Header in the
CONNECTED
frame MUST use that STOMP destination in the
destination
STOMP header when sending a
SUBSCRIBE
frame.
R-STOMP.15 - USP Agents that have
NOT received a subscribe-dest
STOMP Header in the
CONNECTED
frame MUST use the STOMP destination found in the
Device.LocalAgent.MTP.{i}.STOMP.Destination
Parameter in
the destination
STOMP header when sending a
SUBSCRIBE
frame.
R-STOMP.16 - USP Agents that have
NOT received a subscribe-dest
STOMP Header in the
CONNECTED
frame and do NOT have a value in the
Device.LocalAgent.MTP.{i}.STOMP.Destination
Parameter MUST
terminate the STOMP communications session (preferably via the
DISCONNECT
frame) and enter a connection retry state
following R-STOMP.7.
R-STOMP.17 - USP Endpoints
sending a SUBSCRIBE
frame MUST use an ack
value of “auto”.
4.4.3 Mapping USP Records to STOMP Frames
A USP Record is sent from a USP Endpoint to a STOMP Server within a
SEND
frame. The STOMP Server delivers that USP Record to
the destination STOMP Endpoint within a MESSAGE
frame. When
a USP Endpoint responds to the USP request, the USP Endpoint sends the
USP Record to the STOMP Server within a SEND
frame, and the
STOMP Server delivers that USP Record to the destination USP Endpoint
within a MESSAGE
frame.
R-STOMP.18 - USP Endpoints
utilizing STOMP clients for message transport MUST send USP Records in a
SEND
frame to the STOMP server as defined in the “SEND”
section of the STOMP Specification.
R-STOMP.19 - USP Endpoints
sending a SEND
frame MUST include (in addition to other
mandatory STOMP headers) a content-length
STOMP header
containing the length of the body included in the SEND
frame.
R-STOMP.20 - USP Endpoints
sending a SEND
frame MUST include (in addition to other
mandatory STOMP headers) a content-type
STOMP header with a
value of “application/vnd.bbf.usp.msg
”, which signifies
that the body included in the SEND
frame contains a
Protocol Buffer [8] binary encoding
message.
R-STOMP.21 - USP Endpoints
sending a SEND
frame with content-type of
application/vnd.bbf.usp.msg
MUST include (in addition to
other mandatory STOMP headers) a reply-to-dest
STOMP header
containing the STOMP destination that indicates where the USP Endpoint
that receives the USP Record should send any response (if required).
R-STOMP.22 - USP Endpoints
sending a SEND
frame with content-type of
application/vnd.bbf.usp.msg
MUST include the Protocol
Buffer [8] binary encoding
of the USP Record as the body of the SEND
frame.
R-STOMP.23 - When a USP Endpoint
receives a MESSAGE
frame it MUST use the
reply-to-dest
included in the STOMP headers as the STOMP
destination of the USP response (if a response is required by the
incoming USP request).
<IP_ADDRESS> Handling Errors
If a STOMP USP Endpoint receives a MESSAGE
frame
containing a USP Record that cannot be extracted for processing (e.g.,
text frame instead of a binary frame, malformed USP Record, bad
encoding), it will silently drop the unprocessed USP Record. If the
requirements according to USP Record Errors are fulfilled, for the STOMP MTP
specifically this means that the reply-to-dest
information
has to be available, then a USP Record with an appropriate Error Message
must be created and transmitted via STOMP SEND
frame.
Note: Error handling was unified between MTPs in USP 1.2 by using USP Records instead of MTP specific messages, deprecating most of this section, specifically the requirements R-STOMP.23a, R-STOMP.23b, R-STOMP.24, R-STOMP.24a and R-STOMP.24b. Please see USP Record Errors for details.
R-STOMP.23a (DEPRECATED) - USP
Endpoints MUST support STOMP content-type header value of
application/vnd.bbf.usp.error
.
Note: Requirement R-STOMP.23a was removed in USP 1.2
R-STOMP.23b (DEPRECATED) - A USP
Endpoint MUST include a usp-err-id
STOMP header in
SEND
frames of content-type
application/vnd.bbf.usp.msg
. The value of this header is:
<USP Record to_id> + "/" + <USP Message msg_id>
,
the <USP Message msg_id>
field can be left blank if
the Record does not contain a USP Message. Since the colon
“:
” is a reserved character in STOMP headers, all instances
of “:
” in the USP Record to_id MUST be expressed using an
encoding of \c
.
Note: Requirement R-STOMP.23b was removed in USP 1.2
R-STOMP.24 (DEPRECATED) - When a
USP Endpoint receives a MESSAGE
frame containing a USP
Record or an encapsulated USP Message within a USP Record that cannot be
extracted for processing, the receiving USP Endpoint MUST ignore the USP
Record if the received STOMP MESSAGE frame did not include a
usp-err-id
header.
Note: Requirement R-STOMP.24 was removed in USP 1.2
R-STOMP.24a (DEPRECATED) - When a
USP Endpoint receives a MESSAGE frame containing a USP Record or an
encapsulated USP Message within a USP Record that cannot be extracted
for processing, the receiving USP Endpoint MUST send a STOMP SEND frame
with an application/vnd.bbf.usp.error
content-type header
value if the received STOMP MESSAGE frame included a
usp-err-id
header.
Note: Requirement R-STOMP.24a was removed in USP 1.2
R-STOMP.24b (DEPRECATED) - A
STOMP SEND frame with application/vnd.bbf.usp.error
content-type MUST contain the received usp-err-id
header,
the destination header value set to the received
reply-to-dest
header, and a message body (formatted using
UTF-8 encoding) with the following 2 lines:
err_code:<numeric code indicating the type of error that caused the overall message to fail>
err_msg:<additional information about the reason behind the error>
The specific error codes are listed in the MTP USP Record Errors section.
The following is an example message. This example uses
“^@
” to represent the NULL octet that follows a STOMP
body.
SEND
destination:/usp/the-reply-to-dest
content-type:application/vnd.bbf.usp.error
usp-err-id:cid\c3AA3F8\cusp-id-42/683
err_code:7100
err_msg:Field n is not recognized.^@
Note: Requirement R-STOMP.24b was removed in USP 1.2
R-STOMP.25 - If an
ERROR
frame is received by the USP Endpoint, the STOMP
server will terminate the connection. In this case the USP Endpoint MUST
enter a connection retry state. For a USP Agent the retry mechanism is
based on the STOMP.Connection.{i}.
retry Parameters:
ServerRetryInitialInterval
,