Asterisk - The Open Source Telephony Project  21.4.1
sdp_srtp.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2006 - 2007, Mikael Magnusson
5  *
6  * Mikael Magnusson <mikma@users.sourceforge.net>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*!
20  * \file
21  *
22  * \brief SRTP and SDP Security descriptions
23  *
24  * Specified in RFC 3711, 6188, 7714, and 4568
25  *
26  * \author Mikael Magnusson <mikma@users.sourceforge.net>
27  */
28 
29 #ifndef _SDP_SRTP_H
30 #define _SDP_SRTP_H
31 
32 #include "asterisk/linkedlists.h" /* for AST_LIST_ENTRY */
33 #include "asterisk/rtp_engine.h" /* for ast_rtp_instance */
34 
35 struct ast_sdp_crypto;
36 
37 /*! \brief structure for secure RTP audio */
38 struct ast_sdp_srtp {
39  unsigned int flags;
40  struct ast_sdp_crypto *crypto;
41  AST_LIST_ENTRY(ast_sdp_srtp) sdp_srtp_list;
42 };
43 
44 /* SRTP flags */
45 #define AST_SRTP_CRYPTO_OFFER_OK (1 << 1)
46 #define AST_SRTP_CRYPTO_TAG_32 (1 << 2)
47 #define AST_SRTP_CRYPTO_TAG_80 (1 << 3)
48 #define AST_SRTP_CRYPTO_TAG_16 (1 << 4)
49 #define AST_SRTP_CRYPTO_TAG_8 (1 << 5)
50 #define AST_SRTP_CRYPTO_AES_192 (1 << 6)
51 #define AST_SRTP_CRYPTO_AES_256 (1 << 7)
52 #define AST_SRTP_CRYPTO_OLD_NAME (1 << 8)
53 
54 /*!
55  * \brief allocate a ast_sdp_srtp structure
56  * \return a new malloc'd ast_sdp_srtp structure on success
57  * \retval NULL on failure
58 */
59 struct ast_sdp_srtp *ast_sdp_srtp_alloc(void);
60 
61 /*!
62  * \brief free a ast_sdp_srtp structure
63  * \param srtp a ast_sdp_srtp structure
64 */
65 void ast_sdp_srtp_destroy(struct ast_sdp_srtp *srtp);
66 
67 /*! \brief Destroy a previously allocated ast_sdp_crypto struct */
68 typedef void (*sdp_crypto_destroy_cb)(struct ast_sdp_crypto *crypto);
69 
70 /*!
71  * \brief Initialize and return an ast_sdp_crypto struct
72  *
73  * \details
74  * This function allocates a new ast_sdp_crypto struct and initializes its values
75  *
76  * \retval NULL on failure
77  * \return a pointer to a new ast_sdp_crypto structure
78  */
79 typedef struct ast_sdp_crypto *(*sdp_crypto_alloc_cb)(void);
80 
81 /*!
82  * \brief Generate an SRTP a=crypto offer
83  *
84  * \details
85  * The offer is stored on the ast_sdp_crypto struct in a_crypto
86  *
87  * \param crypto A valid ast_sdp_crypto struct
88  * \param taglen Length
89  *
90  * \retval 0 success
91  * \retval nonzero failure
92  */
93 typedef int (*sdp_crypto_build_offer_cb)(struct ast_sdp_crypto *crypto, int taglen);
94 
95 /*!
96  * \brief Parse the a=crypto line from SDP and set appropriate values on the
97  * ast_sdp_crypto struct.
98  *
99  * The attribute line should already have "a=crypto:" removed.
100  *
101  * \param rtp The rtp instance associated with the SDP being parsed
102  * \param srtp SRTP structure
103  * \param attr the a:crypto line from SDP
104  *
105  * \retval 0 success
106  * \retval nonzero failure
107  */
108 typedef int (*sdp_crypto_parse_offer_cb)(struct ast_rtp_instance *rtp, struct ast_sdp_srtp *srtp, const char *attr);
109 
110 /*!
111  * \brief Get the crypto attribute line for the srtp structure
112  *
113  * \details
114  * The attribute line does not contain the initial "a=crypto:" and does
115  * not terminate with "\r\n".
116  *
117  * \param srtp The ast_sdp_srtp structure for which to get an attribute line
118  * \param dtls_enabled Whether this connection is encrypted with datagram TLS
119  * \param default_taglen_32 Whether to default to a tag length of 32 instead of 80
120  *
121  * \return An attribute line containing cryptographic information
122  * \retval NULL if the srtp structure does not require an attribute line containing crypto information
123  */
124 typedef const char *(*sdp_srtp_get_attr_cb)(struct ast_sdp_srtp *srtp, int dtls_enabled, int default_taglen_32);
125 
127  /*! Destroy a crypto struct */
129  /*! Allocate a crypto struct */
131  /*! Build a SDP a=crypto offer line parameter string */
133  /*! Parse a SDP a=crypto offer line parameter string */
135  /*! Get the SDP a=crypto offer line parameter string */
137 };
138 
139 /*!
140  * \brief Register SDP SRTP crypto processing routines.
141  * \since 14.0.0
142  *
143  * \param api Callbacks to register.
144  *
145  * \retval 0 on success.
146  * \retval -1 on error.
147  */
149 
150 /*!
151  * \brief Unregister SDP SRTP crypto processing routines.
152  * \since 14.0.0
153  *
154  * \param api Callbacks to unregister.
155  */
157 
158 /*! \brief Initialize an return an ast_sdp_crypto struct
159  *
160  * \details
161  * This function allocates a new ast_sdp_crypto struct and initializes its values
162  *
163  * \retval NULL on failure
164  * \return a pointer to a new ast_sdp_crypto structure
165  */
167 
168 /*! \brief Destroy a previously allocated ast_sdp_crypto struct */
169 void ast_sdp_crypto_destroy(struct ast_sdp_crypto *crypto);
170 
171 /*! \brief Parse the a=crypto line from SDP and set appropriate values on the
172  * ast_sdp_crypto struct.
173  *
174  * The attribute line should already have "a=crypto:" removed.
175  *
176  * \param rtp The rtp instance associated with the SDP being parsed
177  * \param srtp SRTP structure
178  * \param attr the a:crypto line from SDP
179  *
180  * \retval 0 success
181  * \retval nonzero failure
182  */
183 int ast_sdp_crypto_process(struct ast_rtp_instance *rtp, struct ast_sdp_srtp *srtp, const char *attr);
184 
185 /*! \brief Generate an SRTP a=crypto offer
186  *
187  * \details
188  * The offer is stored on the ast_sdp_crypto struct in a_crypto
189  *
190  * \param p A valid ast_sdp_crypto struct
191  * \param taglen Length
192  *
193  * \retval 0 success
194  * \retval nonzero failure
195  */
196 int ast_sdp_crypto_build_offer(struct ast_sdp_crypto *p, int taglen);
197 
198 /*! \brief Get the crypto attribute line for the srtp structure
199  *
200  * The attribute line does not contain the initial "a=crypto:" and does
201  * not terminate with "\r\n".
202  *
203  * \param srtp The ast_sdp_srtp structure for which to get an attribute line
204  * \param dtls_enabled Whether this connection is encrypted with datagram TLS
205  * \param default_taglen_32 Whether to default to a tag length of 32 instead of 80
206  *
207  * \return An attribute line containing cryptographic information
208  * \retval NULL if the srtp structure does not require an attribute line containing crypto information
209  */
210 const char *ast_sdp_srtp_get_attrib(struct ast_sdp_srtp *srtp, int dtls_enabled, int default_taglen_32);
211 
212 /*! \brief Get the RTP profile in use by a media session
213  *
214  * \param sdes_active Whether the media session is using SDES-SRTP
215  * \param instance The RTP instance associated with this media session
216  * \param using_avpf Whether the media session is using early feedback (AVPF)
217  * \param force_avp Force SAVP or SAVPF profile when DTLS is in use
218  *
219  * \return A non-allocated string describing the profile in use (does not need to be freed)
220  */
221 char *ast_sdp_get_rtp_profile(unsigned int sdes_active, struct ast_rtp_instance *instance, unsigned int using_avpf,
222  unsigned int force_avp);
223 #endif /* _SDP_CRYPTO_H */
structure for secure RTP audio
Definition: sdp_srtp.h:38
void ast_sdp_crypto_destroy(struct ast_sdp_crypto *crypto)
Destroy a previously allocated ast_sdp_crypto struct.
Definition: sdp_srtp.c:64
sdp_crypto_parse_offer_cb parse_offer
Definition: sdp_srtp.h:134
struct ast_sdp_crypto *(* sdp_crypto_alloc_cb)(void)
Initialize and return an ast_sdp_crypto struct.
Definition: sdp_srtp.h:79
int(* sdp_crypto_build_offer_cb)(struct ast_sdp_crypto *crypto, int taglen)
Generate an SRTP a=crypto offer.
Definition: sdp_srtp.h:93
sdp_crypto_build_offer_cb build_offer
Definition: sdp_srtp.h:132
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...
Definition: sdp_srtp.h:108
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...
Definition: sdp_srtp.c:79
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.
Definition: sdp_srtp.c:103
sdp_crypto_alloc_cb alloc
Definition: sdp_srtp.h:130
void(* sdp_crypto_destroy_cb)(struct ast_sdp_crypto *crypto)
Destroy a previously allocated ast_sdp_crypto struct.
Definition: sdp_srtp.h:68
sdp_crypto_destroy_cb dtor
Definition: sdp_srtp.h:128
A set of macros to manage forward-linked lists.
int ast_sdp_crypto_build_offer(struct ast_sdp_crypto *p, int taglen)
Generate an SRTP a=crypto offer.
Definition: sdp_srtp.c:87
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
struct ast_sdp_srtp * ast_sdp_srtp_alloc(void)
allocate a ast_sdp_srtp structure
Definition: sdp_srtp.c:41
struct ast_sdp_crypto * ast_sdp_crypto_alloc(void)
Initialize an return an ast_sdp_crypto struct.
Definition: sdp_srtp.c:71
void ast_sdp_srtp_destroy(struct ast_sdp_srtp *srtp)
free a ast_sdp_srtp structure
Definition: sdp_srtp.c:51
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.
Definition: sdp_srtp.h:124
void ast_sdp_crypto_unregister(struct ast_sdp_crypto_api *api)
Unregister SDP SRTP crypto processing routines.
Definition: sdp_srtp.c:132
int ast_sdp_crypto_register(struct ast_sdp_crypto_api *api)
Register SDP SRTP crypto processing routines.
Definition: sdp_srtp.c:123
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.
Definition: sdp_srtp.c:95
Pluggable RTP Architecture.
sdp_srtp_get_attr_cb get_attr
Definition: sdp_srtp.h:136