diff options
Diffstat (limited to 'third_party/libwebrtc/pc/g3doc')
| -rw-r--r-- | third_party/libwebrtc/pc/g3doc/dtls_transport.md | 53 | ||||
| -rw-r--r-- | third_party/libwebrtc/pc/g3doc/peer_connection.md | 59 | ||||
| -rw-r--r-- | third_party/libwebrtc/pc/g3doc/rtp.md | 56 | ||||
| -rw-r--r-- | third_party/libwebrtc/pc/g3doc/sctp_transport.md | 42 | ||||
| -rw-r--r-- | third_party/libwebrtc/pc/g3doc/srtp.md | 72 |
5 files changed, 282 insertions, 0 deletions
diff --git a/third_party/libwebrtc/pc/g3doc/dtls_transport.md b/third_party/libwebrtc/pc/g3doc/dtls_transport.md new file mode 100644 index 0000000000..28d6739413 --- /dev/null +++ b/third_party/libwebrtc/pc/g3doc/dtls_transport.md @@ -0,0 +1,53 @@ +<!-- go/cmark --> +<!--* freshness: {owner: 'hta' reviewed: '2021-05-07'} *--> + +## Overview + +WebRTC uses DTLS in two ways: + +* to negotiate keys for SRTP encryption using + [DTLS-SRTP](https://www.rfc-editor.org/info/rfc5763) +* as a transport for SCTP which is used by the Datachannel API + +The W3C WebRTC API represents this as the +[DtlsTransport](https://w3c.github.io/webrtc-pc/#rtcdtlstransport-interface). + +The DTLS handshake happens after the ICE transport becomes writable and has +found a valid pair. It results in a set of keys being derived for DTLS-SRTP as +well as a fingerprint of the remote certificate which is compared to the one +given in the SDP `a=fingerprint:` line. + +This documentation provides an overview of how DTLS is implemented, i.e how the +following classes interact. + +## webrtc::DtlsTransport + +The [`webrtc::DtlsTransport`][1] class is a wrapper around the +`cricket::DtlsTransportInternal` and allows registering observers implementing +the `webrtc::DtlsTransportObserverInterface`. The +[`webrtc::DtlsTransportObserverInterface`][2] will provide updates to the +observers, passing around a snapshot of the transports state such as the +connection state, the remote certificate(s) and the SRTP ciphers as +[`DtlsTransportInformation`][3]. + +## cricket::DtlsTransportInternal + +The [`cricket::DtlsTransportInternal`][4] class is an interface. Its +implementation is [`cricket::DtlsTransport`][5]. The `cricket::DtlsTransport` +sends and receives network packets via an ICE transport. It also demultiplexes +DTLS packets and SRTP packets according to the scheme described in +[RFC 5764](https://tools.ietf.org/html/rfc5764#section-5.1.2). + +## webrtc::DtlsSrtpTranport + +The [`webrtc::DtlsSrtpTransport`][6] class is responsŃ–ble for extracting the +SRTP keys after the DTLS handshake as well as protection and unprotection of +SRTP packets via its [`cricket::SrtpSession`][7]. + +[1]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/dtls_transport.h;l=32;drc=6a55e7307b78edb50f94a1ff1ef8393d58218369 +[2]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/dtls_transport_interface.h;l=76;drc=34437d5660a80393d631657329ef74c6538be25a +[3]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/dtls_transport_interface.h;l=41;drc=34437d5660a80393d631657329ef74c6538be25a +[4]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/dtls_transport_internal.h;l=63;drc=34437d5660a80393d631657329ef74c6538be25a +[5]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/dtls_transport.h;l=94;drc=653bab6790ac92c513b7cf4cd3ad59039c589a95 +[6]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/dtls_srtp_transport.h;l=31;drc=c32f00ea9ddf3267257fe6b45d4d79c6f6bcb829 +[7]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=33;drc=be66d95ab7f9428028806bbf66cb83800bda9241 diff --git a/third_party/libwebrtc/pc/g3doc/peer_connection.md b/third_party/libwebrtc/pc/g3doc/peer_connection.md new file mode 100644 index 0000000000..cd01265cff --- /dev/null +++ b/third_party/libwebrtc/pc/g3doc/peer_connection.md @@ -0,0 +1,59 @@ +<!-- go/cmark --> +<!--* freshness: {owner: 'hta' reviewed: '2021-05-07'} *--> + +# PeerConnection and friends + +The PeerConnection is the C++-level implementation of the Javascript +object "RTCPeerConnection" from the +[WEBRTC specification](https://w3c.github.io/webrtc-pc/). + +Like many objects in WebRTC, the PeerConnection is used via a factory and an +observer: + + * PeerConnectionFactory, which is created via a static Create method and takes + a PeerConnectionFactoryDependencies structure listing such things as + non-default threads and factories for use by all PeerConnections using + the same factory. (Using more than one factory should be avoided, since + it takes more resources.) + * PeerConnection itself, which is created by the method called + PeerConnectionFactory::CreatePeerConnectionOrError, and takes a + PeerConnectionInterface::RTCConfiguration argument, as well as + a PeerConnectionDependencies (even more factories, plus other stuff). + * PeerConnectionObserver (a member of PeerConnectionDependencies), which + contains the functions that will be called on events in the PeerConnection + +These types are visible in the API. + +## Internal structure of PeerConnection and friends + +The PeerConnection is, to a large extent, a "God object" - most things +that are done in WebRTC require a PeerConnection. + +Internally, it is divided into several objects, each with its own +responsibilities, all of which are owned by the PeerConnection and live +as long as the PeerConnection: + + * SdpOfferAnswerHandler takes care of negotiating configurations with + a remote peer, using SDP-formatted descriptions. + * RtpTransmissionManager takes care of the lists of RtpSenders, + RtpReceivers and RtpTransceivers that form the heart of the transmission + service. + * DataChannelController takes care of managing the PeerConnection's + DataChannels and its SctpTransport. + * JsepTransportController takes care of configuring the details of senders + and receivers. + * Call does management of overall call state. + * RtcStatsCollector (and its obsolete sibling, StatsCollector) collects + statistics from all the objects comprising the PeerConnection when + requested. + +There are a number of other smaller objects that are also owned by +the PeerConnection, but it would take too much space to describe them +all here; please consult the .h files. + +PeerConnectionFactory owns an object called ConnectionContext, and a +reference to this is passed to each PeerConnection. It is referenced +via an rtc::scoped_refptr, which means that it is guaranteed to be +alive as long as either the factory or one of the PeerConnections +is using it. + diff --git a/third_party/libwebrtc/pc/g3doc/rtp.md b/third_party/libwebrtc/pc/g3doc/rtp.md new file mode 100644 index 0000000000..28da3fba97 --- /dev/null +++ b/third_party/libwebrtc/pc/g3doc/rtp.md @@ -0,0 +1,56 @@ +<!-- go/cmark --> +<!--* freshness: {owner: 'hta' reviewed: '2021-06-03'} *--> + +# RTP in WebRTC + +WebRTC uses the RTP protocol described in +[RFC3550](https://datatracker.ietf.org/doc/html/rfc3550) for transporting audio +and video. Media is encrypted using [SRTP](./srtp.md). + +## Allocation of payload types + +RTP packets have a payload type field that describes which media codec can be +used to handle a packet. For some (older) codecs like PCMU the payload type is +assigned statically as described in +[RFC3551](https://datatracker.ietf.org/doc/html/rfc3551). For others, it is +assigned dynamically through the SDP. **Note:** there are no guarantees on the +stability of a payload type assignment. + +For this allocation, the range from 96 to 127 is used. When this range is +exhausted, the allocation falls back to the range from 35 to 63 as permitted by +[section 5.1 of RFC3550][1]. Note that older versions of WebRTC failed to +recognize payload types in the lower range. Newer codecs (such as flexfec-03 and +AV1) will by default be allocated in that range. + +Payload types in the range 64 to 95 are not used to avoid confusion with RTCP as +described in [RFC5761](https://datatracker.ietf.org/doc/html/rfc5761). + +## Allocation of audio payload types + +Audio payload types are assigned from a table by the [PayloadTypeMapper][2] +class. New audio codecs should be allocated in the lower dynamic range [35,63], +starting at 63, to reduce collisions with payload types + +## Allocation of video payload types + +Video payload types are allocated by the +[GetPayloadTypesAndDefaultCodecs method][3]. The set of codecs depends on the +platform, in particular for H264 codecs and their different profiles. Payload +numbers are assigned ascending from 96 for video codecs and their +[associated retransmission format](https://datatracker.ietf.org/doc/html/rfc4588). +Some codecs like flexfec-03 and AV1 are assigned to the lower range [35,63] for +reasons explained above. When the upper range [96,127] is exhausted, payload +types are assigned to the lower range [35,63], starting at 35. + +## Handling of payload type collisions + +Due to the requirement that payload types must be uniquely identifiable when +using [BUNDLE](https://datatracker.ietf.org/doc/html/rfc8829) collisions between +the assignments of the audio and video payload types may arise. These are +resolved by the [UsedPayloadTypes][4] class which will reassign payload type +numbers descending from 127. + +[1]: https://datatracker.ietf.org/doc/html/rfc3550#section-5.1 +[2]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/media/engine/payload_type_mapper.cc;l=25;drc=4f26a3c7e8e20e0e0ca4ca67a6ebdf3f5543dc3f +[3]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/media/engine/webrtc_video_engine.cc;l=119;drc=b412efdb780c86e6530493afa403783d14985347 +[4]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/used_ids.h;l=94;drc=b412efdb780c86e6530493afa403783d14985347 diff --git a/third_party/libwebrtc/pc/g3doc/sctp_transport.md b/third_party/libwebrtc/pc/g3doc/sctp_transport.md new file mode 100644 index 0000000000..161315324e --- /dev/null +++ b/third_party/libwebrtc/pc/g3doc/sctp_transport.md @@ -0,0 +1,42 @@ +<!-- go/cmark --> +<!--* freshness: {owner: 'hta' reviewed: '2021-04-13'} *--> + +# SctpTransport + +## webrtc::SctpTransport + +The [`webrtc::SctpTransport`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/sctp_transport.h;l=33?q=class%20webrtc::SctpTransport) class encapsulates an SCTP association, and exposes a +few properties of this association to the WebRTC user (such as Chrome). + +The SctpTransport is used to support Datachannels, as described in the [WebRTC +specification for the Peer-to-peer Data +API](https://w3c.github.io/webrtc-pc/#peer-to-peer-data-api). + +The public interface ([`webrtc::SctpTransportInterface`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/sctp_transport_interface.h?q=webrtc::SctpTransportInterface)) exposes an observer +interface where the user can define a callback to be called whenever the state +of an SctpTransport changes; this callback is called on the network thread (as +set during PeerConnectionFactory initialization). + +The implementation of this object lives in pc/sctp_transport.{h,cc}, and is +basically a wrapper around a `cricket::SctpTransportInternal`, hiding its +implementation details and APIs that shoudldn't be accessed from the user. + +The `webrtc::SctpTransport` is a ref counted object; it should be regarded +as owned by the PeerConnection, and will be closed when the PeerConnection +closes, but the object itself may survive longer than the PeerConnection. + +## cricket::SctpTransportInternal + +[`cricket::SctpTransportInternal`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/media/sctp/sctp_transport_internal.h?q=cricket::SctpTransportInternal) owns two objects: The SCTP association object +and the DTLS transport, which is the object used to send and receive messages +as emitted from or consumed by the sctp library. + +It communicates state changes and events using sigslot. + +See header files for details. + + + + + + diff --git a/third_party/libwebrtc/pc/g3doc/srtp.md b/third_party/libwebrtc/pc/g3doc/srtp.md new file mode 100644 index 0000000000..eb457efacf --- /dev/null +++ b/third_party/libwebrtc/pc/g3doc/srtp.md @@ -0,0 +1,72 @@ +<!-- go/cmark --> +<!--* freshness: {owner: 'hta' reviewed: '2021-05-13'} *--> + +# SRTP in WebRTC + +WebRTC mandates encryption of media by means of the Secure Realtime Protocol, or +SRTP, which is described in +[RFC 3711](https://datatracker.ietf.org/doc/html/rfc3711). + +The key negotiation in WebRTC happens using DTLS-SRTP which is described in +[RFC 5764](https://datatracker.ietf.org/doc/html/rfc5764). The older +[SDES protocol](https://datatracker.ietf.org/doc/html/rfc4568) is implemented +but not enabled by default. + +Unencrypted RTP can be enabled for debugging purposes by setting the +PeerConnections [`disable_encryption`][1] option to true. + +## Supported cipher suites + +The implementation supports the following cipher suites: + +* SRTP_AES128_CM_HMAC_SHA1_80 +* SRTP_AEAD_AES_128_GCM +* SRTP_AEAD_AES_256_GCM + +The SRTP_AES128_CM_HMAC_SHA1_32 cipher suite is accepted for audio-only +connections if offered by the other side. It is not actively supported, see +[SelectCrypto][2] for details. + +The cipher suite ordering allows a non-WebRTC peer to prefer GCM cipher suites, +however they are not selected as default by two instances of the WebRTC library. + +## cricket::SrtpSession + +The [`cricket::SrtpSession`][3] is providing encryption and decryption of SRTP +packets using [`libsrtp`](https://github.com/cisco/libsrtp). Keys will be +provided by `SrtpTransport` or `DtlsSrtpTransport` in the [`SetSend`][4] and +[`SetRecv`][5] methods. + +Encryption and decryption happens in-place in the [`ProtectRtp`][6], +[`ProtectRtcp`][7], [`UnprotectRtp`][8] and [`UnprotectRtcp`][9] methods. The +`SrtpSession` class also takes care of initializing and deinitializing `libsrtp` +by keeping track of how many instances are being used. + +## webrtc::SrtpTransport and webrtc::DtlsSrtpTransport + +The [`webrtc::SrtpTransport`][10] class is controlling the `SrtpSession` +instances for RTP and RTCP. When +[rtcp-mux](https://datatracker.ietf.org/doc/html/rfc5761) is used, the +`SrtpSession` for RTCP is not needed. + +[`webrtc:DtlsSrtpTransport`][11] is a subclass of the `SrtpTransport` that +extracts the keying material when the DTLS handshake is done and configures it +in its base class. It will also become writable only once the DTLS handshake is +done. + +## cricket::SrtpFilter + +The [`cricket::SrtpFilter`][12] class is used to negotiate SDES. + +[1]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/peer_connection_interface.h;l=1413;drc=f467b445631189557d44de86a77ca6a0c3e2108d +[2]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/media_session.cc;l=297;drc=3ac73bd0aa5322abee98f1ff8705af64a184bf61 +[3]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=33;drc=be66d95ab7f9428028806bbf66cb83800bda9241 +[4]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=40;drc=be66d95ab7f9428028806bbf66cb83800bda9241 +[5]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=51;drc=be66d95ab7f9428028806bbf66cb83800bda9241 +[6]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=62;drc=be66d95ab7f9428028806bbf66cb83800bda9241 +[7]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=69;drc=be66d95ab7f9428028806bbf66cb83800bda9241 +[8]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=72;drc=be66d95ab7f9428028806bbf66cb83800bda9241 +[9]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=73;drc=be66d95ab7f9428028806bbf66cb83800bda9241 +[10]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_transport.h;l=37;drc=a4d873786f10eedd72de25ad0d94ad7c53c1f68a +[11]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/dtls_srtp_transport.h;l=31;drc=2f8e0536eb97ce2131e7a74e3ca06077aa0b64b3 +[12]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_filter.h;drc=d15a575ec3528c252419149d35977e55269d8a41 |