libzrtp
1.2.0
ZRTP VoIP security
|
The libzrtp library consists of three main components: the protocol module responsible for the safe connection of a call, the encryption module, and a set of interfaces. ZRTP works by assuming control of the VoIP traffic and initiating an encrypted connection between two ZRTP endpoints after a safe mode is achieved. To integrate the library, please review our documentation on the ZRTP interfaces, connections management, and integration plan.
Generally these should be all that are needed to build the libraries, applications, and samples:
<H3>Building Win32 Target with Microsoft Visual Studio</H3> Generally we can just do these steps: -# Visual Studio 8: open projects/win/libzrtp_vc8.sln solution, -# build the libzrtp_test application. <H3>Building for Windows Mobile</H3> Generally these are all that are needed: -# Visual Studio 8: open projects/win/libzrtp_wince_vc8.sln solution, -# build the libzrtp_test application. <H3>Locating Output Binaries/Libraries</H3> For GNU targets, library files will be placed to <c>./projects/gnu/build</c> and <c>./third_party/bnlib</c>. <H3>Running the Applications</H3> After successful build, you can try running libzrtp_test application on projects/gnu/build/test directory.
Getting the released tarball is the best way to obtain stable version of libzrtp. The tarball may not contain the latest features or bug-fixes, but normally it is considered more stable, tested and well documented.
The latest released tarball can be downloaded from the http://zfoneproject.com/prod_sdk.html
At the moment, SVN repository is available for libzrtp developers only. It will be opened for public soon.
The top-level directories (denoted as $TOP here) in the source distribution contains the following sub-directories:
$TOP/doc
- documentation folder;
$TOP/include
- header files:
zrtp_config_user.h
- user defined ZRTP configuration options;zrtp_config_win.h
- Windows related configuration options;zrtp_config.h
- libzrtp automatic configuration routine.zrtp_crypto.h
- contains definitions of the data types and functions necessary to strengthen the crypto-segment of the library. These functions are used only by libzrtp developers only. Typical projects based on libzrtp do not use these functions;zrtp_engine.h
- contains types and functions needed by the ZRTP state-machine For internal use only;zrtp_error.h
- contains error codes returned by the libzrtp functions;zrtp_iface_system.h
- contains a set of OS-related interface functions which must be implemented in order to use the library;zrtp_iface.h
- contains a set of ZRTP utility interface functions which must be implemented in order to use the library;zrtp_legal.h
- libzrtp license agreement;zrtp_list.h
- contains functions and macros for safe operations with linked lists. All lists in libzrtp are based on these functions. They can be used to avoid mistakes in list operations;zrtp_log.h
- contains functions to track bugs and store the error log.;zrtp_pbx.h
- conatins declarations of the main PBX related functions. Use this header if you are the implementor of some VoIP-server solutions;zrtp_srtp.h
- SRTP crypto types and interfaces. Used to integrate libzrtp with third party SRTP implementations;zrtp_srtp_builtin.h
- data structures for built-in realization of SRTP.zrtp_string.h
- contains functions for the use of the special, safe strings, zrtp_stringn_t, used by libzrtp.zrtp_types.h
- contains the definitions of the internal data types which are used by libzrtp developers and experienced users.zrtp.h
- conatins declarations of the main dataypes and function functions necessary to operate libzrtp. This file header is only must to be included in each module using the libzrt functions;$TOP/projects
gnu
- make files for Unix-like systems using autotools;symbian
- configuration and make files for Symbian platform;win
- Set of Microsoft Visual Studio project files for Windows and Windows CE.win_kernel
- makefiles for Windows Kernel mode.xcode
- project files for Apple Xcode.$TOP/src
- libzrtp source files;
$TOP/test
- test suite for libZRTP kernel logic. Includes versions for Unix, Windows, Windows CE and Symbian.
$TOP/third_party
bnlib
- libbn files which are not intended for external use;bgaes
- AES encryption library and hash functions by Brian Gladman;Before building libzrtp, some adjustments may be performed according to developers needs. In order to do this, include/zrtp_cinfig_user.h
should be used. Most of configuration parameters are optional and libzrtp can be build without any modifications.
Check Build Configuration for more information.
The library requires external implementation of some system-dependent functions to enable cross-platform operation. The libzrtp distribution contains almost all interface implementations for the following platforms: Windows, Linux, Mac OSX, Symbian, Windows CE. The Quick Start allows a fast integration of the library. Built-in implementations are used by default and developer don't need to anything more.
In order to start using libzrtp, developer should implement just few feedback interfaces. Libzrtp uses callbacks to notify application about some events in ZRTP protocol, such as:
Another callback which must be implemented - transport routine:
These only two callbacks which must be implemented to start using libzrtp. Example can be found at the end of this article.
For more detail information about libzrtp platform-dependent interfaces check XXX.
The new, autoconf based GNU build system can be used to build the libraries/applications for the following targets:
In order to use libzrtp's GNU build system, these typical GNU tools are needed:
In addition, the appropriate libraries must be installed for platform-dependent interfaces implementation. This could just be a libc and the appropriate system abstraction library such as Posix.
The build system is known to work on the following hosts:
Run "./configure" without any options to let the script detect the appropriate settings for the host:
Once the configure script completes successfully, libzrtp is ready to be built. Use following commands:
Description of all make targets supported by the Makefile's: - \c all. The default (or first) target to build the library binary; - \c clean. Clean the object files and libzrtp binary; - \c check. Build test cases and start libzrtp_test application; - \c distclean. Remove all generated files (object, libraries, binaries, and dependency files). - \c install. Make install of libzrtp headers and binaries; - \c uninstall. Remove installed headers and binaries.
To build libzrtp on OS X using Xcode you need following:
Follow the steps below to build libzrtp using Apple Xcode:
projects/xcode/libzrtp.xcodeproj
project file.projects/xcode/build/Debug
or Release.Use projects/xcode/libzrtp_test.xcodeproj
by analogy to build the test application.
The Microsoft Visual Studio based project files can be used with one of the following:
For the host platform, the following are required:
Follow the steps below to build libzrtp using Visual Studio:
projects/win/Debug
or Release.To build libzrtp test-cases use "libzrtp_test" as StartUp Project and perform steps listed above.
The Microsoft Visual Studio based project files can be used with one of the following:
For the host platform, the following are required:
Follow the steps below to build libzrtp using Visual Studio:
projects/win/Debug
or Release.libzrtp/include
libzrtp/include/enterprise
(if you are using Enterprise version of libzrtp)libzrtp/third_party/bgaes
libzrtp/third_party/bnlib
libzrtp/projects/gnu/config
(for GNU Autoconf targets)libzrtp/third_party/bnlib
libzrtp/projects/gnu/build
(for GNU Autoconf targets)libzrtp/projects/xcode/build/Release
(when building with Xcode)libzrtp/projects/win/Release
(when building with Visual Studio)libzrtp.h
header file to the application.libzrtp
and bnlib
.An overview for creating an encrypted channel using libzrtp:
@subsection howto_example_init 11.1 Initialization The library supports profiling and dictating different channel parameters, though the initialization can be performed by one function call with default parameters.
@subsection howto_example_sessions 11.2 Sessions/Streams The library operates with the ZRTP streams concept, where each packet is encrypted within this stream. The streams are created before the start of the encryption process.
@subsection howto_example_protocol 11.3 Protocol Handling To create an encrypted channel, run the ZRTP engine for each stream added to the session. In our case we have two streams. The library will notify when achieving safe mode through the feedback path interface.
The three steps above create the encrypted channel. After entering the "Secure" state, you provide a plain packet to the library and receive an encrypted packet ready to be sent. Decryption works in the analogous way.
@subsection howto_example_callbacks 11.4 Callbacks libzrtp informs the user application about all changes in protocol state through a system of callback functions. The developer's guide considers this question in detail in \ref XXX. In most cases we need to display the SAS string and some other stream options after switching to the Secure state. An example of doing this is follow:
An overview for closing an secure channel using libzrtp:
@subsection howto_example_utilization 11.5 Utilization The uninstall session permits libzrtp to dispose of all engaged resources and release memory for session context storage. ZRTP streams will be also released, so you don't need to call separate functions.
When you no longer need the library, dispose of all resources allocated before the beginning of the operation.