From e3d66733712e161d9287ea3f0116e5b57477b0d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Sun, 8 Jul 2018 12:19:16 +0200 Subject: [PATCH] python: Import improved python bindings. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit imports the python bindings from: https://github.com/poljar/python-olm The bindings are imported at commit c44b145818520d69eaaa350fb95afcb846125e0f Minor modifications were made while importing: - Removed travis config - Removed Arch Linux PKGBUILD - Removed the html docs, they can be rebuild by running make html in the docs folder - Slightly modified the README The new bindings feature some improvements over the old ones: - Python 2 and 3 support - Automatic memory management - Automatic memory clearing before it is freed - Type signatures via the python typing module - Full test coverage - Properties are utilized where it makes sense (e.g. account.id) Signed-off-by: Damir Jelić --- python/.gitignore | 11 + python/LICENSE | 177 +++++++ python/MANIFEST.in | 3 + python/Makefile | 35 ++ python/README.md | 164 ++++++ python/docs/Makefile | 20 + python/docs/conf.py | 165 ++++++ python/docs/index.html | 1 + python/docs/index.rst | 19 + python/docs/make.bat | 36 ++ python/docs/olm.rst | 34 ++ python/include/olm/olm.h | 787 +++++++++++++++++++++++++++++ python/olm/__init__.py | 26 + python/olm/__version__.py | 9 + python/olm/_compat.py | 24 + python/olm/_finalize.py | 65 +++ python/olm/account.py | 239 +++++++++ python/olm/group_session.py | 467 +++++++++++++++++ python/olm/session.py | 452 +++++++++++++++++ python/olm/utility.py | 91 ++++ python/olm_build.py | 40 ++ python/requirements.txt | 3 + python/setup.cfg | 8 + python/setup.py | 27 + python/test-requirements.txt | 7 + python/tests/account_test.py | 100 ++++ python/tests/group_session_test.py | 114 +++++ python/tests/session_test.py | 143 ++++++ python/tox.ini | 43 ++ 29 files changed, 3310 insertions(+) create mode 100644 python/.gitignore create mode 100644 python/LICENSE create mode 100644 python/MANIFEST.in create mode 100644 python/Makefile create mode 100644 python/README.md create mode 100644 python/docs/Makefile create mode 100644 python/docs/conf.py create mode 100644 python/docs/index.html create mode 100644 python/docs/index.rst create mode 100644 python/docs/make.bat create mode 100644 python/docs/olm.rst create mode 100644 python/include/olm/olm.h create mode 100644 python/olm/__init__.py create mode 100644 python/olm/__version__.py create mode 100644 python/olm/_compat.py create mode 100644 python/olm/_finalize.py create mode 100644 python/olm/account.py create mode 100644 python/olm/group_session.py create mode 100644 python/olm/session.py create mode 100644 python/olm/utility.py create mode 100644 python/olm_build.py create mode 100644 python/requirements.txt create mode 100644 python/setup.cfg create mode 100644 python/setup.py create mode 100644 python/test-requirements.txt create mode 100644 python/tests/account_test.py create mode 100644 python/tests/group_session_test.py create mode 100644 python/tests/session_test.py create mode 100644 python/tox.ini diff --git a/python/.gitignore b/python/.gitignore new file mode 100644 index 0000000..3393fec --- /dev/null +++ b/python/.gitignore @@ -0,0 +1,11 @@ +.coverage +.mypy_cache/ +.ropeproject/ +.pytest_cache/ +packages/ +python_olm.egg-info/ +_libolm* +__pycache__ +*.pyc +.hypothesis/ +.tox/ diff --git a/python/LICENSE b/python/LICENSE new file mode 100644 index 0000000..f433b1a --- /dev/null +++ b/python/LICENSE @@ -0,0 +1,177 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS diff --git a/python/MANIFEST.in b/python/MANIFEST.in new file mode 100644 index 0000000..bfddd4f --- /dev/null +++ b/python/MANIFEST.in @@ -0,0 +1,3 @@ +include olm.h +include Makefile +include olm_build.py diff --git a/python/Makefile b/python/Makefile new file mode 100644 index 0000000..998d307 --- /dev/null +++ b/python/Makefile @@ -0,0 +1,35 @@ +PYTHON ?= python + +all: olm + +olm: + $(PYTHON) setup.py build + +install: olm + $(PYTHON) setup.py install --skip-build -O1 --root=$(DESTDIR) + +test: develop py2develop + python3 -m pytest + python2 -m pytest + python3 -m pytest --flake8 --benchmark-disable + python3 -m pytest --isort --benchmark-disable + python3 -m pytest --cov --cov-branch --benchmark-disable + +clean: + -rm -r python_olm.egg-info/ dist/ __pycache__/ + -rm *.so _libolm.o + -rm -r packages/ + -rm -r build/ + +develop: _libolm.o +py2develop: _libolm.so + +_libolm.so: include/olm/olm.h olm_build.py + python2 olm_build.py + -rm _libolm.c + +_libolm.o: include/olm/olm.h olm_build.py + python3 olm_build.py + -rm _libolm.c + +.PHONY: all olm install clean test develop diff --git a/python/README.md b/python/README.md new file mode 100644 index 0000000..e354cfd --- /dev/null +++ b/python/README.md @@ -0,0 +1,164 @@ +python-olm +========== + +[![Travis Build Status](https://travis-ci.org/poljar/python-olm.svg?branch=master)](https://travis-ci.org/poljar/python-olm) +[![Codecov Coverage Status](https://codecov.io/gh/poljar/python-olm/branch/master/graph/badge.svg)](https://codecov.io/gh/poljar/python-olm) + +Python bindings for Olm. + +The specification of the Olm cryptographic ratchet which is used for peer to +peer sessions of this library can be found [here][4]. + +The specification of the Megolm cryptographic ratchet which is used for group +sessions of this library can be found [here][5]. + +An example of the implementation of the Olm and Megolm cryptographic protocol +can be found in the Matrix protocol for which the implementation guide can be +found [here][6]. + +The full API reference can be found [here][7]. + +# Accounts + +Accounts create and hold the central identity of the Olm protocol, they consist of a fingerprint and identity +key pair. They also produce one time keys that are used to start peer to peer +encrypted communication channels. + +## Account Creation + +A new account is created with the Account class, it creates a new Olm key pair. +The public parts of the key pair are available using the identity_keys property +of the class. + +```python +>>> alice = Account() +>>> alice.identity_keys +{'curve25519': '2PytGagXercwHjzQETLcMa3JOsaU2qkPIESaqoi59zE', + 'ed25519': 'HHpOuFYdHwoa54GxSttz9YmaTmbuVU3js92UTUjYJgM'} +``` + + +## One Time keys + +One time keys need to be generated before people can start an encrypted peer to +peer channel to an account. + +```python +>>> alice.generate_one_time_keys(1) +>>> alice.one_time_keys +{'curve25519': {'AAAAAQ': 'KiHoW6CIy905UC4V1Frmwr3VW8bTWkBL4uWtWFFllxM'}} +``` + +After the one time keys are published they should be marked as such so they +aren't reused. + +```python +>>> alice.mark_keys_as_published() +>>> alice.one_time_keys +{'curve25519': {}} +``` + +## Pickling + +Accounts should be stored for later reuse, storing an account is done with the +pickle method while the restoring step is done with the from_pickle class +method. + +```python +>>> pickle = alice.pickle() +>>> restored = Account.from_pickle(pickle) +``` + +# Sessions + +Sessions are used to create an encrypted peer to peer communication channel +between two accounts. + +## Session Creation +```python +>>> alice = Account() +>>> bob = Account() +>>> bob.generate_one_time_keys(1) +>>> id_key = bob.identity_keys["curve25519"] +>>> one_time = list(bob.one_time_keys["curve25519"].values())[0] +>>> alice_session = OutboundSession(alice, id_key, one_time) +``` + +## Encryption + +After an outbound session is created an encrypted message can be exchanged: + +```python +>>> message = alice_session.encrypt("It's a secret to everybody") +>>> message.ciphertext +'AwogkL7RoakT9gnjcZMra+y39WXKRmnxBPEaEp6OSueIA0cSIJxGpBoP8YZ+CGweXQ10LujbXMgK88 +xG/JZMQJ5ulK9ZGiC8TYrezNYr3qyIBLlecXr/9wnegvJaSFDmWDVOcf4XfyI/AwogqIZfAklRXGC5b +ZJcZxVxQGgJ8Dz4OQII8k0Dp8msUXwQACIQvagY1dO55Qvnk5PZ2GF+wdKnvj6Zxl2g' +>>> message.message_type +0 +``` + +After the message is transfered, bob can create an InboundSession to decrypt the +message. + +```python +>>> bob_session = InboundSession(bob, message) +>>> bob_session.decrypt(message) +"It's a secret to everybody" +``` + +## Pickling + +Sessions like accounts can be stored for later use the API is the same as for +accounts. + +```python +>>> pickle = session.pickle() +>>> restored = Session.from_pickle(pickle) +``` + +# Group Sessions + +Group Sessions are used to create a one-to-many encrypted communication channel. +The group session key needs to be shared with all participants that should be able +to decrypt the group messages. Another thing to notice is that, since the group +session key is ratcheted every time a message is encrypted, the session key should +be shared before any messages are encrypted. + +## Group Session Creation + +Group sessions aren't bound to an account like peer-to-peer sessions so their +creation is straightforward. + +```python +>>> alice_group = OutboundGroupSession() +>>> bob_inbound_group = InboundGroupSession(alice_group.session_key) +``` + +## Group Encryption + +Group encryption is pretty simple. The important part is to share the session +key with all participants over a secure channel (e.g. peer-to-peer Olm +sessions). + +```python +>>> message = alice_group.encrypt("It's a secret to everybody") +>>> bob_inbound_group.decrypt(message) +("It's a secret to everybody", 0) +``` + +## Pickling + +Pickling works the same way as for peer-to-peer Olm sessions. + +```python +>>> pickle = session.pickle() +>>> restored = InboundGroupSession.from_pickle(pickle) +``` +[1]: https://git.matrix.org/git/olm/about/ +[2]: https://git.matrix.org/git/olm/tree/python?id=f8c61b8f8432d0b0b38d57f513c5048fb42f22ab +[3]: https://cffi.readthedocs.io/en/latest/ +[4]: https://git.matrix.org/git/olm/about/docs/olm.rst +[5]: https://git.matrix.org/git/olm/about/docs/megolm.rst +[6]: https://matrix.org/docs/guides/e2e_implementation.html +[7]: https://poljar.github.io/python-olm/html/index.html diff --git a/python/docs/Makefile b/python/docs/Makefile new file mode 100644 index 0000000..a72f9d9 --- /dev/null +++ b/python/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = olm +SOURCEDIR = . +BUILDDIR = . + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/python/docs/conf.py b/python/docs/conf.py new file mode 100644 index 0000000..ce2a88d --- /dev/null +++ b/python/docs/conf.py @@ -0,0 +1,165 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath('../')) + + +# -- Project information ----------------------------------------------------- + +project = 'python-olm' +copyright = '2018, Damir Jelić' +author = 'Damir Jelić' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '2.2' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.coverage', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages', + 'sphinx.ext.napoleon', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'olmdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'olm.tex', 'olm Documentation', + 'Damir Jelić', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'olm', 'olm Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'olm', 'olm Documentation', + author, 'olm', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Extension configuration ------------------------------------------------- diff --git a/python/docs/index.html b/python/docs/index.html new file mode 100644 index 0000000..9644bbb --- /dev/null +++ b/python/docs/index.html @@ -0,0 +1 @@ + diff --git a/python/docs/index.rst b/python/docs/index.rst new file mode 100644 index 0000000..39e6657 --- /dev/null +++ b/python/docs/index.rst @@ -0,0 +1,19 @@ +.. olm documentation master file, created by + sphinx-quickstart on Sun Jun 17 15:57:08 2018. + +Welcome to olm's documentation! +=============================== + +.. toctree:: + Olm API reference + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/python/docs/make.bat b/python/docs/make.bat new file mode 100644 index 0000000..1c5b4d8 --- /dev/null +++ b/python/docs/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=olm + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/python/docs/olm.rst b/python/docs/olm.rst new file mode 100644 index 0000000..9d8edf0 --- /dev/null +++ b/python/docs/olm.rst @@ -0,0 +1,34 @@ +olm package +=========== + +olm.account module +------------------ + +.. automodule:: olm.account + :members: + :undoc-members: + :show-inheritance: + +olm.group\_session module +------------------------- + +.. automodule:: olm.group_session + :members: + :undoc-members: + :show-inheritance: + +olm.session module +------------------ + +.. automodule:: olm.session + :members: + :undoc-members: + :show-inheritance: + +olm.utility module +------------------ + +.. automodule:: olm.utility + :members: + :undoc-members: + :show-inheritance: diff --git a/python/include/olm/olm.h b/python/include/olm/olm.h new file mode 100644 index 0000000..1ea0971 --- /dev/null +++ b/python/include/olm/olm.h @@ -0,0 +1,787 @@ +/* Copyright 2015, 2016 OpenMarket Ltd + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +static const size_t OLM_MESSAGE_TYPE_PRE_KEY = 0; +static const size_t OLM_MESSAGE_TYPE_MESSAGE = 1; + +typedef struct OlmAccount OlmAccount; +typedef struct OlmSession OlmSession; +typedef struct OlmUtility OlmUtility; + +/** Get the version number of the library. + * Arguments will be updated if non-null. + */ +void olm_get_library_version(uint8_t *major, uint8_t *minor, uint8_t *patch); + +/** The size of an account object in bytes */ +size_t olm_account_size(); + +/** The size of a session object in bytes */ +size_t olm_session_size(); + +/** The size of a utility object in bytes */ +size_t olm_utility_size(); + +/** Initialise an account object using the supplied memory + * The supplied memory must be at least olm_account_size() bytes */ +OlmAccount * olm_account( + void * memory +); + +/** Initialise a session object using the supplied memory + * The supplied memory must be at least olm_session_size() bytes */ +OlmSession * olm_session( + void * memory +); + +/** Initialise a utility object using the supplied memory + * The supplied memory must be at least olm_utility_size() bytes */ +OlmUtility * olm_utility( + void * memory +); + +/** The value that olm will return from a function if there was an error */ +size_t olm_error(); + +/** A null terminated string describing the most recent error to happen to an + * account */ +const char * olm_account_last_error( + OlmAccount * account +); + +/** A null terminated string describing the most recent error to happen to a + * session */ +const char * olm_session_last_error( + OlmSession * session +); + +/** A null terminated string describing the most recent error to happen to a + * utility */ +const char * olm_utility_last_error( + OlmUtility * utility +); + +/** Clears the memory used to back this account */ +size_t olm_clear_account( + OlmAccount * account +); + +/** Clears the memory used to back this session */ +size_t olm_clear_session( + OlmSession * session +); + +/** Clears the memory used to back this utility */ +size_t olm_clear_utility( + OlmUtility * utility +); + +/** Returns the number of bytes needed to store an account */ +size_t olm_pickle_account_length( + OlmAccount * account +); + +/** Returns the number of bytes needed to store a session */ +size_t olm_pickle_session_length( + OlmSession * session +); + +/** Stores an account as a base64 string. Encrypts the account using the + * supplied key. Returns the length of the pickled account on success. + * Returns olm_error() on failure. If the pickle output buffer + * is smaller than olm_pickle_account_length() then + * olm_account_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */ +size_t olm_pickle_account( + OlmAccount * account, + void const * key, size_t key_length, + void * pickled, size_t pickled_length +); + +/** Stores a session as a base64 string. Encrypts the session using the + * supplied key. Returns the length of the pickled session on success. + * Returns olm_error() on failure. If the pickle output buffer + * is smaller than olm_pickle_session_length() then + * olm_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */ +size_t olm_pickle_session( + OlmSession * session, + void const * key, size_t key_length, + void * pickled, size_t pickled_length +); + +/** Loads an account from a pickled base64 string. Decrypts the account using + * the supplied key. Returns olm_error() on failure. If the key doesn't + * match the one used to encrypt the account then olm_account_last_error() + * will be "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then + * olm_account_last_error() will be "INVALID_BASE64". The input pickled + * buffer is destroyed */ +size_t olm_unpickle_account( + OlmAccount * account, + void const * key, size_t key_length, + void * pickled, size_t pickled_length +); + +/** Loads a session from a pickled base64 string. Decrypts the session using + * the supplied key. Returns olm_error() on failure. If the key doesn't + * match the one used to encrypt the account then olm_session_last_error() + * will be "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then + * olm_session_last_error() will be "INVALID_BASE64". The input pickled + * buffer is destroyed */ +size_t olm_unpickle_session( + OlmSession * session, + void const * key, size_t key_length, + void * pickled, size_t pickled_length +); + +/** The number of random bytes needed to create an account.*/ +size_t olm_create_account_random_length( + OlmAccount * account +); + +/** Creates a new account. Returns olm_error() on failure. If weren't + * enough random bytes then olm_account_last_error() will be + * "NOT_ENOUGH_RANDOM" */ +size_t olm_create_account( + OlmAccount * account, + void * random, size_t random_length +); + +/** The size of the output buffer needed to hold the identity keys */ +size_t olm_account_identity_keys_length( + OlmAccount * account +); + +/** Writes the public parts of the identity keys for the account into the + * identity_keys output buffer. Returns olm_error() on failure. If the + * identity_keys buffer was too small then olm_account_last_error() will be + * "OUTPUT_BUFFER_TOO_SMALL". */ +size_t olm_account_identity_keys( + OlmAccount * account, + void * identity_keys, size_t identity_key_length +); + + +/** The length of an ed25519 signature encoded as base64. */ +size_t olm_account_signature_length( + OlmAccount * account +); + +/** Signs a message with the ed25519 key for this account. Returns olm_error() + * on failure. If the signature buffer was too small then + * olm_account_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */ +size_t olm_account_sign( + OlmAccount * account, + void const * message, size_t message_length, + void * signature, size_t signature_length +); + +/** The size of the output buffer needed to hold the one time keys */ +size_t olm_account_one_time_keys_length( + OlmAccount * account +); + +/** Writes the public parts of the unpublished one time keys for the account + * into the one_time_keys output buffer. + *

+ * The returned data is a JSON-formatted object with the single property + * curve25519, which is itself an object mapping key id to + * base64-encoded Curve25519 key. For example: + * 

+ * {
+ *     curve25519: {
+ *         "AAAAAA": "wo76WcYtb0Vk/pBOdmduiGJ0wIEjW4IBMbbQn7aSnTo",
+ *         "AAAAAB": "LRvjo46L1X2vx69sS9QNFD29HWulxrmW11Up5AfAjgU"
+ *     }
+ * }
+ *
+ * Returns olm_error() on failure. + *

+ * If the one_time_keys buffer was too small then olm_account_last_error() + * will be "OUTPUT_BUFFER_TOO_SMALL". */ +size_t olm_account_one_time_keys( + OlmAccount * account, + void * one_time_keys, size_t one_time_keys_length +); + +/** Marks the current set of one time keys as being published. */ +size_t olm_account_mark_keys_as_published( + OlmAccount * account +); + +/** The largest number of one time keys this account can store. */ +size_t olm_account_max_number_of_one_time_keys( + OlmAccount * account +); + +/** The number of random bytes needed to generate a given number of new one + * time keys. */ +size_t olm_account_generate_one_time_keys_random_length( + OlmAccount * account, + size_t number_of_keys +); + +/** Generates a number of new one time keys. If the total number of keys stored + * by this account exceeds max_number_of_one_time_keys() then the old keys are + * discarded. Returns olm_error() on error. If the number of random bytes is + * too small then olm_account_last_error() will be "NOT_ENOUGH_RANDOM". */ +size_t olm_account_generate_one_time_keys( + OlmAccount * account, + size_t number_of_keys, + void * random, size_t random_length +); + +/** The number of random bytes needed to create an outbound session */ +size_t olm_create_outbound_session_random_length( + OlmSession * session +); + +/** Creates a new out-bound session for sending messages to a given identity_key + * and one_time_key. Returns olm_error() on failure. If the keys couldn't be + * decoded as base64 then olm_session_last_error() will be "INVALID_BASE64" + * If there weren't enough random bytes then olm_session_last_error() will + * be "NOT_ENOUGH_RANDOM". */ +size_t olm_create_outbound_session( + OlmSession * session, + OlmAccount * account, + void const * their_identity_key, size_t their_identity_key_length, + void const * their_one_time_key, size_t their_one_time_key_length, + void * random, size_t random_length +); + +/** Create a new in-bound session for sending/receiving messages from an + * incoming PRE_KEY message. Returns olm_error() on failure. If the base64 + * couldn't be decoded then olm_session_last_error will be "INVALID_BASE64". + * If the message was for an unsupported protocol version then + * olm_session_last_error() will be "BAD_MESSAGE_VERSION". If the message + * couldn't be decoded then then olm_session_last_error() will be + * "BAD_MESSAGE_FORMAT". If the message refers to an unknown one time + * key then olm_session_last_error() will be "BAD_MESSAGE_KEY_ID". */ +size_t olm_create_inbound_session( + OlmSession * session, + OlmAccount * account, + void * one_time_key_message, size_t message_length +); + +/** Create a new in-bound session for sending/receiving messages from an + * incoming PRE_KEY message. Returns olm_error() on failure. If the base64 + * couldn't be decoded then olm_session_last_error will be "INVALID_BASE64". + * If the message was for an unsupported protocol version then + * olm_session_last_error() will be "BAD_MESSAGE_VERSION". If the message + * couldn't be decoded then then olm_session_last_error() will be + * "BAD_MESSAGE_FORMAT". If the message refers to an unknown one time + * key then olm_session_last_error() will be "BAD_MESSAGE_KEY_ID". */ +size_t olm_create_inbound_session_from( + OlmSession * session, + OlmAccount * account, + void const * their_identity_key, size_t their_identity_key_length, + void * one_time_key_message, size_t message_length +); + +/** The length of the buffer needed to return the id for this session. */ +size_t olm_session_id_length( + OlmSession * session +); + +/** An identifier for this session. Will be the same for both ends of the + * conversation. If the id buffer is too small then olm_session_last_error() + * will be "OUTPUT_BUFFER_TOO_SMALL". */ +size_t olm_session_id( + OlmSession * session, + void * id, size_t id_length +); + +int olm_session_has_received_message( + OlmSession *session +); + +/** Checks if the PRE_KEY message is for this in-bound session. This can happen + * if multiple messages are sent to this account before this account sends a + * message in reply. Returns 1 if the session matches. Returns 0 if the session + * does not match. Returns olm_error() on failure. If the base64 + * couldn't be decoded then olm_session_last_error will be "INVALID_BASE64". + * If the message was for an unsupported protocol version then + * olm_session_last_error() will be "BAD_MESSAGE_VERSION". If the message + * couldn't be decoded then then olm_session_last_error() will be + * "BAD_MESSAGE_FORMAT". */ +size_t olm_matches_inbound_session( + OlmSession * session, + void * one_time_key_message, size_t message_length +); + +/** Checks if the PRE_KEY message is for this in-bound session. This can happen + * if multiple messages are sent to this account before this account sends a + * message in reply. Returns 1 if the session matches. Returns 0 if the session + * does not match. Returns olm_error() on failure. If the base64 + * couldn't be decoded then olm_session_last_error will be "INVALID_BASE64". + * If the message was for an unsupported protocol version then + * olm_session_last_error() will be "BAD_MESSAGE_VERSION". If the message + * couldn't be decoded then then olm_session_last_error() will be + * "BAD_MESSAGE_FORMAT". */ +size_t olm_matches_inbound_session_from( + OlmSession * session, + void const * their_identity_key, size_t their_identity_key_length, + void * one_time_key_message, size_t message_length +); + +/** Removes the one time keys that the session used from the account. Returns + * olm_error() on failure. If the account doesn't have any matching one time + * keys then olm_account_last_error() will be "BAD_MESSAGE_KEY_ID". */ +size_t olm_remove_one_time_keys( + OlmAccount * account, + OlmSession * session +); + +/** The type of the next message that olm_encrypt() will return. Returns + * OLM_MESSAGE_TYPE_PRE_KEY if the message will be a PRE_KEY message. + * Returns OLM_MESSAGE_TYPE_MESSAGE if the message will be a normal message. + * Returns olm_error on failure. */ +size_t olm_encrypt_message_type( + OlmSession * session +); + +/** The number of random bytes needed to encrypt the next message. */ +size_t olm_encrypt_random_length( + OlmSession * session +); + +/** The size of the next message in bytes for the given number of plain-text + * bytes. */ +size_t olm_encrypt_message_length( + OlmSession * session, + size_t plaintext_length +); + +/** Encrypts a message using the session. Returns the length of the message in + * bytes on success. Writes the message as base64 into the message buffer. + * Returns olm_error() on failure. If the message buffer is too small then + * olm_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL". If there + * weren't enough random bytes then olm_session_last_error() will be + * "NOT_ENOUGH_RANDOM". */ +size_t olm_encrypt( + OlmSession * session, + void const * plaintext, size_t plaintext_length, + void * random, size_t random_length, + void * message, size_t message_length +); + +/** The maximum number of bytes of plain-text a given message could decode to. + * The actual size could be different due to padding. The input message buffer + * is destroyed. Returns olm_error() on failure. If the message base64 + * couldn't be decoded then olm_session_last_error() will be + * "INVALID_BASE64". If the message is for an unsupported version of the + * protocol then olm_session_last_error() will be "BAD_MESSAGE_VERSION". + * If the message couldn't be decoded then olm_session_last_error() will be + * "BAD_MESSAGE_FORMAT". */ +size_t olm_decrypt_max_plaintext_length( + OlmSession * session, + size_t message_type, + void * message, size_t message_length +); + +/** Decrypts a message using the session. The input message buffer is destroyed. + * Returns the length of the plain-text on success. Returns olm_error() on + * failure. If the plain-text buffer is smaller than + * olm_decrypt_max_plaintext_length() then olm_session_last_error() + * will be "OUTPUT_BUFFER_TOO_SMALL". If the base64 couldn't be decoded then + * olm_session_last_error() will be "INVALID_BASE64". If the message is for + * an unsupported version of the protocol then olm_session_last_error() will + * be "BAD_MESSAGE_VERSION". If the message couldn't be decoded then + * olm_session_last_error() will be BAD_MESSAGE_FORMAT". + * If the MAC on the message was invalid then olm_session_last_error() will + * be "BAD_MESSAGE_MAC". */ +size_t olm_decrypt( + OlmSession * session, + size_t message_type, + void * message, size_t message_length, + void * plaintext, size_t max_plaintext_length +); + +/** The length of the buffer needed to hold the SHA-256 hash. */ +size_t olm_sha256_length( + OlmUtility * utility +); + +/** Calculates the SHA-256 hash of the input and encodes it as base64. If the + * output buffer is smaller than olm_sha256_length() then + * olm_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL". */ +size_t olm_sha256( + OlmUtility * utility, + void const * input, size_t input_length, + void * output, size_t output_length +); + +/** Verify an ed25519 signature. If the key was too small then + * olm_session_last_error will be "INVALID_BASE64". If the signature was invalid + * then olm_session_last_error() will be "BAD_MESSAGE_MAC". */ +size_t olm_ed25519_verify( + OlmUtility * utility, + void const * key, size_t key_length, + void const * message, size_t message_length, + void * signature, size_t signature_length +); + +typedef struct OlmOutboundGroupSession OlmOutboundGroupSession; + +/** get the size of an outbound group session, in bytes. */ +size_t olm_outbound_group_session_size(); + +/** + * Initialise an outbound group session object using the supplied memory + * The supplied memory should be at least olm_outbound_group_session_size() + * bytes. + */ +OlmOutboundGroupSession * olm_outbound_group_session( + void *memory +); + +/** + * A null terminated string describing the most recent error to happen to a + * group session */ +const char *olm_outbound_group_session_last_error( + const OlmOutboundGroupSession *session +); + +/** Clears the memory used to back this group session */ +size_t olm_clear_outbound_group_session( + OlmOutboundGroupSession *session +); + +/** Returns the number of bytes needed to store an outbound group session */ +size_t olm_pickle_outbound_group_session_length( + const OlmOutboundGroupSession *session +); + +/** + * Stores a group session as a base64 string. Encrypts the session using the + * supplied key. Returns the length of the session on success. + * + * Returns olm_error() on failure. If the pickle output buffer + * is smaller than olm_pickle_outbound_group_session_length() then + * olm_outbound_group_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" + */ +size_t olm_pickle_outbound_group_session( + OlmOutboundGroupSession *session, + void const * key, size_t key_length, + void * pickled, size_t pickled_length +); + +/** + * Loads a group session from a pickled base64 string. Decrypts the session + * using the supplied key. + * + * Returns olm_error() on failure. If the key doesn't match the one used to + * encrypt the account then olm_outbound_group_session_last_error() will be + * "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then + * olm_outbound_group_session_last_error() will be "INVALID_BASE64". The input + * pickled buffer is destroyed + */ +size_t olm_unpickle_outbound_group_session( + OlmOutboundGroupSession *session, + void const * key, size_t key_length, + void * pickled, size_t pickled_length +); + + +/** The number of random bytes needed to create an outbound group session */ +size_t olm_init_outbound_group_session_random_length( + const OlmOutboundGroupSession *session +); + +/** + * Start a new outbound group session. Returns olm_error() on failure. On + * failure last_error will be set with an error code. The last_error will be + * NOT_ENOUGH_RANDOM if the number of random bytes was too small. + */ +size_t olm_init_outbound_group_session( + OlmOutboundGroupSession *session, + uint8_t *random, size_t random_length +); + +/** + * The number of bytes that will be created by encrypting a message + */ +size_t olm_group_encrypt_message_length( + OlmOutboundGroupSession *session, + size_t plaintext_length +); + +/** + * Encrypt some plain-text. Returns the length of the encrypted message or + * olm_error() on failure. On failure last_error will be set with an + * error code. The last_error will be OUTPUT_BUFFER_TOO_SMALL if the output + * buffer is too small. + */ +size_t olm_group_encrypt( + OlmOutboundGroupSession *session, + uint8_t const * plaintext, size_t plaintext_length, + uint8_t * message, size_t message_length +); + + +/** + * Get the number of bytes returned by olm_outbound_group_session_id() + */ +size_t olm_outbound_group_session_id_length( + const OlmOutboundGroupSession *session +); + +/** + * Get a base64-encoded identifier for this session. + * + * Returns the length of the session id on success or olm_error() on + * failure. On failure last_error will be set with an error code. The + * last_error will be OUTPUT_BUFFER_TOO_SMALL if the id buffer was too + * small. + */ +size_t olm_outbound_group_session_id( + OlmOutboundGroupSession *session, + uint8_t * id, size_t id_length +); + +/** + * Get the current message index for this session. + * + * Each message is sent with an increasing index; this returns the index for + * the next message. + */ +uint32_t olm_outbound_group_session_message_index( + OlmOutboundGroupSession *session +); + +/** + * Get the number of bytes returned by olm_outbound_group_session_key() + */ +size_t olm_outbound_group_session_key_length( + const OlmOutboundGroupSession *session +); + +/** + * Get the base64-encoded current ratchet key for this session. + * + * Each message is sent with a different ratchet key. This function returns the + * ratchet key that will be used for the next message. + * + * Returns the length of the ratchet key on success or olm_error() on + * failure. On failure last_error will be set with an error code. The + * last_error will be OUTPUT_BUFFER_TOO_SMALL if the buffer was too small. + */ +size_t olm_outbound_group_session_key( + OlmOutboundGroupSession *session, + uint8_t * key, size_t key_length +); + +typedef struct OlmInboundGroupSession OlmInboundGroupSession; + +/** get the size of an inbound group session, in bytes. */ +size_t olm_inbound_group_session_size(); + +/** + * Initialise an inbound group session object using the supplied memory + * The supplied memory should be at least olm_inbound_group_session_size() + * bytes. + */ +OlmInboundGroupSession * olm_inbound_group_session( + void *memory +); + +/** + * A null terminated string describing the most recent error to happen to a + * group session */ +const char *olm_inbound_group_session_last_error( + const OlmInboundGroupSession *session +); + +/** Clears the memory used to back this group session */ +size_t olm_clear_inbound_group_session( + OlmInboundGroupSession *session +); + +/** Returns the number of bytes needed to store an inbound group session */ +size_t olm_pickle_inbound_group_session_length( + const OlmInboundGroupSession *session +); + +/** + * Stores a group session as a base64 string. Encrypts the session using the + * supplied key. Returns the length of the session on success. + * + * Returns olm_error() on failure. If the pickle output buffer + * is smaller than olm_pickle_inbound_group_session_length() then + * olm_inbound_group_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" + */ +size_t olm_pickle_inbound_group_session( + OlmInboundGroupSession *session, + void const * key, size_t key_length, + void * pickled, size_t pickled_length +); + +/** + * Loads a group session from a pickled base64 string. Decrypts the session + * using the supplied key. + * + * Returns olm_error() on failure. If the key doesn't match the one used to + * encrypt the account then olm_inbound_group_session_last_error() will be + * "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then + * olm_inbound_group_session_last_error() will be "INVALID_BASE64". The input + * pickled buffer is destroyed + */ +size_t olm_unpickle_inbound_group_session( + OlmInboundGroupSession *session, + void const * key, size_t key_length, + void * pickled, size_t pickled_length +); + + +/** + * Start a new inbound group session, from a key exported from + * olm_outbound_group_session_key + * + * Returns olm_error() on failure. On failure last_error will be set with an + * error code. The last_error will be: + * + * * OLM_INVALID_BASE64 if the session_key is not valid base64 + * * OLM_BAD_SESSION_KEY if the session_key is invalid + */ +size_t olm_init_inbound_group_session( + OlmInboundGroupSession *session, + /* base64-encoded keys */ + uint8_t const * session_key, size_t session_key_length +); + +/** + * Import an inbound group session, from a previous export. + * + * Returns olm_error() on failure. On failure last_error will be set with an + * error code. The last_error will be: + * + * * OLM_INVALID_BASE64 if the session_key is not valid base64 + * * OLM_BAD_SESSION_KEY if the session_key is invalid + */ +size_t olm_import_inbound_group_session( + OlmInboundGroupSession *session, + /* base64-encoded keys; note that it will be overwritten with the base64-decoded + data. */ + uint8_t const * session_key, size_t session_key_length +); + + +/** + * Get an upper bound on the number of bytes of plain-text the decrypt method + * will write for a given input message length. The actual size could be + * different due to padding. + * + * The input message buffer is destroyed. + * + * Returns olm_error() on failure. + */ +size_t olm_group_decrypt_max_plaintext_length( + OlmInboundGroupSession *session, + uint8_t * message, size_t message_length +); + +/** + * Decrypt a message. + * + * The input message buffer is destroyed. + * + * Returns the length of the decrypted plain-text, or olm_error() on failure. + * + * On failure last_error will be set with an error code. The last_error will + * be: + * * OLM_OUTPUT_BUFFER_TOO_SMALL if the plain-text buffer is too small + * * OLM_INVALID_BASE64 if the message is not valid base-64 + * * OLM_BAD_MESSAGE_VERSION if the message was encrypted with an unsupported + * version of the protocol + * * OLM_BAD_MESSAGE_FORMAT if the message headers could not be decoded + * * OLM_BAD_MESSAGE_MAC if the message could not be verified + * * OLM_UNKNOWN_MESSAGE_INDEX if we do not have a session key corresponding to the + * message's index (ie, it was sent before the session key was shared with + * us) + */ +size_t olm_group_decrypt( + OlmInboundGroupSession *session, + + /* input; note that it will be overwritten with the base64-decoded + message. */ + uint8_t * message, size_t message_length, + + /* output */ + uint8_t * plaintext, size_t max_plaintext_length, + uint32_t * message_index +); + + +/** + * Get the number of bytes returned by olm_inbound_group_session_id() + */ +size_t olm_inbound_group_session_id_length( + const OlmInboundGroupSession *session +); + +/** + * Get a base64-encoded identifier for this session. + * + * Returns the length of the session id on success or olm_error() on + * failure. On failure last_error will be set with an error code. The + * last_error will be OUTPUT_BUFFER_TOO_SMALL if the id buffer was too + * small. + */ +size_t olm_inbound_group_session_id( + OlmInboundGroupSession *session, + uint8_t * id, size_t id_length +); + +/** + * Get the first message index we know how to decrypt. + */ +uint32_t olm_inbound_group_session_first_known_index( + const OlmInboundGroupSession *session +); + + +/** + * Check if the session has been verified as a valid session. + * + * (A session is verified either because the original session share was signed, + * or because we have subsequently successfully decrypted a message.) + * + * This is mainly intended for the unit tests, currently. + */ +int olm_inbound_group_session_is_verified( + const OlmInboundGroupSession *session +); + +/** + * Get the number of bytes returned by olm_export_inbound_group_session() + */ +size_t olm_export_inbound_group_session_length( + const OlmInboundGroupSession *session +); + +/** + * Export the base64-encoded ratchet key for this session, at the given index, + * in a format which can be used by olm_import_inbound_group_session + * + * Returns the length of the ratchet key on success or olm_error() on + * failure. On failure last_error will be set with an error code. The + * last_error will be: + * * OUTPUT_BUFFER_TOO_SMALL if the buffer was too small + * * OLM_UNKNOWN_MESSAGE_INDEX if we do not have a session key corresponding to the + * given index (ie, it was sent before the session key was shared with + * us) + */ +size_t olm_export_inbound_group_session( + OlmInboundGroupSession *session, + uint8_t * key, size_t key_length, uint32_t message_index +); diff --git a/python/olm/__init__.py b/python/olm/__init__.py new file mode 100644 index 0000000..b52c88b --- /dev/null +++ b/python/olm/__init__.py @@ -0,0 +1,26 @@ +# -*- coding: utf-8 -*- +# libolm python bindings +# Copyright © 2015-2017 OpenMarket Ltd +# Copyright © 2018 Damir Jelić +""" +Olm Python bindings +~~~~~~~~~~~~~~~~~~~~~ +| This package implements python bindings for the libolm C library. +| © Copyright 2015-2017 by OpenMarket Ltd +| © Copyright 2018 by Damir Jelić +""" +from .utility import ed25519_verify, OlmVerifyError +from .account import Account, OlmAccountError +from .session import ( + Session, + InboundSession, + OutboundSession, + OlmSessionError, + OlmMessage, + OlmPreKeyMessage +) +from .group_session import ( + InboundGroupSession, + OutboundGroupSession, + OlmGroupSessionError +) diff --git a/python/olm/__version__.py b/python/olm/__version__.py new file mode 100644 index 0000000..dccfdd0 --- /dev/null +++ b/python/olm/__version__.py @@ -0,0 +1,9 @@ +__title__ = "python-olm" +__description__ = ("python CFFI bindings for the olm " + "cryptographic ratchet library") +__url__ = "https://github.com/poljar/python-olm" +__version__ = "0.1" +__author__ = "Damir Jelić" +__author_email__ = "poljar@termina.org.uk" +__license__ = "Apache 2.0" +__copyright__ = "Copyright 2018 Damir Jelić" diff --git a/python/olm/_compat.py b/python/olm/_compat.py new file mode 100644 index 0000000..67d312b --- /dev/null +++ b/python/olm/_compat.py @@ -0,0 +1,24 @@ +# -*- coding: utf-8 -*- +# libolm python bindings +# Copyright © 2015-2017 OpenMarket Ltd +# Copyright © 2018 Damir Jelić + +from builtins import bytes, str +from typing import AnyStr + +try: + import secrets + URANDOM = secrets.token_bytes # pragma: no cover +except ImportError: # pragma: no cover + from os import urandom + URANDOM = urandom # type: ignore + + +def to_bytes(string): + # type: (AnyStr) -> bytes + if isinstance(string, bytes): + return string + elif isinstance(string, str): + return bytes(string, "utf-8") + + raise TypeError("Invalid type {}".format(type(string))) diff --git a/python/olm/_finalize.py b/python/olm/_finalize.py new file mode 100644 index 0000000..9f467bc --- /dev/null +++ b/python/olm/_finalize.py @@ -0,0 +1,65 @@ +# The MIT License (MIT) +# Copyright (c) 2010 Benjamin Peterson + +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: + +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. + +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, +# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR +# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE +# OR OTHER DEALINGS IN THE SOFTWARE. + +"""Finalization with weakrefs + +This is designed for avoiding __del__. +""" +from __future__ import print_function + +import sys +import traceback +import weakref + +__author__ = "Benjamin Peterson " + + +class OwnerRef(weakref.ref): + """A simple weakref.ref subclass, so attributes can be added.""" + pass + + +def _run_finalizer(ref): + """Internal weakref callback to run finalizers""" + del _finalize_refs[id(ref)] + finalizer = ref.finalizer + item = ref.item + try: + finalizer(item) + except Exception: # pragma: no cover + print("Exception running {}:".format(finalizer), file=sys.stderr) + traceback.print_exc() + + +_finalize_refs = {} + + +def track_for_finalization(owner, item, finalizer): + """Register an object for finalization. + + ``owner`` is the the object which is responsible for ``item``. + ``finalizer`` will be called with ``item`` as its only argument when + ``owner`` is destroyed by the garbage collector. + """ + ref = OwnerRef(owner, _run_finalizer) + ref.item = item + ref.finalizer = finalizer + _finalize_refs[id(ref)] = ref diff --git a/python/olm/account.py b/python/olm/account.py new file mode 100644 index 0000000..5705fe3 --- /dev/null +++ b/python/olm/account.py @@ -0,0 +1,239 @@ +# -*- coding: utf-8 -*- +# libolm python bindings +# Copyright © 2015-2017 OpenMarket Ltd +# Copyright © 2018 Damir Jelić +"""libolm Account module. + +This module contains the account part of the Olm library. It contains a single +Account class which handles the creation of new accounts as well as the storing +and restoring of them. + +Examples: + >>> acc = Account() + >>> account.identity_keys() + >>> account.generate_one_time_keys(1) + +""" + +import json +# pylint: disable=redefined-builtin,unused-import +from builtins import bytes, super +from typing import AnyStr, Dict, Optional, Type + +from future.utils import bytes_to_native_str + +# pylint: disable=no-name-in-module +from _libolm import ffi, lib # type: ignore + +from ._compat import URANDOM, to_bytes +from ._finalize import track_for_finalization + +# This is imported only for type checking purposes +if False: + from .session import Session # pragma: no cover + + +def _clear_account(account): + # type: (ffi.cdata) -> None + lib.olm_clear_account(account) + + +class OlmAccountError(Exception): + """libolm Account error exception.""" + + +class Account(object): + """libolm Account class.""" + + def __new__(cls): + # type: (Type[Account]) -> Account + obj = super().__new__(cls) + obj._buf = ffi.new("char[]", lib.olm_account_size()) + obj._account = lib.olm_account(obj._buf) + track_for_finalization(obj, obj._account, _clear_account) + return obj + + def __init__(self): + # type: () -> None + """Create a new Olm account. + + Creates a new account and its matching identity key pair. + + Raises OlmAccountError on failure. If there weren't enough random bytes + for the account creation the error message for the exception will be + NOT_ENOUGH_RANDOM. + """ + # This is needed to silence mypy not knowing the type of _account. + # There has to be a better way for this. + if False: # pragma: no cover + self._account = self._account # type: ffi.cdata + + random_length = lib.olm_create_account_random_length(self._account) + random = URANDOM(random_length) + random_buffer = ffi.new("char[]", random) + + self._check_error( + lib.olm_create_account(self._account, random_buffer, + random_length)) + + def _check_error(self, ret): + # type: (int) -> None + if ret != lib.olm_error(): + return + + last_error = bytes_to_native_str( + ffi.string((lib.olm_account_last_error(self._account)))) + + raise OlmAccountError(last_error) + + def pickle(self, passphrase=""): + # type: (Optional[str]) -> bytes + """Store an Olm account. + + Stores an account as a base64 string. Encrypts the account using the + supplied passphrase. Returns a byte object containing the base64 + encoded string of the pickled account. Raises OlmAccountError on + failure. + + Args: + passphrase(str, optional): The passphrase to be used to encrypt + the account. + """ + byte_key = bytes(passphrase, "utf-8") if passphrase else b"" + key_buffer = ffi.new("char[]", byte_key) + + pickle_length = lib.olm_pickle_account_length(self._account) + pickle_buffer = ffi.new("char[]", pickle_length) + + self._check_error( + lib.olm_pickle_account(self._account, key_buffer, len(byte_key), + pickle_buffer, pickle_length)) + return ffi.unpack(pickle_buffer, pickle_length) + + @classmethod + def from_pickle(cls, pickle, passphrase=""): + # type: (bytes, Optional[str]) -> Account + """Load a previously stored olm account. + + Loads an account from a pickled base64-encoded string and returns an + Account object. Decrypts the account using the supplied passphrase. + Raises OlmAccountError on failure. If the passphrase doesn't match the + one used to encrypt the account then the error message for the + exception will be "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded + then the error message will be "INVALID_BASE64". + + Args: + pickle(bytes): Base64 encoded byte string containing the pickled + account + passphrase(str, optional): The passphrase used to encrypt the + account. + """ + if not pickle: + raise ValueError("Pickle can't be empty") + + byte_key = bytes(passphrase, "utf-8") if passphrase else b"" + key_buffer = ffi.new("char[]", byte_key) + pickle_buffer = ffi.new("char[]", pickle) + + obj = cls.__new__(cls) + + ret = lib.olm_unpickle_account(obj._account, key_buffer, len(byte_key), + pickle_buffer, len(pickle)) + obj._check_error(ret) + + return obj + + @property + def identity_keys(self): + # type: () -> Dict[str, str] + """dict: Public part of the identity keys of the account.""" + out_length = lib.olm_account_identity_keys_length(self._account) + out_buffer = ffi.new("char[]", out_length) + + self._check_error( + lib.olm_account_identity_keys(self._account, out_buffer, + out_length)) + return json.loads(ffi.unpack(out_buffer, out_length).decode("utf-8")) + + def sign(self, message): + # type: (AnyStr) -> str + """Signs a message with this account. + + Signs a message with the private ed25519 identity key of this account. + Returns the signature. + Raises OlmAccountError on failure. + + Args: + message(str): The message to sign. + """ + bytes_message = to_bytes(message) + out_length = lib.olm_account_signature_length(self._account) + message_buffer = ffi.new("char[]", bytes_message) + out_buffer = ffi.new("char[]", out_length) + + self._check_error( + lib.olm_account_sign(self._account, message_buffer, + len(bytes_message), out_buffer, out_length)) + + return bytes_to_native_str(ffi.unpack(out_buffer, out_length)) + + @property + def max_one_time_keys(self): + # type: () -> int + """int: The maximum number of one-time keys the account can store.""" + return lib.olm_account_max_number_of_one_time_keys(self._account) + + def mark_keys_as_published(self): + # type: () -> None + """Mark the current set of one-time keys as being published.""" + lib.olm_account_mark_keys_as_published(self._account) + + def generate_one_time_keys(self, count): + # type: (int) -> None + """Generate a number of new one-time keys. + + If the total number of keys stored by this account exceeds + max_one_time_keys() then the old keys are discarded. + Raises OlmAccountError on error. If the number of random bytes is + too small then the error message of the exception will be + NOT_ENOUGH_RANDOM. + + Args: + count(int): The number of keys to generate. + """ + random_length = lib.olm_account_generate_one_time_keys_random_length( + self._account, count) + random = URANDOM(random_length) + random_buffer = ffi.new("char[]", random) + self._check_error( + lib.olm_account_generate_one_time_keys( + self._account, count, random_buffer, random_length)) + + @property + def one_time_keys(self): + # type: () -> Dict[str, Dict[str, str]] + """dict: The public part of the one-time keys for this account.""" + out_length = lib.olm_account_one_time_keys_length(self._account) + out_buffer = ffi.new("char[]", out_length) + + self._check_error( + lib.olm_account_one_time_keys(self._account, out_buffer, + out_length)) + + return json.loads(ffi.unpack(out_buffer, out_length).decode("utf-8")) + + def remove_one_time_keys(self, session): + # type: (Session) -> None + """Remove used one-time keys. + + Removes the one-time keys that the session used from the account. + Raises OlmAccountError on failure. If the account doesn't have any + matching one-time keys then the error message of the exception will be + "BAD_MESSAGE_KEY_ID". + + Args: + session(Session): An Olm Session object that was created with this + account. + """ + self._check_error(lib.olm_remove_one_time_keys(self._account, + session._session)) diff --git a/python/olm/group_session.py b/python/olm/group_session.py new file mode 100644 index 0000000..6b13c60 --- /dev/null +++ b/python/olm/group_session.py @@ -0,0 +1,467 @@ +# -*- coding: utf-8 -*- +# libolm python bindings +# Copyright © 2015-2017 OpenMarket Ltd +# Copyright © 2018 Damir Jelić +"""libolm Group session module. + +This module contains the group session part of the Olm library. It contains two +classes for creating inbound and outbound group sessions. + +Examples: + >>> outbound = OutboundGroupSession() + >>> InboundGroupSession(outbound.session_key) +""" + +# pylint: disable=redefined-builtin,unused-import +from builtins import bytes, super +from typing import AnyStr, Optional, Tuple, Type + +from future.utils import bytes_to_native_str + +# pylint: disable=no-name-in-module +from _libolm import ffi, lib # type: ignore + +from ._compat import URANDOM, to_bytes +from ._finalize import track_for_finalization + + +def _clear_inbound_group_session(session): + # type: (ffi.cdata) -> None + lib.olm_clear_inbound_group_session(session) + + +def _clear_outbound_group_session(session): + # type: (ffi.cdata) -> None + lib.olm_clear_outbound_group_session(session) + + +class OlmGroupSessionError(Exception): + """libolm Group session error exception.""" + + +class InboundGroupSession(object): + """Inbound group session for encrypted multiuser communication.""" + + def __new__( + cls, # type: Type[InboundGroupSession] + session_key=None # type: Optional[str] + ): + # type: (...) -> InboundGroupSession + obj = super().__new__(cls) + obj._buf = ffi.new("char[]", lib.olm_inbound_group_session_size()) + obj._session = lib.olm_inbound_group_session(obj._buf) + track_for_finalization(obj, obj._session, _clear_inbound_group_session) + return obj + + def __init__(self, session_key): + # type: (AnyStr) -> None + """Create a new inbound group session. + Start a new inbound group session, from a key exported from + an outbound group session. + + Raises OlmGroupSessionError on failure. The error message of the + exception will be "OLM_INVALID_BASE64" if the session key is not valid + base64 and "OLM_BAD_SESSION_KEY" if the session key is invalid. + """ + if False: # pragma: no cover + self._session = self._session # type: ffi.cdata + + byte_session_key = to_bytes(session_key) + + key_buffer = ffi.new("char[]", byte_session_key) + ret = lib.olm_init_inbound_group_session( + self._session, key_buffer, len(byte_session_key) + ) + self._check_error(ret) + + def pickle(self, passphrase=""): + # type: (Optional[str]) -> bytes + """Store an inbound group session. + + Stores a group session as a base64 string. Encrypts the session using + the supplied passphrase. Returns a byte object containing the base64 + encoded string of the pickled session. + + Args: + passphrase(str, optional): The passphrase to be used to encrypt + the session. + """ + byte_passphrase = bytes(passphrase, "utf-8") if passphrase else b"" + + passphrase_buffer = ffi.new("char[]", byte_passphrase) + pickle_length = lib.olm_pickle_inbound_group_session_length( + self._session) + pickle_buffer = ffi.new("char[]", pickle_length) + + ret = lib.olm_pickle_inbound_group_session( + self._session, passphrase_buffer, len(byte_passphrase), + pickle_buffer, pickle_length + ) + + self._check_error(ret) + + return ffi.unpack(pickle_buffer, pickle_length) + + @classmethod + def from_pickle(cls, pickle, passphrase=""): + # type: (bytes, Optional[str]) -> InboundGroupSession + """Load a previously stored inbound group session. + + Loads an inbound group session from a pickled base64 string and returns + an InboundGroupSession object. Decrypts the session using the supplied + passphrase. Raises OlmSessionError on failure. If the passphrase + doesn't match the one used to encrypt the session then the error + message for the exception will be "BAD_ACCOUNT_KEY". If the base64 + couldn't be decoded then the error message will be "INVALID_BASE64". + + Args: + pickle(bytes): Base64 encoded byte string containing the pickled + session + passphrase(str, optional): The passphrase used to encrypt the + session + """ + if not pickle: + raise ValueError("Pickle can't be empty") + + byte_passphrase = bytes(passphrase, "utf-8") if passphrase else b"" + passphrase_buffer = ffi.new("char[]", byte_passphrase) + pickle_buffer = ffi.new("char[]", pickle) + + obj = cls.__new__(cls) + + ret = lib.olm_unpickle_inbound_group_session( + obj._session, + passphrase_buffer, + len(byte_passphrase), + pickle_buffer, + len(pickle) + ) + obj._check_error(ret) + + return obj + + def _check_error(self, ret): + # type: (int) -> None + if ret != lib.olm_error(): + return + + last_error = bytes_to_native_str(ffi.string( + lib.olm_inbound_group_session_last_error(self._session))) + + raise OlmGroupSessionError(last_error) + + def decrypt(self, ciphertext): + # type: (AnyStr) -> Tuple[str, int] + """Decrypt a message + + Returns a tuple of the decrypted plain-text and the message index of + the decrypted message or raises OlmGroupSessionError on failure. + On failure the error message of the exception will be: + + * OLM_INVALID_BASE64 if the message is not valid base64 + * OLM_BAD_MESSAGE_VERSION if the message was encrypted with an + unsupported version of the protocol + * OLM_BAD_MESSAGE_FORMAT if the message headers could not be + decoded + * OLM_BAD_MESSAGE_MAC if the message could not be verified + * OLM_UNKNOWN_MESSAGE_INDEX if we do not have a session key + corresponding to the message's index (i.e., it was sent before + the session key was shared with us) + + Args: + ciphertext(str): Base64 encoded ciphertext containing the encrypted + message + """ + if not ciphertext: + raise ValueError("Ciphertext can't be empty.") + + byte_ciphertext = to_bytes(ciphertext) + + ciphertext_buffer = ffi.new("char[]", byte_ciphertext) + + max_plaintext_length = lib.olm_group_decrypt_max_plaintext_length( + self._session, ciphertext_buffer, len(byte_ciphertext) + ) + plaintext_buffer = ffi.new("char[]", max_plaintext_length) + ciphertext_buffer = ffi.new("char[]", byte_ciphertext) + + message_index = ffi.new("uint32_t*") + plaintext_length = lib.olm_group_decrypt( + self._session, ciphertext_buffer, len(byte_ciphertext), + plaintext_buffer, max_plaintext_length, + message_index + ) + + self._check_error(plaintext_length) + + return bytes_to_native_str(ffi.unpack( + plaintext_buffer, + plaintext_length + )), message_index[0] + + @property + def id(self): + # type: () -> str + """str: A base64 encoded identifier for this session.""" + id_length = lib.olm_inbound_group_session_id_length(self._session) + id_buffer = ffi.new("char[]", id_length) + ret = lib.olm_inbound_group_session_id( + self._session, + id_buffer, + id_length + ) + self._check_error(ret) + return bytes_to_native_str(ffi.unpack(id_buffer, id_length)) + + @property + def first_known_index(self): + # type: () -> int + """int: The first message index we know how to decrypt.""" + return lib.olm_inbound_group_session_first_known_index(self._session) + + def export_session(self, message_index): + # type: (int) -> str + """Export an inbound group session + + Export the base64-encoded ratchet key for this session, at the given + index, in a format which can be used by import_session(). + + Raises OlmGroupSessionError on failure. The error message for the + exception will be: + + * OLM_UNKNOWN_MESSAGE_INDEX if we do not have a session key + corresponding to the given index (ie, it was sent before the + session key was shared with us) + + Args: + message_index(int): The message index at which the session should + be exported. + """ + + export_length = lib.olm_export_inbound_group_session_length( + self._session) + + export_buffer = ffi.new("char[]", export_length) + ret = lib.olm_export_inbound_group_session( + self._session, + export_buffer, + export_length, + message_index + ) + self._check_error(ret) + return bytes_to_native_str(ffi.unpack(export_buffer, export_length)) + + @classmethod + def import_session(cls, session_key): + # type: (AnyStr) -> InboundGroupSession + """Create an InboundGroupSession from an exported session key. + + Creates an InboundGroupSession with an previously exported session key, + raises OlmGroupSessionError on failure. The error message for the + exception will be: + + * OLM_INVALID_BASE64 if the session_key is not valid base64 + * OLM_BAD_SESSION_KEY if the session_key is invalid + + Args: + session_key(str): The exported session key with which the inbound + group session will be created + """ + obj = cls.__new__(cls) + + byte_session_key = to_bytes(session_key) + + key_buffer = ffi.new("char[]", byte_session_key) + ret = lib.olm_import_inbound_group_session( + obj._session, + key_buffer, + len(byte_session_key) + ) + obj._check_error(ret) + + return obj + + +class OutboundGroupSession(object): + """Outbound group session for encrypted multiuser communication.""" + + def __new__(cls): + # type: (Type[OutboundGroupSession]) -> OutboundGroupSession + obj = super().__new__(cls) + obj._buf = ffi.new("char[]", lib.olm_outbound_group_session_size()) + obj._session = lib.olm_outbound_group_session(obj._buf) + track_for_finalization( + obj, + obj._session, + _clear_outbound_group_session + ) + return obj + + def __init__(self): + # type: () -> None + """Create a new outbound group session. + + Start a new outbound group session. Raises OlmGroupSessionError on + failure. If there weren't enough random bytes for the session creation + the error message for the exception will be NOT_ENOUGH_RANDOM. + """ + if False: # pragma: no cover + self._session = self._session # type: ffi.cdata + + random_length = lib.olm_init_outbound_group_session_random_length( + self._session + ) + random = URANDOM(random_length) + random_buffer = ffi.new("char[]", random) + + ret = lib.olm_init_outbound_group_session( + self._session, random_buffer, random_length + ) + self._check_error(ret) + + def _check_error(self, ret): + # type: (int) -> None + if ret != lib.olm_error(): + return + + last_error = bytes_to_native_str(ffi.string( + lib.olm_outbound_group_session_last_error(self._session) + )) + + raise OlmGroupSessionError(last_error) + + def pickle(self, passphrase=""): + # type: (Optional[str]) -> bytes + """Store an outbound group session. + + Stores a group session as a base64 string. Encrypts the session using + the supplied passphrase. Returns a byte object containing the base64 + encoded string of the pickled session. + + Args: + passphrase(str, optional): The passphrase to be used to encrypt + the session. + """ + byte_passphrase = bytes(passphrase, "utf-8") if passphrase else b"" + passphrase_buffer = ffi.new("char[]", byte_passphrase) + pickle_length = lib.olm_pickle_outbound_group_session_length( + self._session) + pickle_buffer = ffi.new("char[]", pickle_length) + + ret = lib.olm_pickle_outbound_group_session( + self._session, passphrase_buffer, len(byte_passphrase), + pickle_buffer, pickle_length + ) + self._check_error(ret) + return ffi.unpack(pickle_buffer, pickle_length) + + @classmethod + def from_pickle(cls, pickle, passphrase=""): + # type: (bytes, Optional[str]) -> OutboundGroupSession + """Load a previously stored outbound group session. + + Loads an outbound group session from a pickled base64 string and + returns an OutboundGroupSession object. Decrypts the session using the + supplied passphrase. Raises OlmSessionError on failure. If the + passphrase doesn't match the one used to encrypt the session then the + error message for the exception will be "BAD_ACCOUNT_KEY". If the + base64 couldn't be decoded then the error message will be + "INVALID_BASE64". + + Args: + pickle(bytes): Base64 encoded byte string containing the pickled + session + passphrase(str, optional): The passphrase used to encrypt the + """ + if not pickle: + raise ValueError("Pickle can't be empty") + + byte_passphrase = bytes(passphrase, "utf-8") if passphrase else b"" + passphrase_buffer = ffi.new("char[]", byte_passphrase) + pickle_buffer = ffi.new("char[]", pickle) + + obj = cls.__new__(cls) + + ret = lib.olm_unpickle_outbound_group_session( + obj._session, + passphrase_buffer, + len(byte_passphrase), + pickle_buffer, + len(pickle) + ) + obj._check_error(ret) + + return obj + + def encrypt(self, plaintext): + # type: (AnyStr) -> str + """Encrypt a message. + + Returns the encrypted ciphertext. + + Args: + plaintext(str): A string that will be encrypted using the group + session. + """ + byte_plaintext = to_bytes(plaintext) + message_length = lib.olm_group_encrypt_message_length( + self._session, len(byte_plaintext) + ) + + message_buffer = ffi.new("char[]", message_length) + + plaintext_buffer = ffi.new("char[]", byte_plaintext) + + ret = lib.olm_group_encrypt( + self._session, + plaintext_buffer, len(byte_plaintext), + message_buffer, message_length, + ) + self._check_error(ret) + return bytes_to_native_str(ffi.unpack(message_buffer, message_length)) + + @property + def id(self): + # type: () -> str + """str: A base64 encoded identifier for this session.""" + id_length = lib.olm_outbound_group_session_id_length(self._session) + id_buffer = ffi.new("char[]", id_length) + + ret = lib.olm_outbound_group_session_id( + self._session, + id_buffer, + id_length + ) + self._check_error(ret) + + return bytes_to_native_str(ffi.unpack(id_buffer, id_length)) + + @property + def message_index(self): + # type: () -> int + """int: The current message index of the session. + + Each message is encrypted with an increasing index. This is the index + for the next message. + """ + return lib.olm_outbound_group_session_message_index(self._session) + + @property + def session_key(self): + # type: () -> str + """The base64-encoded current ratchet key for this session. + + Each message is encrypted with a different ratchet key. This function + returns the ratchet key that will be used for the next message. + """ + key_length = lib.olm_outbound_group_session_key_length(self._session) + key_buffer = ffi.new("char[]", key_length) + + ret = lib.olm_outbound_group_session_key( + self._session, + key_buffer, + key_length + ) + self._check_error(ret) + + return bytes_to_native_str(ffi.unpack(key_buffer, key_length)) diff --git a/python/olm/session.py b/python/olm/session.py new file mode 100644 index 0000000..b7b2c4b --- /dev/null +++ b/python/olm/session.py @@ -0,0 +1,452 @@ +# -*- coding: utf-8 -*- +# libolm python bindings +# Copyright © 2015-2017 OpenMarket Ltd +# Copyright © 2018 Damir Jelić +"""libolm Session module. + +This module contains the Olm Session part of the Olm library. + +It is used to establish a peer-to-peer encrypted communication channel between +two Olm accounts. + +Examples: + >>> alice = Account() + >>> bob = Account() + >>> bob.generate_one_time_keys(1) + >>> id_key = bob.identity_keys['curve25519'] + >>> one_time = list(bob.one_time_keys["curve25519"].values())[0] + >>> session = OutboundSession(alice, id_key, one_time) + +""" + +# pylint: disable=redefined-builtin,unused-import +from builtins import bytes, super +from typing import AnyStr, Optional, Type + +from future.utils import bytes_to_native_str + +# pylint: disable=no-name-in-module +from _libolm import ffi, lib # type: ignore + +from ._compat import URANDOM, to_bytes +from ._finalize import track_for_finalization + +# This is imported only for type checking purposes +if False: + from .account import Account # pragma: no cover + + +class OlmSessionError(Exception): + """libolm Session exception.""" + + +class _OlmMessage(object): + def __init__(self, ciphertext, message_type): + # type: (AnyStr, ffi.cdata) -> None + if not ciphertext: + raise ValueError("Ciphertext can't be empty") + + # I don't know why mypy wants a type annotation here nor why AnyStr + # doesn't work + self.ciphertext = ciphertext # type: ignore + self.message_type = message_type + + def __str__(self): + # type: () -> str + type_to_prefix = { + lib.OLM_MESSAGE_TYPE_PRE_KEY: "PRE_KEY", + lib.OLM_MESSAGE_TYPE_MESSAGE: "MESSAGE" + } + + prefix = type_to_prefix[self.message_type] + return "{} {}".format(prefix, self.ciphertext) + + +class OlmPreKeyMessage(_OlmMessage): + """Olm prekey message class + + Prekey messages are used to establish an Olm session. After the first + message exchange the session switches to normal messages + """ + + def __init__(self, ciphertext): + # type: (AnyStr) -> None + """Create a new Olm prekey message with the supplied ciphertext + + Args: + ciphertext(str): The ciphertext of the prekey message. + """ + _OlmMessage.__init__(self, ciphertext, lib.OLM_MESSAGE_TYPE_PRE_KEY) + + def __repr__(self): + # type: () -> str + return "OlmPreKeyMessage({})".format(self.ciphertext) + + +class OlmMessage(_OlmMessage): + """Olm message class""" + + def __init__(self, ciphertext): + # type: (AnyStr) -> None + """Create a new Olm message with the supplied ciphertext + + Args: + ciphertext(str): The ciphertext of the message. + """ + _OlmMessage.__init__(self, ciphertext, lib.OLM_MESSAGE_TYPE_MESSAGE) + + def __repr__(self): + # type: () -> str + return "OlmMessage({})".format(self.ciphertext) + + +def _clear_session(session): + # type: (ffi.cdata) -> None + lib.olm_clear_session(session) + + +class Session(object): + """libolm Session class. + This is an abstract class that can't be instantiated except when unpickling + a previously pickled InboundSession or OutboundSession object with + from_pickle. + """ + + def __new__(cls): + # type: (Type[Session]) -> Session + + obj = super().__new__(cls) + obj._buf = ffi.new("char[]", lib.olm_session_size()) + obj._session = lib.olm_session(obj._buf) + track_for_finalization(obj, obj._session, _clear_session) + return obj + + def __init__(self): + # type: () -> None + if type(self) is Session: + raise TypeError("Session class may not be instantiated.") + + if False: + self._session = self._session # type: ffi.cdata + + def _check_error(self, ret): + # type: (int) -> None + if ret != lib.olm_error(): + return + + last_error = bytes_to_native_str( + ffi.string(lib.olm_session_last_error(self._session))) + + raise OlmSessionError(last_error) + + def pickle(self, passphrase=""): + # type: (Optional[str]) -> bytes + """Store an Olm session. + + Stores a session as a base64 string. Encrypts the session using the + supplied passphrase. Returns a byte object containing the base64 + encoded string of the pickled session. Raises OlmSessionError on + failure. + + Args: + passphrase(str, optional): The passphrase to be used to encrypt + the session. + """ + byte_key = bytes(passphrase, "utf-8") if passphrase else b"" + key_buffer = ffi.new("char[]", byte_key) + + pickle_length = lib.olm_pickle_session_length(self._session) + pickle_buffer = ffi.new("char[]", pickle_length) + + self._check_error( + lib.olm_pickle_session(self._session, key_buffer, len(byte_key), + pickle_buffer, pickle_length)) + return ffi.unpack(pickle_buffer, pickle_length) + + @classmethod + def from_pickle(cls, pickle, passphrase=""): + # type: (bytes, Optional[str]) -> Session + """Load a previously stored Olm session. + + Loads a session from a pickled base64 string and returns a Session + object. Decrypts the session using the supplied passphrase. Raises + OlmSessionError on failure. If the passphrase doesn't match the one + used to encrypt the session then the error message for the + exception will be "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded + then the error message will be "INVALID_BASE64". + + Args: + pickle(bytes): Base64 encoded byte string containing the pickled + session + passphrase(str, optional): The passphrase used to encrypt the + session. + """ + if not pickle: + raise ValueError("Pickle can't be empty") + + byte_key = bytes(passphrase, "utf-8") if passphrase else b"" + key_buffer = ffi.new("char[]", byte_key) + pickle_buffer = ffi.new("char[]", pickle) + + session = cls.__new__(cls) + + ret = lib.olm_unpickle_session(session._session, key_buffer, + len(byte_key), pickle_buffer, + len(pickle)) + session._check_error(ret) + + return session + + def encrypt(self, plaintext): + # type: (AnyStr) -> _OlmMessage + """Encrypts a message using the session. Returns the ciphertext as a + base64 encoded string on success. Raises OlmSessionError on failure. If + there weren't enough random bytes to encrypt the message the error + message for the exception will be NOT_ENOUGH_RANDOM. + + Args: + plaintext(str): The plaintext message that will be encrypted. + """ + byte_plaintext = to_bytes(plaintext) + + r_length = lib.olm_encrypt_random_length(self._session) + random = URANDOM(r_length) + random_buffer = ffi.new("char[]", random) + + message_type = lib.olm_encrypt_message_type(self._session) + + self._check_error(message_type) + + ciphertext_length = lib.olm_encrypt_message_length( + self._session, len(plaintext) + ) + ciphertext_buffer = ffi.new("char[]", ciphertext_length) + + plaintext_buffer = ffi.new("char[]", byte_plaintext) + + self._check_error(lib.olm_encrypt( + self._session, + plaintext_buffer, len(byte_plaintext), + random_buffer, r_length, + ciphertext_buffer, ciphertext_length, + )) + + if message_type == lib.OLM_MESSAGE_TYPE_PRE_KEY: + return OlmPreKeyMessage( + bytes_to_native_str(ffi.unpack( + ciphertext_buffer, + ciphertext_length + ))) + elif message_type == lib.OLM_MESSAGE_TYPE_MESSAGE: + return OlmMessage( + bytes_to_native_str(ffi.unpack( + ciphertext_buffer, + ciphertext_length + ))) + else: # pragma: no cover + raise ValueError("Unknown message type") + + def decrypt(self, message): + # type: (_OlmMessage) -> str + """Decrypts a message using the session. Returns the plaintext string + on success. Raises OlmSessionError on failure. If the base64 couldn't + be decoded then the error message will be "INVALID_BASE64". If the + message is for an unsupported version of the protocol the error message + will be "BAD_MESSAGE_VERSION". If the message couldn't be decoded then + the error message will be "BAD_MESSAGE_FORMAT". If the MAC on the + message was invalid then the error message will be "BAD_MESSAGE_MAC". + + Args: + message(OlmMessage): The Olm message that will be decrypted. It can + be either an OlmPreKeyMessage or an OlmMessage. + """ + if not message.ciphertext: + raise ValueError("Ciphertext can't be empty") + + byte_ciphertext = to_bytes(message.ciphertext) + ciphertext_buffer = ffi.new("char[]", byte_ciphertext) + + max_plaintext_length = lib.olm_decrypt_max_plaintext_length( + self._session, message.message_type, ciphertext_buffer, + len(byte_ciphertext) + ) + plaintext_buffer = ffi.new("char[]", max_plaintext_length) + ciphertext_buffer = ffi.new("char[]", byte_ciphertext) + plaintext_length = lib.olm_decrypt( + self._session, message.message_type, ciphertext_buffer, + len(byte_ciphertext), plaintext_buffer, max_plaintext_length + ) + self._check_error(plaintext_length) + return bytes_to_native_str( + ffi.unpack(plaintext_buffer, plaintext_length)) + + @property + def id(self): + # type: () -> str + """str: An identifier for this session. Will be the same for both + ends of the conversation. + """ + id_length = lib.olm_session_id_length(self._session) + id_buffer = ffi.new("char[]", id_length) + + self._check_error( + lib.olm_session_id(self._session, id_buffer, id_length) + ) + return bytes_to_native_str(ffi.unpack(id_buffer, id_length)) + + def matches(self, message, identity_key=None): + # type: (OlmPreKeyMessage, Optional[AnyStr]) -> bool + """Checks if the PRE_KEY message is for this in-bound session. + This can happen if multiple messages are sent to this session before + this session sends a message in reply. Returns True if the session + matches. Returns False if the session does not match. Raises + OlmSessionError on failure. If the base64 couldn't be decoded then the + error message will be "INVALID_BASE64". If the message was for an + unsupported protocol version then the error message will be + "BAD_MESSAGE_VERSION". If the message couldn't be decoded then then the + error message will be * "BAD_MESSAGE_FORMAT". + + Args: + message(OlmPreKeyMessage): The Olm prekey message that will checked + if it is intended for this session. + identity_key(str, optional): The identity key of the sender. To + check if the message was also sent using this identity key. + """ + if not isinstance(message, OlmPreKeyMessage): + raise TypeError("Matches can only be called with prekey messages.") + + if not message.ciphertext: + raise ValueError("Ciphertext can't be empty") + + ret = None + + byte_ciphertext = to_bytes(message.ciphertext) + + message_buffer = ffi.new("char[]", byte_ciphertext) + + if identity_key: + byte_id_key = to_bytes(identity_key) + identity_key_buffer = ffi.new("char[]", byte_id_key) + + ret = lib.olm_matches_inbound_session_from( + self._session, + identity_key_buffer, len(byte_id_key), + message_buffer, len(byte_ciphertext) + ) + + else: + ret = lib.olm_matches_inbound_session( + self._session, + message_buffer, len(byte_ciphertext)) + + self._check_error(ret) + + return bool(ret) + + +class InboundSession(Session): + """Inbound Olm session for p2p encrypted communication. + """ + + def __new__(cls, account, message, identity_key=None): + # type: (Account, OlmPreKeyMessage, Optional[AnyStr]) -> Session + return super().__new__(cls) + + def __init__(self, account, message, identity_key=None): + # type: (Account, OlmPreKeyMessage, Optional[AnyStr]) -> None + """Create a new inbound Olm session. + + Create a new in-bound session for sending/receiving messages from an + incoming prekey message. Raises OlmSessionError on failure. If the + base64 couldn't be decoded then error message will be "INVALID_BASE64". + If the message was for an unsupported protocol version then + the errror message will be "BAD_MESSAGE_VERSION". If the message + couldn't be decoded then then the error message will be + "BAD_MESSAGE_FORMAT". If the message refers to an unknown one-time + key then the error message will be "BAD_MESSAGE_KEY_ID". + + Args: + account(Account): The Olm Account that will be used to create this + session. + message(OlmPreKeyMessage): The Olm prekey message that will checked + that will be used to create this session. + identity_key(str, optional): The identity key of the sender. To + check if the message was also sent using this identity key. + """ + if not message.ciphertext: + raise ValueError("Ciphertext can't be empty") + + super().__init__() + byte_ciphertext = to_bytes(message.ciphertext) + message_buffer = ffi.new("char[]", byte_ciphertext) + + if identity_key: + byte_id_key = to_bytes(identity_key) + identity_key_buffer = ffi.new("char[]", byte_id_key) + self._check_error(lib.olm_create_inbound_session_from( + self._session, + account._account, + identity_key_buffer, len(byte_id_key), + message_buffer, len(byte_ciphertext) + )) + else: + self._check_error(lib.olm_create_inbound_session( + self._session, + account._account, + message_buffer, len(byte_ciphertext) + )) + + +class OutboundSession(Session): + """Outbound Olm session for p2p encrypted communication.""" + + def __new__(cls, account, identity_key, one_time_key): + # type: (Account, AnyStr, AnyStr) -> Session + return super().__new__(cls) + + def __init__(self, account, identity_key, one_time_key): + # type: (Account, AnyStr, AnyStr) -> None + """Create a new outbound Olm session. + + Creates a new outbound session for sending messages to a given + identity key and one-time key. + + Raises OlmSessionError on failure. If the keys couldn't be decoded as + base64 then the error message will be "INVALID_BASE64". If there + weren't enough random bytes for the session creation the error message + for the exception will be NOT_ENOUGH_RANDOM. + + Args: + account(Account): The Olm Account that will be used to create this + session. + identity_key(str): The identity key of the person with whom we want + to start the session. + one_time_key(str): A one-time key from the person with whom we want + to start the session. + """ + if not identity_key: + raise ValueError("Identity key can't be empty") + + if not one_time_key: + raise ValueError("One-time key can't be empty") + + super().__init__() + + byte_id_key = to_bytes(identity_key) + byte_one_time = to_bytes(one_time_key) + + session_random_length = lib.olm_create_outbound_session_random_length( + self._session) + + random = URANDOM(session_random_length) + random_buffer = ffi.new("char[]", random) + identity_key_buffer = ffi.new("char[]", byte_id_key) + one_time_key_buffer = ffi.new("char[]", byte_one_time) + + self._check_error(lib.olm_create_outbound_session( + self._session, + account._account, + identity_key_buffer, len(byte_id_key), + one_time_key_buffer, len(byte_one_time), + random_buffer, session_random_length + )) diff --git a/python/olm/utility.py b/python/olm/utility.py new file mode 100644 index 0000000..838cf3f --- /dev/null +++ b/python/olm/utility.py @@ -0,0 +1,91 @@ +# -*- coding: utf-8 -*- +# libolm python bindings +# Copyright © 2015-2017 OpenMarket Ltd +# Copyright © 2018 Damir Jelić +"""libolm Utility module. + +This module contains utilities for olm. +It only contains the ed25519_verify function for signature verification. + +Examples: + >>> alice = Account() + + >>> message = "Test" + >>> signature = alice.sign(message) + >>> signing_key = alice.identity_keys["ed25519"] + + >>> ed25519_verify(signing_key, message, signature) + +""" + +# pylint: disable=redefined-builtin,unused-import +from typing import AnyStr, Type + +# pylint: disable=no-name-in-module +from _libolm import ffi, lib # type: ignore + +from ._compat import to_bytes +from ._finalize import track_for_finalization + + +def _clear_utility(utility): # pragma: no cover + # type: (ffi.cdata) -> None + lib.olm_clear_utility(utility) + + +class OlmVerifyError(Exception): + """libolm signature verification exception.""" + + +class _Utility(object): + # pylint: disable=too-few-public-methods + """libolm Utility class.""" + + _buf = None + _utility = None + + @classmethod + def _allocate(cls): + # type: (Type[_Utility]) -> None + cls._buf = ffi.new("char[]", lib.olm_utility_size()) + cls._utility = lib.olm_utility(cls._buf) + track_for_finalization(cls, cls._utility, _clear_utility) + + @classmethod + def _check_error(cls, ret): + # type: (int) -> None + if ret != lib.olm_error(): + return + + raise OlmVerifyError("{}".format( + ffi.string(lib.olm_utility_last_error( + cls._utility)).decode("utf-8"))) + + @classmethod + def _ed25519_verify(cls, key, message, signature): + # type: (Type[_Utility], AnyStr, AnyStr, AnyStr) -> None + if not cls._utility: + cls._allocate() + + byte_key = to_bytes(key) + byte_message = to_bytes(message) + byte_signature = to_bytes(signature) + + cls._check_error( + lib.olm_ed25519_verify(cls._utility, byte_key, len(byte_key), + byte_message, len(byte_message), + byte_signature, len(byte_signature))) + + +def ed25519_verify(key, message, signature): + # type: (AnyStr, AnyStr, AnyStr) -> None + """Verify an ed25519 signature. + + Raises an OlmVerifyError if verification fails. + + Args: + key(str): The ed25519 public key used for signing. + message(str): The signed message. + signature(bytes): The message signature. + """ + return _Utility._ed25519_verify(key, message, signature) diff --git a/python/olm_build.py b/python/olm_build.py new file mode 100644 index 0000000..5ffefc2 --- /dev/null +++ b/python/olm_build.py @@ -0,0 +1,40 @@ +# -*- coding: utf-8 -*- + +# libolm python bindings +# Copyright © 2018 Damir Jelić +# +# Permission to use, copy, modify, and/or distribute this software for +# any purpose with or without fee is hereby granted, provided that the +# above copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +# SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER +# RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF +# CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +from __future__ import unicode_literals + +import os + +from cffi import FFI + +ffibuilder = FFI() +PATH = os.path.dirname(__file__) + + +ffibuilder.set_source( + "_libolm", + r""" + #include + #include + #include + """, libraries=["olm"]) + +with open(os.path.join(PATH, "include/olm/olm.h")) as f: + ffibuilder.cdef(f.read(), override=True) + +if __name__ == "__main__": + ffibuilder.compile(verbose=True) diff --git a/python/requirements.txt b/python/requirements.txt new file mode 100644 index 0000000..c627b85 --- /dev/null +++ b/python/requirements.txt @@ -0,0 +1,3 @@ +future +cffi +typing diff --git a/python/setup.cfg b/python/setup.cfg new file mode 100644 index 0000000..d10b7e4 --- /dev/null +++ b/python/setup.cfg @@ -0,0 +1,8 @@ +[tool:pytest] +testpaths = tests +flake8-ignore = + olm/*.py F401 + tests/*.py W503 + +[coverage:run] +omit=olm/__version__.py diff --git a/python/setup.py b/python/setup.py new file mode 100644 index 0000000..4b0deb1 --- /dev/null +++ b/python/setup.py @@ -0,0 +1,27 @@ +# -*- coding: utf-8 -*- + +import os +from codecs import open + +from setuptools import setup + +here = os.path.abspath(os.path.dirname(__file__)) + +about = {} +with open(os.path.join(here, "olm", "__version__.py"), "r", "utf-8") as f: + exec(f.read(), about) + +setup( + name=about["__title__"], + version=about["__version__"], + description=about["__description__"], + author=about["__author__"], + author_email=about["__author_email__"], + url=about["__url__"], + license=about["__license__"], + packages=["olm"], + setup_requires=["cffi>=1.0.0"], + cffi_modules=["olm_build.py:ffibuilder"], + install_requires=["cffi>=1.0.0", "future", "typing"], + zip_safe=False +) diff --git a/python/test-requirements.txt b/python/test-requirements.txt new file mode 100644 index 0000000..eb89250 --- /dev/null +++ b/python/test-requirements.txt @@ -0,0 +1,7 @@ +pytest +hypothesis +pytest-flake8 +pytest-isort +pytest-cov +pytest-benchmark +aspectlib diff --git a/python/tests/account_test.py b/python/tests/account_test.py new file mode 100644 index 0000000..4fef72c --- /dev/null +++ b/python/tests/account_test.py @@ -0,0 +1,100 @@ +from builtins import int + +import pytest +from hypothesis import given +from hypothesis.strategies import text + +from olm import Account, OlmAccountError, OlmVerifyError, ed25519_verify +from olm._compat import to_bytes + + +class TestClass(object): + def test_to_bytes(self): + assert isinstance(to_bytes("a"), bytes) + assert isinstance(to_bytes(u"a"), bytes) + assert isinstance(to_bytes(b"a"), bytes) + assert isinstance(to_bytes(r"a"), bytes) + with pytest.raises(TypeError): + to_bytes(0) + + def test_account_creation(self): + alice = Account() + assert alice.identity_keys + assert len(alice.identity_keys) == 2 + + def test_account_pickle(self): + alice = Account() + pickle = alice.pickle() + assert (alice.identity_keys == Account.from_pickle(pickle) + .identity_keys) + + def test_invalid_unpickle(self): + with pytest.raises(ValueError): + Account.from_pickle(b"") + + def test_passphrase_pickle(self): + alice = Account() + passphrase = "It's a secret to everybody" + pickle = alice.pickle(passphrase) + assert (alice.identity_keys == Account.from_pickle( + pickle, passphrase).identity_keys) + + def test_wrong_passphrase_pickle(self): + alice = Account() + passphrase = "It's a secret to everybody" + pickle = alice.pickle(passphrase) + + with pytest.raises(OlmAccountError): + Account.from_pickle(pickle, "") + + def test_one_time_keys(self): + alice = Account() + alice.generate_one_time_keys(10) + one_time_keys = alice.one_time_keys + assert one_time_keys + assert len(one_time_keys["curve25519"]) == 10 + + def test_max_one_time_keys(self): + alice = Account() + assert isinstance(alice.max_one_time_keys, int) + + def test_publish_one_time_keys(self): + alice = Account() + alice.generate_one_time_keys(10) + one_time_keys = alice.one_time_keys + + assert one_time_keys + assert len(one_time_keys["curve25519"]) == 10 + + alice.mark_keys_as_published() + assert not alice.one_time_keys["curve25519"] + + def test_clear(self): + alice = Account() + del alice + + @given(text()) + def test_valid_signature(self, message): + alice = Account() + + signature = alice.sign(message) + signing_key = alice.identity_keys["ed25519"] + + assert signature + assert signing_key + + ed25519_verify(signing_key, message, signature) + + @given(text()) + def test_invalid_signature(self, message): + alice = Account() + bob = Account() + + signature = alice.sign(message) + signing_key = bob.identity_keys["ed25519"] + + assert signature + assert signing_key + + with pytest.raises(OlmVerifyError): + ed25519_verify(signing_key, message, signature) diff --git a/python/tests/group_session_test.py b/python/tests/group_session_test.py new file mode 100644 index 0000000..c17e84f --- /dev/null +++ b/python/tests/group_session_test.py @@ -0,0 +1,114 @@ +import pytest + +from olm import InboundGroupSession, OlmGroupSessionError, OutboundGroupSession + + +class TestClass(object): + def test_session_create(self): + OutboundGroupSession() + + def test_session_id(self): + session = OutboundGroupSession() + assert isinstance(session.id, str) + + def test_session_index(self): + session = OutboundGroupSession() + assert isinstance(session.message_index, int) + assert session.message_index == 0 + + def test_outbound_pickle(self): + session = OutboundGroupSession() + pickle = session.pickle() + + assert (session.id == OutboundGroupSession.from_pickle( + pickle).id) + + def test_invalid_unpickle(self): + with pytest.raises(ValueError): + OutboundGroupSession.from_pickle(b"") + + with pytest.raises(ValueError): + InboundGroupSession.from_pickle(b"") + + def test_inbound_create(self): + outbound = OutboundGroupSession() + InboundGroupSession(outbound.session_key) + + def test_invalid_decrypt(self): + outbound = OutboundGroupSession() + inbound = InboundGroupSession(outbound.session_key) + + with pytest.raises(ValueError): + inbound.decrypt("") + + def test_inbound_pickle(self): + outbound = OutboundGroupSession() + inbound = InboundGroupSession(outbound.session_key) + pickle = inbound.pickle() + InboundGroupSession.from_pickle(pickle) + + def test_inbound_export(self): + outbound = OutboundGroupSession() + inbound = InboundGroupSession(outbound.session_key) + imported = InboundGroupSession.import_session( + inbound.export_session(inbound.first_known_index) + ) + assert "Test", 0 == imported.decrypt(outbound.encrypt("Test")) + + def test_first_index(self): + outbound = OutboundGroupSession() + inbound = InboundGroupSession(outbound.session_key) + index = inbound.first_known_index + assert isinstance(index, int) + + def test_encrypt(self, benchmark): + benchmark.weave(OutboundGroupSession.encrypt, lazy=True) + outbound = OutboundGroupSession() + inbound = InboundGroupSession(outbound.session_key) + assert "Test", 0 == inbound.decrypt(outbound.encrypt("Test")) + + def test_decrypt(self, benchmark): + benchmark.weave(InboundGroupSession.decrypt, lazy=True) + outbound = OutboundGroupSession() + inbound = InboundGroupSession(outbound.session_key) + assert "Test", 0 == inbound.decrypt(outbound.encrypt("Test")) + + def test_decrypt_twice(self): + outbound = OutboundGroupSession() + inbound = InboundGroupSession(outbound.session_key) + outbound.encrypt("Test 1") + message, index = inbound.decrypt(outbound.encrypt("Test 2")) + assert isinstance(index, int) + assert ("Test 2", 1) == (message, index) + + def test_decrypt_failure(self): + outbound = OutboundGroupSession() + inbound = InboundGroupSession(outbound.session_key) + eve_outbound = OutboundGroupSession() + with pytest.raises(OlmGroupSessionError): + inbound.decrypt(eve_outbound.encrypt("Test")) + + def test_id(self): + outbound = OutboundGroupSession() + inbound = InboundGroupSession(outbound.session_key) + assert outbound.id == inbound.id + + def test_inbound_fail(self): + with pytest.raises(TypeError): + InboundGroupSession() + + def test_oubtound_pickle_fail(self): + outbound = OutboundGroupSession() + pickle = outbound.pickle("Test") + + with pytest.raises(OlmGroupSessionError): + OutboundGroupSession.from_pickle(pickle) + + def test_outbound_clear(self): + session = OutboundGroupSession() + del session + + def test_inbound_clear(self): + outbound = OutboundGroupSession() + inbound = InboundGroupSession(outbound.session_key) + del inbound diff --git a/python/tests/session_test.py b/python/tests/session_test.py new file mode 100644 index 0000000..ab1c38b --- /dev/null +++ b/python/tests/session_test.py @@ -0,0 +1,143 @@ +import pytest + +from olm import (Account, InboundSession, OlmMessage, OlmPreKeyMessage, + OlmSessionError, OutboundSession, Session) + + +class TestClass(object): + def _create_session(self): + alice = Account() + bob = Account() + bob.generate_one_time_keys(1) + id_key = bob.identity_keys["curve25519"] + one_time = list(bob.one_time_keys["curve25519"].values())[0] + session = OutboundSession(alice, id_key, one_time) + return alice, bob, session + + def test_session_create(self): + _, _, session_1 = self._create_session() + _, _, session_2 = self._create_session() + assert session_1 + assert session_2 + assert session_1.id != session_2.id + assert isinstance(session_1.id, str) + + def test_session_clear(self): + _, _, session = self._create_session() + del session + + def test_invalid_session_create(self): + with pytest.raises(TypeError): + Session() + + def test_session_pickle(self): + alice, bob, session = self._create_session() + Session.from_pickle(session.pickle()).id == session.id + + def test_session_invalid_pickle(self): + with pytest.raises(ValueError): + Session.from_pickle(b"") + + def test_wrong_passphrase_pickle(self): + alice, bob, session = self._create_session() + passphrase = "It's a secret to everybody" + pickle = alice.pickle(passphrase) + + with pytest.raises(OlmSessionError): + Session.from_pickle(pickle, "") + + def test_encrypt(self): + plaintext = "It's a secret to everybody" + alice, bob, session = self._create_session() + message = session.encrypt(plaintext) + + assert (repr(message) + == "OlmPreKeyMessage({})".format(message.ciphertext)) + + assert (str(message) + == "PRE_KEY {}".format(message.ciphertext)) + + bob_session = InboundSession(bob, message) + assert plaintext == bob_session.decrypt(message) + + def test_empty_message(self): + with pytest.raises(ValueError): + OlmPreKeyMessage("") + empty = OlmPreKeyMessage("x") + empty.ciphertext = "" + alice, bob, session = self._create_session() + + with pytest.raises(ValueError): + session.decrypt(empty) + + def test_inbound_with_id(self): + plaintext = "It's a secret to everybody" + alice, bob, session = self._create_session() + message = session.encrypt(plaintext) + alice_id = alice.identity_keys["curve25519"] + bob_session = InboundSession(bob, message, alice_id) + assert plaintext == bob_session.decrypt(message) + + def test_two_messages(self): + plaintext = "It's a secret to everybody" + alice, bob, session = self._create_session() + message = session.encrypt(plaintext) + alice_id = alice.identity_keys["curve25519"] + bob_session = InboundSession(bob, message, alice_id) + bob.remove_one_time_keys(bob_session) + assert plaintext == bob_session.decrypt(message) + + bob_plaintext = "Grumble, Grumble" + bob_message = bob_session.encrypt(bob_plaintext) + + assert (repr(bob_message) + == "OlmMessage({})".format(bob_message.ciphertext)) + + assert bob_plaintext == session.decrypt(bob_message) + + def test_matches(self): + plaintext = "It's a secret to everybody" + alice, bob, session = self._create_session() + message = session.encrypt(plaintext) + alice_id = alice.identity_keys["curve25519"] + bob_session = InboundSession(bob, message, alice_id) + assert plaintext == bob_session.decrypt(message) + + message_2nd = session.encrypt("Hey! Listen!") + + assert bob_session.matches(message_2nd) is True + assert bob_session.matches(message_2nd, alice_id) is True + + def test_invalid(self): + alice, bob, session = self._create_session() + message = OlmMessage("x") + + with pytest.raises(TypeError): + session.matches(message) + + message = OlmPreKeyMessage("x") + message.ciphertext = "" + + with pytest.raises(ValueError): + session.matches(message) + + with pytest.raises(ValueError): + InboundSession(bob, message) + + with pytest.raises(ValueError): + OutboundSession(alice, "", "x") + + with pytest.raises(ValueError): + OutboundSession(alice, "x", "") + + def test_doesnt_match(self): + plaintext = "It's a secret to everybody" + alice, bob, session = self._create_session() + message = session.encrypt(plaintext) + alice_id = alice.identity_keys["curve25519"] + bob_session = InboundSession(bob, message, alice_id) + + _, _, new_session = self._create_session() + + new_message = new_session.encrypt(plaintext) + assert bob_session.matches(new_message) is False diff --git a/python/tox.ini b/python/tox.ini new file mode 100644 index 0000000..e3a0188 --- /dev/null +++ b/python/tox.ini @@ -0,0 +1,43 @@ +# content of: tox.ini , put in same dir as setup.py +[tox] +envlist = py27,py36,pypy,{py2,py3}-cov,coverage +[testenv] +basepython = + py27: python2.7 + py36: python3.6 + pypy: pypy + py2: python2.7 + py3: python3.6 + +deps = -rrequirements.txt + -rtest-requirements.txt + +passenv = TOXENV CI TRAVIS TRAVIS_* +commands = pytest --benchmark-disable +usedevelop = True + +[testenv:py2-cov] +commands = + pytest --cov-report term-missing --cov=olm --benchmark-disable --cov-branch +setenv = + COVERAGE_FILE=.coverage.py2 + +[testenv:py3-cov] +commands = + py.test --cov=olm --cov-report term-missing --benchmark-disable --cov-branch +setenv = + COVERAGE_FILE=.coverage.py3 + +[testenv:coverage] +basepython = python3.6 +commands = + coverage erase + coverage combine + coverage xml + coverage report --show-missing + codecov -e TOXENV +deps = + coverage + codecov>=1.4.0 +setenv = + COVERAGE_FILE=.coverage