Module: base_session_manager

class slixmpp_omemo.base_session_manager.TrustLevel(*values)

Bases: Enum

Trust levels modeling Blind Trust Before Verification (BTBV) and manual trust.

TRUSTED = 'TRUSTED'

BLINDLY_TRUSTED = 'BLINDLY_TRUSTED'

UNDECIDED = 'UNDECIDED'

DISTRUSTED = 'DISTRUSTED'

class slixmpp_omemo.base_session_manager.BaseSessionManager

Bases: SessionManager

Partial SessionManager implementation with BTBV and manual trust as its trust systems.

async _evaluate_custom_trust_level(device)

Evaluate a custom trust level to one of the three core trust levels:

• TRUSTED: This device is trusted, encryption/decryption of messages to/from it is allowed.

• DISTRUSTED: This device is explicitly not trusted, do not encrypt/decrypt messages to/from it.

• UNDECIDED: A trust decision is yet to be made. It is not clear whether it is okay to encrypt messages to it, however decrypting messages from it is allowed.

Parameters:

device (DeviceInformation) – Information about the device, including the custom trust level name to translate.

Return type:

TrustLevel

Returns:

The core trust level corresponding to the custom trust level.

Raises:

UnknownTrustLevel – if a custom trust level with this name is not known. Feel free to raise a subclass instead.

async _make_trust_decision(undecided, identifier)

Make a trust decision on a set of undecided identity keys. The trust decisions are expected to be persisted by calling set_trust().

Parameters:

• undecided (FrozenSet[DeviceInformation]) – A set of devices that require trust decisions.

• identifier (str | None) – A piece of application-specific information that callers can pass to encrypt(), which is then forwarded here unaltered. This can be used, for example, by instant messaging clients, to identify the chat tab which triggered the call to encrypt() and subsequently this call to _make_trust_decision().

Raises:

TrustDecisionFailed – if for any reason the trust decision failed/could not be completed. Feel free to raise a subclass instead.

Return type:

None

Note

This is called when the encryption needs to know whether it is allowed to encrypt for these devices or not. When this method returns, all previously undecided trust levels should have been replaced by calling set_trust() with a different trust level. If they are not replaced or still evaluate to the undecided trust level after the call, the encryption will fail with an exception. See encrypt() for details.

abstract property _btbv_enabled: bool

Returns: Whether BTBV is enabled.

async _devices_blindly_trusted(blindly_trusted, identifier)

Get notified about newly blindly trusted devices. This method is called automatically by _make_trust_decision() whenever at least one device was blindly trusted. You can use this method for example to notify the user about the automated change in trust.

Does nothing by default.

Parameters:

• blindly_trusted (FrozenSet[DeviceInformation]) – A set of devices that were blindly trusted.

• identifier (str | None) – Forwarded from _make_trust_decision(), refer to its documentation for details.

Return type:

None

abstractmethod async _prompt_manual_trust(manually_trusted, identifier)

Prompt manual trust decision on a set of undecided identity keys. The trust decisions are expected to be persisted by calling set_trust().

Parameters:

• manually_trusted (FrozenSet[DeviceInformation]) – A set of devices whose trust has to be manually decided by the user.

• identifier (str | None) – Forwarded from _make_trust_decision(), refer to its documentation for details.

Raises:

TrustDecisionFailed – if for any reason the trust decision failed/could not be completed. Feel free to raise a subclass instead.

Return type:

None

Note

This is called when the encryption needs to know whether it is allowed to encrypt for these devices or not. When this method returns, all previously undecided trust levels should have been replaced by calling set_trust() with a different trust level. If they are not replaced or still evaluate to the undecided trust level after the call, the encryption will fail with an exception. See encrypt() for details.