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