summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMaxime “pep” Buquet <pep@bouah.net>2019-07-01 23:54:10 +0200
committerMaxime “pep” Buquet <pep@bouah.net>2019-07-01 23:54:10 +0200
commita8bf37eb611ce8fd8d963adb90cab6329ee0b8b6 (patch)
tree0e13701994f1f4727c3b2e169d0b6c35dae18470
parentdd6efb144467a6f8463f194394cb1e725e4535b1 (diff)
downloadpoezio-a8bf37eb611ce8fd8d963adb90cab6329ee0b8b6.tar.gz
poezio-a8bf37eb611ce8fd8d963adb90cab6329ee0b8b6.tar.bz2
poezio-a8bf37eb611ce8fd8d963adb90cab6329ee0b8b6.tar.xz
poezio-a8bf37eb611ce8fd8d963adb90cab6329ee0b8b6.zip
e2ee-api: Add documentation
Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>
-rw-r--r--doc/source/dev/e2ee.rst55
-rw-r--r--doc/source/dev/index.rst1
-rw-r--r--poezio/plugin_e2ee.py63
3 files changed, 111 insertions, 8 deletions
diff --git a/doc/source/dev/e2ee.rst b/doc/source/dev/e2ee.rst
new file mode 100644
index 00000000..08cae715
--- /dev/null
+++ b/doc/source/dev/e2ee.rst
@@ -0,0 +1,55 @@
+End-to-end Encryption API documentation
+=======================================
+
+E2EEPlugin
+----------
+
+.. module:: poezio.plugin_e2ee
+
+
+.. autoclass:: E2EEPlugin
+ :members:
+
+Builds on top of :py:class:`~BasePlugin` and requires the developer to
+implement two methods, `decrypt` and `encrypt`, as well as the
+`encryption_name` and `eme_ns` attribute.
+
+Please refer to :py:class:`~BasePlugin` for more information on how to
+write plugins.
+
+Example plugins
+---------------
+
+**Example 1:** Base64 plugin
+
+.. code-block:: python
+
+ from base64 import b64decode, b64encode
+ from poezio.plugin_e2ee import E2EEPlugin
+ from slixmpp import Message
+
+
+ class Plugin(E2EEPlugin):
+ """Base64 Plugin"""
+
+ encryption_name = 'base64'
+ encryption_short_name = 'b64'
+ eme_ns = 'urn:xmpps:base64:0'
+
+ # This encryption mechanism is using <body/> as a container
+ replace_body_with_eme = False
+
+ def decrypt(self, message: Message, _tab) -> None:
+ """
+ Decrypt base64
+ """
+ body = message['body']
+ message['body'] = b64decode(body.encode()).decode()
+
+ def encrypt(self, message: Message, _tab) -> None:
+ """
+ Encrypt to base64
+ """
+ # TODO: Stop using <body/> for this. Put the encoded payload in another element.
+ body = message['body']
+ message['body'] = b64encode(body.encode()).decode()
diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst
index 21ea6253..630abfad 100644
--- a/doc/source/dev/index.rst
+++ b/doc/source/dev/index.rst
@@ -14,6 +14,7 @@ About plugins
:maxdepth: 2
plugin
+ e2ee
events
slix
xep
diff --git a/poezio/plugin_e2ee.py b/poezio/plugin_e2ee.py
index 3f67d2f3..4e4eec2a 100644
--- a/poezio/plugin_e2ee.py
+++ b/poezio/plugin_e2ee.py
@@ -35,13 +35,31 @@ HINTS_NS = 'urn:xmpp:hints'
class E2EEPlugin(BasePlugin):
- """Interface for E2EE plugins"""
+ """Interface for E2EE plugins.
- # Specifies that the encryption mechanism does more than encrypting
- # <body/>.
+ This is a wrapper built on top of BasePlugin. It provides a base for
+ End-to-end Encryption mechanisms in poezio.
+
+ Plugin developers are excepted to implement the `decrypt` and
+ `encrypt` function, provide an encryption name (and/or short name),
+ and an eme namespace.
+
+ Once loaded, the plugin will attempt to decrypt any message that
+ contains an EME message that matches the one set.
+
+ The plugin will also register a command (using the short name) to
+ enable encryption per tab. It is only possible to have one encryption
+ mechanism per tab, even if multiple e2ee plugins are loaded.
+
+ The encryption status will be displayed in the status bar, using the
+ plugin short name, alongside the JID, nickname etc.
+ """
+
+ #: Specifies that the encryption mechanism does more than encrypting
+ #: <body/>.
stanza_encryption = False
- # Whitelist applied to messages when `stanza_encryption` is False.
+ #: Whitelist applied to messages when `stanza_encryption` is False.
tag_whitelist = list(map(lambda x: '{%s}%s' % (x[0], x[1]), [
(JCLIENT_NS, 'body'),
(EME_NS, EME_TAG),
@@ -52,13 +70,22 @@ class E2EEPlugin(BasePlugin):
# TODO: Add other encryption mechanisms tags here
]))
+ #: Replaces body with `eme <https://xmpp.org/extensions/xep-0380.html>`_
+ #: if set. Should be suitable for most plugins except those using <body/>
+ #: directly as their encryption container, like OTR, or the example base64
+ #: plugin in poezio.
replace_body_with_eme = True
- # At least one of encryption_name and encryption_short_name must be set
+ #: Encryption name, used in command descriptions, and logs. At least one
+ #: of `encryption_name` and `encryption_short_name` must be set.
encryption_name = None # type: Optional[str]
+
+ #: Encryption short name, used as command name, and also to display
+ #: encryption status in a tab. At least one of `encryption_name` and
+ #: `encryption_short_name` must be set.
encryption_short_name = None # type: Optional[str]
- # Required.
+ #: Required.
eme_ns = None # type: Optional[str]
# Static map, to be able to limit to one encryption mechanism per tab at a
@@ -217,9 +244,29 @@ class E2EEPlugin(BasePlugin):
return message
def decrypt(self, _message: Message, tab: ChatTabs):
- """Decryption method"""
+ """Decryption method
+
+ This is a method the plugin must implement. It is expected that this
+ method will edit the received message and return nothing.
+
+ :param message: Message to be decrypted.
+ :param tab: Tab the message is coming from.
+
+ :returns: None
+ """
+
raise NotImplementedError
def encrypt(self, _message: Message, tab: ChatTabs):
- """Encryption method"""
+ """Encryption method
+
+ This is a method the plugin must implement. It is expected that this
+ method will edit the received message and return nothing.
+
+ :param message: Message to be encrypted.
+ :param tab: Tab the message is going to.
+
+ :returns: None
+ """
+
raise NotImplementedError