OTR Plugin¶
SleekXMPP Plugin to use OTR
Uses Python-Potr in combination with SleekXMPP to enable OTR messaging for Jabber clients. This plugin adds the event ‘message_received’, which forwards decrypted messages as well. Use that instead of the ‘message’ event. Furthermore, the plugin fires ‘otr_event’ events. These events always consist of a dictionary with the following content (keys):
jid: | The Jabber ID this event is about (This is a SleekXMPP JID object) |
---|---|
type: | The name of the event type that is fired, e.g. “otr_enabled” |
data: | Accompanying data for the event, this may be of any class, but we would recommend using strings. Currently, no events use this field. |
List of event types¶
otr_enabled: | OTR was off and is now on |
---|---|
otr_disabled: | OTR was on and is now off |
otr_already_setup: | |
OTR conversation was finished and is refreshed | |
smp_started: | User tried to start SMP |
smp_question_used: | |
User tried to start SMP with a question | |
smp_aborted: | SMP was aborted from either side. |
correct_secret_received: | |
User supplied the secret through anothes channel and was received correctly. SMP trust is now established. | |
incorrect_secret_received: | |
No trust has been established after SMP | |
unsafe_secret_received: | |
Not implemented in this plugin. Can be used if you have a way to check
the strength of secrets. Look at
core.otrbot.state.action_check_secret_safe() for an example |
Credits¶
The following two scripts have been used as a basis for this plugin:
-
class
otrbot.otrplugin.plugin.
OtrPlugin
(xmpp, config=None)¶ OtrPlugin: enables OTR commands
-
plugin_init
()¶ Initialise plugin. Sets the description (needed for being a SleekXMPP plugin) to the docstring of this class. Makes this plugin handle the ‘message’ event and registers the OtrMessage stanza plugin.
-
setup_otr
(xmpp_account)¶ Setup OTR account to be used for encryption and decryption. This function should be run after plugin_init and before anything else.
Parameters: xmpp_account (dict) – An account as found in the sample settings. This needs at least a JID. Private keys for the account will be generated automatically
-
set_secret
(jid, secret, start_smp=False)¶ Set the secret in the otr_context for this jid to this secret. Create a context if it does not exist for this jid.
Parameters:
-
decrypt
(message)¶ Try to decrypt a message and sets message.otr_state to a state from OTR_STATES. Then launches the event ‘message_received’, unless the message was empty.
Parameters: message (str) – A string that can be decrypted by Python-Potr
-
encrypt
(jid, message_string)¶ Send message “message” to “jid” if encryption is possible. If there’s no encryption, “jid” is asked to enable encryption(?)
Parameters: Returns: The message as it was sent
-
emit_event
(jid, event, data=None)¶ Emit an otr_event on xmpp
Parameters:
-
Otr Context that keeps all the otr-relevant information for a certain peer
-
class
otrbot.otrplugin.context.
OtrContext
(account, otr_plugin, peer, fingerprint)¶ Knows how peers can be contacted (OTR enabled or not, etc.) Implements these functions from Context:
- getPolicy
- setState
- inject
Create a context for the account to OTR-message with.
Parameters: - account (OtrAccount) – The OTR account
- otr_plugin (OtrPlugin) – An OTR plugin instance
- peer (str) – A JID
- fingerprint (str) – fingerprint for the JID, becomes lower case, is allowed to be None
-
emit_event
(event, data=None)¶ Makes the otr_plugin emit an event for self.peer
Parameters:
-
processTLVs
(tlvs, appdata=None)¶ Process typle/length/value records. First check if message is an SMP message and fire the appropriate otr_event if so. Then call the super to do further processing.
Parameters: - tlvs (list) – a list of TLV objects
- appdata – Gets passed to super
-
getPolicy
(key)¶ Returns the default policy from DEFAULT_POLICY_FLAGS. Returns False if the policy does not exist.
Parameters: key – The policy that should be returned. Possible keys:
- ALLOW_V1
- ALLOW_V2
- REQUIRE_ENCRYPTION
- SEND_TAG
- WHITESPACE_START_AKE
- ERROR_START_AKE
-
setState
(new_state)¶ Sets trust based on their fingerprint
Parameters: new_state (int) – The new state corresponding to the possible states in potr.context
.
-
inject
(msg, appdata=None)¶ Use OtrPlugin to send a message. This will be encrypted if possible.
Parameters:
Simple implementation of the abstract potr Account class.
-
class
otrbot.otrplugin.account.
OtrAccount
(otr_plugin, jid, private_key=None)¶ Implementation of potr Account class
Taken from OtrXMPPChannel
Init and create a private key if needed
-
loadPrivkey
()¶ overload not-implemented load function
-
savePrivkey
()¶ Should be overloaded, but don’t know with what functionality
-
saveTrusts
()¶ Should be overloaded, but don’t know with what functionality. Apparently this function is called after a user ends a private conversation
-
Simple implementation of the abstract potr Manager class.
-
class
otrbot.otrplugin.manager.
OtrManager
(jid, otr_plugin)¶ Class that retrieves contexts for messages. The contexts manage decryption and encryption of messages
Initialise with account and empty contexts dictionary. The dictionary wil contain bare JIDs and OtrContext objects. Each JID will talk to a different OtrAccount instance of the bot. This way, the bot always has a different fingerprint for each session, enabling a user to go through the same steps several times.
-
contexts
= None¶ Dictionary of people the bot is talking to - Keys: str of bare jids - Values: OtrContexts objects
-
get_context
(jid)¶ Return the context for the conversation with JID jid. If it does not exist, a new account (with a new random private key) is created for the session with the jid.
Parameters:
-
destroy_context
(jid)¶ Remove the context with JID jid from the contexts
Parameters: jid (JID) –
-
destroy_all_contexts
()¶ Remove all context for converations
-