Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

5 files changed, 325 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..6dd7b99b09
--- /dev/null
+++ b/third_party/libwebrtc/pc/g3doc/rtp.md
@@ -0,0 +1,99 @@
+<!-- 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.
+
+# Bitrate probing
+
+Bandwidth estimation sometimes requires sending RTP packets to ramp up the
+estimate above a certain treshold. WebRTC uses two techniques for that:
+
+* Packets that only consist of RTP padding
+* RTX packets
+
+At the receiving end, both types of probing packets do not interfere with media processing.
+After being taken into account for bandwidth estimation, probing packets only consisting
+of padding can be dropped and RTX packets act as redundancy.
+
+Using RTX for probing is generally preferred as padding probes are limited to 256 bytes
+of RTP payload which results in a larger number of packets being used for probing which
+is a disadvantage from a congestion control point of view.
+
+## Padding probes
+
+Padding probes consist of RTP packets with header extensions (either abs-send time or
+the transport-wide-cc sequence number) and set the RTP "P" bit. The last byte of the
+RTP payload which specifies the amount of padding is set to 255 and preceeded by 255
+bytes of all zeroes. See [section 5.1 of RFC3550][1].
+Padding probes use the RTX RTP stream (i.e. payload type, sequence number and timestamp)
+when RTX is negotiated or share the same RTP stream as the media packets otherwise.
+
+Padding probes are used either when
+* RTX is not negotiated (such as for audio, less commonly for video) or
+* no suitable original packet is found for RTX probing.
+
+Padding probes should not be interleaved with packets of a video frame.
+
+## RTX probes
+
+RTX probes are resends of previous packets that use RTX retransmissions specified in
+[RFC4588](https://www.rfc-editor.org/rfc/rfc4588) as payload format when negotiated with
+the peer. These packets will have a different abs-send-time or transport-wide-cc sequence
+number and use the RTX RTP stream (i.e. RTX payload type, sequence number and timestamp)
+associated with the media RTP stream.
+
+RTX probing uses recently sent RTP packets that have not yet been acknowledged by
+the remote side. Sending these packets again has a small chance of being useful when the
+original packet is lost and will not affect RTP processing at the receiver otherwise.
+
+[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..100eb92e47
--- /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 shouldn'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