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 (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
- 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
- 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")
Functions ¶
This section is empty.
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 ¶
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 (*Client) CloseDialing ¶
func (*Client) ConnectAddFriend ¶
func (*Client) ConnectDialing ¶
func (*Client) GetFriend ¶
GetFriend returns the friend object for the given username, or nil if username is not in the client's address book.
func (*Client) GetFriends ¶
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) Persist ¶
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) SessionKey ¶
SessionKey returns the shared key at the given round. This should only be used for debugging.
func (*Friend) SetExtraData ¶
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 ¶
UnsafeKeywheelState exposes the internal keywheel state for this friend. This should only be used for debugging.
type IncomingCall ¶
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
}
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package addfriend provides functionality for Alpenhorn's add-friend protocol.
|
Package addfriend provides functionality for Alpenhorn's add-friend protocol. |
|
Package bloom implements Bloom filters.
|
Package bloom implements Bloom filters. |
|
Package cdn simulates a basic CDN server.
|
Package cdn simulates a basic CDN server. |
|
cmd
|
|
|
Package coordinator implements the entry/coordinator server.
|
Package coordinator implements the entry/coordinator server. |
|
Package dialing provides functionality for Alpenhorn's dialing protocol.
|
Package dialing provides functionality for Alpenhorn's dialing protocol. |
|
Package edhttp is an HTTP client that connects to HTTP servers on edtls listeners.
|
Package edhttp is an HTTP client that connects to HTTP servers on edtls listeners. |
|
Package edtls provides ed25519 signatures on top of TLS certificates.
|
Package edtls provides ed25519 signatures on top of TLS certificates. |
|
encoding
|
|
|
toml
Package toml implements Tom's Obvious Minimal Language.
|
Package toml implements Tom's Obvious Minimal Language. |
|
Package errors implements basic error handling.
|
Package errors implements basic error handling. |
|
internal
|
|
|
Package keywheel implements Alpenhorn's keywheel construction.
|
Package keywheel implements Alpenhorn's keywheel construction. |
|
Package log provides structured logging.
|
Package log provides structured logging. |
|
ansi
Package ansi implements ANSI escape codes for terminal colors.
|
Package ansi implements ANSI escape codes for terminal colors. |
|
Package pkg implements a Private Key Generator (PKG) for Identity-Based Encryption (IBE).
|
Package pkg implements a Private Key Generator (PKG) for Identity-Based Encryption (IBE). |
|
Package typesocket implements a websocket server and client.
|
Package typesocket implements a websocket server and client. |