OTR Bot¶

XMPP client for the OTR bot. Manages all conversations.

Usage¶

Start a bot by initialising the class:

>>> bot = OtrBot()

Then, you can connect to the Jabber server:

>>> bot.connect()

Lastly, start the bot by running process:

>>> bot.process()

If a user wants to be able to talk to the OTR bot, you should be added to its whitelist. This is achieved by running OtrBot.add_jid(), or adding the jid to the whitelist in the Settings. When adding someone to the whitelist, it is possible to supply its locale. All supported locales are in the root directory, in the locales folder.

After running add_jid, the bot will add a user to his whitelist and roster, and will invite the user to talk with him over Jabber. When the user starts talking to the bot, it will start a session for the user, and respond to him. When a user is inactive for too long, his session will be removed from the bot. See the functions warn_session(), kill_session() and terminate_session() for more information.

The bot is supplied in conjunction with an LTI interface for adding Jabber IDs to the bot and supplying shared secrets, but it is possible to use the bot from the command line, without using the LTI interface.

SleekXMPP¶

The bot uses SleekXMPP for communication and scheduling. A custom OTR Plugin fires events through SleekXMPP and are used by the bot to react on the user’s actions.

Class documentation¶

class otrbot.core.client.OtrBot(jid=None, **kwargs)¶

OTR bot ClientXMPP implementation

Start an OTR bot for a specifig Jabber ID.

Parameters:

jid (str) – The Jabber ID the bot can use. Its password needs to be in the settings, or supplied as a keyword argument. :keyword str password: The password for the jabber account
default_locale (str) – The default locale for the bot, overrides the setting DEFAULT_LOCALE.
shared_secret (str) – The default shared secret for the bot, overrides the setting DEFAULT_SECRET. Can be None, if the secret is added via another route, e.g., LTI.
key_file (str) – The name of the file containing the private key for the bot

REFRESH_SESSION_WHITELIST = ('message_received', 'otr_enabled', 'smp_started', 'smp_aborted', 'otr_disabled')¶: The events that allow the session of a user to be refreshed, extending its timeout

SIGN_OUT_MESSAGE = 'Your session has expired, you can start a new session from ${project_name}.'¶: This message is sent when the bot signs out and no other message is supplied

connect()¶: Connecting with the TLS and SSL flags set to None allows manipulation of these settings through the XML stream object

bot_connected(event)¶: Verify that the connection is established as requested, i.e.: the TLS cipher(s) that was(/were) configured is(/are) used. If this is not the case, disconnect and quit with a fatal error.

session_start(event)¶: Bring the bot online. All the JIDs that are already in the bot’s whitelist are added to the roster.

session_end(event)¶: Clean up at the end of the session. Kill all sessions, delete all aggregated data and empty the roster.

otr_event(event)¶

Apply an OTR event to the state machine of a specific JID. OTR events are fired by the OtrPlugin.

If the JID was unknown in the _sessions dict, but is in the _whitelist, a new session is started with start_sessions.

Parameters:	event (dict) – A dictionary containing the keys `jid` (JID), `type` (str) and `data` (any type). The `type` should be an event that can be handled by the current state. If the event can not be handled by the state, it will raise a CannotHandle exception.

check_sessions()¶: Checks all sessions’ contexts in self._sessions for timeouts. If a timeout is imminent (WARNING_TIMEOUT seconds have passed), it fires a warning using warn_session(). If a timeout has passed (SESSION_TIMEOUT seconds have passed), it removes the session by using kill_session().

refresh_session(jid)¶

Refresh the users session by resetting the timeouts. If the user has been warned about a session timeout, the bot sends a notification that the session has been refreshed.

Parameters:	jid (JID) – The user’s jid.

warn_session(jid)¶

Send a warning to the user, that they should reply to maintain the session.

Parameters:	jid (JID) – The user’s jid.

kill_session(jid, msg=None)¶

Tell the user the session has expired, then set a timeout for termination of the session (allows the message to be sent out first).

Parameters:	jid (JID) – The user’s jid, an instance of `sleekxmpp.jid.JID` msg (str) – The message that will be sent by the bot before going down.

terminate_session(jid, msg=None)¶

Remove the session from _sessions and the user from the roster. Also makes the bot offline to the user. A status message is set explaining how the user can re-enable the bot.

Parameters:	jid (JID) – The user’s jid, an instance of `sleekxmpp.jid.JID` msg (str) – The status message for the bot the user will see.

changed_subscription(presence)¶

Only authorize and subscribe to people in self._whitelist, which is populated by settings.JID_WHITELIST.

Parameters:	presence (Presence) – A `sleekxmpp.stanza.presence.Presence` stanza for the subscription

add_jid(jid, locale='en_GB')¶

Add the supplied JID to the whitelist and the roster and send a presence to appear online for that user.

Parameters:	jid (JID) – The Jabber ID to add

get_shared_secret(jid)¶

Return the shared secret set by the jabber ID jid, or none if he has not set one

Parameters:	jid (str) – The JID that should have set a shared secret

set_shared_secret(jid, secret)¶

Insert the secret into the context for the jid. The otr_event ‘secret_received’ is fired afterwards.

Parameters:	jid (str) – A valid jabber ID that is in self._sessions secret (str) – A secret that should be supplied by the user

check_bot_secret(jid, secret)¶

Check if the secret that the bot has provided via chat corresponds with the secret that is inserted into this function

Parameters:	jid (str) – The JID that received the secret secret (str) – The secret. Note that this is not the SMP shared secret
Return bool:	True if the secrets are the same, False otherwise.
Raises:	JidNotKnown – If the jid is not in _sessions, an exception is raised.

jid_in_sessions(jid)¶

Checks if the supplied JID has a running session.

Parameters:	jid (str) – The Jabber ID
Returns bool:	True if the jid is a key in self._sessions