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