diff options
Diffstat (limited to 'third_party/libwebrtc/p2p/g3doc/ice.md')
| -rw-r--r-- | third_party/libwebrtc/p2p/g3doc/ice.md | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/third_party/libwebrtc/p2p/g3doc/ice.md b/third_party/libwebrtc/p2p/g3doc/ice.md new file mode 100644 index 0000000000..81c9541b64 --- /dev/null +++ b/third_party/libwebrtc/p2p/g3doc/ice.md @@ -0,0 +1,102 @@ +<!-- go/cmark --> +<!--* freshness: {owner: 'jonaso' reviewed: '2021-04-12'} *--> + +# ICE + +## Overview + +ICE ([link](https://developer.mozilla.org/en-US/docs/Glossary/ICE)) provides +unreliable packet transport between two clients (p2p) or between a client and a +server. + +This documentation provides an overview of how ICE is implemented, i.e how the +following classes interact. + +* [`cricket::IceTransportInternal`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/ice_transport_internal.h;l=225;drc=8cb97062880b0e0a78f9d578370a01aced81a13f) - + is the interface that does ICE (manage ports, candidates, connections to + send/receive packets). The interface is implemented by + [`cricket::P2PTransportChannel`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/p2p_transport_channel.h;l=103;drc=0ccfbd2de7bc3b237a0f8c30f48666c97b9e5523). + +* [`cricket::PortInterface`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/port_interface.h;l=47;drc=c3a486c41e682cce943f2b20fe987c9421d4b631) + Represents a local communication mechanism that can be used to create + connections to similar mechanisms of the other client. There are 4 + implementations of `cricket::PortInterface` + [`cricket::UDPPort`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/stun_port.h;l=33;drc=a4d873786f10eedd72de25ad0d94ad7c53c1f68a), + [`cricket::StunPort`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/stun_port.h;l=265;drc=a4d873786f10eedd72de25ad0d94ad7c53c1f68a), + [`cricket::TcpPort`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/tcp_port.h;l=33;drc=7a284e1614a38286477ed2334ecbdde78e87b79c) + and + [`cricket::TurnPort`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/turn_port.h;l=44;drc=ffb7603b6025fbd6e79f360d293ab49092bded54). + The ports share lots of functionality in a base class, + [`cricket::Port`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/port.h;l=187;drc=3ba7beba29c4e542c4a9bffcc5a47d5e911865be). + +* [`cricket::Candidate`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/candidate.h;l=30;drc=10542f21c8e4e2d60b136fab45338f2b1e132dde) + represents an address discovered by a `cricket::Port`. A candidate can be + local (i.e discovered by a local port) or remote. Remote candidates are + transported using signaling, i.e outside of webrtc. There are 4 types of + candidates: `local`, `stun`, `prflx` or `relay` + ([standard](https://developer.mozilla.org/en-US/docs/Web/API/RTCIceCandidateType)) + +* [`cricket::Connection`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/connection.h) + provides the management of a `cricket::CandidatePair`, i.e for sending data + between two candidates. It sends STUN Binding requests (aka STUN pings) to + verify that packets can traverse back and forth and keep connections alive + (both that NAT binding is kept, and that the remote peer still wants the + connection to remain open). + +* `cricket::P2PTransportChannel` uses an + [`cricket::PortAllocator`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/port_allocator.h;l=335;drc=9438fb3fff97c803d1ead34c0e4f223db168526f) + to create ports and discover local candidates. The `cricket::PortAllocator` + is implemented by + [`cricket::BasicPortAllocator`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/client/basic_port_allocator.h;l=29;drc=e27f3dea8293884701283a54f90f8a429ea99505). + +* `cricket::P2PTransportChannel` uses an + [`cricket::IceControllerInterface`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/ice_controller_interface.h;l=73;drc=9438fb3fff97c803d1ead34c0e4f223db168526f) + to manage a set of connections. The `cricket::IceControllerInterface` + decides which `cricket::Connection` to send data on. + +## Connection establishment + +This section describes a normal sequence of interactions to establish ice state +completed +[ link ](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/ice_transport_internal.h;l=208;drc=9438fb3fff97c803d1ead34c0e4f223db168526f) +([ standard ](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/iceConnectionState)) + +All of these steps are invoked by interactions with `PeerConnection`. + +1. [`P2PTransportChannel::MaybeStartGathering`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/p2p_transport_channel.cc;l=864;drc=0ccfbd2de7bc3b237a0f8c30f48666c97b9e5523) + This function is invoked as part of `PeerConnection::SetLocalDescription`. + `P2PTransportChannel` will use the `cricket::PortAllocator` to create a + `cricket::PortAllocatorSession`. The `cricket::PortAllocatorSession` will + create local ports as configured, and the ports will start gathering + candidates. + +2. [`IceTransportInternal::SignalCandidateGathered`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/ice_transport_internal.h;l=293;drc=8cb97062880b0e0a78f9d578370a01aced81a13f) + When a port finds a local candidate, it will be added to a list on + `cricket::P2PTransportChannel` and signaled to application using + `IceTransportInternal::SignalCandidateGathered`. A p2p application can then + send them to peer using favorite transport mechanism whereas a client-server + application will do nothing. + +3. [`P2PTransportChannel::AddRemoteCandidate`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/p2p_transport_channel.cc;l=1233;drc=0ccfbd2de7bc3b237a0f8c30f48666c97b9e5523) + When the application get a remote candidate, it can add it using + `PeerConnection::AddRemoteCandidate` (after + `PeerConnection::SetRemoteDescription` has been called!), this will trickle + down to `P2PTransportChannel::AddRemoteCandidate`. `P2PTransportChannel` + will combine the remote candidate with all compatible local candidates to + form new `cricket::Connection`(s). Candidates are compatible if it is + possible to send/receive data (e.g ipv4 can only send to ipv4, tcp can only + connect to tcp etc...) The newly formed `cricket::Connection`(s) will be + added to the `cricket::IceController` that will decide which + `cricket::Connection` to send STUN ping on. + +4. [`P2PTransportChannel::SignalCandidatePairChanged`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/ice_transport_internal.h;l=310;drc=8cb97062880b0e0a78f9d578370a01aced81a13f) + When a remote connection replies to a STUN ping, `cricket::IceController` + will instruct `P2PTransportChannel` to use the connection. This is signalled + up the stack using `P2PTransportChannel::SignalCandidatePairChanged`. Note + that `cricket::IceController` will continue to send STUN pings on the + selected connection, as well as other connections. + +5. [`P2PTransportChannel::SignalIceTransportStateChanged`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/ice_transport_internal.h;l=323;drc=8cb97062880b0e0a78f9d578370a01aced81a13f) + The initial selection of a connection makes `P2PTransportChannel` signal up + stack that state has changed, which may make [`cricket::DtlsTransportInternal`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/dtls_transport_internal.h;l=63;drc=653bab6790ac92c513b7cf4cd3ad59039c589a95) + initiate a DTLS handshake (depending on the DTLS role). |