From 940108b04f507cd0ddadb2fdb306139f0d30e245 Mon Sep 17 00:00:00 2001 From: Artem Titov Date: Wed, 26 May 2021 12:47:34 +0200 Subject: [PATCH] Apply autoformat to the docs Bug: None Change-Id: Iea7823827d6f5a2d400ccbb208f91829165ee518 Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/220163 Reviewed-by: Harald Alvestrand Reviewed-by: Artem Titov Commit-Queue: Artem Titov Cr-Commit-Position: refs/heads/master@{#34133} --- pc/g3doc/dtls_transport.md | 41 +++++++++++++++++++++--------- pc/g3doc/srtp.md | 52 ++++++++++++++++++++++++++++---------- 2 files changed, 67 insertions(+), 26 deletions(-) diff --git a/pc/g3doc/dtls_transport.md b/pc/g3doc/dtls_transport.md index 8b4ccaf3f1..65206dff5d 100644 --- a/pc/g3doc/dtls_transport.md +++ b/pc/g3doc/dtls_transport.md @@ -4,28 +4,45 @@ ## 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). +* 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 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. +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). +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]. + +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/+/master:third_party/webrtc/pc/dtls_transport.h;l=32;drc=6a55e7307b78edb50f94a1ff1ef8393d58218369 [2]: https://source.chromium.org/chromium/chromium/src/+/master:third_party/webrtc/api/dtls_transport_interface.h;l=76;drc=34437d5660a80393d631657329ef74c6538be25a diff --git a/pc/g3doc/srtp.md b/pc/g3doc/srtp.md index 3c806e1bbd..47446157c9 100644 --- a/pc/g3doc/srtp.md +++ b/pc/g3doc/srtp.md @@ -2,36 +2,60 @@ # 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. +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). -Unencrypted RTP can be enabled for debugging purposes by setting the PeerConnections [`disable_encryption`][1] option to true. +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. +* SRTP_AES128_CM_HMAC_SHA1_80 +* SRTP_AEAD_AES_128_GCM +* SRTP_AEAD_AES_256_GCM -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. +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. +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. +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