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 https://github.com/agl/pond/.
We have made several changes in this fork:

* "post-quantum hybrid ratchet"; CSIDH and ECDH ratchets progress together and both computed shared
  secrets are feed into the root KDF chain
* uses memguard to protect and wipe the memory used to store cryptographic
  key material
* 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
==========

This code has not be audited for security or logic errors. 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 originally written by AGL to implement the axolotl ratchet (designed by Trevor Perrin) for the Pond messaging system but then modified for a Katzenpost decryption mix network messaging system. Improvements herein made by Masala, Sofia Celli and David Stainton. David's latest changes turn the ratchet into a computationally expensive PQ hybrid ratchet wherein there's an ECDH and a CSIDH ratchet which both progress together. Both of these ratchets feed their computed shared secrets into the KDF ratchet via the root KDF chain. More clever designs and feedback encouraged.

Index

• Constants
• Variables
• func DestroyRatchet(r *Ratchet)
• type Ratchet
  • func InitRatchet(rand io.Reader) (*Ratchet, error)
  • func NewRatchetFromBytes(rand io.Reader, data []byte) (*Ratchet, error)
  • func (r *Ratchet) CreateKeyExchange() ([]byte, error)
  • func (r *Ratchet) Decrypt(ciphertext []byte) ([]byte, error)
  • func (r *Ratchet) Encrypt(out, msg []byte) ([]byte, error)
  • func (r *Ratchet) ProcessKeyExchange(exchangePayload []byte) error
  • func (r *Ratchet) Save() (data []byte, err error)

Constants

const (
	PQRatchetPublicKeyInHeaderOffset = 4 + 4 + 32

	// MaxMissingMessages is the maximum number of missing messages that
	// we'll keep track of.
	MaxMissingMessages = 8

	// 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 + csidh.PublicKeySize
)

Variables

var (
	ErrDuplicateOrDelayed                     = errors.New("Ratchet: duplicate message or message delayed longer than tolerance")
	ErrHandshakeAlreadyComplete               = errors.New("Ratchet: handshake already complete")
	ErrCannotDecrypt                          = errors.New("Ratchet: cannot decrypt")
	ErrIncorrectHeaderSize                    = errors.New("Ratchet: incorrect header size")
	ErrSerialisedKeyLength                    = errors.New("Ratchet: bad serialised key length")
	ErrNextEncryptedMessageWithoutRatchetFlag = errors.New("Ratchet: received message encrypted to next header key without ratchet flag set")
	ErrOldFormKeyExchange                     = errors.New("Ratchet: peer using old-form key exchange")
	ErrCorruptMessage                         = errors.New("Ratchet: corrupt message")
	ErrMessageExceedsReorderingLimit          = errors.New("Ratchet: message exceeds reordering limit")
	ErrEchoedDHValues                         = errors.New("Ratchet: peer echoed our own DH values back")
	ErrInvalidSignatureLength                 = errors.New("Ratchet: invalid signature length")
	ErrRatchetHeaderTooSmall                  = errors.New("Ratchet: header too small to be valid")
	ErrInvalidKeyExchange                     = errors.New("Ratchet: peer's key exchange is invalid")
	ErrFailedToInitializeRatchet              = errors.New("Ratchet: failed to initialize")
	ErrInvalidPubkey                          = errors.New("Ratchet: invalid public key")
	ErrInvalidPublicIdentityKey               = errors.New("Ratchet: invalid public identity key")
	ErrInvalidSignature                       = errors.New("Ratchet: invalid signature")
	ErrKeyExchangeKeysNotIsomorphicallyEqual  = errors.New("Ratchet: key exchange and identity public keys must be isomorphically equal")
	ErrFailedToLoadPQRatchet                  = errors.New("Ratchet: failed to load PQ Ratchet from state")
	ErrImportPQDh0                            = errors.New("Ratchet: failed to import PQ DH0 from exchange blob")
	ErrCSIDHSharedSecret                      = errors.New("Ratchet: failed to compute shared secret from PQDH0")
	ErrCSIDHPrivateExport                     = errors.New("Ratchet: CSIDH: failed to export private key")
	ErrCSIDHPrivateImport                     = errors.New("Ratchet: CSIDH: failed to import private key")
	ErrCSIDHPublicExport                      = errors.New("Ratchet: CSIDH: failed to export public key")
	ErrCSIDHPublicImport                      = errors.New("Ratchet: CSIDH: failed to import public key")
	ErrCSIDHInvalidPublicKey                  = errors.New("Ratchet: CSIDH public key validation failure")
	ErrInconsistentState                      = errors.New("Ratchet: the state is inconsistent")
)

Functions

func DestroyRatchet

func DestroyRatchet(r *Ratchet)

DestroyRatchet destroys the ratchet

Types

type Ratchet

type Ratchet struct {
	// 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 NewRatchetFromBytes

func NewRatchetFromBytes(rand io.Reader, data []byte) (*Ratchet, error)

NewRatchetFromBytes takes ownership of data and unmarshals it into a new *Ratchet. The bytes are wiped afterwards. The new *Ratchet is returned unless there's an error.

func (*Ratchet) CreateKeyExchange

func (r *Ratchet) CreateKeyExchange() ([]byte, error)

CreateKeyExchange returns a byte slice which is meant to be transmitted to the other party via an encrypted and authenticated communications channel. The other party can then call their Ratchet's ProcessKeyExchange method to process this byte blob and establish a communications channel with the sender.

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, error)

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

func (*Ratchet) ProcessKeyExchange

func (r *Ratchet) ProcessKeyExchange(exchangePayload []byte) error

ProcessKeyExchange processes the data of a keyExchange which is used to establish an encrypted authenticated communications channel.

func (*Ratchet) Save

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

Save transforms the object into a stream