cunicu/docs/Signaling.md

Session signaling

Lets assume two Wireguard peers Pa & Pb 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(PA) < PK(PB).

PA                         PB

  --- initial offer     -->        id=SID_Pa, version=0, candidates=[], eoc=false
  <-- initial offer     ---        id=SID_Pb, version=0, candidates=[], eoc=false

  --- subsequent offers -->        id=SID_Pa, version=1, candidates=[C1_Pa], eoc=false
  <-- subsequent offers ---        id=SID_Pb, version=1, candidates=[C1_Pb], eoc=false

  --- subsequent offers -->        id=SID_Pa, version=2, candidates=[C1_Pa, C2_Pa], eoc=false
  <-- subsequent offers ---        id=SID_Pb, version=2, candidates=[C1_Pb, C2_Pb], eoc=false

  ---  eoc. offer       -->        id=SID_Pa, version=3, candidates=[C1_Pa, C2_Pa], eoc=true
  <--  eoc. offer       ---        id=SID_Pb, version=3, candidates=[C1_Pb, C2_Pb], eoc=true

Restart

Agent will restart

• if

  • last_recv.id has been set
  • recv.id!=last_recv.id
  • recv.version==0

• then

  • set

    • local.id=rand()
    • local.version=0
    • local.candidates=[]

  • publish new offer

  • wait for first offer including candidates from remote

  • (re)start agent

  • add first received

  • start gathering candidates

    • send an offers for each candidate c:
      • candidates=local.candidates.append(c)
      • id=local.id
      • rid=local.rid
      • version=local.version++

Offer

Offers are exchanged by one or more the signaling backends via Protobuf messages.

Checkout the pkg/pb/offer.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

Currently, the main backend is based on libp2p. 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.