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 UDP will be expected to implement, at least, DTLS 1.2 as defined in [22].

MTPs that operate over TCP will be expected to implement, at least, TLS 1.2 as defined in [17].

Specific requirements for implementing these are provided in the individual MTP sections.

R-MTP.1 – When TLS or DTLS 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 or DTLS encryption to secure MTP communication. If an Agent for any reason is unable to obtain absolute time, it can establish TLS or DTLS without waiting for accurate absolute time. If an Agent chooses to establish TLS or DTLS 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 or DTLS 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 or DTLS 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.

Figure 2: Receiving a X.509 Certificate

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 Message 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.

Following are the fields contained within a USP Record. When not explicitly set or included in the Record, the fields have a default value based on the type of field. For strings, the default value is an empty byte string. For numbers (uint64) and enumerations, the default value is 0. For repeated bytes, the default value is an empty byte string. The term “Optional” means it is not necessary to include the field in a sent Record. The receiving Endpoint will use default values for fields not included in a received Record. “Required” fields are always included. A Record without a “Required” field will fail to be processed by a receiving Endpoint. “Repeated” fields can be included any number of times, including zero.

4.1.3.1 Record Definition

Note: This version of the specification defines 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 (i.e., “1.0” or “1.1”).

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

DisconnectRecord disconnect

4.1.3.1.1 NoSessionContextRecord fields

The following describe the fields included if record_type is no_session_context.

bytes payload

Required. The USP Message.

4.1.3.1.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.

4.1.3.1.3 WebSocketConnectRecord fields

This Record type has no fields.

4.1.3.1.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 MQTT Topic it is subscribed to).

4.1.3.1.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).

4.1.3.1.6 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, and a MTP-specific return path is known. If any of those criteria on the erroneous Record are not met or the Record is known to contain a USP Message of types Response or Error, 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 (DEPRECATED)

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.

The Constrained Application Protocol (CoAP) MTP transfers USP Records between USP Endpoints using the CoAP protocol as defined in RFC 7252 [29]. 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.

Figure 3: Example: USP Request/Response over the CoAP MTP

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 [29] 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 [29].

R-COAP.1 - A USP Endpoint MUST be represented as a CoAP resource with the following resource attributes:

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 [29]. 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 [29].

R-COAP.5 – USP Records that exceed the CoAP message size MUST be block encapsulated in accordance with [31].

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).

4.2.2.1 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 [29].

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:

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 [29].

In section 9 of RFC 7262 [29], CoAP messages are secured using one of three modes:

R-COAP.14 - CoAP clients and servers MUST implement the NoSec and Certificate modes of CoAP security as defined in RFC 7262 [29].

While section 9 of RFC 7262 [29] provides guidance on securing CoAP, further guidance related to DTLS implementations for the Internet of Things is provided by RFC 7925 [30].

R-COAP.15 - CoAP clients and servers MUST implement the mandatory statements of RFC 7925 [30] with the exception that:

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 [23]. 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 [23].

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 [23].

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 [23].

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.

Figure 4: WebSocket Session Handshake

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 [23].

R-WS.8 - A USP Endpoint MUST implement the procedures to close a WebSocket connection as defined in section 7 of RFC 6455 [23].

4.3.2.1 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 WebSocket Extension bbf-usp-protocol has been registered. The extension parameter of eid is defined for use with this extension. The value of the eid parameter will be the Endpoint ID of the Endpoint sending the WebSocket header.

Note: When using an Endpoint ID as the value of the eid parameter in the Sec-WebSocket-Extensions header, it will need to be in the quoted-string form as referenced in section 9 of RFC 6455 [23].

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 - 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.

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 MUST 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 SHOULD NOT consider WebSocket responses that do not include the bbf-usp-protocol WebSocket Extension to be an error.

R-WS.11c - WebSocket servers SHOULD 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 [23].

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.

Figure 5: USP Request using a WebSocket Session

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 [23].

R-WS.15 - USP Records are transferred between USP Endpoints using message body procedures as defined in section 6 of RFC 6455 [23].

4.3.3.1 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.

4.3.3.2 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 [23].

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.

4.3.3.3 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 [23].

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 [23].

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 [21] guidance.

4.4 STOMP Binding

The STOMP MTP transfers USP Records between USP endpoints using version 1.2 of the STOMP protocol [35], 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.

Figure 6: USP over STOMP Architecture

The basic steps for any USP Endpoint that utilizes a STOMP MTP are:

  1. Negotiate TLS (if required/configured)
  2. Connect to the STOMP Server
  3. Maintain Heart Beats (if configured)
  4. Subscribe to a Destination
  5. 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).

4.4.1.1 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.

4.4.1.2 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.

4.4.2.1 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 [6] 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 [6] 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).

4.4.3.1 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:

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, ServerRetryIntervalMultiplier, and ServerRetryMaxInterval.

4.4.3.2 Handling Other STOMP Frames

R-STOMP.26 - USP Endpoints utilizing STOMP clients for message transport MUST NOT send the transactional STOMP frames including: BEGIN, COMMIT, and ABORT.

R-STOMP.27 - USP Endpoints utilizing STOMP clients for message transport MUST NOT send the acknowledgement STOMP frames including: ACK and NACK.

R-STOMP.28 - USP Endpoints utilizing STOMP clients for message transport MAY send the following STOMP frames when shutting down a STOMP connection: UNSUBSCRIBE (according to the rules defined in the UNSUBSCRIBE section of the STOMP Specification) and DISCONNECT (according to the rules defined in the DISCONNECT section of the STOMP Specification).

R-STOMP.29 - USP Endpoints utilizing STOMP clients for message transport that DID NOT receive a subscribe-dest STOMP Header in the CONNECTED frame when establishing the STOMP communications session MUST update their STOMP subscription when their destination is altered by sending the UNSUBSCRIBE STOMP frame (according to the rules defined in the UNSUBSCRIBE section of the STOMP Specification) and then re-subscribing as detailed in the “Subscribing a USP Endpoint to a STOMP Destination” section.

R-STOMP.30 - USP Endpoints utilizing STOMP clients for message transport MAY receive a RECEIPT frame in which case the STOMP server is acknowledging that the corresponding client frame has been processed by the server.

4.4.4 Discovery Requirements

The USP Discovery section details requirements about the general usage of DNS, mDNS, and DNS-SD records as it pertains to the USP protocol. This section provides further requirements as to how a USP Endpoint advertises discovery information when a STOMP MTP is being utilized.

R-STOMP.31 - When creating a DNS-SD record, an Endpoint MUST set the DNS-SD “path” attribute equal to the value of the destination that it has subscribed to.

R-STOMP.32 - When creating a DNS-SD record, an Endpoint MUST utilize the STOMP server’s address information in the A and AAAA records instead of the USP Endpoint’s address information.

4.4.5 STOMP Server Requirements

R-STOMP.33 - A STOMP server implementation MUST adhere to the requirements defined in the STOMP Specification.

R-STOMP.34 - A STOMP server implementation MUST perform authentication of the STOMP client and ensure that a Remote USP Endpoint is only allowed to subscribe to the destination that is associated with the USP Endpoint.

R-STOMP.35 - A STOMP server implementation SHOULD support both Client Certification Authentication and Username/Password Authentication mechanisms.

4.4.6 MTP Message Encryption

STOMP MTP message encryption is provided using TLS certificates.

R-STOMP.36 - USP Endpoints utilizing STOMP clients for message transport MUST implement TLS 1.2 RFC 5246 [17] or later with backward compatibility to TLS 1.2.

R-STOMP.37 - STOMP server certificates MAY contain domain names and those domain names MAY contain domain names with wildcard characters per RFC 6125 [21] guidance.

4.5 MQTT Binding

The Message Queuing Telemetry Transport (MQTT) MTP transfers USP Records between USP Endpoints using the MQTT protocol. Messages that are transferred between MQTT clients utilize a message bus interaction model where the MQTT server is the messaging broker that routes and delivers messages based on the Topic Name included in the MQTT Publish packet variable header.

The following figure depicts the transfer of the USP Records between USP Agents and Controllers.

Figure 7: USP over MQTT Architecture

The basic steps for any USP Endpoint that utilizes an MQTT MTP are:

The following figure shows the MQTT packets that have requirements in this section for their use when MQTT is a USP MTP.

Figure 8: MQTT Packets

R-MQTT.1 - USP Endpoints utilizing MQTT clients for message transport MUST implement MQTT 5.0 [5].

R-MQTT.2 - USP Endpoints utilizing MQTT clients for message transport MAY implement MQTT 3.1.1 [4].

Requirements in this MQTT MTP specification are common to both the MQTT 3.1.1 and MQTT 5.0 specifications unless an MQTT version is named.

The MQTT specifications are very complete and comprehensive in describing syntax and usage requirements of MQTT packets and behaviors. Therefore, none of those requirements are re-iterated in this specification. This specification only contains requirements unique to use of MQTT as a USP MTP. The above two requirements for compliance with the MQTT specifications are critical in developing an implementation compliant with this MQTT Binding specification. Wherever an MQTT packet or other functionality is mentioned in the requirements in this MQTT Binding specification, the requirement for compliance with the MQTT specification (R-MQTT.1 and R-MQTT.2) apply.

R-MQTT.3 - USP Agents utilizing MQTT clients for message transport MUST support MQTT over TCP transport protocol.

The MQTT specification also describes how MQTT can run over WebSockets. Deployments can choose to use MQTT over WebSockets, if they use MQTT clients and servers with support for this option. The TCP option is required to ensure interoperability.

R-MQTT.4 - USP Agents utilizing MQTT clients for message transport MUST support the MQTTClientCon:1, MQTTClientSubscribe:1, MQTTAgent:1, and MQTTController:1 data model profiles.

R-MQTT.5 - USP Agents utilizing MQTT clients for message transport SHOULD support the MQTTClientExtended:1 data model profile.

4.5.1 Connecting a USP Endpoint to the MQTT Server

When exchanging USP Records across MQTT MTPs, each USP Endpoint establishes a communications session with an MQTT server. These MQTT communications sessions are expected to be long-lived and are re-used for subsequent exchange of USP Records. An MQTT communications session is established using the procedure in this section. An MQTT communications session is intended to be established as soon as the USP Endpoint becomes network-aware and can send TCP/IP messages.

When an MQTT communications session is no longer necessary or expires (see “Keep Alive” section below), the MQTT connection is closed by the MQTT client, preferably by sending a DISCONNECT packet (see Handling Other MQTT Packets section below).

R-MQTT.1 and R-MQTT.2 require that all MQTT capabilities referenced in this section and its sub-sections are compliant with the MQTT specifications. Reading the MQTT specification is highly recommended to ensure the correct syntax and usage of MQTT packets and properties (CONNECT, CONNACK, User Name, Password, ClientId, User Property, Keep Alive, PINGREQ, PINGRESP, etc.).

R-MQTT.6 - USP Endpoints utilizing MQTT clients for message transport MUST send a CONNECT packet to the MQTT server to initiate the MQTT communications session.

R-MQTT.7 - USP Endpoints with a configured MQTT User Name and Password for use with this MQTT server MUST include these in the MQTT CONNECT packet. The .MQTT.Client.{i}.Username and .MQTT.Client.{i}.Password Parameter values (associated with this MQTT server) will be used for User Name and Password.

R-MQTT.8 - USP Endpoints MUST set the value of the CONNECT packet Client Identifier (ClientId) as follows:

R-MQTT.9 - An MQTT 5.0 client MUST save (in the .MQTT.Client.{i}.ClientID Parameter) an Assigned Client Identifier included in a CONNACK packet as its configured ClientId for future connections to the MQTT server.

R-MQTT.10 - If the connection to the MQTT 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 MQTT.Client.{i}. retry Parameters: ConnectRetryTime, ConnectRetryIntervalMultiplier, and ConnectRetryMaxInterval.

R-MQTT.11 - Once a USP Endpoint has successfully connected to an MQTT server, it MUST use the same ClientId for all subsequent connections with that server.

4.5.1.1 CONNECT Flags and Properties

The MQTT CONNECT packet has a number of flags and properties that can be set. The User Name and Password flags are set to 1 if these parameters are included. The use of the Will Retain, Will QoS, and Will Flag are left up to the deployment. They are not needed in order to use MQTT as a USP MTP and can be “0” if there is no deployment-specified need for them. The Clean Start flag can also be used according to deployment-specified needs. Configured values for these flags can be provided through the related .MQTT.Client.{i}. Parameters.

MQTT 3.1.1 does not provide a simple mechanism for a USP MQTT client to provide its Endpoint ID to the MQTT server. But the server does have other options, such as:

  1. Support Endpoint ID as ClientId.
  2. Get Endpoint ID from client TLS certificate.

MQTT 3.1.1 also does not provide a mechanism for the MQTT server to tell a client what Topic other Endpoints should use to send it a message (the “reply to” Topic). This information would need to be pre-configured or provided in some manner not specified here.

MQTT 5.0 includes additional properties that deployments can choose to use.

R-MQTT.12 - An MQTT 5.0 USP Endpoint MUST support setting the Request Response Information property to 1, and MUST support receiving the corresponding Response Information in the CONNACK packet.

The Response Information property is used by an MQTT 5.0 client as the Response Topic (which is the MQTT 5.0 PUBLISH packet property identifying the Topic to send a USP response to). The Response Information property requirements for use of the received Response Information are below in Sending the USP Record in a PUBLISH Packet Payload. Ensuring the client is subscribed to this Topic or a Topic Filter that includes this Topic is described in Subscribing to MQTT Topics.

R-MQTT.13 - An MQTT 5.0 USP Endpoint MUST include a User Property name-value pair in the CONNECT packet with name of “usp-endpoint-id” and value of this Endpoint’s USP Endpoint ID.

4.5.1.2 Keep Alive

The MQTT Keep Alive mechanism has several components:

The client can indicate the Server is not required to disconnect the Client on the grounds of inactivity by setting the CONNECT Keep Alive to zero (0). Note that WebSockets mechanisms can be used to keep the connection alive if MQTT is being run over WebSockets. Also note the server is allowed to disconnect the client at any time, regardless of Keep Alive value.

R-MQTT.14 - USP Endpoints with a configured Keep Alive value MUST include this in the MQTT CONNECT packet. The .MQTT.Client.{i}.KeepAliveTime Parameter value (associated with this MQTT server) will be used for the Keep Alive value.

Use of PINGREQ and PINGRESP for keeping sessions alive (or determining session aliveness) is as described in the MQTT specification. No additional requirements are provided for use of these packets in a USP context.

4.5.2 Subscribing to MQTT Topics

The SUBSCRIBE packet is sent by the MQTT client to subscribe to one or more Topics or Topic Filters. These are needed to allow the MQTT client to receive application messages. The MQTT client will receive all application messages published by other clients that are sent to a Topic that matches (either exactly or within a wildcarded Topic Filter) a subscribed-to Topic or Topic Filter. The MQTT server indicates in the SUBACK response packet whether the client has succeeded or failed to subscribe to each Topic or Topic Filter sent in the SUBSCRIBE packet.

USP Endpoints can be configured with one or more specific MQTT Topics or Topic Filters to subscribe to for each MQTT server they are associated with. In MQTT 5.0, a CONNACK User Property named “subscribe-topic” can be used to provide the client with Topic or Topic Filter values for the client to subscribe to. There is no similar capability in MQTT 3.1.1. This means configuration or some out-of-band mechanism are the only means of supplying subscription Topics or Topic Filters to an MQTT 3.1.1 client. An Agent will need to be configured with a Controller’s MQTT Topic (the Device.LocalAgent.Controller.{i}.MTP.{i}.MQTT.Topic Parameter is used to configure this), to send a Notification to that Controller.

R-MQTT.1 and R-MQTT.2 require that all MQTT capabilities referenced in this section and its sub-sections are compliant with the MQTT specifications. Reading the MQTT specification is highly recommended to ensure the correct syntax and usage of MQTT packets and properties (SUBSCRIBE, Topic Filter, QoS 0, QoS 1, QoS 2, etc.).

R-MQTT.15 - USP Endpoints that successfully connect to an MQTT server MUST send a SUBSCRIBE packet with all Topic Filters identified in the following list:

R-MQTT.16 - USP Agents that have NOT received a “subscribe-topic” User Property in the CONNACK and do NOT have a configured Topic Filter (Device.MQTT.Client.{i}.Subscription.{i}.Topic Parameter for this Client instance in the data model) MUST terminate the MQTT communications session (via the DISCONNECT packet) and consider the MTP disabled.

R-MQTT.17 - If a USP Endpoint does not successfully subscribe to at least one Topic, it MUST NOT publish a packet with a USP Record in its Application Message, and MUST disconnect from the MQTT server.

For each Topic listed in a SUBSCRIBE packet, the client will also provide a desired QoS level. See the MQTT specification (MQTT 3.1.1 [4] or MQTT 5.0 [5], Section 4.3) for description of the three QoS levels (QoS 0, QoS 1, QoS 2). The usefulness of these QoS levels in the context of USP depends on the particulars of the MQTT deployment. It is therefore up to the implementer / deployer to decide which QoS setting to use. In order to ensure deployments have the ability to use at least QoS 1, MQTT clients and servers are required to implement at least QoS 1 (see requirements in Sending the USP Record in a PUBLISH Packet Payload and MQTT Server Requirements).

4.5.3 Sending the USP Record in a PUBLISH Packet Payload

A USP Record is sent from a USP Endpoint to an MQTT Server within a PUBLISH packet payload. The MQTT Server delivers that PUBLISH packet to the destination MQTT client USP Endpoint. This is true of all USP Message types.

R-MQTT.1 and R-MQTT.2 require that all MQTT capabilities referenced in this section and its sub-sections are compliant with the MQTT specifications. Reading the MQTT specification is highly recommended to ensure the correct syntax and usage of MQTT packets and properties (PUBLISH, Content Type, Response Topic, etc.).

R-MQTT.18 - USP Endpoints utilizing MQTT clients for message transport MUST send the USP Record in the payload of a PUBLISH packet.

R-MQTT.19 - USP Endpoints MUST send USP Records using the Protocol Buffer [6] binary encoding of the USP Record.

R-MQTT.20 - USP Endpoints utilizing MQTT clients for message transport MUST support MQTT QoS 0 and QoS 1.

The USP Controller’s MQTT Topic needs to be known by any USP Agent expected to send a Notify message to the Controller.

The USP Agent will also need to know an exact Topic where it can be reached (and not just a Topic Filter) in order to provide a Controller with the Agent’s “reply to” Topic.

R-MQTT.21 - An MQTT 5.0 USP Endpoint that receives Response Information in the CONNACK packet MUST use this as its “reply to” Topic.

R-MQTT.22 - USP Endpoints MUST include a “reply to” Topic in all PUBLISH packets transporting USP Records.

R-MQTT.23 - USP Endpoints using MQTT 5.0 MUST include their “reply to” Topic in the PUBLISH Response Topic property.

R-MQTT.24 - USP Endpoints using MQTT 3.1.1 MUST include their “reply to” Topic after “/reply-to=” at the end of the PUBLISH Topic Name, with any “/” character in the Topic replaced by “%2F”.

For example, if a Controller’s “reply to” Topic is “usp/controllers/oui:00256D:my-unique-bbf-id-42”, and it is sending to an Agent whose Topic is “usp/agents/cid:3AA3F8:my-unique-usp-id-42”, the PUBLISH Topic Name for a USP Controller using an MQTT 3.1.1 client will be “usp/agents/cid:3AA3F8:my-unique-usp-id-42/reply-to= usp%2Fcontrollers%2Foui:00256D:my-unique-bbf-id-42”.

USP Endpoints that need to send a response to a received USP Record will need to determine the Topic Name to use in the responding PUBLISH packet.

R-MQTT.25 - USP Endpoints using MQTT 3.1.1 MUST interpret the portion of the received PUBLISH Topic Name following the last forward slash “/reply-to=” as the response Topic Name. Any instance of “%2F” in this received string MUST be replaced with “/”.

R-MQTT.26 - USP Endpoints using MQTT 5.0 MUST use the received PUBLISH Response Topic property as the response Topic Name.

When an USP Endpoint receives a MQTT 3.1.1 PUBLISH packet without “reply to” Topic or a USP Connect Record with a different MQTT version indicated in the version field of the mqtt_connect Record type, then a MQTT version mismatch between brokers involved in the MQTT communication has occurred.

R-MQTT.26a - If a MQTT version mismatch is encountered and the sender “reply to” Topic is known, the receiving Endpoint MUST handle this error according to Handling Errors and cease communication until the mismatch has been addressed by the sender.

R-MQTT.27 - USP Endpoints sending a USP Record using MQTT 5.0 MUST have “usp.msg” in the Content Type property.

MQTT clients using MQTT 3.1.1 will need to know to pass the payload to the USP Agent for handling. There is no indication in MQTT 3.1.1 of the payload application or encoding. an MQTT 3.1.1 deployment could choose to dedicate the MQTT connection to USP, or put something in the syntax of PUBLISH packet Topic Names that would indicate the payload is a USP Record.

R-MQTT.27a - USP Endpoints receiving a MQTT 5.0 PUBLISH packet MUST interpret the Content Type property of “usp.msg” or “application/vnd.bbf.usp.msg” (the registered USP Record MIME type) as indicating the packet contains a USP Record.

4.5.4 Handling Errors

The MQTT specification requires servers and clients to disconnect if there is a violation at the MQTT protocol layer.

If a MQTT USP Endpoint receives a PUBLISH packet containing a USP Record that cannot be extracted for processing (e.g. malformed USP Record or bad encoding), it will silently drop the unprocessed USP Record. If the requirements according to USP Record Errors are fulfilled, then a USP Record with an appropriate Error Message will be created and published.

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 R-MQTT.28, R-MQTT.29, R-MQTT.30, R-MQTT.31, R-MQTT.31a and R-MQTT.32. Please see USP Record Errors for details.

R-MQTT.28 (DEPRECATED) - MQTT 5.0 Endpoints MUST support PUBLISH Content Type value of “usp.error”.

Note: Requirement R-MQTT.28 was removed in USP 1.2

R-MQTT.29 (DEPRECATED) - MQTT 5.0 Endpoints MUST include a usp-err-id MQTT User Property in PUBLISH packets of content-type “usp.msg”. The value of this User Property 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.

Note: Requirement R-MQTT.29 was removed in USP 1.2

R-MQTT.30 (DEPRECATED) - When an MQTT 3.1.1 USP Endpoint receives a PUBLISH packet containing a USP Record or an encapsulated USP Message within a USP Record that cannot be extracted for processing, the receiving USP Endpoint MUST silently drop the USP Record.

Note: Requirement R-MQTT.30 was removed in USP 1.2

R-MQTT.31 (DEPRECATED) - When an MQTT 5.0 USP Endpoint receives a PUBLISH packet containing a USP Record or an encapsulated USP Message within a USP Record that cannot be extracted for processing and the PUBLISH packet contains a usp-err-id header, the receiving USP Endpoint MUST send a PUBLISH packet with Content Type “usp.error”, a User Property set to the received usp-err-id User Property, the Topic Name set to the received Response Topic, and a PUBLISH Payload (formatted using UTF-8 encoding) with the following 2 lines:

The specific error codes are listed in the MTP USP Record Errors section.

MQTT 5.0 includes a Reason Code that is used to respond to PUBLISH packets when QoS 1 or QoS 2 is used.

Note: Requirement R-MQTT.31 was removed in USP 1.2

R-MQTT.31a (DEPRECATED) - USP Endpoints receiving a MQTT 5.0 PUBLISH packet MUST interpret the Content Type property of “usp.error” or “application/vnd.bbf.usp.error” (the registered USP error message MIME type) as indicating the packet contains a USP error message and code.

Note: Requirement R-MQTT.31a was removed in USP 1.2

R-MQTT.32 (DEPRECATED) - When a USP Endpoint using MQTT 5.0 receives a PUBLISH packet with QoS 1 or QoS 2 containing a USP Record or an encapsulated USP Message within a USP Record that cannot be extracted for processing, the receiving USP Endpoint MUST include Reason Code 153 (0x99) identifying “Payload format invalid” in any PUBACK or PUBREC packet.

Note these packets will be received by the MQTT server and will not be forwarded to the USP Endpoint that originally sent the USP Record.

Note: Requirement R-MQTT.32 was removed in USP 1.2

R-MQTT.33 - If the MQTT server terminates the connection, the USP Endpoint MUST enter a connection retry state. For a USP Agent the retry mechanism is based on the MQTT.Client.{i}. ConnectRetryTime Parameter.

4.5.5 Handling Other MQTT Packets

Use of PUBREL, and PUBCOMP depends on the QoS level being used for the subscribed Topic. No additional requirements are provided for use of these packets in a USP context.

Use of PINGREQ and PINGRESP for keeping sessions alive (or determining session aliveness) is as described in the MQTT specification. No additional requirements are provided for use of these packets in a USP context.

Use of UNSUBSCRIBE and UNSUBACK is as described in the MQTT specification. If an Agent’s configured Topics are disabled by a Controller (by setting Device.MQTT.Client.{i}.Subscription.{i}.Enable to “false”), UNSUBSCRIBE is used to unsubscribe from them.

R-MQTT.34 - USP Endpoints utilizing MQTT clients for message transport SHOULD send an UNSUBSCRIBE packet when a subscribed Topic or Topic Filter is no longer indicated but the MQTT connection is expected to stay up.

R-MQTT.1 and R-MQTT.2 require that all MQTT capabilities referenced in this section and its sub-sections are compliant with the MQTT specifications. Reading the MQTT specification is highly recommended to ensure the correct syntax and usage of MQTT packets and properties (DISCONNECT, etc.).

R-MQTT.35 - USP Endpoints utilizing MQTT clients for message transport SHOULD send a DISCONNECT packet when shutting down an MQTT connection.

MQTT 5.0 specifies the AUTH packet to use for extended authentication. Implementations can make use of extended authentication but should only do so if they are sure that all clients and servers will support the same authentication mechanisms.

4.5.6 Discovery Requirements

The USP discovery section details requirements about the general usage of DNS, mDNS, and DNS-SD records as it pertains to the USP protocol. This section provides further requirements as to how a USP Endpoint advertises discovery information when an MQTT MTP is being utilized.

R-MQTT.36 - When creating a DNS-SD record (DNS-SD Records), an Agent MUST set the DNS-SD “path” attribute equal to the value of its “reply to” Topic.

R-MQTT.37 - When creating a DNS-SD record (DNS-SD Records), a Controller MUST set the DNS-SD “path” attribute equal to a value that is included among the Controller’s subscribed Topics and Topic Filters.

R-MQTT.38 - When creating a DNS-SD record, an Endpoint MUST utilize the MQTT server’s address information in the A and AAAA records instead of the USP Endpoint’s address information.

4.5.7 MQTT Server Requirements

R-MQTT.39 - MQTT servers MUST implement MQTT 5.0 [5].

R-MQTT.40 - MQTT servers SHOULD implement MQTT 3.1.1 [4].

R-MQTT.41 - MQTT servers MUST implement MQTT over TCP transport protocol.

R-MQTT.42 - An MQTT server MUST support authentication of the MQTT client through at least one of the mechanisms described in Section 5.4.1 of the MQTT specification, and support an Access Control List mechanism that can restrict the topics an authenticated MQTT client can subscribe or publish to.

R-MQTT.43 - An MQTT server SHOULD support both Client Certification Authentication and User Name / Password Authentication mechanisms.

R-MQTT.44 - An MQTT server SHOULD support sending Topic or Topic Filter values in a “subscribe-topic” User Property in the CONNACK packet.

R-MQTT.45 - If an MQTT server supports subscriptions from unconfigured Agents, it MUST support wildcarded Topic Filters.

This will allow support for Agents that try to subscribe to “+/<Endpoint ID>/#” and “+/+/<Endpoint ID>/#” Topic Filters.

R-MQTT.46 - An MQTT server MUST support at least MQTT QoS 1 level.

R-MQTT.47 - An MQTT server SHOULD support a ClientId value that is a USP Endpoint ID. This includes supporting all Endpoint ID characters (includes “-”, “.”, “_”, “%”, and “:”) and at least 64 characters length.

4.5.8 MTP Message Encryption

MQTT MTP message encryption is provided using TLS certificates.

R-MQTT.48 - USP Endpoints utilizing MQTT clients for message transport MUST implement TLS 1.2 [17] or later with backward compatibility to TLS 1.2.

R-MQTT.49 - MQTT server certificates MAY contain domain names and those domain names MAY contain domain names with wildcard characters per RFC 6125 [21] guidance.