alpenhorn

README

Alpenhorn

Alpenhorn is the first system for initiating an encrypted connection between two users that provides strong privacy and forward secrecy guarantees for metadata. Alpenhorn does not require out-of-band communication other than knowing your friend's Alpenhorn username (usually their email address). Alpenhorn's design, threat model, and performance are described in our OSDI 2016 paper.

In short, Alpenhorn works well for bootstrapping conversations in Vuvuzela. Now users can start chatting on Vuvuzela without having to exchange keys in person or over some less secure channel.

A beta deployment of Alpenhorn and Vuvuzela is coming soon.

Documentation

Overview

Package alpenhorn implements an Alpenhorn client.

Index

• Constants
• Variables
• type Client
  • func LoadClient(clientPersistPath, keywheelPersistPath string) (*Client, error)
  • func (c *Client) Bootstrap(addFriendConfig, dialingConfig *config.SignedConfig) error
  • func (c *Client) CloseAddFriend() error
  • func (c *Client) CloseDialing() error
  • func (c *Client) ConnectAddFriend() (chan error, error)
  • func (c *Client) ConnectDialing() (chan error, error)
  • func (c *Client) GetFriend(username string) *Friend
  • func (c *Client) GetFriends() []*Friend
  • func (c *Client) GetIncomingFriendRequests() []*IncomingFriendRequest
  • func (c *Client) GetOutgoingFriendRequests() []*OutgoingFriendRequest
  • func (c *Client) GetSentFriendRequests() []*OutgoingFriendRequest
  • func (c *Client) PKGStatus() []PKGStatus
  • func (c *Client) Persist() error
  • func (c *Client) Register(server pkg.PublicServerConfig, token string) error
  • func (c *Client) SendFriendRequest(username string, key ed25519.PublicKey) (*OutgoingFriendRequest, error)
• type EventHandler
• type Friend
  • func (f *Friend) Call(intent int) *OutgoingCall
  • func (f *Friend) ExtraData() []byte
  • func (f *Friend) Remove() error
  • func (f *Friend) SessionKey(round uint32) *[32]byte
  • func (f *Friend) SetExtraData(data []byte) error
  • func (f *Friend) UnsafeKeywheelState() (uint32, *[32]byte)
• type IncomingCall
• type IncomingFriendRequest
  • func (r *IncomingFriendRequest) Approve() (*OutgoingFriendRequest, error)
  • func (v IncomingFriendRequest) MarshalEasyJSON(w *jwriter.Writer)
  • func (v IncomingFriendRequest) MarshalJSON() ([]byte, error)
  • func (r *IncomingFriendRequest) Reject() error
  • func (v *IncomingFriendRequest) UnmarshalEasyJSON(l *jlexer.Lexer)
  • func (v *IncomingFriendRequest) UnmarshalJSON(data []byte) error
• type OutgoingCall
  • func (r *OutgoingCall) Cancel() error
  • func (r *OutgoingCall) Intent() int
  • func (r *OutgoingCall) Sent() bool
  • func (r *OutgoingCall) SessionKey() *[32]byte
  • func (r *OutgoingCall) UpdateIntent(intent int) error
• type OutgoingFriendRequest
  • func (r *OutgoingFriendRequest) Cancel() error
  • func (v OutgoingFriendRequest) MarshalEasyJSON(w *jwriter.Writer)
  • func (v OutgoingFriendRequest) MarshalJSON() ([]byte, error)
  • func (v *OutgoingFriendRequest) UnmarshalEasyJSON(l *jlexer.Lexer)
  • func (v *OutgoingFriendRequest) UnmarshalJSON(data []byte) error
• type PKGStatus

Constants

const IntentMax = 3

Intents are the dialing intents passed to Call.

Variables

var ErrTooLate = errors.New("too late")

Types

type Client

type Client struct {
	Username           string
	LongTermPublicKey  ed25519.PublicKey
	LongTermPrivateKey ed25519.PrivateKey
	PKGLoginKey        ed25519.PrivateKey

	ConfigClient *config.Client

	Handler EventHandler

	// ClientPersistPath is where the client writes its state when it changes.
	// If empty, the client does not persist state.
	ClientPersistPath string

	// KeywheelPersistPath is the path where the client's keywheel is stored.
	// This field is not persisted along with the rest of the client's state,
	// so it must be set before calling Connect.
	//
	// The client state and keywheel are persisted in separate files for
	// forward secrecy. The client state is long-term and should be backed
	// up regularly. The keywheel is ephemeral and should not be backed up
	// (doing so hurts forward secrecy, and the keywheel can be recreated
	// from the client state).
	KeywheelPersistPath string
	// contains filtered or unexported fields
}

func LoadClient

func LoadClient(clientPersistPath, keywheelPersistPath string) (*Client, error)

LoadClient loads a client from persisted state at the given path. You should set the client's KeywheelPersistPath before connecting.

func (*Client) Bootstrap

func (c *Client) Bootstrap(addFriendConfig, dialingConfig *config.SignedConfig) error

func (*Client) CloseAddFriend

func (c *Client) CloseAddFriend() error

func (*Client) CloseDialing

func (c *Client) CloseDialing() error

func (*Client) ConnectAddFriend

func (c *Client) ConnectAddFriend() (chan error, error)

func (*Client) ConnectDialing

func (c *Client) ConnectDialing() (chan error, error)

func (*Client) GetFriend

func (c *Client) GetFriend(username string) *Friend

GetFriend returns the friend object for the given username, or nil if username is not in the client's address book.

func (*Client) GetFriends

func (c *Client) GetFriends() []*Friend

GetFriends returns all the friends in the client's address book.

func (*Client) GetIncomingFriendRequests

func (c *Client) GetIncomingFriendRequests() []*IncomingFriendRequest

func (*Client) GetOutgoingFriendRequests

func (c *Client) GetOutgoingFriendRequests() []*OutgoingFriendRequest

func (*Client) GetSentFriendRequests

func (c *Client) GetSentFriendRequests() []*OutgoingFriendRequest

func (*Client) PKGStatus

func (c *Client) PKGStatus() []PKGStatus

func (*Client) Persist

func (c *Client) Persist() error

Persist writes the client's state to disk. The client persists itself automatically, so Persist is only needed when creating a new client.

func (*Client) Register

func (c *Client) Register(server pkg.PublicServerConfig, token string) error

Register registers the username with the given PKG.

func (*Client) SendFriendRequest

func (c *Client) SendFriendRequest(username string, key ed25519.PublicKey) (*OutgoingFriendRequest, error)

SendFriendRequest sends a friend request to the given username using Alpenhorn's add-friend protocol. The key is optional and specifies the username's long-term public key if it is known ahead of time.

The friend request is not sent right away but queued for an upcoming add-friend round. The resulting OutgoingFriendRequest is the queued friend request.

type EventHandler

type EventHandler interface {
	// Error is called when the Alpenhorn client experiences an error.
	Error(error)

	// ConfirmedFriend is called when the add-friend protocol is completed
	// between two friends, resulting in a new Friend object.
	ConfirmedFriend(*Friend)

	// SentFriendRequest is called when an OutgoingFriendRequest is sent
	// to the entry server.
	SentFriendRequest(*OutgoingFriendRequest)

	// ReceivedFriendRequest is called when the client receives a friend request.
	// The application should eventually call .Approve() or .Remove() on the
	// IncomingFriendRequest.
	ReceivedFriendRequest(*IncomingFriendRequest)

	// UnexpectedSigningKey is called when an incoming friend request corresponds
	// to a friend request the user sent but has a different long term key than
	// what the user specified.
	UnexpectedSigningKey(*IncomingFriendRequest, *OutgoingFriendRequest)

	// SendingCall is called when an OutgoingCall is about to be sent to the
	// entry server. The application can finalize the call to get its session key.
	SendingCall(*OutgoingCall)

	// ReceivedCall is called when the client receives a call from a friend.
	ReceivedCall(*IncomingCall)

	// NewConfig is called when the configuration for the add-friend or dialing
	// protocol changes. The chain starts with the new config and ends with the
	// client's previous config.
	NewConfig(chain []*config.SignedConfig)
}

An EventHandler specifies how an application should react to events in the Alpenhorn client.

type Friend

type Friend struct {
	Username    string
	LongTermKey ed25519.PublicKey
	// contains filtered or unexported fields
}

Friend is an entry in the client's address book.

func (*Friend) Call

func (f *Friend) Call(intent int) *OutgoingCall

Call is used to call a friend using Alpenhorn's dialing protocol. Call does not send the call right away but queues the call for an upcoming dialing round. The resulting OutgoingCall is the queued call object. Call does nothing and returns nil if the friend is not in the client's address book.

func (*Friend) ExtraData

func (f *Friend) ExtraData() []byte

ExtraData returns a copy of the extra data field for the friend.

func (*Friend) Remove

func (f *Friend) Remove() error

Remove removes the friend from the client's address book.

func (*Friend) SessionKey

func (f *Friend) SessionKey(round uint32) *[32]byte

SessionKey returns the shared key at the given round. This should only be used for debugging.

func (*Friend) SetExtraData

func (f *Friend) SetExtraData(data []byte) error

SetExtraData overwrites the friend's extra data field with the given data. The extra data field is useful for application-specific data about the friend, such as additional contact info, notes, or a photo.

Applications should use the extra data field to store information about friends instead of maintaining a separate friend list because the Alpenhorn client will (eventually) ensure that the size of the persisted data on disk does not leak metadata.

func (*Friend) UnsafeKeywheelState

func (f *Friend) UnsafeKeywheelState() (uint32, *[32]byte)

UnsafeKeywheelState exposes the internal keywheel state for this friend. This should only be used for debugging.

type IncomingCall

type IncomingCall struct {
	Username   string
	Intent     int
	SessionKey *[32]byte
}

type IncomingFriendRequest

type IncomingFriendRequest struct {
	Username    string
	LongTermKey ed25519.PublicKey
	DHPublicKey *[32]byte
	DialRound   uint32
	Verifiers   []pkg.PublicServerConfig
	// contains filtered or unexported fields
}

func (*IncomingFriendRequest) Approve

func (r *IncomingFriendRequest) Approve() (*OutgoingFriendRequest, error)

Approve accepts the friend request and queues a confirmation friend request. The add-friend protocol is complete for this friend when the confirmation request is sent. Approve assumes that the friend request has not been previously rejected.

func (IncomingFriendRequest) MarshalEasyJSON

func (v IncomingFriendRequest) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (IncomingFriendRequest) MarshalJSON

func (v IncomingFriendRequest) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*IncomingFriendRequest) Reject

func (r *IncomingFriendRequest) Reject() error

Reject rejects the friend request, returning ErrTooLate if the friend request is not found in the client's queue.

func (*IncomingFriendRequest) UnmarshalEasyJSON

func (v *IncomingFriendRequest) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*IncomingFriendRequest) UnmarshalJSON

func (v *IncomingFriendRequest) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type OutgoingCall

type OutgoingCall struct {
	Username string
	Created  time.Time
	// contains filtered or unexported fields
}

func (*OutgoingCall) Cancel

func (r *OutgoingCall) Cancel() error

Cancel removes the call from the outgoing queue, returning ErrTooLate if the call is not found in the queue.

func (*OutgoingCall) Intent

func (r *OutgoingCall) Intent() int

func (*OutgoingCall) Sent

func (r *OutgoingCall) Sent() bool

Sent returns true if the call has been sent and false otherwise.

func (*OutgoingCall) SessionKey

func (r *OutgoingCall) SessionKey() *[32]byte

SessionKey returns the session key established for this call, or nil if the call has not been sent yet.

func (*OutgoingCall) UpdateIntent

func (r *OutgoingCall) UpdateIntent(intent int) error

type OutgoingFriendRequest

type OutgoingFriendRequest struct {
	Username    string
	ExpectedKey ed25519.PublicKey

	// Confirmation indicates whether this request is in response to an
	// incoming friend request.
	Confirmation bool

	// DialRound is the round that the resulting shared key between friends
	// corresponds to. This field is only used when Confirmation is true.
	// Otherwise, the client uses the latest dialing round when the friend
	// request is sent.
	DialRound uint32
	// contains filtered or unexported fields
}

func (*OutgoingFriendRequest) Cancel

func (r *OutgoingFriendRequest) Cancel() error

Cancel cancels the friend request by removing it from the queue. It returns ErrTooLate if the request is not found in the queue.

func (OutgoingFriendRequest) MarshalEasyJSON

func (v OutgoingFriendRequest) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (OutgoingFriendRequest) MarshalJSON

func (v OutgoingFriendRequest) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*OutgoingFriendRequest) UnmarshalEasyJSON

func (v *OutgoingFriendRequest) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*OutgoingFriendRequest) UnmarshalJSON

func (v *OutgoingFriendRequest) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type PKGStatus

type PKGStatus struct {
	Server pkg.PublicServerConfig
	Error  error
}