handshake

README

handshake

a peculiar chat app for strange times

Handshake is designed to be an experiment in one-time key symmetric encrypted communications. The tool is based on in-person initialization of communication so that all future transmissions rely on symmetric key cryptography. This is primarily a design for out-of-band communication in which communicating parties aim to mitigate potential compromises in asymmetric encryption methodology ranging from CA poisoning to reliance on trusted centralized service providers for communications technology, and it can even be used to explore patterns in post-quantum readiness.

Handshake is designed initially to work on IPFS and hashmap, but there are no technical reasons other backends couldn't be supported. In fact, support for strategies is built into the core of handshake to allow for experimentation. For the sake of focus, this initial implementation utilizes hashmap and IPFS, but other decentralized tooling based around smart contracts and other systems should be able to be incorporated in the future.

You can read more about how handshake works in the design doc.

You can check out an early CLI-based proof of concept here:

installing the CLI tool

You can install the CLI tool by running go install

go install github.com/nomasters/handshake/cmd/handshake

or by building from the cmd/handshake directory.

Documentation

Index

• Constants
• func NewGenesisProfile(password string) error
• func ProfilesExist() (bool, error)
• type CipherType
• type NonceType
• type Profile
  • func (p Profile) IDBytes() ([]byte, error)
  • func (p Profile) KeyBase64() string
  • func (p Profile) KeyHex() string
• type SecretBoxCipher
  • func (s SecretBoxCipher) Decrypt(data []byte, key []byte) ([]byte, error)
  • func (s SecretBoxCipher) Encrypt(data []byte, key []byte) ([]byte, error)
• type Session
  • func NewDefaultSession(password string) (*Session, error)
  • func NewSession(password string, opts SessionOptions) (*Session, error)
  • func (s *Session) AddPeerToHandshake(body []byte) (bool, error)
  • func (s *Session) Close() error
  • func (s *Session) GetChatlog(chatID string) (chatLog, error)
  • func (s *Session) GetHandshakePeerConfig(sortNumber int) ([]byte, error)
  • func (s *Session) GetHandshakePeerTotal() int
  • func (s *Session) GetMyPeerID(chatID string) (string, error)
  • func (s *Session) GetProfile() Profile
  • func (s *Session) ListChats() ([]byte, error)
  • func (s *Session) NewChat() (string, error)
  • func (s *Session) NewInitiatorWithDefaults()
  • func (s *Session) NewPeerWithDefaults()
  • func (s *Session) RetrieveMessages(chatID string) ([]byte, error)
  • func (s *Session) SendMessage(chatID string, b []byte) ([]byte, error)
  • func (s *Session) ShareHandshakePosition() (b []byte, err error)
• type SessionOptions
• type StorageEngine
• type StorageOptions

Constants

const (
	// DefaultSessionTTL is the default TTL before a Session closes
	DefaultSessionTTL = 15 * 60 // 15 minutes in seconds
	// DefaultMaxLoginAttempts is the number of times failed login attempts are allowed
	DefaultMaxLoginAttempts = 10
)

const (

	// Version is the hard coded version of handshake-core running
	Version = "0.0.1"
)

Functions

func NewGenesisProfile

func NewGenesisProfile(password string) error

NewGenesisProfile takes password and

func ProfilesExist

func ProfilesExist() (bool, error)

ProfilesExist configures a storage engine and checks `profilesExist`. It returns a bool and error. This is used on app startup to check to see if this is the first time running the tool. If this function returns `false` and no errors, the next step would be to prompt the user to setup a new profile using `NewGenesisProfile()`.

Types

type CipherType

type CipherType int

CipherType is used for type enumeration of Ciphers

const (
	// SecretBox is a CipherType
	SecretBox CipherType = iota
)

type NonceType

type NonceType int

NonceType is used for type enumeration for Ciphers Nonces

const (
	// RandomNonce is the NonceType used for pure crypto/rand generated nonces
	RandomNonce NonceType = iota
	// TimeSeriesNonce is the NonceType used for 4 byte unix time prefixed crypto/rand generated nonces
	TimeSeriesNonce
)

type Profile

type Profile struct {
	ID       string
	Key      []byte
	Settings profileSettings
}

Profile represents a profile that has been accessed this would contain successfully decrypted profile data

func (Profile) IDBytes

func (p Profile) IDBytes() ([]byte, error)

IDBytes converts the ID string in base64 to decoded bytes

func (Profile) KeyBase64

func (p Profile) KeyBase64() string

KeyBase64 returns a base64 encoded string of the key

func (Profile) KeyHex

func (p Profile) KeyHex() string

KeyHex returns a hex encoded string of the key

type SecretBoxCipher

type SecretBoxCipher struct {
	Nonce     NonceType
	ChunkSize int
}

SecretBoxCipher is a struct and method set that conforms to the Cipher interface. This is the primary cipher used for all blob encryption and decryption for handshake

func (SecretBoxCipher) Decrypt

func (s SecretBoxCipher) Decrypt(data []byte, key []byte) ([]byte, error)

Decrypt takes byte slices for data and key and returns the clear text output for secretbox

func (SecretBoxCipher) Encrypt

func (s SecretBoxCipher) Encrypt(data []byte, key []byte) ([]byte, error)

Encrypt takes byte slices for data and a key and returns the ciphertext output for secretbox

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session is the primary struct for a logged in user. It holds the profile data as well as settings information

func NewDefaultSession

func NewDefaultSession(password string) (*Session, error)

NewDefaultSession is a wrapper around NewSession and applies simple defaults. This is intended to be used by the reference apps.

func NewSession

func NewSession(password string, opts SessionOptions) (*Session, error)

NewSession takes a password and opts and returns a pointer to Session and an error

func (*Session) AddPeerToHandshake

func (s *Session) AddPeerToHandshake(body []byte) (bool, error)

AddPeerToHandshake takes a json encoded peerConfig, attempts to unmarshal it and add it as a peer. It returns a bool and an error. The bool indicates if handshake.AllPeersReceived == true, in which case the handshake can safely be conversted int a chat.

func (*Session) Close

func (s *Session) Close() error

Close gracefully closes the session

func (*Session) GetChatlog

func (s *Session) GetChatlog(chatID string) (chatLog, error)

func (*Session) GetHandshakePeerConfig

func (s *Session) GetHandshakePeerConfig(sortNumber int) ([]byte, error)

GetHandshakePeerConfig returns the json bytes encoded peerConfig based on peerID or and an error

func (*Session) GetHandshakePeerTotal

func (s *Session) GetHandshakePeerTotal() int

GetHandshakePeerTotal returns an int count of the number of peers to expect for a handshake

func (*Session) GetMyPeerID

func (s *Session) GetMyPeerID(chatID string) (string, error)

GetMyPeerID returns a string of the profile user's peerID for a specific chat, returns the peerID and an error

func (*Session) GetProfile

func (s *Session) GetProfile() Profile

GetProfile returns the profile in the Session struct

func (*Session) ListChats

func (s *Session) ListChats() ([]byte, error)

ListChats returns a json encoded list of chatIDs and an error

func (*Session) NewChat

func (s *Session) NewChat() (string, error)

NewChat creates a new chat from the activeHandshake and returns a chat ID string and error. If the chat is successfully created, it deletes the contents of the activeHandshake

func (*Session) NewInitiatorWithDefaults

func (s *Session) NewInitiatorWithDefaults()

NewInitiatorWithDefaults provides a simple method with no arguments to create a default handshake for an initiator. Adds this handshake pointer to the ActiveHandshake in the session.

func (*Session) NewPeerWithDefaults

func (s *Session) NewPeerWithDefaults()

NewPeerWithDefaults provides a simple method with no arguments to create a default handshake for an peer. Adds this handshake pointer to the ActiveHandshake in the session.

func (*Session) RetrieveMessages

func (s *Session) RetrieveMessages(chatID string) ([]byte, error)

RetrieveMessages takes a chatID and initiates the retrieval process for all peers it returns a json encoded chatLogList and error

func (*Session) SendMessage

func (s *Session) SendMessage(chatID string, b []byte) ([]byte, error)

SendMessage takes a chatID and message bytes and submits the message to the message storage and rendezvous point. It returns a json encoded chatLogList and error

func (*Session) ShareHandshakePosition

func (s *Session) ShareHandshakePosition() (b []byte, err error)

ShareHandshakePosition returns the values from negotiator.Share() from the ActiveHandshake

type SessionOptions

type SessionOptions struct {
	StorageEngine   StorageEngine
	StorageFilePath string
}

SessionOptions holds session options for initialization

type StorageEngine

type StorageEngine int

StorageEngine type for enum

const (
	// BoltEngine is the default storage engine for device storage
	BoltEngine StorageEngine = iota
	// HashmapEngine is the default Rendezvous storage type
	HashmapEngine
	// IPFSEngine is the default message storage type
	IPFSEngine
)

type StorageOptions

type StorageOptions struct {
	Engine     StorageEngine
	FilePath   string
	Signatures []signatureAlgorithm
	ReadNodes  []node
	WriteNodes []node
	ReadRule   consensusRule
	WriteRule  consensusRule
}

StorageOptions are used to pass in initialization settings