Asterisk ZRTP Users Guide

1. Scenarios

There are two main ZRTP Asterisk modes: Passthrough and MiTM. In Passthrough mode, PBX just transfers media data and ZRTP messages without modification. There is only one change we need to make in this mode - to make Asterisk accept and transfer ZRTP protocol messages. In MiTM mode Asterisk acts as a ZRTP endpoint and runs the ZRTP protocol to setup a secure ZRTP connection between two endpoints separately.

In this document we will list all possible ZRTP states and illustrate them using diagrams. The following are basic terms for understanding these states:

SIP client - software or hardware VoIP client using SIP signaling protocol;
nonSIP client - as a rule hardware clients used PSTN or GSM lines and communicate with the PBX through PST/GSM gateways. SIP is unavailable for such clients;
SIP-registered - user registered to Asterisk PBX using his account name and password;
ZRTP-enrolled - user performed special enrollment ritual and delegated Asterisk PBX to act as a proxy and transfer the SAS.
ZRTP-ready - ZRTP endpoint user used ZFone or some VoIP client with integrated ZRTP encryption.

To read diagrams: to the right of every diagram the PBX local user is displayed, and the set of outside callers is displayed at the left. The lines at the bottom of the user icon define his options (see comments above). Black lines indicate an encrypted media channel, red lines indicate plain data.

1.1 ZRTP PBX Passthrough mode

1.1.1 ZRTP call in Passthrough mode for ZRTP user

This diagram explains how a ZRTP call operates in Passthrough mode between a registered inside user and any outside caller: the ZRTP stream will be established as it runs directly between two endpoints. PBX doesn't provide any ZRTP related processing.

1.1.2 ZRTP call in Passthrough mode for non-ZRTP user

Diagram 1.1.2 shows that a call will not be encrypted if the inside user doesn't support ZRTP. Note: If you need ZRTP encryption without having ZFone you should configure PBX in MiTM mode.

1.2 ZRTP PBX MiTM mode

1.2.1 ZRTP call in MiTM mode for enrolled user

In this case the enrolled user makes calls to different outside users. Two separate ZRTP channels are established: between Alice and the PBX and between the PBX and Bob. This results in two separate media streams encrypted by different stream keys and with two different Short Authentication Strings. The PBX should transfer its SAS to the enrolled user for verification. If both users are enrolled, the PBX will choose one according to the ZRTP protocol.

In case a), both Alice and Bob are enrolled and the PBX transfers the SAS to one of the parties using a special algorithm defined in the ZRTP specification. Case b) shows the case when the internal user is the only one enrolled. In this case the SAS will be transferred to Alice. In case c) Bob doesn't support ZRTP and the PBX can't establish a secure channel.

1.2.2 ZRTP call in MiTM mode for non-enrolled user

Diagram 1.2.2 shows cases where Alice doesn't trust the PBX for some reason. In case a) the PBX will transfer to Bob, who is enrolled to this PBX. Case c) is when neither Alice nor Bob are enrolled, so the PBX will not transfer an SAS and SAS values will be different for Alice and Bob. At least one of the users MUST be enrolled to allow ZRTP connections. Info: We recommend that the enrollment ritual is provided for all PBX registered users.

1.2.2 ZRTP call in MiTM mode for non-ZRTP user

Diagram 1.2.3 explains how ZRTP encryption works when the inside user doesn't support ZRTP by itself. In this case the PBX will act as a ZRTP proxy and encrypt calls with outside ZRTP-ready users. In both cases a) and b), the PBX will establish an encrypted channel with Bob and read the Short Authentication String to Alice by an automated voice. This scheme allows Alice to compare the SAS if she doesn't have the ZFoneGUI or even if she uses a hardware VoIP phone.

2. PBX usage

2.1 Usage for users who have Zfone or ZRTP-ready software installed

Enrollment with your PBX

If you know that your phone is already preconfigured by your administrator to trust your PBX, you may skip the ZRTP enrollment process. To carry out the ZRTP enrollment process yourself, call the special ZRTP enrollment number you can obtain from your administrator.

If you call the ZRTP enrollment number the first time your Zfone goes to the secure state, you will hear this message from the PBX:

"Welcome to the PBX ZRTP security enrollment agent. This PBX is equipped to handle ZRTP-encrypted phone calls. You must decide if you want to allow this PBX to be in a position to intercept and possibly monitor your secure phone calls. If you trust this PBX to relay ZRTP-secured calls, press the appropriate button on your phone to enroll and bind this PBX to your phone. You may hang up after you have done this."

Next you have to mark your PBX as verified and select "Register with this PBX" from the menu of your Zfone or ZRTP-ready software and then hang up.

After successfully enrolling, you may make secure calls with peers whether or not they are enrolled. A secure call can be made and the SAS will be relayed if at least one peer is ZRTP-enrolled with the PBX.

If you don't trust your PBX anymore you can cancel your enrollment. To do this you have to delete the appropriate cache entry from your Zfone caches menu.

If you call the ZRTP enrollment number when you are already enrolled, you will hear this message:

",,Welcome to the PBX ZRTP security enrollment agent. Your phone indicates that it already trusts this PBX to relay ZRTP-secured calls, so you do not need to do anything more. Thank you for calling. Goodbye."

If you call the ZRTP enrollment number using a phone that does not have ZRTP capabilities, you will hear this message:

",,Welcome to the PBX ZRTP security enrollment agent. Only phones equipped with the ZRTP protocol can use this extension. Your phone is not a ZRTP-enabled phone, so this call will have no effect. Thank you for calling. Goodbye."

If you call the ZRTP enrollment number using a phone that is not SIP-registered to this PBX, you will hear this message:

",,Welcome to the PBX ZRTP security enrollment agent. Only phones that are recognized by this PBX as SIP-registered to this PBX can be configured to trust this PBX to relay ZRTP-secured calls. Your phone is not SIP-registered with this PBX, so this call will have no effect. Thank you for calling. Goodbye."

Making calls

When you are connected to a call through your PBX, SAS values will appear on your Zfone upon entering the secure state. You then compare your SAS values with your peer. If the SAS values match, the call is secure and you can mark your peer as verified. After this you will not have to compare SAS values again with this peer as long as you trust it. If you stop trusting the peer, you can unmark it for the next call.

2.2 Usage for users who don't have Zfone or ZRTP-ready software installed

Making calls

When you are connected to a call through your PBX, SAS values will be played for you by an automated voice. You can request a replay of the SAS values by pushing the appropriate number key*. If the SAS values you heard match the SAS values of your peer, your call is secure. In this case you may mark your peer as verified. To do this you have to push the appropriate number key**. If you mark your peer as verified you will not have to check SAS values with him/her. So, SAS values will not be played for you when you make another call with this peer, but if you want to check SAS values you may push the number button to replay them. You also can cancel the verified state of your peer by pushing the SAS verified number button a second time.

∗ contact your administrator to get the number for SAS replay
∗∗ contact your administrator to get the SAS verified number

3. Configuration of the zrtp module

All ZRTP parameters can be divided in two groups: "behavior settings" and "crypto-settings". The first group is responsible for the ZRTP stream's "behavior" and the other one determines the secure stream cryptographic parameters.

"Behavior" settings are represented by boolean flags with "true" and "false" values. They include:

"staysecure" (zrtp_profile_t::staysecure) - prohibits moving to the non-protected mode. If this option is on, the ZRTP engine ignores all attempts to transition to the non-protected mode. This option is enabled by default and can't be changed in the current version of ZRTP for PBX. If we find it useful we will may make this option configurable;
"autosecure" (zrtp_profile_t::autosecure) automatically activates transition to the secure mode right after the "discovery phase", omitting any Clear state. I.e., if this operation is on, ZRTP moves the stream to the protected mode. ZRTP for PBX works in "autosecure" mode by default. This option can't be changed.

"Crypto-settings": the protocol defines 5 crypto-component types used in calculations:

cipher type is the type of block cipher used for encryption of RTP traffic and some ZRTP packets. At the moment the following ciphers are available: AES1 and AES3, with key sizes of 128-bits and 256-bits respectively;
pk scheme is the public key exchange scheme used in establishing the secure channel. There are two kinds of key exchange schemes: Full and Fast. Full schemes are based on the Diffie-Hellman key exchange and used to setup the ZRTP session. Already established sessions may be extended with a video channel by using a Fast stream which omits the DH exchange and derives the stream key from the session key. Full PK exchange schemes: classic Diffie-Hellman DH3K, and Elliptic Curve Diffie-Hellman ECDH-256 (EC25) and ECDH-384 (EC38).
hash type is the type of hash function used for RTP media packet authentication and other calculations in the connection installation. At this time only the SHA algorithm with a 256 bit key size is supported.
SRTP authentication scheme is used by libZRTP in traffic encryption. The ZRTP Internet draft defines HS32 and HS80 values;
SAS scheme defines the information provision scheme for verifying retained secrets. ZRTP supports two SAS types: base 32 and base 256.

The "crypto-settings" configuration contributes to the choice of each component type by providing a priority ranking. It works as a request, in that the component chosen for the first priority is not necessarily used in the connection installation. Rather, the resulting component type depends also on the opposite side's settings. The component choosing mechanism is as follows: both sides communicate their supported components during the "discovery phase". After that the initiator chooses the optimal intersection of components. Thus it is possible to set a condition such as: "use component type A; if A is not supported by the other side, then use B; never use C".

The configuration file of the ZRTP module is at /etc/asterisk/zrtp.conf. Configuration parameters explanation:

staysecure: enabled by default, not configurable
CACHE_TTL: Set to "Forever"
ATL: ATL32 MUST be in the profile and ATL80 is optional;
SAS: B32 MUST be in the profile and B256 is recomended;
HASH: S256 is the only one and is a mandatory option;
CIPHER: AES1 is mandatory and AES3 is optional;
PKTYPE: DH3K and MULT are mandatory and ECDH-256 (EC25), ECDH-384 (EC38) are optional;
DIR: patch to store ZRTP related data;
sas_replay_dtmf: DTMF signals sequence to replay SAS values for non-ZRTP peer.
sas_verified_dtmf: DTMF signals sequence to toggle SAS verified flag by non-ZRTP peer.
automatic_play_sas: if set to 'yes' then SAS values will be played by an automated voice to the non-ZRTP peer when the appropriate ZRTP peer is in Secure mode. If the appropriate ZRTP peer has been verified, SAS values will not be played automatically. If set to 'no', SAS values will not be played. To play SAS values, the non-ZRTP peer has to send the DTMF sequence set in the sas_replay_dtmf parameter.

4. Getting ZRTP works in peer-to-peer mode

It is more safely when zrtp works in peer-to-peer mode than when PBX acts trusted man in the middle role. If you completely trust your PBX in the security context this is no matter in which mode zrtp works.

In peer-to-peer ZRTP mode PBX doesn't have access to the plain data even it flows through it. Opposite in trusted MiTM mode PBX has full access to the plain data and can modify it before send to another peer.

ZRTP works in peer-to-peer mode when:

PBX works in pass-through mode (RTP traffic doesn't flow through PBX. Peers communicate directly with each other.)
RTP traffic flows through PBX but it should not translate RTP packets (no codecs translation, no DTMF signals interpretation and so on is needed). In this case RTP traffic will be just redirected from one peer to another and PBX will acts proxy role.

5. Installation of the zrtp module

The patch filename consists of zrtp_asterisk-<asterisk_version>-<patch_version>

This patch has been tested on Asterisk version that pointed in the patch filename.

Ensure that you have libzrtp v 0.6.7 installed on your system.

    Note: libzrtp has to be configured used ./cfg.asterisk or ./cfg.asterisk_ec

Apply the patch to Asterisk. Use -p2 argument to apply patch.
Build and install Asterisk.

Put zrtp.conf into asterisk configuration directory (usually /etc/asterisk)

    Note: if you use libzrtp without EC support EC-related PKTYPE values (EC521P, EC384P, EC256P)
            aren's significant.

Ensure that res_zrtp.so module loads before res_features.so module. To do this add load => res_zrtp.so to [modules] section of modules.conf file. This item have to be before load => res_features.so if it exists.
Put ./sounds/zrtp directory to Asterisk sounds directory (usually /var/lib/asterisk/sounds).

Add new extension into extensions.conf for enrollment procedure activate. E.g.

    exten => 1717,1,Answer
    exten => 1717,n,Enroll_zrtp ; permit transfer
    exten => 1717,n,Hangup