ZRTP

From FreeSWITCH Wiki
Jump to: navigation, search

Contents

Making FreeSWITCH History

On Wed, May 20, 2009, bkw_ announced ZRTP support in FreeSWITCH core. ZRTP is SRTP based, but instead of using SIP to exchange keys, it exchanges keys within the media stream itself making it more secure. It does not require PKI. With integrated ZRTP support, FreeSWITCH automatically negotiates secure connections with endpoints that support the protocol. Currently, ZRTP is integrated into a few softphones, and is also available as a intermediary client application that intercepts your softphone's media and negotiates key exchange with FreeSWITCH (or any other ZRTP enabled endpoint). In our case, we will use the ZRTP SDK to build the supporting library for FreeSWITCH.

Getting Started

In order to enable ZRTP on FreeSWITCH, you need to be on a version newer than 05 Apr 2012. Versions prior to that will require you to separately obtain the libZRTP SDK.

Step 1

You will need to execute the following as your normal build process.

git pull
./bootstrap.sh
./configure --enable-zrtp
make
make install


Step 2

Assuming you have existing configurations, you need to add (or check is there) the following at the end of the settings stanza in your conf/autoload_configs/switch.conf.xml. For clarification, look at src/freeswitch/conf/autoload_configs/switch.conf.xml:

<param name="rtp-enable-zrtp" value="true"/>

Verification

Verification with a soft-phone

Enable ZRTP in your dialplan or globally as described below.

At this point you should be able to start your FreeSWITCH with ZRTP active. To test, return to the ZFone site and download the ZFone client app for your platform. After installing and firing it up, start up your favorite softphone (make sure it's supported, X-Lite is) and call your loopback (9996). If the ZFone client lights up green with "Secure Audio," Congratulations - Your FreeSWITCH is ZRTP capable!

Verification with FreeSWITCH CLI and Debug

Assuming you're familiar with the FreeSWITCH CLI, you can enable debug output and watch for the following output when the session starts. The important part to look for is "[ zrtp main]: Session initialization - DON"

2009-05-22 23:12:57 [DEBUG] switch_rtp.c:1037 switch_rtp_create() Starting timer [soft] 1 bytes per 10ms
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]: START SESSION INITIALIZATION. sID=44.
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]: ZID=343865343930656366336534.
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]: Loading User's profile:
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]:    allowclear: ON
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]:    autosecure: ON
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]:  disclose_bit: OFF
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]:           TTL: 4294967295
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]:   SAS schemes: 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() B256 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() B32
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]:      Ciphers: 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() AES3 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() AES1 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]:    PK schemes: 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() DH3k 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() DH2k 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() Mult 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]:           ATL: 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() HS32 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]:       Hashes: 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() S256 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger() 
2009-05-22 23:12:57 [DEBUG] switch_rtp.c:472 zrtp_logger()  [   zrtp main]: Session initialization - DONE. sID=44.

Enabling And Disabling ZRTP With The 'zrtp_secure_media' Variable

ZRTP can be controlled on a per-channel basis or globally with the zrtp_secure_media variable. To enable or disable globally use this API syntax:

global_setvar zrtp_secure_media=[true|false]

To enable or disable on a single channel from the dialplan use the set application:

<action application="set" data="zrtp_secure_media=[true|false]"/>

NOTE: Setting the zrtp_secure_media variable for a channel will override the global settings.

Enrollment For Trusted Man-In-The-Middle (MITM)

Use the zrtp_enrollment variable to have FreeSWITCH send an enrollment packet for trusted MITM:

<action application="set" data="zrtp_enrollment=true"/>

ZRTP passthru

When using MITM and you enable proxy-media you might experience that the UAs ignore the zrtp-hash. In that case you should enable inbound-zrtp-passthru:

<param name="inbound-zrtp-passthru" value="true"/>