Module: session

class omemo.session.Initiation(value)[source]

Bases: Enum

Enumeration identifying whether a session was built through active or passive session initiation.

ACTIVE: str = 'ACTIVE'

PASSIVE: str = 'PASSIVE'

class omemo.session.Session[source]

Bases: ABC

Class representing an OMEMO session. Used to encrypt/decrypt key material for/from a single recipient/sender device in a perfectly forwared secure manner.

Warning

Changes to a session may only be persisted when store_session() is called.

Warning

Multiple sessions for the same device can exist in memory, however only one session per device can exist in storage. Which one of the in-memory sessions is persisted in storage is controlled by calling the store_session() method.

Note

The API of the Session class was intentionally kept thin. All “complex” interactions with session objects happen via methods of Backend. This allows backend implementors to have the Session class be a simple “stupid” data holding structure type, while all of the more complex logic is located in the implementation of the Backend class itself. Backend implementations are obviously free to implement logic on their respective Session implementations and forward calls to them from the Backend methods.

abstract property namespace: str

Return type: str

abstract property bare_jid: str

Return type: str

abstract property device_id: int

Return type: int

abstract property initiation: Initiation

Returns: Whether this session was actively initiated or passively.

Return type: Initiation

abstract property confirmed: bool

In case this session was built through active session initiation, this flag should indicate whether the session initiation has been “confirmed”, i.e. at least one message was received and decrypted using this session.

Return type: bool

abstract property key_exchange: KeyExchange

Either the key exchange information received during passive session building, or the key exchange information created as part of active session building. The key exchange information is needed by the protocol for stability reasons, to make sure that all sides can build the session, even if messages are lost or received out of order.

Return type: KeyExchange
Returns: The key exchange information associated with this session.

abstract property receiving_chain_length: Optional[int]

Returns: The length of the receiving chain, if it exists, used for own staleness detection.

Return type: Optional[int]

abstract property sending_chain_length: int

Returns: The length of the sending chain, used for staleness detection of other devices.

Return type: int