README.md
1This is a python port of [libsignal-protocol-java](https://github.com/WhisperSystems/libaxolotl-android) originally written by [Moxie Marlinspike](https://github.com/moxie0)
2
3Compare with
4[libsignal-protocol-php](https://github.com/albert-chin/libsignal-protocol-php)
5forked from
6[libaxolotl-php](https://github.com/mgp25/libaxolotl-php),
7which is a php port.
8
9Overview from original author's:
10
11 > 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).
12
13Read rest of of details [here](https://github.com/WhisperSystems/libaxolotl-android/blob/master/README.md).
14
15# Installation
16
17The library has some dependencies which are automatically pulled and installed if you use the instructions below for your OS
18
19 - [protobuf 2.6+](https://github.com/google/protobuf/)
20 - [cryptography](https://cryptography.io)
21 - [python-axolotl-curve25519](https://github.com/tgalal/python-axolotl-curve25519)
22
23## Linux
24
25You need to have python headers installed, usually through installing a package called `python-dev`, then as superuser run:
26```
27python setup.py install
28```
29
30## Mac
31
32I don't have mac to test. Send me instructions or a MacBook.
33
34## Windows
35
36 - Install [mingw](http://www.mingw.org/) compiler
37 - Add mingw to your PATH
38 - In PYTHONPATH\Lib\distutils create a file called distutils.cfg and add these lines:
39
40```
41[build]
42compiler=mingw32
43```
44
45 - Install gcc: ```mingw-get.exe install gcc```
46 - Install [zlib](http://www.zlib.net/)
47 - ```python setup.py install```
48
49
50# Usage
51
52This 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.
53
54## Install time
55
56At install time, a libaxolotl client needs to generate its identity keys, registration id, and
57prekeys.
58
59```python
60 identityKeyPair = KeyHelper.generateIdentityKeyPair()
61 registrationId = KeyHelper.generateRegistrationId()
62 preKeys = KeyHelper.generatePreKeys(startId, 100)
63 lastResortKey = KeyHelper.generateLastResortKey()
64 signedPreKey = KeyHelper.generateSignedPreKey(identityKeyPair, 5)
65
66 #Store identityKeyPair somewhere durable and safe.
67 #Store registrationId somewhere durable and safe.
68
69 #Store preKeys in PreKeyStore.
70 #Store signed prekey in SignedPreKeyStore.
71```
72
73## Building a session
74
75A libaxolotl client needs to implement four interfaces: IdentityKeyStore, PreKeyStore,
76SignedPreKeyStore, and SessionStore. These will manage loading and storing of identity,
77prekeys, signed prekeys, and session state.
78
79Once those are implemented, building a session is fairly straightforward:
80
81```python
82sessionStore = MySessionStore()
83preKeyStore = MyPreKeyStore()
84signedPreKeyStore = MySignedPreKeyStore()
85identityStore = MyIdentityKeyStore()
86
87# Instantiate a SessionBuilder for a remote recipientId + deviceId tuple.
88sessionBuilder = SessionBuilder(sessionStore, preKeyStore, signedPreKeyStore,
89 identityStore, recipientId, deviceId)
90
91# Build a session with a PreKey retrieved from the server.
92sessionBuilder.process(retrievedPreKey)
93
94sessionCipher = SessionCipher(sessionStore, recipientId, deviceId)
95message = sessionCipher.encrypt("Hello world!")
96
97deliver(message.serialize())
98```
99
100# Examples
101
102python-axolotl is actively used in [yowsup](https://github.com/tgalal/yowsup) to support the new end to end encryption in WhatsApp
103
104# License
105
106Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html
107