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 gowormhole 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 ¶
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") // ErrBadKey is returned when the peer on the same slot uses a different password. ErrBadKey = errors.New("bad key") // ErrTimedOut indicates signalling has timed out. ErrTimedOut = errors.New("timed out") )
var Verbose = false
Verbose logging.
Functions ¶
This section is empty.
Types ¶
type InitMsg ¶
type InitMsg struct {
Mode SlotItemMode `json:"exists,omitempty"`
Slot string `json:"slot,omitempty"`
ICEServers []webrtc.ICEServer `json:"iceServers,omitempty"`
}
type SlotItemMode ¶
type SlotItemMode int
const ( ModeNone SlotItemMode = iota // 当前 Slot 为保留（预先生成 code 专用) ModePeer1 // 当前 Slot 已经有一方与信令服务器建立 WebSocket 连接 ModePeer2 // 当前 Slot 已经有两方与信令服务器建立 WebSocket 连接 )
func (SlotItemMode) String ¶
func (mode SlotItemMode) String() string
type Timeouts ¶
type Timeouts struct {
DisconnectedTimeout util.Duration `json:"disconnectedTimeout" default:"5s"`
FailedTimeout util.Duration `json:"failedTimeout" default:"10s"`
KeepAliveInterval util.Duration `json:"keepAliveInterval" default:"2s"`
// CloseTimeout set the timeout for the closing, see Wormhole.Close
CloseTimeout util.Duration `json:"closeTimeout" default:"10s"`
// RwTimeout set the read/write timeout for data channel io.
RwTimeout util.Duration `json:"rwTimeout" default:"10s"`
}
type Wormhole ¶
type Wormhole struct {
// code for the current
Code string
Timeouts *Timeouts
// 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 (*Wormhole) Close ¶
Close attempts to flush the DataChannel buffers then close it and its PeerConnection.
func (*Wormhole) IsRelay ¶
IsRelay returns whether the peer connection is over a TURN relay server or not.
Notes ¶
Bugs ¶
A PeerConnection established via Wormhole will always have a DataChannel created for it, with the name "data" and id 0.
Source Files