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:

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:

  1. "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;
  2. "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:

  1. 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;
  2. 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).
  3. 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.
  4. SRTP authentication scheme is used by libZRTP in traffic encryption. The ZRTP Internet draft defines HS32 and HS80 values;
  5. 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:

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:

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.

This file is part of the documentation for Zfone.
Copyright ©  2006-2008 Philip R. Zimmermann. All rights reserved.
Generated on Mon April 21 2008 by doxygen 1.5.3-20060202. Written by Vitaly Rozhkov,Viktor Krikun, © 2007-2008