admin/webrtc_m130
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Apply autoformat to the docs

Browse Source 
Bug: None
Change-Id: Iea7823827d6f5a2d400ccbb208f91829165ee518
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/220163
Reviewed-by: Harald Alvestrand <hta@webrtc.org>
Reviewed-by: Artem Titov <titovartem@webrtc.org>
Commit-Queue: Artem Titov <titovartem@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#34133}
This commit is contained in:
Artem Titov 2021-05-26 12:47:34 +02:00 committed by WebRTC LUCI CQ
parent 8f8bf252e6
commit 940108b04f
2 changed files with 67 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
pc/g3doc/dtls_transport.md
View File

@ -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

52
pc/g3doc/srtp.md
View File

@ -2,36 +2,60 @@
<?% config.freshness.owner = 'hta' %?>
# 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