Changes between Version 7 and Version 8 of SRTP


Ignore:
Timestamp:
Jan 25, 2008 9:39:25 AM (15 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • SRTP

    v7 v8  
    11= SRTP Support in PJSIP = 
    22 
    3 This article describes about SRTP support in PJSIP , which was included in version 0.9 (see ticket #61). 
     3This article describes about SRTP support in PJSIP. SRTP support is included in version 0.9 (see ticket #61). 
    44 
    5 '''Table of Contents:''' 
     5'''Table of Contents''' 
    66[[PageOutline(2-3,,inline)]] 
     7 
     8---- 
     9 
     10== Features == 
     11 
     12The SRTP functionality in PJSIP has the following features: 
     13 - SRTP ([http://www.ietf.org/rfc/rfc3711.txt RFC 3711]), using the Open Source [http://sourceforge.net/projects/srtp/ libsrtp] library. 
     14 - Keys exchange using Security Descriptions for Media Streams (SDESC, [http://www.ietf.org/rfc/rfc4568.txt RFC 4568]) 
     15 - Supported cryptos: 
     16     - AES_CM_128_HMAC_SHA1_80 
     17     - AES_CM_128_HMAC_SHA1_32 
     18 - Secure RTCP (SRTCP) is supported. 
     19 
     20Negotiation of crypto session parameters in SDP is currently not supported. 
     21 
    722---- 
    823 
    924== Compatibility Info == 
    1025 
    11 Please note the following issues regarding compatibility with previous PJSIP code: 
     26Few notes regarding compatibility with previous PJSIP code. 
    1227 
    1328=== Build Systems === 
    … …  
    1732'''For GNU build systems:''' 
    1833  1. You will need to re-run {{{./configure}}}, {{{make dep}}} and {{{make}}} to update {{{build.mak}}} and rebuild the project dependencies. 
    19   1. If your Makefile includes {{{build.mak}}} (as explained in [wiki:Getting_Started_Using Getting Stared part 2], you just need to rebuild your application as the input libraries will be updated automatically. 
     34  1. If your Makefile includes {{{build.mak}}} (as explained in [wiki:Getting_Started_Using Getting Stared part 2]), you just need to rebuild your application as the input libraries will be updated automatically (by {{{build.mak}}}). 
    2035  1. If you maintain your own independent Makefile, please add {{{libsrtp-$(TARGET)}}} from {{{third_party/lib}}} directory to your input libraries.  
    2136 
    2237'''For Visual Studio 6 and 2005:''' 
    23   1. New {{{libsrtp}}} project has been added into PJSIP workspace. 
     38  1. New {{{libsrtp}}} project has been added into '''pjproject.dsw''' and '''pjproject-vs8.sln''' workspace. 
    2439  1. If you maintain your own application workspace, you need to add {{{libsrtp}}} project into your application. The {{{libsrtp}}} project files are in {{{third_party/build/srtp}}} directory. 
    2540 
    2641'''For Windows Mobile developments:''' 
    27   1. New {{{libsrtp}}} project has been added into PJSIP workspace. 
    28   1. If you maintain your own application workspace, you need to add {{{libsrtp}}} project into your application. The {{{libsrtp}}} project files are in {{{third_party/build/srtp}}} directory. 
    29   1. Make sure you import the Embedded Visual Studio project ({{{libsrtp.vcp}}}) rather than the Visual Studio ({{{libsrtp.vcproj}}}) project! 
     42  1. New {{{libsrtp}}} project has been added into '''wince_demos.vcw''' workspace (the workspace is located in {{{pjsip-apps/build/wince-evc4}}} directory). 
     43  1. If you maintain your own application workspace, you need to add '''{{{libsrtp.vcp}}}''' project into your application. The {{{libsrtp}}} project files are in {{{third_party/build/srtp}}} directory. 
     44  1. If you're using Visual Studio rather than Embedded Visual C++ 4, make sure you import the Embedded Visual Studio project ({{{libsrtp.vcp}}}) rather than the Visual Studio ({{{libsrtp.vcproj}}}) project! 
    3045 
    3146'''Symbian:''' 
    32   1. To be done. 
     47  1. Symbian port for libsrtp will be added soon. 
     48 
    3349 
    3450=== API Changes === 
    … …  
    7995=== Using SRTP in PJSUA-LIB === 
    8096 
    81 In [http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB.htm PJSUA-LIB], the use of SRTP is controlled by settings in both [http://www.pjsip.org/pjsip/docs/html/structpjsua__config.htm pjsua_config] and [http://www.pjsip.org/pjsip/docs/html/structpjsua__acc__config.htm pjsua_acc_config]. The settings in [http://www.pjsip.org/pjsip/docs/html/structpjsua__config.htm pjsua_config] specifies the default settings for all accounts, and the settings in [http://www.pjsip.org/pjsip/docs/html/structpjsua__acc__config.htm pjsua_acc_config] can be used to further set the behavior for that specific account. 
     97In [http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB.htm PJSUA-LIB], the use of SRTP is controlled by settings in both [http://www.pjsip.org/pjsip/docs/html/structpjsua__config.htm pjsua_config] and [http://www.pjsip.org/pjsip/docs/html/structpjsua__acc__config.htm pjsua_acc_config]. The settings in [http://www.pjsip.org/pjsip/docs/html/structpjsua__config.htm pjsua_config] specify the default settings for all accounts, and the settings in [http://www.pjsip.org/pjsip/docs/html/structpjsua__acc__config.htm pjsua_acc_config] can be used to further set the behavior for that specific account. 
    8298 
    83 In both {{{pjsua_config}}} and {{{pjsua_acc_config}}}, there are two configuration items to control: 
     99In both {{{pjsua_config}}} and {{{pjsua_acc_config}}}, there are two configuration items related to SRTP: 
    84100 
    85101 '''{{{use_srtp}}}''':: 
    86102  This option controls whether secure media transport (SRTP) should be used for this account. Valid values are: 
    87    - {{{PJMEDIA_SRTP_DISABLED}}} (0): SRTP is disabled, and incoming call with RTP/SAVP transport will be rejected. 
    88    - {{{PJMEDIA_SRTP_OPTIONAL}}} (1): SRTP will be advertised and SRTP will be used if remote supports it, but the call may fall back to unsecure media. 
     103   - {{{PJMEDIA_SRTP_DISABLED}}} (0): SRTP is disabled, and incoming call with RTP/SAVP transport will be rejected with 488/Not Acceptable Here response. 
     104   - {{{PJMEDIA_SRTP_OPTIONAL}}} (1): SRTP will be advertised and SRTP will be used if remote supports it, but the call may fall back to unsecure media. Incoming call with RTP/SAVP is accepted and responded with RTP/SAVP too. 
    89105   - {{{PJMEDIA_SRTP_MANDATORY}}} (2): secure media is mandatory, and the call can only proceed if secure media can be established. 
    90106  The default value for this option is {{{PJSUA_DEFAULT_USE_SRTP}}}, which is zero (disabled). 
    … …  
    92108 '''{{{srtp_secure_signaling}}}''':: 
    93109  This option controls whether SRTP requires secure signaling to be used. This option is only used when {{{use_srtp}}} option above is non-zero. Valid values are: 
    94      - 0: SRTP does not require secure signaling 
    95      - 1: SRTP requires secure transport such as TLS 
    96      - 2: SRTP requires secure end-to-end transport (SIPS) 
     110     - 0: SRTP does not require secure signaling (not recommended) 
     111     - 1: SRTP requires secure transport such as TLS to be used. 
     112     - 2: SRTP requires secure end-to-end transport ('''sips:''' URI scheme) to be used. 
    97113  The default value for this option is {{{PJSUA_DEFAULT_SRTP_SECURE_SIGNALING}}}, which is 1 (require TLS transport). 
    98114 
    … …  
    102118=== pjsua === 
    103119 
    104 New option '''---use-srtp''' is added, with valid values are 0, 1, or 2. This corresponds to {{{use_srtp}}} setting above. 
     120Two new options were added to [http://www.pjsip.org/pjsua.htm pjsua]: 
     121 
     122 '''{{{--use-srtp=N}}}''' 
     123   This corresponds to {{{use_srtp}}} setting above. Valid values are 0, 1, or 2. Default value is 0. 
     124 
     125 '''{{{--srtp-secure=N}}}''' 
     126   This corresponds to {{{srtp_secure_signaling}}} setting above. Valid values are 0, 1, or 2. Default value is 1. 
    105127 
    106128Sample usage: 
    107129{{{ 
    108  $ ./pjsua --use-tls --use-srtp=1 
     130 $ ./pjsua --use-tls --use-srtp=1 sip:alice@example.com;transport=tls 
    109131}}} 
    110  
    111 Note: we need to enable TLS since by default SRTP requires secure signaling to be used (see ''srtp_secure_signaling'' setting above). If you want to use SRTP with non-secure transport (which is not recommended unless for testing purpose only!), you can modify ''srtp_secure_signaling'' setting in pjsua application. 
    112132 
    113133 
    114134=== Using SRTP Transport Directly === 
    115135 
    116 The SRTP transport may also be used directly without having to involve SDP negotiations. However, you will need to have a different mechanism to exchange keys between endpoints. 
     136The SRTP transport may also be used directly without having to involve SDP negotiations (for example, to use SRTP without SIP). Please see '''streamutil''' from the samples collection for a sample application. For this to work, you will need to have a different mechanism to exchange keys between endpoints. 
    117137 
    118138To use SRTP transport directly: 
    … …  
    129149=== Changes in Media Transport Interface === #med-tp-changes 
    130150 
    131 Since the availability of SRTP changes contents of SDP (Session Description Protocol) and the SDP negotiation, we need to add new interfaces in PJMEDIA transport API to allow media transport to modify and negotiate SDP. Incidently this would work well with ICE too (previously we treat ICE as a special kind of media transport so it is treated differently, but with this new interfaces, all media transports will behave uniformly (anyway that's what API abstraction is for!)). 
     151Since the availability of SRTP changes SDP (Session Description Protocol) contents and the SDP negotiation, we needed to modify/add new interfaces in PJMEDIA transport API to allow media transport to modify and negotiate SDP. Incidently this would work well with ICE too (previously we treat ICE as a special kind of media transport so it is treated differently, but with this new interfaces, all media transports will behave uniformly (anyway that's what API abstraction is for!)). 
    132152 
    133153New interfaces in media transport are as follows (please consult the PJMEDIA transport documentation for more info): 
    134154 
    135155 '''media_create()''':: 
    136   This callback is called by application (or PJSUA-LIB) to allow the media transport to add more information in the SDP offer, before the offer is sent to remote. Additionally, for answerer side, this callback allows the media transport to reject the offer from the remote before this offer is processed by the SDP negotiator. 
     156  This callback is called by application (or PJSUA-LIB) to allow the media transport to add more information in the SDP offer, before the offer is sent to remote. Additionally, for answerer side, this callback allows the media transport to reject the offer before this offer is processed by the SDP negotiator. 
    137157 
    138158 '''media_start()''':: 
    139   This callback is called after offer and answer are negotiated, and before the media is started. For answerer side, this callback will be called before the answer is sent to remote, to allow media transport to put additional info in the SDP. The media transport also has the final chance to negotiate the offer and answer before media is really started. 
     159  This callback is called after offer and answer are negotiated, and both SDPs are available, and before the media is started. For answerer side, this callback will be called before the answer is sent to remote, to allow media transport to put additional info in the SDP. For offerer side, this callback will be called after SDP answer is received. In this callback, the media transport has the final chance to negotiate/validate the offer and answer before media is really started (and answer is sent, for answerer side). 
    140160 
    141161 '''media_stop()''':: 
    … …  
    143163 
    144164 '''simulate_lost()''':: 
    145   This has nothing to do with SRTP, but since all media transports support this feature (packet loss simulation), we add this as a new interface. 
     165  This has nothing to do with SRTP, but since all media transports support this feature (packet loss simulation), we added this as a new interface. 
    146166 
    147167 
    … …  
    154174I think the diagram above is self-explanatory. 
    155175 
    156 With SRTP, the SRTP is implemented as some kind of "adapter", which is plugged between the stream and the actual media transport that does sending/receiving RTP/RTCP packets. When SRTP is used, the interconnection between stream and transport is like the diagram below: 
     176SRTP functionality is implemented as some kind of "adapter", which is plugged between the stream and the actual media transport that does sending/receiving RTP/RTCP packets. When SRTP is used, the interconnection between stream and transport is like the diagram below: 
    157177 
    158178[[Image(media-srtp-transport.PNG)]] 
    159179 
    160 So to stream, the SRTP transport behaves as if it is a media transport (because it '''is''' a media transport), and to the media transport it behaves as if it is a stream. The SRTP object will forward RTP packets back and forth from stream to the actual transport and vice versa, encrypting/decrypting the RTP/RTCP packets as necessary. 
     180So to stream, the SRTP transport behaves as if it is a media transport (because it '''is''' a media transport), and to the media transport it behaves as if it is a stream. The SRTP object then forwards RTP packets back and forth between stream and the actual transport, encrypting/decrypting the RTP/RTCP packets as necessary. 
    161181 
    162182The neat thing about this design is the SRTP "adapter" then can be used to encrypt any kind of media transports. We currently have UDP and ICE media transports that can benefit SRTP, and we could add SRTP to any media transports that will be added in the future.