retronetworking
/
freeswitch
12
0
Fork 0
Code Pull Requests Releases Activity

Merge Phil Zimmermann's libzrtp as a FreeSWITCH library 

Thanks to Phil Zimmermann for the code and for the license exception
we needed to include it.

There remains some build system integration work to be done before
this code will build properly in the FreeSWITCH tree.
v1.2.stable
Travis Cross 2012-03-31 23:42:27 +00:00
parent 350b41fa19 fcfa41e537
commit d2edcad66e
261 changed files with 86866 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
libs/libzrtp/AUTHORS Normal file
View File

@ -0,0 +1,33 @@
#
# Copyright (c) 2006-2009 Philip R. Zimmermann. All rights reserved.
# Contact: http://philzimmermann.com
# For licensing and other legal details, see the file zrtp_legal.c.
#
# Viktor Krikun <v.krikun at zfoneproject.com>
libzrtp BETA
Created by Phil Zimmermann.
Developers:
Viktor Krikun
Nikolay Popok
Vitaly Rozhkov
Andrey Rozinko
Bryce Wilcox-O'Hearn
Thanks to:
Alan Johnston
Jon Callas
Hal Finney
Colin Plumb
Sagar Pai
Werner Dittmann
L. Amber Wilcox-O'Hearn
Ariel Boston
Donovan Preston
Software development services provided by Soft_industry http://www.soft-industry.com/en.
Portions of this software are available under open source licenses from other authors.
Notably, Brian Gladman's AES implementation, and David McGrew's libSRTP package.

556
libs/libzrtp/ChangeLog Normal file
View File

@ -0,0 +1,556 @@
* libZRTP SDK library, implements the ZRTP secure VoIP protocol.
* Copyright (c) 2006-2009 Philip R. Zimmermann. All rights reserved.
* Contact: http://philzimmermann.com
* For licensing and other legal details, see the file zrtp_legal.c.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
SINCE LIBZRTP v0.80 CHANGELOG IS A PART OF HTML DOCUMENTATION.
https://developers.zfoneproject.com/libzrtp/wiki/LibzrtpChangeLog
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
libzrtp 0.7.1 18.11.2008
--------------------------------------------------------------------------------
1. Fixed bug with hardcoded AES128 cipher for generating SRTP keys. In this
version is selected according to ZRTP discovery.
2. Added initialization/deinitalization functions to zrtp helper functions.
libzrtp 0.7.0 04.11.2008
--------------------------------------------------------------------------------
1. Changes in libzrtp sources tree.
2. Improvements in libzrtp initialization routine:
- all global zrtp options were combined in zrtp_config_t structure;
- zrtp_init() allocates memory for zrtp global context;
- zrtp_config_defaults()
3. Improvements for Passive/Active mode support.
a) A passive endpoint never sends a commit message, period. Also, it
declares itself as a passive endpoint by setting the P flag it its own
Hello message;
b) A active endpoint does not send a commit to a passive endpoint, which it
recognizes by detecting the P flag;
c) A passive phone, if acting as a SIP initiator (meaning it initiated the
call), rejects all commit packets from everyone;
d) A passive phone rejects all commit messages from a PBX, which is easily
recognized by the M flag.
Passive mode support is built into the library logic and will be used
automatically if the developer specifies signaling role by setting
is_initiator flag in zrtp_init_session_ctx().
4. Improvements in ZRTP feedback interface and system-dependent functions.
There are two types of interface functions in libzrtp: system dependent API
and realization of helper functions and events. System dependent API in
defined in zrtp_iface_system.h as set of extern functions. System
functions are already implemented for several basic platforms in
zrtp_iface.sys.c libzrtp feedback and helper functions were re-factored
and implemented as set of callbacks. If the developer doesn't want to
handle one or another event it may just leave necessary pointer empty.
See zrtp_init() and zrtp_callback_t, zrtp_iface.h for more details.
5. ZRTP configuration approach was improved: zrtp_config_xxx.h contains
adjustments for necessary target platform. libzrtp contains default
configs for Linux, OS X, Windows, Window CE and Symbian platforms.
All ZRTP protocol and behavior related adjustments are collected in
zrtp_config_user.h. Edit this file to configure libzrtp for your
needs.
6. Implemented new functions in protocol according to the Internet Draft v 10.
7. Improved realization of built-in libzrtp scheduler. Fixed bug with crashing
on performing delay call when zrtp session have been already deleted.
8. Logging function was improved. Use ZRTP_LOG macro to print log messages. See
zrtp_log.h for more information.
libzrtp 0.6.8 03.09.2008
--------------------------------------------------------------------------------
ZRTP
1. Fixed bug with incorrect maximum value for T1 retry interval timer which
increased delay between LOOKING_FOR_ZRTP and NO_ZRTP_SUPPORT states.
Internal fix, no API changes required;
2. Implemented version negotiation according to the latest specification.
libzrtp v 0.6.8 supports ZRTP v0.90 only. No changes required in
applications that use the SDK.
3. Compilation flag WITH_ZFONE was removed. The developer, who wants to use
built-in ZRTP cache, has to set name of the ZRTP cache explicitly,
implementing zrtp_get_cache_path() function.
4. New libzrtp licensing scheme was implemented. It allows the licensing policy
to be changed at run time. See zrtp_license_mode_t doc. for more details.
Affected API - zrtp_init().
5. ZRTP Protocol version was changed to 0.90 according to ZRTP Internet Draft.
6. Some changes in Linux config files: surplus configuration flags were removed
from ./cfg.XXX templates.
7. Added experimental ZRTP messages retries scheduler for slow channels. As
ex ample for GSM CSD channel with average bandwidth 6Kb/s. To use this
option build library with BUILD_FOR_CSD flag.
libzrtp 0.6.6 27.06.2008
--------------------------------------------------------------------------------
ZRTP
1. Small bug was fixed in S0 calculation: when RS1 is corrupted the library uses
RS2 instead;
2. Some changes in Makefile and building process: unused header were eliminated
from the installation process.
3. -DBUILD_WITH_ZRTP_MUTEXES was replaced with --enable_mutexes option passed to
./configure script. This change allows not to specify any libzrtp compilation
flags during user application compilation. --enable-mutexes adds
BUILD_ZRTP_MUTEXES definition to the ./config/zrtp_unix_config.h so if you
build libzrtp on other platforms - define this flag manually (windows
configuration file already includes this option).
4. Clean-up in .h and .c comments was made.
libzrtp 0.6.5 04.06.2008
--------------------------------------------------------------------------------
ZRTP
1. New names for: other_secret - pbxs; srtps - auxs. In bits and secrets storages;
2. RS2 secret was eliminated form DH s0 calculation;
3. Protocol version number was increased to 0.85
libzrtp 0.6.4 19.05.2008
--------------------------------------------------------------------------------
ZRTP
1. According to the new version of the Internet Draft Signaling shared secret was
removed from the protocol and from the sources. It was not used by interface
functions and developers may change nothing in libzrtp based applications.
2. DH4K Key echange was eleminated from the specification and from the sources.
Now ECDH is used for all larger AES key sizes.
libzrtp 0.6.2 04.02.2008
--------------------------------------------------------------------------------
ZRTP
1. New behaviour for Secure --> Clear --> Secure scenario was implemnted. According
to ZRTP ID 06 section 5.7.2.1 new value of ZRTPSess computed as hash(ZRTPSess).
DOC:
Libzrtp documentation was updated up to version 0.6.2.
libzrtp 0.6.1 03.14.2008
--------------------------------------------------------------------------------
ZRTP
1. Multistream mode was implemented according to ZRTP Internet Draft 05.n:
- new stream mode zrtp_stream_mode_t:: ZRTP_STREAM_MODE_MULT;
- Multistream key exchange component was added with ID zrtp_pktype_id_t::
ZRTP_PKTYPE_MULT and symbolic name ZRTP_MULT. To allow libzrtp use Multistream
mode - ZRTP_PKTYPE_MULT have to be added to the stream profile in the first
position;
- According to the new draft SAS and ZRTPSess key are Session option and
were moved to the zrtp_conn_ctx_t structure. New specification defines
single SAS values for all streams within the session;
- ZRTP state-machine was changed to handle Multistream mode. In .Fast. mode
DH exchange is omitted and stream skips ZRTP_STATE_WAIT_CONFIRM1 and
ZRTP_STATE_PENDINGSECURE for the Initiator and Responder state-machines,
respectively;
2. Hash preimages were added to prevent DOS attacks. See ZRTP ID sec 9.0 for detail
information. This option is available using zrtp_set_signaling_hash() and
zrtp_get_signaling_hash() functions.
3. Hmac values were added to every packet to allow eliminate SAS validation
if SIP is protected;
4. Autosave. of the default realization of the ZRTP cache to the hard drive was
implemented;
5. Lot of other internal changes and improvements according to the latest ZRTP
specification v06.
libzrtp 0.4.5-6
--------------------------------------------------------------------------------
1. Full PBX support. Tested on GS-Labs Asterisk
API:
DOC:
2. Resolved problem with BG ciphers compilation: initialization of AES hash tables.
3. Fixed bug in SRTP replay protection. (Undeleted nodes for mulsy-stream encryption)
(May resulted in a error zrtp_protocol_error_t::zrtp_status_rp_fail)
4. Vrification is a session option. Input parameter of zrtp_set_verified() was
changed from stream to ZRTP session structure.
5. Fixed bug with malformed ZRTP Hello packet.
5. fast video
libzrtp 0.4.4 31.07.2007
--------------------------------------------------------------------------------
1. New extra error code for replay protection was added.
See zrtp_status_t::zrtp_status_rp_fail.
2. Fixed bug which may resulted in a dammage with decrypt failed 7 error. It
was happen when libzrtp passed RTP alerts packet to the replay protection
engine and ROC was broken.
3. Fixed RTCP encryption/decryption.
4. Fixed bug with RS1 and RS2 swapping when one of the sides lost RS1.
(May resulted in a error zrtp_protocol_error_t::zrtp_error_auth_decrypt )
libzrtp 0.4.3 06.07.2007
--------------------------------------------------------------------------------
1. Beta version of API for PBX support according to the latest ZRTP draft.
Not tested. For internal development only. Follow // PBX comments;
- secret's cache format was changed.
2. S0 calculation according to NIST recommendations; Internal change
- ZRTP protocol version was increased to 0.07.
3. All libzrtp sources was audited with coverity code analyzer. http://coverity.com/
libzrtp (0.3.9 - 0.4.2) 27.06.2008
--------------------------------------------------------------------------------
1. Changes according to new draft 04a. All changes are internal.
a) new DH packets: pvi/pvr, nonce field is at the end of the DH packet.
In "Preshared" mode both DH packets contain nonce value instead of pvi/r;
b) new hvi value the same for all modes (DH and Preshared)
hvi = hash(initiator's DHPart2 message | responder's Hello message);
c) new algorithm of SAS computing: sasvalue = HMAC(hmackeyi,"SAS");
2. New GUI based test-unite forSymbian platform
3. Default implementation of the packet retries unite for Symbian was added
to the libzrtp package. Except besides scheduler, libzrtp includes
realization of some synchronization and threading routines. These
components written in C++ and can't be linked with the library. One should
add them to own Symbian project project.
4. Compilation of default realization of ZRTP mutexes was separated from
the other system interfaces. To build library with default mutexes
BUILD_ZRTP_MUTEXES flag should be used;
5. New clearing logic. Goals:
API:
- state-machine states were changed
- goclear reason was eliminated. Now we can switch to CLEAR just on
user action.
- ZRTP_EVENT_IS_INITIATINGCLEAR was removed as a uperfluous event. As a
result all event codes were changed.
- new clear_hmac = HMAC(hmakkeyi/r, "Clear Hmac")
6. New Errors handling logic. See updated state-macine diagram and "developers
guide".
API:
- ZRTP_STATE_ERROR was added to handle error requests. Libzrtp switches
to this state after the Error exchange. From ZRTP_STATE_ERROR stream
cxan be started again or destroyed, depending on application strategy.
- ZRTP_ERRORACK and ZRTP_ERROR packets were added
- new event ZRTP_ENEVT_NO_ZRTP inform's user that other side doesn't
support ZRTP encryption.
7. -D WITH_STACK_MINIM compilation flag allows to minimize coasts for the
system stack. In the most critical places dynamic allocation will be used
instead of static variables. This option can be useful on mobile platforms
in kernel mode, etc.
8. Several bug fixes in scheduler. Improved built-in realization of Symbian
platform. If you use our default realization on Symbian - please update.
9. David A. McGrew's srtp was replaced with our own. We did it to get control
over all crypto functions, generalize interface of crypto component. It
allows us to port libsrtp to any platforms more smoothly. We have one
configuration file, all platform-dependent function and definitions are
concentrated at one place. We eliminated superfluous functionality from
libsrtp, made it crossplatform and thread-safe. In SRTP engine we use our
own crypto-components based on by Dr. Brian Gladman's sources. Each component
has strong self-test function allows it to be tested on any platform and
in any environment.
- project structure was changed;
- bgaes folder includes AES and SHA routines by Dr. Brian Gladman. For details
see dgaes/howto and bg2zrtp.h files;
- libzrtp supports external realizations of SRTP (Use zrtp_srtp.h API and flag
-D WITHOUT_BUILTIN_SRTP );
10. Header files were refactored: one can add just single zrtp.h include to use
any libzrtp function or data type;
11. Solved problem with deadlock during Video conferences. (One side starts
negotioation with Video and another one with Audio stream)
12. Some changes in test-unite:
- test vectores and test-cases for all cryptio components are available;
- zrtp_system_test.h checks environment and compilation flags
- use ZRTP_ENABLE_TEST flag to build library with all tests
13. Full documentation review and updating.
14. Sources clean up and some refactoring;
15. Fixing in "break the tie" logic. See diagrams and zrtp_preparse_commit(),
zrtp_preparse_init_commit();
16. Some changes according to the lates ZRTP specification:
- sasvalue was trancated to 32 bits and used mostleft parts of the hashvalue.
17. Small bug fixes (zrtp_can_start_dh and zrtp_can_start_preshared() mixed into
zrtp_can_start_stream);
18. New key derivation mechanism according to NIST standarts. See ZRTP Draft
5.4.4 and 5.5.4.
libzrtp (0.3.7)
--------------------------------------------------------------------------------
1. New, more clear and useful test-unite
2. Eliminated zrtp_stop_protocol(). Now zrtp_done_session_ctx() includes
protocol stopping.
3. Some simplifications in project structure: removed zrtp_inet.h and bnase32.h,
zrtp_iface.c was removed to src\iface folder;
4. ZSTR_GET_VALUE should be used to convert zrtp_stringxx_t to zrtp_stringn_t;
5. Some changes for windows CE;
6. Changed default options: SAS base256 enabled by defauld and "staysecure" is on.
libzrtp (0.3.6)
--------------------------------------------------------------------------------
FIXES:
a) CRC now covers the whole ZRTP packet, not just a body
b) improved names of some crypto-components in HELLO/COMMIT packets
c) improved messages hash: hash function covers all ZRTP message with
magic number and length fields;
d) fixed DHPart1 and DHPart2 packets format according to last version
of ZRTP Internet draft.
e) fixed retain secrets sorting algorithm according to the last version
of the internet draft.
1. Windows CE support. Now library is fully compatible with Windows CE.
- .\libzrtp\projects\libzrtp_wince_vc8.sln project file for MS VS 2005
- .\libzrtp\test\WinCE contains sources of simple test-unite ( We have
just started working in this direction and more intelligent test unite
will be available soon. Tested on HTC S620 with Windows CE 2005 )
2. Added previous state field to ZRTP stream structure. It can be used to
analyze conditions of switching from one state to another. (For libzrtp
developers only)
API:
- zrtp_stream_ctx_t#_prev_state was added
- _zrtp_change_state() MUST be used to switch from one state to another
3. Some changes in PENDING_CLEAR state handler. In case of error during
transition from CLEAR to SECURE state-machine will switch back to CLEAR
without the confirmation by user.
libzrtp (0.3.5)
--------------------------------------------------------------------------------
Full description is in progress
1. Support of all crypto futures according to the new ZRTP draft v 0.3. Lots
of internal changes were provided in ZRTP kernel.
2. Symbian support. Now you can build libzrtp and test unites on Symbian
platforms. There are .inf and .mmp files in corresponded directories.
(Symbian project files are a little bit row and we will appreciate any
suggestions and advices.)
3. ZRTP stream became more independent. You can use different configurations
for different streams. So
ZRTP profile: profile;
"staysecure" flag: staysecure;
SAS values: sas_values;
cache TTL: cache_ttl;
and all used crypto components were removed from session context
(zrtp_conn_ctx_t) to stream context (zrtp_stream_ctx_t).
API:
- you should configure every stream in the same way as the whole session in
previous version has been done. See zrtp_init_session_ctx()
and zrtp_attach_stream()
4. "Multistream" mode was replaced by "Preshared" (based on retain secrets
from previous call. See http://zfoneproject.com/docs/ietf/draft-zimmermann-avt-zrtp-03.html#anchor19 .
Preshared mode is available as a normal ZRTP crypto component e.g."DH3K"
or "DH4K". If you enable Preshared mode in profile and libzrtp finds
secrets in your cache - "Preshared" mode will be used for all next calls
API:
- the choice of stream mode was removed from zrtp_start_stream() and
from zrtp_secure_stream().
5. Integer enumerations for all crypto components e.g. Hash type, cipher type
etc. You should use these values instead of character values for optional
profile configuration. (as an example for enabling "preshared" mode)
API:
- enumerations types zrtp_hash_id, zrtp_cipher_idzrtp_atl_id,
zrtp_pktype_id, zrtp_sas_id in zrtp_crypto.h
- all crypto components structures now have id field and libzrtp
operates with this field to find, register or delete crypto
components.
- ZRTP profile: zrtp_profile_t uses this integer values too. (list of
crypto-components is a zero terminated array of values of necessary
type)
- zrtp_find_in_profile() and zrtp_find_comp() operate with component
integer identifiers
- there are two special functions to convert component ID to ZRTP
character name: zrtp_comp_id2type(), zrtp_comp_type2id.
6. Integer error codes were provided instead of 4-character values. One should
use them to analyze zrtp_stream_ctx_t#last_error value in your ZRTP
errors handlers.
API:
- zrtp_protocol_error_t was added to zrtp_error.h.
- zrtp_stream_ctx_t#last_error now is an integer value from
zrtp_protocol_error_t space.
7. Special function for verification of SAS value was added. One should use
this function to set/unset SAS verification flag from his own
application.
API:
- zrtp_set_verified() was added to zrtp.h
8. Some optimization of types was provided. Here are some possible changes which you
need to make in your product:
- libzrtp uses it own strings (zrtp_stringXX_t group) to operate with
binary and character strings. In this version we made attempt to
minimize memory coasts and replaced zrtp_string_t with zrtp_stringXX_t
group, where XX - maximum length in bytes. zrtp_stringxx_t contains
its length and as a result all functions for work with strings are
type independent. So one should use one of these types to store binary
strings and zrtp_stringn_t as a type of operand in all global functions.
- all retain secrets holders and flags were removed to zrtp_secrets
structure in zrtp_conn_ctx_t#secrets.
- zrtp_packet_string4_t was replaced by zrtp_ucharXX_t group where XX -
type length in bytes. These types are used in library for packets
construction instead of char arrays.
9. Packets retries synchronization was added. zrtp_retry_task_t structure
from zrtp_types_t is used for all operations with scheduler. One should
use #callback and #timeout fields from this structure.
API:
- zrtp_send_packet_later(), zrtp_cancel_send_packet_later()
libzrtp (0.3.4)
--------------------------------------------------------------------------------
1. ZRTP state-macine was fully refactored. All transitions between states
are absolutely identical to diagram attached to documentation.
DOC:
- See doc/img/png/state_mach_ext.png
2. ZRTP uses new packets format according to draft-zimmermann-avt-zrtp-03i
3. Improved some mistakes in libbn make-files for windows. Unused
functions were omitted.
4. Provided types optimization to decrease RAM memory costs.
5. Packets retries were synchronized.
6. zrtp_voip_proto_t was removed from the library
API:
- if you need this enumeration see zfone_types.h in zfone project
7. "GoClear reasons" support
8. Some internal changes according to draft-zimmermann-avt-zrtp-03i
a) Commit hash covers the whole Hello body
b) GoClear hmac includes "Reason string"
c) Confirm body encrypted by AES CDB cipher
d) Confirm hmac covers whole encrypted part of the packet
9. Use BUILD_ZRTP_DEBUG_LOG flag instead of BUILD_DEBUG_LOG to build the
library with debug logs.
libzrtp (0.3.3) 21.02.2007
--------------------------------------------------------------------------------
1. libzrtp test application refactored for better performance and usability.
For addition information see test application README file and
"libzrtp test suite" chapter in main documentation page.
2. Some changes in documentation for better English
3. Use microseconds in zrtp_time_t instead of milliseconds.
API changes:
- change zrtp_get_time() function realization if needed
4. Fixed several small mistakes
libzrtp (0.3.2) 09.02.2007
--------------------------------------------------------------------------------
1. Global context allocation removed to user space.
This was made to able RNG using before library initialization.
API changes:
- zrtp_init(), zrtp_down()
- zrtp_randstr(), zrtp_add_system_state()
2. Fixed bug in srtp SHA1 calculation for Windows.
3. Confirm and GoClear HMAC was truncated to 64 bits.
4. Calls stack minimized for library using in kernel mode
5. Default realization of secrets' cache is available. Cache was implemented
as a simple binary file and can be built using -DBUILD_DEFAULT_CACHE file.
API:
- realization at src\iface\zrtp_cache.c
DOC:
- 1.4 libZRTP setup and building
- 2.2 System-dependent functions
6. Default cross-platform realization of time-out sending unite is available.
This unite is available for Linux, MacOS and Windows. It can be built using
-DBUILD_DEFAULT_TIMER flag.
API:
- realization at src\iface\zrtp_scheduler.c
DOC:
- 1.4 libZRTP setup and building
- 2.2 System-dependent functions
7. "HOWTO libzrtp" was added to the library documentation
libzrtp (0.3.1) 06.12.2006
--------------------------------------------------------------------------------
1. Global variables were removed from c-files. Added global context
zrtp_global_ctx_t for necessary data storing. This was made to allow
to build library in some special environment as Symbian OS ed2.
DOC changes:
- 2.1.2 data structure
API changes:
- zrtp_global_ctx_t added
- zrtp_init(), zrtp_down(), zrtp_init_session(), zrtp_down_session()
2. Added multithreading support. Now libzrtp is thread-safe. About all
conditions of usage in multithreading application and synchronization
schemes see section "2.3.3 Multithreading and concurrent streams" in
developers guide.
DOC changes:
- 2.2.3 Multithreading and concurrent streams
API changes:
- mutex were added to main data structures
- mutex interface section at zrtp_iface.c, default realization at
zrtp_iface.c
3. Session configuration routine was simplified. ZRTP profile is applied on
session initialization. Some configuration functions were removed and
changed.
DOC changes:
- 2.3.1 Setup, initialization and deinitialization
API:
- zrtp_profile_autoload() removed
- zrtp_init_session(), zrtp_check_profile()
4. Default realizations of system interfaces was added (for Windows, Linux
and MacOS).
API:
- zrtp_iface.c added
5. Test suit developed.
Simple test-unite created. It runs several ZRTP sessions, enters SECURE
mode, shows statistics and is closed. To build test-suite on Unix - use C
flags -DBUILD_DEBUG_LOG -DBUILD_WITH_CFUNC -DBUILD_EMPTY_CACHE
-DBUILD_EMPTY_TIMER and configure param. --enable-test. To run tests:
make check. To build test-suite on Windows use necessary project files.
DOC changes:
- 1.4 libZRTP setup and building
API:
- Sources can be found at /test directory
6. Some changes in project structure, configuration and make files according
to new functionality.
DOC changes:
- 1.4 libZRTP setup and building

10
libs/libzrtp/README Normal file
View File

@ -0,0 +1,10 @@
#
# libZRTP SDK library, implements the ZRTP secure VoIP protocol.
# Copyright (c) 2006-2009 Philip R. Zimmermann. All rights reserved.
# Contact: http://philzimmermann.com
# For licensing and other legal details, see the file zrtp_legal.c.
#
- Check HTML Documentation ./doc
- Visit the Zfone Project Home Page http://zfoneproject.com/
- Report bugs via the Zfone Bugs Page http://zfoneproject.com/bugs.html

1553
libs/libzrtp/doc/Doxyfile Normal file
View File

File diff suppressed because it is too large Load Diff

451
libs/libzrtp/doc/doxygen.css Normal file
View File

@ -0,0 +1,451 @@
BODY,H1,H2,H3,H4,H5,H6,P,CENTER,TD,TH,UL,DL,DIV {
font-family: Geneva, Arial, Helvetica, sans-serif;
}
BODY,TD {
font-size: 100%;
}
CODE {
font-size: 120%;
font-family: monospace;
}
.fragment, pre {
font-size: 110%;
font-family: monospace;
}
H1 {
text-align: center;
font-size: 240%;
}
H2 {
font-size: 180%;
margin-top: 60px;
}
H3 {
font-size: 140%;
}
H4 {
font-size: 120%;
}
caption {
font-weight: bold;
}
div.qindex, div.navtab{
background-color: #e8eef2;
border: 1px solid #84b0c7;
text-align: center;
margin: 2px;
padding: 2px;
}
div.qindex, div.navpath {
width: 100%;
line-height: 140%;
}
div.navtab {
margin-right: 15px;
}
/* @group Link Styling */
a {
color: #153788;
font-weight: normal;
text-decoration: none;
}
.contents a:visited {
color: #1b77c5;
}
a:hover {
text-decoration: underline;
}
a.qindex {
font-weight: bold;
}
a.qindexHL {
font-weight: bold;
background-color: #6666cc;
color: #ffffff;
border: 1px double #9295C2;
}
.contents a.qindexHL:visited {
color: #ffffff;
}
a.el {
font-weight: bold;
}
a.elRef {
}
a.code {
}
a.codeRef {
}
/* @end */
dl.el {
margin-left: -1cm;
}
.fragment {
font-family: monospace, fixed;
font-size: 105%;
}
pre.fragment {
border: 1px solid #CCCCCC;
background-color: #f5f5f5;
padding: 4px 6px;
margin: 4px 8px 4px 2px;
}
div.ah {
background-color: black;
font-weight: bold;
color: #ffffff;
margin-bottom: 3px;
margin-top: 3px
}
div.groupHeader {
margin-left: 16px;
margin-top: 12px;
margin-bottom: 6px;
font-weight: bold;
}
div.groupText {
margin-left: 16px;
font-style: italic;
}
body {
background: white;
color: black;
margin-right: 20px;
margin-left: 20px;
}
td.indexkey {
background-color: #e8eef2;
font-weight: bold;
border: 1px solid #CCCCCC;
margin: 2px 0px 2px 0;
padding: 2px 10px;
}
td.indexvalue {
background-color: #e8eef2;
border: 1px solid #CCCCCC;
padding: 2px 10px;
margin: 2px 0px;
}
tr.memlist {
background-color: #f0f0f0;
}
p.formulaDsp {
text-align: center;
}
img.formulaDsp {
}
img.formulaInl {
vertical-align: middle;
}
/* @group Code Colorization */
span.keyword {
color: #008000
}
span.keywordtype {
color: #604020
}
span.keywordflow {
color: #e08000
}
span.comment {
color: #800000
}
span.preprocessor {
color: #806020
}
span.stringliteral {
color: #002080
}
span.charliteral {
color: #008080
}
span.vhdldigit {
color: #ff00ff
}
span.vhdlchar {
color: #000000
}
span.vhdlkeyword {
color: #700070
}
span.vhdllogic {
color: #ff0000
}
/* @end */
.search {
color: #003399;
font-weight: bold;
}
form.search {
margin-bottom: 0px;
margin-top: 0px;
}
input.search {
font-size: 75%;
color: #000080;
font-weight: normal;
background-color: #e8eef2;
}
td.tiny {
font-size: 75%;
}
.dirtab {
padding: 4px;
border-collapse: collapse;
border: 1px solid #84b0c7;
}
th.dirtab {
background: #e8eef2;
font-weight: bold;
}
hr {
height: 0;
border: none;
border-top: 1px solid #666;
}
/* @group Member Descriptions */
.mdescLeft, .mdescRight,
.memItemLeft, .memItemRight,
.memTemplItemLeft, .memTemplItemRight, .memTemplParams {
background-color: #FAFAFA;
border: none;
margin: 4px;
padding: 1px 0 0 8px;
}
.mdescLeft, .mdescRight {
padding: 0px 8px 4px 8px;
color: #555;
}
.memItemLeft, .memItemRight, .memTemplParams {
border-top: 1px solid #ccc;
}
.memTemplParams {
color: #606060;
}
/* @end */
/* @group Member Details */
/* Styles for detailed member documentation */
.memtemplate {
font-size: 80%;
color: #606060;
font-weight: normal;
margin-left: 3px;
}
.memnav {
background-color: #e8eef2;
border: 1px solid #84b0c7;
text-align: center;
margin: 2px;
margin-right: 15px;
padding: 2px;
}
.memitem {
padding: 0;
}
.memname {
white-space: nowrap;
font-weight: bold;
}
.memproto, .memdoc {
border: 1px solid #84b0c7;
}
.memproto {
padding: 0;
background-color: #d5e1e8;
font-weight: bold;
-webkit-border-top-left-radius: 8px;
-webkit-border-top-right-radius: 8px;
-moz-border-radius-topleft: 8px;
-moz-border-radius-topright: 8px;
}
.memdoc {
padding: 2px 5px;
background-color: #eef3f5;
border-top-width: 0;
-webkit-border-bottom-left-radius: 8px;
-webkit-border-bottom-right-radius: 8px;
-moz-border-radius-bottomleft: 8px;
-moz-border-radius-bottomright: 8px;
}
.paramkey {
text-align: right;
}
.paramtype {
white-space: nowrap;
}
.paramname {
color: #602020;
white-space: nowrap;
}
.paramname em {
font-style: normal;
}
/* @end */
/* @group Directory (tree) */
/* for the tree view */
.ftvtree {
font-family: sans-serif;
margin: 0.5em;
}
/* these are for tree view when used as main index */
.directory {
font-size: 9pt;
font-weight: bold;
}
.directory h3 {
margin: 0px;
margin-top: 1em;
font-size: 11pt;
}
/*
The following two styles can be used to replace the root node title
with an image of your choice. Simply uncomment the next two styles,
specify the name of your image and be sure to set 'height' to the
proper pixel height of your image.
*/
/*
.directory h3.swap {
height: 61px;
background-repeat: no-repeat;
background-image: url("yourimage.gif");
}
.directory h3.swap span {
display: none;
}
*/
.directory > h3 {
margin-top: 0;
}
.directory p {
margin: 0px;
white-space: nowrap;
}
.directory div {
display: none;
margin: 0px;
}
.directory img {
vertical-align: -30%;
}
/* these are for tree view when not used as main index */
.directory-alt {
font-size: 100%;
font-weight: bold;
}
.directory-alt h3 {
margin: 0px;
margin-top: 1em;
font-size: 11pt;
}
.directory-alt > h3 {
margin-top: 0;
}
.directory-alt p {
margin: 0px;
white-space: nowrap;
}
.directory-alt div {
display: none;
margin: 0px;
}
.directory-alt img {
vertical-align: -30%;
}
/* @end */
address {
font-style: normal;
color: #333;
}

4
libs/libzrtp/doc/footer.html Normal file
View File

@ -0,0 +1,4 @@
<hr size="1"><address style="text-align: right;"><small>
Generated on $datetime for $projectname &nbsp;<a href="http://www.zfoneproject.com"><img src="zfone.jpg" alt="zfone" align="middle" border="0"></a> </small></address>
</body>
</html>

6
libs/libzrtp/doc/header.html Normal file
View File

@ -0,0 +1,6 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>$title</title>
<link href="$relpath$tabs.css" rel="stylesheet" type="text/css">
<link href="$relpath$doxygen.css" rel="stylesheet" type="text/css">
</head><body>

197
libs/libzrtp/doc/manuals/changelog.dox Normal file
View File

@ -0,0 +1,197 @@
#
# Copyright (c) 2006-2009 Philip R. Zimmermann. All rights reserved.
# Contact: http://philzimmermann.com
# For licensing and other legal details, see the file zrtp_legal.c.
#
# Viktor Krykun <v.krikun at zfoneproject.com>
/**
* \file changelog.dox
* \brief libzrtp ChangeLog
*/
/*!
\page changelog libzrtp ChangeLog
****************************************************************************************************
\section v091 DEVELOPERS BUILD Release Notes - libzrtp - Version 0.91 build XXX (ZRTP ID v16x, protocol 1.X)
****************************************************************************************************
\note To build Libzrtp Enterprise with Elliptic Cure Diffie-Hellman support on Unix platform, use
<c>"./configure --enable-enterprise".</c> By default libzrtp will be build with no ECDH support.
<HR>
***\subsection v091_feature New features and improvements.
***\subsection v091_bugs Bug fixes
*- [LZRTP-179] Fixed bug in build scripts when commercial version of libzrtp v0.90 was built
with ZRTP_ENABLE_EC set to 1 by default.
*- [LZRTP-181] Fixed zrtp_init() crash on Mac OSX 10.6
*- [LZRTP-182] Fixed libzrtp build issue on Free-BSD
****************************************************************************************************
\section v090 Release Notes - libzrtp - Version 0.90 build 577 (ZRTP ID v15x, protocol 1.1)
****************************************************************************************************
<HR>
***\subsection v090_feature New features and improvements.
*- [LZRTP-178] After the cache mismatch don't update the cache automatically, wait for the SAS verification. More details at this feature could be found in ZRTP ID section 4.6.1.1
*- [LZRTP-151] Add secrets flags to \ref zrtp_info_t to allow user monitor secrets state
*- [LZRTP-169] Check and optimize build process on Windows mingw and msys.
***\subsection v090_bugs Bug fixes
*- [LZRTP-176] Added -fPIC flag to Linux and Mac builds to be able to link the library into 64bit applications.
*- [LZRTP-175] Change SHA1 definition name to SRTP_SHA1 and move to private part of the API to eliminate ambiguity.
*- [LZRTP-155] Session info should display current, updated value of the TTL, not the old one from previous negotiation.
*- [LZRTP-177] Diffie-Hellman secret exponent for DH2K should be 256bits instead of 128.
****************************************************************************************************
\section v082 Release Notes - libzrtp - Version 0.82 build 540 (ZRTP ID v15, protocol 1.1)
****************************************************************************************************
<HR>
Minor improvements. Zfone and libZRTP projects moved to public bug-tracking and wiki system.
***\subsection v082_feature New features and improvements.
*- Improved libzrtp resistance to long delays during DH calculations on slow hardware.
*- Structures Members alignment in Microsoft Visual Studio projects was changed from 1 byte to "Default".
*- Implemented entropy collection from dropped RTP messages. Don't forget to store RNG seed when you done with libzrtp and upload it agan on next session.
*- Implement default entropy collector for Win32 platform. RtlGenRandom() system call is used. Together with the entropy collection from dropped RTP message, it should guaranty good enough entropy.
*- zrtp_def_cache_reset_since() was implemented as call-back, similar to the rest of ZRTP cache interfaces.
*- Eliminated secure logs from the public build.
*- Public bug-tracker and wiki launched (in addition to our internal tools)
*- libzrtp API documentation is available at developers.zfoneproject.com
****************************************************************************************************
\section v081 Release Notes - libzrtp - Version 0.81 build 514 (ZRTP ID v15, protocol 1.1)
****************************************************************************************************
<HR>
***\subsection v081_bugs Bug
*- [LZRTP-161] <b>Improvement in ZRTP state-machine</b>\n
libzrtp state-machine didn't process incoming Hello message in StartInitiatingSecure state.
In some situations this issue could cause libzrtp not responding on incoming HELLO messages and freeze the protocol.
*- [LZRTP-166] <b>Fixed "Secure Since" logic.</b>\n
Previous version of libzrtp computed secure since in a wrong way. libzrtp 0.81 remembers secure since date when new RS1 secret is generated and keep it unchanged while RS secrets are matched for all next calls.
\n
Use zrtp_def_cache_get_since() to get secure since for the particular pair of ZIDs.
\warning Secure since function is available for the build-in implementation of ZRTP cache.
***\subsection v081_feature New Feature
*- [LZRTP-157] <b>Implement algorithms negotiation according to ZRTP ID v15 section 4.1.2</b>\n
This method is provided to allow the two parties to mutually and deterministically choose the same DH key size and algorithm before a Commit message is sent. No API changes required.
*- [LZRTP-158] <b>Zfone Ping response implemented.</b>\n
New Zfone3 software uses specific VoIp calls detection algorithms and uses ZRTP Ping to discover the call topology. Each ZRTP endpoint may response with PingAck to be compatible with Zfone3. libzrtp based products don't need to do anything more to support Zfone3. The library handles this automatically. Ping-Response doesn't affect res of ZRTP logic.
\n
\sa Check ZRTP RFC sec 5.16 for more information.
***\subsection v081_improv Improvement
*- [LZRTP-164] <b>New ZRTP security event was added.</b>\n
Libzrtp rises special event when after switching to secure state, the secrets are not expired, cached, but don't match. In other words: it is typical condition for the MitM attacks. Developer should use this event to notify user about the situation. Check zrtp_security_event_t#ZRTP_EVENT_MITM_WARNING for more detail information.
*- [LZRTP-153] <b>New Project files to build libzrtp on Windows CE.</b>\n
Check ./projects/win_ce directory to find appropriate Microsoft Visual Studio projects.
****************************************************************************************************
\section v080 Release Notes - libzrtp - Version 0.80
****************************************************************************************************
<HR>
***\subsection v080_bugs Bug
- [LZRTP-97] <b>zrtp_hex2str and zrtp_st2hex don't work correct.</b>\n
Fixed bug in str2hex() providing wrong converting. Previous versions of libzrtp were affect,
but str2hex wasn't used in crypto logic and there was no security weakness.
- [LZRTP-154] zrtp_register_with_trusted_mitm() on storing MiTM secret didn't set the "matches" flag for ZRTP_BIT_PBX. In result, zrtp_is_user_enrolled() returned false right after ZRTP_STATE_SECURE event. This issue affected ZRTP MitM endpoints only and for the very first enrollment stream with the endpoint. In all next calls with the endpoint zrtp_is_user_enrolled() worked correct.
***\subsection v080_improv Improvement
*- [LZRTP-26] <b>Refactoring in the test-unite</b>\n
Test-unite was redesigned: platform independent test-core and UI parts, specific for every
target platform. test-core has cleaner API and internal structure. UI part allow to simplify
application and separate business logic from UI routine.
*- [LZRTP-46] <b>Change zrtp_time_t to literal integer type.</b>\n
zrtp_tim_now() just returns current time in milliseconds instead of zrtp_time_t structure.
*- [LZRTP-83] <b>Refactoring in libzrtp debug logging.</b>\n
Made logs easy to read and analyze. Used indention.
*- [LZRTP-84] <b>Refactoring in libzrtp terms.</b>\n
Following changes in functions names and data structures were made:
zrtp_stream_ctx_t - zrtp_stream_t\n
zrtp_conn_ctx_t - zrtp_session_t\n
zrtp_global_ctx_t - zrtp_global_t\n
(in zrtp.h more explicitly reflect meaning of data types)\n
\n
ZSTR_GET_VALUE/P - ZRTP_GV/P\n
SET_EMPTY_ZRTP_STRING - ZSTR_SET_EMPTY\n
(in zrtp_string.h just cleaner and shorter names)\n
\n
zrtp_init() (Allocates memory)\n
zrtp_init_session_ctx() - zrtp_session_init(). (Allocates memory)\n
zrtp_add_entropy() - zrtp_entropy_add() \n
zrtp_secure_stream() - zrtp_stream_secure()\n
zrtp_clear_stream() - zrtp_stream_clear()\n
zrtp_done_session_ctx - zrtp_session_down()\n
zrtp_attach_stream - zrtp_stream_attach()\n
zrtp_start_stream() - zrtp_stream_start()\n
zrtp_stop_stream() - zrtp_stream_stop()\n
zrtp_set_verified - zrtp_verified_set()\n
zrtp_check_profile - zrtp_profile_check()\n
(in zrtp.h used following approach: zrtp prefix; module name; action name)
*- [LZRTP-85] <b>Hide private fields in zrtp_session_ctx and zrtp_stream_ctx.</b>\n
zrtp_stream_t and zrtp_session_t structures were hidden inside libzrtp internal data-types. General libzrtp-based application shouldn't use these structures directly. zrtp_stream_info_t and zrtp_session_info_t structures should be used instead. To implement data encapsulation, libzrtp provides following functions:
zrtp_stream_get(), zrtp_session_get()\n
zrtp_stream_set_userdata(), zrtp_stream_get_userdata()\n
zrtp_session_set_userdata(), zrtp_session_get_userdata()\n
\n
Advanced zrtp products may access zrtp_stream_t and zrtp_session_t directly but implementer can avoid this in most of the cases.
*- [LZRTP-88] <b>Create a macro for UNALIGNED constructions on mobile platforms.</b>\n
*- [LZRTP-89] <b>Code style for crypto components sources.</b>\n
Public API not affected. Internal changes:
- more compact code because fo using more general crypto functions
- code stayle and comments
- test-vectors were moved inside c-files fof appropriate crypto components.
*- [LZRTP-99] <b>zrtp_session_init should allocate memory for zrtp_session_t.</b>\n
*- [LZRTP-112] <b>Modify zrtp logger to be able write \\n and NON \\n logs.</b>\n
ZRTP_LOG by default doesn't add \\n at the end of the log string. ZRTP_LOGC print plain log message without header and any formatting.
*- [LZRTP-116] <b>Review synchronization objects in libzrtp.</b>\n
- zrtp_global_t#comp_protector was removed. This mutex protected crypto components list. Since v0.80 libzrtp doesn't allow users to manage list of crypto components. libzrtp loads all available components at zrtp_init() and destroys them on zrtp_down(). Any modification with the list performed between these two call - don't need mutex.
- zrtp_secrets_t#protector was removed, just unused in the code
- zrtp_global_t#cache_protector was removed. Third-party ZRTP cache implementation should be thread-safe. It was made because it is simpler and more flexible solution.
*- [LZRTP-120] <b>Add file with version number to identify builds.</b>\n
zrtp_version.h have been added to the project.
*- [LZRTP-128] <b>Eliminate Sound event from libzrtp.</b>\n
zrtp_callback_misc_t::on_sound_event() was eliminated. This message was originally deigned for early versions of ZFone project. Event is supernumerary and duplicated other protocol and security events. Users, who need such event may perform the same actions using zrtp_callback_event_t events.
*- [LZRTP-133] <b>Move ssrc parameter from stream_create() to stream_start()</b>\n
SSRC parameter was moved from zrtp_stream_attach() to zrtp_stream_start(). Such improvement should allow users to create zrtp streams before media starts and ssrc is unknown. It may be useful for proxy products: ZFone, UM-Lab software and other.
*- [LZRTP-143] <b>Speedup DH key exchange procedure.</b>\n
DH crypto context data was moved directly to zrtp_stream_t and statically allocated. On creating protocol routine, libzrtp checks is DH context have been already initialized with the same type of key exchange scheme. If so - new DH value will not be recalculated.
***\subsection v080_feature New Feature
- [LZRTP-14] <b>Add DH2K public key exchange scheme</b>\n
DH2K public key exchange scheme was implemented and available for developers the same way as rest of crypto components.
***\subsection v080_tasks Task
*- [LZRTP-24] <b>Implement Self-tests for DH and ECDH components.</b>\n
Test cases for DH components were implemented and added to the libzrtp test-unite routine. DH checks algorithm correctness and performance as well. Besides test-vectors, it emulates DH exchange computing public and secret values for both endpoints.
*- [LZRTP-122] <b>Print out all zrtp configuration settings and adjustments on initialization.</b>
*- [LZRTP-123] <b>Create standard error codes and error text descriptions.</b>\n
New functions zrtp_log_error2str() and zrtp_log_status2str() were added to convert status codes to text description. Some clean-up in zrtp_status_t was made, removed unused or ambiguous status codes.
*- [LZRTP-132] <b>Replace HMAC with KDF function call.</b>\n
Since ZRTP draft 12b defines ZRTP KDF to be in compliance with the recommendations in NIST SP 800-108. KDF function implemented as _zrtp_kdf() in zrtp_utils_proto.c. All KDF operations were replaced with from hmac to kdf function.
*/

489
libs/libzrtp/doc/manuals/howto.dox Normal file
View File

@ -0,0 +1,489 @@
#
# Copyright (c) 2006-2009 Philip R. Zimmermann. All rights reserved.
# Contact: http://philzimmermann.com
# For licensing and other legal details, see the file zrtp_legal.c.
#
# Viktor Krykun <v.krikun at zfoneproject.com>
/**
* \file howto.dox
* \brief How to Get Up and Running Quickly with libZRTP
*/
/**
\page howto How to Get Up and Running Quickly with libZRTP
****************************************************************************************************
\section howto_about 1. About
****************************************************************************************************
<HR>
The libzrtp library is a cross-platform implementation of ZRTP, a VoIP encryption protocol developed by Phil Zimmermann. libzrtp is suitable for inclusion in software VoIP clients, firmware for hardware VoIP phones, VoIP PBX servers, mobile VoIP clients, and SIP border control servers, enabling a VoIP application to interoperate and make secure calls with the rest of the ZRTP
community.
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.
****************************************************************************************************
\section howto_quick 2. Quick Info
****************************************************************************************************
<HR>
***<H3>Building with GNU tools (Linux, *BSD, MacOS X, mingw, etc.)</H3>
Generally these should be all that are needed to build the libraries, applications, and samples:
-# go to ./projects/gnu and run
\code
$ ./configure
$ make clean && make
\endcode
**<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.
****************************************************************************************************
\section howto_getting_source 3. Getting the Source Distribution
****************************************************************************************************
<HR>
***\subsection howto_getting_source_tar 3.1 Getting the Release tarball
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
***\subsection howto_getting_source_svn 3.2 Getting from Subversion trunk
At the moment, SVN repository is available for libzrtp developers only. It will be opened for public soon.
***\subsection howto_getting_source_layout 3.3 Source Directories Layout
The top-level directories (denoted as $TOP here) in the source distribution contains the following sub-directories:
\c $TOP/doc - documentation folder;
\c $TOP/include - header files:
- \c zrtp_config_user.h - user defined ZRTP configuration options;
- \c zrtp_config_win.h - Windows related configuration options;
- \c zrtp_config.h - libzrtp automatic configuration routine.
- \c 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;
- \c zrtp_engine.h - contains types and functions needed by the ZRTP state-machine For
internal use only;
- \c zrtp_error.h - contains error codes returned by the libzrtp functions;
- \c zrtp_iface_system.h - contains a set of OS-related interface functions which must be
implemented in order to use the library;
- \c zrtp_iface.h - contains a set of ZRTP utility interface functions which must be
implemented in order to use the library;
- \c zrtp_legal.h - libzrtp license agreement;
- \c 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;
- \c zrtp_log.h - contains functions to track bugs and store the error log.;
- \c zrtp_pbx.h - conatins declarations of the main PBX related functions. Use this header if you are the implementor of some VoIP-server solutions;
- \c zrtp_srtp.h - SRTP crypto types and interfaces. Used to integrate libzrtp with third
party SRTP implementations;
- \c zrtp_srtp_builtin.h - data structures for built-in realization of SRTP.
- \c zrtp_string.h - contains functions for the use of the special, safe strings,
zrtp_stringn_t, used by libzrtp.
- \c zrtp_types.h - contains the definitions of the internal data types which are used by
libzrtp developers and experienced users.
- \c 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;
\c $TOP/projects
- \c gnu - make files for Unix-like systems using autotools;
- \c symbian - configuration and make files for Symbian platform;
- \c win - Set of Microsoft Visual Studio project files for Windows and Windows CE.
- \c win_kernel - makefiles for Windows Kernel mode.
- \c xcode - project files for Apple Xcode.
\c $TOP/src - libzrtp source files;\n
\c $TOP/test - test suite for libZRTP kernel logic. Includes versions for Unix, Windows,
Windows CE and Symbian.
\c $TOP/third_party
- \c bnlib - libbn files which are not intended for external use;
- \c bgaes - AES encryption library and hash functions by Brian Gladman;
****************************************************************************************************
\section howto_praparations 4. Build Preparation
****************************************************************************************************
<HR>
***\subsection howto_praparations_config 4.1 zrtp_cinfig_user.h
Before building libzrtp, some adjustments may be performed according to developers needs. In order to do this, \c include/zrtp_cinfig_user.h should be used. Most of configuration parameters are optional and libzrtp can be build without any modifications.
Check \ref zrtp_config for more information.
***\subsection howto_praparations_iface 4.2 libzrtp platform-dependent interfaces
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:
- zrtp_callback_event_t#on_zrtp_secure - notify user about switching to secure;
- zrtp_callback_event_t#on_zrtp_not_secure - notify about ZRTP security issues.
Another callback which must be implemented - transport routine:
- zrtp_callback_misc_t#on_send_packet - libzrtp uses this function to deliver ZRTP protocol message to the remote party.
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 \ref XXX.
****************************************************************************************************
\section howto_unix 5. Building Linux, *nix, *BSD, and MacOS X Targets with GNU Build Systems
****************************************************************************************************
<HR>
***\subsection howto_unix_targets Supported Targets
The new, autoconf based GNU build system can be used to build the libraries/applications for the following targets:
- Linux (i386, Opteron, Itanium, MIPS, PowerPC, etc.),
- MacOS X (Intel, PowerPC),
- mingw (i386),
- FreeBSD (i386, Opteron, etc.),
- etc.
***\subsection howto_unix_requir 5.1 Requirements
In order to use libzrtp's GNU build system, these typical GNU tools are needed:
- GNU make,
- GNU binutils for the target, and
- GNU gcc for the target.
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:
- Linux, many types of distributions.
- MacOS X 10.4 and higher
***\subsection howto_unix_build 5.2 Running configure and make
Run "./configure" without any options to let the script detect the appropriate settings for the host:
\code
$ cd libzrtp
$ ./configure
...
\endcode
Once the configure script completes successfully, libzrtp is ready to be built. Use following commands:
\code
$ cd libzrtp
$ make clean
$ make
\endcode
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.
****************************************************************************************************
\section howto_osx 6. Building MacOS X Targets with Xcode
****************************************************************************************************
<HR>
***\subsection howto_osx_requir 6.1 Requirements
To build libzrtp on OS X using Xcode you need following:
- Mac OSX 10.4 or later.
- Apple developers Tools installed.
- Xcode 3.1 or higher.
***\subsection howto_osx_build 6.2 Building the Projects
Follow the steps below to build libzrtp using Apple Xcode:
-# For Apple Xcode: open \c projects/xcode/libzrtp.xcodeproj project file.
-# Set "libzrtp" or "libzrtp_ec" as Active Target.
-# Select Debug or Release build as appropriate.
-# Build "configure" target.
-# Build the project. This will build libzrtp with all dependencies.
-# After successful build, libzrtp will be placed in \c projects/xcode/build/Debug or Release.
Use \c projects/xcode/libzrtp_test.xcodeproj by analogy to build the test application.
****************************************************************************************************
\section howto_win 7. Building for Windows Targets with Microsoft Visual Studio
****************************************************************************************************
<HR>
***\subsection howto_win_requir 7.1 Requirements
The Microsoft Visual Studio based project files can be used with one of the following:
- Microsoft Visual C++ 2005 (including Express edition),
For the host platform, the following are required:
- Windows NT, 2000, XP, 2003, or later ,
- Sufficient amount of RAM for the build process (at least 256MB).
***\subsection howto_win_build 7.2 Building the Projects
Follow the steps below to build libzrtp using Visual Studio:
-# For Visual Studio 8 (VS 2005): open libzrtp_vs8.sln solution file.
-# Set "libzrtp" or "libzrtp_ec" as StartUp Project.
-# Select Debug or Release build as appropriate.
-# Build the project. This will build libzrtp and all dependencies.
-# After successful build, libzrtp will be placed in \c projects/win/Debug or Release.
To build libzrtp test-cases use "libzrtp_test" as StartUp Project and perform steps listed above.
****************************************************************************************************
\section howto_wince 8. Building for Windows Mobile Targets (Windows CE/WinCE/PDA/SmartPhone)
****************************************************************************************************
<HR>
***\subsection howto_wince_requir 8.1 Requirements
The Microsoft Visual Studio based project files can be used with one of the following:
- Microsoft Visual C++ 2005
For the host platform, the following are required:
- Windows NT, 2000, XP, 2003, or later ,
- Sufficient amount of RAM for the build process (at least 256MB).
***\subsection howto_wince_build 8.2 Building the Projects
Follow the steps below to build libzrtp using Visual Studio:
-# For Visual Studio 8 (VS 2005): open libzrtp_wince_vs8.sln solution file.
-# Set "libzrtp" or "libzrtp_ec" as StartUp Project.
-# Select Debug or Release build as appropriate.
-# Build the project. This will build libzrtp and all dependencies.
-# After successful build, libzrtp will be placed in \c projects/win/Debug or Release.
\note
The Test Application is not available for Windows Mobile platform at the moment. We will fix this in next version of libzrtp.
****************************************************************************************************
\section howto_symbian 9. Building for Symbian
****************************************************************************************************
<HR>
****************************************************************************************************
\section howto_using 10. Using libzrtp with Applications
****************************************************************************************************
<HR>
Regardless of the build system being used, the following tasks are normally needed to be done in order to build application to use libzrtp:
-# Add following include directories in the include search path:
- \c libzrtp/include
- \c libzrtp/include/enterprise (if you are using Enterprise version of libzrtp)
- \c libzrtp/third_party/bgaes
- \c libzrtp/third_party/bnlib
- \c libzrtp/projects/gnu/config (for GNU Autoconf targets)
-# Put these library directories in the library search path:
- \c libzrtp/third_party/bnlib
- \c libzrtp/projects/gnu/build (for GNU Autoconf targets)
- \c libzrtp/projects/xcode/build/Release (when building with Xcode)
- \c libzrtp/projects/win/Release (when building with Visual Studio)
-# Include \c libzrtp.h header file to the application.
-# Link with \c libzrtp and \c bnlib.
-# Link with system spesific libraries:
- Windows: Add (among other things): ws2_32.lib.
- Linux, *nix, *BSD: Add (among other things): '-lpthread'.
- MacOS X: Add (among other things): '-lpthread'.
****************************************************************************************************
\section howto_example 11. Quick Start Example
****************************************************************************************************
<HR>
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.
\code
typedef struct testcon_t
{
zrtp_session_t *zrtp_session; // ZRTP Session structure
zrtp_stream_t *zrtp_audio; // ZRTP stream for voice encryption
zrtp_stream__t *zrtp_video; // ZRTP stream for video encryption
} testcon_t;
testcon_t safe_connection; // Secure channel instance
zrtp_global_t zrtp_global; // Persistent storage for libzrtp data
\endcode
\code
zrtp_status_t s = zrtp_status_ok;
zrtp_config_t zrtp_config;
// Initialize zrtp config with default values
zrtp_config_defaults(&zrtp_config);
// Make some adjustments:
// - Set Client ID to identify ourself
// - Set appropriate license mode
// - We going to use default zrtp cache implementation, so let's specify cache file path
strcpy(zrtp_config.client_id, TEST_CLIENT_ID);
zrtp_config.lic_mode = ZRTP_LICENSE_MODE_ACTIVE;
zrtp_zstrcpyc( ZSTR_GV(zrtp_config.def_cache_path), TEST_CACHE_PATH);
// Define interface callback functions
zrtp_config.cb.misc_cb.on_send_packet = on_send_packet;
zrtp_config.cb.event_cb.on_zrtp_secure = on_zrtp_secure;
zrtp_config.cb.event_cb.on_zrtp_security_event = on_zrtp_event;
// Everything is ready - initialize libzrtp.
s = zrtp_init(&zrtp_config, &zrtp_global);
if (zrtp_status_ok != s) {
// Check error code and debug logs
}
// The library has been initialized and is ready to use
. . .
\endcode
*** \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.
\code
//
// Allocate zrtp session with default parameters
//
z = zrtp_session_init( zrtp_global,
NULL,
zid,
is_initator,
&safe_connection->zrtp_session);
if (zrtp_status_ok != s) {
// Check error code and debug logs
}
// Set call-back pointer to our parent structure
zrtp_session_set_userdata(safe_connection->zrtp_session, &safe_connection);
//
// Attach Audio and Video Streams
//
s = zrtp_stream_attach(safe_connection->zrtp_session, &safe_connection->zrtp_audio);
if (zrtp_status_ok != s) {
// Check error code and debug logs
}
zrtp_stream_set_userdata(safe_connection->zrtp_audio, &safe_connection);
s = zrtp_stream_attach(safe_connection->zrtp_session, &safe_connection->zrtp_video);
if (zrtp_status_ok != s) {
// Check error code and debug logs
}
zrtp_stream_set_userdata(safe_connection->zrtp_video, &safe_connection);
\endcode
*** \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.
\code
//
// Streams are ready - initiate ZRTP protocol
//
zrtp_stream_start(safe_connection->zrtp_audio, assrc);
zrtp_stream_start(safe_connection->zrtp_video, vssrc);
\endcode
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.
\code
zrtp_status_t s = zrtp_status_fail;
char packet[MAX_RTP_SIZE];
int size = 0;
// Some abstract function for packets receiving
size = get_packet(packet);
//
// Processing incoming packets.
// You must determine media type and choose corresponding ZRTP stream
//
s = zrtp_process_srtp(safe_connection->zrtp_audio, packet, &size);
switch (s) {
case zrtp_status_ok:
//
// Packet was successfully decrypted. Dont forget that packet
// size was changed during decryption. New size now in size
//
case zrtp_status_drop:
//
// This is a protocol ZRTP packet or masked RTP media.
// In either case the packet must be dropped to protect your
// private data and media codec
case zrtp_status_fail:
//
// This is some kind of error - see logs for more information.
// Don't put such packet to the network. It is not secure.
//
}
\endcode
*** \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:
\code
static void on_zrtp_secure(zrtp_stream_t *stream, unsigned event)
{
test_options_t* info; // some user-defined stream options
switch (event) {
case ZRTP_EVENT_IS_SECURE:
{
safe_connection_t* safe_connection = zrtp_stream_get_userdata(stream);
zrtp_session_info_t zrtp_session_info;
zrtp_session_get(safe_connection->zrtp_session, &zrtp_session_info);
//
// Print out SAS there.
//
} break;
// ...
// handle other events there
default:
break;
}
}
\endcode
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.
\code
zrtp_session_down(safe_connection->zrtp_session);
\endcode
When you no longer need the library, dispose of all resources allocated before the beginning of the operation.
\code
zrtp_down(&zrtp_global);
\endcode