CLI: Create ast_cli_completion_vector.
[asterisk/asterisk.git] / include / asterisk / sdp_srtp.h
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 /*! \file sdp_srtp.h
20  *
21  * \brief SRTP and SDP Security descriptions
22  *
23  * Specified in RFC 3711, 6188, 7714, and 4568
24  *
25  * \author Mikael Magnusson <mikma@users.sourceforge.net>
26  */
27
28 #ifndef _SDP_SRTP_H
29 #define _SDP_SRTP_H
30
31 #include "asterisk/linkedlists.h"       /* for AST_LIST_ENTRY */
32 #include "asterisk/rtp_engine.h"        /* for ast_rtp_instance */
33
34 struct ast_sdp_crypto;
35
36 /*! \brief structure for secure RTP audio */
37 struct ast_sdp_srtp {
38         unsigned int flags;
39         struct ast_sdp_crypto *crypto;
40         AST_LIST_ENTRY(ast_sdp_srtp) sdp_srtp_list;
41 };
42
43 /* SRTP flags */
44 #define AST_SRTP_CRYPTO_OFFER_OK (1 << 1)
45 #define AST_SRTP_CRYPTO_TAG_32   (1 << 2)
46 #define AST_SRTP_CRYPTO_TAG_80   (1 << 3)
47 #define AST_SRTP_CRYPTO_TAG_16   (1 << 4)
48 #define AST_SRTP_CRYPTO_TAG_8    (1 << 5)
49 #define AST_SRTP_CRYPTO_AES_192  (1 << 6)
50 #define AST_SRTP_CRYPTO_AES_256  (1 << 7)
51 #define AST_SRTP_CRYPTO_OLD_NAME (1 << 8)
52
53 /*!
54  * \brief allocate a ast_sdp_srtp structure
55  * \retval a new malloc'd ast_sdp_srtp structure on success
56  * \retval NULL on failure
57 */
58 struct ast_sdp_srtp *ast_sdp_srtp_alloc(void);
59
60 /*!
61  * \brief free a ast_sdp_srtp structure
62  * \param srtp a ast_sdp_srtp structure
63 */
64 void ast_sdp_srtp_destroy(struct ast_sdp_srtp *srtp);
65
66 /*! \brief Destroy a previously allocated ast_sdp_crypto struct */
67 typedef void (*sdp_crypto_destroy_cb)(struct ast_sdp_crypto *crypto);
68
69 /*!
70  * \brief Initialize and return an ast_sdp_crypto struct
71  *
72  * \details
73  * This function allocates a new ast_sdp_crypto struct and initializes its values
74  *
75  * \retval NULL on failure
76  * \retval a pointer to a  new ast_sdp_crypto structure
77  */
78 typedef struct ast_sdp_crypto *(*sdp_crypto_alloc_cb)(void);
79
80 /*!
81  * \brief Generate an SRTP a=crypto offer
82  *
83  * \details
84  * The offer is stored on the ast_sdp_crypto struct in a_crypto
85  *
86  * \param crypto A valid ast_sdp_crypto struct
87  * \param taglen Length
88  *
89  * \retval 0 success
90  * \retval nonzero failure
91  */
92 typedef int (*sdp_crypto_build_offer_cb)(struct ast_sdp_crypto *crypto, int taglen);
93
94 /*!
95  * \brief Parse the a=crypto line from SDP and set appropriate values on the
96  * ast_sdp_crypto struct.
97  *
98  * The attribute line should already have "a=crypto:" removed.
99  *
100  * \param p A valid ast_sdp_crypto struct
101  * \param attr the a:crypto line from SDP
102  * \param rtp The rtp instance associated with the SDP being parsed
103  * \param srtp SRTP structure
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  * \retval 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
126 struct ast_sdp_crypto_api {
127         /*! Destroy a crypto struct */
128         sdp_crypto_destroy_cb dtor;
129         /*! Allocate a crypto struct */
130         sdp_crypto_alloc_cb alloc;
131         /*! Build a SDP a=crypto offer line parameter string */
132         sdp_crypto_build_offer_cb build_offer;
133         /*! Parse a SDP a=crypto offer line parameter string */
134         sdp_crypto_parse_offer_cb parse_offer;
135         /*! Get the SDP a=crypto offer line parameter string */
136         sdp_srtp_get_attr_cb get_attr;
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  */
148 int ast_sdp_crypto_register(struct ast_sdp_crypto_api *api);
149
150 /*!
151  * \brief Unregister SDP SRTP crypto processing routines.
152  * \since 14.0.0
153  *
154  * \param api Callbacks to unregister.
155  *
156  * \return Nothing
157  */
158 void ast_sdp_crypto_unregister(struct ast_sdp_crypto_api *api);
159
160 /*! \brief Initialize an return an ast_sdp_crypto struct
161  *
162  * \details
163  * This function allocates a new ast_sdp_crypto struct and initializes its values
164  *
165  * \retval NULL on failure
166  * \retval a pointer to a  new ast_sdp_crypto structure
167  */
168 struct ast_sdp_crypto *ast_sdp_crypto_alloc(void);
169
170 /*! \brief Destroy a previously allocated ast_sdp_crypto struct */
171 void ast_sdp_crypto_destroy(struct ast_sdp_crypto *crypto);
172
173 /*! \brief Parse the a=crypto line from SDP and set appropriate values on the
174  * ast_sdp_crypto struct.
175  *
176  * The attribute line should already have "a=crypto:" removed.
177  *
178  * \param p A valid ast_sdp_crypto struct
179  * \param attr the a:crypto line from SDP
180  * \param rtp The rtp instance associated with the SDP being parsed
181  * \param srtp SRTP structure
182  *
183  * \retval 0 success
184  * \retval nonzero failure
185  */
186 int ast_sdp_crypto_process(struct ast_rtp_instance *rtp, struct ast_sdp_srtp *srtp, const char *attr);
187
188 /*! \brief Generate an SRTP a=crypto offer
189  *
190  * \details
191  * The offer is stored on the ast_sdp_crypto struct in a_crypto
192  *
193  * \param p A valid ast_sdp_crypto struct
194  * \param taglen Length
195  *
196  * \retval 0 success
197  * \retval nonzero failure
198  */
199 int ast_sdp_crypto_build_offer(struct ast_sdp_crypto *p, int taglen);
200
201 /*! \brief Get the crypto attribute line for the srtp structure
202  *
203  * The attribute line does not contain the initial "a=crypto:" and does
204  * not terminate with "\r\n".
205  *
206  * \param srtp The ast_sdp_srtp structure for which to get an attribute line
207  * \param dtls_enabled Whether this connection is encrypted with datagram TLS
208  * \param default_taglen_32 Whether to default to a tag length of 32 instead of 80
209  *
210  * \retval An attribute line containing cryptographic information
211  * \retval NULL if the srtp structure does not require an attribute line containing crypto information
212  */
213 const char *ast_sdp_srtp_get_attrib(struct ast_sdp_srtp *srtp, int dtls_enabled, int default_taglen_32);
214
215 /*! \brief Get the RTP profile in use by a media session
216  *
217  * \param sdes_active Whether the media session is using SDES-SRTP
218  * \param instance The RTP instance associated with this media session
219  * \param using_avpf Whether the media session is using early feedback (AVPF)
220  * \param force_avp Force SAVP or SAVPF profile when DTLS is in use
221  *
222  * \retval A non-allocated string describing the profile in use (does not need to be freed)
223  */
224 char *ast_sdp_get_rtp_profile(unsigned int sdes_active, struct ast_rtp_instance *instance, unsigned int using_avpf,
225         unsigned int force_avp);
226 #endif  /* _SDP_CRYPTO_H */