e2ee-api: Add documentation

Signed-off-by: Maxime Buquet's avatarMaxime “pep” Buquet <pep@bouah.net>
parent dd6efb14
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()
...@@ -14,6 +14,7 @@ About plugins ...@@ -14,6 +14,7 @@ About plugins
:maxdepth: 2 :maxdepth: 2
plugin plugin
e2ee
events events
slix slix
xep xep
......
...@@ -35,13 +35,31 @@ HINTS_NS = 'urn:xmpp:hints' ...@@ -35,13 +35,31 @@ HINTS_NS = 'urn:xmpp:hints'
class E2EEPlugin(BasePlugin): class E2EEPlugin(BasePlugin):
"""Interface for E2EE plugins""" """Interface for E2EE plugins.
# Specifies that the encryption mechanism does more than encrypting This is a wrapper built on top of BasePlugin. It provides a base for
# <body/>. 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 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]), [ tag_whitelist = list(map(lambda x: '{%s}%s' % (x[0], x[1]), [
(JCLIENT_NS, 'body'), (JCLIENT_NS, 'body'),
(EME_NS, EME_TAG), (EME_NS, EME_TAG),
...@@ -52,13 +70,22 @@ class E2EEPlugin(BasePlugin): ...@@ -52,13 +70,22 @@ class E2EEPlugin(BasePlugin):
# TODO: Add other encryption mechanisms tags here # 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 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_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] encryption_short_name = None # type: Optional[str]
# Required. #: Required.
eme_ns = None # type: Optional[str] eme_ns = None # type: Optional[str]
# Static map, to be able to limit to one encryption mechanism per tab at a # Static map, to be able to limit to one encryption mechanism per tab at a
...@@ -217,9 +244,29 @@ class E2EEPlugin(BasePlugin): ...@@ -217,9 +244,29 @@ class E2EEPlugin(BasePlugin):
return message return message
def decrypt(self, _message: Message, tab: ChatTabs): 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 raise NotImplementedError
def encrypt(self, _message: Message, tab: ChatTabs): 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 raise NotImplementedError
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment