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

4.10.   Secure Channel Protocol

 

This section specifies the formal protocol definition for the Secure Channel Protocol. Secure Chan­ nel Protocol defines the control plane for secure channel communication and security.

 

4.10.1.  Secure Channel Protocol Messages

 

Secure Channel Protocol is composed of a collection of sub-protocols, including:

 

  • Message Counter Synchronization Protocol (MCSP)
  • Message Reliability Protocol (MRP)
  • Passcode Based Session Establishment (PASE)
  • Certificate Based Session Establishment (CASE)

 

The protocol opcodes for messages within the Secure Channel Protocol are grouped based on the underlying sub-protocol that uses the message type. Table 17, “Secure Channel Protocol Opcodes” lists the messages defined by Secure Channel Protocol.

Table 17. Secure Channel Protocol Opcodes

 

Protocol Opcode Protocol Command Name Description
Protocol ID = PROTOCOL_ID_SECURE_CHANNEL
0x00 MsgCounterSyncReq The Message Counter Synchronization Request message queries the current message counter from a peer to boot­ strap replay protection.
0x01 MsgCounterSyncRsp The Message Counter Synchronization Response message provides the current message counter from a peer to boot­ strap replay protection.
0x10 MRP Standalone Acknowl­ edgement This message is dedicated for the purpose of sending a stand-alone acknowledgement when there is no other data message available to piggyback an acknowledgement on top of.
0x20 PBKDFParamRequest The request for PBKDF parameters necessary to complete the PASE protocol.
0x21 PBKDFParamResponse The PBKDF parameters sent in response to PBKDF­ ParamRequest during the PASE protocol.
0x22 PASE Pake1 The first PAKE message of the PASE protocol.
0x23 PASE Pake2 The second PAKE message of the PASE protocol.
0x24 PASE Pake3 The third PAKE message of the PASE protocol.
0x30 CASE Sigma1 The first message of the CASE protocol.
0x31 CASE Sigma2 The second message of the CASE protocol.
0x32 CASE Sigma3 The third message of the CASE protocol.

 

 

Protocol Opcode Protocol Command Name Description
0x33 CASE Sigma2_Resume The second resumption message of the CASE protocol.
0x40 StatusReport The Status Report message encodes the result of an opera­ tion in the Secure Channel as well as other protocols.

 

4.10.1.1.  Session Establishment – Out of Resources

 

After a successful session establishment using CASE or PASE, a responder may not have enough resources to save all of the session context information. To free resources, a responder SHALL evict an existing session using the following procedure:

  1. Use the SessionTimestamp to determine the least-recently used session.
  2. Determine the session that was least-recently used then:
    1. Send a status report: StatusReport(GeneralCode: SUCCESS, ProtocolId: SECURE_CHANNEL, Pro­ tocolCode: CLOSE_SESSION) message to the peer node
    2. Remove all state associated with the session (see Section 4.12.2.1, “Secure Session Context”). The Node MAY save state necessary to perform Session Resumption, see Section 4.13.2.2.1, “Session Resumption State” for more
  3. Respond to the initiator with the appropriate session establishment message

 

4.10.1.2.  Status Report

 

The Status Report message is sent from protocol handlers to convey the status of an operation using a common format as defined in Appendix D, Status Report Messages. The StatusReport message is a part of the Secure Channel protocol, but embeds an additional context-specific ProtocolID field in its message-specific payload. In this way, the StatusReport can convey status for any protocol han­ dler.

 

4.10.1.3.  Secure Channel Status Report Messages

 

Status Reports specific to the Secure Channel are designated by embedding the PROTOCOL_ID_SE­ CURE_CHANNEL in the ProtocolId field of the StatusReport body. All Secure Channel Status Report Mes­ sages SHALL use the PROTOCOL_ID_SECURE_CHANNEL protocol id. For example, a failure to find a com­ mon root of trust may be written in the specification as follows: StatusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: NO_SHARED_TRUST_ROOTS).

There are several cases for which the secure channel layer may emit a status report:

 

  1. To indicate successful session establishment
  2. In response to errors during session establishment
  3. In response to errors after session establishment
  4. To indicate that a Node is terminating a session

 

For each of these cases, a Secure Channel Status Report message SHALL be sent with an appropriate

ProtocolCode as detailed below.

 

The following table describes the Secure Channel Status Report Protocol Specific codes. Each entry in the list details the appropriate General Code to be utilized with the message and whether it may be sent unencrypted. Secure Channel Status Report messages which are marked as encrypted below SHALL only be sent encrypted in a session established with CASE or PASE.

Table 18. Secure Channel Protocol Codes

 

Protocol Code Error General Code Encrypted Additional Data Description
0x0000 SESSION_ESTABLISH­ MENT_SUCCESS SUCCESS N N Indication that the last session establishment message was successfully processed.
0x0001 NO_SHARED_TRUST_­ ROOTS FAILURE N N Failure to find a common set of shared roots.
0x0002 INVALID_PARAMETER FAILURE N N Generic failure during session establishment.
0x0003 CLOSE_SESSION SUCCESS Y N Indication that the sender will close the current session. See Section 4.10.1.4, “CloseSession” for more details.
0x0004 BUSY BUSY N Y Indication that the sender can­ not currently fulfill the request. See Section 4.10.1.5, “Busy” for more details.

 

4.10.1.4.  CloseSession

 

A node may choose to close a session for a variety of reasons including, but not limited to, the fol­ lowing:

  1. The interaction between nodes is complete
  2. The node needs to free up resources for a new session
  3. Fabric configuration associated with the CASE session was removed with the RemoveFabric command invoked by an Administrator while the session was open

The CloseSession StatusReport SHALL only be sent encrypted within an exchange associated with a PASE or CASE session. The CloseSession StatusReport SHALL be sent within a new exchange and SHALL NOT set the R Flag.

If a Node has either sent or received a CloseSession StatusReport, that Node SHALL remove all state associated with the session (see Section 4.12.2.1, “Secure Session Context”). The Node MAY save state necessary to perform Session Resumption, see Section 4.13.2.2.1, “Session Resumption State”

for more details.

 

4.10.1.5.  Busy

 

When a receiver receives a request to start a new secure session via a Sigma1 or PBKDFParamRe­

 

quest message, the receiver MAY respond with the BUSY StatusReport when it is unable to fulfill the request. The BUSY StatusReport SHALL:

  1. Set the R Flag to 0
  2. Set the S Flag to 0
  3. Set the StatusReport ProtocolData to a 16-bit (two byte) little-endian value indicating the mini­ mum time in milliseconds to wait before retrying the original
  4. Set the Exchange ID to the Exchange ID present in the Sigma1 or PBKDFParamRequest message which triggered this

 

For example, a responder wishing to indicate they are unable to fulfill the request and that the ini­ tiator should wait 500 milliseconds before trying again would send StatusReport(GeneralCode: BUSY, ProtocolId: SECURE_CHANNEL, ProtocolCode: BUSY, ProtocolData: [0xF4, 0x01]).

The BUSY StatusReport SHALL NOT be sent in response to any message except for Sigma1 or PBKDFParamRequest.

An initiator receiving a BUSY StatusReport from a responder SHALL wait for at least a period of t milliseconds before retrying the request where t is the value obtained from the Busy StatusReport ProtocolData field.

If the initiator sends a new session establishment request after receiving a BUSY StatusReport, the request SHALL contain new values for all randomized parameters.

 

4.10.2.  Parameters and Constants

 

Table 19, “Glossary of constants” is a glossary of constants used in the secure channel protocol, along with a brief description and the default for each constant.

Table 19. Glossary of constants

 

Constant Name Description Value
MSG_COUNTER_WINDOW_SIZE Maximum number of previously processed mes­ sage counters to accept from a given Node and key. 32
MSG_COUNTER_SYNC_REQ_JIT­ TER Maximum amount of random delay before send­ ing a MsgCounterSyncReq when the synchroniza­ tion request is triggered by receipt of a multicast message. 500 millisec­ onds
MSG_COUNTER_SYNC_TIMEOUT The maximum amount of time (in milliseconds) which a Node SHALL wait for a MsgCounterSyn­ cRsp after sending a MsgCounterSyncReq. 400 millisec­ onds

 

 

 

4.11.   Message Reliability Protocol (MRP)

 

The Message Reliability Protocol (MRP) provides confirmation of delivery for messages that require reliability. The protocol is optimized for constrained devices that may not be able to receive a mes­

 

sage at the point it is due to be delivered to them. Reliable messaging MAY be enabled on an indi­ vidual message basis as required by the protocol design of the higher layer application. Reliability is achieved through time-bounded delivery confirmation, ensuring best effort delivery of critical messages over what may be an inherently lossy and unreliable communication medium.

Flow control mechanisms are not incorporated in MRP because it is intended to be used for short interactions with small numbers of messages in them.

 

4.11.1.  Reliable Messaging Header Fields

 

The following fields are defined in the Exchange Flags for use exclusively by MRP:

 

  • R Flag

 

Indicates a reliable message. This flag SHALL be set by the sender when a message being sent requires the receiver to send back an acknowledgment. To support unreliable messages, this flag bit MAY be clear, so that no acknowledgements are requested from the receiver.

  • A Flag

 

Indicates the message is acting as an acknowledgement. This flag MAY be set on any message. When set, the Acknowledged Message Counter field SHALL be present and valid. This flag SHALL always be set for MRP Standalone Acknowledgement messages.

  • Acknowledged Message Counter

 

This field SHALL be set to the Message Counter of the message that is being acknowledged.

 

4.11.2.  Reliable transfer

 

When the reliability bit is set, the reliable message is transmitted at most MRP_MAX_TRANSMIS­ SIONS times until an acknowledgement of receipt is received from the peer or a timeout.

 

4.11.2.1.  Retransmissions

 

Senders provide an automatic retransmission mechanism for reliable messages. In order for the receiver to receive a message reliably, the sender SHALL trigger the automatic retry mechanism after a period of mrpBackoffTime milliseconds without receiving an acknowledgement, where mrp­ BackoffTime is calculated according to the formula below. The sender SHALL retry up to a config­ ured maximum number of times (MRP_MAX_TRANSMISSIONS – 1) before giving up and notifying the application.

Messages sent to a Node can be lost for various reasons such as lossy network or insufficient buffer space at the receiver. In the case of sleepy end devices, which wake up infrequently to receive mes­ sages destined for them, a sender must be aware of the characteristics of the recipient to ensure it does not attempt to send at a rate beyond the recipient’s capability. Therefore, the sender SHALL choose retransmission timeouts based on the sleepy characteristics of the destination Node using Section 4.3.2, “Operational Discovery”.

At each sender, a retransmission timer is started each time a reliable message is transmitted. The

 

duration of the retransmission timer SHALL be calculated as follows:

 

“mrpBackoffTime” = i * “MRP_BACKOFF_BASE”^(max(0,n-“MRP_BACKOFF_THRESHOLD”)) * (1.0 + “random”(0,1) * “MRP_BACKOFF_JITTER”)

Where:

 

{:(“mrpBackoffTime”, =, “the resultant retransmission timeout for this transmission”),(n, =, “the number of send attempts before the current one for this message (0 if this is the initial transmission)”),(i, =, “the base retry interval for the Exchange (either IDLE or ACTIVE)”):}

 

For each unique Exchange, the sender SHALL wait for the acknowledgement message until the retransmission timer, mrpBackoffTime, expires. A sleepy sender SHOULD increase t to also account for its own sleepy interval required to receive the acknowledgment.

The base interval, i, SHALL be set according to the active state of the peer node as stored in the Ses­ sion Context of the session (either the Secure Session Context or the Unsecured Session Context depending on the Session Type). The backoff base interval SHALL be set to a value at least 10%

greater than the sleep interval of the destination:

  • If PeerActiveMode in the Session Context is true:
    • i = SLEEPY_ACTIVE_INTERVAL of the peer
  • Else the peer is in idle mode:
    • i = SLEEPY_IDLE_INTERVAL of the peer
  • i = MRP_BACKOFF_MARGIN * i

The MRP_BACKOFF_THRESHOLD parameter creates a two-phase scheme which begins with linear backoff to improve initial latency when congestion is not the cause of packet drops, and then transi­ tions to exponential backoff to provide convergence when the network is congested. If a positive acknowledgment is received before the retransmission timer expires, the retransmission timer is stopped. Otherwise, if the retransmission timer expires, the message is retransmitted and the timer started again.

The following table illustrates minimum, maximum, and cumulative retransmission times using default parameters.

Table 20. Example MRP Retransmission Times

 

Metric Transmission Time [ms]
Min Jitter 330 330 528 845 1352
Max Jitter 413 413 660 1056 1690
Min Total 330 660 1188 2033 3385
Max Total 413 825 1485 2541 4231

 

 

Metric Transmission Time [ms]
Transmission # 0 1 2 3 4

 

The sender SHOULD initiate Section 4.3.2, “Operational Discovery” in parallel with the first retry to re-resolve the address of the destination Node if the initial transmission fails after one expected round trip. The sender SHOULD use the latest MRP parameters for the destination that result from subsequent Operational Discovery.

 

4.11.2.2.  Acknowledgements

 

A receiver SHALL acknowledge a reliable message by either using a “piggybacked” acknowledg­ ment in the next message destined to the peer, or a standalone acknowledgment, or both.

The acknowledgement message SHALL set the Acknowledged Message Counter field to the value of the Message Counter of the reliable message to be acknowledged.

 

Piggybacking Acknowledgments on Responses

 

Acknowledgements MAY be conveyed at the same time (i.e. piggybacked) as data in a response mes­ sage. The receiver tries to optimize message transmission by deferring acknowledgments when a reliable message is received (see Section 4.11.5.2.2, “Standalone acknowledgement processing”) and piggybacking outstanding acknowledgments on messages that it needs to send back (see Section 4.11.5.1.1, “Piggyback acknowledgment processing” for more details).

 

Duplicate Message Detection

Since the reliable messaging protocol has a provision for the sender to retransmit messages, there is a significant chance that a duplicate message may arrive at the receiver. The receiver SHALL detect and mark duplicate messages that it receives using the standard authentication and replay protection mechanisms of the secure message layer (see Section 4.5.4, “Replay Prevention and Duplicate Message Detection”). The receiver SHALL send an acknowledgment message to the sender for each instance of an authenticated, reliable message, including duplicates. The reliability layer SHALL only propagate the first instance of a message to the next higher layer. Any message marked as a duplicate SHALL be dropped by the reliability layer.

 

4.11.3.  Peer Exchange Management

 

The Reliable Messaging Protocol operates within the scope of an Exchange between two Nodes. MRP SHALL support one pending acknowledgement and one pending retransmission per Exchange.

MRP control parameters, detailed in Table 21, “Glossary of parameters”, are computed outside of the Exchange communication itself; instead, they are valid for the duration of a secure session. The

SLEEPY_ACTIVE_INTERVAL and SLEEPY_IDLE_INTERVAL, used in computation of MRP control parameters,

are determined during Operational Discovery or Section 4.3.1, “Commissionable Node Discovery”.

Additionally, the initiator of a secure session MAY provide these parameters in the initial CASE Sig­ ma1 or PASE PBKDFParamRequest messages, and the responder MAY provide its parameters in the corresponding protocol messages CASE Sigma2 or PBKDFParamResponse.

 

4.11.4.  Transport Considerations

 

When the upper layer requests a reliable message over a UDP transport, the R Flag SHALL be set on that message indicating that MRP SHALL be used. Reliable messages sent over TCP or BTP SHALL utilize the underlying reliability mechanisms of those transports and SHOULD NOT set the R Flag.

 

4.11.5.  Reliable Message Processing

 

4.11.5.1.  Reliable Message Processing of Outgoing Messages

 

To prepare a given Protocol Message for transmission, the message SHALL be processed as follows:

 

  1. Proceed to Section 4.11.5.1.1, “Piggyback acknowledgment processing”.

 

Piggyback acknowledgment processing

 

  1. Determine if there is a matching pending acknowledgement in the acknowledgement table for the given message by checking all of the following conditions:
    1. If the Destination Node Id and Exchange Id of the given message and pending acknowledge­ ment are the same
    2. AND either
      1. the Session Id and underlying Session Credentials of the given message and pending acknowledgement are the same
      2. OR both the given message and pending acknowledgement are of Unsecured Session Type.
    3. If there is a matching pending acknowledgement, the A Flag SHALL be set on the outbound mes­ sage so it will serve as a piggybacked
      1. For such a piggybacked acknowledgement, the Acknowledgment Message Counter field SHALL be set to the message counter of the received message for which an acknowledge­ ment was
      2. If the message being prepared is not a standalone acknowledgement, remove the matching entry from the acknowledgement table.
      3. If the message being prepared is a standalone acknowledgement, set the StandaloneAckSent

field of the matching entry in the acknowledgement table to true.

 

Message retransmission processing

 

  1. If the outbound message is marked to be delivered reliably over a UDP transport, the R Flag SHALL be set on the given message to request an acknowledgement from the peer upon
    1. Any message flagged for reliable delivery (R Flag set) SHALL be stored in the retransmission table to track the message until it has been successfully acknowledged by the
  2. Perform Section 4.6.1, “Message Transmission” processing step on the message to send the mes­ sage to the peer:
    1. The same Session ID, Destination Node ID, Security Flags, and transport as were used for the initial message transmission SHALL be

 

  1. If the transport interface returns an error on the send attempt, the error is assessed to deter­ mine whether the message can be
    1. If the error is fatal, the application is notified and the message removed from the retrans­ mission table.
    2. If there is no error, or a non-fatal error such as no memory, the message is resent
      1. Update the retransmission table to reflect the send
      2. Start a retransmission timer to track the maximum time to wait before attempting another
  • For each retry, the retransmission table is updated to track the number of retries until the maximum number is attempted, at which point the message is evicted from the retransmission table.

 

Send flow state diagram

 

The MRP send flow described above is depicted in the control flow diagram Figure 12, “MRP send flow”.

 

 

Figure 12. MRP send flow

 

4.11.5.2.  Reliable Message Processing of Incoming Messages

 

A message received from Section 4.6.2, “Message Reception” for reliability processing SHALL be processed as follows:

  1. Verify the message has a legal combination of reliability flags:
    1. If the R Flag is set:
      1. If Group Session Type AND C Flag = 0, drop the
    2. If the A Flag is set:
      1. If Group Session Type AND C Flag = 0, drop the
    3. Proceed to Section 4.9.5.1, “Exchange Message Matching”.
    4. Proceed to Section 4.11.5.2.1, “Received acknowledgement processing”.

 

Received acknowledgement processing

 

  1. If the A Flag is set:
    1. Query the retransmission table for the Acknowledgement Message Counter contained in the received
      1. If there is a match:
        1. Remove the entry from the retransmission table.
        2. Stop the retransmission timer for that
      2. If there is no match, it indicates that this is either a duplicate acknowledgment or the Exchange context does not
    2. Proceed to Section 4.11.5.2.2, “Standalone acknowledgement processing”.

 

Standalone acknowledgement processing

 

  1. If the R Flag is set, the received message is requesting an acknowledgement be sent back:
    1. If the message is marked as a duplicate:
      1. Immediately send a standalone acknowledgment.
      2. If the Exchange is marked as an ephemeral exchange the Exchange SHALL be
  • Drop the
  1. Otherwise, instead of sending an acknowledgement immediately upon the receipt of a reli­ able message from a peer, the receiver SHOULD wait for a time no longer than MRP_STAND­ ALONE_ACK_TIMEOUT before sending a standalone acknowledgment:
    1. Add the message counter of the received message to the acknowledgement table to signal that an outbound acknowledgement is pending. There can be only one outstanding acknowledgement at a time on a single Exchange. If a pending acknowledgement

already exists for the Exchange, and it has StandaloneAckSent set to false, a standalone

acknowledgment SHALL be sent immediately for that pending message counter, and the

acknowledgement table entry SHALL be replaced for the new message.

  1. Start the acknowledgement timer for the

 

  1. If the timer triggers before being cancelled, a standalone acknowledgment SHALL be

sent to the source of the message. Sending this standalone acknowledgment SHALL NOT remove the acknowledgement table entry and SHALL set the StandaloneAckSent field of the entry to true.

  1. The received message is then delivered to the next processing step of Section 4.6.2, “Message Reception”.

 

Receive flow state diagram

 

The MRP receive flow described above is depicted in Figure Figure 13, “MRP receive flow”.

 
   

Figure 13. MRP receive flow

 

4.11.6.  Reliable Message State

 

4.11.6.1.  Retransmission Table

 

For retransmissions, the sender maintains a retransmission table of context records containing information on all reliable messages sent that have acknowledgments still pending. Each such reli­ able message context record includes the following fields:

  • Reference to Exchange Context
  • Message Counter
  • Reference to fully formed, encoded and encrypted message buffer
  • Send count
  • Retransmission timeout counter

 

Each time a message that requires acknowledgment is sent, a new retransmission context record is inserted into the retransmission table or an existing record is updated to increment its send count. The message is sent a configurable maximum number of times (MRP_MAX_TRANSMISSIONS) and, if still undelivered, the application is notified of the failure.

 

4.11.6.2.  Acknowledgement Table

 

The receiver maintains an acknowledgement table of context records containing information on each reliable message for which an acknowledgment SHALL be sent. Each such reliable message context record includes the following fields:

  • Reference to Exchange Context
  • Message Counter
  • A boolean, StandaloneAckSent, indicating whether a standalone acknowledgement has been sent for this message counter. Initially

 

An entry SHALL remain in the table until one of the following things happens:

 

  1. The exchange associated with the entry is closed. See Section 4.9.5.3, “Closing an Exchange”.
  2. The exchange associated with the entry has switched to track a pending acknowledgement for a new message counter See Section 4.11.5.2.2, “Standalone acknowledgement processing”.
  3. A message that is not a standalone acknowledgement is sent which serves as an acknowledge­ ment for the See Section 4.11.5.1.1, “Piggyback acknowledgment processing”.

 

 

4.11.7.  MRP Messages

 

4.11.7.1.  MRP Standalone Acknowledgement

 

The MRP Standalone Acknowledgement message SHALL be formed as follows:

 

  • The application payload SHALL be
  • The A Flag SHALL be set to 1.

 

  • The Acknowledged Message Counter SHALL be included in the
  • The Protocol ID SHALL be set to PROTOCOL_ID_SECURE_CHANNEL.
  • The Protocol Opcode SHALL be set to MRP Standalone Acknowledgement.

 

The rules for when to send this message are detailed in Section 4.11.5.2.2, “Standalone acknowl­ edgement processing”.

 

4.11.8.  Parameters and Constants

 

Table 21, “Glossary of parameters” is a glossary of parameters used in this chapter with a brief description for each parameter. A Node SHALL use the provided default value for each parameter unless the message recipient Node advertises an alternate value for the parameter via Operational Discovery.

Table 21. Glossary of parameters

 

Parameter Name Description Default Value
MRP_MAX_TRANSMISSIONS The maximum number of transmission attempts for a given reliable message. The sender MAY choose this value as it sees fit. 5
MRP_BACKOFF_BASE The base number for the exponential back­ off equation. 1.6
MRP_BACKOFF_JITTER The scaler for random jitter in the backoff equation. 0.25
MRP_BACKOFF_MARGIN The scaler margin increase to backoff over the peer sleepy interval. 1.1
MRP_BACKOFF_THRESHOLD The number of retransmissions before transitioning from linear to exponential backoff. 1
MRP_STANDALONE_ACK_TIMEOUT Amount of time to wait for an opportunity to piggyback an acknowledgement on an outbound message before falling back to sending a standalone acknowledgement. 200 millisec­ onds

 

 

 

4.12.   Unicast Communication

 

This section specifies the semantics of establishing a unicast session and the lifecycle of a unicast session.

Unicast sessions exist in one of two phases:

 

  1. Session Establishment Phase: A series of well-defined unencrypted messages that aim to estab­ lish a shared
  2. Application Data Phase: A series of ad-hoc encrypted messages exchanging interaction model protocol actions, application data,

 

4.12.1.  Session Establishment Phase

 

Session establishment uses either the CASE or PASE protocol.

 

CASE SHALL be used as a session establishment mechanism for all sessions except:

 

  1. Communication for the purpose of commissioning when NOC has not yet been installed

 

PASE SHALL only be used for session establishment mechanism during device commissioning. PASE SHALL NOT be used as a session establishment mechanism for any other session. BTP MAY be used as the transport for device commissioning. BTP SHALL NOT be used as a transport for opera­ tional purposes.

Unless otherwise specified, the CASE, PASE, User-Directed Commissioning protocol, and Secure Channel Status Report messages SHALL be the only allowed unencrypted messages.

This phase aims to:

 

  1. Authenticate peers (CASE-based sessions only).
  2. Derive shared secrets to encrypt subsequent session
  3. Choose session identifiers to identify the subsequent

 

4.12.1.1.  Unsecured Session Context

 

The following session context data SHALL be utilized to associate messages to a particular peer and recover context during unencrypted sessions:

  1. Session Role: Records whether the node is the session initiator or
  2. Ephemeral Initiator Node ID: Randomly selected for each session by the initiator from the Oper­ ational Node ID range and enclosed by initiator as Source Node ID and responder as Destination Node ID.
    • Initiators SHALL select a new random ephemeral node ID for each unsecured session, and SHALL select an ID that does not conflict with any ephemeral node IDs for any other ongo­ ing unsecured sessions opened by the
  3. Message Reception State: Provides tracking for the Unencrypted Message Counter of the remote peer.

Matching and responder creation of Unsecured Session Contexts SHALL be as follows:

  1. Given an incoming unencrypted message
    1. Locate any Unsecured Session Context with matching Ephemeral Initiator Node ID
      1. If any is located, the incoming message SHALL be assumed to be associated with this

Unsecured Session Context

  1. Else if the message carries a Source Node ID
    1. Create a new Unsecured Session Context
    2. Set Session Role to responder

 

  • Record the incoming message’s Source Node ID as Ephemeral Initiator Node ID
  1. Else discard the message

Initiator creation of Unsecured Session Contexts SHALL be as follows:

  1. Given the first outgoing message of an unencrypted exchange
    1. Create a new Unsecured Session Context
    2. Set Session Role to initiator
    3. Randomly select a node ID from the Operational Node ID range that does not collide with any ephemeral node IDs for any other ongoing unsecured sessions opened by the initiator

and record this as Ephemeral Initiator Node ID

 

4.12.1.2.  Session Establishment over IP

 

When establishing a session over IP, the initiator SHALL use TCP when both of the following are true:

  1. The initiator supports TCP
  2. The responder supports TCP as indicated by the T flag

If one or both nodes do not support TCP, the initiator SHALL use MRP to establish the session.

 

The choice of transport used during session establishment SHALL be used for the transport of mes­ sages of the established session.

 

4.12.1.3.  Shared Secrets

 

Both CASE and PASE produce two shared keys: I2RKey and R2IKey. These keys will be saved to the session’s context and used to encrypt and decrypt messages during the Session Data Phase.

 

Nodes that support the CASE session resumption SHALL also save to the session’s context the

SharedSecret computed during the CASE protocol execution.

 

4.12.1.4.  Choosing Secure Unicast Session Identifiers

 

Both CASE and PASE allow each participant the ability to choose a unicast session identifier for the subsequent encrypted session. The session identifier SHALL be used to look up the relevant encryp­ tion keys and any other metadata for a particular session.

Messages using a unicast session identifier SHALL set the Session Type field to 0. Each peer SHALL specify a Session Identifier unique in reference to their own active sessions. There SHALL NOT be overlap between the Session ID values allocated for PASE and CASE sessions, as the Session Identi­ fier space is shared across both session establishment methods.

For example, if the initiator has two active sessions with session identifiers 0x0001 and 0x0002, it could choose any non-zero session identifier besides 0x0001 and 0x0002.

If there are no available session identifiers (i.e. the participant has 65,535 open sessions), the Node SHALL terminate an existing session to free a session identifier.

 

4.12.2.  Application Data Phase

 

When the last CASE or PASE protocol message is sent or received and successfully processed, ses­ sion establishment has completed.

 

4.12.2.1.  Secure Session Context

 

During the Application Data Phase, the following conceptual session context data SHALL be utilized to securely process subsequent messages:

  1. Session Type: Records whether the session was established using CASE or PASE.
  2. Session Role: Records whether the node is the session initiator or
  3. Local Session Identifier: Individually selected by each participant in secure unicast communi­ cation during session establishment and used as a unique identifier to recover encryption keys, authenticate incoming messages and associate them to existing
    • On a given Node, this is the identifier that SHALL be used to map from an incoming mes­ sage’s Session ID field to the session context
  4. Peer Session Identifier: Assigned by the peer during session
    • On a given Node, this is the identifier that SHALL be used in the Session ID field of every out­ going message associated with the session, so that it can be interpreted as the Local Session Identifier by the remote peer.
  5. I2RKey: Encrypts data in messages sent from the initiator of session establishment to the respon­ der.
  6. R2IKey: Encrypts data in messages sent from the session establishment responder to the initia­ tor.
  7. SharedSecret: Computed during the CASE protocol execution and re-used when CASE session resumption is
  8. Local Message Counter: Secure Session Message Counter for outbound
    • At successful session establishment, the Local Message Counter SHALL be initialized per Sec­ tion 4.5.1.1, “Message Counter Initialization”.
  9. Message Reception State: Provides tracking for the Secure Session Message Counter of the remote
  10. Local Fabric Index: Records the local Index for the session’s Fabric, which MAY be used to look up Fabric metadata related to the Fabric for which this session context
    • This field SHALL contain the “no Fabric” value of 0 when the SessionType is PASE and success­ ful invocation of the AddNOC command has not yet occurred during
  11. Peer Node ID: Records the authenticated node ID of the remote peer, when
    • This field SHALL contain the “Unspecified Node ID” value of 0 when the SessionType is PASE.
  12. Resumption ID: The ID used when resuming a session between the local and remote
  13. SessionTimestamp: A timestamp indicating the time at which the last message was sent or received. This timestamp SHALL be initialized with the time the session was created. See Sec­ tion 4.10.1.1, “Session Establishment – Out of Resources” for more

 

  1. ActiveTimestamp: A timestamp indicating the time at which the last message was received. This timestamp SHALL be initialized with the time the session was
  2. The following sleepy parameters (see Table 5, “Glossary of parameters”):
  1. SLEEPY_IDLE_INTERVAL
  2. SLEEPY_ACTIVE_INTERVAL
  3. PeerActiveMode: A boolean that tracks whether the peer node is in Active or Idle mode as defined in Section 2.9, “Sleepy End Device (SED)”. PeerActiveMode is set as follows:

 

PeerActiveMode = (now() – ActiveTimestamp) < “SLEEPY_ACTIVE_THRESHOLD”

Note that the Local Fabric Index and Peer Fabric Index reported in the NOC Response MAY differ in value, while still referring to the same Fabric, since for a given complete Fabric Reference, the short Fabric Index allocated during commissioning of the respective Nodes on the same Fabric MAY be

different. This possible difference is due to the order in which the Fabric in question was joined in the lifecycle of the respective Nodes. See the section on AddNOC command behavior for details on Fabric Index allocation behavior over time.

There SHALL also be reservation of storage to support CASE Authenticated Tag (CAT) fields. The CAT fields are 32-bit values that MAY have been present in RDN case-authenticated-tag of the remote peer’s operational certificate, during CASE.

The CAT fields are used to cache Operational Certificate data so that it can be used by the ACL processing logic to support CASE Authenticated Tags.

 

Since these fields MAY be omitted from NOCs, they MAY be marked as absent in the context, such that they are not taken into account when missing. When present, they SHALL be stored. Maximum

up to 3 CAT fields SHALL be supported.

Their value is unused in PASE session contexts.

 

 

 

4.13.   Session Establishment

 

4.13.1.  Passcode-Authenticated Session Establishment (PASE)

 

This section describes session establishment using a shared passcode together with an augmented Password-Authenticated Key Exchange (PAKE), in which only one party knows the passcode before­ hand, to generate shared keys. This protocol is only used when commissioning a Node (i.e. the Com­ missionee).

 

4.13.1.1.  Protocol Overview

 

The Passcode-Authenticated Session Establishment (PASE) protocol aims to establish the first ses­ sion between a Commissioner and a Commissionee using a known passcode provided out-of-band. The pairing is performed using Section 3.10, “Password-Authenticated Key Exchange (PAKE)” and relies on a Password-Based Key Derivation Function (PBKDF) where the passcode is used as pass­ word.

 

This session establishment protocol provides a means to:

 

  1. Communicate PBKDF
  2. Derive PAKE bidirectional
 
   

Figure 14. Overview of the PASE Protocol

 

The Commissioner is the Initiator and the Commissionee is the Responder.

 

It is assumed that the initiator has somehow obtained the passcode and that the responder has the relevant Crypto_PAKEValues_Responder corresponding to the passcode before starting a PASE session establishment protocol.

 

4.13.1.2.  Protocol Details

 

Message format

 

All PASE messages SHALL be structured as specified in Section 4.4, “Message Frame Format”. All PASE messages are unsecured at the message layer:

  • The Session ID field SHALL be set to 0.
  • The Session Type bits of the Security Flags SHALL be set to 0.
  • The S Flag and DSIZ fields of the Message Flags SHALL be set to 0.

For each PASE message, the application payload is the TLV encoding of the message structure as defined below:

Table 22. PASE Messages

 

Message Name Payload TLV Encoding
PBKDFParamRequest pbkdfparamreq-struct
PBKDFParamResponse pbkdfparamresp-struct
Pake1 pake-1-struct
Pake2 pake-2-struct

 

 

Message Name Payload TLV Encoding
Pake3 pake-3-struct
PakeFinished N/A (encoded via StatusReport)

 

The other fields of the Message format are not specific to the PASE messages.

 

For all TLV-encoded PASE messages, any context-specific tags not listed in the associated TLV schemas SHALL be reserved for future use, and SHALL be silently ignored if seen by a recipient which cannot understand them.

 

Message Exchange

The PBKDFParamRequest, PBKDFParamResponse, Pake1, Pake2, Pake3, and PakeFinished of a distinct session establishment are part of the same message exchange. The initiator and responder SHALL NOT send encrypted application data in the newly established session until PakeFinished is received by the initiator within the unencrypted session used for establishment.

Each message SHALL use PROTOCOL_ID_SECURE_CHANNEL as Protocol ID and the corresponding Protocol Opcode as defined in Table 17, “Secure Channel Protocol Opcodes”.

 

The flags of the Exchange Flags of the Protocol Header are defined as follows per PASE message:

 

Message I Flag
PBKDFParamRequest 1
PBKDFParamResponse 0
Pake1 1
Pake2 0
Pake3 1

All PASE messages SHALL be sent reliably. This may be implicit (e.g. TCP) or explicit (e.g. MRP reli­ able messaging) in the underlying transport.

The other fields of the Protocol Header are not specific to the PASE messages.

 

PBKDFParamRequest

 

This message serves to request the PBKDF parameters, with a payload that follows this TLV schema:

 

pbkdfparamreq-struct => STRUCTURE [ tag-order ]

{

initiatorRandom            [1] : OCTET STRING [ length 32 ], initiatorSessionId [2] : UNSIGNED INTEGER [ range 16-bits ], passcodeId                     [3] : UNSIGNED INTEGER [ length 16-bits ], hasPBKDFParameters [4] : BOOLEAN,

initiatorSEDParams [5, optional] : sed-parameter-struct

}

 

  1. The initiator SHALL generate a random number InitiatorRandom = Crypto_DRBG(len = 32 * 8).
  2. The initiator SHALL generate a session identifier (InitiatorSessionId) for subsequent identifica­ tion of this session. The InitiatorSessionId field SHALL NOT overlap with any other existing PASE or CASE session identifier in use by the responder. See Section 4.12.1.4, “Choosing Secure Unicast Session Identifiers” for more details. The initiator SHALL set the Local Session Identi­ fier in the Session Context to the value InitiatorSessionId.
  3. The initiator SHALL choose a passcode identifier (PasscodeId) corresponding to a particular PAKE passcode verifier installed on the responder. A value of 0 for the passcodeID SHALL corre­ spond to the PAKE passcode verifier for the currently-open commissioning window, if Non-

zero values are reserved for future use. For example, for initial commissioning, the verifier would be the built-in verifier matching the Onboarding Payload’s passcode or, equivalently, the multi-fabric Basic Commissioning Method passcode if that method is supported. For the multi- fabric Enhanced Commissioning Method, the verifier would match the verifier provided through the OpenCommissioningWindow command.

  1. The initiator SHALL indicate whether the PBKDF parameters (salt and iterations) are known for the particular passcodeId (for example from the QR code) by setting HasPBKDFParameters. If HasP­ BKDFParameters is set to True, the responder SHALL NOT return the PBKDF parameters. If HasP­ BKDFParameters is set to False, the responder SHALL return the PBKDF parameters.
  2. The initiator SHALL send a message with the appropriate Protocol Id and Protocol Opcode from Table 17, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded pbkdf­

paramreq-struct PBKDFParamRequest with an anonymous tag for the outermost struct.

 
   

 

PBKDFParamResponse

 

pbkdfparamresp-struct => STRUCTURE [ tag-order ]

{

initiatorRandom            [1] : OCTET STRING [ length 32 ], responderRandom        [2] : OCTET STRING [ length 32 ], responderSessionId [3] : UNSIGNED INTEGER [ range 16-bits ], pbkdf_parameters     [4] : Crypto_PBKDFParameterSet, responderSEDParams [5, optional] : sed-parameter-struct

}

On receipt of PBKDFParamRequest, the responder SHALL:

  1. Verify passcodeID is set to 0. If verification fails, the responder SHALL send a status report: Sta­ tusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAME­

 

TER) and perform no further processing.

  1. Generate a random number ResponderRandom = Crypto_DRBG(len = 32 * 8).
  2. Generate a session identifier (ResponderSessionId) for subsequent identification of this session. The ResponderSessionId field SHALL NOT overlap with any other existing PASE or CASE session identifier in use by the responder. See Section 4.12.1.4, “Choosing Secure Unicast Session Identi­ fiers” for more details. The responder SHALL set the Local Session Identifier in the Session Context to the value ResponderSessionId.
  3. Set the Peer Session Identifier in the Session Context to the value initia­ torSessionId.
  4. Construct the appropriate Crypto_PBKDFParameterSet (PBKDFParameters). If PBKDFParamRe­ hasPBKDFParameters is True the responder SHALL NOT include the PBKDF parameters (i.e. salt and iteration count) in the Crypto_PBKDFParameterSet. If Msg1.hasPBKDFParameters is False the responder SHALL include the PBKDF parameters (i.e. salt and iteration count) in the Crypto_P­ BKDFParameterSet.
  5. Send a message with the appropriate Protocol Id and Protocol Opcode from Table 17, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded pbkdfparamresp-struct PBKDF­ ParamResponse with an anonymous tag for the outermost struct.
 
   

 

Pake1

 

pake-1-struct => STRUCTURE [ tag-order ]

{

pA [1] : OCTET STRING [ length CRYPTO_PUBLIC_KEY_SIZE_BYTES ],

}

On receipt of PBKDFParamResponse, the initiator SHALL:

  1. Set the Peer Session Identifier in the Session Context to the value respon­ derSessionId.
  2. Generate the Crypto_PAKEValues_Initiator according to the pbkdf_parameters
  3. Using Crypto_PAKEValues_Initiator, generate pA := Crypto_pA(Crypto_PAKEValues_Initiator)
  4. Send a message with the appropriate Protocol Id and Protocol Opcode from Table 17, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded pake-1-struct Pake1 with an anonymous tag for the outermost

 

 

 

Pake2

 

pake-2-struct => STRUCTURE [ tag-order ]

{

pB [1] : OCTET STRING [ length CRYPTO_PUBLIC_KEY_SIZE_BYTES ], cB [2] : OCTET STRING [ length CRYPTO_HASH_LEN_BYTES],

}

On receipt of Pake1, the responder SHALL:

  1. Compute pB := Crypto_pB(Crypto_PAKEValues_Responder) using the passcode verifier indicated in

PBKDFParamRequest

  1. Compute TT := Crypto_Transcript(PBKDFParamRequest, PBKDFParamResponse, Pake1.pA, pB)
  2. Compute (cA, cB, Ke) := Crypto_P2(TT, Pake1.pA, pB)
  3. Send a message with the appropriate Protocol Id and Protocol Opcode from Table 17, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded pake-2-struct Pake2 with an anonymous tag for the outermost
 
   

 

Pake3

 

pake-3-struct => STRUCTURE [ tag-order ]

{

cA [1] : OCTET STRING [length CRYPTO_HASH_LEN_BYTES],

}

On receipt of Pake2, the initiator SHALL:

  1. Compute TT := Crypto_Transcript(PBKDFParamRequest, PBKDFParamResponse, Pake1.pA, pB)
  2. Compute (cA, cB, Ke) := Crypto_P2(TT, Pake1.pA, Pake2.pB)
  3. Verify cB against cB. If verification fails, the initiator SHALL send a status report: Status­ Report(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform no further processing.

 

  1. Send a message with the appropriate Protocol Id and Protocol Opcode from Table 17, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded pake-3-struct Pake3 with an anonymous tag for the outermost
 
   

 

  1. The initiator SHALL NOT send any encrypted application data until it receives PakeFinished

from the responder.

On reception of Pake3, the responder SHALL:

  1. Verify cA against cA. If verification fails, the responder SHALL send a status report: Sta­ tusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAME­ TER) and perform no further processing.
  2. The responder SHALL set SessionTimestamp to a timestamp from a clock which would allow for the eventual determination of the last session use relative to other
  3. The responder SHALL encode and send PakeFinished.

 

PakeFinished

 

To indicate the successful completion of the protocol, the responder SHALL send a status report: StatusReport(GeneralCode: SUCCESS, ProtocolId: SECURE_CHANNEL, ProtocolCode: SESSION_ESTABLISH­ MENT_SUCCESS).

The initiator SHALL set SessionTimestamp to a timestamp from a clock which would allow for the eventual determination of the last session use relative to other sessions.

 

Session Encryption Keys

After verification of Pake3, each party can compute their sending and receiving session keys as described below:

 

byte SEKeys_Info[] = /* “SessionKeys” */

{0x53, 0x65, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x4b, 0x65, 0x79, 0x73}

 

I2RKey || R2IKey || AttestationChallenge =

Crypto_KDF (

inputKey = Ke, salt = [],

info = SEKeys_Info,

len = 3 * CRYPTO_SYMMETRIC_KEY_LENGTH_BITS

)

 

  1. Each key is exactly CRYPTO_SYMMETRIC_KEY_LENGTH_BITS
  2. The initiator SHALL use I2RKey to encrypt and integrity protect messages and the `R2IKey’ to decrypt and verify
  3. The responder SHALL use R2IKey to encrypt and integrity protect messages and the `I2RKey’ to decrypt and verify
  4. The AttestationChallenge SHALL only be used as a challenge during device attestation. See Sec­ tion 6.2.3, “Device Attestation Procedure” for more

 

Upon initial installation of the new PASE Session Keys:

 

  1. The Node SHALL initialize its Local Message Counter in the Session Context per Section 4.5.1.1, “Message Counter Initialization”.
  2. The Node SHALL initialize the Message Reception State in the Session Context` and set the syn­ chronized max_message_counter of the peer to 0.

where || indicates message concatenation and [] a zero-length array.

 

4.13.2.  Certificate Authenticated Session Establishment (CASE)

 

This section describes a certificate-authenticated session establishment (CASE) protocol using Node Operational credentials. This session establishment mechanism provides an authenticated key exchange between exactly two peers while maintaining privacy of each peer. A resumption mecha­ nism allows bootstrapping a new session from a previous one, dramatically reducing the computa­ tion required as well as reducing the number of messages exchanged.

 

4.13.2.1.  Protocol Overview

 

This session establishment protocol provides a means to:

 

  1. Mutually authenticate both peer Nodes
  2. Generate cryptographic keys to secure subsequent communication within a session
  3. Exchange operational parameters for the session, such as Session Identifier and MRP parame­ ters

The cryptographic protocol mirrors the [SIGMA] protocol and uses the Identity Protection Key (IPK) to provide better identity protection. Briefly, the protocol will:

  1. Exchange ephemeral elliptic curve public keys (initiatorEphPubKey and Sigma2.respon­ derEphPubKey) to generate a shared secret
  2. Exchange certificates to prove identities (encrypted2.responderNOC and Sigma3.encrypt­ ed3.initiatorNOC)
  3. Prove possession of the NOC private key by signing the ephemeral keys and NOC (sigma-2-tbs­

data and sigma-3-tbsdata)

The basic protocol can be achieved within 2 round trips as shown below:

 

 

 

Figure 15. Basic Session Establishment

 

4.13.2.2.  Session Resumption

 

The protocol also provides a means to quickly resume a session using a previously established ses­ sion. Resumption does not require expensive signature creation and verification which signifi­ cantly reduces the computation time. Because of this, resumption is favoured for low-powered devices when applicable. Session resumption SHOULD be used by initiators when the necessary state is known to the initiator.

The nomenclature Sigma1 with Resumption in the following subsections implies a Sigma1 message with both the optional resumptionID and initiatorResumeMIC fields populated in sigma-1-struct.

 
   

Figure 16. Session Resumption

 

In the case where a Responder is not able to resume a session as requested by a Sigma1 with Resump­ tion, the information included in the Sigma1 with Resumption message SHALL be processed as a Sig­ ma1 message without any resumption fields to construct a Sigma2 message and continue the stan­

dard session establishment protocol without resumption.

 

To make the resumption succeed, both the Initiator and the Responder SHALL have remembered the SharedSecret they have computed during the previous execution of the CASE session establish­ ment. It SHALL be that SharedSecret that is used to compute the resumption ID.

 

Session Resumption State

 

To perform session resumption, the following state from the previous session context must be known to the initiator and responder:

  1. SharedSecret

 

  1. Local Fabric Index
  2. Peer Node ID
  3. Peer CASE Authenticated Tags
  4. ResumptionID

 

4.13.2.3.  Protocol Details

 

Message format

 

All CASE messages SHALL be structured as specified in Section 4.4, “Message Frame Format”. All CASE messages are unsecured at the message layer:

  • The Session ID field SHALL be set to 0.
  • The Session Type bits of the Security Flags SHALL be set to 0.
  • The S Flag and DSIZ fields of the Message Flags SHALL be set to 0.

For each CASE message, the application payload is the TLV encoding of the message structure as defined below:

Table 23. CASE Messages

 

Message Name Payload TLV Encoding
Sigma1 sigma-1-struct
Sigma2 sigma-2-struct,
Sigma3 sigma-3-struct,
Sigma2_Resume sigma-2-resume-struct,
SigmaFinished N/A (encoded via StatusReport)

 

The other fields of the Message format are not specific to the CASE messages.

 

Message Exchange

 

The Sigma1, Sigma2, Sigma3, and SigmaFinished of a distinct session establishment are part of the same message exchange. The Sigma1 with resumption, Sigma2_Resume and SigmaFinished of a distinct ses­ sion resumption are part of the same message exchange. The Sigma1 with resumption, Sigma2, Sigma3 and SigmaFinished of a distinct session resumption that failed to perform the resumption are part of

the same message exchange.

Each message SHALL use PROTOCOL_ID_SECURE_CHANNEL as Protocol ID and the corresponding Protocol Opcode as defined in Table 17, “Secure Channel Protocol Opcodes”.

 

The Exchange Flags of the Protocol Header are defined as follows per CASE message:

 

Message I Flag
CASE Sigma1 1

 

 

Message I Flag
CASE Sigma2 0
CASE Sigma3 1
CASE Sigma2_Resume 0

 

For the SigmaFinished message the value of the I Flag is set depending on whether the status mes­ sage is sent by the Initiator or the Responder.

 

All CASE messages SHALL be sent reliably. This may be implicit (e.g. TCP) or explicit (e.g. MRP reli­ able messaging) in the underlying transport.

The other fields of the Exchange format are not specific to the CASE messages.

 

Generate and Send Sigma1

The initiator encodes and sends a Sigma1 message, with a payload that follows this TLV schema:

 

sigma-1-struct => STRUCTURE [ tag-order ]

{

initiatorRandom            [1] : OCTET STRING [ length 32 ], initiatorSessionId [2] : UNSIGNED INTEGER [ range 16-bits ], destinationId                  [3] : destination-identifier, initiatorEphPubKey [4] : ec-pub-key,

initiatorSEDParams [5, optional] : sed-parameter-struct, resumptionID                                          [6, optional] : OCTET STRING [ length 16 ], initiatorResumeMIC [7, optional] : OCTET STRING [ length CRYPTO_AEAD_MIC_LENGTH_BYTES ]

}

  1. The initiator SHALL generate a random number InitiatorRandom = Crypto_DRBG(len = 32 * 8).
  2. The initiator SHALL generate a session identifier (InitiatorSessionId) for subsequent identifica­ tion of this session. The InitiatorSessionId field SHALL NOT overlap with any other existing PASE or CASE session identifier in use by the See Section 4.12.1.4, “Choosing Secure

Unicast Session Identifiers” for more details.

  1. The initiator SHALL generate a destination identifier (DestinationId) according to Destination Identifier to enable the responder to properly select a mutual Fabric and trusted root for the secure
  2. The initiator SHALL generate an ephemeral key pair InitiatorEphKeyPair = Crypto_GenerateKey­ pair().
  3. The initiator MAY encode any relevant MRP parameters.
  4. Any context-specific tags not listed in the above TLV schemas SHALL be reserved for future use, and SHALL be silently ignored if seen by a responder which cannot understand
  5. If the initiator is resuming a session from a previous execution of the CASE with the same peer, the initiator SHALL:

 

  1. Note the ResumptionID of the previous session.
  2. Generate the S1RK key.
  3. Generate the initiatorResumeMIC using the SharedSecret from the previous session:
 
   

 

  1. The initiator SHALL send a message with Secure Channel Protocol ID and Sigma1 Protocol Opcode from Table 17, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded Sigma1 Msg1 with an anonymous tag for the outermost struct.
 
   

 

Validate Sigma1

On receipt of Msg1, the responder SHALL perform the following:

  1. If Msg1 contains either a resumptionID or an initiatorResumeMIC field but not both, the responder SHALL send a status report: StatusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform no further processing.
  2. Set the Peer Session Identifier in the Session Context to the value initiatorSessionId.
  3. If Msg1 contains both the resumptionID and initiatorResumeMIC fields, the responder SHALL search for an existing session that has a Resumption ID equal to the incoming resumptionID. If a single such session exists, the responder SHALL follow the steps in Section 4.13.2.3.10, “Validate

Sigma1 with Resumption” rather than continue the steps outlined in Section 4.13.2.3.5, “Validate

 

Sigma1 Destination ID”.

  1. If Msg1 does not contain a resumptionID and initiatorResumeMIC field, the responder SHALL con­ tinue the steps in Section 4.13.2.3.5, “Validate Sigma1 Destination ID”.

 

Validate Sigma1 Destination ID

  1. The responder SHALL validate the incoming destinationId:
    1. The responder SHALL traverse all its installed Node Operational Certificates (NOC), gather­

ing the associated trusted roots’ public keys from the associated chains and SHALL generate a candidateDestinationId based on the procedure in Section 4.13.2.4.1, “Destination Identi­ fier” for that tuple of <Root Public Key, Fabric ID, Node ID>.

  1. The responder SHALL verify that the incoming destinationId matches one of the candidat­ eDestinationId generated above. Upon such a match, the associated trusted root, Fabric ID, Node ID and IPK SHALL be recorded for subsequent
  2. Note that at the initiator, only the current Epoch Key for the IPK will have been used. At the receiver, several IPK Epoch Keys may be installed, requiring several candidateDestinationId to be computed, one per available IPK Operational Key, per
  1. If there is no candidateDestinationId matching the incoming destinationId, the responder SHALL send a status report: StatusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: NO_SHARED_TRUST_ROOTS) and perform no further processing.
  2. Otherwise, if a match was found for the destinationId, the matched NOC, ICAC (if present), and associated trusted root SHALL be used for selection of the responderNOC and responderICAC in the steps for Sigma2.

 

Generate and Send Sigma2

If validation is successful, the responder encodes and sends a Sigma2 message.

 

sigma-2-tbsdata => STRUCTURE [ tag-order ]

{

responderNOC               [1] : OCTET STRING, responderICAC [2, optional] : OCTET STRING, responderEphPubKey [3] : ec-pub-key, initiatorEphPubKey [4] : ec-pub-key,

}

sigma-2-tbedata => STRUCTURE [ tag-order ]

{

responderNOC    [1] : OCTET STRING, responderICAC [2, optional] : OCTET STRING, signature              [3] : ec-signature,

resumptionID      [4] : OCTET STRING [ length 16 ],

}

sigma-2-struct => STRUCTURE [ tag-order ]

{

responderRandom        [1] : OCTET STRING [ length 32 ],

 

 

responderSessionId [2] : UNSIGNED INTEGER [ range 16-bits ], responderEphPubKey [3] : ec-pub-key,

encrypted2                     [4] : OCTET STRING, responderSEDParams [5, optional] : sed-parameter-struct

}

 

 

 

NOTE

sigma-2-tbsdata is NOT transmitted but is instead signed; the signature will be encrypted and transmitted.

 

  1. The responder SHALL generate a random resumption ID ResumptionID = Crypto_DRBG(len = 16 * 8).
    1. The responder SHALL set the Resumption ID in the Session Context to the value ResumptionID.
  2. The responder SHALL use the Node Operational Key Pair ResponderNOKeyPair, responderNOC, and responderICAC (if present) corresponding to the NOC obtained in Section 4.13.2.3.4, “Validate Sig­ ma1”.
  3. The responder SHALL generate an ephemeral key pair ResponderEphKeyPair = Crypto_Gener­ ateKeypair().
  4. The responder SHALL generate a shared secret:
 
   

 

  1. The responder SHALL encode the following items as a sigma-2-tbsdata with an anonymous tag:
    1. responderNOC as a matter-certificate
    2. responderICAC (if present) as a matter-certificate
    3. publicKey
    4. initiatorEphPubKey
  2. The responder SHALL generate a signature:
 
   

 

  1. The responder SHALL encode the following items as a sigma-2-tbedata, where the encoding of responderNOC and responderICAC items SHALL be byte-for-byte identical to the encoding in sigma- 2-tbsdata:
    1. responderNOC as a matter-certificate. This encoding SHALL be byte-for-byte identical to the encoding in sigma-2-tbsdata.
    2. responderICAC (if present) as a matter-certificate. This encoding SHALL be byte-for-byte iden­

 

tical to the encoding in sigma-2-tbsdata.

  1. TBSData2Signature
  2. ResumptionID
  1. The responder SHALL generate a random number Random = Crypto_DRBG(len = 32 * 8).
  2. The responder SHALL generate the S2K key using Random as Responder Random and Respon­ publicKey as Responder Ephemeral Public Key.
  3. The responder SHALL generate the encrypted and integrity protected data:
 
   

 

  1. The responder SHALL generate a session identifier (ResponderSessionId) for subsequent identifi­ cation of this secured session. The ResponderSessionId field SHALL NOT overlap with any other existing PASE or CASE session identifier in use by the responder. See Section 4.12.1.4, “Choosing Secure Unicast Session Identifiers” for more details. The responder SHALL set the Local Session Identifier in the Session Context to the value ResponderSessionId.
  2. The responder SHALL use the Fabric IPK configured as described in Section 4.13.2.6.1, “Identity Protection Key (IPK)”.
  3. Any context-specific tags not listed in the above TLV schemas SHALL be reserved for future use, and SHALL be silently ignored if seen by an initiator which cannot understand
  4. The responder SHALL send a message with Secure Channel Protocol ID and Sigma2 Protocol Opcode from Table 17, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded Sigma2 Msg2 with an anonymous tag for the outermost struct.
 
   

 

Validate Sigma2

On receipt of Msg2, the initiator SHALL perform the following:

  1. The initiator SHALL generate a shared secret:
 
   

 

  1. The initiator SHALL generate the S2K key using responderRandom as Responder Random and

Msg2.responderEphPubKey as Responder Ephemeral Public Key.

  1. The initiator SHALL generate the decrypted data:
 
   

 

  1. If the value of Success is FALSE, the initiator SHALL send a status report: StatusReport(General­ Code: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform no further
  2. The initiator SHALL verify that the NOC in responderNOC and ICAC in TBEData2.respon­ derICAC (if present) fulfills the following constraints:
    1. The Fabric ID and Node ID SHALL match the intended identity of the receiver Node, as included in the computation of the Destination Identifier when generating
    2. If an ICAC is present, and it contains a Fabric ID in its subject, then it SHALL match the Fab­ ricID in the NOC leaf
    3. The certificate chain SHALL chain back to the Trusted Root CA Certificate TrustedRCAC whose public key was used in the computation of the Destination Identifier when generating Sig­ ma1.
    4. All the elements in the certificate chain SHALL respect the Matter Certificate DN Encoding Rules, including range checks for identifiers such as Fabric ID and Node
  3. If any of the validations from the previous step fail, the initiator SHALL send a status report: StatusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARA­ METER) and perform no further processing.

 

  1. The initiator SHALL verify responderNOC using:
    1. Success = Crypto_VerifyChain(certificates = [TBEData2.responderNOC, responderI­

CAC, TrustedRCAC]), when TBEData2.responderICAC is present, or

  1. Success = Crypto_VerifyChain(certificates = [TBEData2.responderNOC, TrustedRCAC]), when

TBEData2.responderICAC is not present.

  1. If the value of Success is FALSE, the initiator SHALL send a status report: StatusReport(General­ Code: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform no further
  2. The initiator SHALL encode the following items as a sigma-2-tbsdata with an anonymous tag:
    1. responderNOC as copied from TBEData2
    2. responderICAC (if present) as copied from TBEData2
    3. responderEphPubKey
    4. publicKey
  3. The initiator SHALL verify signature (see RFC 5280):
 
   

 

  1. If the value of Success is FALSE, the initiator SHALL send a status report: StatusReport(General­ Code: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform no further
  2. Set the Resumption ID in the Session Context to the value resumptionID.
  3. Set the Peer Session Identifier in the Session Context to the value responderSessionId.

 

Generate and Send Sigma3

If validation is successful, the initiator encodes and sends a Sigma3 message.

 

sigma-3-tbsdata => STRUCTURE [ tag-order ]

{

initiatorNOC                   [1] : OCTET STRING, initiatorICAC     [2, optional] : OCTET STRING, initiatorEphPubKey [3] : ec-pub-key, responderEphPubKey [4] : ec-pub-key,

}

sigma-3-tbedata => STRUCTURE [ tag-order ]

{

initiatorNOC        [1] : OCTET STRING, initiatorICAC [2, optional] : OCTET STRING,

signature              [3] : ec-signature,

 

 

}

sigma-3-struct => STRUCTURE [ tag-order ]

{

encrypted3 [1] : OCTET STRING,

}

 

 

 

NOTE

sigma-3-tbsdata is NOT transmitted but is instead signed; the signature will be encrypted and transmitted.

 

  1. The initiator SHALL select its Node Operational Key Pair InitiatorNOKeyPair, Node Operational Certificates initiatorNOC and initiatorICAC (if present), and Trusted Root CA Certificate Truste­ dRCAC corresponding to the chosen Fabric as determined by the Destination Identifier from Sig­

ma1.

  1. The initiator SHALL encode the following items as a sigma-3-tbsdata with an anonymous tag:
    1. initiatorNOC as a matter-certificate
    2. initiatorICAC (if present) as a matter-certificate
    3. publicKey
    4. responderEphPubKey
  2. The initiator SHALL generate a signature:
 
   

 

  1. The initiator SHALL encode the following items as a sigma-3-tbedata:
    1. initiatorNOC as a matter-certificate. This encoding SHALL be byte-for-byte identical to the encoding in sigma-3-tbsdata.
    2. initiatorICAC (if present) as a matter-certificate. This encoding SHALL be byte-for-byte iden­ tical to the encoding in sigma-3-tbsdata.
    3. TBSData3Signature
  2. The initiator SHALL generate the S3K key.
  3. The initiator SHALL generate the encrypted and integrity protected data:
 
   

 

 

 

  1. Any context-specific tags not listed in the above TLV schemas SHALL be reserved for future use, and SHALL be silently ignored if seen by a responder which cannot understand
  2. The initiator SHALL send a message with Secure Channel Protocol ID and Sigma3 Protocol Opcode from Table 17, “Secure Channel Protocol Opcodes” whose payload is the TLV-encoded Sigma3 Msg3 = { encrypted3 (1) = TBEData3Encrypted } with an anonymous tag for the outermost struct.
  3. The initiator SHALL generate the session encryption keys using the method described in Section 4.13.2.6.6, “Session Encryption Keys”.

 

Validate Sigma3

On receipt of Msg3, the responder SHALL perform the following:

  1. The responder SHALL generate the S3K key.
  2. The responder SHALL generate the decrypted data:
 
   

 

  1. If the value of Success is FALSE, the responder SHALL send a status report: StatusReport(Gener­ alCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform no further
  2. The responder SHALL verify that the NOC in initiatorNOC and the ICAC in TBE­ Data3.initiatorICAC fulfill the following constraints:
    1. The Fabric ID SHALL match the Fabric ID matched during processing of the Destination Identifier after receiving
    2. If an ICAC is present, and it contains a Fabric ID in its subject, then it SHALL match the Fab­ ricID in the NOC leaf
    3. The certificate chain SHALL chain back to the Trusted Root CA Certificate TrustedRCAC whose public key was matched during processing of the Destination Identifier after receiving Sig­ ma1.
    4. All the elements in the certificate chain SHALL respect the Matter Certificate DN Encoding

 

Rules, including range checks for identifiers such as Fabric ID and Node ID.

  1. If any of the validations from the previous step fail, the responder SHALL send a status report: StatusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARA­ METER) and perform no further processing.
  2. The responder SHALL verify initiatorNOC using:
    1. Success = Crypto_VerifyChain(certificates = [TBEData3.initiatorNOC, initiatorI­

CAC, TrustedRCAC]), when TBEData3.initiatorICAC is present, or

  1. Success = Crypto_VerifyChain(certificates = [TBEData3.initiatorNOC, TrustedRCAC]), when

TBEData3.initiatorICAC is not present.

  1. If the value of Success is FALSE, the responder SHALL send a status report: StatusReport(General­ Code: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER_) and perform no further
  2. The responder SHALL encode the following items as a sigma-3-tbsdata with an anonymous tag:
    1. initiatorNOC as copied from TBEData3
    2. initiatorICAC (if present) as copied from TBEData3
    3. initiatorEphPubKey
    4. publicKey
  3. The responder SHALL verify signature (see RFC 5280):
 
   

 

  1. If the value of Success is FALSE, the responder SHALL send a status report: StatusReport(General­ Code: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER) and perform no further
  2. The responder SHALL generate the session keys as described in Section 4.13.2.6.6, “Session Encryption Keys”.
  3. The responder SHALL initialize its Local Message Counter in the Session Context per Section 4.5.1.1, “Message Counter Initialization”.
  4. The responder SHALL initialize the Message Reception State in the Session Context` and set the synchronized max_message_counter of the peer to 0.
  5. The responder SHALL set SessionTimestamp to a timestamp from a clock which would allow for the eventual determination of the last session use relative to other
  6. The responder SHALL encode and send SigmaFinished.

 

Validate Sigma1 with Resumption

The responder SHALL continue validating the Sigma1 message Msg1 as follows:

 

  1. Obtain the SharedSecret from the Section 4.12.2.1, “Secure Session Context” of the resumed ses­ sion.
  2. Generate the S1RK key.
  3. Verify the Resume1MIC by decrypting the following values:
 
   

 

  1. If the value of Success is FALSE, the responder SHALL continue processing Sigma1 as if it didn’t include any resumption information by continuing the steps in Section 4.13.2.3.5, “Validate Sig­ ma1 Destination ID”.
  2. If the value of Success is TRUE, the responder SHALL:
    1. Set the Peer Session Identifier in the in the Session Context to the value initiatorSes­ sionId.
    2. Send a Sigma2_Resume

 

Generate and Send Sigma2_Resume

The responder SHALL encode and send a Sigma2_Resume message in response to a valid Sigma1 with response.

 

sigma-2-resume-struct => STRUCTURE [ tag-order ]

{

resumptionID                 [1] : OCTET STRING [ length 16 ], sigma2ResumeMIC       [2] : OCTET STRING [ length 16 ], responderSessionID [3] : UNSIGNED INTEGER [ range 16-bits ], responderSEDParams [4, optional] : sed-parameter-struct

}

  1. The responder SHALL generate a new resumption ID ResumptionID = Crypto_DRBG(len = 128).
  2. The responder SHALL generate a session identifier (ResponderSessionId) for subsequent identifi­ cation of this session. The ResponderSessionId field SHALL NOT overlap with any other existing PASE or CASE session identifier in use by the responder. See Section 4.12.1.4, “Choosing Secure Unicast Session Identifiers” for more details. The responder SHALL set the Local Session Iden­ tifier in the Session Context to the value ResponderSessionId.
  3. The responder SHALL generate the S2RK key.

 

  1. The responder SHALL generate a resumption MIC:
 
   

 

  1. Any context-specific tags not listed in the above TLV schemas SHALL be reserved for future use, and SHALL be silently ignored if seen by an initiator which cannot understand
  2. The responder SHALL send a message with the Secure Channel Protocol ID and Sigma2Resume Pro­ tocol Opcode from Table 17, “Secure Channel Protocol Opcodes” whose payload is the TLV- encoded Sigma2_Resume ResumeMsg2 with an anonymous tag for the outermost struct.
 
   

 

  1. The responder SHALL generate the session keys as described in Section 4.13.2.6.7, “Resumption Session Encryption Keys”.

 

Validate Sigma2_Resume

On receipt of ResumeMsg2, the initiator SHALL perform the following:

  1. The initiator SHALL generate the S2RK key.
  2. The initiator SHALL verify the Resume2MIC by decrypting the following values:
 
   

 

 

 

  1. If Success is FALSE, the initiator SHALL send a status report: StatusReport(GeneralCode: FAILURE, ProtocolId: SECURE_CHANNEL, ProtocolCode: INVALID_PARAMETER_) and perform no further processing.
  2. The initiator SHALL set the Resumption ID in the Session Context to the value resump­ tionID.
  3. The initiator SHALL generate the session keys as described in Section 4.13.2.6.7, “Resumption Session Encryption Keys”.
  4. The initiator SHALL reset its Local Message Counter in the Session Context per Section 4.5.1.1, “Message Counter Initialization”.
  5. The initiator SHALL reset the Message Reception State of the Session Context` and set the syn­ chronized max_message_counter of the peer to 0.
  6. The initiator SHALL set SessionTimestamp to a timestamp from a clock which would allow for the eventual determination of the last session use relative to other
  7. The initiator SHALL set the Peer Session Identifier in the in the Session Context to the value

ResumeMsg2.responderSessionId.

  1. The initiator SHALL send Section 4.13.2.3.13, “SigmaFinished”.

 

SigmaFinished

 

To indicate the successful completion of the protocol, the Node receiving Sigma3 (if a new session is being established) or Sigma2_Resume (if a session is being resumed) SHALL send a status report:

StatusReport(GeneralCode: SUCCESS, ProtocolId: SECURE_CHANNEL, ProtocolCode: SESSION_ESTABLISH­

MENT_SUCCESS).

On successful receipt of SigmaFinished:

  1. The receiving node SHALL initialize the Local Message Counter according to Section 4.5.1.1, “Message Counter Initialization” for the newly established secure session whose success is acknowledged by this
  2. The receiving node SHALL set SessionTimestamp to a timestamp from a clock which would allow for the eventual determination of the last session usage relative to other

 

If this message is received out-of-order or unexpectedly, then it SHALL be ignored.

 

4.13.2.4.  Field Descriptions

 

Destination Identifier

 

destination-identifier => OCTET STRING [length CRYPTO_HASH_LEN_BYTES]

 

The Destination Identifier field enables the initiator of the Sigma1 message to unambiguously

 

express the following, in a privacy-preserving manner:

 

  • Which shared Trusted Root to select
  • Which Fabric ID to use for validation of initiator and responder operational certificates
  • Which Node ID is targeted in the given Fabric This serves several purposes:
    1. It requires an initiator to have knowledge of both the IPK and one of the full identities of the responder Node before it forces the responder node to generate a costly Sigma2 message
      1. Note that the replay of previously recorded initiator messages is possible, and therefore a Node MAY choose to keep memory of some prior destination identifiers which it would later reject if seen again, for additional replay protection
    2. It ensures that there is no ambiguity on the responder as to which Fabric was selected for com­ munication
    3. It hides which Fabric was chosen by the initiator A destination identifier is generated by:
  1. Concatenating the following octet strings for subsequent usage as a destinationMessage:
    • initiatorRandom: The value of initiatorRandom that will be used in the same message as the Destination Identifier
    • rootPublicKey: The public key of the root of trust of the desired fabric, from the ec-pub-key field of the Matter Certificate of that root, as an uncompressed elliptic curve point as defined in section 2.3.3 of SEC1
    • fabricId: The Fabric ID of the destination, matching the matter-fabric-id field of the Matter Certificate of the desired destination’s NOC, and encoding the 64-bit scalar as a little-endian byte order octet string
    • nodeId: The Node ID of the destination, matching the matter-node-id field of the Matter Cer­ tificate of the desired destination’s NOC, and encoding the 64-bit scalar as a little-endian byte order octet string
  2. Obtaining the appropriate Identity Protection Key (IPK) Operational Group Key for the associ­ ated Fabric under Group Key Set index 0 within the Group Key Management Cluster.
  3. Computing an identifier destinationIdentifier of length CRYPTO_HASH_LEN_BYTES using Crypto_H­ MAC() with the IPK as the key and destinationMessage as the message

The above steps can be summarized as:

 

destinationMessage = initiatorRandom || rootPublicKey || fabricId || nodeId destinationIdentifier = Crypto_HMAC(key=IPK, message=destinationMessage)

For example, given the following:

 

  • Root public key for the common Fabric, in uncompressed elliptical curve point form:

 

 

RootPublicKey := // Raw uncompressed point form 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

 

  • Common Fabric ID of 0x2906_C908_D115_D362 scalar (octets “62:d3:15:d1:08:c9:06:29” in little- endian)
  • Desired Destination Node ID of 0xCD55_44AA_7B13_EF14 (octets “14:ef:13:7b:aa:44:55:cd” in lit­ tle-endian)
  • Identity Protection Key Epoch Key value of:
 
   

 

  • Note that this is the octet string of a group Epoch Key as would be provided in the IPKValue field of the AddNOC command in the Node Operational Credentials Cluster, or in one of the

EpochKey fields of the KeySetWrite command in the Group Key Management Cluster.

  • The derived Operational Group Key to be used for computation of a destination identifier, given the above values of root public key, Fabric ID and Identity Protection Key Epoch Key, would be:
 
   

 

  • Initiator Random value of:

 

7e:17:12:31:56:8d:fa:17:20:6b:3a:cc:f8:fa:ec:2f:

4d:21:b5:80:11:31:96:f4:7c:7c:4d:eb:81:0a:73:dc

Then, using the above procedure would yield the following:

 

  • DestinationMessage octets:

 

7e:17:12:31:56:8d:fa:17:20:6b:3a:cc:f8:fa:ec:2f:

4d:21:b5:80:11:31:96:f4:7c:7c:4d:eb:81:0a:73:dc:

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:62:d3:15:d1:08:c9:06:29:14:ef:13:7b:aa:44:55:

cd

  • DestinationIdentifier octets:

 

 

dc:35:dd:5f:c9:13:4c:c5:54:45:38:c9:c3:fc:42:97:

c1:ec:33:70:c8:39:13:6a:80:e1:07:96:45:1d:4c:53

 

Public Key

 

ec-pub-key => OCTET STRING [ length CRYPTO_PUBLIC_KEY_SIZE_BYTES ]

A public key ec-pub-key is the byte string representation of an uncompressed elliptic curve point as defined in section 2.3.3 of SEC1.

 

4.13.2.5.  Signature

 

An ec-signature is the encoding of the signature as defined in Section 3.5.3, “Signature and verifica­ tion”.

 

ec-signature => OCTET STRING [ length (CRYPTO_GROUP_SIZE_BYTES * 2) ]

 

4.13.2.6.  Cryptographic Keys

 

Identity Protection Key (IPK)

The Identity Protection Key (IPK) SHALL be the operational group key under GroupKeySetID of 0

for the fabric associated with the originator’s chosen destination.

 

The IPK SHALL be exclusively used for Certificate Authenticated Session Establishment. The IPK SHALL NOT be used for operational group communication.

For the generation of the Destination Identifier, the originator SHALL use the operational group key with the second newest EpochStartTime, if one exists, otherwise it SHALL use the single operational group key available.

The operational group key index to use to follow the “second newest EpochStartTime” rule is illus­ trated below:

 

Number of keys in Group Key Set Operational key index Epoch Key
1 0 EpochKey0
2 0 EpochKey0
3 1 EpochKey1

 

Sigma2 Key (S2K)

 

  1. A transcript hash SHALL be generated:

 

 

 

  1. The Sigma2 key SHALL be generated:
 
   

 

where || indicates message concatenation and IPK is generated according to Section 4.13.2.6.1, “Identity Protection Key (IPK)”.

 

Sigma3 Key (S3K)

 

  1. A transcript hash SHALL be generated:
 
   

 

  1. The Sigma3 key SHALL be generated:
 
   

 

where || indicates message concatenation and IPK is generated according to Section 4.13.2.6.1, “Identity Protection Key (IPK)”.

 

Sigma1 Resumption Key

 

The Sigma1 resumption key SHALL be generated:

 

byte S1RK_Info[] = /* “Sigma1_Resume” */

{0x53, 0x69, 0x67, 0x6d, 0x61, 0x31, 0x5f,

0x52, 0x65, 0x73, 0x75, 0x6d, 0x65}

 

 

S3K_Info

S1RK = Crypto_KDF(

inputKey = SharedSecret,

salt = Sigma1.initiatorRandom || ResumptionID, info = S1RK_Info,

len = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS

)

 

where || indicates message concatenation and ResumptionID is the identifier for the previous ses­ sion.

 

Sigma2 Resumption Key

 

The Sigma2 resumption key SHALL be generated:

 

byte S2RK_Info[] = /* “Sigma2_Resume” */

{0x53, 0x69, 0x67, 0x6d, 0x61, 0x32, 0x5f, 0x52, 0x65, 0x73, 0x75, 0x6d, 0x65}

S2RK = Crypto_KDF(

inputKey = SharedSecret,

salt = Sigma1.initiatorRandom || ResumptionID, info = S2RK_Info,

len = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS

)

where || indicates message concatenation and ResumptionID is the new identifier for the this ses­ sion.

 

Session Encryption Keys

 

  1. A transcript hash SHALL be generated:
 
   

 

  1. The session encryption keys SHALL be generated:
 
   

 

 

 

  1. Each key is exactly CRYPTO_SYMMETRIC_KEY_LENGTH_BITS
  2. The initiator SHALL use I2RKey to encrypt and integrity protect messages and the `R2IKey’ to decrypt and verify
  3. The responder SHALL use R2IKey to encrypt and integrity protect messages and the `I2RKey’ to decrypt and verify
  4. The AttestationChallenge SHALL only be used as a challenge during device attestation. See Sec­ tion 6.2.3, “Device Attestation Procedure” for more

where || indicates message concatenation.

 

Resumption Session Encryption Keys

 

  1. The resumption session encryption keys SHALL be generated:
 
   

 

  1. Each key is exactly CRYPTO_SYMMETRIC_KEY_LENGTH_BITS
  2. The initiator SHALL use I2RKey to encrypt and integrity protect messages and the `R2IKey’ to decrypt and verify
  3. The responder SHALL use R2IKey to encrypt and integrity protect messages and the `I2RKey’ to decrypt and verify
  4. The AttestationChallenge SHALL only be used as a challenge during device attestation. See Sec­ tion 6.2.3, “Device Attestation Procedure” for more

where || indicates message concatenation and ResumptionID is the new identifier for the this ses­ sion.

 

4.13.2.7.  Session Context Storage

 

After the session is established successfully at both peers, some fields SHALL be recorded in the secure session context for later use (see Section 4.12.2, “Application Data Phase”), in addition to the Session Encryption Keys:

  • The peer NOC’s matter-node-id (3.6.1.4.1.37244.1.1) from the subject field

 

  • The Section 2.5.1, “Fabric References and Fabric Identifier” for the Fabric within which this secure session is being established
  • All peer NOC’s case-authenticated-tag (3.6.1.4.1.37244.1.6) from the subject field, if present

These fields MAY be recorded at any opportune point during the protocol, but SHALL only be com­ mitted to the secure session context once the session is established successfully at both peers.

 

4.13.2.8.  Minimal Number of CASE Sessions

 

A node SHALL support at least 3 CASE session contexts per fabric. Device type specifications MAY require a larger minimum. Unless the device type specification says otherwise, a minimum number it defines is a per-fabric minimum.

The minimal supported capabilities, subject to the minimal constraints above, are reported in the CapabilityMinima of the Basic Information cluster.

  • Example: If a device type requires at least 4 CASE session contexts, and a node supports 7 fab­ rics, the node would support at least 28 CASE session contexts, and ensure that each fabric could use at least 4 of

 

 

 

 

4.14.   Group Communication

 

This section specifies the semantics of sending and receiving multicast group messages and the life­ cycle of such groupcast sessions. Multicast addressing is accomplished using the 16-bit Group ID field as the destination address. A multicast group is a collection of Nodes, all registered under the same multicast Group ID. A multicast message is sent to a particular destination group and is received by all members of that group.

 

4.14.1.  Groupcast Session Context

 

Groupcast sessions are conceptually long-running, lasting the duration of a node’s membership in a group. Group membership is tracked in the Group Key Management Cluster. However, on ingress of each groupcast message, the following ephemeral context SHALL be constructed to inform upper layers of groupcast message provenance:

  1. Fabric Index: Records the local Fabric Index for the Fabric to which an incoming message’s group is
  2. Group ID: Captures the Group ID to which a groupcast message was
  3. Source Node ID: The Source Node ID enclosed by the sender of a groupcast
    • Together, Fabric Index, Group ID and Source Node ID comprise a unique identifier that upper layers may use to understand the source and destination of groupcast
  4. Source IP Address: The unicast source IP address for the originator of the
  5. Source Port: The source port for the originator of the
    • The source IP address and port MAY be used for unicast responses to group communication peers, as are required for the Message Counter Synchronization Protocol.
  6. Operational Group Key: The Operational Group Key that was used to encrypt the incoming group

 

message.

  1. Group Session ID: Records the Group Session ID derived from the Operational Group Key used to encrypt the

 

Once a Groupcast Session Context with trust-first policy is created to track authenticated messages from a given Source Node ID, that record SHALL NOT be deleted or recycled until the node reboots. This is to prevent replay attacks that first exhaust the memory allocated to group session counter tracking and then inject older messages as valid, and enforces that trust-first authentication works as intended within the full duration of a boot cycle. Any message from a source that cannot be tracked SHALL be dropped.

 

4.14.2.  Sending a group message

 

To prepare a multicast message to a Group ID with a given GroupKeySetID and IPv6 hop count parameter, the Node SHALL:

  1. Obtain, for the given GroupKeySetID, the current Operational Group Key as the Encryption Key, and the associated Group Session
    1. If no key is found for the given GroupKeySetID, security processing SHALL fail and no fur­ ther security processing SHALL be done on this
  2. Perform Section 4.6.1, “Message Transmission” processing steps on the message with the follow­ ing arguments:
    1. The Destination Node Id argument SHALL be the Group Node Id corresponding to the given Group
    2. The Session Id argument SHALL be the Group Session ID from step
    3. The Security Flags SHALL have only the P Flag
    4. The transport SHALL be a site-local routable IPv6

 

Next, prepare the message as an IPv6 packet:

 

  1. Set the private, secured message from step 2 above as the IPv6
  2. Set the IPv6 hop count to the value
  3. Set the IPv6 destination to the Section 2.5.6.2, “IPv6 Multicast Address” based on the provided destination Group ID, Fabric ID, and Section 11.2.6.4.9, “GroupKeyMulticastPolicy Field” of the group
  4. Set the IPv6 source to an operational IPv6 Unicast Address of the sending
  5. Set the IPv6 UDP port number to the Matter IPv6 multicast port.

 

4.14.3.  Receiving a group message

 

All Nodes supporting groups SHALL register to receive on the associated IPv6 multicast address, at the Matter IPv6 multicast port, for each group of which they are a member.

Upon receiving an IPv6 message addressed to one of these Multicast Addresses the Node is regis­ tered for, the Node SHALL:

 

  1. Extract the message from the IPv6
  2. Perform Section 4.6.2, “Message Reception” processing steps on the

 

 

 

4.15.   Group Key Management

 

This section describes operational group keys, a mechanism for generating, disseminating and managing shared symmetric keys across a group of Nodes in a Fabric. Operational group keys are made available to applications for the purpose of authenticating peers, securing group communica­ tions, and encrypting data. These keys allow Nodes to:

  • Prove to each other that they are members of the associated group
  • Exchange messages confidentially, and without fear of manipulation by non-members of the group
  • Encrypt data in such a way that it can only be decrypted by other members of the group

 

A central feature of operational group keys is the ability to limit access to keys to a trusted set of Nodes. In particular, credentials required to generate operational group keys SHALL only be acces­ sible to Nodes with a certain level of privilege — those deemed a member of the group. Barring soft­ ware error or compromise of a privileged Node, access to shared keys SHALL be computationally infeasible for non-trusted parties.

Operational group keys are shareable across all types and combinations of Nodes as determined by the Administrator managing the group. Given all Nodes in possession of the current epoch keys for the group can communicate with other Nodes in the group, it is the responsibility of the Adminis­ trator managing the group to only compose groups of Nodes where communication is appropriate for the given application and security requirements.

 

4.15.1.  Operational Groups

 

An operational group is a logical collection of Nodes that are running one or more common applica­ tion clusters and share a common security domain in the form of a shared, symmetric group key. For example, a set of Nodes running a lighting application can form an operational group by shar­ ing a common operational group key derived from the mechanisms described here. Subgroups can be formed within the operational group by defining distinct Group Identifiers for each set of Nodes, while sharing a common operational group key.

Membership in the security domain of an operational group is determined by a Node’s possession of all the epoch keys required to generate the current, valid operational group key for the group. Individual Nodes can be members of multiple operational groups simultaneously. The set of groups to which a Node belongs can change over time as dictated by application requirements and policies. Groups MAY be introduced or withdrawn over time as need arises. === Operational Group Ids Oper­ ational groups are identified uniquely within a Fabric by a Group Identifier. Administrators SHALL assign Group Ids such that no two operational groups within a Fabric have the same Group ID. It is assumed a given Administrator has sufficient access to centralized knowledge, so as to allocate unique Group Ids under a given Fabric such that there are no collisions.

Multiple operational groups MAY share the same operational group key, and thus be used to create

 

logical subgroups over a shared security domain. Operational groups which do not share related functionality, such as a lighting group and a sprinkler group, SHOULD NOT share the same opera­ tional key. As an example policy, a lighting application could have all lighting Nodes share a single group key, while organizing lighting subgroups for various rooms or spaces within the structure by assigning a different Group ID to each such subgroup.

 

4.15.2.  Operational Group Key Derivation

 

An operational group key is a symmetric key used as the Encryption Key during Message Processing for group communication. An operational group key is produced by applying a key derivation func­ tion with an epoch key and salt value as inputs as follows:

 

OperationalGroupKey =

Crypto_KDF (

InputKey = Epoch Key,

Salt = CompressedFabricIdentifier, Info = “GroupKey v1.0”,

Length = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS

)

where [] denotes a zero-length array.

The Info portion of the key derivation is specified in Section 4.15.2.1, “Group Security Info”. The

Salt portion of the key derivation is specified in Section 4.3.2.2, “Compressed Fabric Identifier”.

For example, given:

  • An Epoch Key value of: 23:5b:f7:e6:28:23:d3:58:dc:a4:ba:50:b1:53:5f:4b
  • A CompressedFabricIdentifier value of: 87:e1:b0:04:e2:35:a1:30

After the above derivation following the definition of Crypto_KDF in Section 3.8, “Key Derivation Function (KDF)”, the resulting operational group key would be: a6:f5:30:6b:af:6d:05:0a:f2:3b:a4:bd:6b:9d:d9:60.

Group membership is enforced by limiting access to the epoch keys. Only Nodes that possess the input epoch key can derive a given operational key. Lack of possession of a particular epoch key restricts access, based on the distribution policy of the epoch keys.

The following diagram shows the process by which operational keys are derived from the epoch key material:

 

 

Figure 17. Group Key Derivation

 

4.15.2.1.  Group Security Info

 

A hard-coded group security info is used to diversify the set of operational group keys. This value is hard-coded into the standard’s implementation, and thus is distributed with the associated code. Should the standard’s security mechanisms need to evolve (e.g. to upgrade encryption from AES- 128 to AES-256), the group security info can be changed to ensure that new keys will be derived for use in the new algorithm. The group security info SHALL be the byte stream “GroupKey v1.0”, i.e.

0x47 0x72 0x6f 0x75 0x70 0x4b 0x65 0x79 0x20 0x76 0x31 0x2e 0x30.

With the exception of the group security info, all input key material SHALL be maintained on a per- Fabric basis.

 

4.15.2.2.  Group Key Set

 

A group key set limits the key derivation process to Nodes within the respective operational groups. Access to a group key set is limited based on the functionality provided by a Node and/or the privi­ lege afforded to it. For example, certain home security devices, such as a security system or door lock, may have access to a “Physical Access” group key set, while devices such as light bulbs or win­ dow coverings would not.

Operational group key lifetime is limited by assigning an expiration time to each epoch key in a given group key set. By constraining the validity of a given epoch key to an epoch, the ability for members to derive and operate with an operational group key can be constrained to particular periods of time. Epoch keys may be rotated on a periodic basis, and denying access to updated ver­ sions of these keys serves as a means to eject group members.

 

4.15.3.  Epoch Keys

 

Epoch keys provide a means for limiting the lifetime of derived operational group keys. They also provide a way for an Administrator to revoke access to Nodes that have been explicitly excluded from an operational group (albeit after a period of time).

 

Epoch keys are generated, managed, and stored by an Administrator on a per-Fabric basis. Each key SHALL be a random value of length CRYPTO_SYMMETRIC_KEY_LENGTH_BITS bits.

 

EpochKey = Crypto_DRBG(len = CRYPTO_SYMMETRIC_KEY_LENGTH_BITS)

 

Each epoch key has associated with it a start time that denotes the time at which the key becomes active for use by transmitting Nodes. Epoch key start times are absolute UTC time in microseconds encoded using the epoch-us representation.

 

4.15.3.1.  Using Epoch Keys

 

Nodes sending group messages SHALL use operational group keys that are derived from the current epoch key (specifically, the epoch key with the latest start time that is not in the future). Nodes that cannot reliably keep track of time calculate the current epoch key as described in Section 4.15.3.4, “Epoch Key Rotation without Time Synchronization”.

Nodes receiving group messages SHALL accept the use of any key derived from one of the currently installed epoch keys. This requirement holds regardless of whether the start time for the key is in the future or the past. This means Nodes continue to accept communication secured under an epoch key until that key is withdrawn by explicitly deleting the key from a Node’s group state by the key distribution Administrator.

Note that there is no end time associated with an epoch key. An epoch key marked with the maxi­ mum start time SHALL be disabled and render the corresponding epoch key slot unused.

 

4.15.3.2.  Managing Epoch Keys

 

The epoch keys are managed using the Group Key Management Cluster. For every group key set published by the key distribution Administrator, there SHALL be at least 1 and at most 3 epoch keys in rotation. Key additions or updates are done using the KeySetWrite command.

Key updates are idempotent operations to ensure the Administrator is always the source of truth. An epoch key update SHALL order the keys from oldest to newest.

Any epoch key update MAY deliver a partial key set but SHALL include EpochKey0 and MAY include EpochKey1 and EpochKey2. Any update of the key set, including a partial update, SHALL remove all previous keys in the set, however many were defined.

 

An Administrator MAY completely remove a group key set from a Node using the KeySetRemove command.

 

4.15.3.3.  Epoch Key Rotation

 

The key distribution Administrator generates new epoch keys on a regular basis, giving each a unique id and adding them to the list of existing epoch keys within a group. The start time for each new epoch key is scheduled to occur after a configurable key propagation interval. The propagation interval is set sufficiently large such that the Administrator can synchronize all Nodes in the opera­ tional group with the new epoch key list within that time.

The rotation rate for epoch keys is expected to be on the order of days to weeks for typical applica­ tions, but the rate is configurable as required by the key distribution Administrator. Because of the relatively long rotation interval, and the overlap of active epoch keys, local clock drift within Nodes is generally not a concern.

 

4.15.3.4.  Epoch Key Rotation without Time Synchronization

 

Although epoch keys are distributed with an associated start time, it is nonetheless possible for Nodes that do not maintain a synchronized clock to participate in key rotation. Specifically, upon receiving a new epoch key list from the key distribution Administrator, such a Node can note which of the keys is the current epoch key by comparing their relative start times and using the current epoch key which has the second newest time. It can then use the current key for all locally initiated security interactions until such time as it makes contact with the distribution Administrator again.

This scheme requires the Node to receive epoch keys from the key distribution Administrator at a rate that is at least as fast as the configured key propagation interval. The Administrator SHOULD provide a sufficient set of epoch keys to Nodes that do not maintain synchronized time so that they can maintain communication with other group members while a key update is in progress. The key distribution Administrator SHOULD update all Nodes without time, such as SEDs, before the new epoch key is activated, and then let Nodes with time all roll to the new epoch key at the synchronized start time.

 

4.15.3.5.  Epoch Key Rotation logic

 

The full life-cycle of Epoch Key rotation is shown in Figure 18, “Epoch Key Rotation”. For each epoch key slot, the start time of the key is shown as one of the following values:

  • New – a key with a start time in the
  • Current – the active key with the newest start
  • Previous – the active key with the second newest start
  • Old – an active key with the third newest start

 

The diagram shows two types of state transitions:

 

  1. Admin – an update of an old key by the Administrator. Changes made during this state transi­ tion are indicated in
  2. Epoch Activate – activation of an epoch key due to system time becoming greater than the start time. Changes during this state transition are indicated in

 

 

Figure 18. Epoch Key Rotation

 

The Admin Refresh state begins when an entire group key set is freshly written to a Node during commissioning or administration, such as when a new group is added. The Epoch Activate state is entered when time progresses to activate a fresh current epoch key, aging out the other epoch key slots. The Admin Update state is entered when an Administrator updates an old epoch key with a new epoch key. When in steady state, the Admin Refresh state MAY be entered in place of an Admin Update state transition to update additional keys to the required ones or to completely reset the group secu­

rity.

 

Note that in the above diagram, only an example key distribution scheme is illustrated. It is also possible to devise key distribution algorithms that to not rely on time synchronization, or group configurations that never rotate keys in favor or configuring new groups and removing groups and group key sets with expired keys.

 

Group Key Set ID

 

The Group Key Set ID is a 16-bit field that uniquely identifies the set of epoch keys used for deriva­ tion of an operational group key. Each Group Key Set ID is scoped to a particular Fabric and assigned by an Administrator so as to be unique within a Fabric.

The Group Key Set ID of 0 SHALL be reserved for managing the Identity Protection Key (IPK) on a given Fabric. It SHALL NOT be possible to remove the IPK Key Set if it exists.

 

4.15.3.6.  Group Session ID

 

A Group Session ID is a special case of a 16-bit Session ID that is specifically used for group commu­ nication. When Session Type is 1, denoting a group session, the Session ID SHALL be a Group Ses­ sion ID as defined here. The Group Session ID identifies probable operational group keys across a Fabric. The Group Session ID for a given operational group key is derived by treating the output of a Crypto_KDF against the associated Operational Group Key as a big-endian representation of a 16-bit

 

integer, as follows:

 

GroupKeyHash =

Crypto_KDF (

InputKey = OperationalGroupKey, Salt = [],

Info = “GroupKeyHash”, Length = 16        // Bits

)

// GroupKeyHash is an array of 2 bytes (16 bits) per Crypto_KDF

// GroupSessionId is computed by considering the GroupKeyHash as a Big-Endian

// value. GroupSessionId is a scalar. Its use in fields within messages may cause a

// re-serialization into a different byte order than the one used for initial generation.

GroupSessionId = (GroupKeyHash[0] << 8) | (GroupKeyHash[1] << 0)

where [] denotes a zero-length array. For example, given:

  • An Operational Group Key value of: a6:f5:30:6b:af:6d:05:0a:f2:3b:a4:bd:6b:9d:d9:60

After the above derivation following the definition of Crypto_KDF in Section 3.8, “Key Derivation Function (KDF)”, the resulting Group Session ID data would be:

  • Raw output of GroupKeyHash: b9:f7
  • Group Session ID scalar value to be used for further processing: 0xB9F7 (47607 decimal)

 

The Group Session ID MAY help receiving nodes efficiently locate the Operational Group Key used to encrypt an incoming groupcast message. It SHALL NOT be used as the sole means to locate the asso­ ciated Operational Group Key, since it MAY collide within the fabric. Instead, the Group Session ID provides receiving nodes a means to identify Operational Group Key candidates without the need to first attempt to decrypt groupcast messages using all available keys.

On receipt of a message of Group Session Type, all valid, installed, operational group key candidates referenced by the given Group Session ID SHALL be attempted until authentication is passed or there are no more operational group keys to try. This is done because the same Group Session ID might arise from different keys. The chance of a Group Session ID collision is 2-16 but the chance of both a Group Session ID collision and the message MIC matching two different operational group keys is 2-80.

Group Session Ids are sized to fit within the context of the Session Identifier field of a message. When used in this context, the Group Session ID value allows a receiving Node to identify the appropriate message encryption key to use from the set of active operational keys it has currently installed.

 

4.15.4.  Distribution of Key Material

 

The operational group keys mechanism relies on a key distribution Administrator to reliably dis­ tribute select epoch key material to appropriate participants. It is assumed the key distribution Administrator is in possession of all epoch keys, has knowledge of the set of group security domain members which require access to those keys, and is responsible for pushing updates of these cre­ dentials to all authorized Nodes in those groups it manages.

Key material is distributed to key holders using the Group Key Management Cluster. In general, the key material of a Node is exposed via Attributes with ACL entries that only allow access by the key distribution Administrator. The information exposed in the Section 11.2, “Group Key Management Cluster” includes the group epoch keys and associated group session identifiers.

 
   

Figure 19. Group Key Distribution

 

4.15.4.1.  Installing a Group onto a Newly Commissioned Node

 

This section provides an example of the operations required to install a group onto a newly com­ missioned node.

 

 

Figure 20. Installing a group onto a new node

 

Sequence:

 

  • Admin:
    • Generate fabric-unique group ID GID and random key key0 for group key set ID K.
    • Write the group key set K to the remote node, GroupMember, using KeySetWrite
    • Associate group ID GID with key set K by writing an entry to the GroupKeyMap list
  • GroupMember:
    • Node subscribes to the IPv6 multicast address generated from the fabric ID and group
  • Admin:
    • Associate endpoint with group ID GID by sending the Groups cluster’s AddGroup command to
  •  

 

4.16.   Message Counter Synchronization Protocol (MCSP)

 

This section describes the protocol used to securely synchronize the message counter used by a sender of messages encrypted with a symmetric group key.

Message counter synchronization is an essential part of enabling secure messaging between mem­ bers of an operational group. Specifically, it protects against replay attacks, where an attacker replays older messages, which may result in unexpected behaviour if accepted and processed by the receiver.

The recipient of a message encrypted with a group key can trust and process that message only if it has kept the last message counter received from a given sender using that key.

Underlying MCSP is a simple request / response protocol. When a multicast message with unknown counter is received, synchronization via MCSP begins by sending a synchronization request via uni­ cast UDP to the multicast message originator’s unicast IPv6 address. That originator then sends a synchronization response to the unsynchronized node via unicast UDP. After cryptographic verifi­ cation, the formerly unsynchronized node is now synchronized with the originator’s message counter and can trust the original and subsequent messages from the originator node.

 

4.16.1.  Message Counter Synchronization Methods

 

There are two methods for synchronizing the message counter of a peer node, which are config­ urable per-group-key based on the GroupKeySecurityPolicy field of a given group key set (see GroupKeySetStruct).

 

4.16.1.1.  Trust-first policy

 

The first authenticated message counter from an unsynchronized peer is trusted, and its message counter is used to configure message-counter-based replay protection on future messages from that node. All control messages (any message with C Flag set) use the control message counter and SHALL use Trust-first for synchronization. Note that MCSP is not used for Trust-first synchroniza­ tion.

This policy provides lower latency for less security-sensitive applications such as lighting.

 

WARNING         Trust-first synchronization is susceptible to accepting a replayed message after a Node has been rebooted.

 

4.16.1.2.  Cache-and-sync policy

 

The message that triggers message counter synchronization is stored, a message counter synchro­ nization exchange is initiated, and only when the synchronization is completed is the original mes­ sage processed. Cache-and-sync provides replay protection even in the case where a Node has been rebooted, at the expense of higher latency.

Support for the cache-and-sync policy and MCSP is optional. A node indicates its ability to support this feature via the Group Key Management cluster FeatureMap.

 

 

 

 

 

WARNING

Large groups may cause significant message synchronization burden on the sender and message queueing pressure or latency on the receiver when mes­ sage counter synchronization state is out of sync, such as after a brown-out, on first message to a new large group, or similar large scale sets of synchroniza­ tions being required at a single point in time.

 

 

4.16.2.  Group Peer State

 

The Group Peer State Table stores information about every peer with which the node had a group message exchange. For every peer node id the following information is available in the table:

  • Peer’s Encrypted Group Data Message Counter Status:
  • Synchronized Data Message Counter – the largest encrypted data message counter received from the peer, if
  • Flag to indicate whether this counter value is valid and
  • The message reception state bitmap tracking the recent window of data message counters received from the
    • Peer’s Encrypted Group Control Message Counter Status:
  • Synchronized Control Message Counter – the largest encrypted control message counter received from the peer, if
  • Flag to indicate whether this counter value is valid and
  • The message reception state bitmap tracking the recent window of control message counters received from the

There are three scenarios where the receiver of an encrypted message does not know the sender’s last message counter:

  • The encrypted message is the first received from a
  • The device rebooted without persisting the Group Peer State Table Note: it is not required to persist the Peer State Table.
  • The entry for the Peer in the Group Peer State Table was expunged due to the table being

 

There SHALL be at least 10 entries per supported fabric for Peer Encrypted Group data Message Status in the Group Peer State table. This number SHOULD NOT be less than 5 entries per fabric per instance of Groups cluster on an endpoint. The number of entries is a compromise between the number of peers that can send a group message to a receiver while the table is maintained, and the associated memory usage.

There SHALL be at least 2 entries per supported fabric for Peer Encrypted Group Control Message Status in the Group Peer State table.

The next sections describe the functional protocol used to request message counter synchronization with a peer and form responses to such message counter synchronization requests.

 

4.16.3.  MCSP Messages

 

4.16.3.1.  MsgCounterSyncReq – Message Counter Synchronization Request

 

The Message Counter Synchronization Request (MsgCounterSyncReq) message is sent when a mes­ sage was received from a peer whose current message counter is unknown.

A MsgCounterSyncReq message SHALL set the C Flag in the message header. The control message counter SHALL be used for message protection.

 

A MsgCounterSyncReq message SHALL be secured with the group key for which counter synchro­ nization is requested and SHALL set the Session Type to 1, indicating a group session as per the rules outline in Section 4.16.5, “Message Counter Synchronization Exchange”.

 

The payload of the MsgCounterSyncReq message takes the format defined in Table 24, “Message Counter Sync Request”:

Table 24. Message Counter Sync Request

 

Field Size Message Field Description
8 bytes Challenge The Challenge is a 64-bit random number generated using the DRBG by the initiator of a MsgCounterSyncReq to uniquely identify the synchronization request crypto­ graphically.

 

4.16.3.2.  MsgCounterSyncRsp – Message Counter Synchronization Response

 

The Message Counter Synchronization Response (MsgCounterSyncRsp) message is sent in response to a MsgCounterSyncReq.

A MsgCounterSyncRsp message SHALL set the C Flag in the message header. The control message counter SHALL be used for message protection.

The MsgCounterSyncRsp message has the format defined in Table 25, “Message Counter Sync Response”:

Table 25. Message Counter Sync Response

 

Field Size Message Field Description
4 bytes Synchronized Counter The current data message counter for the node sending the MsgCounterSyncRsp message.
8 bytes Response The Response SHALL be the same as the 64-bit value sent in the Challenge field of the corresponding MsgCounter­ SyncReq.

 

 

4.16.4.  Unsynchronized Message Processing

 

An unsynchronized message is one that is cryptographically verified from a node whose message

 

counter is unknown. Upon receipt of an unsynchronized message process the message as follows:

 

  1. The message SHALL be of Group Session Type, otherwise discard the
  2. If C Flag is set to 1:
    1. Create a Message Reception State and set its max_message_counter to the message counter of the given message, i.e. trust-first.
    2. Accept the message for further
  3. If C Flag is set to 0:
    1. Determine the GroupKeySecurityPolicy (as set by the Section 11.2, “Group Key Management Cluster”) of the operational group key used to authenticate the
    2. If the key has a trust-first security policy, the receiver SHALL:
      1. Set the peer’s group key data message counter to Message Counter of the
        1. Clear the Message Reception State bitmap for the group session from the
        2. Mark the peer ‘s group key data message counter as
      2. Process the
    3. If the key has a cache-and-sync security policy, the receiver SHALL:
      1. If MCSP is not in progress for the given peer Node ID and group key:
        1. Store the message for later
        2. Proceed to Section 4.16.5, “Message Counter Synchronization Exchange”.
      2. Otherwise, do not process the
        1. An implementation MAY queue the message for later processing after MCSP com­ pletes if resources

For each peer Node ID and group key pair there SHALL be at most one synchronization exchange outstanding at a time.

 

4.16.5.  Message Counter Synchronization Exchange

 

A message synchronization exchange starts by sending the MsgCounterSyncReq message to the peer Node that sent the message with unknown message counter. When a synchronization request is triggered by an incoming multicast message, the Node SHALL first wait for a uniformly random

amount of time between 0 and MSG_COUNTER_SYNC_REQ_JITTER.

The sender of the MsgCounterSyncReq message SHALL:

 

  1. Set the Message Header fields as follows:
    1. The S Flag SHALL be set to 1.
    2. The DSIZ field SHALL be set to 1.
    3. The P Flag SHALL be set to 1.
    4. The C Flag SHALL be set to 1.
    5. The Session Type field SHALL be set to 1.

 

  1. The Session ID field SHALL be set to the Group Session Id for the operational group key being
  2. The Source Node ID field SHALL be set to the Node ID of the sender
  3. The Destination Node ID field SHALL be set to the Source Node ID of the message that trig­ gered the synchronization
  1. Create a new synchronization Exchange.
    1. The Exchange ID of the message SHALL be set to match the new
    2. The I Flag SHALL be set to 1.
    3. The A Flag SHALL be set to 0.
    4. The R Flag SHALL be set to 1.
  2. Set the Challenge field to the value returned by Crypto_DRBG(len = 8 * 8) and store that value to resolve synchronization responses from the destination
  3. Arm a timer to enforce that a synchronization response is received before MSG_COUNTER_­ SYNC_TIMEOUT.
    1. Upon firing of the timer:
      1. The synchronization exchange SHALL be
      2. Any message waiting on synchronization associated with the exchange SHALL be dis­ carded.
    2. The timer SHALL be stopped upon receipt of an authenticated MsgCounterSyncRsp message that matches:
      1. The Source Node ID field matches the Destination Node ID field of the most recent Msg­ CounterSyncReq message generated for that
      2. The Response field corresponds to the Challenge field of the MsgCounterSyncReq mes­ sage.
    3. Invoke Section 4.6.1, “Message Transmission” using parameters from step 1 to encrypt and then send the request message over UDP to the IPv6 unicast address of the
      1. The request message SHALL use the same operational group key as the message which trig­ gered
      2. The group key SHALL be known/derivable by both parties (sender and receiver).

 

The receiver of MsgCounterSyncReq SHALL:

 

  1. Verify the Destination Node ID field SHALL match the Node ID of the receiver, otherwise discard the
  2. Respond with MsgCounterSyncRsp.

 

The sender of the MsgCounterSyncRsp response message SHALL:

 

  1. Set the Message Header fields as follows:
    1. The S Flag SHALL be set to 1.
    2. The DSIZ field SHALL be set to 1.

 

  1. The P Flag SHALL be set to 1.
  2. The C Flag SHALL be set to 1.
  3. The Session Type field SHALL be set to 1.
  4. The Session ID field SHALL be set to the Group Session Id for the operational group key being
  5. The Source Node ID field SHALL be set to the Node ID of the sender
  6. The Destination Node ID field SHALL be set to the Source Node ID of the MsgCounterSyn­ cReq.
  1. Set the MsgCounterSyncRsp payload fields as follows:
    1. The Response field SHALL be set to the value of the Challenge field from the MsgCounterSyn­ cReq.
    2. The Synchronized Counter field SHALL be set to the current Global Group Encrypted Data Message Counter of the
  2. Use the same exchange context as the MsgCounterSyncReq being responded
    1. The Exchange ID of the message SHALL be set to the Exchange ID of the MsgCounterSyncReq.
    2. The I Flag SHALL be set to 0.
    3. The A Flag SHALL be set to 1.
    4. The R Flag SHALL be set to 1.
  3. Invoke Section 4.6.1, “Message Transmission” using parameters from step 1 to encrypt and then send the response message over UDP to the IPv6 unicast address of the

The receiver of the MsgCounterSyncRsp message SHALL:

 

  1. Verify the MsgCounterSyncRsp matches a previously sent MsgCounterSyncReq:
    1. An active synchronization exchange SHALL exist with the source
    2. The Exchange ID field SHALL match the Exchange ID used for the original MsgCounterSyn­ cReq
    3. The Response field SHALL match the Challenge field used for the original MsgCounterSyn­ cReq
    4. The Destination Node ID field SHALL match the Source Node ID of the original MsgCounter­ SyncReq
    5. The Source Node ID field SHALL match the Destination Node ID of the original MsgCounter­ SyncReq
  2. On verification failure:
    1. Silently ignore the MsgCounterSyncRsp
  3. On verification success:
    1. Set the peer’s group key data message counter to Synchronized Counter.
    2. Clear the Section 5.4.1, “Message Reception State” bitmap for the peer.
    3. Mark the peer ‘s group key data message counter as

 

  1. Resume processing of any queued message that triggered synchronization according to Sec­ tion 4.5.6, “Counter Processing of Incoming Messages”.
    1. If more than one message is queued from the synchronized peer, using the same opera­ tional group key, the messages SHALL be processed in the order
  2. Close the synchronization exchange created for the original MsgCounterSyncReq

 

4.16.6.  Message Counter Synchronization Session Context

 

While conducting Message Counter Synchronization with a peer, nodes SHALL maintain the follow­ ing session context. For nodes initiating message counter synchronization, this context SHALL be maintained throughout the full exchange of MsgCounterSyncReq and MsgCounterSyncRsp messages. For nodes responding to MsgCounterSyncReq messages, the context SHALL only be maintained long enough to generate and successfully transmit the MsgCounterSyncRsp message.

  1. Fabric Index: Records the Index for the Fabric within which nodes are conducting message counter
    • Fabric Index is derived by identification of an Operational Group Key associated with the fabric through successful decryption with that key and verification of the Message Integrity Check. For nodes initiating counter synchronization, this occurs at decryption of an inbound groupcast message. For nodes in the responder role, this occurs at decryption of an inbound MsgCounterSyncReq
  2. Peer Node ID: Records the node ID of the peer with which message counter synchronization is being
    • For nodes initiating message counter synchronization, this is the node ID of the responder. For nodes responding to message counter synchronization, this is the node ID of the initia­ tor.
  3. Role: Records whether the node is the initiator of or responder to message counter synchroniza­ tion.
    • Together, Fabric Index, Peer Node ID and Role comprise a unique key that can be used to match incoming messages to ongoing MCSP
  4. Message Reception State: Provides tracking for the Control Message Counter of the remote
  5. Peer IP Address: The unicast IP address of the
  6. Peer Port: The receiving port of the
  7. Operational Group Key: The Operational Group Key that is being used to encrypt messages within the counter synchronization
  8. Group Session ID: Records the Group Session ID derived from the Operational Group Key that is being used to encrypt messages within the counter synchronization

 

4.16.7.  Sequence Diagram

 

The following sequence diagram shows an example of how message counter synchronization behaves in the most common scenario.

 

4.16.7.1.  Scenario 1 — Multicast Receiver Initiated

 

Assumptions:

 

  • Sender transmits a multicast
  • Receiver does not know Sender ‘s message
 
   

Figure 21. Multicast Receiver Initiated Message Counter Synchronization

 

Sequence:

 

  • Sender:
    • Generates, encrypts and sends Msg1 as a multicast message. Msg1 could be:
      • Regular message that starts encrypted group communication with receivers Receiver1

and Receiver2.

 

  • Receivers Receiver1 and Receiver2 each:
  • Receive, decrypt, authenticate, and cache Msg1 message for later
    • Generate, encrypt, and send MsgCounterSyncReq
      • Sender:
    • Receives MsgCounterSyncReq
    • Generates, encrypts and sends MsgCounterSyncRsp
      • R1 and R2 each:
    • Receive, decrypt, process, and verify MsgCounterSyncRsp message from Sender.
    • On verification success: marks Sender ‘s group key message counter as
      • Processes cached Msg1

 

 

 

4.17.   Bluetooth Transport Protocol (BTP)

 

The Bluetooth Transport Protocol (BTP) provides a TCP-like layer of reliable, connection-oriented data transfer on top of GATT. BTP splits individual Service Data Unit (SDU) messages into multiple BTP segments, which are each transmitted via a single GATT write or indication (as shown in Figure 22, “MATTERoBLE: Matter Message / BTP layering”).

While BTP is a generic protocol, Matter specifically uses BTP to define a Matter-over-Bluetooth Low Energy (MATTERoBLE) Interface. A MATTERoBLE Interface MUST implement BTP as a universally compatible transport mode. A MATTERoBLE Interface SHALL only be used to transport Matter mes­ sages as the BTP SDU.

 
   

Figure 22. MATTERoBLE: Matter Message / BTP layering

 

The BTP session handshake allows devices to check BTP protocol version compatibility and exchange other data before a BTP session is established. Once established, this session is used to send and receive BTP SDUs (such as Matter messages) as BTP Message Segments. A BTP session MAY open and close with no effect on the state of the underlying Bluetooth LE connection, except in the case where a BTP session is closed by the Peripheral Device. Either the Peripheral or the Central MAY signal the end of a BTP session by closing the underlying BLE connection.

 

Due chiefly to constraints put on design by resource-limited BLE chipsets, BTP defines a receive window for each side of a session in units of GATT PDUs. Each GATT Write Characteristic Value (ATT_WRITE_REQ) PDU or Indication (ATT_HANDLE_VALUE_IND) PDU is sent with a sequence num­ ber which the receiver uses to acknowledge receipt of each packet at the BTP layer and open its receive window from the sender’s perspective.

 

4.17.1.  BTP Session Interface

 

Conceptually, an open BTP session is exposed to the next-higher session layer as a full-duplex mes­ sage stream.

 

4.17.2.  BTP Frame Formats

 

A BTP Frame consists of an 8-bit header followed by one or more optional fields, as detailed below. BTP uses little endian encoding for any header fields larger than one byte in length.

 

4.17.2.1.  BTP Packet Protocol Data Unit

 

Table 26, “BTP Packet PDU format” defines the BTP Packet PDU format. Unused fields SHALL be set to ‘0’.

Table 26. BTP Packet PDU format

 

 

bit 0

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
H M A E B [Management Opcode]
[Ack Number] [Sequence Number]
[Message Length]
[Segment Payload]…

 

H (Handshake) bit

 

Set to ‘0’ for normal BTP packets. When set, this bit indicates a BTP handshake packet for session establishment and has a different packet format described below.

 

M (Management Message) bit

 

Indicates the presence (‘1’) or absence (‘0’) of the Management Opcode field. All segments of a mes­ sage MUST set this bit to the same value.

 

A (Acknowledgement) bit

 

Indicates the presence of the Ack Number field.

 

B (Beginning Segment) bit

 

Set to ‘1’ on the first segment of a BTP SDU and set to ‘0’ for all remaining segments of the same BTP SDU. It indicates the presence of the Message Length field.

 

E (Ending Segment) bit

 

Set to ‘1’ on the last segment of a BTP SDU and set to ‘0’ for all other segments of the same BTP SDU. A segment MAY have both the Beginning and Ending bits set indicating that a full BTP SDU is included in the message. When set, the segment payload length is equal to the total remaining unre­ ceived message data. When not set, the segment payload length is equal to the maximum allowable BTP session packet size minus header overhead.

 

Ack Number

 

Optional field specified in Section 4.17.3.8, “Packet Acknowledgements”.

 

Sequence Number

 

Mandatory field for regular data messages specified in Section 4.17.3.6, “Sequence Numbers”.

 

Message Length

 

Optional field present in Beginning Segment only. Value indicates the length in bytes of the full mes­ sage buffer to be transmitted. None of the BTP Packet PDU fields is included in the Message Length.

 

Segment Payload

 

Optional field containing a segment of the Service Data Unit (SDU) message in transmission to the receiver.

 

4.17.2.2.  BTP Control Frames

 

BTP defines different control frame formats depending on the Management Opcode that is in the BTP Packet PDU header. Valid Management Opcodes for BTP Control Frames are defined in Table 27, “BTP Control codes”.

Table 27. BTP Control codes

 

Management Opcode Name Description
0x6C Handshake Request and response for BTP session establishment

 

4.17.2.3.  BTP Handshake Request

 

Table 28. BTP Handshake Request format

 

 

bit 0

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
0 H=1 M=1 0 A=0 E=1 0 B=1 Management Opcode = 0x6C
Ver[1] Ver[0] Ver[3] Ver[2]
Ver[5] Ver[4] Ver[7] Ver[6]
Requested ATT_MTU
Client Window Size  

 

H (Handshake) bit

 

Set to ‘1’ for connection handshake messages.

 

M (Management) bit

 

Set to ‘1’ for connection handshake messages.

 

Ver[i] (Version) nibbles

 

Used to negotiate the highest version capability between a Device pair. Supported versions are listed once each, newest first, in descending order. Unused version fields are filled with ‘0’.

The following values are defined:

 

  • 0 — Unused field
  • 4 — BTP as defined by Matter 0

 

Requested ATT_MTU

 

Requested ATT_MTU is a 16-bit unsigned integer field containing the size of the GATT PDU (ATT_MTU) that can be received by the sender minus the size of the GATT header (3). This value is obtained via the standard ATT MTU exchange procedure (see Bluetooth® Core Specification 4.2 Vol 3, Part F, Section 3.4.2 “MTU Exchange”) and is used to validate that both sides of the BLE connec­ tion are using the common minimum value. If BTP is not aware of the negotiated GATT MTU, the value shall be set to ’23’, indicating the minimum ATT_MTU defined by GATT. If the client has no preference, the value may be set to ‘0’.

 

NOTE         Each GATT PDU used by the BTP protocol introduces 3 byte header overhead mak­ ing the maximum BTP Segment Size for the session equal to negotiated ATT_MTU-3.

 

Client Window Size

 

Value of the maximum receive window size supported by the server, specified in units of BTP pack­ ets where each packet may be up to 244 bytes in length. This maximum was chosen so a single BTP segment can fit into a single 255 byte BLE link layer PDU, including all headers from the link layer, L2CAP, GATT, and BTP.

 

4.17.2.4.  BTP Handshake Response

 

Table 29. BTP Handshake Response format

 

 

bit 0

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
0 H=1 M=1 0 A=0 E=1 0 B=1 Management Opcode = 0x6C
Reserved Final Protocol Version Selected ATT_MTU (low byte)…
…Selected ATT_MTU (high byte) Selected Window Size

 

H (Handshake) bit

 

Set to ‘1’ for session handshake messages.

 

M (Management) bit

 

Set to ‘1’ for session handshake messages.

 

Reserved

 

Must be set to ‘0’.

 

Final Protocol Version

 

Value of the BTP protocol version selected by the server.

 

Selected ATT_MTU

 

Value of the maximum ATT_MTU for the connection selected by the server as a 16-bit unsigned inte­ ger.

 

Selected Window Size

 

Value of the maximum receive window size supported by the server, specified in units of BTP pack­ ets where each packet may be up to the selected segment size in length.

 

4.17.3.  BTP GATT Service

 

4.17.3.1.  BTP Channelization

 

Bluetooth Transport Protocol provides a packetized stream interface over GATT but says nothing about the actual contents of the data packets it transports. The BTP Service UUID is used to specify the actual contents of the packets (see Table 30, “BTP Service UUID”).

Table 30. BTP Service UUID

 

BTP Datagram Contents BTP Service UUID
Matter Message frames

MATTER_BLE_SERVICE_UUID

Note: See Section 4.17.5, “Bluetooth SIG Consid­ erations” for terms of use.

 

While a single BTP connection may exist between a BTP Client and BTP Server, multiple BTP ses­ sions may be established between various peers.

 

4.17.3.2.  BTP GATT Service

 

The BTP GATT service is composed of a service with three characteristics—C1, C2 and C3 (see Table 31, “BTP GATT service”). The client SHALL exclusively use C1 to initiate BTP sessions by sending BTP handshake requests and send data to the server via GATT ATT_WRITE_CMD PDUs. While a client is subscribed to allow indications over C2, the server SHALL exclusively use C2 to respond to BTP handshake requests and send data to the client via GATT ATT_HANDLE_VALUE_IND PDUs.

Table 31. BTP GATT service

 

 

Attribute Description
BTP Service UUID = MATTER_BLE_SERVICE_UUID
C1 Characteristic (Client TX Buffer)

UUID = 18EE2EF5-263D-4559-959F-4F9C429F9D11

Characteristic Properties = Write max length = 247 bytes

C2 Characteristic (Client RX Buffer)

UUID = 18EE2EF5-263D-4559-959F-4F9C429F9D12

Characteristic Properties = Indication max length = 247 bytes

C3 Characteristic

(Additional commissioning- related data)

UUID = 64630238-8772-45F2-B87D-748A83218F04

Characteristic Properties = Read max length = 512 bytes

 

For all messages sent from the BTP Client to BTP Server, BTP SHALL use the GATT Write Character­ istic Value sub-procedure. For all messages sent from the BTP Server to BTP Client, BTP SHALL use the GATT Indications sub-procedure.

The values of C1 and C2 SHALL both be limited to a maximum length of 247 bytes. This constraint is imposed to align with maximum PDU size when LE Data Packet Length Extensions (DPLE) is enabled on Bluetooth 4.2 hardware. Per Bluetooth® Core Specification 4.2 Vol 3, Part F, Section 3.2.9 “Long Attribute Values”, the maximum characteristic value length is 512 bytes. The maximum lengths of C1 and C2 may increase in a future version of the BTP specification to allow higher throughput on BLE connections whose ATT_MTU exceeds 247 bytes.

C3 is an optional characteristic that the server MAY use to include additional data required during the provisioning as defined in Section 5.4.2.5.7, “GATT-based Additional Data”.

BTP Clients SHALL perform certain GATT operations synchronously, including GATT discovery, sub­ scribe, and unsubscribe operations. GATT discovery, subscribe, or unsubscribe SHALL NOT be initi­ ated while the result of a previous operation remains outstanding. This requirement is imposed by GATT protocol.

 

4.17.3.3.  Session Establishment

 

Before a BTP session can be initiated, a central SHALL first establish a BLE connection to a periph­ eral. Once a BLE connection has been formed, centrals SHALL assume the GATT client role for BTP session establishment and data transfer, and peripherals SHALL assume the GATT server role. If peripheral supports LE Data Packet Length Extension (DPLE) feature it SHOULD perform data length update procedure before establishing a GATT connection.

Before establishing a BTP session, the GATT client SHOULD perform a GATT Exchange MTU proce­ dure.

After that the BTP Client SHALL execute the GATT discovery procedure. The GATT discovery proce­ dure starts with primary service discovery using either the GATT Discover All Primary Services sub- procedure or the GATT Discover Primary Services by Service UUID sub-procedure.

The BTP Client SHALL perform either the GATT Discover All Characteristics of a Service sub-proce­ dure or the GATT Discover Characteristics by UUID sub-procedure in order to discover the C1 and

 

C2 characteristics.

 

The BTP Client SHALL perform the GATT Discover All Characteristic Descriptors sub-procedure in order to discover the Client Characteristic Configuration descriptor (CCCD) of C2 characteristic.

To initiate a BTP session, a BTP Client SHALL send a BTP handshake request packet to the BTP Server via a ATT_WRITE_CMD PDU on characteristic C1 of the BTP Service. The handshake request packet SHALL include, a list of BTP protocol versions supported by the client, the client’s GATT ATT_MTU, and the client’s maximum receive window size. The list of supported protocol versions SHALL be sorted in descending numerical order. If the client cannot determine the BLE connec­ tion’s ATT_MTU, it SHALL specify a value of ’23’ (the minimum ATT_MTU supported by GATT) for this field in the handshake request. For a detailed specification of the handshake request binary data format, see Section 4.17.2.3, “BTP Handshake Request”.

After the BTP Client acknowledges delivery of the handshake request packet, upon receipt of a GATT Write Response, the BTP Client SHALL enable indications over C2 characteristics by writing value 0x01 to C2’s Client Characteristic Configuration descriptor as described in Bluetooth® Core Specification 4.2 Vol 3, Part C, Section 10.3.1.1 “Handling GATT Indications and Notifications”.

Once the GATT server has received a client’s BTP handshake request and confirmed the client’s sub­ scription to C2, it SHALL send a BTP handshake response to the client via a ATT_HANDLE_VAL­ UE_IND PDU on C2. This response SHALL contain the window size, maximum BTP packet size, and BTP protocol version selected by the server. For a detailed specification of the handshake response binary data format, see Section 4.17.2.4, “BTP Handshake Response”.

The server SHALL select a window size equal to the minimum of its and the client’s maximum win­ dow sizes. Likewise, the server SHALL select a maximum BTP Segment Size for the BLE connection by taking the minimum of 244 bytes (the maximum characteristic value length of C1 and C2), server’s ATT_MTU-3 and ATT_MTU-3 as declared by the client.

The server SHALL select a BTP protocol version that is the newest which it and the client both sup­ port, where newer protocol version numbers are strictly larger than those of older versions. The version number returned in the handshake response SHALL determine the version of the BTP pro­ tocol used by client and server for the duration of the session.

If the server determines that it and the client do not share a supported BTP protocol version, the server SHALL close its BLE connection to the client. When a client sends a handshake request, it SHALL start a timer with a globally-defined duration of BTP_CONN_RSP_TIMEOUT seconds. If this timer expires before the client receives a handshake response from the server, the client SHALL close the BTP session and report an error to the application. Likewise, a server SHALL start a timer with the same duration when it receives a handshake request from a client. If this timer expires before the server receives a subscription request on C2, the server SHALL close the BTP session and report an error to the application. The state machine in Figure 23, “BTP session handshake” illus­ trates the function of these timers as part of the BTP session establishment procedure.

 

 

Figure 23. BTP session handshake

 

4.17.3.4.  Data Transmission

 

Once a BTP session has been established, the next-higher-layer application on both peers may use this BLE connection to send and receive data via GATT writes or indications, according to a peer’s GATT role. Clients SHALL exclusively use GATT Write Characteristic Value sub-procedure to send data to servers and servers SHALL exclusively use GATT Indication sub-procedure to send data to clients.

All BTP packets sent on an open BLE connection SHALL adhere to the BTP Packet PDU binary data format specified in BTP Frame Formats. All BTP packets SHALL include a header flags byte and an 8-bit unsigned sequence number. All other packet fields are optional. These optional fields include an 8-bit unsigned received packet acknowledgement number, 16-bit unsigned buffer length indica­ tion, and variable-length buffer segment payload.

This section is defined entirely within the scope of a single BTP session. Concurrent BTP sessions between the same peer and multiple remote hosts SHALL maintain separate and independent acknowledgement timers, sequence numbers, and receive windows.

 

4.17.3.5.  Message Segmentation and Reassembly

 

When the session layer (that is, MATTERoBLE) sends a Matter Message as a BTP SDU over a BTP ses­ sion, that BTP SDU SHALL be split into ordered, non-overlapping BTP segments so the set of all BTP segments may be reassembled into the original BTP SDU (see Figure 22, “MATTERoBLE: Matter Mes­ sage / BTP layering”). Each BTP segment SHALL be prepended with a BTP packet header and sent as

 

the payload of a single GATT PDU. If a BTP SDU is split into more than one BTP segment, the BTP segments SHALL be sent in order of their position in the original BTP SDU, starting with the BTP segment at the buffer’s head.

At any point in time, only one BTP SDU may be transmitted in each direction over a BTP session. The transmission of BTP segments of any two BTP SDUs SHALL not overlap. If the application attempts to send one BTP SDU while transmission of another BTP SDU is in progress, the new BTP SDU SHALL be appended to a first-in, first-out queue. The next BTP SDU SHALL be dequeued from this queue and transmitted once transmission of the current BTP SDU completes, that is, once all BTP segments of the current BDP SDU have been transmitted and received by the peer via GATT.

The first BTP segment of a BTP SDU sent over a BTP session SHALL have its Beginning Segment header flag set to indicate the beginning of a new BTP SDU (see Table 26, “BTP Packet PDU format”). The presence of this flag SHALL indicate the further presence of a 16-bit unsigned integer field, the Message Length, that provides the receiver with the total length of the BTP SDU. The last BTP seg­ ment for a given BTP SDU SHALL have its Ending Segment flag set to indicate the end of the trans­ mitted BTP SDU. A BTP packet that bears an unsegmented BTP SDU—that is, a BTP SDU small enough to fit into a single BTP segment—SHALL have both its Beginning Segment and Ending Seg­ ment flags set.

The size of a single BTP SDU sent via BTP is limited to 64KB, that is, the maximum size of the Mes­ sage Length field in the BTP packet header. The number of segments used to send a buffer is unlim­ ited and delimited by the Beginning Segment and Ending Segment bits in the BTP packet header. The upper layer imposes more stringent requirements over the maximum SDU size, such as Section 4.4.4, “Message Size Requirements”.

The length of the data payload in each BTP segment whose Ending Segment bit is not set SHALL be equal to the session’s maximum BTP packet size minus the size of that packet’s header. If a packet’s Ending Segment bit is set, the length of its BTP segment data payload SHALL equal the size of the original BTP SDU minus the total size of all previously transmitted BTP segments of that BTP SDU. In this way, the length of a SDU’s last BTP segment is implied by its size.

Once a peer receives a complete set of BTP segments, it SHALL reassemble them in the order received, and verify that the reassembled BTP SDU’s total length matches that specified by the Beginning Segment’s Message Length value. If they match, the receiver SHALL pass the reassem­ bled BTP SDU up to the next-higher-layer. If the reassembled buffer’s length does not match that specified by the sender, or if received BTP segment payload size would exceed the maximum BTP packet size, or receiver receives an Ending Segment without the presence of a previous Beginning Segment, or a Beginning Segment when another BTP SDU’s transmission is already in progress, the receiver BTP SHALL close the BTP session and report an error to the application.

 

4.17.3.6.  Sequence Numbers

 

All BTP packets SHALL be sent with sequence numbers, regardless of whether they contain SDU segments (for example, a packet acknowledgement with no attached segment payload). The pur­ pose of sequence numbers is to facilitate the BTP receive window. A BTP sequence number SHALL be defined as an unsigned 8-bit integer value that monotonically increments by 1 with each packet sent by a given peer. A sequence number incremented past 255 SHALL wrap to zero.

 

Sequence numbers SHALL be separately defined for either direction of a BTP session. The sequence number of the first packet sent by the client after completion of the BTP session handshake SHALL be zero. The server’s BTP handshake response bears an implied sequence number of zero because it occupies a slot in the client’s receive window. The client acknowledges the server’s BTP hand­ shake response with an acknowledgement sequence of zero. For this reason, the sequence number of the first data packet sent by the server after completion of the BTP session handshake SHALL be 1.

Peers SHALL check to ensure that all received BTP packets properly increment the sender’s previ­ ous sequence number by 1. If this check fails, the peer SHALL close the BTP session and report an error to the application.

 

4.17.3.7.  Receive Windows

 

The purpose of the receive window is to enable flow control at the GATT session layer between BTP peers.

Flow control is required at the GATT transport layer for embedded platforms that use “minimal” BLE chipsets. These platforms may have limited space on the host processor to receive packets from their BLE chipsets. In the case of some dual-chip architectures, writes and indications are received and confirmed by the BLE chip with no input from the host processor. When the BLE chip sends the result of a received GATT PDU to the host processor, that payload and the corresponding BTP packet will be permanently lost if the host does not have enough space to receive it. For this reason, knowl­ edge of a remote host’s ability to reliably receive GATT PDUs is presented at the transport layer in the form of the BTP receive window.

Both peers in a BTP session SHALL define a receive window, where the window’s size indicates the number of GATT PDUs (that is, BTP segments) a peer can reliably receive and store without session- layer acknowledgment. A maximum window size SHALL be established for both peers as part of the BTP session handshake. To prevent sequence number wrap-around, the largest maximum win­ dow size any peer may support is 255.

Both peers SHALL maintain a counter to reflect the current size of the remote peer’s receive win­ dow. Each peer SHALL decrement this counter when it sends a packet via GATT write or indication and increment this counter when a sent packet is acknowledged.

If a local peer’s counter for a remote peer’s receive window is zero, the window SHALL be consid­ ered closed, and the local peer SHALL NOT send packets until the window reopens (is incremented above zero). When a closed window reopens, a local peer SHALL immediately resume any pending BTP packet transmission.

A local peer SHALL also not send packets if the remote peer’s receive window has one slot open and the local peer does not have a pending packet acknowledgement. This is to avoid the situation where the receive windows of both peers are full and neither can send an acknowledgement to reopen its window for the other. Because the server’s handshake response bears an implicit BTP sequence number of zero, a server SHALL initialize its counter for the client’s receive window size at (negotiated maximum window size – 1). A client SHALL initialize its counter for the server’s receive window at the negotiated maximum window size.

Both peers SHALL also keep a counter of their own receive window size based on the sequence

 

number difference between the last packet they received and the last packet they acknowledged. This counter is used to proactively send early packet acknowledgements when a peer’s own receive window is about to close. See Section 4.17.3.8, “Packet Acknowledgements” for details.

An example scenario involving BTP receive windows is depicted in Figure 24, “Example receive window scenario”, complete with packet acknowledgements as specified in Section 4.17.3.8, “Packet Acknowledgements”. In this scenario, the client transmits a three-segment buffer to the server once it receives the server’s handshake request. The handshake request occupies one slot in the client’s initial receive window. The server’s initial receive window is empty. Both client and server have a maximum window size of 4.

 
   

Figure 24. Example receive window scenario

 

4.17.3.8.  Packet Acknowledgements

 

The purpose of sequence numbers and packet receipt acknowledgements is to support the BTP receive window and provide a keep-alive signal when a session is idle to affirm the health and con­ tinued operation of a remote BTP stack.

Per BTP Frame Formats, BTP packet receipt acknowledgements SHALL be received as unsigned 8- bit integer values in the header of a BTP packet. The value of this field SHALL indicate the sequence number of the acknowledged packet.

Acknowledgement of a sequence number indicates acknowledgement of the previous sequence number, if it too is unacknowledged. By induction, acknowledgement of a given packet implies acknowledgement of all packets received on the same BTP session prior to the acknowledged packet.

 

An acknowledgement is invalid if the acknowledged sequence number does not correspond to an outstanding, unacknowledged BTP packet sequence number. In contrast to TCP, BTP acks are not “free.” A stand-alone ack—that is, a BTP packet that contains a packet receipt acknowledgement value but no buffer segment payload—consumes a slot in a remote peer’s window just like any other packet. Stand-alone acknowledgement packets SHALL be acknowledged by a remote peer. The implications of this are examined in Section 4.17.3.9, “Idle Connection State”.

Each peer SHALL maintain an acknowledgement-received timer. When a peer sends any BTP packet, it SHALL start this timer if it is not already running. The timer’s duration SHALL be globally defined as BTP_ACK_TIMEOUT seconds, referred to as the acknowledgement timeout interval.

A peer SHALL restart its acknowledgement-received timer when a valid acknowledgement is received for any but its most recently sent unacknowledged packet. A peer SHALL stop its acknowl­ edgement-received timer if it receives an acknowledgement for its most recently sent unacknowl­ edged packet. If a peer’s acknowledgement-received timer expires, or if a peer receives an invalid acknowledgement, the peer SHALL close the BTP session and report an error to the application.

Because the server’s handshake response bears an implicit BTP sequence number of zero, a server SHALL start its acknowledgement-received timer when it sends a handshake response.

Each peer SHALL also maintain a send-acknowledgement timer. When it receives any BTP packet, a peer SHALL record the packet’s sequence number as the corresponding BTP session’s pending acknowledgement value and start the send-acknowledgement timer if it is not already running. The timer’s duration timer SHALL be defined as any value less than one-half the acknowledgement timeout interval. This ensures that on a healthy BLE connection, a peer will always receive acknowledgements for sent packets before its acknowledgement-received timer expires.

A peer SHALL stop its send-acknowledgement timer when any pending acknowledgement is sent, either as a stand-alone BTP packet or piggybacked onto an outgoing buffer segment. If this timer expires and the peer has a pending acknowledgement, the peer SHALL immediately send that acknowledgement. If the peer sends any packet before this timer expires, it SHALL piggyback any pending acknowledgement on the transmitted packet and stop the send-acknowledgement timer.

Because the server’s handshake response bears an implicit BTP sequence number of zero, a client SHALL set its pending acknowledgement value to zero and start its send-acknowledgement timer when it receives the server’s a handshake response. Operation of the send-acknowledgement and acknowledgement-received timers is illustrated in Figure 26, “BTP session lifecycle for Central act­ ing as GATT Client” in Section 4.17.3.11, “Protocol State Diagrams”.

If a peer detects that its receive window has shrunk to two or fewer free slots, it SHALL immedi­ ately send any pending acknowledgement as a stand-alone BTP packet. This prevents the session from stalling in the interval between when a peer’s receive window becomes empty and when its send-acknowledgement timer would normally fire.

 

4.17.3.9.  Idle Connection State

 

When neither side of a BTP session has data to send, BTP packets will still be exchanged every send- acknowledgement interval due to acknowledgements generated by the receipt of previous data or stand-alone acknowledgement packets, as discussed in Section 4.17.3.8, “Packet Acknowledge­ ments”. The behavior of the acknowledgement-received timer in this scenario doubles as a keep-

 

alive mechanism, as it will cause a peer to close a BLE connection automatically if the remote BTP stack crashes or becomes unresponsive. This scenario is illustrated in Figure 25, “Idle connection scenario”.

 

 
   

 

Figure 25. Idle connection scenario

 

4.17.3.10.  Connection Shutdown

 

To close a BTP session, a GATT client SHALL unsubscribe from characteristic C2. The GATT server SHALL take this action to indicate closure of any BTP session open to the client.

If a BTP Server needs to close the BTP session, it SHALL terminate its BLE connection to the client.

 

4.17.3.11.  Protocol State Diagrams

 

Figure 26, “BTP session lifecycle for Central acting as GATT Client” shows the state machine for BTP session management of a BTP Client Device.

 

 

Figure 26. BTP session lifecycle for Central acting as GATT Client

 

Figure 27, “BTP session lifecycle for Peripheral acting as GATT Server” shows the state machine for BTP session management of a BTP Server Device.

 

 

 

Figure 27. BTP session lifecycle for Peripheral acting as GATT Server

 

Note that in Figure 27, “BTP session lifecycle for Peripheral acting as GATT Server”, the state machine is identical for GATT clients and servers with the distinction that clients send data to servers via confirmed writes, and servers send data to clients via indications.

Figure 28, “State diagram for BTP session post-establishment” shows the state machine for BTP ses­ sion maintenance at the protocol level, including liveliness enforcement through keep alive mes­ sages and automatic teardown if acknowledgements are received before the timeout.

 

 

Figure 28. State diagram for BTP session post-establishment

 

4.17.4.  Parameters and Constants

 

Table 32, “Glossary of constants” is a glossary of constants used in this chapter, along with a brief description and the default for each constant.

Table 32. Glossary of constants

 

 

Constant Name Description Default
BTP_CONN_RSP_TIMEOUT The maximum amount of time after sending a BTP Session Handshake request to wait for a BTP Session Handshake response before closing the con­ nection. 5 seconds
BTP_ACK_TIMEOUT The maximum amount of time after receipt of a segment before a stand-alone ACK must be sent. 15 seconds
BTP_CONN_IDLE_TIMEOUT The maximum amount of time no unique data has been sent over a BTP session before the Central Device must close the BTP session. 30 seconds

 

4.17.5.  Bluetooth SIG Considerations

 

The UUID is provided by Bluetooth SIG, Inc. and may only be used by its members in compliance with all terms and conditions of use issued by the Bluetooth SIG, Inc. For more information, visit https://www.bluetooth.com/specifications/assigned-numbers/16-bit-uuids-for-sdos.

Use of the Bluetooth extensions feature of this specification and specifically the MATTER_BLE_SER­ VICE_UUID is strictly prohibited unless the product is certified by both the Bluetooth SIG and the Connectivity Standards Alliance by a member of good standing of both organizations.

Table 33. SIG UUID assignment

 

Constant Name Description Value
MATTER_BLE_SERVICE_UUID The UUID for the Matter-over- BLE service as assigned by the Bluetooth SIG. 0xFFF6

 

 

 

 

 

 

 

Adsense

 

 WiFi IoT Module

 

www.mxchip.com

 

 

 Bluetooth Module

www.feasycom.com

 

 

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

 

www.simcom.com

 

Viewed Page List