페이지 선택
Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
Search in pages

Chapter 4. Secure Channel

 

 

 

4.1.   General Description

 

The Secure Channel and Message Layer provides a consistent networking service substrate to allow Nodes to communicate securely with one another.

During commissioning and unicast communication, a discovery mechanism is provided to deter­ mine peer IPv6 addresses and operational parameters. Secure session establishment mechanisms are provided using either certificates (CASE) or shared passcodes (PASE).

 

4.1.1.  Messages

 

Communication is performed using messages. Messages are either secured or unsecured.

 

Each message has a Session Type and Session ID in order to identify whether it is secured and how it is to be decrypted and authenticated if it is. Each message has a Message Counter field in order to uniquely identify the message for the purposes of security and duplicate detection.

Operational communication is defined as traffic that uses the secured Matter message format between commissioned nodes over an IP transport. All operational communication has message security enabled. Operational communication between Nodes can be either unicast or multicast.

Unsecured communication is strictly limited to:

 

  • Discovery, which does not use the Matter message
  • User Directed Commissioning (UDC), which uses unsecured messages to initiate the commission­ ing
  • Session establishment, which uses unsecured messages to establish a CASE or PASE

 

4.1.1.1.  Message Types

 

Messages are defined as either a control message or data message. Most messages are data mes­ sages. Control messages are reserved for internal protocols such as MCSP to initialize security. Both message types are identical in format, but use separate message counter domains so they can oper­ ate securely over the same security key.

 

4.1.1.2.  Message Transports

 

Messages are of finite size and are sent as individual packets over the supported transports:

 

  • UDP transports each message as a separate datagram. Messages support a basic reliability pro­ tocol called MRP for use when the underlying transport (in this case UDP) doesn’t provide such features.
  • TCP transports each message with a length prepended, performing segmentation and reassem­ bly as
  • BTP transports each message over BLE as a separate SDU, performing segmentation and

 

reassembly as needed.

 

BTP is provided as a transport protocol for commissioning. TCP and MRP (UDP with added reliabil­ ity) are provided as transport protocols for operational messaging.

 

4.1.1.3.  Message Exchanges

 

Messages provide an Exchange Layer to track related messages that make up small, discrete trans­ actions. The Exchange Layer provides this transaction tracking facility to the Interaction Model Layer above, providing a means to multiplex multiple such concurrent transactions over a given underlying session. The Exchange Layer also integrates the Message Reliability Protocol (MRP) as a service for use over UDP transports. This Message Layer architecture is shown below in Figure 6, “Message Layer Stack”:

 
   

Figure 6. Message Layer Stack

 

 

 

4.2.   IPv6 Reachability

 

This section describes IPv6 network configuration requirements to enable IPv6 reachability between Nodes. As described in Section 2.3, “Network Topology”, a Matter network may be com­ posed of one or more IPv6 networks.

In a single network configuration, all Matter Nodes are attached to the same IPv6 link. A single net­ work configuration may consist of a single bridged Wi-Fi / Ethernet network where all nodes attached to that network are part of the same broadcast domain. When all Matter Nodes are attached to the same Wi-Fi / Ethernet network, link-local IPv6 addressing is sufficient – no addi­ tional IPv6 network infrastructure is required.

In a multiple network configuration, a Matter network is composed of (typically one) infrastructure network and one or more stub networks. Unlike an infrastructure network, stub networks do not serve as transit networks. Typically, the infrastructure network is a bridged Wi-Fi / Ethernet net­ work and the Thread networks are stub networks. A stub router connects a stub network to an infrastructure network and provides IPv6 reachability between the two networks.

 

4.2.1.  Stub Router Behavior

 

A stub router SHALL implement [draft-lemon-stub-networks]. In a multiple network configuration, both the infrastructure and stub networks require routable IPv6 addresses to communicate across networks. A routable IPv6 address SHALL have global scope (e.g. GUA or ULA) [RFC 4007] and SHALL be constructed out of a prefix advertised as on-link. If there is no routable prefix on a given network, the stub router SHALL provide its own routable prefix. Note that Thread’s “on-mesh pre­ fix” is equivalent to Wi-Fi / Ethernet’s “on-link prefix”.

Stub routers SHALL advertise reachability to all routable prefixes on the adjacent network. A stub router connecting a Thread network SHALL advertise reachability to all of the Thread network’s routable prefixes to  the  adjacent  infrastructure  network  using  Route  Information  Options [RFC 4191] contained in Router Advertisements [RFC 4861]. That same stub router SHALL also advertise reachability to all of the infrastructure network’s routable prefixes to the adjacent Thread network in the Thread Network Data [Thread specification].

 

4.2.2.  Matter Node Behavior

 

Matter Nodes SHALL configure a link-local IPv6 address. In addition, Nodes SHALL support configu­ ration of at least three routable IPv6 addresses (in addition to the link-local and, in the case of Thread, mesh-local addresses). On a Wi-Fi / Ethernet interface, ICMPv6 Router Advertisement (RA) messages advertise prefixes for use on the link [RFC 4861]. On a Thread interface, the Thread Net­ work Data contains prefixes for use on the link [Thread specification]. If a Node receives an on-link prefix that allows autonomous configuration on a given interface and the Node has fewer than three routable IPv6 addresses configured, the Node SHALL autonomously configure an IPv6 address out of that prefix.

Matter Nodes SHALL also configure routes to adjacent networks. On Wi-Fi / Ethernet networks, Nodes SHALL process Route Information Options [RFC 4191] and configure routes to IPv6 prefixes assigned to stub networks via stub routers. Wi-Fi / Ethernet interfaces SHALL support maintaining at least 16 different routes configured using Route Information Options. On Thread networks, Nodes SHALL route according to routing information provided in the Thread Network Data [Thread specification]. Thread devices SHALL support as many routes as can be encoded in the Thread Net­ work Data.

Matter Nodes SHALL support a number of IPv6 neighbor cache entries at least as large as the num­ ber of supported CASE sessions plus the number of supported routes.

 

 

 

4.3.   Discovery

 

This section describes Service Advertising and Discovery for Matter.

 

Service Advertising and Discovery is used within Matter in the following contexts:

 

  • Commissionable Node Discovery
  • Operational Discovery
  • Commissioner Discovery
  • User Directed Commissioning

 

Service Advertising and Discovery for Matter uses IETF Standard DNS-Based Service Discovery (DNS‑SD) [RFC 6763]. Matter requires no modifications to IETF Standard DNS‑SD.

Using DNS‑SD means that both the unicast IPv6 address and port of the offered service are discov­ ered, freeing Matter from requiring a single preallocated fixed port. This also makes it possible to run multiple instances of Matter software on a single device, because each instance has its own dynamically allocated port, instead of conflicting over attempting to use the same preallocated fixed port.

On Wi‑Fi and Ethernet networks today, DNS‑SD [RFC 6763] uses Multicast DNS [RFC 6762] for zero- configuration operation.

Since Matter protocols must support IPv6 at a minimum, Matter software discovering other Matter instances SHALL process DNS AAAA (IPv6 address) records, but also MAY process DNS A (IPv4 address) records.

Because of this, where feasible in the underlying service discovery API, Matter software advertising the availability of a service SHOULD indicate that announcements and answers for this service need include only IPv6 address records, not IPv4 address records. On a general-purpose dual-stack host that supports both IPv4 and IPv6, this can be achieved by having Matter-related SRV records reference a Matter-specific target hostname that has only IPv6 address records attached. This allows a general-purpose dual-stack host to offer discoverable IPv4 addresses for legacy client soft­ ware that still requires IPv4, while offering optimized IPv6-only address discovery for Matter pur­ poses.

Similarly, since Matter does not use IPv4, Matter software discovering other Matter instances SHOULD NOT expect any IPv4 addresses included in responses.

These two items address the content of service discovery messages. When using Multicast DNS simi­ lar efficiency questions arise related to the delivery of those service discovery messages, sent over IPv4, IPv6, or both.

Where supported in the underlying service discovery API, Matter software using Multicast DNS to advertise the availability of a service SHOULD indicate that announcements and answers for this service need only be performed over IPv6.

Similarly, where supported in the underlying service discovery API, Matter application software using Multicast DNS to issue service discovery queries SHOULD indicate that these queries need only be performed over IPv6.

These optimizations reduce both the size and the number of multicast packets, which is particularly beneficial on Wi‑Fi networks. A Matter device that only supports IPv6 gets these optimizations auto­ matically, simply by virtue of not supporting IPv4 at all.

For Thread mesh networks, where excessive use of multicast would be detrimental [RFC 7558], DNS‑SD uses Unicast DNS instead, leveraging capabilities of the Thread Service Registry on the Thread Border Router [draft-lemon-stub-networks].

Conceptually, the DNS‑SD [RFC 6763] information being communicated is identical to when Multi­ cast DNS [RFC 6762] is being used, except that the information is communicated in unicast packets

 

to and from a designated Service Registry, rather than being communicated in multicast packets to and from every other node in the same broadcast domain.

Using Service Registration Protocol [SRP] and an Advertising Proxy [AdProx] running on the Thread Border Router, Matter Nodes on a Thread mesh can be discovered by other Matter Nodes on an adjacent Ethernet or Wi‑Fi link, without the cost of using multicast on the Thread mesh. All Thread- connected Matter Nodes SHALL implement Service Registration Protocol.

Thread Border Routers advertise available SRP servers in the Thread Network Data [Thread specifi­ cation]. Thread devices SHALL register their services using an available SRP server [Thread specifi­ cation].

When Matter Nodes issue short-lived requests to other Matter Nodes, the response is sent back to the source IPv6 address and port of the request. When Matter Nodes issue long-lived requests to other Matter Nodes, by the time the response is generated the requester may have changed IPv6 address or port, so the responder may have to discover the current IPv6 address and port of the ini­ tiator in order to send the response.

A Thread Border Router SHALL implement DNS‑SD Discovery Proxy [RFC 8766] to enable clients on the Thread mesh (e.g., other Nodes) to discover services (e.g., Matter Nodes) advertised using Multi­ cast DNS on an adjacent Ethernet or Wi‑Fi link, also without the cost of using multicast on the Thread mesh [draft-lemon-stub-networks]. For short-lived instantaneous queries, these queries can be performed using unicast DNS over UDP to the DNS‑SD Discovery Proxy. For long-lived queries with ongoing change notification, DNS Push Notifications [RFC 8765] with DNS Stateful Operations [RFC 8490] allows clients on the Thread mesh to be notified of changes to the set of discovered ser­ vices without expensive polling.

In principle, the Thread mesh Service Registry can be run on any capable Node(s) within (or even outside) the Thread mesh, though in practice the Thread Border Router is an attractive candidate to offer the Service Registry. Thread Border Router devices are typically AC-powered, and typically have more capable CPUs with greater flash storage and RAM than more constrained battery-pow­ ered Thread Nodes. Matter devices on Thread are dependent on Thread providing reliable service for those Thread devices on the Thread mesh. This is similar to how Matter devices on Wi‑Fi are dependent on the Wi‑Fi access point (AP) providing reliable service for those Wi‑Fi devices using that Wi‑Fi access point.

 

4.3.1.  Commissionable Node Discovery

 

The Matter protocol family supports UDP and TCP for Matter commissioning of Commissionees already on the customer’s IP network (such as Ethernet-connected Nodes, or Wi‑Fi Nodes already associated to the Wi‑Fi network via other means), and for the commissioning of Commissionees in conjunction with Wi‑Fi Soft-AP (for Wi‑Fi Nodes not already on the customer’s IP network, when the Node does not support Matter commissioning using BLE).

For these Commissionees, Matter Commissionable Node Discovery is performed using IETF Stan­ dard DNS-Based Service Discovery (DNS‑SD) [RFC 6763] as described below.

For Matter Commissionable Node Discovery in the already-on-network and Soft-AP cases, the DNS‑SD instance name SHALL be a dynamic, pseudo-randomly selected, 64-bit temporary unique

 

identifier, expressed as a fixed-length sixteen-character hexadecimal string, encoded as ASCII (UTF-

8) text using capital letters, e.g., DD200C20D25AE5F7. A new instance name SHALL be selected when the Node boots. A new instance name SHALL be selected whenever the Node enters Commissioning

mode. A new instance name MAY be selected at other times, as long as the instance name does not change while the Node is in commissioning mode.

When a Node receives either the OpenCommissioningWindow or the OpenBasicCommissioning­ Window command, the Node SHALL only beacon on the IP network using the relevant DNS-SD properties described below.

 

The Matter Commissionable Node Discovery DNS‑SD instance name SHALL be unique within the namespace of the local network (the .local link-local namespace of the Ethernet and Wi‑Fi links [RFC 6762], or the unicast domain selected by the Thread Border Router for devices on the Thread

mesh).

 

In the rare event of a collision in the selection of the 64-bit temporary unique identifier, the existing DNS‑SD name conflict detection mechanism will detect this collision, and a new pseudo-randomly selected 64-bit temporary unique identifier SHALL be generated by the Matter Commissionee that is preparing for commissioning. Name conflict detection is described in Section 9 (“Conflict Resolu­ tion”) of the Multicast DNS specification [RFC 6762] and Section 2.4.3.1 (“Validation of Adds”) of the Service Registration Protocol specification [SRP].

The DNS‑SD service type [RFC 6335] for Matter Commissionable Node Discovery is _matterc._udp.

For link-local Multicast DNS the service domain SHALL be local. For Unicast DNS such as used on Thread the service domain SHALL be as configured automatically by the Thread Border Router.

 

4.3.1.1.  Host Name Construction

 

For DNS‑SD a target host name is required, in addition to the instance name. The target host name SHALL be constructed using one of the available link-layer addresses, such as a 48-bit device MAC address (for Ethernet and Wi‑Fi) or a 64-bit MAC Extended Address (for Thread) expressed as a fixed-length twelve-character (or sixteen-character) hexadecimal string, encoded as ASCII (UTF-8)

text  using  capital  letters,  e.g.,  B75AFB458ECD.<domain>.  In  the  event  that  a  device  performs MAC

address randomization for privacy, then the target host name SHALL use the privacy-preserving

randomized version and the hostname SHALL be updated in the record every time the underlying link-layer address rotates. Note that it is legal to reuse the same hostname on more than one inter­ face, even if the underlying link-layer address does not match the hostname on that interface, since the goal of using a link-layer address is to ensure local uniqueness of the generated hostname. If future link layers are supported by Matter that do not use 48-bit MAC addresses or 64-bit MAC Extended Address identifiers, then a similar rule will be defined for those technologies.

 

4.3.1.2.  Extended Discovery

 

A Matter Commissionee that advertises Commissionable Node Discovery service records is not nec­ essarily in a state that will allow Commissioning (this state is referred to below as “in Commission­ ing Mode”). While Section 5.4.2.3, “Announcement Duration” is limited for some forms of device advertisement, a Matter device MAY advertise Matter Commissionable Node Discovery service records for longer periods, possibly permanently. Advertising Commissionable Node Discovery

 

when not in Commissioning Mode is referred to here as Extended Discovery. Extended Discovery is allowed only for DNS-SD advertisements and not for the other forms of Device Discovery such as BLE Commissioning Discovery and Wi-Fi Temporary Access Point Commissioning Discovery.

To protect customer privacy on public networks, a Matter Commissionee SHALL provide a way for the customer to set a timeout on Extended Discovery, or otherwise disable Extended Discovery. The default behavior for Commissionable Node Discovery SHOULD default to limiting announcement as defined in Section 5.4.2.3, “Announcement Duration” unless the Manufacturer wishes to enable longer periods for specific use cases.

 

4.3.1.3.  Commissioning Subtypes

 

The following subtypes for Matter Commissionable Node Discovery are defined:

  1. _L<dddd>, where <dddd> provides the full 12-bit discriminator, encoded as a variable-length deci­ mal number in ASCII text, omitting any leading
  2. _S<dd>, where <dd> provides the upper 4 bits of the discriminator, encoded as a variable-length decimal number in ASCII text, omitting any leading
  3. _V<ddddd>, where <ddddd> provides the 16-bit Vendor ID, encoded as a variable-length decimal number in ASCII text, omitting any leading
  4. _T<ddd>, where <ddd> provides the device type identifier for the device, encoded as a variable- length decimal number in ASCII (UTF-8) text, omitting any leading zeroes. In case the device combines multiple device types, the manufacturer SHOULD choose the device type identifier of

the primary function of the device for which the device wishes to be discoverable.

  1. _CM, which represents “currently in Commissioning Mode” (due to any method, for example, a factory new device that has just been put into commissioning mode by the user, or an already- commissioned device which has just received the Open Commissioning Window command).

The long discriminator subtype (e.g., _L840) enables filtering of results to find only Commissionees that match the full discriminator code, as provided in the onboarding payload.

The short discriminator subtype (e.g., _S3) enables filtering of results to find only Commissionees that match the upper 4 bits of the discriminator code, as provided in the manual pairing code.

The optional Vendor ID subtype (e.g., _V123) enables a vendor-specific app to achieve filtering of results to find only Nodes that match that Vendor ID.

 

The Commissioning Mode subtype (e.g., _CM) enables filtering of results to find only Nodes that are currently in Commissioning Mode. Note that the subtype is _CM regardless of whether the TXT record for commissioning mode is set to 1 (CM=1) or 2 (CM=2). A Commissionee that is not in commis­ sioning mode (CM=0) SHALL NOT publish this subtype.

The optional device type subtype (e.g., _T10) enables filtering of results to find only Nodes that match the device type, generally used for the User-Initiated Beacon Detection, Not Yet Commissioned Device and the User-Initiated Beacon Detection, Already Commissioned Device use cases.

 

In the event that a vendor-specific app wishes to show the user only some of that vendor’s Commis­ sionees awaiting commissioning but not all of them, any desired filtering logic (based upon arbi­

 

trary criteria, not only Product ID) MAY be implemented within that vendor’s proprietary commis­ sioning app.

 

4.3.1.4.  TXT Records

 

After discovery, IPv6 addresses are returned in the AAAA records and key/value pairs are returned in the DNS‑SD TXT record.

Nodes SHALL publish AAAA records for all available IPv6 addresses upon which they are willing to accept Matter commissioning messages.

TXT records available for Commissionable Node Discovery include the common TXT record key/value pairs defined in Section 4.3.4, “Common TXT Key/Value Pairs”.

Commissioners SHALL silently ignore TXT record keys that they do not recognize. This is to facili­ tate future evolution of this specification without breaking backwards compatibility with existing Commissioners that do not implement the new functionality.

The following subsections describe key/value pairs that are defined specifically for Commissionable Node discovery.

 

4.3.1.5.  TXT key for discriminator (D)

 

The key D SHALL provide the full 12-bit discriminator for the Commissionable Node and SHALL be present in the DNS-SD TXT record.

 

The discriminator value SHALL be encoded as a variable-length decimal number in ASCII text, with up to four digits, omitting any leading zeroes.

Any key D with a value mismatching the aforementioned format SHALL be silently ignored.

As an example, value D=840 would indicate that this Commissionable Node has decimal long dis­ criminator 840. When needed, the upper 4 bits of the discriminator provided by the manual pairing code can be algorithmically derived from the full discriminator.

 

4.3.1.6.  TXT key for Vendor ID and Product ID (VP)

 

The optional key VP, if present, MAY provide Vendor ID and Product ID information of the device. A vendor MAY choose not to include it at all, for privacy reasons.

If the VP key is present then it MAY take two forms:

  1. VP=123 gives Vendor ID
  2. VP=123+456 gives Vendor ID + Product ID

The Vendor ID and Product ID SHALL both be expressed as variable-length decimal numbers, encoded as ASCII text, omitting any leading zeroes, and of maximum length of 5 characters each to fit their 16-bit numerical range.

If the Product ID is present, it SHALL be separated from the Vendor ID using a ‘+’ character.

 

If the VP key is present without a Product ID, the value SHALL contain only the Vendor ID alone, with no ‘+’ character.

If the VP key is present, the value SHALL contain at least the Vendor ID. If the VP key is present, it SHALL NOT have a missing or empty value.

 

4.3.1.7.  TXT key for commissioning mode (CM)

 

The key CM (Commissioning Mode) SHALL indicate whether or not the publisher of the record is cur­ rently in Commissioning Mode and available for immediate commissioning. When in commission­ ing mode, the value associated with the CM key indicates the source of the passcode.

Four situations are legal:

  1. The absence of key CM SHALL imply a value of 0 (CM=0).
  2. The key/value pair CM=0 SHALL indicate that the publisher is not currently in Commissioning Mode.
  3. The key/value pair CM=1 SHALL indicate that the publisher is currently in Commissioning Mode and requires use of a passcode for commissioning provided by the Commissionee (e.g., printed on a label or displayed on screen), such as when the device is in a factory-new state or when the

Open Basic Commissioning Window command has been used to enter commissioning mode.

  1. The key/value pair CM=2 SHALL indicate that the publisher is currently in Commissioning Mode and requires use of a dynamically generated passcode for commissioning corresponding to the verifier that was passed to the device using the Open Commissioning Window

 

A key value of 2 MAY be used to disambiguate collisions of discriminators between uncommis­ sioned Nodes and commissioned Nodes announcing after a commissioning window was opened. A key value of 2 serves as a hint to Commissioners to possibly expect multiple Nodes with the same discriminator (see Commissioning Discriminator), and to instruct the user to enter the Onboarding Payload presented by another Administrator rather than a code provided by the Commissionee.

Since Extended Discovery can be disabled by the customer, a key value of 0 may not ever be returned by a publisher. When Extended Discovery is disabled and the publisher is not in commis­ sioning mode, then the publisher will not respond to Commissionable Node Discovery.

 

4.3.1.8.  TXT key for device type (DT)

 

The optional key DT MAY provide the publisher’s primary device type (see Section 11.22.5.3, “Device­ TypeID”). In case the device combines multiple device types, the manufacturer SHOULD choose the device type identifier of the primary function of the device for which the device wishes to be dis­

coverable. If present, it SHALL be encoded as a variable-length decimal number in ASCII text, omit­ ting any leading zeroes.

For example, the DT=10 key/value pair would indicate that the primary device type is 10 (0x000a), which is the device type identifier for a Door Lock.

 

4.3.1.9.  TXT key for device name (DN)

 

The optional key DN MAY provide a device advertisement name. If present, it SHALL be encoded as a valid UTF-8 string with a maximum length of 32 bytes (matching the maximum length of the Node­ Label string in the Basic Information Cluster).

 

When provided, the source of this value SHALL be editable by the user with use clearly designated as being for on-network advertising and MAY be the value stored in the NodeLabel attribute of the Basic Information Cluster) of the Node.

To protect customer privacy on public networks, if a Commissionee supports this key/value pair, then the Commissionee SHALL provide a way for the customer to disable its inclusion.

A Commissionee SHOULD NOT include this field unless doing so for specific use cases which call for it.

For example, the DN=Living Room key/value pair indicates that the advertisement name specified by the user is ‘Living Room’.

 

4.3.1.10.  TXT key for rotating device identifier (RI)

 

The optional key RI MAY provide a Rotating Device Identifier.

If present, the value associated with the RI key SHALL contain the octets of the Rotating Device Identifier octet string encoded as the concatenation of each octet’s value as a 2-digit uppercase hexadecimal number.

 

The resulting ASCII string SHALL NOT be longer than 100 characters, which implies a Rotating Device Identifier of at most 50 octets.

 

4.3.1.11.  TXT key for pairing hint (PH)

 

The optional key PH MAY provide a pairing hint.

If present, it SHALL be encoded as a variable-length decimal number in ASCII text, omitting any leading zeroes.

The pairing hint represents a base-10 numeric value for a bitmap of methods supported by the Commissionee in its current state for putting it in Commissioning Mode.

For example, the PH=5 key/value pair represents a hint value with bits 0 and 2 are set. This value MAY change during the lifecycle of the device.

For example, a device may have a value with bit 0 (Power Cycle) set and bit 2 (Administrator app) unset when in a factory reset state, and then have a value with bit 0 unset and bit 2 set after it has been Commissioned.

The bitmap of methods is defined in Table 6, “Pairing Hint Values”.

 

If the Commissionee has enabled Extended Discovery, then it SHALL include the key/value pair for

PH in the DNS‑SD TXT record when not in Commissioning Mode (CM=0).

 

This key/value pair MAY be returned when in Commissioning Mode (CM=1).

If the Commissioner does not recognize this value, for example, if the value indicates bit indices defined in a newer version of this specification than the version which the Commissioner imple­ ments, then the Commissioner MAY utilize the bits that it does understand and MAY utilize addi­ tional data sets available for assisting the user. For example, when a Vendor ID and Product ID are available to the Commissioner, the Section 11.22, “Distributed Compliance Ledger” may also pro­ vide a URL for the Device User Guide which can contain additional information to help in Commis­ sioning this Commissionee.

 

Some of the pairing hints MAY require additional information to be encoded for proper expression of their meaning. This is accomplished with the PI TXT key, described in a following section. Depen­ dency on usage of the PI key is expressed by the PI Dependency column in the table below.

The following fields in the bitmap are currently defined for values of the PH key:

Table 6. Pairing Hint Values

 

Bit index Name PI Dependency Description
0 Power Cycle False The Device will auto­ matically enter Com­ missioning Mode upon power cycle (unplug/re- plug, remove/re-insert batteries). This bit SHALL be set to 1 for devices using Standard Commissioning Flow, and set to 0 otherwise.
1 Device Manufacturer URL False

This SHALL be set to 1 for devices requiring Custom Commissioning Flow before they can be available for Com­ missioning by any Com­ missioner. For such a flow, the user SHOULD be sent to the URL spec­

ified in the Commission­ ingCustomFlowUrl of the

DeviceModel schema entry indexed by the Vendor ID and Product ID (e.g., as found in the announcement) in the Distributed Compliance Ledger.

 

 

Bit index Name PI Dependency Description
2 Administrator False The Device has been commissioned. Any Administrator that commissioned the device provides a user interface that may be used to put the device into Commissioning Mode.
3 Settings menu on the Node False The settings menu on the Device provides instructions to put it into Commissioning Mode.
4 Custom Instruction True The PI key/value pair describes a custom way to put the Device into Commissioning Mode. This Custom Instruc­ tion option is NOT rec­ ommended for use by a Device that does not have knowledge of the user’s language prefer­ ence.
5 Device Manual False The Device Manual pro­ vides special instruc­ tions to put the Device into Commissioning Mode (see Section 11.22.5.8, “UserManu­ alUrl”). This is a catch- all option to capture user interactions that are not codified by other options in this ta­ ble.
6 Press Reset Button False The Device will enter Commissioning Mode when reset button is pressed.

 

 

Bit index Name PI Dependency Description
7 Press Reset Button with application of power False The Device will enter Commissioning Mode when reset button is pressed when applying power to it.
8 Press Reset Button for N seconds True The Device will enter Commissioning Mode when reset button is pressed for N seconds. The exact value of N SHALL be made avail­ able via PI key.
9 Press Reset Button until light blinks True The Device will enter Commissioning Mode when reset button is pressed until associated light blinks. Informa­ tion on color of light MAY be made available via PI key (see Note 1).
10 Press Reset Button for N seconds with applica­ tion of power True The Device will enter Commissioning Mode when reset button is pressed for N seconds when applying power to it. The exact value of N SHALL be made available via PI key.
11 Press Reset Button until light blinks with appli­ cation of power True The Device will enter Commissioning Mode when reset button is pressed until associated light blinks when applying power to the Device. Information on color of light MAY be made available via PI key (see Note 1).

 

 

Bit index Name PI Dependency Description
12 Press Reset Button N times True The Device will enter Commissioning Mode when reset button is pressed N times with maximum 1 second between each press. The exact value of N SHALL be made avail­ able via PI key.
13 Press Setup Button False The Device will enter Commissioning Mode when setup button is pressed.
14 Press Setup Button with application of power False The Device will enter Commissioning Mode when setup button is pressed when applying power to it.
15 Press Setup Button for N seconds True The Device will enter Commissioning Mode when setup button is pressed for N seconds. The exact value of N SHALL be made avail­ able via PI key.
16 Press Setup Button until light blinks True The Device will enter Commissioning Mode when setup button is pressed until associated light blinks. Informa­ tion on color of light MAY be made available via PI key (see Note 1).
17 Press Setup Button for N seconds with applica­ tion of power True The Device will enter Commissioning Mode when setup button is pressed for N seconds when applying power to it. The exact value of N SHALL be made available via PI key.

 

 

Bit index Name PI Dependency Description
18 Press Setup Button until light blinks with application of power True The Device will enter Commissioning Mode when setup button is pressed until associated light blinks when applying power to the Device. Information on color of light MAY be made available via PI key (see Note 1).
19 Press Setup Button N times True The Device will enter Commissioning Mode when setup button is pressed N times with maximum 1 second between each press. The exact value of N SHALL be made avail­ able via PI key.

 

Note 1: When the PH key indicates a light to blink (one or more of bits 9, 11, 16 or 18 is set), informa­ tion on color of light MAY be made available via PI key. When using such color indication in PI key, only basic primary and secondary colors that could unambiguously be decoded by a commissioner

and understood by an end-user, but without worry of localization, SHOULD be used, e.g. white, red, green, blue, orange, yellow, purple.

Note 2: Any undefined values are reserved for future use.

 

Note 3: A Commissionee can indicate multiple ways of being put into Commissioning Mode by set­ ting multiple bits in the bitmap at the same time. However, only one method can be specified which has a dependency on the PI key (PI Dependency=True) at a time.

For example:

  • A PH value of 33 (bits 0 and 5 are set) indicates that the user can cause the Commissionee to enter Commissioning Mode by either power cycling it or by following special instructions pro­ vided in the Device
  • A PH value of 9 (bits 0 and 3 are set) indicates that the user can cause the Commissionee to enter Commissioning Mode by either power cycling it or going to the settings menu and following instructions
  • A PH value of 1 (bit 0 is set) indicates that the user can cause the Commissionee to enter Commis­ sioning Mode only by power cycling
  • A PH value of 16 (bit 4 is set) indicates that the user can cause the Commissionee to enter Com­ missioning Mode following a custom procedure described by the value of the PI
  • A PH value of 256 (bits 8 is set) indicates that the user can cause the Commissionee to enter Com­

 

missioning Mode by pressing the reset button for a duration of time in seconds specified via by the value of the PI key.

When the PH key is provided, at least one bit in the above bitmap SHALL be set. That is, a PH value of 0 is undefined and illegal.

When the PH key is provided, the Commissioner SHOULD take its value into account when provid­ ing guidance to the user regarding steps required to put the Commissionee into Commissioning Mode.

 

4.3.1.12.  TXT key for pairing instructions (PI)

 

The optional key PI MAY give the pairing instruction.

If present, the value SHALL be encoded as a valid UTF-8 string with a maximum length of 128 bytes.

The meaning of this key is dependent upon the PH key value, see Table 6, “Pairing Hint Values”.

For example, given PH=256, bit 8 is set which indicates “Press Reset Button for N seconds”. Therefore, a value of PI=10 would indicate that N is 10 in that context.

When bit 4 of the value expressed by the PH key is set, indicating presence of a custom string, the Commissionee SHALL be responsible for localization (translation to user’s preferred language) as required using the Device’s currently configured locale. The Custom Instruction option is NOT rec­

ommended for use by a Commissionee that does not have knowledge of the user’s language prefer­ ence.

It is RECOMMENDED to keep the length of PI field small and adhere to the guidance given in section 6.2 of [RFC 6763].

This key/value pair SHALL only be returned in the DNS‑SD TXT record if the PH bitmap value has a bit set which has PI Dependency = True, see Table 6, “Pairing Hint Values”. The PH key SHALL NOT not have more than one bit set which has a dependency on the PI key (PI Dependency = True) to avoid ambiguity in PI key usage.

 

4.3.1.13.  Examples

 

The examples below simulate a Node in commissioning mode advertising its availability for com­ missioning.

Examples are shown using both the dns-sd command-line test tool and the avahi command-line test tool. The dns-sd command-line test tool is included in all versions of macOS. It is installed as a DOS command with Bonjour for Windows, and is available on Linux by installing the mDNSResponder

package [https://github.com/balaji-reddy/mDNSResponder]. The Avahi package of command line tools is available from the Avahi project [https://github.com/lathiat/avahi] for most Linux distributions.

These examples are given for illustrative purposes only. Real Matter Commissionees and Commis­ sioners would not use a command-line test tool for advertising and discovery. Real Matter Commis­ sionees and Commissioners would use the appropriate DNS‑SD APIs in their respective chosen pro­ gramming languages.

 

Consider a device on Wi-Fi using the 48-bit device MAC address of B75AFB458ECD as its host name and a value of DD200C20D25AE5F7 as its commissionable service instance name. DNS-SD records for it can be set up as follows:

 

dns-sd -R DD200C20D25AE5F7 _matterc._udp,_S3,_L840,_CM . 11111 D=840 CM=2

or

 

avahi-publish-service –subtype=_S3._sub._matterc._udp

–subtype=_L840._sub._matterc._udp DD200C20D25AE5F7 –subtype=_CM._sub._matterc._udp

_matterc._udp 11111 D=840 CM=2

  • Short discriminator is filterable through _S3 subtype and algorithmically through D=840 TXT
  • Long discriminator is filterable through _L840 subtype and directly through D=840 TXT
  • The Commissionee is currently in Commissioning Mode after an Administrator having opened a commissioning window (see Section 4.3.1.7, “TXT key for commissioning mode (CM)”), as shown by CM=2 TXT key and availability by browsing the _CM
    • Had the Commissionee been discoverable for initial commissioning rather than subsequent additional commissioning, a CM=1 TXT key would have been published instead.

Avahi only sends a single AAAA record. To force the link-local address to be used, use avahi-pub­ lish-address. For example:

 

avahi-publish-address B75AFB458ECD.local fe80::f515:576f:9783:3f30

The DNS‑SD service registration commands shown above results in the creation of the following Multicast DNS records:

 

_matterc._udp.local.                                                PTR                                                                                      DD200C20D25AE5F7._matterc._udp.local.

_S3._sub._matterc._udp.local.                               PTR                                                                                      DD200C20D25AE5F7._matterc._udp.local.

_L840._sub._matterc._udp.local.                          PTR                                                                                      DD200C20D25AE5F7._matterc._udp.local.

_CM._sub._matterc._udp.local.                             PTR                                                                                      DD200C20D25AE5F7._matterc._udp.local. DD200C20D25AE5F7._matterc._udp.local.          SRV           0 0 11111 B75AFB458ECD.local.

DD200C20D25AE5F7._matterc._udp.local.                                                                                      TXT                                                                                      “D=840” “CM=2” B75AFB458ECD.local.                                                                                      AAAA                                                                                      fe80::f515:576f:9783:3f30

Consider a device on Wi-Fi using the 48-bit device MAC address of B75AFB458ECD as its host name. DNS-SD records for it can be set up as follows, when it is in Commissionable Node Discovery.

 

dns-sd -R DD200C20D25AE5F7 _matterc._udp,_S3,_L840,_V123,_CM,_T81 . 11111 D=840 VP=123+456 CM=2 DT=81 DN=”Kitchen Plug” PH=256 PI=5

or

 

 

avahi-publish-service –subtype=_S3._sub._matterc._udp

–subtype=_L840._sub._matterc._udp –subtype=_V123._sub._matterc._udp

–subtype=_CM._sub._matterc._udp –subtype=_T81._sub._matterc._udp DD200C20D25AE5F7

_matterc._udp 11111 D=840 VP=123+456 CM=2 DT=81 DN=”Kitchen Plug” PH=256 PI=5

 

  • Short discriminator is 3, long discriminator is 840.
  • Vendor ID is 123, Product ID is 456.
  • Commissioning Mode is 2, indicating the Commissionee is currently in Commissioning Mode due to the Open Commissioning Window
  • Device type is 81 which is a Smart Plug (Device Type Identifier 0x0051).
  • Device name is Kitchen Plug.
  • Pairing hint is 256 which indicates that the Commissionee’s reset button must be held down for 5 seconds to enter Commissioning Mode where the value 5 is obtained by reading the value of the PI
  • Pairing instruction is 5.

Avahi only sends a single AAAA record. To force the link-local address to be used, use avahi-pub­ lish-address. For example:

 

avahi-publish-address B75AFB458ECD.local fe80::f515:576f:9783:3f30

The DNS‑SD service registration commands shown above results in the creation of the following Multicast DNS records:

 

_matterc._udp.local.                                                PTR                                                                                      DD200C20D25AE5F7._matterc._udp.local.

_S3._sub._matterc._udp.local.                               PTR                                                                                      DD200C20D25AE5F7._matterc._udp.local.

_L840._sub._matterc._udp.local.                          PTR                                                                                      DD200C20D25AE5F7._matterc._udp.local.

_V123._sub._matterc._udp.local.                          PTR                                                                                      DD200C20D25AE5F7._matterc._udp.local.

_CM._sub._matterc._udp.local.                             PTR                                                                                      DD200C20D25AE5F7._matterc._udp.local.

_T81._sub._matterc._udp.local.                            PTR                                                                                      DD200C20D25AE5F7._matterc._udp.local. DD200C20D25AE5F7._matterc._udp.local.          TXT                                                                                      “D=840” “VP=123+456” “CM=1” “DT=81” “DN=Kitchen Plug” “PH=256” “PI=5”

DD200C20D25AE5F7._matterc._udp.local.          SRV      0 0 11111 B75AFB458ECD.local. B75AFB458ECD.local.                                                                                      AAAA                                                                                      fe80::f515:576f:9783:3f30

The port number 11111 is given here purely as an example. One of the benefits of using DNS‑SD is that services are not constrained to use a single predetermined well-known port. The port, along with the IPv6 address, is discovered by Commissioners at run time.

A Commissioner can discover all available Commissionees awaiting commissioning:

 

dns-sd -B _matterc._udp

 

or

 

avahi-browse _matterc._udp -r

A Commissioner can discover Commissionees awaiting commissioning with short discriminator 3:

 

dns-sd -B _matterc._udp,_S3

or

 

avahi-browse _S3._sub._matterc._udp -r

A Commissioner can discover Commissionees awaiting commissioning with long discriminator 840:

 

dns-sd -B _matterc._udp,_L840

or

 

avahi-browse _L840._sub._matterc._udp -r

A Commissioner can discover Commissionees awaiting commissioning with Vendor ID 123:

 

dns-sd -B _matterc._udp,_V123

or

 

avahi-browse _V123._sub._matterc._udp -r

A Commissioner can discover all Commissionees in commissioning mode:

 

dns-sd -B _matterc._udp,_CM

or

 

avahi-browse _CM._sub._matterc._udp -r

A commissioner can discover Matter Nodes with Device Type 81:

 

dns-sd -B _matterc._udp,_T81

 

or

 

avahi-browse _T81._sub._matterc._udp -r

A Commissioner can discover Nodes that are currently in Commissioning Mode as a result of a com­ missioning window opened by a current Administrator as a result of invoking either the Open Com­ missioning Window command or the Open Basic Commissioning Window command, using the

presence of the _CM subtype as a browsing filter:

 

dns-sd -B _matterc._udp,_CM

or

 

avahi-browse _CM._sub._matterc._udp -r

 

4.3.1.14.  Efficiency Considerations

 

Discovering and using an offered service on the network typically involves several steps:

 

  1. Enumeration of instances available on the network (“browsing”)
  2. Lookup of a selected instance’s port number, host name, and other additional information, com­ municated in DNS‑SD using SRV and TXT records (“resolving”)
  3. Lookup of the IPv6 address(es) associated with the desired target
  4. Use of IPv6 Neighbor Discovery and/or IPv6 routing to translate from destination IPv6 address to the next-hop link-layer address for that
  5. Establishing a cryptographically secure communication channel between the two endpoints, and then engaging in useful

Although the first three steps are exposed in some APIs as separate steps, at a protocol level they usually require only a single network round-trip. When a PTR query is issued to discover service instances, the usual DNS Additional Record mechanism, where packet space permits, automatically places the related SRV, TXT, and address records into the Additional Record section of the reply.  These additional records are stored by the client, to enable subsequent steps in the sequence to be performed without additional redundant network operations to learn the same information a sec­ ond time.

DNS‑SD over Multicast DNS works by receiving replies from other Nodes attached to the same local link, Nodes that may have been previously completely unknown to the requester. Because of this, Multicast DNS, like IPv6 Neighbor Discovery, does not have any easy way to distinguish genuine replies from malicious or fraudulent replies. Consequently, application-layer end-to-end security is essential. Should a malicious device on the same local link give deliberately malicious or fraudulent replies, the misbehavior will be detected when the device is unable to establish a cryptographically secure application-layer communication channel. This reduces the threat to a Denial-of-Service attack, which can be remedied by physically removing the offending device.

 

4.3.2.  Operational Discovery

 

For Matter Nodes that have already been commissioned onto a Matter Fabric, run-time dynamic discovery of operational Matter Nodes is used, rather than assuming a fixed unchanging IPv6 address and port for the lifetime of the product. This is done to allow for greater flexibility, so that the underlying IPv6 network can grow and evolve over time as needed without breaking Matter functionality. This is the same reason that other networked consumer electronics products do not assume a single fixed unchanging IP address for the lifetime of the product [RFC 5505].

 

4.3.2.1.  Operational Instance Name

 

For Matter operational discovery the DNS‑SD instance name is constructed from a 64-bit com­ pressed Fabric identifier, and a 64-bit Node identifier, as assigned by the commissioner, each expressed as a fixed-length sixteen-character hexadecimal string, encoded as ASCII (UTF-8) text using capital letters, separated by a hyphen. For example, a Matter Node with Matter compressed

fabric identifier 2906-C908-D115-D362 and Matter Node identifier 8FC7-7724-01CD-0696 has Matter operational discovery DNS‑SD instance name 2906C908D115D362-8FC7772401CD0696.

 

The Matter operational discovery DNS‑SD instance name needs to be unique within the namespace of the local network (the .local link-local namespace of the Ethernet and Wi‑Fi links [RFC 6762], or the unicast domain selected by the Thread Border Router for devices on the Thread mesh). This

uniqueness is assumed to be guaranteed by appropriate selection of a unique Matter fabric identi­ fier and unique Node identifier within that Matter fabric.

 

4.3.2.2.  Compressed Fabric Identifier

 

In order to reduce the very large size of a full Fabric Reference which would need to be used as the scoping construct in the instance name, a 64-bit compressed version of the full Fabric Reference SHALL be used. The computation of the Compressed Fabric Identifier SHALL be as follows:

 

byte CompressedFabricInfo[16] = /* “CompressedFabric” */

{0x43, 0x6f, 0x6d, 0x70, 0x72, 0x65, 0x73, 0x73, 0x65, 0x64, 0x46, 0x61, 0x62, 0x72, 0x69, 0x63}

 

CompressedFabricIdentifier = Crypto_KDF(

inputKey := TargetOperationalRootPublicKey, salt:= TargetOperationalFabricID,

info := CompressedFabricInfo, len := 64)

Where:

  • TargetOperationalRootPublicKey is the raw uncompressed elliptical curve public key of the root certificate for the advertised Node’s Operational Certificate chain, without any format marker prefix byte (i.e. after removing the first byte of the ec-pub-key field in the Operational Certifi­ cate’s root).
  • TargetOperationalFabricID is the octet string for the Fabric ID as it appears in the advertised

 

Node’s Operational Certificate’s subject field, under the 1.3.6.1.4.1.37244.1.5 RDN, that is, a 64-bit unsigned integer scalar in big-endian byte order.

 

For example, if the root public key for a given Operational Certificate chain containing the identity to be advertised were the following:

 

pub:

04:4a:9f:42:b1:ca:48:40:d3:72:92:bb:c7:f6:a7:e1:

1e:22:20:0c:97:6f:c9:00:db:c9:8a:7a:38:3a:64:1c:

b8:25:4a:2e:56:d4:e2:95:a8:47:94:3b:4e:38:97:c4:

a7:73:e9:30:27:7b:4d:9f:be:de:8a:05:26:86:bf:ac:

fa

Then the value for TargetOperationalRootPublicKey to use in the derivation of the compressed Fab­ ric Identifier would be without the leading 04:

 

4a:9f:42:b1:ca:48:40:d3:72:92:bb:c7:f6:a7:e1:1e:

22:20:0c:97:6f:c9:00:db:c9:8a:7a:38:3a:64:1c:b8:

25:4a:2e:56:d4:e2:95:a8:47:94:3b:4e:38:97:c4:a7:

73:e9:30:27:7b:4d:9f:be:de:8a:05:26:86:bf:ac:fa

If using the above TargetOperationalRootPublicKey and a TargetOperationalFabricID value of 0x2906_C908_D115_D362 (octet string 29:06:c9:08:d1:15:d3:62 in big-endian), then the Compressed­ FabricIdentifier to use in advertising would be 87E1B004E235A130 (octet string 87:e1:b0:04:e2:35:a1:30).

 

4.3.2.3.  Operational Service Type

 

The DNS‑SD service type [RFC 6335] for Matter Operational Discovery is _matter._tcp. Note that the string _tcp is boilerplate text inherited from the original DNS SRV specification [RFC 2782], and doesn’t necessarily mean that the advertised application-layer protocol runs only over TCP. It is

merely mnemonic text which is there to help human readers, and in no way affects software adver­ tising or using the application-layer protocol identified by that unique IANA-recorded service type string.

The following subtype is defined:

  1. Compressed Fabric Identifier _I<hhhh>, where <hhhh> is the Compressed Fabric Identifier encoded as exactly 16 uppercase hexadecimal characters, for example _I87E1B004E235A130 for the Compressed Fabric Identifier example of the previous section. This subtype enables filtering

of devices per Fabric if service enumeration (browsing) is attempted, to reduce the set of results to Nodes of interest with operational membership in a given Fabric..

 

4.3.2.4.  Operational Service Domain and Host Name

 

For link-local Multicast DNS the service domain SHALL be local. For Unicast DNS such as used on Thread the service domain SHALL be as configured automatically by the Thread Border Router.

 

For DNS‑SD a target host name is required, in addition to the instance name. The target host name SHALL be constructed using one of the available link-layer addresses, such as a 48-bit device MAC address (for Ethernet and Wi‑Fi) or a 64-bit MAC Extended Address (for Thread) expressed as a

fixed-length twelve-character (or sixteen-character) hexadecimal string, encoded as ASCII (UTF-8) text using capital letters, e.g., B75AFB458ECD.<domain>. In the event that a device performs MAC address randomization for privacy, then the target host name SHALL use the privacy-preserving

randomized version and the hostname SHALL be updated in the record every time the underlying link-layer address rotates. Note that it is legal to reuse the same hostname on more than one inter­ face, even if the underlying link-layer address does not match the hostname on that interface, since the goal of using a link-layer address is to ensure local uniqueness of the generated hostname. If future link layers are supported by Matter that do not use 48-bit MAC addresses or 64-bit MAC Extended Address identifiers, then a similar rule will be defined for those technologies.

 

4.3.2.5.  Operational Discovery Service Records

 

After discovery, IPv6 addresses are returned in the AAAA records and key/value pairs are returned in the DNS‑SD TXT record. The TXT record MAY be omitted if no keys are defined.

Nodes SHALL publish AAAA records for all available IPv6 addresses upon which they are willing to accept operational messages.

Only the common TXT record key/value pairs defined in Section 4.3.4, “Common TXT Key/Value Pairs” are defined for use in Operational Discovery.

Nodes SHALL silently ignore TXT record keys that they do not recognize.

 

4.3.2.6.  Performance Recommendations

 

To improve overall performance of operational discovery, especially in large installations, the fol­ lowing recommendations SHOULD be taken in account:

  1. Nodes SHOULD cache the last-known IPv6 address and port for each peer Node with which they interact from their SRV record resolved using DNS-SD, to save the cost of a run-time network lookup operation when not needed. When the IPv6 address and port for a peer Node is not known, or an attempt to communicate with a peer Node at its last-known IPv6 address and port does not appear to be succeeding within the expected network round-trip time (i.e., the retrans­ mission timeout value for the first message packet) a Node SHOULD then perform a run-time discovery in parallel, to determine whether the desired Node has acquired a new IPv6 address and/or port [RFC 8305].
  2. Nodes SHOULD respond to nonspecific service enumeration queries for the generic Matter Operational Discovery service type (_tcp), but these queries SHOULD NOT be used in routine operation, and instead it is RECOMMENDED that they only be used for diagnostics pur­

poses or to determine new membership within a fabric. When used, it is RECOMMENDED that service enumeration employ the _I<HHHH> Fabric-specific subtype to only enumerate the desired Nodes on the Fabric of interest in the local network. Moreover, Known Answer Suppression

[RFC 6762] SHOULD be employed in such cases to further minimize the number of unnecessary responses to such a query.

  1. When resolving the operational service record of another Node, a Node SHOULD use an SRV

 

query for the desired operational service instance rather than doing general enumeration of all nodes (e.g. PTR query) followed by filtering for the desired service instance. This recommenda­ tion reduces the amount of multicast traffic generated on-link when Multicast DNS is used, and reduces latency to successful service resolution.

  1. Since proxied DNS-SD service discovery MAY be in use within a given network, and service record caching is expected of DNS-SD clients, Nodes SHOULD NOT use DNS-SD as an operational liveness determination method. This is because there may be stale records not yet expired after a Node becomes unreachable which may still be

 

4.3.2.7.  Operational Discovery DNS-SD Examples

 

The example below simulates a commissioned Matter Node advertising its availability for control via the Matter protocol.

Examples are shown using both the dns-sd command-line test tool and the avahi command-line test tool. The dns-sd command-line test tool is included in all versions of macOS. It is installed as a DOS command with Bonjour for Windows, and is available on Linux by installing the mDNSResponder package [https://github.com/balaji-reddy/mDNSResponder]. The avahi command line-test tool is available

from the Avahi project [https://github.com/lathiat/avahi] for most Linux distributions.

 

This example is given for illustrative purposes only. Real Matter Nodes and controllers would not use a command-line test tool for advertising and discovery. Real Matter Nodes and controllers would use the appropriate DNS‑SD APIs in their respective chosen programming languages.

Consider a device on Wi-Fi using the 48-bit device MAC address of B75AFB458ECD as its host name. DNS-SD records for can be set up as follows:

 

dns-sd -R 87E1B004E235A130-8FC7772401CD0696 _matter._tcp . 22222

or

 

avahi-publish-service 87E1B004E235A130-8FC7772401CD0696 _matter._tcp 22222

The port number 22222 is given here purely as an example. One of the benefits of using DNS‑SD is that services are not constrained to use a single predetermined well-known port. This means that multiple instances of the Matter Node control service can run on the same device at the same time, listening on different ports [RFC 6760]. The port, along with the IPv6 address, is discovered by the Matter controller at run time.

Avahi only sends a single AAAA record. To force the link-local address to be used, use avahi-pub­ lish-address. For example:

 

avahi-publish-address B75AFB458ECD.local fe80::f515:576f:9783:3f30

A Matter controller can discover the current IPv6 address and port for a known commissioned Mat­ ter Node:

 

 

dns-sd -L 87E1B004E235A130-8FC7772401CD0696 _matter._tcp 87E1B004E235A130-8FC7772401CD0696._matter._tcp.local. can be reached at B75AFB458ECD.local.:22222

 

dns-sd -Gv6 B75AFB458ECD.local fe80::f515:576f:9783:3f30

 

or

 

avahi-browse _matter._tcp -r

hostname = [B75AFB458ECD.local] address = [fe80::f515:576f:9783:3f30] port = [22222]

 

4.3.3.  Commissioner Discovery

 

A Commissionee MAY initiate the commissioning process by discovering Commissioners on the net­ work (see Initiating Commissioning from an Existing Device). This MAY be done using Commis­ sioner Discovery described in this section.

With Commissioner Discovery, a Commissionee, upon user interaction, MAY discover Commission­ ers on the network and obtain a list of information for each which may include Vendor ID, Product ID and friendly name. A Commissionee with a user interface, such as a Television, Thermostat or Video Player device, MAY display the list of discovered commissioners to the user for selection. Once selected, the Commissionee MAY use the User Directed Commissioning protocol with the Com­ missioner to indicate that the user has selected it for commissioning of the Commissionee. The Commissioner Discovery service records thus enable a form of “door bell” protocol to allow a Com­ missionee to request Commissioning.

The Commissioner Discovery feature is optional for both the Commissionee and the Commissioner. Any mandatory requirements described in this section SHALL apply only if the Node or the Com­ missioner supports this feature. To protect customer privacy on public networks, a Matter Commis­ sioner SHALL provide a way for the customer to set a timeout on Commissioner Discovery, or other­ wise disable Commissioner Discovery.

For Commissioner Discovery, the DNS-SD instance name is generated the same way it is done for Commissionable Node Discovery and has the same requirements (uniqueness on local network, and collision detection and recovery) as those in Commissionable Node Discovery, but the require­ ments for when a new instance name is selected from Commissionable Node Discovery do not apply to Commissioner Discovery. The instance name for Commissioner Discovery MAY be selected whenever the Commissioner deems necessary.

The DNS-SD service type [RFC 6335] is _matterd._udp.

The port advertised by a _matterd._udp service record SHALL be different than any port associated with other advertised _matterc._udp, _matter._tcp or _matterd._udp services, in order to ensure that

 

the session-less messaging employed by the User Directed Commissioning protocol does not cause

invalid message handling from fully operational Matter nodes at the same address. In other words, each _matterd._udp service instance needs to be independent from other services to ensure unam­ biguous processing of the incoming User Directed Commissioning messages.

 

The following subtype is defined:

  • \_T<ddd> where <ddd> is the device type identifier (see Data Model Device Types), encoded as a variable-length decimal number in ASCII (UTF-8) text, without leading zeroes. This optional Device Type subtype enables filtering of results to find only Commissioners that match a device

type, for example, to discover Commissioners of type Video Player (35 is decimal representation for Video Player device type identifier 0x0023). For such a Video Player filter, subtype _T35 would be used.

For link-local Multicast DNS the service domain SHALL be local. For Unicast DNS such as used on Thread the service domain SHALL be as configured automatically by the Thread Border Router.

 

The target host name is generated the same way it is done for Commissionable Node Discovery (see Host Name Construction).

After discovery, IPv6 addresses are returned in the AAAA records and key/value pairs are returned in the DNS‑SD TXT record. The TXT record MAY be omitted if no keys are defined.

Nodes SHALL publish AAAA records for all their available IPv6 addresses.

 

In addition to the common TXT record key/value pairs defined in Section 4.3.4, “Common TXT Key/Value Pairs”, the following key/value pairs are defined specifically for Commissioner discovery:

  • The optional key VP gives vendor and product information. This key is optional for a vendor to provide, and optional for a commissioner to use. This value takes the same format described for the VP key in Commissionable Node Discovery (see Section 4.3.1.6, “TXT key for Vendor ID and Product ID (VP)”). This key/value pair MAY be returned in the DNS‑SD TXT
  • The optional key DT gives the device type identifier for the Commissioner (see Data Model Device Types). This value takes the same format described for the DT key in Commissionable Node Discovery (see Commissioning Device Type). This key/value pair MAY be returned in the

DNS‑SD TXT record.

  • The optional key DN gives the device This value takes the same format described for the DN key in Commissionable Node Discovery (see Commissioning Device Name). This key/value pair MAY be returned in the DNS‑SD TXT record. To protect customer privacy on public networks, a

Matter Commissioner SHALL provide a way for the customer to disable inclusion of this key.

 

Commissionees SHALL silently ignore TXT record keys that they do not recognize. This is to facili­ tate future evolution of the Matter Commissioner Discovery protocol specification without breaking backwards compatibility with existing Commissionees that do not implement the new functionality.

 

4.3.3.1.  Examples

 

The examples below simulate a Matter Commissioner advertising that it is present on the network. Examples are shown using both the dns-sd command-line test tool and the avahi command-line test

 

tool. The dns-sd command-line test tool is included in all versions of macOS. It is installed as a DOS command with Bonjour for Windows, and is available on Linux by installing the mDNSResponder package [https://github.com/balaji-reddy/mDNSResponder]. The avahi command line-test tool is available from the Avahi project [https://github.com/lathiat/avahi] for most Linux distributions.

 

These examples are given for illustrative purposes only.

 

Consider a device on Wi-Fi using the 48-bit device MAC address of B75AFB458ECD as its host name. DNS-SD records for can be set up as follows:

 

dns-sd -R DD200C20D25AE5F7 _matterd._udp,_V123,_T35 . 33333 VP=123+456 DT=35

DN=”Living Room TV”

or

 

avahi-publish-service –subtype=_V123._sub._matterd._udp DD200C20D25AE5F7

_matterd._udp 33333 VP=123+456 DT=35 DN=”Living Room TV”

This produces DNS-SD messages with the following characteristics:

  • Vendor ID is 123, Product ID is 456.
  • Device type is 35 which is a Video Player (Device Type Identifier 0x0023).
  • Device name is Living Room TV.

Avahi only sends a single AAAA record. To force the link-local address to be used, use avahi-pub­ lish-address. For example:

 

avahi-publish-address B75AFB458ECD.local fe80::f515:576f:9783:3f30

The DNS‑SD service registration command shown above results in the creation of the following Multicast DNS records:

 

_matterd._udp.local.                                                PTR                                                                                      DD200C20D25AE5F7._matterd._udp.local.

_V123._sub._matterd._udp.local.                         PTR                                                                                      DD200C20D25AE5F7._matterd._udp.local.

_T35._sub._matterd._udp.local.                            PTR                                                                                      DD200C20D25AE5F7._matterd._udp.local. DD200C20D25AE5F7._matterd._udp.local.         TXT                                                                                      “VP=123+456” “DT=35” “DN=Living Room TV” DD200C20D25AE5F7._matterd._udp.local.         SRV      0 0 33333 B75AFB458ECD.local.

B75AFB458ECD.local.                                               AAAA                                                                                      fe80::f515:576f:9783:3f30

The port number 33333 is given here purely as an example. A Commissionee can discover all Commissioners:

dns-sd -B _matterd._udp

 

or

 

avahi-browse _matterd._udp -r

A Commissionee can discover Commissioners with device type 35:

 

dns-sd -B _matterd._udp,_T35

or

 

avahi-browse _T35._sub._matterd._udp -r

A Commissionee can discover Commissioners with Vendor ID 123:

 

dns-sd -B _matterd._udp,_V123

or

 

avahi-browse _V123._sub._matterd._udp -r

 

4.3.4.  Common TXT Key/Value Pairs

 

The TXT records provided during Commissionable, Operational and Commissioner discovery MAY contain the following optional key/value pairs which are common to every discovery method:

  • The optional key SII indicates the SLEEPY_IDLE_INTERVAL of the Node. This key MAY option­ ally be provided by a Node to override sleepy defaults. If the key is not included or invalid, the Node querying the service record SHALL use the default SED parameter value. The SII value is an unsigned integer with units of milliseconds and SHALL be encoded as a variable-length deci­ mal number in ASCII encoding, omitting any leading zeros. The SII value SHALL NOT exceed 3600000 (1 hour in milliseconds).
    • Example: SII=5300 to override the initial retry interval value to 5.3 seconds.
  • The optional key SAI indicates the SLEEPY_ACTIVE_INTERVAL of the Node. This key MAY option­ ally be provided by a Node to override SED defaults. If the key is not included or invalid, the Node querying the service record SHALL use the default MRP parameter value. The SAI value is an unsigned integer with units of milliseconds and SHALL be encoded as a variable-length deci­ mal number in ASCII encoding, omitting any leading zeros. The SAI value SHALL NOT exceed 3600000 (1 hour in milliseconds).
    • Example: SAI=1250 to override the active retry interval value to 1.25 seconds.
  • The optional key T indicates whether the Node supports This key MAY optionally be pro­ vided by a Node that does not support TCP. If the key is not included or invalid, the Node query­

 

ing the service record SHALL assume the default value of T=0 indicating TCP is not supported. The T key, if included, SHALL have one of two valid values: ‘0’ to indicate “TCP not supported”, or ‘1’ to indicate “TCP supported”.

  • Example: T=1 to announce TCP is supported by the advertising Node.

 

 

 

4.4.   Message Frame Format

 

This section describes the encoding of the Matter message format. The Matter message format pro­ vides flexible support for various communication paradigms, including unicast secure sessions, multicast group messaging, and session establishment itself. The process of encrypting Matter mes­ sages is the same in all modes of communication, and assumes symmetric keys are shared between communicating parties. Unencrypted messages are used only for protocols which bootstrap secure messaging, such as session establishments.

Matter messages are used by Matter applications, as well as the Matter protocol stack itself, to con­ vey application-specific data and/or commands. The Protocol portion of a Matter message contains a Protocol ID and Protocol Opcode which identify both the semantic meaning of the message as well as the structure of any associated application payload data. Matter messages also convey an Exchange ID, which relates the message to a particular exchange (i.e. conversation) taking place between two nodes. Finally, certain types of Matter messages can convey information that acknowl­ edges the reception of an earlier message. This is used as part of the Message Reliability Protocol to provide guaranteed delivery of messages over unreliable transports.

All multi-byte integer fields are transmitted in little-endian byte order unless otherwise noted in the field description.

Matter messages are structured as follows:

 

NOTE         [] denotes the field is optional.

 

Table 7. Matter Message format definition

 

Length Field
Message Header
2 bytes [ Message Length ]
1 byte Message Flags
2 bytes Session ID
1 byte Security Flags
4 bytes Message Counter
0/8 bytes [ Source Node ID ]
0/2/8 bytes [ Destination Node ID ]
variable [ Message Extensions . . . ]
Message Payload
variable [ Message Payload . . . ] (encrypted)

 

 

Length Field
Message Footer
variable [ Message Integrity Check ]

 

The Message Payload of a Matter message SHALL contain a Protocol Message with format as fol­ lows:

Table 8. Protocol Message format definition

 

Length Field
Protocol Header
1 byte Exchange Flags
1 byte Protocol Opcode
2 bytes Exchange ID
2 bytes [ Protocol Vendor ID ]
2 bytes Protocol ID
4 bytes [ Acknowledged Message Counter ]
variable [ Secured Extensions . . . ]
Application Payload
variable [ Application Payload . . . ]

 

4.4.1.  Message Header Field Descriptions

 

4.4.1.1.  Message Length (16 bits)

 

An optional, unsigned integer value specifying the overall length of the message in bytes, not including the size of the Message Length field itself. This field SHALL only be present when the message is being transmitted over a stream-oriented channel such as TCP. When transmitted over a message-oriented channel, the message length is conveyed by the underlying channel. For example, when transmitted over UDP, the message length is equal to the payload length of the UDP packet.

 

4.4.1.2.  Message Flags (8 bits)

 

An unsigned integer bit field containing the following subfields:

 

Table 9. Message Flags field definition

 

 

bit 7

6 5 4 3 2 1 0
Version S DSIZ

 

 

 

NOTE

All unused bits in the Message Flags field are reserved and SHALL be set to zero on transmission and SHALL be silently ignored on reception.

 

Version (4 bits, positions 4-7)

 

An unsigned integer specifying the version of the Matter Message format used to encode the mes­ sage. Currently only one version is defined:

  • 0 — Matter Message Format version 0
  • 1-15 — Reserved for future use

 

Messages with version field set to reserved values SHALL be dropped without sending a message- layer acknowledgement.

 

 

 

NOTE

The Version field conveys information solely about the structure of the Matter mes­ sage itself, not about the structure of the application payload or the interpretation of the message’s type. Thus, changes to how an application handles or interprets a message do not result in the creation of a new message format version number.

 

 

S Flag (1 bit, position 2)

 

A single bit field which SHALL be set if and only if the Source Node ID field is present.

 

DSIZ Field (2 bits, position 0-1)

 

This field SHALL indicate the size and meaning of the Destination Node ID field.

 

  • 0 — Destination Node ID field is not present
  • 1 — Destination Node ID field is present as a 64-bit Node ID
  • 2 — Destination Node ID field is present as a 16-bit Group ID
  • 3 — Reserved for future use

 

Messages with DSIZ field set to reserved values SHALL be dropped without sending a message-layer acknowledgement.

 

4.4.1.3.  Session ID (16 bits)

 

An unsigned integer value identifying the session associated with this message. The session identi­ fies the particular key used to encrypt a message out of the set of available keys (either session or group), and the particular encryption/message integrity algorithm to use for the message. The Ses­ sion ID field is always present. For details on derivation of this field, see respective sections on uni­ cast and group session ID derivation.

 

4.4.1.4.  Security Flags (8 bits)

 

An unsigned integer bit field containing the following subfields:

 

Table 10. Security Flags field definition

 

 

bit 7

6 5 4 3 2 1 0
P C MX Reserved Session Type

 

 

 

 

NOTE

All unused bits in the Security Flags field are reserved and SHALL be set to zero on transmission and SHALL be silently ignored on reception.

 

 

P Flag (1 bit, position 7)

 

The Privacy (P) flag is a single bit field which, when set, SHALL identify that the message is encoded with privacy enhancements as specified in Section 4.8.3, “Privacy Processing of Outgoing Mes­ sages”.

 

C Flag (1 bit, position 6)

 

The Control message (C) flag is a single bit field which, when set, SHALL identify that the message is a control message, such as for the Message Counter Synchronization Protocol, and uses the control message counter for the nonce field as specified in Section 4.7.1.1, “Nonce”.

 

MX Flag (1 bit, position 5)

 

The Message Extensions (MX) flag is a single bit field which, when set, SHALL indicate that the Mes­ sage Extensions portion of the message is present and has non-zero length. Version 1.0 Nodes SHALL set this flag to zero.

 

Session Type (2 bit, position 0-1)

 

An unsigned integer specifying the type of session associated with the message. The following val­ ues are defined:

  • 0 — Unicast Session
  • 1 — Group Session
  • 2-3 — Reserved for future use

 

Messages with Session Type set to reserved values are not valid and SHALL be dropped without sending a message-layer acknowledgement.

The Session Type defines how the Session ID is to be interpreted.

The Unsecured Session SHALL be indicated when both Session Type and Session ID are set to 0. The

Unsecured Session SHALL have no encryption, privacy, or message integrity checking.

 

A Secure Unicast Session SHALL be indicated when Session Type is Unicast Session and Session ID is NOT 0.

 

4.4.1.5.  Message Counter (32 bits)

 

An unsigned integer value uniquely identifying the message from the perspective of the sending node. The message counter is generated based on the Session Type and increases monotonically for each unique message generated. When messages are retransmitted, using the reliable messaging capabilities, the counter remains the same, as logical retransmission is of a given message as identi­ fied by its message counter. Similarly, acknowledgements refer to values of the message counter being acknowledged.

 

 

 

 

 

NOTE

The Message Counter field is scoped to a given Encryption Key. Also, the Message Counter values are independent for control messages and data messages, as indi­ cated by the C Flag. So it is possible to have the same Message Counter for two mes­ sages encrypted with different keys, as well as two messages encrypted with the same key but different values of the C Flag.

 

 

4.4.1.6.  Source Node ID (64 bits)

 

An optional sequence of 8 bytes containing the unique identifier of the source node. The Source Node ID field SHALL only be present in a message when the S Flag in the Message Flags field is set to 1.

 

4.4.1.7.  Destination Node ID

 

The optional Destination Node ID field contains the unique Node Identifier of the destination Node or group to which the message is being sent. The size and encoding of the Destination Node ID field depends on the value of the DSIZ field.

 

4.4.1.8.  Message Extensions (variable)

 

The Message Extensions field is a variable length block of data for providing backwards compatible extensibility. The format of the Message Extensions block is shown in Table 11, “Message Extensions block format definition”. The Message Extensions block SHALL be present only if the MX Flag is set to 1 in the Security Flags field.

Table 11. Message Extensions block format definition

 

Length Field
2 bytes Message Extensions Payload Length, in bytes
variable [ Message Extensions Payload ]

 

If the MX Flag is set to 1, the Message Extensions Payload Length field SHALL be present and SHALL contain the length of the Message Extensions Payload. The Message Extensions Payload Length field SHALL NOT be privacy obfuscated.

Version 1.0 Nodes SHALL ignore the contents of the Message Extensions payload, by skipping it, to access the Message Payload.

 

4.4.2.  Message Footer Field Descriptions

 

4.4.2.1.  Message Integrity Check (variable length)

 

A sequence of bytes containing the message integrity check value (a.k.a. tag or MIC) for the mes­ sage. The length and byte order of the field depend on the integrity check algorithm in use as speci­ fied in Section 3.6, “Data Confidentiality and Integrity”.

The Message Integrity Check field SHALL be present for all messages except those of Unsecured Ses­ sion Type.

 

The MIC is calculated as described in Section 4.7.2, “Security Processing of Outgoing Messages”.

 

4.4.3.  Protocol Header Field Descriptions

 

4.4.3.1.  Exchange Flags (8 bits)

 

An unsigned integer bit field containing the following subfields:

 

Table 12. Exchange Flags field definition

 

 

bit 7

6 5 4 3 2 1 0
V SX R A I

 

 

 

NOTE

All unused bits in the Exchange Flags field are reserved and SHALL be set to zero on transmission and SHALL be silently ignored on reception.

 

 

I Flag (1 bit, position 0)

 

The Initiator (I) flag is a single bit field which, when set, SHALL indicate that the message was sent by the initiator of the exchange.

 

A Flag (1 bit, position 1)

 

The Acknowledgement (A) flag is a single bit field which, when set, SHALL indicate that the mes­ sage serves as an acknowledgement of a previous message received by the current message sender.

 

R Flag (1 bit, position 2)

 

The Reliability (R) flag is a single bit field which, when set, SHALL indicate that the message sender wishes to receive an acknowledgement for the message.

 

SX Flag (1 bit, position 3)

 

The Secured Extensions (SX) flag is a single bit field which, when set, SHALL indicate that the Secured Extensions portion of the message is present and has non-zero length. Version 1.0 Nodes SHALL set this flag to zero.

 

V Flag (1 bit, position 4)

 

The Vendor (V) protocol flag is a single bit field which, when set, SHALL indicate whether the Proto­ col Vendor ID is present.

 

4.4.3.2.  Protocol Opcode (8 bits)

 

An unsigned integer value identifying the type of the message. The Protocol Opcode is interpreted relative to the Matter protocol specified in the Protocol ID field.

Opcodes are defined by the corresponding Protocol specification, for example Secure Channel Pro­ tocol.

 

4.4.3.3.  Exchange ID (16 bits)

 

An unsigned integer value identifying the exchange to which the message belongs. An Exchange ID is allocated by the initiator of the exchange, and is unique within the initiator exchange number space as specified in Section 4.9.2, “Exchange ID”.

 

4.4.3.4.  Protocol ID (16 bits)

 

An unsigned integer value identifying the protocol in which the Protocol Opcode of the message is defined.

When the Protocol Vendor ID is the Matter Standard Vendor ID, the Protocol ID SHALL have one of the values specified by Table 13, “Protocol IDs for the Matter Standard Vendor ID”.

Table 13. Protocol IDs for the Matter Standard Vendor ID

 

Range Type Message Specification
0x0000 PROTOCOL_ID_SECURE_CHAN­ NEL Section 4.10.1, “Secure Channel Protocol Messages”
0x0001 PROTOCOL_ID_INTERACTION_­ MODEL Section 10.2.1, “IM Protocol Messages”
0x0002 PROTOCOL_ID_BDX Section 11.21.3.1, “BDX Protocol Messages”
0x0003 PROTOCOL_ID_USER_DIRECTED_­ COMMISSIONING Section 5.3.2, “UDC Protocol Messages”
0x0004 PROTOCOL_ID_FOR_TESTING Reserved for bespoke protocols run in an isolated test environment.

0x0005 –

0xFFFF

reserved reserved

 

4.4.3.5.  Protocol Vendor ID (16 bits)

 

An optional, unsigned integer value that contains the Vendor ID namespacing for the Protocol ID field. This field SHALL only be present when the V Flag is set; otherwise the default is 0, corre­ sponding to the Matter Standard Vendor ID.

 

4.4.3.6.  Acknowledged Message Counter (32 bits)

 

An optional, unsigned integer value containing the message counter of a previous message that is being acknowledged by the current message. The Acknowledged Message Counter field is SHALL only be present when the A Flag in the Exchange Flags field is 1.

 

4.4.3.7.  Secured Extensions (variable)

 

The Secured Extensions field is a variable length block of data for providing backwards compatible extensibility. The format of the Secured Extensions block is shown in Table 14, “Secured Extensions block format definition”. The Secured Extensions block SHALL be present only if the SX Flag is set to 1 in the Exchange Flags field.

 

Version 1.0 Nodes SHALL ignore the contents of the Secured Extensions payload.

 

The Secured Extensions block SHALL be encrypted and authenticated based on the Security Flags settings.

Table 14. Secured Extensions block format definition

 

Length Field
2 bytes Secured Extensions Payload Length, in bytes.
variable [ Secured Extensions Payload ]

 

4.4.3.8.  Application Payload (variable length)

 

A sequence of zero or more bytes containing the application data conveyed by the message.

 

4.4.4.  Message Size Requirements

 

Support for IPv6 fragmentation is not mandatory in Matter, and the expected supported MTU is 1280 bytes, the minimum required by IPv6. Therefore, all messages, including transport headers, SHALL fit within that minimal IPv6 MTU. This message size limit SHALL apply to the UDP transport. A message received over UDP that exceeds this message size limit SHALL NOT be processed. Mes­ sages sent over TCP or BTP over BLE transports MAY exceed the message size limit if both nodes are capable of supporting larger message sizes.

 

 

 

4.5.   Message Counters

 

All messages contain a 32-bit message counter assigned by the sender of the message. Message counters are assigned sequentially, by monotonically increasing the counter value maintained by the sender of the message. Message counters serve several purposes:

  • Duplicate Message Detection – Receiving systems use message counters to detect messages that have been retransmitted by the sender, g. in response to packet loss in the network.
  • Message Acknowledgement – In the Message Reliability Protocol (MRP), message counters pro­ vide a way for receivers to identify messages for the purpose of acknowledging their
  • Encryption Nonces – When encrypted messages are sent, message counters provide an encryp­ tion nonce that ensures each message is encrypted in a unique
  • Replay Prevention – Related to encryption, message counters also provide a means for detect­ ing and preventing the replay of encrypted

 

4.5.1.  Message Counter Types

 

All Nodes implement three global 32-bit counters to vend message counters for certain types of messages:

  • Global Unencrypted Message Counter
  • Global Group Encrypted Data Message Counter
  • Global Group Encrypted Control Message Counter

 

Additionally, Nodes implement a separate 32-bit counter for each session as part of secure session state:

  • Secure Session Message Counter

 

Technical details for how each counter type works are described in the following sections. Table 15, “Message Counter Type Overview” is provided to summarize higher-level differences between Mes­ sage Counter Types:

Table 15. Message Counter Type Overview

 

Message Counter Type Session Type Lifetime Rollover Pol­ icy Nonvolatile
Global Unencrypted Unsecured Unlimited Allowed Optional
Global Encrypted Data Group Operational Group Key Allowed Mandatory
Global Encrypted Con­ trol Group Operational Group Key Allowed Mandatory
Secure Session Unicast Session Key Expires Optional

 

4.5.1.1.  Message Counter Initialization

 

All message counters SHALL be initialized with a random value using the Crypto_DRBG(len = 28) + 1 primitive. Message counters are initialized to a random number to increase the difficulty of traffic analysis attacks by making it harder to determine how long a particular session has been open. The

random initializer ranges from 1 to 228 in order to maximize initial entropy while still reserving the vast majority of the range to actual counter values (roughly 232 – 228).

 

4.5.1.2.  Global Unencrypted Message Counter

 

All Nodes SHALL implement an unencrypted message counter, which is used to generate counters for unencrypted messages.

Typically, Nodes store the Global Unencrypted Message Counter in RAM. This makes the counter sub­ ject to loss whenever the system reboots or otherwise loses its state. This is permissible because retaining the Global Unencrypted Message Counter is not essential to the confidentiality or integrity of the message. In the event that the Global Unencrypted Message Counter for a Node is lost, Nodes SHALL randomize the initial value of this counter on startup per Section 4.5.1.1, “Message Counter Initialization”.

 

4.5.1.3.  Global Group Encrypted Message Counters

 

The Global Group Encrypted Message Counters are used to generate the counter for messages encrypted using group keys. There are two such counters:

  • The Global Group Encrypted Data Message Counter is used to encode regular data messages encrypted with a group
  • The Global Group Encrypted Control Message Counter is used to encode control messages encrypted with a group

 

Some Nodes might not be required to implement communication using group keys, in which case they MAY omit the Global Group Encrypted Message Counters. In contrast to the Global Unencrypted Message Counter, Nodes are required to persist the Global Group Encrypted Message Counters in durable storage. In particular, Nodes are required to ensure that the value of the Global Group Encrypted Message Counters never rolls back and that it is monotonic within the bounds of its range for its use for a given group key. A Node SHALL randomize the initial value of this counter on fac­ tory reset per Section 4.5.1.1, “Message Counter Initialization”.

While Global Group Encrypted Message Counters are shared by many group keys to generate nonces, rollover is not an issue as long as the Epoch Key that generates each operational group key rotates frequently enough.

 

 

 

NOTE

If a nonce is duplicated for a given key, the security consequences are isolated only to the specific key with which the duplicate nonce occurred — a key that has not been updated prior to rollover and has been presumably abandoned or aged out.

 

 

4.5.2.  Secure Session Message Counters

 

A Secure Session Message Counter is a per-session, 32-bit, ephemeral counter that is used by the encoding of any encrypted messages using an associated session key. Each peer in a Secure Unicast Session SHALL maintain its own message counters, with independent counters being used for each unique session used. Session Message Counters SHALL exist for as long as the associated security session is in effect. A Node SHALL randomize the initial value of this counter on session establish­ ment per Section 4.5.1.1, “Message Counter Initialization”.

The Secure Session Message Counter history window SHALL be maintained for the lifetime of the session, and SHALL be deleted at the same time as the session keys, when the session ends.

Sessions SHALL be discarded and re-established before any Secure Session Message Counter over­ flow or repetition occurs.

 

4.5.3.  Message Counters as Encryption Nonces

 

In the context of encrypted messages, message counters serve as nonces for the encryption algo­ rithm, ensuring that every message is encrypted in a unique manner. The uniqueness of an encrypted message’s counter is vital to the confidentiality of the message, as the encryption algo­ rithm makes it trivial for an eavesdropper to decrypt messages if the attacker can find two different messages with the same message counter that were encrypted using the same key. Specifically, an attacker can XOR the two different messages that share the same key and nonce to obtain a “block key” which can be used to decrypt any message that uses that key and nonce.

Nodes SHOULD rotate their encryption keys on a regular basis, to ensure that old encryption keys are retired before a Global Group Encrypted Message Counter has a chance to wrap to a value previ­ ously used with the encryption key. In practice, the frequency of message transmission is such that encryption keys generally rotate at a rate that is much faster than the rate at which a Global Group Encrypted Message Counter wraps. In the event that a Global Group Encrypted Message Counter wraps before the associated keys are rotated, all keys associated with that Global Group Encrypted Message Counter are considered exhausted and are no longer valid to use. In such cases, a new uni­ cast session SHALL be established to the Matter Node to rotate such retired keys before secure com­

 

munication can resume. Given the importance of confidentiality and message integrity, every effort SHOULD be made to ensure that keys are rotated on a regular basis.

 

4.5.4.  Replay Prevention and Duplicate Message Detection

 

Beyond their role as encryption nonces, message counters also serve as a means to detect repeated reception of the same message. Message duplication may occur for a number of reasons: out-of- order arrival, network latency, malicious attack, or network error. For example, a duplicate can be caused when a sender retransmits a message after failing to receive an acknowledgement, or because a malicious third party attempted to replay an old message to gain some advantage. To detect duplicate messages, Nodes maintain a history window of the message counters they have received from a particular sender (see Message Reception State). Whenever a message is received, its message counter is checked against the history window of message counters from that sender to determine whether it is a duplicate. The Message Layer SHALL discard duplicate messages before they reach the application layer.

 

4.5.4.1.  Message Reception State

 

The state maintained by a Node about the messages it has received from a particular peer is referred to as message reception state. Nodes use this state information to determine whether a newly arrived message is a duplicate of a previous message. Message reception state is maintained on a per-peer or per-session basis, depending on the type of message encryption being used.

At a conceptual level, message reception state consists of a set of integers corresponding to the counters of all the messages that have been received from a particular peer. To limit the amount of memory required to store this state, Nodes employ a lossy compression scheme that takes advan­ tage of the fact that message counters are generated sequentially by the sender. The scheme allows for a limited amount of out-of-order message arrivals due to network effects without inducing false detection of duplicates.

 

In the compressed form, message reception state is structured as a pair of values: a integer repre­ senting the largest valid, or maximum message counter received from the peer (max_message_­ counter), and a bitmap of size MSG_COUNTER_WINDOW_SIZE indicating which messages immedi­

ately prior to the max message have been received. The offset into the bitmap equates to the differ­ ence between the corresponding message counter and the max message counter, i.e. the first bit  in

the bitmap indicates whether the message with the counter of max_message_counter – 1 has been received, the second indicates whether message max_message_counter – 2 has been received, and so

  1. A message counter is within the range of the bitmap, also known as the message counter win­ dow, when the counter value is between [(max_message_counter – MSG_COUNTER_WINDOW_SIZE) to (max_message_counter – 1) mod 232]. As messages arrive, the message reception state is queried to

determine if an arriving message is new or duplicate. If a message is new, the state is then updated to reflect the arrival of the message. When a message arrives with a message counter that is logi­ cally greater than the current maximum message counter for that peer, the maximum message counter value for the peer is updated and the bitmap shifted accordingly.

 

 

Figure 7. Message Reception State Example

 

4.5.4.2.  Use of Message Reception State for Encrypted Messages

 

The algorithm for querying and updating message reception state varies slightly depending on whether the system is tracking reception of encrypted messages or unencrypted messages.

 

Message Counters with maximum

 

For encrypted messages of Secure Unicast Session Type, any arriving message with a counter in the range [(max_message_counter + 1) to (232 – 1)] SHALL be considered new, and cause the max_mes­ sage_counter value to be updated. Message counters within the range of the bitmap SHALL be con­

sidered duplicate if the corresponding bit offset is set to true. All other message counters SHALL be considered duplicate.

 

Message Counters with rollover

 

A message counter with rollover is a free running message counter that monotonically increases, but rolls over to zero when it exceeds the maximum value of the counter (32-bits). Group keys are secured by a shared, global message counter with rollover as described in Section 4.5.1.3, “Global Group Encrypted Message Counters”.

 

For encrypted messages of Group Session Type, any arriving message with a counter in the range [(max_message_counter + 1) to (max_message_counter + 231 – 1)] (modulo 232) SHALL be considered new, and cause the max_message_counter value to be updated. Messages with counters from

[(max_message_counter – 231) to (max_message_counter – MSG_COUNTER_WINDOW_SIZE – 1)] (modulo 2

32) SHALL be considered duplicate. A message counter equal to max_message_counter SHALL be con­

sidered duplicate. Message counters within the range of the bitmap SHALL be considered duplicate

 

if the corresponding bit offset is set to true.

 

This scheme for encrypted messages effectively divides the message counter space in half: those counters that are forward of the max message counter, which are considered new, and those coun­ ters that are behind the max message counter, which are considered duplicates unless indicated otherwise by the values in the bitmap.

 

4.5.4.3.  Use of Message Reception State for Unencrypted Messages

 

For unencrypted messages, the algorithms for tracking messages and detecting duplicates are simi­ lar to, but more permissive than for encrypted messages using Section 4.5.4.2.2, “Message Counters with rollover”. This reflects the fact that duplicate detection of unencrypted messages is not done for security reasons, but rather to catch duplicates caused by network errors (e.g. loss of an ack), which are generally more bounded in time. The more relaxed algorithm for unencrypted duplicate detection also relaxes the durability requirement on the sender’s message counter, allowing senders to store the counter in RAM.

For unencrypted messages, any message counter equal to max_message_counter or within the mes­ sage counter window, where the corresponding bit is set to true SHALL be considered duplicate. All other message counters, whether behind the window or ahead of max_message_counter, are consid­ ered new and shall update max_message_counter and shift the window accordingly.  Messages with a

counter behind the window are likely caused by a node rebooting and are thus processed as rolling back the window to the current location. Note that when max_message_counter is close to the mini­ mum of the range, the window shall roll back to cover message counters near the maximum of the

range.

 

4.5.4.4.  Message Reception State Initialization

 

To initialize Message Reception State for a given Peer Node ID, initial max_message_counter, Message Type (control or data), Encryption Level (encrypted or unencrypted), and Encryption Key (for any Encryption Level except unencrypted):

 

  • The Message Reception State fields SHALL be set as follows:
    • The Peer Node ID SHALL reference the given Peer Node
    • The Message Type SHALL be the given Message
    • The Encryption Level SHALL be the given Encryption
    • If the Encryption Level is NOT unencrypted, the Encryption Key SHALL reference the given
    • The max_message_counter SHALL be set to the given max_message_counter.
    • The Message Counter bitmap SHALL be set to all 1, indicating that only new messages with counter greater than max_message_counter SHALL be accepted.

 

4.5.5.  Counter Processing of Outgoing Messages

 

  1. Obtain the outgoing message counter of the sending Node for the given Security Flags, Session Id, and Encryption Key:

 

  1. A message of Unsecured Session Type SHALL use the current Global Unencrypted Message Counter.
  2. A message of Secure Unicast Session Type SHALL use the current Secure Session Message Counter for the session associated with the Session
  3. A message of Group Session Type SHALL use:
    1. The Global Group Encrypted Data Message Counter if the Security Flags C Flag = 0.
    2. The Global Group Encrypted Control Message Counter if the Security Flags C Flag = 1.
  4. The outgoing message counter from step 1 SHALL be incremented by
  5. Store the incremented outgoing message counter in the OutgoingMessageCounter element asso­ ciated with the Session Context for the
    1. If the message counter wraps around from 0xFFFF_FFFF to 0x0000_0000 and the message is of Secure Unicast Session Type:
      1. The Encryption Key SHALL be expired in the Session Context. The session will need to be renegotiated to resume communication after transmission of this final

 

4.5.6.  Counter Processing of Incoming Messages

 

  1. Determine the Message Reception State for the sending peer and get the current max_message_­ counter.
    1. Given a decrypted message of Unicast Session Type:
      1. Get the session-specific Message Reception State from the Secure Unicast Session Con­ text.
    2. Given a decrypted message of Group Session Type:
      1. Extract the Source Node ID from the Message Header.
        1. If there is no Source Node ID for the message, drop the
      2. Get the Message Reception State for the Source Node ID of the given message:
        1. If the Security Flags C Flag = 0, get the Data Message Reception State for the peer node.
        2. If the Security Flags C Flag = 1, get the Control Message Reception State for the peer node.
  • If there is no Message Reception State for the groupcast message, initiate Section 4.16.4, “Unsynchronized Message Processing”.
  1. Given an unencrypted message:
    1. Get the Message Reception State associated with the Unsecured Session Context.
    2. If there is no Message Reception State for the unencrypted message, create it with the information from the given
  2. If the Message Counter is outside the valid message counter window, the message SHALL be marked as a duplicate. Note that while messages may be outside of the window for reasons other than being a duplicate, and we always mark them as

 

  1. If the message is a duplicate:
    1. If the message is marked as encrypted, follow Section 4.5.4.2, “Use of Message Reception State for Encrypted Messages”.
    2. If the message is marked as unencrypted, follow Section 4.5.4.3, “Use of Message Reception State for Unencrypted Messages”.
    3. If the message is encrypted and marked as a duplicate, i.e. Message Counter is outside the valid message counter window or marked as previously received in the Message Reception State:
      1. Perform Section 4.11.5.2, “Reliable Message Processing of Incoming Messages” on the duplicate
    4. Otherwise, update the Message Reception State as detailed in Section 4.5.4.1, “Message Reception State”, and accept the message for further

 

 

 

4.6.   Message Processing

 

This sub-clause describes the fundamental procedures for transmission and reception.

 

4.6.1.  Message Transmission

 

To prepare a message for transmission with a given Session ID, Destination Node ID (which may be a group node id or an operational node id) and Security Flags, the following steps SHALL be per­ formed, in order:

  1. Process the message as described in Section 4.5.5, “Counter Processing of Outgoing Messages”.
  2. If the message’s Session Type is a Unicast Session:
    1. Set SessionTimestamp to a timestamp from a clock which would allow for the eventual deter­ mination of the last session use relative to other
    2. Process the message as described in Section 4.7.2, “Security Processing of Outgoing Mes­ sages”.
    3. Process the message as described in Section 4.8.3, “Privacy Processing of Outgoing Mes­ sages”.

 

4.6.2.  Message Reception

 

To process a received message, the following steps SHALL be performed in order:

 

  1. Perform validity checks on the message; if any fail, processing of the message SHALL stop, and a ‘message invalid’ error SHOULD be indicated to the next higher layer:
    1. The Version field SHALL be 0.
    2. If the message is of Secure Unicast Session Type:
      1. The DSIZ field SHALL NOT indicate a Group ID is
    3. If the message is of Group Session Type:
      1. The DSIZ field SHALL NOT be 0.

 

  1. The S Flag field SHALL NOT be 0.
  1. If the message is NOT of Unsecured Session Type:
    1. Obtain the Privacy and Encryption Keys associated with the given Session ID:
      1. If no keys are found, security processing SHALL indicate a failure to the next higher layer with a status of ‘message security failed’ and no further security processing SHALL be done on this
    2. For each Privacy and Encryption Key, of which there may be more than one in the case of group messages:
      1. If the P Flag is set, follow Section 4.8.4, “Privacy Processing of Incoming Messages” to deobfuscate the
      2. Follow Section 4.7.3, “Security Processing of Incoming Messages” to decrypt and authen­ ticate the
    3. Follow Section 4.5.6, “Counter Processing of Incoming Messages” to enforce replay protection and duplicate
    4. If the message transport is UDP, follow Section 4.11.5.2, “Reliable Message Processing of Incom­ ing Messages” to process message
    5. If the message’s Session Type is a Unicast Session:
      1. Set SessionTimestamp and ActiveTimestamp to a timestamp from a clock which would allow for the eventual determination of the last session use relative to other
    6. The received message is then delivered to Section 9.5, “Exchange Message Processing”.

 

 

 

4.7.   Message Security

 

The detailed steps involved in security processing of outgoing and incoming Matter messages are described in Section 4.7.2, “Security Processing of Outgoing Messages” and Section 4.7.3, “Security Processing of Incoming Messages” respectively. Section 4.7.1, “Data confidentiality and integrity with data origin authentication parameters” defines how the cryptographic parameters are set for securing Matter messages.

 

4.7.1.  Data confidentiality and integrity with data origin authentication parameters

 

This section specifies the parameters to use the data confidentiality and integrity cryptographic primitive as defined in Section 3.6, “Data Confidentiality and Integrity”.

The parameters in this section SHALL apply for all encrypted messages, i.e. all messages except those of Unsecured Session Type.

 

4.7.1.1.  Nonce

 

The nonce SHALL be formatted as specified in Table 16, “Nonce”.

 

Table 16. Nonce

 

 

Octets: 1 4 8
Security Flags Message Counter Source Node ID

 

The nonce used for the Authenticated Encryption with Additional Data (AEAD) algorithm (see Sec­ tion 3.6, “Data Confidentiality and Integrity”) for a given message SHALL be defined as the concate­ nation of the Security Flags, the Message Counter, and the Source Node ID of that message. The scalar fields in the nonce, namely the Message Counter and the Source Node ID SHALL be encoded in little-endian byte order for the purposes of serialization within the nonce, that is, in the same byte ordering as the segment of the message from which its data originates.

The Source Node ID field used in the nonce SHALL be set to the Operational Node ID of the node originating security protection of the message:

  • If the message is of Secure Unicast Session Type:
    • For a CASE session, the Nonce Source Node ID SHALL be determined via the Secure Session Context associated with the Session
    • For a PASE session, the Nonce Source Node ID SHALL be Unspecified Node ID.
  • If the message is of Group Session Type:
    • The S Flag of the message SHALL be 1 and the Nonce Source Node ID SHALL be the Source Node ID of the
    • If the S Flag of the message is 0 the message SHALL be dropped.

 

 

 

NOTE

Because PASE negotiates strong one-time keys per session and the I2RKey and R2IKey are distinct for each direction of communication, the use of the Unspecified Node ID as the Nonce Source Node ID remains semantically secure.

 

 

4.7.2.  Security Processing of Outgoing Messages

 

The process for encrypting Matter messages is depicted graphically in Figure 8, “Matter Message Encryption” with color code conventions described in Figure 9, “Matter Message Encryption Leg­ end”.

 

 

Figure 8. Matter Message Encryption

 
   

Figure 9. Matter Message Encryption Legend

 

To prepare a secure message for transmission with a given Session ID, Destination Node ID (which may be a group node id or an operational node id) and Security Flags, the Node SHALL perform the following steps:

  1. Obtain the Encryption Key associated with the Session ID and Destination Node ID and the Ses­ sion Type associated with the Destination Node ID:
    1. If no key is found for the given Session ID, security processing SHALL fail and no further security processing SHALL be done on this
  2. Obtain the outgoing message counter of the sending Node as per Section 4.5.5, “Counter Process­

 

ing of Outgoing Messages”.

  1. Set the Security fields as follows:
    1. The Session ID field SHALL be set to the value provided to step
    2. The Security Flags field SHALL be set to the value provided to step 1 with the following sub­ fields updated:
      1. The Session Type field SHALL be set to the value obtained from step
    3. Set the Message Flags, Destination Node ID, and Source Node ID fields as follows:
      1. If the Session Type is a unicast session:
        1. Set S Flag to
        2. Set DSIZ to
  • Omit both Destination Node ID, and Source Node ID.
  1. Else if the Session Type is a group session:
    1. Set S Flag to
    2. Set DSIZ to
  • Set Source Node ID field to the operational node id of the sending
  1. Set Destination Node ID field to the 16-bit Group ID derived from the Destination Node ID.
  1. Set the Message Counter field to the outgoing message counter from step
  2. Execute the AEAD generate and encrypt operation, as specified in Section 3.6.1, “Generate and encrypt”, with the following instantiations:
    1. The bit string key K SHALL be the Encryption Key obtained from step 1;
    2. The nonce N SHALL be the CRYPTO_AEAD_NONCE_LENGTH_BYTES-octet string constructed accord­ ing to Table 16, “Nonce”;
    3. The parameter P SHALL be the Message Payload;
    4. The additional data octet string A SHALL be the Message Header contents, using little-endian byte order for all scalars, exactly as they appear in the message segments from which they originate:
 
   

 

with the optional fields appended according to the Message Flags:

 
   

 

  1. C = Crypto_AEAD_GenerateEncrypt(K, P, A, N)
  1. If the AEAD operation invoked in step 6 results in an error, then security processing SHALL fail and no further security processing SHALL be done on this

 

  1. Let C be the output from step 6. C contains the tag of CRYPTO_AEAD_MIC_LENGTH_BITS bits (Message Integrity Check (MIC)) as specified by Section 3.6.1, “Generate and encrypt”. The secured outgo­ ing message SHALL be:
 
   

 

4.7.3.  Security Processing of Incoming Messages

 

All incoming message processing SHALL occur in a serialized manner. If an implementation chooses to process messages in a parallel manner, it must ensure that the behavior is opaque-box identical to a serialized processing implementation.

If the transport layer receives a secured message as indicated by the Session ID, it SHALL perform the following steps:

  1. Determine the Session Type, Session ID, and Message Counter from the message header of the received
  2. Obtain the Encryption Key associated with the Session Context of the given Session ID and Ses­ sion Type:
    1. If no key is found for the given Session ID, security processing SHALL indicate a failure to the next higher layer with a status of ‘message security failed’ and no further security processing SHALL be done on this
  3. Execute the AEAD decryption and verification operation as specified in Section 3.6.2, “Decrypt and verify” with the following instantiations:
    1. The bit string key K SHALL be the Encryption Key obtained from step 2;
    2. The nonce N SHALL be the CRYPTO_AEAD_NONCE_LENGTH_BYTES-octet string constructed accord­ ing to Table 16, “Nonce”;
    3. The parameter C SHALL be the encrypted and authenticated Message Payload;
    4. The additional data octet string A SHALL be the authenticated Message Header:
    5. {success, P} = Crypto_AEAD_DecryptVerify(K, C, A, N)
  4. Return the result {success, P} of the AEAD operation:
    1. If the success is FALSE, security processing SHALL fail and further processing SHALL NOT be performed on this message. An appropriate error SHOULD be raised to the upper layer to indicate the
    2. Otherwise, set the octet string PlaintextMessage to the string
 
   

 

  1. PlaintextMessage now represents the deciphered, authenticated, received
    1. NOTE: The message has not yet undergone counter processing nor replay
    2. The PlaintextMessage SHALL be marked as successfully security processed and SHALL be

 

released to the next processing layer.

 

 

 

4.8.   Message Privacy

 

Privacy processing of a message describes the obfuscation and deobfuscation of the message header fields after encryption and before decryption.

The detailed steps involved in privacy processing of outgoing and incoming Matter messages are described in Section 4.8.3, “Privacy Processing of Outgoing Messages” and Section 4.8.4, “Privacy Processing of Incoming Messages” respectively. They rely on the cryptographic primitives in Section 3.7, “Message privacy”.

 

4.8.1.  Privacy Key

 

The Privacy Key is a symmetric key specifically used for Privacy Processing that is derived from the EncryptionKey used for Security Processing of a given message. Given a Session ID reference to a specific Encryption Key, the Privacy Key is derived as follows:

 

PrivacyKey =

Crypto_KDF (

InputKey = EncryptionKey, Salt = [],

Info = “PrivacyKey”,

Length = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS

)

 

 

4.8.2.  Privacy Nonce

 

The Privacy Nonce is a nonce specifically used for Privacy Processing that is derived from the Ses­ sionId and MIC of the message. The Privacy Nonce SHALL be the CRYPTO_AEAD_NONCE_LENGTH_BYTES

-octet string constructed as the 16-bit Session ID (in big-endian format) concatenated with the lower 11 (i.e. CRYPTO_AEAD_MIC_LENGTH_BYTES-5) bytes of the MIC:

 

PrivacyNonce = Session ID || MIC[5..15]

For example if Session ID is 42 (i.e. 0x002A) and the computed MIC is

c5:a0:06:3a:d5:d2:51:81:91:40:0d:d6:8c:5c:16:3b:

 

Session ID = 00:2a

MIC = c5:a0:06:3a:d5:d2:51:81:91:40:0d:d6:8c:5c:16:3b MIC[5..15] = d2:51:81:91:40:0d:d6:8c:5c:16:3b

PrivacyNonce = SessionID || MIC[5..15] = 00:2a || d2:51:81:91:40:0d:d6:8c:5c:16:3b PrivacyNonce = 00:2a:d2:51:81:91:40:0d:d6:8c:5c:16:3b

 

4.8.3.  Privacy Processing of Outgoing Messages

 

The process for privacy encoding Matter message headers is depicted graphically in Figure 10, “Matter Message Privacy”.

 
   

Figure 10. Matter Message Privacy

 

To apply privacy obfuscation to an encrypted message prepared for transmission by Section 4.6.1, “Message Transmission”, apply obfuscation steps as follows:

  1. If P Flag is not set, do
  2. Obtain the Privacy Key for the Encryption Key used to secure the
  3. Execute the encryption operation as specified in Section 3.7.1, “Privacy encryption” with the fol­ lowing instantiations:
    1. The bit string key K SHALL be the Privacy Key obtained from step 1;
    2. The MIC SHALL be the last CRYPTO_AEAD_MIC_LENGTH_BYTES bytes of the C outcome of the mes­ sage security protection as specified in Section 4.7.2, “Security Processing of Outgoing Mes­ sages” (MIC = C[(CRYPTO_AEAD_MIC_LENGTH_BYTES-1)..0])
    3. The nonce N SHALL be the PrivacyNonce of the
    4. The parameter M SHALL be the message header fields where optional fields are only present in M if they are present in the message:
 
   

 

  1. CP = Crypto_Privacy_Encrypt(K, M, N)
  1. Let CP be the obfuscated output from step 2. CP SHALL be used in the final private message in place of the message header

 

4.8.4.  Privacy Processing of Incoming Messages

 

To deobfuscate a private message received by Section 4.6.2, “Message Reception” with a given Pri­ vacy Key, perform security processing as follows:

  1. If P Flag is not set, do
  2. With the given Privacy Key, execute the decryption as specified in Section 3.7.2, “Privacy decryp­ tion” with the following instantiations:
    1. The bit string key K SHALL be the Privacy Key obtained from step 1;
    2. The MIC SHALL be the last CRYPTO_AEAD_MIC_LENGTH_BYTES bytes of the C outcome of the mes­ sage security protection as specified in Section 4.7.3, “Security Processing of Incoming Mes­ sages” (MIC = C[(CRYPTO_AEAD_MIC_LENGTH_BYTES-1)..0])
    3. The nonce N SHALL be the PrivacyNonce of the
    4. The parameter CP SHALL be the message header fields where optional fields are only present in CP if they are present in the message:
 
   

 

  1. M = Crypto_Privacy_Decrypt(K, CP, N)
  1. Let M be the deobfuscated output from step
    1. M SHALL be used in the final private message in place of the message header
    2. The first successfully validated message, M, by Section 4.7.3, “Security Processing of Incom­ ing Messages” SHALL terminate iteration through Privacy Keys in step

 

 

 

4.9.   Message Exchanges

 

An Exchange provides a way to group related messages together, organize communication flows, and enable higher levels of the communication stack to track semantically relevant groupings of messages.

An Exchange SHALL be bound to exactly one underlying session that will transport all associated Exchange messages for the life of that Exchange. The underlying session SHALL be one of the fol­ lowing session types: secure unicast (as established by PASE or CASE), unsecured (as is used for the initial session establishment phase of a PASE/CASE session), secure group, or MCSP.

When used with reliability, Exchanges assume basic flow control by the upper layer. The Exchange Layer SHALL not accept a message from the upper layer when there is an outbound reliable mes­ sage pending on the same Exchange.

 

4.9.1.  Exchange Role

 

The first Node to send a message in an Exchange is said to be in the Initiator role, and all the other Nodes that subsequently participate in the Exchange are said to be in a Responder role. An Exchange is always between one Initiator and one or more peer Responder Nodes. An Exchange

 

does not survive a reboot of one of the participants. Adjacent layers MAY close an Exchange at any time.

 

4.9.2.  Exchange ID

 

An Exchange of messages is identified by the Exchange ID field described in Section 4.4.3.3, “Exchange ID (16 bits)”. The Exchange ID is allocated by the Initiator. The first message the Initiator sends in a new Exchange SHALL contain a fresh value for the Exchange ID field. The Exchange is

then identified by the tuple {Session Context, Exchange ID, Exchange Role} where Session Context is

one of an Unsecured, Secured, Groupcast or MCSP session context. All messages that are part of a

given Exchange, whether they are sent by the Initiator or not, share the same Exchange ID, allow­ ing the Initiator and Responder Nodes to match responses to requests or otherwise group messages together that are part of more complex transactions. The first Exchange ID for a given Initiator Node SHALL be a random integer. All subsequent Exchange IDs created by that Initiator SHALL be the last Exchange ID it created incremented by one. An Exchange ID is an unsigned integer that rolls over to zero when its maximum value is exceeded.

 

4.9.3.  Exchange Context

 

An Exchange context is the metadata tracked for an Exchange by all exchange participants. An Exchange context tracks the following data:

  1. Exchange ID: The Exchange ID assigned by the Initiator
  2. Exchange Role: Initiator or Responder
  3. Session Context: The underlying Unsecured, Secured, Groupcast or MCSP session context
    • Together, Session Context, Exchange ID and Role comprise a unique key allowing partici­ pants to identify any

 

4.9.3.1. Protocol ID Registration

The Interaction Model layer indicates to the Exchange Layer which Protocols it will accept. Any message for a Protocol ID that is not registered with the Exchange Layer SHALL be dropped.

 

4.9.4.  Exchange Message Dispatch

 

When sending a message to the Exchange Layer, the next higher layer SHALL specify whether the message is part of an existing Exchange, or the first of a new Exchange. For the case of a first mes­ sage, the Initiator creates a new Exchange. The Node in the Initiator role SHALL always set the I Flag in the Exchange Flags of every message it sends in that Exchange.

Each Node in a Responder role for an Exchange SHALL use the Exchange ID received in previous messages for the Exchange. Each Node in the Responder role SHALL NOT set the I Flag in the Exchange Flags of every message it sends in that Exchange. Each Node in a Responder role SHALL NOT set the Destination Node ID field to a value that identifies any Node other than the Node in the Initiator role for the Exchange.

Processing SHALL then proceed to Section 4.11.5.1, “Reliable Message Processing of Outgoing Mes­ sages”.

 

4.9.5.  Exchange Message Processing

 

After completion of Section 4.6.2, “Message Reception”, if the message matches an existing Exchange, it is dispatched to the appropriate protocol handler in the next higher layer. Messages for an existing Exchange are dispatched to the handler for that Exchange. Otherwise, the unso­ licited message that created the Exchange is dispatched to the unsolicited message handler.

 

4.9.5.1.  Exchange Message Matching

 

Upon receipt of a message, the Exchange Layer attempts to match the message to an existing Exchange. A given message is part of an Exchange if it satisfies all the following criteria:

  1. The message was received over the session associated with the
  2. The Exchange ID of the message matches the Exchange ID of the Exchange,
  3. The message has the I Flag set and the Exchange Role of the Exchange is Responder,

OR the message does not have the I Flag set and the Exchange Role of the Exchange is Initiator.

 

If the message does not match an existing Exchange, the message is considered an unsolicited mes­ sage.

 

4.9.5.2.  Unsolicited Message Processing

 

An unsolicited message is processed as follows:

 

  1. If the unsolicited message is not marked as having a duplicate message counter, has a registered Protocol ID, and the I Flag is set:
    1. Create a new exchange from the incoming
    2. The new exchange will be used by the upper layer for generating responses and subsequent processing of the
  2. Otherwise, if the message has the R Flag set:
    1. Create an ephemeral exchange from the incoming message and send an immediate stand­ alone
    2. The message SHALL NOT be forwarded to the upper layer, and excluding the sending of an immediate standalone acknowledgment, SHALL be
    3. The ephemeral exchange created for such duplicate or unknown messages with R Flag set is automatically closed in Section 4.11.5.2.2, “Standalone acknowledgement processing”.
  3. Otherwise, processing of the message SHALL

 

Creating an Exchange based on an Incoming Message

 

The steps to create a new Exchange based on an incoming message are as follows:

 

  1. A new Exchange and Exchange Context SHALL be created with the following settings:
    1. The Exchange ID SHALL be set to the Exchange ID of the
    2. The Exchange Role SHALL be set to the inverse of the incoming message I Flag, for example set the Exchange Role to Responder if the message is from an

 

  1. The Session Context SHALL be set to the Session on which the message was

 

A node SHOULD limit itself to a maximum of 5 concurrent exchanges over a unicast session. This is to prevent a node from exhausting the message counter window of the peer node.

 

4.9.5.3.  Closing an Exchange

 

An Exchange MAY be closed by the application layer or a fatal connection error from the lower message layer. The process of closing an Exchange follows:

 

  1. Any pending acknowledgements associated with the Exchange SHALL be flushed. If there is a pending acknowledgment in the acknowledgement table for the Exchange and it has Stand­ aloneAckSent set to false:
    1. Immediately send a standalone acknowledgement for the pending
    2. Remove the acknowledgement table entry for the pending
  2. Wait for all pending retransmissions associated with the Exchange to
    1. If the retransmission list for the Exchange is empty, remove the
    2. Otherwise, leave the Exchange open and only close it once the retransmission list is

 

These steps are depicted in Figure 11, “Exchange close flow”.

 
   

Figure 11. Exchange close flow

 

 

 

 

 

Adsense

 

 WiFi IoT Module

 

www.mxchip.com

 

 

 Bluetooth Module

www.feasycom.com

 

 

 5G/LTE/CAT-M1/NB-IoT

 

www.simcom.com

 

Viewed Page List