https://github.com/xmikos/pyxolotl
Send and receive messages encrypted with Axolotl (Double Ratchet) protocol
https://github.com/xmikos/pyxolotl
Last synced: 3 months ago
JSON representation
Send and receive messages encrypted with Axolotl (Double Ratchet) protocol
- Host: GitHub
- URL: https://github.com/xmikos/pyxolotl
- Owner: xmikos
- License: gpl-3.0
- Created: 2015-10-07T23:45:57.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2019-01-17T22:37:49.000Z (over 6 years ago)
- Last Synced: 2025-03-01T06:51:13.913Z (4 months ago)
- Language: Python
- Homepage:
- Size: 41 KB
- Stars: 45
- Watchers: 4
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
Awesome Lists containing this project
README
Pyxolotl
========
Send and receive messages encrypted with `Axolotl (Double Ratchet) `_ protocol
Description
-----------
Pyxolotl allows you to send and receive secure end-to-end encrypted messages with
`perfect forward and future secrecy `_ over
any channel (email, IM, IRC, Twitter, Hangouts, Facebook, etc.). It uses same
`Axolotl (Double Ratchet) `_ protocol as Signal
messaging app by Open Whisper Systems.
Protocol
--------
Actual wire protocol is described
`here `_. Headers
(for differentiating between standard message and key exchange message) are obfuscated
with 100000 iterations of PBKDF2 (with whole encrypted message used as salt). This should make
identifying Pyxolotl messages very resource-intensive to impede mass surveillance or filtering.
Key exchange
------------
Pyxolotl is serverless, all messages are sent P2P, so it doesn't use
`prekeys `_. You must first send initial key
exchange message to recipient and wait for his reply before sending actual message (this is same as
`SMS Transport `_
in older versions of TextSecure and in SMSSecure / Silence). Once this initial key exchange is completed,
both parties can send messages to each other without any other inconveniences. Security model is
`TOFU `_ (Trust On First Use), both parties
should compare public keys via independent secure channel to mitigate potential MITM attack during
initial key exchange.
Transports
----------
Pyxolotl have pluggable transports. For now there is only *plaintext* transport (which prints
encoded messages to terminal) and *email* transport (messages are encoded to / decoded from
well-formed MIME emails).
Encodings
---------
Encrypted messages can use different transport encodings. For now there is standard *Base64*
encoding (without padding) and as a curiosity *mnemonic* encoding (based on
`BIP-0039: Mnemonic code for generating deterministic keys `_
which encodes encrypted messages as a sequence of words). Mnemonic encoding is inefficient
(messages are about 3.5x larger than Base64), but it can add another layer of obfuscation against
mass surveillance or filtering.
Local encryption
----------------
Local database (private key, sessions, etc.) is encrypted with AES-CBC using 256-bit key derived
from passphrase (with 100000 iterations of PBKDF2 and random salt) and authenticated with HMAC-SHA256.
Requirements
------------
- Python >= 3.3
- enum (https://pypi.python.org/pypi/enum) for Python < 3.4
- python-axolotl (https://github.com/tgalal/python-axolotl)
- python-axolotl-curve25519 (https://github.com/tgalal/python-axolotl-curve25519)
- protobuf (https://github.com/google/protobuf) >= 2.6
- pycrypto (https://github.com/dlitz/pycrypto)
Usage
-----
Run ``pyxolotl --help`` to see all available options.
Help
----
::
usage: pyxolotl [-h] [-d] [-t {plaintext,email}] [-e {base64,mnemonic}]
[--log LOG] [--db DB] [--config CONFIG] [--version]
[-a ADDRESS] [-s SUBJECT]
{list,ls,send,receive,recv,exchange,delete,del,rm,passwd} ...
send and receive messages encrypted with Axolotl protocol
optional arguments:
-h, --help show this help message and exit
-d, --debug log detailed debugging messages (default: False)
-t {plaintext,email}, --transport {plaintext,email}
choose message transport (default: plaintext)
-e {base64,mnemonic}, --encoder {base64,mnemonic}
choose message encoding (default: base64)
--log LOG log file path (default:
~/.local/share/pyxolotl/pyxolotl.log)
--db DB database file path (default:
~/.local/share/pyxolotl/pyxolotl.db)
--config CONFIG configuration file path (default:
~/.local/share/pyxolotl/pyxolotl.json)
--version show program's version number and exit
email transport:
-a ADDRESS, --address ADDRESS
your own email address (default: None)
-s SUBJECT, --subject SUBJECT
subject of sent emails (default: None)
commands:
run `pyxolotl COMMAND --help` to see help message for specific command
{list,ls,send,receive,recv,exchange,delete,del,rm,passwd}
available commands
list (ls) list known identities
send send message to recipient
receive (recv) receive message from sender
exchange start initial key exchage with recipient
delete (del, rm) end session with recipient
passwd change passphrase to local storage
Todo:
-----
- write more transports (especially Google Hangouts, Twitter Direct Messages, Facebook Messenger,
IRC and XMPP)
- make email transport more complete (sending with SMTP, receiving with IMAP IDLE)
- create IM-like console UI (with ``asyncio`` and `Urwid `_)
- create IM-like Qt 5/QML based GUI
- add support for multiple devices
- add support for group messages
- add support for verifying identity with question (using
`socialist millionaire `_ protocol)
Example
-------
::
[[email protected] ~]$ pyxolotl exchange bob
SEND:
To: bob
Encrypted message: 4uJ8zyMIwSgSIQUuLKlC8WdspRietP45P6nFU6/50wT4cQYxNw4vvqKLHxohBYLC5sDLZ78syjQIMf9PA+3Q9MGootUvOajaZA3thspDIiEF6sSiWxB6l0B4oE7gcMl1T3W+hzI548U46cYrR5KUjXY
[[email protected] ~]$ pyxolotl receive
RECEIVE:
From: alice
Encrypted message: 4uJ8zyMIwSgSIQUuLKlC8WdspRietP45P6nFU6/50wT4cQYxNw4vvqKLHxohBYLC5sDLZ78syjQIMf9PA+3Q9MGootUvOajaZA3thspDIiEF6sSiWxB6l0B4oE7gcMl1T3W+hzI548U46cYrR5KUjXY
Received initial key exchange request! Send this reply to complete key exchange:
SEND:
To: alice
Encrypted message: 0yx89TMIwigSIQVN+wtEio0h+Zx7WPcIwM9WreOy0r7eETBclhOtDAvANhohBb4qfe8R05/167DQDdd2Gqp5OrxAPcriwJMtzi+2b7QrIiEFhfVGHlCm6b1SX36V1HeFX4pAeW15v1aLb2nGi57NZFAqQD3rKGjPDCCm1Kj6i8GUnf4MAc56fhRIYhUJH2mSvlcSAl2XotmR2Yz2lY0wa7TW1JnmUX+YBbIEgIHk0gQ9Log
[[email protected] ~]$ pyxolotl receive
RECEIVE:
From: bob
Encrypted message: 0yx89TMIwigSIQVN+wtEio0h+Zx7WPcIwM9WreOy0r7eETBclhOtDAvANhohBb4qfe8R05/167DQDdd2Gqp5OrxAPcriwJMtzi+2b7QrIiEFhfVGHlCm6b1SX36V1HeFX4pAeW15v1aLb2nGi57NZFAqQD3rKGjPDCCm1Kj6i8GUnf4MAc56fhRIYhUJH2mSvlcSAl2XotmR2Yz2lY0wa7TW1JnmUX+YBbIEgIHk0gQ9Log
Initial key exchange completed!
[[email protected] ~]$ pyxolotl ls
Your public key: 05eac4a25b107a974078a04ee070c9754f75be873239e3c538e9c62b4792948d76
Existing sessions:
Identity: bob, Pending key exchange: False
Public key: 0585f5461e50a6e9bd525f7e95d477855f8a40796d79bf568b6f69c68b9ecd6450
[[email protected] ~]$ pyxolotl ls
Your public key: 0585f5461e50a6e9bd525f7e95d477855f8a40796d79bf568b6f69c68b9ecd6450
Existing sessions:
Identity: alice, Pending key exchange: False
Public key: 05eac4a25b107a974078a04ee070c9754f75be873239e3c538e9c62b4792948d76
[[email protected] ~]$ pyxolotl send bob
Message: Hello Bob!
SEND:
To: bob
Encrypted message: a74TljMKIQWJl7sz1bTEIhF/7nwKBLRi7XeEpzcur7t/MOixAOfbHRAAGAAiEEgco7NQXppy/qsm5TdJllpW+nTQ1QjVsQ
[[email protected] ~]$ pyxolotl receive
RECEIVE:
From: alice
Encrypted message: a74TljMKIQWJl7sz1bTEIhF/7nwKBLRi7XeEpzcur7t/MOixAOfbHRAAGAAiEEgco7NQXppy/qsm5TdJllpW+nTQ1QjVsQ
DECRYPTED:
Hello Bob!
[[email protected] ~]$ pyxolotl send alice
Message: Hello Alice!
SEND:
To: alice
Encrypted message: Zd/HKjMKIQXLGyTr5AcvrpUhfR2H7bYqLXqVy7GpE84VvFFkm1LDbxAAGAAiEJDC8/kM59yVzNeCBtjDVOe1CHWuFDbhYg
[[email protected] ~]$ pyxolotl receive
RECEIVE:
From: bob
Encrypted message: Zd/HKjMKIQXLGyTr5AcvrpUhfR2H7bYqLXqVy7GpE84VvFFkm1LDbxAAGAAiEJDC8/kM59yVzNeCBtjDVOe1CHWuFDbhYg
DECRYPTED:
Hello Alice!