Wireshark  4.3.0
The Wireshark network protocol analyzer
packet-rtp.h
1 /* packet-rtp.h
2  *
3  * Routines for RTP dissection
4  * RTP = Real time Transport Protocol
5  *
6  * Copyright 2000, Philips Electronics N.V.
7  * Written by Andreas Sikkema <andreas.sikkema@philips.com>
8  *
9  * Wireshark - Network traffic analyzer
10  * By Gerald Combs <gerald@wireshark.org>
11  * Copyright 1998 Gerald Combs
12  *
13  * SPDX-License-Identifier: GPL-2.0-or-later
14  */
15 
16 #ifndef __PACKET_RTP_H__
17 #define __PACKET_RTP_H__
18 
19 #include "epan/packet.h"
20 #include "ws_symbol_export.h"
21 
22 #include "packet-btavdtp.h"
23 #include "packet-sdp.h"
24 
25 #define RTP_MEDIA_AUDIO 1
26 #define RTP_MEDIA_VIDEO 2
27 #define RTP_MEDIA_OTHER 4
28 
29 struct _rtp_info {
30  unsigned int info_version;
31  gboolean info_padding_set;
32  gboolean info_marker_set;
33  guint32 info_media_types;
34  unsigned int info_payload_type;
35  guint16 info_seq_num;
36  guint32 info_extended_seq_num;
37  guint32 info_timestamp;
38  guint64 info_extended_timestamp;
39  guint32 info_sync_src;
40  guint info_data_len; /* length of raw rtp data as reported */
41  gboolean info_all_data_present; /* FALSE if data is cut off */
42  guint info_payload_offset; /* start of payload relative to info_data */
43  guint info_payload_len; /* length of payload (not incl padding) */
44  gboolean info_is_srtp;
45  guint32 info_setup_frame_num; /* the frame num of the packet that set this RTP connection */
46  const guint8* info_data; /* pointer to raw rtp data */
47  const gchar *info_payload_type_str;
48  gint info_payload_rate;
49  unsigned info_payload_channels;
50  wmem_map_t *info_payload_fmtp_map;
51  gboolean info_is_ed137;
52  const gchar *info_ed137_info; /* pointer to static string, no freeing is required */
53  /*
54  * info_data: pointer to raw rtp data = header + payload incl. padding.
55  * That should be safe because the "epan_dissect_t" constructed for the packet
56  * has not yet been freed when the taps are called.
57  * (destroying the "epan_dissect_t" will end up freeing all the tvbuffs
58  * and hence invalidating pointers to their data).
59  * See "add_packet_to_packet_list()" for details.
60  */
61 };
62 
63 /* definitions for SRTP dissection */
64 /* https://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml */
65 
66 /* Encryption algorithms */
67 #define SRTP_ENC_ALG_NOT_SET 0 /* Data not available/empty record */
68 #define SRTP_ENC_ALG_NULL 1 /* non-encrypted SRTP payload - may still be authenticated */
69 #define SRTP_ENC_ALG_AES_CM 2 /* SRTP default algorithm */
70 #define SRTP_ENC_ALG_AES_F8 3
71 #define SRTP_ENC_ALG_AES_GCM 4 /* RFC 7714 */
72 
73 /* Authentication algorithms */
74 #define SRTP_AUTH_ALG_NONE 0 /* no auth tag in SRTP/RTP payload */
75 #define SRTP_AUTH_ALG_HMAC_SHA1 1 /* SRTP default algorithm */
76 #define SRTP_AUTH_ALG_GMAC 2 /* RFC 7714 */
77 
78 
79 #if 0 /* these are only needed once the dissector include the crypto functions to decrypt and/or authenticate */
80 struct srtp_key_info
81 {
82  guint8 *master_key; /* pointer to an wmem_file_scope'ed master key */
83  guint8 *master_salt; /* pointer to an wmem_file_scope'ed salt for this master key - NULL if no salt */
84  guint8 key_generation_rate; /* encoded as the power of 2, 0..24, or 255 (=zero rate) */
85  /* Either the MKI value is used (in which case from=to=0), or the <from,to> values are used (and MKI=0) */
86  guint32 from_roc; /* 32 MSBs of a 48 bit value - frame from which this key is valid (roll-over counter part) */
87  guint16 from_seq; /* 16 LSBs of a 48 bit value - frame from which this key is valid (sequence number part) */
88  guint32 to_roc; /* 32 MSBs of a 48 bit value - frame to which this key is valid (roll-over counter part) */
89  guint16 to_seq; /* 16 LSBs of a 48 bit value - frame to which this key is valid (sequence number part) */
90  guint32 mki; /* the MKI value associated with this key */
91 };
92 #endif
93 
94 struct srtp_info
95 {
96  guint encryption_algorithm; /* at present only NULL vs non-NULL matter */
97  guint auth_algorithm; /* at present only NULL vs non-NULL matter */
98  guint mki_len; /* number of octets used for the MKI in the RTP payload */
99  guint auth_tag_len; /* number of octets used for the Auth Tag in the RTP payload */
100 #if 0 /* these are only needed once the dissector include the crypto functions to decrypt and/or authenticate */
101  struct srtp_key_info **master_keys; /* an array of pointers to master keys and their info, the array and each key struct being wmem_file_scope'ed */
102  void *enc_alg_info, /* algorithm-dependent info struct - may be void for default alg with default params */
103  void *auth_alg_info /* algorithm-dependent info struct - void for default alg with default params */
104 #endif
105 };
106 
107 /* an opaque object holding the hash table - use accessor functions to create/destroy/find */
109 
110 /* RTP dynamic payload handling - use the following to create, insert, lookup, and free the
111  dynamic payload information. Internally, RTP creates the GHashTable with a wmem file scope
112  and increments the ref_count when it saves the info to conversations later. The calling
113  dissector (SDP, H.245, etc.) uses these functions as an interface. If the calling dissector
114  is done with the rtp_dyn_payload_t* for good, it should call rtp_dyn_payload_free() which
115  will decrement the ref_count and free's it if the ref_count is 0. In the worst case, it
116  will get free'd when the wmem file scope is over.
117 
118  This was changed because there were too many bugs with SDP's handling of memory ownership
119  of the GHashTable, with RTP freeing things SDP didn't think were free'ed. And also because
120  the GHashTables never got free'd in many cases by several dissectors.
121  */
122 
123 /* creates a new hashtable and sets ref_count to 1, returning the newly created object */
124 WS_DLL_PUBLIC
125 rtp_dyn_payload_t* rtp_dyn_payload_new(void);
126 
127 /* Creates a copy of the given dynamic payload information. */
128 rtp_dyn_payload_t* rtp_dyn_payload_dup(rtp_dyn_payload_t *rtp_dyn_payload);
129 
130 /* Inserts the given payload type key, for the encoding name, sample rate and
131  audio channels, into the hash table. Copy all the format parameters in the
132  map given into the format parameter map for the new entry.
133  This makes copies of the encoding name and the format parameters, scoped to
134  the life of the capture file or sooner if rtp_dyn_payload_free is called.
135 
136  @param rtp_dyn_payload The hashtable of dynamic payload information
137  @param pt The RTP dynamic payload type number to insert
138  @param encoding_name The encoding name to assign to the payload type
139  @param sample_rate The sample rate to assign to the payload type
140  @param channels The number of audio channels to assign to the payload type (unnecessary for video)
141  @param fmtp_map A map of format parameters to add to the new entry (can be NULL)
142  */
143 WS_DLL_PUBLIC
144 void rtp_dyn_payload_insert_full(rtp_dyn_payload_t *rtp_dyn_payload,
145  const guint pt,
146  const gchar* encoding_name,
147  const int sample_rate,
148  const unsigned channels,
149  wmem_map_t* fmtp_map);
150 
151 /* Inserts the given payload type key, for the encoding name, sample rate, and
152  channels, into the hash table.
153  This makes copies of the encoding name, scoped to the life of the capture
154  file or sooner if rtp_dyn_payload_free is called.
155 
156  @param rtp_dyn_payload The hashtable of dynamic payload information
157  @param pt The RTP dynamic payload type number to insert
158  @param encoding_name The encoding name to assign to the payload type
159  @param sample_rate The sample rate to assign to the payload type
160  @param channels The number of audio channels to assign to the payload type (unnecessary for video)
161  */
162 WS_DLL_PUBLIC
163 void rtp_dyn_payload_insert(rtp_dyn_payload_t *rtp_dyn_payload,
164  const guint pt,
165  const gchar* encoding_name,
166  const int sample_rate,
167  const unsigned channels);
168 
169 /*
170  * Adds the given format parameter to the fmtp_map for the given payload type
171  * in the RTP dynamic payload hashtable, if that payload type has been
172  * inserted with rtp_dyn_payload_insert. The format parameter name and value
173  * are copied, with scope the lifetime of the capture file.
174  *
175  * @param rtp_dyn_payload The hashtable of dynamic payload information
176  * @param pt The RTP payload type number the parameter is for
177  * @param name The name of the format parameter to add
178  * @param value The value of the format parameter to add
179  */
180 WS_DLL_PUBLIC
181 void rtp_dyn_payload_add_fmtp(rtp_dyn_payload_t *rtp_dyn_payload,
182  const guint pt,
183  const char* name,
184  const char* value);
185 
186 /* Replaces the given payload type key in the hash table, with the encoding name and sample rate.
187  This makes copies of the encoding name, scoped to the life of the capture file or sooner if
188  rtp_dyn_payload_free is called. The replaced encoding name is free'd immediately. */
189 /* Not used anymore
190 WS_DLL_PUBLIC
191 void rtp_dyn_payload_replace(rtp_dyn_payload_t *rtp_dyn_payload,
192  const guint pt,
193  const gchar* encoding_name,
194  const int sample_rate);
195 */
196 
197 /* removes the given payload type */
198 /* Not used anymore
199 WS_DLL_PUBLIC
200 gboolean rtp_dyn_payload_remove(rtp_dyn_payload_t *rtp_dyn_payload, const guint pt);
201 */
202 
203 /* retrieves the encoding name for the given payload type; the string returned is only valid
204  until the entry is replaced, removed, or the hash table is destroyed, so duplicate it if
205  you need it long. */
206 WS_DLL_PUBLIC
207 const gchar* rtp_dyn_payload_get_name(rtp_dyn_payload_t *rtp_dyn_payload, const guint pt);
208 
209 /*
210  Retrieves the encoding name, sample rate, and format parameters map for the
211  given payload type. The encoding string pointed to is only valid until
212  the entry is replaced, removed, or the hash table is destroyed, so duplicate
213  it if you need it long. Each of the three output parameters are optional and
214  can be NULL.
215 
216  @param rtp_dyn_payload The hashtable of dynamic payload information
217  @param pt The RTP payload type number to look up
218  @param[out] encoding_name The encoding name assigned to that payload type
219  @param[out] sample_rate The sample rate assigned to that payload type
220  @param[out] channels The number of audio channels for that payload type
221  @param[out] fmtp_map The map of format parameters assigned to that type
222  @return TRUE if successful, FALSE if there is no entry for that payload type
223 */
224 WS_DLL_PUBLIC
225 gboolean rtp_dyn_payload_get_full(rtp_dyn_payload_t *rtp_dyn_payload, const guint pt,
226  const gchar **encoding_name, int *sample_rate, unsigned *channels, wmem_map_t **fmtp_map);
227 
228 /* Free's and destroys the dyn_payload hash table; internally this decrements the ref_count
229  and only free's it if the ref_count == 0. */
230 WS_DLL_PUBLIC
231 void rtp_dyn_payload_free(rtp_dyn_payload_t *rtp_dyn_payload);
232 
233 
234 #ifdef DEBUG_CONVERSATION
235 /* used for printing out debugging info, if DEBUG_CONVERSATION is defined */
236 void rtp_dump_dyn_payload(rtp_dyn_payload_t *rtp_dyn_payload);
237 #endif
238 
239 /* Proto data key values */
240 #define RTP_CONVERSATION_PROTO_DATA 0
241 #define RTP_DECODE_AS_PROTO_DATA 1
242 
243 #define MAX_RTP_SETUP_METHOD_SIZE 11
250 {
251  gchar method[MAX_RTP_SETUP_METHOD_SIZE + 1];
252  guint32 frame_number;
253  guint32 media_types;
254  rtp_dyn_payload_t *rtp_dyn_payload;
256  guint32 extended_seqno;
263  struct srtp_info *srtp_info; /* SRTP context */
264  bta2dp_codec_info_t *bta2dp_info;
265  btvdp_codec_info_t *btvdp_info;
266  wmem_array_t *rtp_sdp_setup_info_list;
267 };
268 
269 /* Add an RTP conversation with the given details */
270 WS_DLL_PUBLIC
271 void rtp_add_address(packet_info *pinfo,
272  const port_type ptype,
273  address *addr, int port,
274  int other_port,
275  const gchar *setup_method,
276  guint32 setup_frame_number,
277  guint32 media_types,
278  rtp_dyn_payload_t *rtp_dyn_payload);
279 
280 /* Add an SRTP conversation with the given details */
281 WS_DLL_PUBLIC
282 void srtp_add_address(packet_info *pinfo,
283  const port_type ptype,
284  address *addr, int port,
285  int other_port,
286  const gchar *setup_method,
287  guint32 setup_frame_number,
288  guint32 media_types,
289  rtp_dyn_payload_t *rtp_dyn_payload,
290  struct srtp_info *srtp_info,
291  sdp_setup_info_t *setup_info);
292 
293 /* Add an Bluetooth conversation with the given details */
294 void
295 bluetooth_add_address(packet_info *pinfo, address *addr, guint32 stream_number,
296  const gchar *setup_method, guint32 setup_frame_number,
297  guint32 media_types, void *data);
298 
299 /* Dissect the header only, without side effects */
300 WS_DLL_PUBLIC
301 gint dissect_rtp_shim_header(tvbuff_t *tvb, gint start,
302  packet_info *pinfo, proto_tree *tree,
303  struct _rtp_info *rtp_info);
304 
306  guint payload_len;
307  guint8 padding_len; /* without padding count byte */
308 };
309 
310 #endif /*__PACKET_RTP_H__*/
Definition: address.h:56
Definition: packet-btavdtp.h:26
Definition: packet-btavdtp.h:35
Definition: packet_info.h:44
Definition: proto.h:904
Definition: packet-rtp.c:134
Definition: packet-rtp.h:29
Definition: packet-rtp.h:250
struct srtp_info * srtp_info
Definition: packet-rtp.h:263
struct _rtp_private_conv_info * rtp_conv_info
Definition: packet-rtp.h:260
guint32 extended_seqno
Definition: packet-rtp.h:256
guint64 extended_timestamp
Definition: packet-rtp.h:259
guint32 media_types
Definition: packet-rtp.h:253
Definition: packet-rtp.h:305
Definition: packet-rtp.c:94
Definition: packet-sdp.h:40
Definition: wmem_array.c:27
Definition: wmem_map.c:44
Definition: packet-rtp.h:95
Definition: tvbuff-int.h:35