DoubleRatchet

This is a mostly complete implementation of the Encrypted Header variant of the The Double Ratchet Algorithm designed by Open Whisper Systems.

WARNING: This implementation was created for learning purposes and should not be used outside of a development environment. Any concerns or suggestions are very welcome.

This implementation was built using the NodeJS crypto library as its only dependency. I decided to do this as Electron is the intended usage. However, it would be trivial to abstract the crypto provider in order to make this library browser friendly.

Usage

const Ratchet = require('doubleratchet').Ratchet
 
const pskRoot        = ... // a shared secret between alice and bob
const pskHeader      = ... // a shared secret between alice and bob
const pskNextHeader  = ... // a shared secret between alice and bob
 
const alice = new Ratchet(pskRoot, pskHeader, pskNextHeader)
const bob = new Ratchet(pskRoot, pskNextHeader, pskHeader)
 
alice.acceptHandshake( bob.makeHandshake() )
 
bob.decrypt( alice.encrypt('hello bob') )   // "hello bob"
alice.decrypt( bob.encrypt('hello alice') ) // "hello alice"

See examples directory for more.

Development

git clone https://github.com/jowy/doubleratchet.git
cd doubleratchet
yarn install
yarn build

Implementation Parameters

Parameter	Implementation
Ratchet ECDH Curve	secp521r1
HMAC-KDF (HKDF)	SHA256
Header Cipher	AES256 CBC Mode
Header Key Derivation	Salted HKDF
Header Key Length	32 Bytes (Truncated)
Header IV Derivation	Salted HKDF
Message Cipher	AES256 CBC Mode
Message Key Derivation	Salted HKDF
Message Key Length	32 Bytes (Truncated)
Message IV Derivation	Salted HKDF
Auth Tag Derivation	Salted HKDF
Auth Key Length	32 Bytes (Truncated)
Auth Tag Length	16 Bytes (Truncated)
Skipped Message Key Expire Method	Ratchet Invocation
Skipped Message Key TTL	20

TODO

• flow typing
• comments
• tests
• clean up KDF flow
• clean up Key and CipherKey initialization and handling
• clean up buffer handling
• state (de)serialization
• fix header & nextHeader initialization and flow
• proper handling of input & output encoding
• revise CipherKey kdf
• error handling for various things
• throw properly typed errors
• rollback chain state on failure
• more examples demonstrating various features of the protocol
• API outline