matter_msg.h
Matter message header and protocol (exchange) header.
Overview
Matter message header and protocol (exchange) header. Two headers, one wire format. The message header is the part that travels in clear even on a secure session; the protocol header sits at the front of the (decrypted) payload and names the exchange the message belongs to. message header flags:u8 session_id:u16 security_flags:u8 counter:u32 [source_node_id:u64 if S] [dest:u64|u16 by DSIZ] protocol header exchange_flags:u8 opcode:u8 exchange_id:u16 [vendor_id:u16 if V] protocol_id:u16 [ack_counter:u32 if A] All little-endian.
depends on matter_status.h · used by matter_crypto.h matter_exchange.h matter_msg.c
API
Cstruct matter_msg_header
Matter message header decoded from the wire: flags, session ID, security flags, message counter, optional source/destination node ID (unicast) or group ID (multicast).
Cstruct matter_proto_header
Matter protocol/exchange header decoded from the message body: exchange flags, opcode, exchange ID, optional vendor ID, protocol ID, and optional ACK counter.
Cstruct matter_counter
RX/TX counter state: the last value used and the counter kind (unsecured or session).
##define MATTER_MSG_FLAG_S 0x04u
Source node ID present.
##define MATTER_MSG_DSIZ_MASK 0x03u
Destination size, low two bits.
##define MATTER_MSG_DSIZ_NONE 0x00u
##define MATTER_MSG_DSIZ_NODE 0x01u
##define MATTER_MSG_DSIZ_GROUP 0x02u
##define MATTER_MSG_DSIZ_RESERVED 0x03u
DSIZ 3 is reserved and must be refused rather than ignored.
##define MATTER_MSG_VERSION_MASK 0xF0u
Version lives in the top nibble and must be 0 (MessageHeader.h:118-124,502).
##define MATTER_SEC_FLAG_P 0x80u
##define MATTER_SEC_FLAG_C 0x40u
##define MATTER_SEC_FLAG_MX 0x20u
##define MATTER_SEC_SESSION_TYPE_MASK 0x03u
Session type, low two bits; only unicast and group are assigned.
##define MATTER_SESSION_TYPE_UNICAST 0x00u
##define MATTER_SESSION_TYPE_GROUP 0x01u
##define MATTER_EX_FLAG_I 0x01u
##define MATTER_EX_FLAG_A 0x02u
##define MATTER_EX_FLAG_R 0x04u
##define MATTER_EX_FLAG_SX 0x08u
##define MATTER_EX_FLAG_V 0x10u
##define MATTER_MSG_HEADER_MIN 8u
Fixed part, before any optional field.
##define MATTER_PROTO_HEADER_MIN 6u
##define MATTER_MSG_HEADER_MAX 24u
Both headers at their largest: 8 + 8 + 8, and 4 + 2 + 2 + 4.
##define MATTER_PROTO_HEADER_MAX 12u
Fbool matter_msg_is_secure(const struct matter_msg_header *h)
True when the session is secured, i.e. not the unsecured unicast session 0.
Fint matter_msg_header_decode(const uint8_t *buf, size_t len, struct matter_msg_header *h, size_t *consumed)
@param consumed receives the header length, which is where the payload starts. @return MATTER_OK, MATTER_E_TRUNC if the buffer ends inside the header, or MATTER_E_INVAL for a non-zero version or the reserved DSIZ.
Fint matter_msg_header_encode(const struct matter_msg_header *h, uint8_t *buf, size_t cap, size_t *written)
Fint matter_proto_header_decode(const uint8_t *buf, size_t len, struct matter_proto_header *h, size_t *consumed)
Fint matter_proto_header_encode(const struct matter_proto_header *h, uint8_t *buf, size_t cap, size_t *written)
##define MATTER_COUNTER_INIT_MASK 0x0FFFFFFFu
28-bit mask on the seed (MessageCounter.h:42; CircuitMatter session.py:364).
Cenum matter_counter_kind
Fvoid matter_counter_init(struct matter_counter *c, uint32_t entropy, enum matter_counter_kind kind)
@param entropy a random word; only its low 28 bits are used. Supplied by the caller rather than drawn here, so this layer needs no RNG seam and the host tests need no fake for one.
Fint matter_counter_next(struct matter_counter *c, uint32_t *out)
Advance and return the next counter to send. @return MATTER_OK, or MATTER_E_STATE when a secure session's counter is spent.