mirror of
https://codeberg.org/cunicu/cunicu.git
synced 2025-10-04 16:32:57 +08:00
68 lines
2.3 KiB
Markdown
68 lines
2.3 KiB
Markdown
# 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)$.
|
||
|
||
```mermaid
|
||
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`](../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`](../pkg/signaling/backend.go) 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](https://github.com/stv0g/wice/blob/master/pkg/signaling/backend.go):
|
||
|
||
```go
|
||
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)
|
||
}
|
||
``` |