libsignal 0.0.0

libsignal-python
================

Signal encryption library for Python.

|Maturity| |License| |Version|

About
-----

This is a python port of
`libsignal-protocol-java <https://github.com/WhisperSystems/libaxolotl-android>`__
originally written by `Moxie Marlinspike <https://github.com/moxie0>`__

Compare with
`libsignal-protocol-php <https://github.com/albert-chin/libsignal-protocol-php>`__
forked from
`libaxolotl-php <https://github.com/mgp25/libaxolotl-php>`__, which is a
php port.

Overview from original author’s:

This is a ratcheting forward secrecy protocol that works in
synchronous and asynchronous messaging environments. The protocol
overview is available
`here <https://github.com/trevp/axolotl/wiki>`__, and the details of
the wire format are available
`here <https://github.com/trevp/axolotl/wiki>`__.

Read rest of of details
`here <https://github.com/WhisperSystems/libaxolotl-android/blob/master/README.md>`__.

Installation
------------

The library has some dependencies which are automatically pulled and
installed if you use the instructions below for your OS

- `protobuf 3.6+ <https://github.com/google/protobuf/>`__
- `cryptography <https://cryptography.io>`__
- `python-axolotl-curve25519 <https://github.com/tgalal/python-axolotl-curve25519>`__

Linux
-----

You need to have python headers installed, usually through installing a
package called ``python-dev``, then as superuser run:

::

python setup.py install

Mac
---

I don’t have mac to test. Send me instructions or a MacBook.

Windows
-------

- Install `mingw <http://www.mingw.org/>`__ compiler
- Add mingw to your PATH
- In PYTHONPATH:raw-latex:`\Lib`:raw-latex:`\distutils `create a file
called distutils.cfg and add these lines:

::

[build]
compiler=mingw32

- Install gcc: ``mingw-get.exe install gcc``
- Install `zlib <http://www.zlib.net/>`__
- ``python setup.py install``

Usage
-----

This python port is done in an almost 1:1 mapping to the original java
code. Therefore any original documentation for the java code can be
easily mapped and used with this python port.

Install time
------------

At install time, a libaxolotl client needs to generate its identity
keys, registration id, and prekeys.

.. code:: python

identityKeyPair = KeyHelper.generateIdentityKeyPair()
registrationId = KeyHelper.generateRegistrationId()
preKeys = KeyHelper.generatePreKeys(startId, 100)
lastResortKey = KeyHelper.generateLastResortKey()
signedPreKey = KeyHelper.generateSignedPreKey(identityKeyPair, 5)

#Store identityKeyPair somewhere durable and safe.
#Store registrationId somewhere durable and safe.

#Store preKeys in PreKeyStore.
#Store signed prekey in SignedPreKeyStore.

Building a session
------------------

A libaxolotl client needs to implement four interfaces:
IdentityKeyStore, PreKeyStore, SignedPreKeyStore, and SessionStore.
These will manage loading and storing of identity, prekeys, signed
prekeys, and session state.

Once those are implemented, building a session is fairly
straightforward:

.. code:: python

sessionStore = MySessionStore()
preKeyStore = MyPreKeyStore()
signedPreKeyStore = MySignedPreKeyStore()
identityStore = MyIdentityKeyStore()

# Instantiate a SessionBuilder for a remote recipientId + deviceId tuple.
sessionBuilder = SessionBuilder(sessionStore, preKeyStore, signedPreKeyStore,
identityStore, recipientId, deviceId)

# Build a session with a PreKey retrieved from the server.
sessionBuilder.process(retrievedPreKey)

sessionCipher = SessionCipher(sessionStore, recipientId, deviceId)
message = sessionCipher.encrypt("Hello world!")

deliver(message.serialize())

Examples
--------

python-axolotl is actively used in
`yowsup <https://github.com/tgalal/yowsup>`__ to support the new end to
end encryption in WhatsApp

License
-------

Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html

.. |Maturity| image:: https://img.shields.io/pypi/status/libsignal.svg
:target: https://pypi.python.org/pypi/libsignal
.. |License| image:: https://img.shields.io/pypi/l/libsignal.svg
:target: https://pypi.python.org/pypi/libsignal
.. |Version| image:: https://img.shields.io/pypi/v/libsignal.svg
:target: https://pypi.python.org/pypi/libsignal