FFmpeg
Loading...
Searching...
No Matches
rtc.h
Go to the documentation of this file.
1/*
2 * Shared WebRTC helpers
3 * Copyright (c) 2023 The FFmpeg Project
4 *
5 * This file is part of FFmpeg.
6 *
7 * FFmpeg is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * FFmpeg is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with FFmpeg; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 */
21
22#ifndef AVFORMAT_RTC_H
23#define AVFORMAT_RTC_H
24
25#include <stdint.h>
26#include <stddef.h>
27
28#include "libavutil/base64.h"
29#include "libavutil/lfg.h"
30
31#include "avformat.h"
32#include "tls.h"
33#include "url.h"
34
35/**
36 * Maximum size limit of a Session Description Protocol (SDP),
37 * be it an offer or answer.
38 */
39#define RTC_MAX_SDP_SIZE 8192
40
41/**
42 * The size of the Secure Real-time Transport Protocol (SRTP) master key material
43 * that is exported by Secure Sockets Layer (SSL) after a successful Datagram
44 * Transport Layer Security (DTLS) handshake. This material consists of a key
45 * of 16 bytes and a salt of 14 bytes.
46 */
47#define RTC_DTLS_SRTP_KEY_LEN 16
48#define RTC_DTLS_SRTP_SALT_LEN 14
49
50#define RTC_SRTP_KEY_SIZE AV_BASE64_SIZE(RTC_DTLS_SRTP_KEY_LEN + RTC_DTLS_SRTP_SALT_LEN)
51
52/**
53 * The profile for OpenSSL's SRTP is SRTP_AES128_CM_SHA1_80, see ssl/d1_srtp.c.
54 * The profile for FFmpeg's SRTP is SRTP_AES128_CM_HMAC_SHA1_80, see libavformat/srtp.c.
55 */
56#define RTC_SRTP_SUITE "SRTP_AES128_CM_HMAC_SHA1_80"
57
58/**
59 * The maximum size of the Secure Real-time Transport Protocol (SRTP) HMAC checksum
60 * and padding that is appended to the end of the packet. To calculate the maximum
61 * size of the User Datagram Protocol (UDP) packet that can be sent out, subtract
62 * this size from the `pkt_size`.
63 */
64#define RTC_DTLS_SRTP_CHECKSUM_LEN 16
65
66#define RTC_US_PER_MS 1000
67
68/**
69 * Maximum size of the buffer for sending and receiving UDP packets.
70 * Please note that this size does not limit the size of the UDP packet that can be sent.
71 * To set the limit for packet size, modify the `pkt_size` parameter.
72 * For instance, it is possible to set the UDP buffer to 4096 to send or receive packets,
73 * but please keep in mind that the `pkt_size` option limits the packet size to 1400.
74 */
75#define RTC_MAX_UDP_BUFFER_SIZE 4096
76
77/**
78 * The RTP header is 12 bytes long, comprising the Version(1B), PT(1B),
79 * SequenceNumber(2B), Timestamp(4B), and SSRC(4B).
80 * See https://www.rfc-editor.org/rfc/rfc3550#section-5.1
81 */
82#define RTC_RTP_HEADER_SIZE 12
83
84/* Calculate the elapsed time from starttime to endtime in milliseconds. */
85#define RTC_ELAPSED(starttime, endtime) ((float)(endtime - starttime) / 1000)
86
89
90 /* The initial state. */
92 /* The local peer has sent the offer. */
94 /* The local peer has received the answer. */
96 /**
97 * After parsing the answer received from the peer, the local peer negotiates the abilities
98 * in the offer that it generated.
99 */
101 /* The local peer has connected via UDP. */
103 /* The local peer has sent the ICE request to the peer. */
105 /* The local peer has received the ICE response from the peer. */
107 /* The local peer has finished the DTLS handshake with the peer. */
109 /* The local peer has finished the SRTP setup. */
111 /* The local peer is ready to send/receive media frames. */
113 /* The local peer has failed. */
115};
116
117typedef enum RTCFlags {
118 RTC_DTLS_ACTIVE = (1 << 0),
119} RTCFlags;
120
121typedef struct RTCContext {
123
124 uint32_t flags;
125 /* The state of the RTC connection. */
127
128 /* The random number generator. */
130
131 /* The ICE username and pwd fragment generated by the local peer. */
134
135 /**
136 * This is the SDP offer generated by the local peer based on the codec parameters,
137 * DTLS, and ICE information.
138 */
140
142 uint64_t ice_tie_breaker; // random 64 bit, for ICE-CONTROLLING
143 /* The ICE username and pwd from remote server. */
146 /**
147 * This represents the ICE candidate protocol, priority, host and port.
148 * Currently, we only support one candidate and choose the first UDP candidate.
149 * However, we plan to support multiple candidates in the future.
150 */
152 char *ice_host;
154
155 /* The SDP answer received from the WebRTC server. */
157 /* The resource URL returned in the Location header of the HTTP response. */
159
160 /* These variables represent timestamps used for calculating and tracking the cost. */
171
172 /* The certificate and private key content used for DTLS handshake */
175 /* The fingerprint of certificate, used in SDP offer. */
177 /* remote DTLS cert fingerprint from SDP answer (sha-256). */
179
180 /**
181 * This represents the material used to build the SRTP master key. It is
182 * generated by DTLS and has the following layout:
183 * 16B 16B 14B 14B
184 * client_key | server_key | client_salt | server_salt
185 */
187
190
191 /* TODO: Use AVIOContext instead of URLContext */
193
194 /* The UDP transport is used for delivering ICE, DTLS and SRTP packets. */
196 /* The buffer for UDP transmission. */
198
199 /* The timeout in milliseconds for ICE and DTLS handshake. */
201 /* The timeout in microseconds for HTTP operations. */
203 /**
204 * The size of RTP packet, should generally be set to MTU.
205 * Note that pion requires a smaller value, for example, 1200.
206 */
208 int ts_buffer_size; /* Underlying protocol send/receive buffer size */
209 /**
210 * The optional Bearer token for HTTP Authorization.
211 * See https://www.ietf.org/archive/id/draft-ietf-wish-whip-08.html#name-authentication-and-authoriz
212 */
214 /* The certificate and private key used for DTLS handshake. */
216 char *key_file;
217} RTCContext;
218
220
222
224
225int ff_rtc_media_is_rtp_rtcp(const uint8_t *b, int size);
226
227int ff_rtc_media_is_rtcp(const uint8_t *b, int size);
228
230
232
234
236
238
239void ff_rtc_ice_check_and_update_consent(RTCContext *rtc, const uint8_t *buf, int size);
240
242
243void ff_rtc_deinit(RTCContext *rtc);
244
245#define RTC_OPTIONS(pstruct, field, flag) \
246 { "handshake_timeout", "Timeout in milliseconds for ICE and DTLS handshake.", offsetof(pstruct, field.handshake_timeout), AV_OPT_TYPE_INT, { .i64 = 5000 }, -1, INT_MAX, flag }, \
247 { "timeout", "Set timeout for socket I/O operations", offsetof(pstruct, field.timeout), AV_OPT_TYPE_DURATION, { .i64 = -1 }, -1, INT_MAX, flag }, \
248 { "pkt_size", "The maximum size, in bytes, of RTP packets that send out", offsetof(pstruct, field.pkt_size), AV_OPT_TYPE_INT, { .i64 = 1200 }, -1, INT_MAX, flag }, \
249 { "ts_buffer_size", "The buffer size, in bytes, of underlying protocol", offsetof(pstruct, field.ts_buffer_size), AV_OPT_TYPE_INT, { .i64 = -1 }, -1, INT_MAX, flag }, \
250 { "dtls_active", "Set dtls role as active", 0, AV_OPT_TYPE_CONST, { .i64 = RTC_DTLS_ACTIVE }, 0, UINT_MAX, flag, .unit = "flags" }, \
251 { "authorization", "The optional Bearer token for HTTP Authorization", offsetof(pstruct, field.authorization), AV_OPT_TYPE_STRING, { .str = NULL }, 0, 0, flag }, \
252 { "cert_file", "The optional certificate file path for DTLS", offsetof(pstruct, field.cert_file), AV_OPT_TYPE_STRING, { .str = NULL }, 0, 0, flag }, \
253 { "key_file", "The optional private key file path for DTLS", offsetof(pstruct, field.key_file), AV_OPT_TYPE_STRING, { .str = NULL }, 0, 0, flag }
254
255#endif /* AVFORMAT_RTC_H */
Main libavformat public API header.
long long int64_t
Definition coverity.c:34
#define b
Definition input.c:43
#define RTC_SRTP_KEY_SIZE
Definition rtc.h:50
#define RTC_MAX_UDP_BUFFER_SIZE
Maximum size of the buffer for sending and receiving UDP packets.
Definition rtc.h:75
void ff_rtc_ice_check_and_update_consent(RTCContext *rtc, const uint8_t *buf, int size)
Definition rtc.c:980
void ff_rtc_deinit(RTCContext *rtc)
Definition rtc.c:1000
#define RTC_DTLS_SRTP_SALT_LEN
Definition rtc.h:48
int ff_rtc_parse_answer(RTCContext *rtc)
Parses the ICE ufrag, pwd, and candidates from the SDP answer.
Definition rtc.c:330
int ff_rtc_media_is_rtcp(const uint8_t *b, int size)
Definition rtc.c:651
int ff_rtc_ice_dtls_handshake(RTCContext *rtc)
Definition rtc.c:737
int ff_rtc_ice_check_consent(RTCContext *rtc, int64_t now)
Definition rtc.c:988
int ff_rtc_srtp_export_keys(RTCContext *rtc)
Definition rtc.c:846
int ff_rtc_dispose_session(RTCContext *rtc)
RTC is connectionless, for it's based on UDP, so it check whether sesison is timeout.
Definition rtc.c:899
int ff_rtc_media_is_rtp_rtcp(const uint8_t *b, int size)
In RTP packets, the first byte is represented as 0b10xxxxxx, where the initial two bits (0b10) indica...
Definition rtc.c:645
RTCFlags
Definition rtc.h:117
@ RTC_DTLS_ACTIVE
Definition rtc.h:118
int ff_rtc_initialize(RTCContext *rtc)
Definition rtc.c:165
int ff_rtc_exchange_sdp(RTCContext *rtc)
Exchange SDP offer with WebRTC peer to get the answer.
Definition rtc.c:203
int ff_rtc_ice_check_and_send_consent(RTCContext *rtc, int64_t now)
Refer to RFC 7675 Periodically send Consent Freshness STUN Binding Request.
Definition rtc.c:956
#define RTC_DTLS_SRTP_KEY_LEN
The size of the Secure Real-time Transport Protocol (SRTP) master key material that is exported by Se...
Definition rtc.h:47
RTCState
Definition rtc.h:87
@ RTC_STATE_OFFER
Definition rtc.h:93
@ RTC_STATE_FAILED
Definition rtc.h:114
@ RTC_STATE_ANSWER
Definition rtc.h:95
@ RTC_STATE_ICE_CONNECTED
Definition rtc.h:106
@ RTC_STATE_NONE
Definition rtc.h:88
@ RTC_STATE_SRTP_FINISHED
Definition rtc.h:110
@ RTC_STATE_DTLS_FINISHED
Definition rtc.h:108
@ RTC_STATE_INIT
Definition rtc.h:91
@ RTC_STATE_UDP_CONNECTED
Definition rtc.h:102
@ RTC_STATE_READY
Definition rtc.h:112
@ RTC_STATE_ICE_CONNECTING
Definition rtc.h:104
@ RTC_STATE_NEGOTIATED
After parsing the answer received from the peer, the local peer negotiates the abilities in the offer...
Definition rtc.h:100
int ff_rtc_udp_connect(RTCContext *rtc)
To establish a connection with the UDP server, we utilize ICE-LITE in a Client-Server mode.
Definition rtc.c:700
Format I/O context.
Definition avformat.h:1401
Context structure for the Lagged Fibonacci PRNG.
Definition lfg.h:33
char srtp_send_key[RTC_SRTP_KEY_SIZE]
Definition rtc.h:188
uint8_t dtls_srtp_materials[(RTC_DTLS_SRTP_KEY_LEN+RTC_DTLS_SRTP_SALT_LEN) *2]
This represents the material used to build the SRTP master key.
Definition rtc.h:186
char * ice_host
Definition rtc.h:152
int64_t init_time
Definition rtc.h:162
char key_buf[MAX_CERTIFICATE_SIZE]
Definition rtc.h:174
int64_t dtls_time
Definition rtc.h:167
char * remote_fingerprint
Definition rtc.h:178
int pkt_size
The size of RTP packet, should generally be set to MTU.
Definition rtc.h:207
char * sdp_answer
Definition rtc.h:156
uint32_t flags
Definition rtc.h:124
char buf[RTC_MAX_UDP_BUFFER_SIZE]
Definition rtc.h:197
char * key_file
Definition rtc.h:216
int64_t srtp_time
Definition rtc.h:168
AVLFG rnd
Definition rtc.h:129
char * dtls_fingerprint
Definition rtc.h:176
int ts_buffer_size
Definition rtc.h:208
char ice_ufrag_local[9]
Definition rtc.h:132
int64_t ice_time
Definition rtc.h:166
int64_t timeout
Definition rtc.h:202
URLContext * udp
Definition rtc.h:195
char * cert_file
Definition rtc.h:215
char ice_pwd_local[33]
Definition rtc.h:133
int64_t starttime
Definition rtc.h:161
char * ice_protocol
This represents the ICE candidate protocol, priority, host and port.
Definition rtc.h:151
char * sdp_offer
This is the SDP offer generated by the local peer based on the codec parameters, DTLS,...
Definition rtc.h:139
int64_t last_consent_rx_time
Definition rtc.h:170
int64_t offer_time
Definition rtc.h:163
int64_t answer_time
Definition rtc.h:164
int is_peer_ice_lite
Definition rtc.h:141
int ice_port
Definition rtc.h:153
char * ice_ufrag_remote
Definition rtc.h:144
int64_t udp_time
Definition rtc.h:165
enum RTCState state
Definition rtc.h:126
int handshake_timeout
Definition rtc.h:200
uint64_t ice_tie_breaker
Definition rtc.h:142
char srtp_recv_key[RTC_SRTP_KEY_SIZE]
Definition rtc.h:189
char * resource_url
Definition rtc.h:158
char cert_buf[MAX_CERTIFICATE_SIZE]
Definition rtc.h:173
int64_t last_consent_tx_time
Definition rtc.h:169
URLContext * dtls_uc
Definition rtc.h:192
AVFormatContext * ctx
Definition rtc.h:122
char * authorization
The optional Bearer token for HTTP Authorization.
Definition rtc.h:213
char * ice_pwd_remote
Definition rtc.h:145
#define MAX_CERTIFICATE_SIZE
Maximum size limit of a certificate and private key size.
Definition tls.h:34
int size
unbuffered private I/O API