ratchet

README

.. image:: https://travis-ci.org/katzenpost/doubleratchet.svg?branch=master
  :target: https://travis-ci.org/katzenpost/doubleratchet

.. image:: https://godoc.org/github.com/katzenpost/doubleratchet?status.svg
  :target: https://godoc.org/github.com/katzenpost/doubleratchet

Double Ratchet Library
======================

This library is a fork of agl's double ratchet in his pond messaging system.
We have made several changes in this fork:

* serialization in CBOR instead of protobufs
* this library takes ownership of all key material used
* added methods to perform the complete key exchange
  whereas in pond the code to perform the key exchange was
  spread out and not at all contained with the ratchet code module.

Read **The Double Ratchet Algorithm** by Trevor Perrin (editor), Moxie Marlinspike
https://signal.org/docs/specifications/doubleratchet/


Contact
=======

* IRC: irc.oftc.net #katzenpost <irc://irc.oftc.net/#katzenpost>
* Mailing List <https://lists.mixnetworks.org/listinfo/katzenpost>

Disclaimer
==========

I am not certain to the degree agl's ratchet was audited however
I shall state here that my modifications to this code has NOT been audited
for security vulnerabilities. Therefore this library should be not considered
correct or safe to use. Proceed with caution.

License
=======

This is a fork of agl's double ratchet:
https://github.com/agl/pond/tree/master/client/ratchet

We do not claim any endorsement or approval from agl or pond, obviously.
Please see agl's LICENSE file for details, which is included in this repository
as per the legal requirements of the software license.

Please also note that this license includes a copyright:

Copyright (c) 2013 Adam Langley. All rights reserved.

Documentation

Overview

Package ratchet implements the axolotl ratchet, by Trevor Perrin. See https://github.com/trevp/axolotl/wiki.

Index

• Constants
• func DestroyRatchet(r *Ratchet)
• type KeyExchange
• type MessageKey
• type Ratchet
  • func InitRatchet(rand io.Reader) (*Ratchet, error)
  • func (r *Ratchet) CompleteKeyExchange(kx *KeyExchange) error
  • func (r *Ratchet) CreateKeyExchange() (*SignedKeyExchange, error)
  • func (r *Ratchet) Decrypt(ciphertext []byte) ([]byte, error)
  • func (r *Ratchet) Encrypt(out, msg []byte) []byte
  • func (r *Ratchet) FillKeyExchange(kx *KeyExchange) error
  • func (r *Ratchet) Marshal(now time.Time, lifetime time.Duration) *State
  • func (r *Ratchet) MarshalBinary() (data []byte, err error)
  • func (r *Ratchet) ProcessKeyExchange(signedKeyExchange *SignedKeyExchange) error
  • func (r *Ratchet) Unmarshal(s *State) error
  • func (r *Ratchet) UnmarshalBinary(data []byte) error
• type SavedKeys
• type SignedKeyExchange
• type State

Constants

const (

	// RatchetKeyMaxLifetime is the maximum lifetime of the ratchet
	RatchetKeyMaxLifetime = time.Hour * 672

	// DoubleRatchetOverhead is the number of bytes the ratchet adds in ciphertext overhead.
	DoubleRatchetOverhead = 120
)

Functions

func DestroyRatchet

func DestroyRatchet(r *Ratchet)

DestroyRatchet destroys the ratchet

Types

type KeyExchange

type KeyExchange struct {
	PublicKey      []byte
	IdentityPublic []byte
	Dh             []byte
	Dh1            []byte
}

KeyExchange is structure containing the public keys

type MessageKey

type MessageKey struct {
	Num          uint32
	Key          []byte
	CreationTime int64
}

MessageKey is structure containing the data associated with the message key

type Ratchet

type Ratchet struct {
	TheirSigningPublic  *memguard.LockedBuffer // 32 bytes long
	TheirIdentityPublic *memguard.LockedBuffer // 32 bytes long

	MySigningPublic  *memguard.LockedBuffer // 32 bytes long
	MySigningPrivate *memguard.LockedBuffer // 64 bytes long

	MyIdentityPrivate *memguard.LockedBuffer // 32 bytes long
	MyIdentityPublic  *memguard.LockedBuffer // 32 bytes long

	// Now is an optional function that will be used to get the current
	// time. If nil, time.Now is used.
	Now func() time.Time
	// contains filtered or unexported fields
}

Ratchet stucture contains the per-contact, crypto state.

func InitRatchet

func InitRatchet(rand io.Reader) (*Ratchet, error)

InitRatchet initializes a ratchet struct

func (*Ratchet) CompleteKeyExchange

func (r *Ratchet) CompleteKeyExchange(kx *KeyExchange) error

CompleteKeyExchange takes a KeyExchange message from the other party and establishes the ratchet.

func (*Ratchet) CreateKeyExchange

func (r *Ratchet) CreateKeyExchange() (*SignedKeyExchange, error)

CreateKeyExchange created and add the appropiate fields for the KeyExchange

func (*Ratchet) Decrypt

func (r *Ratchet) Decrypt(ciphertext []byte) ([]byte, error)

Decrypt decrypts a message

func (*Ratchet) Encrypt

func (r *Ratchet) Encrypt(out, msg []byte) []byte

Encrypt acts like append() but appends an encrypted version of msg to out.

func (*Ratchet) FillKeyExchange

func (r *Ratchet) FillKeyExchange(kx *KeyExchange) error

FillKeyExchange sets elements of kx with key exchange information from the ratchet.

func (*Ratchet) Marshal

func (r *Ratchet) Marshal(now time.Time, lifetime time.Duration) *State

Marshal transforms the object into a stream

func (*Ratchet) MarshalBinary

func (r *Ratchet) MarshalBinary() (data []byte, err error)

MarshalBinary transforms the object into a stream

func (*Ratchet) ProcessKeyExchange

func (r *Ratchet) ProcessKeyExchange(signedKeyExchange *SignedKeyExchange) error

ProcessKeyExchange processes the data of a KeyExchange

func (*Ratchet) Unmarshal

func (r *Ratchet) Unmarshal(s *State) error

Unmarshal transforms the stream into the object

func (*Ratchet) UnmarshalBinary

func (r *Ratchet) UnmarshalBinary(data []byte) error

UnmarshalBinary transforms the stream into the object

type SavedKeys

type SavedKeys struct {
	HeaderKey   []byte
	MessageKeys []*MessageKey
}

SavedKeys is structure containing the saved keys from delayed messages

type SignedKeyExchange

type SignedKeyExchange struct {
	Signed    []byte
	Signature []byte
}

SignedKeyExchange is structure containing the signature data

type State

type State struct {
	TheirSigningPublic  []byte
	TheirIdentityPublic []byte
	MySigningPublic     []byte
	MySigningPrivate    []byte
	MyIdentityPrivate   []byte
	MyIdentityPublic    []byte
	SavedKeys           []*SavedKeys
	RootKey             []byte
	SendHeaderKey       []byte
	RecvHeaderKey       []byte
	NextSendHeaderKey   []byte
	NextRecvHeaderKey   []byte
	SendChainKey        []byte
	RecvChainKey        []byte
	SendRatchetPrivate  []byte
	RecvRatchetPublic   []byte
	SendCount           uint32
	RecvCount           uint32
	PrevSendCount       uint32
	Private0            []byte
	Private1            []byte
	Ratchet             bool
}

State constains all the data associated with a ratchet