• Stars
    star
    110
  • Rank 316,770 (Top 7 %)
  • Language
    Go
  • License
    MIT License
  • Created over 7 years ago
  • Updated almost 4 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The Double Ratchet Algorithm implementation in Go

doubleratchet

Go Report Card Build Status Coverage Status GoDoc

The Double Ratchet Algorithm is used by two parties to exchange encrypted messages based on a shared secret key. Typically the parties will use some key agreement protocol (such as X3DH) to agree on the shared secret key. Following this, the parties will use the Double Ratchet to send and receive encrypted messages.

The parties derive new keys for every Double Ratchet message so that earlier keys cannot be calculated from later ones. The parties also send Diffie-Hellman public values attached to their messages. The results of Diffie-Hellman calculations are mixed into the derived keys so that later keys cannot be calculated from earlier ones. These properties gives some protection to earlier or later encrypted messages in case of a compromise of a party's keys.

Project status

The library is in beta version and ready for integration into production projects with care. Let me know if you face any problems or have any questions or suggestions.

Implementation notes

The Double Ratchet logic

  1. No more than 1000 messages can be skipped in a single chain.
  2. Skipped messages from a single ratchet step are deleted after 100 ratchet steps.
  3. Both parties' sending and receiving chains are initialized with the shared key so that both of them could message each other from the very beginning.

Cryptographic primitives

  1. GENERATE_DH(): Curve25519
  2. KDF_RK(rk, dh_out): HKDF with SHA-256
  3. KDF_CK(ck): HMAC with SHA-256 and constant inputs
  4. ENCRYPT(mk, pt, associated_data): AES-256-CTR with HMAC-SHA-256 and IV derived alongside an encryption key

Installation

go get github.com/status-im/doubleratchet

then cd into the project directory and install dependencies:

glide up

If glide is not installed, install it.

Usage

Basic usage example

package main

import (
	"fmt"
	"log"

	"github.com/status-im/doubleratchet"
)

func main() {
	// The shared key both parties have already agreed upon before the communication.
	sk := [32]byte{
		0xeb, 0x8, 0x10, 0x7c, 0x33, 0x54, 0x0, 0x20,
		0xe9, 0x4f, 0x6c, 0x84, 0xe4, 0x39, 0x50, 0x5a,
		0x2f, 0x60, 0xbe, 0x81, 0xa, 0x78, 0x8b, 0xeb,
		0x1e, 0x2c, 0x9, 0x8d, 0x4b, 0x4d, 0xc1, 0x40,
	}

	// Diffie-Hellman key pair generated by one of the parties during key exchange or
	// by any other means. The public key MUST be sent to another party for initialization
	// before the communication begins.
	keyPair, err := doubleratchet.DefaultCrypto{}.GenerateDH()
	if err != nil {
		log.Fatal(err)
	}

	// Bob MUST be created with the shared secret and a DH key pair.
	bob, err := doubleratchet.New([]byte("bob-session-id"), sk, keyPair, nil)
	if err != nil {
		log.Fatal(err)
	}

	// Alice MUST be created with the shared secret and Bob's public key.
	alice, err := doubleratchet.NewWithRemoteKey([]byte("alice-session-id"), sk, keyPair.PublicKey(), nil)
	if err != nil {
		log.Fatal(err)
	}

	// Alice can now encrypt messages under the Double Ratchet session.
	m, err := alice.RatchetEncrypt([]byte("Hi Bob!"), nil)

	if err != nil {
		log.Fatal(err)
	}

	// Which Bob can decrypt.
	plaintext, err := bob.RatchetDecrypt(m, nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(plaintext))
}

Options

Additional options can be passed to constructors to customize the algorithm behavior:

doubleratchet.New(
    sk, keyPair,
    
    // Your own cryptography supplement implementing doubleratchet.Crypto.
    WithCrypto(c),
    
    // Custom storage for skipped keys implementing doubleratchet.KeysStorage.
    WithKeysStorage(ks),
    
    // The maximum number of skipped keys. Error will be raised in an attempt to store more keys
    // in a single chain while decrypting.
    WithMaxSkip(1200),
    
    // The number of Diffie-Hellman ratchet steps skipped keys will be stored.
    WithMaxKeep(90),
)

License

MIT

More Repositories

1

status-mobile

a free (libre) open source, mobile OS for Ethereum
Clojure
3,897
star
2

react-native-desktop-qt

A Desktop port of React Native, driven by Qt, forked from Canonical
JavaScript
1,194
star
3

status-go

The Status module that consumes go-ethereum
Go
728
star
4

nimbus-eth1

Nimbus: an Ethereum Execution Client for Resource-Restricted Devices
Nim
562
star
5

nimbus-eth2

Nim implementation of the Ethereum Beacon Chain
Nim
531
star
6

nim-chronos

Chronos - An efficient library for asynchronous programming
Nim
354
star
7

status-desktop

Status Desktop client made in Nim & QML
QML
291
star
8

status-keycard

Our Javacard Implementation for making secure transactions within Status and Ethereum
Java
195
star
9

status-network-token

Smart Contracts for the Status Contribution Period, along with Genesis and Network Tokens
JavaScript
148
star
10

nim-chronicles

A crafty implementation of structured logging for Nim.
Nim
138
star
11

nim-stew

stew is collection of utilities, std library extensions and budding libraries that are frequently used at Status, but are too small to deserve their own git repository.
Nim
119
star
12

open-bounty

Enable communities to distribute funds to push their cause forward.
JavaScript
118
star
13

nim-faststreams

Nearly zero-overhead input/output streams for Nim
Nim
107
star
14

nim-taskpools

Lightweight, energy-efficient, easily auditable threadpool
Nim
98
star
15

swarms

Swarm Home. New, completed and in-progress features for Status
HTML
92
star
16

contracts

Python
87
star
17

nim-json-rpc

Nim library for implementing JSON-RPC clients and servers
Nim
84
star
18

status-web

TypeScript
79
star
19

nim-websock

Websocket for Nim
Nim
74
star
20

questionable

Elegant optional types for Nim
Nim
73
star
21

nim-stint

Stack-based arbitrary-precision integers - Fast and portable with natural syntax for resource-restricted devices.
Nim
73
star
22

nim-eth

Common utilities for Ethereum
Nim
69
star
23

nim-drchaos

A powerful and easy-to-use fuzzing framework in Nim for C/C++/Obj-C targets
Nim
66
star
24

nim-graphql

Nim implementation of GraphQL with sugar and steroids
Nim
64
star
25

clj-rn

A utility for building ClojureScript-based React Native apps
Clojure
56
star
26

nim-confutils

Simplified handling of command line options and config files
Nim
56
star
27

nim-serialization

A modern and extensible serialization framework for Nim
Nim
54
star
28

nim-presto

REST API framework for Nim language
Nim
52
star
29

keycard-cli

A command line tool and shell to manage keycards
Go
46
star
30

keycard-go

Go pkg to interact with the Status Keycard
Go
41
star
31

nim-json-serialization

Flexible JSON serialization not relying on run-time type information
Nim
39
star
32

nim-metrics

Nim metrics client library supporting the Prometheus monitoring toolkit, StatsD and Carbon
Nim
38
star
33

nim-web3

Nim
37
star
34

nim-bearssl

BearSSL wrapper in Nim
C
37
star
35

ETHPrize-interviews

A repository for the ETHPrize website.
HTML
36
star
36

nim-codex

Decentralized Durability Engine
Nim
36
star
37

nim-toml-serialization

Flexible TOML serialization [not] relying on run-time type information.
Nim
35
star
38

hackathon

Status API Hackathon
JavaScript
32
star
39

nim-rocksdb

Nim wrapper for RocksDB, a persistent key-value store for Flash and RAM Storage.
Nim
29
star
40

nim-daemon

Cross-platform process daemonization library for Nim language
Nim
28
star
41

StatusQ

Reusable Status QML components
QML
27
star
42

nim-http-utils

Nim language HTTP helper procedures
Nim
27
star
43

status-electron

[OUTDATED NOT SUPPORTED] Status Electron (React Native Web and Electron)
Clojure
27
star
44

nim-style-guide

Status style guid for the Nim language
Nim
26
star
45

status-teller-network

DApp which provides a platform for borderless, peer-to-peer, fiat-to-crypto echanges that allows Stakeholders to find nearby users to exchange their cash for digital assets and currency.
JavaScript
26
star
46

nim-decimal

A correctly-rounded arbitrary precision decimal floating point arithmetic library
C
26
star
47

codex-research

Codex durability engine research
Jupyter Notebook
25
star
48

vyper-debug

Easy to use Vyper debugger | vdb (https://github.com/ethereum/vyper)
Python
24
star
49

react-native-status-keycard

React Native library to interact with Status Keycard using NFC connection
Java
24
star
50

nim-unittest2

Beautiful and efficient unit testing for Nim evolved from the standard library `unittest` module
Nim
24
star
51

mingw-windows10-uwp

Minimal Windows 10 Store ready sample of MinGW dll PInvoked from Windows 10 UWP application
C#
24
star
52

wiki.status.im

It's the wiki... for Status
HTML
24
star
53

nim-snappy

Nim implementation of Snappy compression algorithm
Nim
24
star
54

CryptoLife

A repo for all the #CryptoLife Hackathon submissions, The National House Smichov, Prague, 26-28th October 2018.
23
star
55

status-chat-widget

Easily embed a status chatroom in your website - outdated, please use https://github.com/status-im/js-waku
JavaScript
22
star
56

nim-blscurve

Nim implementation of BLS signature scheme (Boneh-Lynn-Shacham) over Barreto-Lynn-Scott (BLS) curve BLS12-381
C
22
star
57

keycard-connect

Keycard + WalletConnect
Kotlin
21
star
58

nimplay

Nim Ethereum Contract DSL. Targeting eWASM.
Nim
20
star
59

nim-cookbook

Nim
20
star
60

whisper-tutorial

Whisper Tutorial using web3js
JavaScript
20
star
61

ens-usernames

DApp to register usernames for Status Network
JavaScript
19
star
62

status-keycard-java

Java SDK for the Status Keycard
Java
19
star
63

Keycard.swift

Swift
19
star
64

account-contracts

Key managers, recovery, gas abstraction and self-sovereign identity for web3 universal login.
Solidity
19
star
65

nim-protobuf-serialization

Nim
19
star
66

ethereumj-personal

EthereumJ for Personal Devices DEPRECATED
Java
19
star
67

liquid-funding

Dapp for delegating donations to projects
JavaScript
19
star
68

nim-testutils

testrunner et al
Nim
17
star
69

react-native-transparent-video

React Native video player with alpha channel (alpha-packing) support.
Java
17
star
70

general-market-framework

A Generalised Market Framework for Ethereum
Python
16
star
71

nim-libbacktrace

Nim wrapper for libbacktrace
C
16
star
72

wallet

CSS
16
star
73

go-maven-resolver

Tool for resolving Java Maven dependencies
Go
15
star
74

murmur

WIP - Whisper node / client implementation built in javascript
JavaScript
15
star
75

keycard-installer-android

discontinued, use https://github.com/status-im/keycard-cli - Keycard applet installer over NFC
Java
15
star
76

bigbrother-specs

Research and specification for Big Brother protocol
14
star
77

status-dev-cli

Status command-line tools
JavaScript
14
star
78

nim-evmc

Nim EVMC - Ethereum VM binary compatible interface
Nim
14
star
79

specs

Specifications for Status clients.
HTML
14
star
80

nescience

A Zero-Knowledge Toolkit
Nim
13
star
81

geth_exporter

geth metrics exporter for Prometheus
Go
13
star
82

autobounty

Github bot that automatically funds https://openbounty.status.im bounties
JavaScript
13
star
83

status-security

Repository for all Status Network related security information
JavaScript
13
star
84

snt-gas-relay

SNT Gas Relay
JavaScript
13
star
85

move

MOVΞ - A Decentralised Ride Sharing DApp
JavaScript
13
star
86

nim-ttmath

C++
12
star
87

nim-eth-p2p

Nim Ethereum P2P protocol implementation
Nim
11
star
88

dreddit-devcon

JavaScript
11
star
89

keycard-pro

WIP
C
11
star
90

syng-client

The Mobile Client for the Ethereum Network DEPRECATED
Java
11
star
91

status-github-bot

A bot for github
JavaScript
11
star
92

embark-status

Provides an ability to debug Embark DApps in Status
JavaScript
11
star
93

pluto

Clojure
11
star
94

snt-voting

JavaScript
11
star
95

nimbus-launch

Jumpstart your Nim project at Status
Nim
11
star
96

keycard-redeem

TypeScript
10
star
97

translate.status.im

Help translate Status into your language!
JavaScript
10
star
98

nim-eth-contracts

Ethereum smart contracts in Nim
Nim
10
star
99

status-console-client

Status messaging console user interface
Go
10
star
100

the-explainers

The Explainers Initiative is an open effort to bring technical content regarding the Serenity upgrade of the Ethereum blockchain closer to non-technical and semi-technical communities
10
star