wormhole

Documentation

Overview

Package wormhole implements a signalling protocol to establish password protected WebRTC connections between peers.

WebRTC uses DTLS-SRTP (https://tools.ietf.org/html/rfc5764) to secure its data. The mechanism it uses to exchange keys relies on exchanging metadata that includes both endpoints' certificate fingerprints via some trusted channel, typically a signalling server over https and websockets. More in RFC5763 (https://tools.ietf.org/html/rfc5763).

This package removes the signalling server from the trust model by using a PAKE to estabish the authenticity of the WebRTC metadata. In other words, it's a clone of Magic Wormhole made to use WebRTC as the transport.

The protocol requires a signalling server that facilitates exchanging arbitrary messages via a slot system. The server subcommand of the ww tool is an implementation of this over WebSockets.

Rough sketch of the handshake:

Peer               Signalling Server                Peer
----open------------------> |
<---new_slot,TURN_ticket--- |
                            | <------------------open----
                            | ------------TURN_ticket--->
<---------------------------|--------------pake_msg_a----
----pake_msg_b--------------|--------------------------->
----sbox(offer)-------------|--------------------------->
<---------------------------|------------sbox(answer)----
----sbox(candidates...)-----|--------------------------->
<---------------------------|-----sbox(candidates...)----

Index

• Constants
• Variables
• type Wormhole
  • func Join(ctx context.Context, slot, pass string, sigserv string) (*Wormhole, error)
  • func New(ctx context.Context, pass string, sigserv string, slotc chan string) (*Wormhole, error)
  • func (c *Wormhole) Close() (err error)
  • func (c *Wormhole) IsRelay() bool
  • func (c *Wormhole) Read(p []byte) (n int, err error)
  • func (c *Wormhole) Write(p []byte) (n int, err error)
• Bugs

Constants

const (
	// CloseNoSuchSlot is the WebSocket status returned if the slot is not valid.
	CloseNoSuchSlot = 4000 + iota

	// CloseSlotTimedOut is the WebSocket status returned when the slot times out.
	CloseSlotTimedOut

	// CloseNoMoreSlots is the WebSocket status returned when the signalling server
	// cannot allocate any new slots at the time.
	CloseNoMoreSlots

	// CloseWrongProto is the WebSocket status returned when the signalling server
	// runs a different version of the signalling protocol.
	CloseWrongProto

	// ClosePeerHungUp is the WebSocket status returned when the peer has closed
	// its connection.
	ClosePeerHungUp

	// CloseBadKey is the WebSocket status returned when the peer has closed its
	// connection because the key it derived is bad.
	CloseBadKey

	// CloseWebRTCSuccess indicates a WebRTC connection was successful.
	CloseWebRTCSuccess

	// CloseWebRTCSuccessDirect indicates a WebRTC connection was successful and we
	// know it's peer-to-peer.
	CloseWebRTCSuccessDirect

	// CloseWebRTCSuccessRelay indicates a WebRTC connection was successful and we
	// know it's going via a relay.
	CloseWebRTCSuccessRelay

	// CloseWebRTCFailed we couldn't establish a WebRTC connection.
	CloseWebRTCFailed
)

const Protocol = "4"

Protocol is an identifier for the current signalling scheme. It's intended to help clients print a friendlier message urging them to upgrade if the signalling server has a different version.

Variables

var (
	// ErrBadVersion is returned when the signalling server runs an incompatible
	// version of the signalling protocol.
	ErrBadVersion = errors.New("bad version")

	// ErrBadVersion is returned when the the peer on the same slot uses a different
	// password.
	ErrBadKey = errors.New("bad key")

	// ErrNoSuchSlot indicates no one is on the slot requested.
	ErrNoSuchSlot = errors.New("no such slot")

	// ErrTimedOut indicates signalling has timed out.
	ErrTimedOut = errors.New("timed out")
)

var Verbose = false

Verbose logging.

Types

type Wormhole

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

A Wormhole is a WebRTC connection established via the WebWormhole signalling protocol. It is wraps webrtc.PeerConnection and webrtc.DataChannel.

BUG(s): A PeerConnection established via Wormhole will always have a DataChannel created for it, with the name "data" and id 0.

func Join

func Join(ctx context.Context, slot, pass string, sigserv string) (*Wormhole, error)

Join performs the signalling handshake to join an existing slot.

slot is used to synchronise with the remote peer on signalling server sigserv, and pass is used as the PAKE password authenticate the WebRTC offer and answer.

If pc is nil it initialises ones using the default STUN server.

func New

func New(ctx context.Context, pass string, sigserv string, slotc chan string) (*Wormhole, error)

New starts a new signalling handshake after asking the server to allocate a new slot.

The slot is used to synchronise with the remote peer on signalling server sigserv, and pass is used as the PAKE password authenticate the WebRTC offer and answer.

The server generated slot identifier is written on slotc.

If pc is nil it initialises ones using the default STUN server.

func (*Wormhole) Close

func (c *Wormhole) Close() (err error)

Close attempts to flush the DataChannel buffers then close it and its PeerConnection.

func (*Wormhole) IsRelay

func (c *Wormhole) IsRelay() bool

IsRelay returns whether this connection is over a TURN relay or not.

func (*Wormhole) Read

func (c *Wormhole) Read(p []byte) (n int, err error)

Read read a message from the default DataChannel.

func (*Wormhole) Write

func (c *Wormhole) Write(p []byte) (n int, err error)

Read writes a message to the default DataChannel.

Notes

Bugs

• A PeerConnection established via Wormhole will always have a DataChannel created for it, with the name "data" and id 0.