sdp_srtp.h File Reference

SRTP and SDP Security descriptions. More...

#include "asterisk/linkedlists.h"
#include "asterisk/rtp_engine.h"

Include dependency graph for sdp_srtp.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_sdp_crypto_api
struct	ast_sdp_srtp
	structure for secure RTP audio More...

Macros
#define	AST_SRTP_CRYPTO_AES_192   (1 << 6)
#define	AST_SRTP_CRYPTO_AES_256   (1 << 7)
#define	AST_SRTP_CRYPTO_OFFER_OK   (1 << 1)
#define	AST_SRTP_CRYPTO_OLD_NAME   (1 << 8)
#define	AST_SRTP_CRYPTO_TAG_16   (1 << 4)
#define	AST_SRTP_CRYPTO_TAG_32   (1 << 2)
#define	AST_SRTP_CRYPTO_TAG_8   (1 << 5)
#define	AST_SRTP_CRYPTO_TAG_80   (1 << 3)

Typedefs
typedef struct ast_sdp_crypto *(*	sdp_crypto_alloc_cb) (void)
	Initialize and return an ast_sdp_crypto struct. More...
typedef int(*	sdp_crypto_build_offer_cb) (struct ast_sdp_crypto *crypto, int taglen)
	Generate an SRTP a=crypto offer. More...
typedef void(*	sdp_crypto_destroy_cb) (struct ast_sdp_crypto *crypto)
	Destroy a previously allocated ast_sdp_crypto struct. More...
typedef int(*	sdp_crypto_parse_offer_cb) (struct ast_rtp_instance *rtp, struct ast_sdp_srtp *srtp, const char *attr)
	Parse the a=crypto line from SDP and set appropriate values on the ast_sdp_crypto struct. More...
typedef const char *(*	sdp_srtp_get_attr_cb) (struct ast_sdp_srtp *srtp, int dtls_enabled, int default_taglen_32)
	Get the crypto attribute line for the srtp structure. More...

Functions
struct ast_sdp_crypto *	ast_sdp_crypto_alloc (void)
	Initialize an return an ast_sdp_crypto struct. More...
int	ast_sdp_crypto_build_offer (struct ast_sdp_crypto *p, int taglen)
	Generate an SRTP a=crypto offer. More...
void	ast_sdp_crypto_destroy (struct ast_sdp_crypto *crypto)
	Destroy a previously allocated ast_sdp_crypto struct. More...
int	ast_sdp_crypto_process (struct ast_rtp_instance *rtp, struct ast_sdp_srtp *srtp, const char *attr)
	Parse the a=crypto line from SDP and set appropriate values on the ast_sdp_crypto struct. More...
int	ast_sdp_crypto_register (struct ast_sdp_crypto_api *api)
	Register SDP SRTP crypto processing routines. More...
void	ast_sdp_crypto_unregister (struct ast_sdp_crypto_api *api)
	Unregister SDP SRTP crypto processing routines. More...
char *	ast_sdp_get_rtp_profile (unsigned int sdes_active, struct ast_rtp_instance *instance, unsigned int using_avpf, unsigned int force_avp)
	Get the RTP profile in use by a media session. More...
struct ast_sdp_srtp *	ast_sdp_srtp_alloc (void)
	allocate a ast_sdp_srtp structure More...
void	ast_sdp_srtp_destroy (struct ast_sdp_srtp *srtp)
	free a ast_sdp_srtp structure More...
const char *	ast_sdp_srtp_get_attrib (struct ast_sdp_srtp *srtp, int dtls_enabled, int default_taglen_32)
	Get the crypto attribute line for the srtp structure. More...

Detailed Description

SRTP and SDP Security descriptions.

Specified in RFC 3711, 6188, 7714, and 4568

Author

Mikael Magnusson mikma.nosp@m.@use.nosp@m.rs.so.nosp@m.urce.nosp@m.forge.nosp@m..net

Definition in file sdp_srtp.h.

Macro Definition Documentation

AST_SRTP_CRYPTO_AES_192

#define AST_SRTP_CRYPTO_AES_192   (1 << 6)

Definition at line 49 of file sdp_srtp.h.

Referenced by res_sdp_crypto_parse_offer(), and res_sdp_srtp_get_attr().

AST_SRTP_CRYPTO_AES_256

#define AST_SRTP_CRYPTO_AES_256   (1 << 7)

Definition at line 50 of file sdp_srtp.h.

Referenced by res_sdp_crypto_parse_offer(), and res_sdp_srtp_get_attr().

AST_SRTP_CRYPTO_OFFER_OK

#define AST_SRTP_CRYPTO_OFFER_OK   (1 << 1)

Definition at line 44 of file sdp_srtp.h.

Referenced by channel_read_rtp(), handle_request_invite(), parse_dtls_attrib(), process_sdp(), and res_sdp_crypto_parse_offer().

AST_SRTP_CRYPTO_OLD_NAME

#define AST_SRTP_CRYPTO_OLD_NAME   (1 << 8)

Definition at line 51 of file sdp_srtp.h.

Referenced by res_sdp_crypto_parse_offer(), and res_sdp_srtp_get_attr().

AST_SRTP_CRYPTO_TAG_16

#define AST_SRTP_CRYPTO_TAG_16   (1 << 4)

Definition at line 47 of file sdp_srtp.h.

Referenced by res_sdp_crypto_parse_offer(), and res_sdp_srtp_get_attr().

AST_SRTP_CRYPTO_TAG_32

#define AST_SRTP_CRYPTO_TAG_32   (1 << 2)

Definition at line 45 of file sdp_srtp.h.

Referenced by res_sdp_crypto_parse_offer(), and res_sdp_srtp_get_attr().

AST_SRTP_CRYPTO_TAG_8

#define AST_SRTP_CRYPTO_TAG_8   (1 << 5)

Definition at line 48 of file sdp_srtp.h.

Referenced by res_sdp_crypto_parse_offer(), and res_sdp_srtp_get_attr().

AST_SRTP_CRYPTO_TAG_80

#define AST_SRTP_CRYPTO_TAG_80   (1 << 3)

Definition at line 46 of file sdp_srtp.h.

Referenced by res_sdp_crypto_parse_offer(), and res_sdp_srtp_get_attr().

Typedef Documentation

sdp_crypto_alloc_cb

typedef struct ast_sdp_crypto*(* sdp_crypto_alloc_cb) (void)

Initialize and return an ast_sdp_crypto struct.

This function allocates a new ast_sdp_crypto struct and initializes its values

Return values

NULL	on failure
a	pointer to a new ast_sdp_crypto structure

Definition at line 78 of file sdp_srtp.h.

sdp_crypto_build_offer_cb

typedef int(* sdp_crypto_build_offer_cb) (struct ast_sdp_crypto *crypto, int taglen)

Generate an SRTP a=crypto offer.

The offer is stored on the ast_sdp_crypto struct in a_crypto

Parameters

crypto	A valid ast_sdp_crypto struct
taglen	Length

Return values

0	success
nonzero	failure

Definition at line 92 of file sdp_srtp.h.

sdp_crypto_destroy_cb

typedef void(* sdp_crypto_destroy_cb) (struct ast_sdp_crypto *crypto)

Destroy a previously allocated ast_sdp_crypto struct.

Definition at line 67 of file sdp_srtp.h.

sdp_crypto_parse_offer_cb

typedef int(* sdp_crypto_parse_offer_cb) (struct ast_rtp_instance *rtp, struct ast_sdp_srtp *srtp, const char *attr)

Parse the a=crypto line from SDP and set appropriate values on the ast_sdp_crypto struct.

The attribute line should already have "a=crypto:" removed.

Parameters

p	A valid ast_sdp_crypto struct
attr	the a:crypto line from SDP
rtp	The rtp instance associated with the SDP being parsed
srtp	SRTP structure

Return values

0	success
nonzero	failure

Definition at line 108 of file sdp_srtp.h.

sdp_srtp_get_attr_cb

typedef const char*(* sdp_srtp_get_attr_cb) (struct ast_sdp_srtp *srtp, int dtls_enabled, int default_taglen_32)

Get the crypto attribute line for the srtp structure.

The attribute line does not contain the initial "a=crypto:" and does not terminate with "\r\n".

Parameters

srtp	The ast_sdp_srtp structure for which to get an attribute line
dtls_enabled	Whether this connection is encrypted with datagram TLS
default_taglen_32	Whether to default to a tag length of 32 instead of 80

Return values

An	attribute line containing cryptographic information
NULL	if the srtp structure does not require an attribute line containing crypto information

Definition at line 124 of file sdp_srtp.h.

Function Documentation

ast_sdp_crypto_alloc()

struct ast_sdp_crypto* ast_sdp_crypto_alloc

(

void

)

Initialize an return an ast_sdp_crypto struct.

This function allocates a new ast_sdp_crypto struct and initializes its values

Return values

NULL	on failure
a	pointer to a new ast_sdp_crypto structure

Definition at line 71 of file sdp_srtp.c.

References ast_sdp_crypto_api::alloc, and NULL.

Referenced by process_crypto(), and setup_srtp().

{
   if (!sdp_crypto_api) {
      return NULL;
   }
   return sdp_crypto_api->alloc();
}

ast_sdp_crypto_build_offer()

int ast_sdp_crypto_build_offer	(	struct ast_sdp_crypto *	p,
		int	taglen
	)

Generate an SRTP a=crypto offer.

The offer is stored on the ast_sdp_crypto struct in a_crypto

Parameters

p	A valid ast_sdp_crypto struct
taglen	Length

Return values

0	success
nonzero	failure

Definition at line 87 of file sdp_srtp.c.

References ast_sdp_crypto_api::build_offer.

{
   if (!sdp_crypto_api) {
      return -1;
   }
   return sdp_crypto_api->build_offer(p, taglen);
}

ast_sdp_crypto_destroy()

void ast_sdp_crypto_destroy

(

struct ast_sdp_crypto *

crypto

)

Destroy a previously allocated ast_sdp_crypto struct.

Definition at line 64 of file sdp_srtp.c.

References ast_sdp_crypto_api::dtor.

Referenced by ast_sdp_srtp_destroy().

{
   if (sdp_crypto_api) {
      sdp_crypto_api->dtor(crypto);
   }
}

ast_sdp_crypto_process()

int ast_sdp_crypto_process	(	struct ast_rtp_instance *	rtp,
		struct ast_sdp_srtp *	srtp,
		const char *	attr
	)

Parse the a=crypto line from SDP and set appropriate values on the ast_sdp_crypto struct.

The attribute line should already have "a=crypto:" removed.

Parameters

p	A valid ast_sdp_crypto struct
attr	the a:crypto line from SDP
rtp	The rtp instance associated with the SDP being parsed
srtp	SRTP structure

Return values

0	success
nonzero	failure

Definition at line 79 of file sdp_srtp.c.

References ast_sdp_crypto_api::parse_offer.

Referenced by process_crypto(), and setup_sdes_srtp().

{
   if (!sdp_crypto_api) {
      return -1;
   }
   return sdp_crypto_api->parse_offer(rtp, srtp, attr);
}

ast_sdp_crypto_register()

int ast_sdp_crypto_register

(

struct ast_sdp_crypto_api *

api

)

Register SDP SRTP crypto processing routines.

Since

14.0.0

Parameters

api	Callbacks to register.

Return values

0	on success.
-1	on error.

Definition at line 123 of file sdp_srtp.c.

Referenced by res_srtp_init().

{
   if (sdp_crypto_api) {
      return -1;
   }
   sdp_crypto_api = api;
   return 0;
}

ast_sdp_crypto_unregister()

void ast_sdp_crypto_unregister

(

struct ast_sdp_crypto_api *

api

)

Unregister SDP SRTP crypto processing routines.

Since

14.0.0

Parameters

api	Callbacks to unregister.

Returns

Nothing

Definition at line 132 of file sdp_srtp.c.

References NULL.

Referenced by res_srtp_shutdown().

{
   if (sdp_crypto_api == api) {
      sdp_crypto_api = NULL;
   }
}

ast_sdp_get_rtp_profile()

char* ast_sdp_get_rtp_profile	(	unsigned int	sdes_active,
		struct ast_rtp_instance *	instance,
		unsigned int	using_avpf,
		unsigned int	force_avp
	)

Get the RTP profile in use by a media session.

Parameters

sdes_active	Whether the media session is using SDES-SRTP
instance	The RTP instance associated with this media session
using_avpf	Whether the media session is using early feedback (AVPF)
force_avp	Force SAVP or SAVPF profile when DTLS is in use

Return values

A	non-allocated string describing the profile in use (does not need to be freed)

Definition at line 103 of file sdp_srtp.c.

References ast_rtp_engine_dtls::active, and ast_rtp_instance_get_dtls().

Referenced by add_sdp(), and create_outgoing_sdp_stream().

{
   struct ast_rtp_engine_dtls *dtls;

   if ((dtls = ast_rtp_instance_get_dtls(instance)) && dtls->active(instance)) {
      if (force_avp) {
         return using_avpf ? "RTP/SAVPF" : "RTP/SAVP";
      } else {
         return using_avpf ? "UDP/TLS/RTP/SAVPF" : "UDP/TLS/RTP/SAVP";
      }
   } else {
      if (using_avpf) {
         return sdes_active ? "RTP/SAVPF" : "RTP/AVPF";
      } else {
         return sdes_active ? "RTP/SAVP" : "RTP/AVP";
      }
   }
}

ast_sdp_srtp_alloc()

struct ast_sdp_srtp* ast_sdp_srtp_alloc

(

void

)

allocate a ast_sdp_srtp structure

Return values

a	new malloc'd ast_sdp_srtp structure on success
NULL	on failure

Definition at line 41 of file sdp_srtp.c.

References ast_calloc, ast_debug, ast_rtp_engine_srtp_is_registered(), and NULL.

Referenced by add_crypto_to_stream(), dialog_initialize_dtls_srtp(), process_crypto(), process_sdp(), res_sdp_srtp_get_attr(), setup_srtp(), and sip_call().

{
   if (!ast_rtp_engine_srtp_is_registered()) {
          ast_debug(1, "No SRTP module loaded, can't setup SRTP session.\n");
          return NULL;
   }

   return ast_calloc(1, sizeof(struct ast_sdp_srtp));
}

ast_sdp_srtp_destroy()

void ast_sdp_srtp_destroy

(

struct ast_sdp_srtp *

srtp

)

free a ast_sdp_srtp structure

Parameters

srtp	a ast_sdp_srtp structure

Definition at line 51 of file sdp_srtp.c.

References ast_free, AST_LIST_NEXT, ast_sdp_crypto_destroy(), ast_sdp_srtp::crypto, ast_sdp_srtp::next, NULL, and ast_sdp_srtp::sdp_srtp_list.

Referenced by dialog_clean_rtp(), process_sdp(), session_media_dtor(), and sip_pvt_dtor().

{
   struct ast_sdp_srtp *next;

   for (next = AST_LIST_NEXT(srtp, sdp_srtp_list);
        srtp;
        srtp = next, next = srtp ? AST_LIST_NEXT(srtp, sdp_srtp_list) : NULL) {
      ast_sdp_crypto_destroy(srtp->crypto);
      srtp->crypto = NULL;
      ast_free(srtp);
   }
}

ast_sdp_srtp_get_attrib()

const char* ast_sdp_srtp_get_attrib	(	struct ast_sdp_srtp *	srtp,
		int	dtls_enabled,
		int	default_taglen_32
	)

Get the crypto attribute line for the srtp structure.

The attribute line does not contain the initial "a=crypto:" and does not terminate with "\r\n".

Parameters

srtp	The ast_sdp_srtp structure for which to get an attribute line
dtls_enabled	Whether this connection is encrypted with datagram TLS
default_taglen_32	Whether to default to a tag length of 32 instead of 80

Return values

An	attribute line containing cryptographic information
NULL	if the srtp structure does not require an attribute line containing crypto information

Definition at line 95 of file sdp_srtp.c.

References ast_sdp_crypto_api::get_attr, and NULL.

Referenced by add_crypto_to_stream(), and crypto_get_attrib().

{
   if (!sdp_crypto_api) {
      return NULL;
   }
   return sdp_crypto_api->get_attr(srtp, dtls_enabled, default_taglen_32);
}