Changes between Version 4 and Version 5 of SRTP


Ignore:
Timestamp:
Jan 23, 2008 7:58:12 PM (17 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • SRTP

    v4 v5  
    55== Requirements == 
    66 
    7 SRTP feature in PJSIP uses [http://sourceforge.net/projects/srtp/ libsrtp] created by David A. !McGrew of Cisco Systems, Inc. Copy of [http://sourceforge.net/projects/srtp/ libsrtp] is included in PJSIP source tree. There is no other software to download. 
     7SRTP feature in PJSIP uses the Open Source [http://sourceforge.net/projects/srtp/ libsrtp] library created by David A. !McGrew of Cisco Systems, Inc. Copy of [http://sourceforge.net/projects/srtp/ libsrtp] is included in PJSIP source tree in {{{third_party/srtp}}} directory. There is no other software to download. 
    88 
    9 [http://sourceforge.net/projects/srtp/ libsrtp] is distributed under BSD-like license, you must satisfy the license requirements if you incorporate SRTP in your application. Please see [http://www.pjsip.org/licensing.htm PJSIP licensing] page for more information about this and other third party libraries used in PJSIP. 
     9[http://sourceforge.net/projects/srtp/ libsrtp] is distributed under BSD-like license, you must satisfy the license requirements if you incorporate SRTP in your application. Please see [http://www.pjsip.org/licensing.htm PJSIP licensing] page for more information about this and other third party libraries licensing in PJSIP. 
    1010 
    1111---- 
    … …  
    2929#define PJMEDIA_HAS_SRTP  0 
    3030}}} 
     31 
     32---- 
     33 
     34== Using SRTP == 
     35 
     36SRTP is implemented as media transport in PJMEDIA. In the high level [http://www.pjsip.org/pjsip/docs/html/group__PJSUA__LIB.htm PJSUA-LIB API], the use of SRTP is controlled by couple of settings as explained below. 
     37 
     38 
     39=== Using SRTP in PJSUA-LIB === 
     40 
     41In [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. 
     42 
     43In both {{{pjsua_config}}} and {{{pjsua_acc_config}}}, there are two configuration items to control: 
     44 
     45 '''{{{use_srtp}}}''':: 
     46  This option controls whether secure media transport (SRTP) should be used for this account. Valid values are: 
     47   - {{{PJMEDIA_SRTP_DISABLED}}} (0): SRTP is disabled, and incoming call with RTP/SAVP transport will be rejected. 
     48   - {{{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. 
     49   - {{{PJMEDIA_SRTP_MANDATORY}}} (2): secure media is mandatory, and the call can only proceed if secure media can be established. 
     50  The default value for this option is {{{PJSUA_DEFAULT_USE_SRTP}}}, which is zero (disabled). 
     51 
     52 '''{{{srtp_secure_signaling}}}''':: 
     53  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: 
     54     - 0: SRTP does not require secure signaling 
     55     - 1: SRTP requires secure transport such as TLS 
     56     - 2: SRTP requires secure end-to-end transport (SIPS) 
     57  The default value for this option is {{{PJSUA_DEFAULT_SRTP_SECURE_SIGNALING}}}, which is 1 (require TLS transport). 
     58 
     59 
     60 
     61 
     62=== pjsua === 
     63 
     64New option '''---use-srtp''' is added, with valid values are 0, 1, or 2. This corresponds to {{{use_srtp}}} setting above. 
     65 
     66Sample usage: 
     67{{{ 
     68 $ ./pjsua --use-tls --use-srtp=1 
     69}}} 
     70 
     71Note: 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. 
     72 
     73 
     74=== Using SRTP Transport Directly === 
     75 
     76The 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. 
     77 
     78To use SRTP transport directly: 
     79 - Call pjmedia_transport_srtp_create() to create the SRTP adapter, giving it the actual media transport instance (such as UDP transport). 
     80 - Call pjmedia_transport_srtp_start() to active SRTP session, giving it both local and remote crypto settings and keys. 
     81 - Call pjmedia_transport_attach() to configure the remote RTP/RTCP addresses and attach your RTP and RTCP callbacks. 
     82 - Call pjmedia_transport_send_rtp() and pjmedia_transport_send_rtcp() to send RTP/RTCP packets. 
     83 - Once you done with your session, call pjmedia_transport_close() to destroy the SRTP adapter (and optionally the actual transport which is attached to the SRTP adapter, depending on whether ''close_member_tp'' flag is set in the options when creating the SRTP adapter). 
    3184 
    3285---- 
    … …  
    69122The 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. 
    70123 
    71 ---- 
    72  
    73 == Using SRTP Transport == 
    74  
    75  
    76 === Using SRTP in PJSUA-LIB === 
    77  
    78 The use of SRTP is controlled by settings in both pjsua_config and pjsua_acc_config. The settings in pjsua_config specifies the default settings for all accounts, and the settings in pjsua_acc_config can be used to further set the behavior for that specific account. 
    79  
    80 In both pjsua_config and pjsua_acc_config, there are two configuration items to control: 
    81  
    82  '''use_srtp''':: 
    83   This option controls whether secure media transport (SRTP) should be used for this account. Valid values are: 
    84    - PJMEDIA_SRTP_DISABLED (0): SRTP is disabled, and incoming call with RTP/SAVP transport will be rejected. 
    85    - 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. 
    86    - PJMEDIA_SRTP_MANDATORY (2): secure media is mandatory, and the call can only proceed if secure media can be established. 
    87   The default value for this option is PJSUA_DEFAULT_USE_SRTP, which is zero (disabled). 
    88  
    89  '''srtp_secure_signaling''':: 
    90   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: 
    91      - 0: SRTP does not require secure signaling 
    92      - 1: SRTP requires secure transport such as TLS 
    93      - 2: SRTP requires secure end-to-end transport (SIPS) 
    94   The default value for this option is PJSUA_DEFAULT_SRTP_SECURE_SIGNALING, which is 1 (require TLS transport). 
    95  
    96  
    97  
    98  
    99 === pjsua === 
    100  
    101 New option '''---use-srtp''' is added, with valid values are 0, 1, or 2. This corresponds to {{{use_srtp}}} setting above. 
    102  
    103 Sample usage: 
    104 {{{ 
    105  $ ./pjsua --use-tls --use-srtp=1 
    106 }}} 
    107  
    108 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. 
    109  
    110  
    111 === Using SRTP Transport Directly === 
    112  
    113 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. 
    114  
    115 To use SRTP transport directly: 
    116  - Call pjmedia_transport_srtp_create() to create the SRTP adapter, giving it the actual media transport instance (such as UDP transport). 
    117  - Call pjmedia_transport_srtp_start() to active SRTP session, giving it both local and remote crypto settings and keys. 
    118  - Call pjmedia_transport_attach() to configure the remote RTP/RTCP addresses and attach your RTP and RTCP callbacks. 
    119  - Call pjmedia_transport_send_rtp() and pjmedia_transport_send_rtcp() to send RTP/RTCP packets. 
    120  - Once you done with your session, call pjmedia_transport_close() to destroy the SRTP adapter (and optionally the actual transport which is attached to the SRTP adapter, depending on whether ''close_member_tp'' flag is set in the options when creating the SRTP adapter).