cunicu/docs/Signaling.md

Session Signaling

Lets assume two WireGuard peers P_a & P_b are seeking to establish a ICE session.

The smaller public key (PK) of the two peers takes the role of the controlling agent. In this example PA has the role of the controlling agent as: PK(P_a) < PK(P_b).

sequenceDiagram
    autonumber

    actor Pa as Peer A
    actor Pb as Peer B
    participant b as Backend

    Pa ->> b: SessionDescription(Pa -> Pb)
    b ->> Pb: SessionDescription(Pa -> Pb)

    Pb ->> b: SessionDescription(Pb -> Pa)
    b ->> Pa: SessionDescription(Pb -> Pa)

Session Description

Session descriptions are exchanged by one or more the signaling backends via signaling envelopes which contain signaling messages. The envelopes are containers which encrypt the carried message via asymmetric cryptography using the public key of the recipient.

Both the envelope and the message are serialized using Protobuf.

Checkout the pkg/pb/signaling.proto for details.

Backends

ɯice can support multiple backends for signaling session information such as session IDs, ICE candidates, public keys and STUN credentials.

Available backends

• gRPC
• Kubernetes API server

For the use within a Kubernetes cluster also a dedicated backend using the Kubernetes api-server is available. Checkout the Backend interface for implementing your own backend.

Semantics

A backend must:

• Allow the exchange of envelopes between peers using their public keys.
• Guarantee a reliable delivery of envelopes.
• Not require not open envelopes (require the knowledge of private keys).
• May deliver the envelopes out-of-order.
• Shall be stateless (not buffer any envelopes if the recipient is not yet know or reachable).

Interface

All signaling backends implement the rather simple signaling.Backend interface:

type Backend interface {
	io.Closer

	// Publish a signaling message to a specific peer
	Publish(ctx context.Context, kp *crypto.KeyPair, msg *signaling.Message) error

	// Get a stream of messages from a specific peer
	Subscribe(ctx context.Context, kp *crypto.KeyPair) (chan *signaling.Message, error)
}