circuitmatter.session

Attributes

`MSG_COUNTER_WINDOW_SIZE`
`MSG_COUNTER_SYNC_REQ_JITTER_MS`
`MSG_COUNTER_SYNC_TIMEOUT_MS`

Classes

`SessionParameterStruct`
`GeneralCode`	Enum where members are also (and must be) ints
`SecureChannelProtocolCode`	Enum where members are also (and must be) ints
`StatusReport`
`SessionContext`
`UnsecuredSessionContext`
`SecureSessionContext`
`MessageReceptionState`
`MessageCounter`
`SessionManager`

Module Contents

circuitmatter.session.MSG_COUNTER_WINDOW_SIZE = 32

circuitmatter.session.MSG_COUNTER_SYNC_REQ_JITTER_MS = 500

circuitmatter.session.MSG_COUNTER_SYNC_TIMEOUT_MS = 400

class circuitmatter.session.SessionParameterStruct

Bases: circuitmatter.tlv.Structure

session_idle_interval

session_active_interval

session_active_threshold

data_model_revision

interaction_model_revision

specification_version

max_paths_per_invoke

__str__()

encode() → memoryview

encode_into(buffer: bytearray, offset: int = 0) → int

classmethod decode(buffer: memoryview, offset=0) → Structure

classmethod decode_member(control_octet, buffer, offset=0, depth=0) → tuple[dict, int]

construct_containers()

classmethod from_value(value)

values

classmethod max_length()

set_value(tag, value)

delete_value(tag)

class circuitmatter.session.GeneralCode

Bases: enum.IntEnum

Enum where members are also (and must be) ints

SUCCESS = 0: Operation completed successfully.

FAILURE = 1: Generic failure, additional details may be included in the protocol specific status.

BAD_PRECONDITION = 2: Operation was rejected by the system because the system is in an invalid state.

OUT_OF_RANGE = 3: A value was out of a required range

BAD_REQUEST = 4: A request was unrecognized or malformed

UNSUPPORTED = 5: An unrecognized or unsupported request was received

UNEXPECTED = 6: A request was not expected at this time

RESOURCE_EXHAUSTED = 7: Insufficient resources to process the given request

BUSY = 8: Device is busy and cannot handle this request at this time

TIMEOUT = 9: A timeout occurred

CONTINUE = 10: Context-specific signal to proceed

ABORTED = 11: Failure, may be due to a concurrency error.

INVALID_ARGUMENT = 12: An invalid/unsupported argument was provided

NOT_FOUND = 13: Some requested entity was not found

ALREADY_EXISTS = 14: The sender attempted to create something that already exists

PERMISSION_DENIED = 15: The sender does not have sufficient permissions to execute the requested operations.

DATA_LOSS = 16: Unrecoverable data loss or corruption has occurred.

MESSAGE_TOO_LARGE = 17: Message size is larger than the recipient can handle.

class circuitmatter.session.SecureChannelProtocolCode

Bases: enum.IntEnum

Enum where members are also (and must be) ints

SESSION_ESTABLISHMENT_SUCCESS = 0: Indication that the last session establishment message was successfully processed.

NO_SHARED_TRUST_ROOTS = 1: Failure to find a common set of shared roots.

INVALID_PARAMETER = 2: Generic failure during session establishment.

CLOSE_SESSION = 3: Indication that the sender will close the current session.

BUSY = 4: Indication that the sender cannot currently fulfill the request.

class circuitmatter.session.StatusReport

PROTOCOL_ID

PROTOCOL_OPCODE

clear()

__len__()

encode_into(buffer, offset=0) → int

decode(buffer)

__str__()

class circuitmatter.session.SessionContext(socket)

socket

responder_exchanges

initiator_exchanges

active_timestamp = None: A timestamp indicating the time at which the last message was received. This timestamp SHALL be initialized with the time the session was created.

session_idle_interval = 0.5

session_active_interval = 0.3

session_active_threshold = 4

property peer_active

receive(message)

class circuitmatter.session.UnsecuredSessionContext(socket, message_counter, initiator, ephemeral_initiator_node_id, node_ipaddress)

Bases: SessionContext

initiator

ephemeral_initiator_node_id

message_reception_state = None

message_counter

local_node_id = 0

node_ipaddress

send(message)

socket

responder_exchanges

initiator_exchanges

active_timestamp = None: A timestamp indicating the time at which the last message was received. This timestamp SHALL be initialized with the time the session was created.

session_idle_interval = 0.5

session_active_interval = 0.3

session_active_threshold = 4

property peer_active

receive(message)

class circuitmatter.session.SecureSessionContext(random_source, socket, local_session_id)

Bases: SessionContext

session_type = None: Records whether the session was established using CASE or PASE.

session_role_initiator = False: Records whether the node is the session initiator or responder.

local_session_id: Individually selected by each participant in secure unicast communication during session establishment and used as a unique identifier to recover encryption keys, authenticate incoming messages and associate them to existing sessions.

peer_session_id = None: Assigned by the peer during session establishment

i2r_key = None: Encrypts data in messages sent from the initiator of session establishment to the responder.

r2i_key = None: Encrypts data in messages sent from the session establishment responder to the initiator.

shared_secret = None: Computed during the CASE protocol execution and re-used when CASE session resumption is implemented.

local_message_counter: Secure Session Message Counter for outbound messages.

message_reception_state = None: Provides tracking for the Secure Session Message Counter of the remote

local_fabric_index = None: 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 applies.

peer_node_id = 0: Records the authenticated node ID of the remote peer, when available.

resumption_id = None: The ID used when resuming a session between the local and remote peer.

session_timestamp = None: 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.

subscriptions

local_node_id = 0

socket

node_ipaddress = None

__str__()

property next_exchange_id

decrypt_and_verify(message)

send(message)

responder_exchanges

initiator_exchanges

active_timestamp = None: A timestamp indicating the time at which the last message was received. This timestamp SHALL be initialized with the time the session was created.

session_idle_interval = 0.5

session_active_interval = 0.3

session_active_threshold = 4

property peer_active

receive(message)

class circuitmatter.session.MessageReceptionState(starting_value, rollover=True, encrypted=False)

message_counter

window_bitmap

mask

encrypted

rollover

process_counter(counter) → bool: Returns True if the counter number is a duplicate

class circuitmatter.session.MessageCounter(starting_value=None, random_source=None)

value

__next__()

class circuitmatter.session.SessionManager(random_source, socket, node_credentials)

nonvolatile

unencrypted_message_counter

group_encrypted_data_message_counter

group_encrypted_control_message_counter

check_in_counter

unsecured_session_context

secure_session_contexts = ['reserved']

socket

random

node_credentials

get_session(message)

send_packets()

mark_duplicate(message): Implements 4.6.7

next_message_counter(message): Implements 4.6.6

new_context()

process_exchange(message)

reply_to_sigma1(exchange, sigma1)

reply_to_sigma3(exchange, sigma3) → SecureChannelProtocolCode