mirror of
https://github.com/signalwire/freeswitch.git
synced 2026-10-09 21:14:02 +00:00
Add libzrtp beta
This commit is contained in:
Viktor Krikun
committed by
Travis Cross
Travis Cross
parent
f61ed4a163
commit
5a61e580b9
+1553
File diff suppressed because it is too large
Load Diff
+451
@@ -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;
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
<hr size="1"><address style="text-align: right;"><small>
|
||||
Generated on $datetime for $projectname <a href="http://www.zfoneproject.com"><img src="zfone.jpg" alt="zfone" align="middle" border="0"></a> </small></address>
|
||||
</body>
|
||||
</html>
|
||||
@@ -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>
|
||||
@@ -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.
|
||||
*/
|
||||
@@ -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
|
||||
|
||||
****************************************************************************************************
|
||||
\section howto_summary 12. Summary
|
||||
****************************************************************************************************
|
||||
<HR>
|
||||
Integration of libzrtp requires familiarity with the protocol and the library operation features. While the encryption of VoIP is not a trivial task, we have attempted to simplify as much as possible the work required to integrate libzrtp.
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,38 @@
|
||||
#
|
||||
# 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>
|
||||
|
||||
/**
|
||||
\mainpage ZRTP VoIP security
|
||||
|
||||
****************************************************************************************************
|
||||
\section intro Intro
|
||||
****************************************************************************************************
|
||||
|
||||
ZRTP Protocol finally goes RFC and we going to stabilize SDK as well. Libzrtp series 0.9X builds
|
||||
will contain bug-fixes, performance and stability improvements only.
|
||||
|
||||
So, please, be a patient with new API changes. We hope you will find them useful.
|
||||
|
||||
****************************************************************************************************
|
||||
\section aboutdoc About this Documentation
|
||||
****************************************************************************************************
|
||||
|
||||
Libzrtp, since v0.80 includes new, documentation. We have updated "How to Get Up and Running Quickly with libZRTP" and Public API documentation.
|
||||
|
||||
We working on new "Libzrtp Developers Guide" which will give more detail information about ZRTP protocol and libzrtp architecture. This document will be available in next versions of libzrtp. But even now, libzrtp contains enough documentation to start using it comfortable.
|
||||
|
||||
\note
|
||||
libzrtp private API may have outdated information from previous version (links like this: \ref XXX). We working hard on that part of the documentation and it will be published in next versions of libzrtp.
|
||||
|
||||
****************************************************************************************************
|
||||
\section zrtp Libzrtp Documents
|
||||
****************************************************************************************************
|
||||
-# \ref changelog
|
||||
-# \ref howto
|
||||
-# \ref rng
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,74 @@
|
||||
#
|
||||
# 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 rng.dox
|
||||
* \brief Random Number Generation in libzrtp
|
||||
*/
|
||||
|
||||
/**
|
||||
\page rng Random Number Generation in libzrtp
|
||||
|
||||
\section rng Random number generation
|
||||
|
||||
The generation of cryptographic key material is a highly sensitive process. To do this, you need high entropy random numbers that an attacker cannot predict. This section discusses the random number generator used by libzrtp, and how suitable entropy can be collected on different hardware platforms.
|
||||
|
||||
Failure to use true entropy from the physical environment as a basis for generating random cryptographic key material would lead to a disastrous loss of security.
|
||||
|
||||
****************************************************************************************************
|
||||
\subsection rng_algorithm Deterministic Random Bit Generator
|
||||
****************************************************************************************************
|
||||
<HR>
|
||||
Libzrtp uses a cryptographically strong Deterministic Random Bit Generator (DRBG), based on running the AES-256 block cipher in counter mode. The output of this DRBG is used for key material by libzrtp for the Diffie-Hellman private keys, and other random protocol components such as nonces. The 256-bit AES key and 128-bit initialization vector for the DRBG are drawn from an entropy pool
|
||||
created by a SHA-512 hash of raw entropy sources. These raw entropy sources are highly platform dependent and thus are not included in libzrtp. The library provides only a set of interfaces for adding the entropy to the entropy pool. We will discuss the entropy collection in the next section.
|
||||
|
||||
When a random number is required by the ZRTP protocol, the library kernel calls the Deterministic Random Bit Generator interface function zrtp_randstr(). That function requires the existance of an entropy pool that has already been seeded with sufficient entropy. This entropy pool must be seeded by calling zrtp_entropy_add().
|
||||
|
||||
The zrtp_entropy_add() function takes a buffer of raw unprocessed entropy provided by the caller and adds it to the entropy pool via the SHA-512 hash function.
|
||||
|
||||
****************************************************************************************************
|
||||
\subsection rng_accumulation Entropy accumulation
|
||||
****************************************************************************************************
|
||||
<HR>
|
||||
Random numbers for cryptographic key material must be derived from a physical entropy source, such as RF noise, acoustic noise, thermal noise, high resolution timings of environmental events, or other unpredictable physical sources of entropy. For a detailed explanation of cryptographic grade random numbers and guidance for collecting suitable entropy, see <A
|
||||
HREF="http://tools.ietf.org/html/rfc4086">RFC 4086</A> and Chapter 10 of "Practical Cryptography" by Ferguson and Schneier. The raw entropy must be distilled and processed through a Deterministic Random Bit Generator (DRBG). We supply a suitable DRBG in libzrtp, which is accessed through the zrtp_randstr() function.
|
||||
|
||||
To add entropy to the entropy pool maintained by the libzrtp random number generator, the application calls the zrtp_entropy_add() function. This entropy accumulation function may be called whenever new entropy becomes available.
|
||||
|
||||
\warning
|
||||
The entropy pool builds up more precious entropy each time you call zrtp_entropy_add(). Once in a while, it is a good idea to save the entropy in nonvolatile storage, by calling zrtp_randstr() and writing the output to a file, or to flash memory, or to some nonvolatile system storage area. This can be done whenever the VoIP application shuts down, or perhaps at the end of each secure VoIP call. A minimum of 512 bits (64 bytes) of output from zrtp_randstr() should be stored this way, but there is no need to store more than 256 bytes. When the VoIP application starts back up again, the contents of this nonvolatile entropy file should be added back into the active entropy pool by passing it to the zrtp_entropy_add() function.
|
||||
|
||||
****************************************************************************************************
|
||||
\subsection rng_default Libzrtp built-in entropy sources
|
||||
****************************************************************************************************
|
||||
<HR>
|
||||
The SDK library provides a default implementation of entropy accumulation for <b>Windows Kernel</b> and <b>Unix based</b> platforms.
|
||||
|
||||
For the Windows kernel mode it gathers current system state information as an entropy source. Among them are the performance counter, the current value of the system interrupt-time count, the count of the interval timer interrupts, and the values of some CPU registers.
|
||||
|
||||
For Unix platforms, libzrtp calls \c /dev/urandom.
|
||||
|
||||
If you are running libzrtp on a Windows Kernel or a full-blown desktop *nix-like system - you need not do anything more to implement the RNG. If you are using some other platform - carefully read the next section.
|
||||
|
||||
****************************************************************************************************
|
||||
\subsection rng_guidelines Entropy sources for your platform.
|
||||
****************************************************************************************************
|
||||
<HR>
|
||||
On a desktop or laptop PC running Linux, FreeBSD, NetBSD, or OpenBSD, a good source of entropy may be found by reading from \c /dev/random or \c /dev/urandom. This is because \c /dev/random is seeded by entropy from keyboard timings, mouse movements, disk latency measurements, or other physical noise sources, some of them involving unpredictable human interaction.
|
||||
|
||||
However, some low cost embedded Linux systems have no keyboard, no mouse or trackpad, no disk drive, and are starving for high quality entropy. There are some low cost Asterisk PBX boxes that are built this way. Or hardware Analog Telephone Adapters. Or low cost consumer routers. Many of them have no \c /dev/random implemented, or worse, have only a stub for /dev/random that does not actually collect any environmental entropy. This creates a dangerous illusion that entropy is available, because \c /dev/urandom appears to work, but is not backed by true entropy. This is bad, and not only for ZRTP. Platforms like these might not be able to generate strong cryptographic key material for SSH or SSL.
|
||||
|
||||
If you are an OEM that builds hardware like this, and you wish to implement the ZRTP protocol with our libzrtp SDK, you really should provide a properly implemented \c /dev/random and \c /dev/urandom, properly supplied with true environmental entropy. If you are building a telephone, you can easily collect entropy from raw audio samples from the microphone. If the phone includes a video camera, you can collect entropy by sampling a few raw uncompressed video frames. If it's a mobile phone or a cordless phone, you can collect entropy from the RF noise in your wireless circuitry. If it's an embedded box like a router or low cost PBX, you can do high resolution timings of packet arrivals and use the timer readings as entropy sources. A PBX might include an analog interface to PSTN phone lines, and those interfaces usually include registers that measure analog voltage levels, which can serve as a source of entropy. The entropy sources do not need to produce much entropy, just a few bits at a time, but it can build up slowly until you have accumulated a few hundred bits of entropy. That's enough to generate cryptographically useful keys. Even if it takes some seconds or even minutes to accumulate this much entropy the first time your product is activated, it can be stored in nonvolatile storage so that it will be ready to reseed the entropy pool instantly the next time your product is powered up.
|
||||
|
||||
In the ideal case, if you are designing the embedded hardware yourself, you could provide a good source of entropy by including a simple <A HREF="http://en.wikipedia.org/wiki/Ring_oscillator">ring oscillator</A> in the hardware. A ring oscillator is a circular chain (a ring) of NOT gates, and has nothing whatsoever to do with a telephone ring generator. The oscillation frequency drifts from thermal noise, and sampling the output at some low sampling rate is a good way to get some entropy. However, most designers have to work with existing hardware designs, and don't have the luxury of adding special hardware to generate entropy, which means you have to improvise with whatever you can collect from the environment, using any of the methods described above.
|
||||
|
||||
If the library is used on another platform, the potential entropy sources should be thoroughly analyzed and a custom implementation must be developed for that platform. You can get your entropy collection ideas by looking at the default implementation of \c zrtp_add_system_state() provided in \c zrtp_rng.c. Again, microphone noise can be a good entropy source for VoIP clients. Raw, uncompressed, unfiltered audio samples should be used.
|
||||
|
||||
If you have entropy gathering schemes for platforms not already supported in libzrtp, or if you doubt the correctness of your entropy collection approach, contact us to discuss how it may be done. We will do our best to provide you with technical assistance.
|
||||
|
||||
*/
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 8.3 KiB |
Reference in New Issue
Block a user