[Ccrtp-devel] GNU ZRTP available as V1.1.0 Release candidate 1

[Werner Dittmann]

All,

after a long time of silence with respect to GNU ZRTP here the latest
news. I'm going to release a new version, GNU ZRTP 1.1.0. It's already
available in CVS as a Release Candidate und the tag V1_1_0-RC1. This
lengthly e-mail gives some information about new ZRTP features, the
GNU ZRTP implementation, installation etc. Please make sure you read
the "Installation" section below :-) .

For your convenience I've updated the ZRTP FAQ and edited a new GNU
ZRTP How-To. Both are part of the GNU Telephony wiki, located in its
documentation category. Here are the URLs:

http://www.gnutelephony.org/index.php/GNU_ZRTP_How_To
http://www.gnutelephony.org/index.php/ZRTP_FAQ

I will update the How-to as new questions arise.

== General Information regarding ZRTP ==

After some heavy discussions during the last few IETF meetings it is
now clear that Phil's ZRTP specification will become an informational
RFC. This will take some time because of the usual IETF proceedings,
also because the competing standards RFC is not yet ready AFAIK. See
footnote [1].

The general the way how ZRTP works, its protocol call flows, and its
basic features were not changed. The internal layout and structure of
the ZRTP messages were changed, new message were introduces as well as
some new features. Most of these new features are purely inside the
GNU ZRTP core and have minimal effect on the external interface
although some small changes were required.

GNU ZRTP implements the basic ZRTP as specificied in the document
''draft-zimmermann-avt-zrtp-06x''. You may access this at this URL:
[http://zfoneproject.com/zrtp_ietf.html]

The most noteable new feature of ZRTP are:

 * Multi-stream mode - a lightwight crypto data exchange that reuses
  data from an existing session tha was created in Diffie-Helman
  mode. An application shall use this mode only in associated RTP
  streams, for example a SIP client starts with audio, then enhances
  to audio and video. The application shall use the same SIP dialog
  (SIP re-invinte) to setup the additional RTP session. Multi-stream
  saves the Diffie-Helman overhead and is ideal for low power CPU, for
  example ARM. GNU ZRTP does not yet implements this mode (see below
  for further explanations).

 * Pre-shared mode - similar to multi-stream mode but is not restricted
  to the "same" SIP dialog (or signaling dialog). Pre-shared mode is
  not as secure as all other modes, thus GNU ZRTP does not implement
  (and probably will never) this mode.

 * PBX enrollement - this feature was introduced to provide a better
  interworking with PBXes, for example Asterisk. IMHO it's a critical
  feature because it introduces the PBX as a "trusted
  Man-in-the-Middle". This is sometimes necessary because PBXes often
  terminate the RTP session from the caller, extract the RTP data, do
  some re-coding and send it over a second session to the callee. This
  second session may be an "old fashioned" TDM connection. This mode
  is also not yet implemented beause it requires some features of the
  application that uses GNU ZRTP (see below for futher explanations).

 * SAS Signature - well, this is for people who like to to full
  automatic ZRTP. This requires some sort of PKI infrastructure and
  specific application functions.

Some explanation how GNU ZRTP supports the additional features: well,
none of the additional features is implemented. However, to keep the
external interface as stable as possible I already implmented stubs
for the additional features. Maybe we can have some discussion here
which of the features should be implemented first.

The current version of GNU ZRTP is compatible and was tested to work
with the latest Zfone beta (dated April, 2nd) (see Zfone project
site).

== Installation of GNU ZRTP 1.1 ==

Before you install GNU ZRTP 1.1 remove all existing GNU ZRTP
headers files from the include directory. Usually this is either
"/usr/include/libzrtpcpp" or
''"/usr/local/include/libzrtpcpp''. Depending how you installed the
previous version you may use ''make uninstall'' from the base directory of
the previous version or remove the packet (RPM or APT packet). You may
check the include directories after this.

Building and installation of the GNU ZRTP 1.1 us the usual triplet of
''./configure; make; sudo make install''. By default GNU ZRTP install
its files into the ''/usr/local'' hierarchy. Don't forget to run
''/sbin/ldconfig'' if you use the ''make install''.

After installation of GNU ZRTP you may adapt your applications and
re-compile and re-build.

== Changes of the interface and header files ==

Because of the new ZRTP features some new methods are available, all
of them are optional, some of these are stubs (see above). Also the
number and structure of header files was changed.

=== Interface changes ==

The ''SymmetricZRTPSession'' implements some new methods to control
ZRTP and its new features. An application usually uses only a few
methods to setup GNU ZRTP. All others are optional and an application
may use them only if it requires a special feature (which is not yet
implemented :-)  ).

The ''ZrtpUserCallback'' class was modified as well. From an
application's point of view

 * The methods in ''ZrtpUserCallback'' are not pure virtual anymore
   but just virtual and have a default implementation, usually a
   simple return. An application may extend this class and overwrite
   only those methods it requires.

 * Change of the constructor - remove the queue parameter thus we have a very
  simple standard constructor. This modifcation may requires a small
  change in the application or class that uses or extends
  ''ZrtpUserCallback''.

 * The method showSAS has an additional parameter:

     showSAS(std::string sas, bool verified);

  the verified flag is set to true in SAS is verified, false if not verified.
  This allows a more flexible support to display the SAS even if SAS is
  verified. Formerly ZRTP did not call "showSAS()" if SAS was verified. Now
  ZRTP always calls showSAS and provides the verification information
  explicitly.

* The siganture of the following methods changed:

        showMessage(GnuZrtpCodes::MessageSeverity sev, int32_t subCode)

        zrtpNegotiationFailed(GnuZrtpCodes::MessageSeverity severity,
                                           int32_t subCode)

  The GNU ZRTP core and the ZRTP ccRTP extension do not contain
  message strings anymore. Both use codes to inform an application
  about events, problems or failure. The folder ''demo'' contains a
  small demo program that shows one way how to map the codes to
  strings. Delegating string handling and formating to the application
  simplifies internationalization etc.

Additional callback interfaces are available, but not yet used. Most
noteably the "enrollment" stuff for PBX as "trusted Man-in-The-Middle"
(Asterisk supports this in its latest version). Have a look into
chapter 8.3 in the ZRTP specificaton to get an idea how this
works. For a client it would require a sort of a''non-modal'' decision
box with OK / Not OK buttons that would be displayed:

on "zrtpAskEnrollment(std::string info)" - callback display the decision box
  user selects OK     - call ''acceptEnrollment(true'' on SymmentricZRTPSession
  user selects not OK - call ''acceptEnrollment(false)'' on 
SymmentricZRTPSession

on "zrtpInformEnrollment(std::string info)" - just show information about
 success or failure of enrollmment.

I would ask application developers to give some feedback if this
feature is required.

Plaese note: these new callback methods and ZrtpQueue methods are only
stubs in the currect version. The real implementation will be done
some time later, but this will not have any impact on the callback
interface because the binary interface (linking) remains unchanged.
Only internal methods need to be modified or implemented.

=== Header files ===

The new version greatly reduces the number of header files installed
in the include directory. In the new version I decoupled the internal
header files and implementation from the external classes and
interfaces an application requires. Only six header files are
installed in libzrtpcpp's include directory.

== Demo program ==

The new folder ''demo'' contains a small demo program that shows
various ways how to use GNU ZRTP to setup secure RTP (SRTP) sessions
even without signaling protocols


Best Regards,
Werner


[1] Note: The other one is DTLS-SRTP. If you are interessted I've done
some analysis of this protocol and have a preliminary description of
this analysis - it's much more complex than ZRTP and is also much more
vulnerable to insider attacks.