diff options
author | Benny Prijono <bennylp@teluu.com> | 2008-01-23 20:39:07 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2008-01-23 20:39:07 +0000 |
commit | 8686b3135348bcd69bdb3c3cb6660a82d989bb30 (patch) | |
tree | 31d9c111724f083782ba5782c58ab2d30a867933 /pjmedia/include | |
parent | 5035ea445fbf6de061efacd90c66390ca15806ed (diff) |
Ticket #61: Implement SRTP support in PJMEDIA and PJSUA-LIB, and updated applications because of the changes. This is a major modification back ported from SRTP branch. See ticket #61 for changelog detail of this commit
git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@1735 74dad513-b988-da41-8d7b-12977e46ad98
Diffstat (limited to 'pjmedia/include')
-rw-r--r-- | pjmedia/include/pjmedia.h | 1 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/config.h | 8 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/errno.h | 81 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/transport.h | 125 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/transport_ice.h | 80 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/transport_srtp.h | 200 | ||||
-rw-r--r-- | pjmedia/include/pjmedia/transport_udp.h | 55 |
7 files changed, 415 insertions, 135 deletions
diff --git a/pjmedia/include/pjmedia.h b/pjmedia/include/pjmedia.h index 4a104512..bf580675 100644 --- a/pjmedia/include/pjmedia.h +++ b/pjmedia/include/pjmedia.h @@ -54,6 +54,7 @@ #include <pjmedia/tonegen.h> #include <pjmedia/transport.h> #include <pjmedia/transport_ice.h> +#include <pjmedia/transport_srtp.h> #include <pjmedia/transport_udp.h> #include <pjmedia/wav_playlist.h> #include <pjmedia/wav_port.h> diff --git a/pjmedia/include/pjmedia/config.h b/pjmedia/include/pjmedia/config.h index 4c7b26be..ecfd371a 100644 --- a/pjmedia/include/pjmedia/config.h +++ b/pjmedia/include/pjmedia/config.h @@ -484,6 +484,14 @@ #endif +/** + * SRTP Transport + * By default it is enabled. + */ +#ifndef PJMEDIA_HAS_SRTP +# define PJMEDIA_HAS_SRTP 1 +#endif + /** * @} diff --git a/pjmedia/include/pjmedia/errno.h b/pjmedia/include/pjmedia/errno.h index f14e3599..6be64979 100644 --- a/pjmedia/include/pjmedia/errno.h +++ b/pjmedia/include/pjmedia/errno.h @@ -42,18 +42,35 @@ PJ_BEGIN_DECL * Start of error code relative to PJ_ERRNO_START_USER. */ #define PJMEDIA_ERRNO_START (PJ_ERRNO_START_USER + PJ_ERRNO_SPACE_SIZE) +#define PJMEDIA_ERRNO_END (PJMEDIA_ERRNO_START + PJ_ERRNO_SPACE_SIZE - 1) /** * Mapping from PortAudio error codes to pjmedia error space. */ -#define PJMEDIA_PORTAUDIO_ERRNO_START (PJMEDIA_ERRNO_START+PJ_ERRNO_SPACE_SIZE-1000) - +#define PJMEDIA_PORTAUDIO_ERRNO_START (PJMEDIA_ERRNO_END-10000) +#define PJMEDIA_PORTAUDIO_ERRNO_END (PJMEDIA_PORTAUDIO_ERRNO_START + 10000 -1) /** * Convert PortAudio error code to PJMEDIA error code. + * PortAudio error code range: 0 >= err >= -10000 */ -#define PJMEDIA_ERRNO_FROM_PORTAUDIO(err) (err+PJMEDIA_PORTAUDIO_ERRNO_START) +#define PJMEDIA_ERRNO_FROM_PORTAUDIO(err) ((int)PJMEDIA_PORTAUDIO_ERRNO_START-err) + + +#if defined(PJMEDIA_HAS_SRTP) && (PJMEDIA_HAS_SRTP != 0) + /** + * Mapping from LibSRTP error codes to pjmedia error space. + */ +#define PJMEDIA_LIBSRTP_ERRNO_START (PJMEDIA_ERRNO_END-10200) +#define PJMEDIA_LIBSRTP_ERRNO_END (PJMEDIA_LIBSRTP_ERRNO_START + 200 - 1) +/** + * Convert LibSRTP error code to PJMEDIA error code. + * LibSRTP error code range: 0 <= err < 200 + */ +#define PJMEDIA_ERRNO_FROM_LIBSRTP(err) (PJMEDIA_LIBSRTP_ERRNO_START+err) + +#endif /************************************************************ * GENERIC/GENERAL PJMEDIA ERRORS @@ -526,6 +543,64 @@ PJ_BEGIN_DECL #define PJMEDIA_ESNDINSAMPLEFMT (PJMEDIA_ERRNO_START+203) /* 220203 */ +#if defined(PJMEDIA_HAS_SRTP) && (PJMEDIA_HAS_SRTP != 0) +/************************************************************ + * SRTP TRANSPORT ERRORS + ***********************************************************/ +/** + * @hideinitializer + * SRTP crypto-suite name not match the offerer tag. + */ +#define PJMEDIA_SRTP_ECRYPTONOTMATCH (PJMEDIA_ERRNO_START+220) /* 220220 */ +/** + * @hideinitializer + * Invalid SRTP key length for specific crypto. + */ +#define PJMEDIA_SRTP_EINKEYLEN (PJMEDIA_ERRNO_START+221) /* 220221 */ +/** + * @hideinitializer + * Unsupported SRTP crypto-suite. + */ +#define PJMEDIA_SRTP_ENOTSUPCRYPTO (PJMEDIA_ERRNO_START+222) /* 220222 */ +/** + * @hideinitializer + * SRTP SDP contains ambigue answer. + */ +#define PJMEDIA_SRTP_ESDPAMBIGUEANS (PJMEDIA_ERRNO_START+223) /* 220223 */ +/** + * @hideinitializer + * Duplicated crypto tag. + */ +#define PJMEDIA_SRTP_ESDPDUPCRYPTOTAG (PJMEDIA_ERRNO_START+224) /* 220224 */ +/** + * @hideinitializer + * Invalid crypto attribute. + */ +#define PJMEDIA_SRTP_ESDPINCRYPTO (PJMEDIA_ERRNO_START+225) /* 220225 */ +/** + * @hideinitializer + * Invalid crypto tag. + */ +#define PJMEDIA_SRTP_ESDPINCRYPTOTAG (PJMEDIA_ERRNO_START+226) /* 220226 */ +/** + * @hideinitializer + * Invalid SDP media transport for SRTP. + */ +#define PJMEDIA_SRTP_ESDPINTRANSPORT (PJMEDIA_ERRNO_START+227) /* 220227 */ +/** + * @hideinitializer + * SRTP crypto attribute required in SDP. + */ +#define PJMEDIA_SRTP_ESDPREQCRYPTO (PJMEDIA_ERRNO_START+228) /* 220228 */ +/** + * @hideinitializer + * Secure transport required in SDP media descriptor. + */ +#define PJMEDIA_SRTP_ESDPREQSECTP (PJMEDIA_ERRNO_START+229) /* 220229 */ + +#endif /* PJMEDIA_HAS_SRTP */ + + /** * Get error message for the specified error code. Note that this * function is only able to decode PJMEDIA specific error code. diff --git a/pjmedia/include/pjmedia/transport.h b/pjmedia/include/pjmedia/transport.h index 1e7d67db..e9fbb1f3 100644 --- a/pjmedia/include/pjmedia/transport.h +++ b/pjmedia/include/pjmedia/transport.h @@ -166,6 +166,7 @@ PJ_BEGIN_DECL +#include <pjmedia/sdp.h> /* * Forward declaration for media transport. @@ -244,6 +245,50 @@ struct pjmedia_transport_op pj_size_t size); /** + * This function is called by application to generate the SDP parts + * related to transport type, e.g: ICE, SRTP. + * + * Application should call #pjmedia_transport_media_create() instead of + * calling this function directly. + */ + pj_status_t (*media_create)(pjmedia_transport *tp, + pj_pool_t *pool, + pjmedia_sdp_session *sdp_local, + const pjmedia_sdp_session *sdp_remote, + unsigned media_index); + + /** + * This function is called by application to start the transport + * based on SDP negotiation result. + * + * Application should call #pjmedia_transport_media_start() instead of + * calling this function directly. + */ + pj_status_t (*media_start) (pjmedia_transport *tp, + pj_pool_t *pool, + pjmedia_sdp_session *sdp_local, + const pjmedia_sdp_session *sdp_remote, + unsigned media_index); + + /** + * This function is called by application to stop the transport. + * + * Application should call #pjmedia_transport_media_stop() instead of + * calling this function directly. + */ + pj_status_t (*media_stop) (pjmedia_transport *tp); + + /** + * This function can be called to simulate packet lost. + * + * Application should call #pjmedia_transport_simulate_lost() instead of + * calling this function directly. + */ + pj_status_t (*simulate_lost)(pjmedia_transport *tp, + pjmedia_dir dir, + unsigned pct_lost); + + /** * This function can be called to destroy this transport. * * Application should call #pjmedia_transport_close() instead of @@ -410,6 +455,67 @@ PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp(pjmedia_transport *tp, /** + * Generate local SDP parts that are related to the specified media transport. + * Remote SDP might be needed as reference when application is in deciding + * side of negotiation (callee side), otherwise it should be NULL. + * This is just a simple wrapper which calls <tt>media_create()</tt> member + * of the transport. + * + * @param tp The media transport. + * @param pool The memory pool. + * @param sdp_local Local SDP. + * @param sdp_remote Remote SDP. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_INLINE(pj_status_t) pjmedia_transport_media_create(pjmedia_transport *tp, + pj_pool_t *pool, + pjmedia_sdp_session *sdp_local, + const pjmedia_sdp_session *sdp_remote, + unsigned media_index) +{ + return (*tp->op->media_create)(tp, pool, sdp_local, sdp_remote, + media_index); +} + +/** + * Start the transport with regards to SDP negotiation result. + * This is just a simple wrapper which calls <tt>media_start()</tt> member + * of the transport. + * + * @param tp The media transport. + * @param pool The memory pool. + * @param sdp_local Local SDP. + * @param sdp_remote Remote SDP. + * @param media_index Media index to start. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_INLINE(pj_status_t) pjmedia_transport_media_start(pjmedia_transport *tp, + pj_pool_t *pool, + pjmedia_sdp_session *sdp_local, + const pjmedia_sdp_session *sdp_remote, + unsigned media_index) +{ + return (*tp->op->media_start)(tp, pool, sdp_local, sdp_remote, media_index); +} + + +/** + * Stop the transport. + * This is just a simple wrapper which calls <tt>media_stop()</tt> member + * of the transport. + * + * @param tp The media transport. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_INLINE(pj_status_t) pjmedia_transport_media_stop(pjmedia_transport *tp) +{ + return (*tp->op->media_stop)(tp); +} + +/** * Close media transport. This is just a simple wrapper which calls * <tt>destroy()</tt> member of the transport. This function will free * all resources created by this transport (such as sockets, memory, etc.). @@ -426,6 +532,25 @@ PJ_INLINE(pj_status_t) pjmedia_transport_close(pjmedia_transport *tp) return PJ_SUCCESS; } +/** + * Simulate packet lost in the specified direction (for testing purposes). + * When enabled, the transport will randomly drop packets to the specified + * direction. + * + * @param tp The media transport. + * @param dir Media direction to which packets will be randomly dropped. + * @param pct_lost Percent lost (0-100). Set to zero to disable packet + * lost simulation. + * + * @return PJ_SUCCESS on success. + */ +PJ_INLINE(pj_status_t) pjmedia_transport_simulate_lost(pjmedia_transport *tp, + pjmedia_dir dir, + unsigned pct_lost) +{ + return (*tp->op->simulate_lost)(tp, dir, pct_lost); +} + PJ_END_DECL diff --git a/pjmedia/include/pjmedia/transport_ice.h b/pjmedia/include/pjmedia/transport_ice.h index da1e0512..c64ac9bc 100644 --- a/pjmedia/include/pjmedia/transport_ice.h +++ b/pjmedia/include/pjmedia/transport_ice.h @@ -16,8 +16,8 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -#ifndef __pjmedia_ice_H__ -#define __pjmedia_ice_H__ +#ifndef __PJMEDIA_TRANSPORT_ICE_H__ +#define __PJMEDIA_TRANSPORT_ICE_H__ /** @@ -75,15 +75,6 @@ PJ_DECL(pj_status_t) pjmedia_ice_create(pjmedia_endpt *endpt, const pjmedia_ice_cb *cb, pjmedia_transport **p_tp); -/** - * Destroy the media transport. - * - * @param tp The media transport. - * - * @return PJ_SUCCESS. - */ -PJ_DECL(pj_status_t) pjmedia_ice_destroy(pjmedia_transport *tp); - /** * Start the initialization process of this media transport. This function @@ -169,71 +160,6 @@ PJ_DECL(pj_status_t) pjmedia_ice_init_ice(pjmedia_transport *tp, const pj_str_t *local_ufrag, const pj_str_t *local_passwd); -/** - * Modify the SDP to add ICE specific SDP attributes before sending - * the SDP to remote host. - * - * @param tp The media transport. - * @param pool Pool to allocate memory for the SDP elements. - * @param sdp The SDP descriptor to be modified. - * - * @return PJ_SUCCESS, or the appropriate error code. - */ -PJ_DECL(pj_status_t) pjmedia_ice_modify_sdp(pjmedia_transport *tp, - pj_pool_t *pool, - pjmedia_sdp_session *sdp); - -/** - * Start ICE connectivity checks. - * - * This function will pair the local and remote candidates to create - * check list. Once the check list is created and sorted based on the - * priority, ICE periodic checks will be started. This function will - * return immediately, and application will be notified about the - * connectivity check status in the callback. - * - * @param tp The media transport. - * @param pool Memory pool to parse the SDP. - * @param rem_sdp The SDP received from remote agent. - * @param media_index The media index (in SDP) to process. - * - * @return PJ_SUCCESS, or the appropriate error code. - */ -PJ_DECL(pj_status_t) pjmedia_ice_start_ice(pjmedia_transport *tp, - pj_pool_t *pool, - const pjmedia_sdp_session *rem_sdp, - unsigned media_index); - -/** - * Stop the ICE session (typically when the call is terminated). Application - * may restart the ICE session again by calling #pjmedia_ice_init_ice(), - * for example to use this media transport for the next call. - * - * @param tp The media transport. - * - * @return PJ_SUCCESS, or the appropriate error code. - */ -PJ_DECL(pj_status_t) pjmedia_ice_stop_ice(pjmedia_transport *tp); - - -/** - * Simulate packet lost in the specified direction (for testing purposes). - * When enabled, the transport will randomly drop packets to the specified - * direction. - * - * @param tp The ICE media transport. - * @param dir Media direction to which packets will be randomly dropped. - * @param pct_lost Percent lost (0-100). Set to zero to disable packet - * lost simulation. - * - * @return PJ_SUCCESS on success. - */ -PJ_DECL(pj_status_t) pjmedia_ice_simulate_lost(pjmedia_transport *tp, - pjmedia_dir dir, - unsigned pct_lost); - - - PJ_END_DECL @@ -243,6 +169,6 @@ PJ_END_DECL */ -#endif /* __pjmedia_ice_H__ */ +#endif /* __PJMEDIA_TRANSPORT_ICE_H__ */ diff --git a/pjmedia/include/pjmedia/transport_srtp.h b/pjmedia/include/pjmedia/transport_srtp.h new file mode 100644 index 00000000..f7ea291d --- /dev/null +++ b/pjmedia/include/pjmedia/transport_srtp.h @@ -0,0 +1,200 @@ +/* $Id$ */ +/* + * Copyright (C) 2003-2007 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJMEDIA_TRANSPORT_SRTP_H__ +#define __PJMEDIA_TRANSPORT_SRTP_H__ + +/** + * @file srtp.h + * @brief transport SRTP encapsulates secure media transport. + */ + +#include <pjmedia/transport.h> + + +PJ_BEGIN_DECL + + +/** + * Crypto option. + */ +typedef enum pjmedia_srtp_crypto_option +{ + /** When this flag is specified, encryption will be disabled. */ + PJMEDIA_SRTP_NO_ENCRYPTION = 1, + + /** When this flag is specified, authentication will be disabled. */ + PJMEDIA_SRTP_NO_AUTHENTICATION = 2 + +} pjmedia_srtp_crypto_option; + + +/** + * This structure describes an individual crypto setting. + */ +typedef struct pjmedia_srtp_crypto +{ + /** Optional key. If empty, a random key will be autogenerated. */ + pj_str_t key; + + /** Crypto name. */ + pj_str_t name; + + /* Flags, bitmask from #pjmedia_srtp_crypto_option */ + unsigned flags; + +} pjmedia_srtp_crypto; + + +/** + * This enumeration specifies the behavior of the SRTP transport regarding + * media security offer and answer. + */ +typedef enum pjmedia_srtp_use +{ + /** + * When this flag is specified, SRTP will be disabled, and the transport + * will reject RTP/SAVP offer. + */ + PJMEDIA_SRTP_DISABLED, + + /** + * When this flag is specified, SRTP will be advertised as optional and + * incoming SRTP offer will be accepted. + */ + PJMEDIA_SRTP_OPTIONAL, + + /** + * When this flag is specified, the transport will require that RTP/SAVP + * media shall be used. + */ + PJMEDIA_SRTP_MANDATORY + +} pjmedia_srtp_use; + + +/** + * Settings to be given when creating SRTP transport. Application should call + * #pjmedia_srtp_setting_default() to initialize this structure with its + * default values. + */ +typedef struct pjmedia_srtp_setting +{ + /** + * Specify the usage policy. Default is PJMEDIA_SRTP_OPTIONAL. + */ + pjmedia_srtp_use use; + + /** + * Specify whether the SRTP transport should close the member transport + * when it is destroyed. Default: PJ_TRUE. + */ + pj_bool_t close_member_tp; + + /** + * Specify the number of crypto suite settings. + */ + unsigned crypto_count; + + /** + * Specify individual crypto suite setting. + */ + pjmedia_srtp_crypto crypto[8]; + +} pjmedia_srtp_setting; + + +/** + * Initialize SRTP setting with its default values. + * + * @param opt SRTP setting to be initialized. + */ +PJ_DECL(void) pjmedia_srtp_setting_default(pjmedia_srtp_setting *opt); + + +/** + * Create an SRTP media transport. + * + * @param endpt The media endpoint instance. + * @param tp The actual media transport to send and receive + * RTP/RTCP packets. This media transport will be + * kept as member transport of this SRTP instance. + * @param opt Optional settings. If NULL is given, default + * settings will be used. + * @param p_tp Pointer to receive the transport SRTP instance. + * + * @return PJ_SUCCESS on success. + */ +PJ_DECL(pj_status_t) pjmedia_transport_srtp_create( + pjmedia_endpt *endpt, + pjmedia_transport *tp, + const pjmedia_srtp_setting *opt, + pjmedia_transport **p_tp); + + +/** + * Manually start SRTP session with the given parameters. Application only + * needs to call this function when the SRTP transport is used without SDP + * offer/answer. When SDP offer/answer framework is used, the SRTP transport + * will be started/stopped by #pjmedia_transport_media_start() and + * #pjmedia_transport_media_stop() respectively. + * + * Please note that even if an RTP stream is only one direction, application + * will still need to provide both crypto suites, because it is needed by + * RTCP. + + * If application specifies the crypto keys, the keys for transmit and receive + * direction MUST be different. + * + * @param srtp The SRTP transport. + * @param tx Crypto suite setting for transmit direction. + * @param rx Crypto suite setting for receive direction. + * + * @return PJ_SUCCESS on success. + */ +PJ_DECL(pj_status_t) pjmedia_transport_srtp_start( + pjmedia_transport *tp, + const pjmedia_srtp_crypto *tx, + const pjmedia_srtp_crypto *rx); + +/** + * Stop SRTP session. + * + * @param srtp The SRTP media transport. + * + * @return PJ_SUCCESS on success. + * + * @see #pjmedia_transport_srtp_start() + */ +PJ_DECL(pj_status_t) pjmedia_transport_srtp_stop(pjmedia_transport *tp); + + +/** + * Query member transport of SRTP. + * + * @param srtp The SRTP media transport. + * + * @return member media transport. + */ +PJ_DECL(pjmedia_transport*) pjmedia_transport_srtp_get_member( + pjmedia_transport *tp); + + +PJ_END_DECL + +#endif /* __PJMEDIA_TRANSPORT_SRTP_H__ */ diff --git a/pjmedia/include/pjmedia/transport_udp.h b/pjmedia/include/pjmedia/transport_udp.h index 12f819d1..5bf5b19d 100644 --- a/pjmedia/include/pjmedia/transport_udp.h +++ b/pjmedia/include/pjmedia/transport_udp.h @@ -56,19 +56,6 @@ enum pjmedia_transport_udp_options /** - * UDP transport info. - */ -typedef struct pjmedia_transport_udp_info -{ - /** - * Media socket info. - */ - pjmedia_sock_info skinfo; - -} pjmedia_transport_udp_info; - - -/** * Create an RTP and RTCP sockets and bind the sockets to the specified * port to create media transport. * @@ -137,18 +124,6 @@ PJ_DECL(pj_status_t) pjmedia_transport_udp_create3(pjmedia_endpt *endpt, unsigned options, pjmedia_transport **p_tp); -/** - * Get media socket info from the specified UDP transport. - * - * @param tp The UDP transport interface. - * @param info Media socket info to be initialized. - * - * @return PJ_SUCCESS on success. - */ -PJ_DECL(pj_status_t) -pjmedia_transport_udp_get_info( pjmedia_transport *tp, - pjmedia_transport_udp_info *info); - /** * Create UDP stream transport from existing sockets. Use this function when @@ -169,36 +144,6 @@ PJ_DECL(pj_status_t) pjmedia_transport_udp_attach(pjmedia_endpt *endpt, pjmedia_transport **p_tp); -/** - * Simulate packet lost in the specified direction (for testing purposes). - * When enabled, the transport will randomly drop packets to the specified - * direction. - * - * @param tp The UDP media transport. - * @param dir Media direction to which packets will be randomly dropped. - * @param pct_lost Percent lost (0-100). Set to zero to disable packet - * lost simulation. - * - * @return PJ_SUCCESS on success. - */ -PJ_DECL(pj_status_t) pjmedia_transport_udp_simulate_lost(pjmedia_transport *tp, - pjmedia_dir dir, - unsigned pct_lost); - - - -/** - * Close UDP transport. Application can also use the "destroy" member of - * media transport interface to close the UDP transport. - * - * @param tp The UDP media transport. - * - * @return PJ_SUCCESS on success. - */ -PJ_DECL(pj_status_t) pjmedia_transport_udp_close(pjmedia_transport *tp); - - - PJ_END_DECL |