1 /* 2 * libZRTP SDK library, implements the ZRTP secure VoIP protocol. 3 * Copyright (c) 2006-2009 Philip R. Zimmermann. All rights reserved. 4 * Contact: http://philzimmermann.com 5 * For licensing and other legal details, see the file zrtp_legal.c. 6 * 7 * Viktor Krykun <v.krikun at zfoneproject.com> 8 */ 9 10 /** 11 * \file zrtp.h 12 * \brief Defines basic libzrtp functions and data types 13 */ 14 15 #ifndef __ZRTP_H__ 16 #define __ZRTP_H__ 17 18 #include "zrtp_config.h" 19 #include "zrtp_base.h" 20 #include "zrtp_error.h" 21 #include "zrtp_types.h" 22 #include "zrtp_protocol.h" 23 #include "zrtp_engine.h" 24 #include "zrtp_crypto.h" 25 #include "zrtp_iface.h" 26 #include "zrtp_iface_system.h" 27 #include "zrtp_iface_scheduler.h" 28 #include "zrtp_list.h" 29 #include "zrtp_legal.h" 30 #include "zrtp_log.h" 31 #include "zrtp_srtp.h" 32 #include "zrtp_srtp_builtin.h" 33 #include "zrtp_string.h" 34 #include "zrtp_pbx.h" 35 #include "zrtp_legal.h" 36 #include "zrtp_version.h" 37 #include "zrtp_iface_cache.h" 38 #include "zrtp_ec.h" 39 40 41 42 /** 43 * \defgroup zrtp_api API 44 * 45 * In this section the basic functions for using the library are defined. They include 46 * initialization and deinitialization functions, functions for session and stream management and 47 * functions for RTP traffic management. 48 * 49 * In most cases this section is all you need to start working with libzrtp. The typical simplified 50 * order of operations in using libzrtp is the following: 51 * -# library configuration 52 * -# library initialization; 53 * -# ZRTP session creation and configuration; 54 * -# ZRTP stream attaching and Protocol initiation; 55 * -# RTP stream processing; 56 * -# ZRTP protocol stopping and releasing resources. 57 * For each of these actions there is a set of corresponding functions. 58 * \sa 59 * - \ref howto 60 * - \ref XXX_GUIDE 61 */ 62 63 64 65 /*======================================================================*/ 66 /* Public ZRTP libzrtp datatypes */ 67 /*======================================================================*/ 68 69 70 /** 71 * \defgroup zrtp_types Types and Definitions 72 * \ingroup zrtp_api 73 * The data types used in libzrtp are defined in this section 74 * \{ 75 * 76 */ 77 /** 78 * \typedef typedef uint32_t zrtp_id_t; 79 * \brief libzrtp general identifier used to debug connections management. 80 * \ingroup zrtp_main_init 81 */ 82 83 /** Length of "zrtp-hash-value", RFC 6189 sec 8. @sa zrtp_signaling_hash_get(); */ 84 #define ZRTP_SIGN_ZRTP_HASH_LENGTH (ZRTP_MESSAGE_HASH_SIZE*2) 85 86 /** 87 * \brief Enumeration for ZRTP Licensing modes 88 * \ingroup zrtp_main_init 89 * 90 * A ZRTP endpoint that is Passive will never send a Commit message, which means that it cannot be 91 * the initiator in the ZRTP exchange. Since at least one of the two parties must be the initiator, 92 * two Passive endpoints cannot make a secure connection. However, a non-Passive ZRTP endpoint can 93 * send a Commit message, enabling it to act as the initiator in a ZRTP exchange. This allows it to 94 * make a secure connection to a Passive endpoint, or to another non-Passive endpoint. 95 * 96 * In addition, a Passive ZRTP endpoint declares that it is Passive by setting the passive flag in 97 * the Hello message, which means the other party will recognize it as Passive. This allows for a 98 * Passive mode and two forms of Active mode-- Active, or Unlimited. These three possible behaviors 99 * for a ZRTP endpoint are defined as: 100 * - \b Passive: Never send a Commit message, and thus can never be the initiator. 101 * - \b Active: Will send a Commit message, but only to non-Passive ZRTP partners. 102 * - \b Unlimited: Will send a Commit message to any ZRTP partner, Passive or non-Passive. 103 * 104 * This can be used to provide three classes of service, which can be licensed t different price 105 * points. Passive can be used in freeware for widest possible deployment, Active can be used in 106 * discount products that can only talk to non-freeware, and Unlimited can be used in full-price 107 * products that will benefit from the network effect of widely deployed Passive freeware. 108 */ 109 typedef enum zrtp_license_mode_t 110 { 111 /** @brief Never send a Commit message, and thus can never be the initiator. */ 112 ZRTP_LICENSE_MODE_PASSIVE = 0, 113 /** @brief Will initiate ZRTP exchange, but only to non-Passive ZRTP partners. */ 114 ZRTP_LICENSE_MODE_ACTIVE, 115 /** @brief Will send a Commit message to any ZRTP partner, Passive or non-Passive. */ 116 ZRTP_LICENSE_MODE_UNLIMITED 117 } zrtp_license_mode_t; 118 119 /** 120 * @brief Enumeration to define Signaling initiator/responder roles. 121 * 122 * Used by libzrtp to optimize some internal processes and protocol handshake. 123 * 124 * @sas zrtp_stream_start(). 125 */ 126 typedef enum zrtp_signaling_role_t 127 { 128 /** @brief Unknown Signaling role, should be used when the app can't determine the role. */ 129 ZRTP_SIGNALING_ROLE_UNKNOWN = 0, 130 /** @brief Signaling Initiator. */ 131 ZRTP_SIGNALING_ROLE_INITIATOR, 132 /** @brief Signaling Responder. */ 133 ZRTP_SIGNALING_ROLE_RESPONDER, 134 ZRTP_SIGNALING_ROLE_COUNT 135 } zrtp_signaling_role_t; 136 137 138 /** @brief 12-byte ZID for unique ZRTP endpoint identification. */ 139 typedef unsigned char zrtp_zid_t[12]; 140 141 /** \brief 16-byte ID for ZRTP endpoint's software identification. */ 142 typedef char zrtp_client_id_t[16]; 143 144 /** 145 * @brief ZRTP global configuration options 146 * @ingroup zrtp_main_init 147 * @warning Use \ref zrtp_config_defaults() before start configuring this structure. 148 */ 149 typedef struct zrtp_config_t 150 { 151 /** @brief Symbolic client identifier */ 152 zrtp_client_id_t client_id; 153 154 /** @brief libzrtp license mode defined protocol behavior */ 155 zrtp_license_mode_t lic_mode; 156 157 /** @brief Set this flag to 1 if you product is MiTM box */ 158 uint8_t is_mitm; 159 160 /** @brief Set of interfaces required to operate with libzrtp */ 161 zrtp_callback_t cb; 162 163 /** @brief Path to zrtp cache file (set if you use built-in realization) */ 164 zrtp_string256_t def_cache_path; 165 166 /** 167 * @brief Flush the cache automatically 168 * Set to 1 if you want libzrtp to flush the cache to the persistent storage 169 * right after it is modified. If cache_auto_store is 0, libzrtp will flush 170 * the cache on going down only and the app is responsible for storing the 171 * cache in unexpected situations. Enabled by default. 172 * 173 * @sa zrtp_def_cache_store() 174 */ 175 unsigned cache_auto_store; 176 } zrtp_config_t; 177 178 /** 179 * \brief zrtp stream information structure 180 * \ingroup zrtp_main_management 181 * 182 * libzrtp, since v0.80 takes data encapsulating approach and hides all private data inside 183 * zrtp_stream_t structure. Developers shouldn't access them directly. \ref zrtp_stream_get() should 184 * be used instead to fill zrtp_stream_info_t structure. zrtp_stream_info_t contains all needed 185 * information in safe and easy to use form. 186 */ 187 struct zrtp_stream_info_t 188 { 189 /** \brief Stream unique identifier for debug purposes */ 190 zrtp_id_t id; 191 192 /** \brief Pointer to the parent zrtp session */ 193 zrtp_session_t* session; 194 195 /** \brief Stream mode. Defines libzrtp behavior related to specified contexts. */ 196 zrtp_stream_mode_t mode; 197 198 /** \brief Defines ZRTP Trusted mitm mode for the current session. */ 199 zrtp_mitm_mode_t mitm_mode; 200 201 /** \brief Reflects current state of ZRTP protocol */ 202 zrtp_state_t state; 203 204 /** 205 * \brief Last protocol error code 206 * 207 * Available for reading in ERROR state on zrtp_security_event_t#ZRTP_EVENT_PROTOCOL_ERROR. 208 */ 209 zrtp_protocol_error_t last_error; 210 211 /** 212 * \brief Remote passive flag 213 * 214 * This flag shows when remote side is "passive" (has license mode PASSIVE) available in CLEAR 215 * state and later. 216 */ 217 uint8_t peer_passive; 218 219 /** 220 * \brief Allowclear flag. 221 * 222 * Current value of "allowclear" option exchanged during ZRTP negotiation. Available in SECURE 223 * state. 224 */ 225 uint8_t res_allowclear; 226 227 /** 228 * \brief Peer disclose bit flag 229 * 230 * Indicates the ability of the remote side to disclose its session key. Specifies that the 231 * remote side allows call monitoring. If this flag is set, the end user must be informed. It 232 * can be read in the SECURE state. 233 */ 234 uint8_t peer_disclose; 235 236 /** 237 * \brief Defines that remote party is ZRTP MiTM endpoint 238 * 239 * Enabled by (Asterisk PBX, UMLab SIP Firewall or etc.) Available for reading in CLEAR state 240 * ande later. 241 */ 242 uint8_t peer_mitm; 243 }; 244 245 /** 246 * \brief zrtp session information structure 247 * \ingroup zrtp_main_management 248 * libzrtp, since v0.80 takes data incapsulating approach and hides all private date inside 249 * zrtp_session_t structure. Developers shouldn't access them directly. \ref zrtp_session_get() 250 * should be used instead to fill zrtp_session_info_t structure. zrtp_session_info_t contains all 251 * needed information in safe and easy to use form. 252 */ 253 struct zrtp_session_info_t 254 { 255 /** \brief Session unique identifier for debug purposes */ 256 zrtp_id_t id; 257 258 /** 259 * \brief Local ZID 260 * 261 The unique 12-characters string that identifies the local ZRTP endpoint.This ID allows remote 262 * peers to recognize this ZRTP endpoint. 263 */ 264 zrtp_string16_t zid; 265 266 /** 267 * \brief Remote ZID 268 * 269 * Extracted from the Hello packet of the very first ZRTP stream. Uniquely identifies the remote 270 * ZRTP peer. 271 */ 272 zrtp_string16_t peer_zid; 273 274 /** \brief Character name identified remote ZRTP endpoint.*/ 275 zrtp_string16_t peer_clientid; 276 277 /** \brief ZRTP Protocol version supported by the remote endpoint. */ 278 zrtp_string16_t peer_version; 279 280 /** 281 * \brief Indicates that SAS related data is available for reading. 282 * \note 283 * As SAS is computed in SECURE state only, it may contain unknown values in other states. Check 284 * sas_is_ready before displaying SAS to the user. 285 */ 286 uint8_t sas_is_ready; 287 288 /** \brief First Short Authentication String */ 289 zrtp_string16_t sas1; 290 291 /** 292 * \brief Second Short Authentication string. 293 * \note 294 * Second SAS is available for \c base256 authentication only (\c sas_is_base256 is set). In 295 * other case, \c sas1 contains \c base32 value and \c sas2 is empty. 296 */ 297 zrtp_string16_t sas2; 298 299 /** \brief Binary SAS digest (ZRTP_SAS_DIGEST_LENGTH bytes) */ 300 zrtp_string32_t sasbin; 301 302 /** 303 * \brief Bit-map to summarize shared secrets "Cached" flags. 304 * 305 * 1 at appropriate bit means that the secrets was found in the cache and restored successfully. 306 * Value equal to 0 indicates that secret for the remote endpoint was not found in the cache 307 * and was generated randomly. 308 * Use ZRTP_BIT_RS1, ZRTP_BIT_RS2, ZRTP_BIT_AUX and ZRTP_BIT_PBX bit-masks to get "cached" value 309 * for the appropriate secret. 310 */ 311 uint32_t cached_flags; 312 313 /** 314 * \brief Bit-map to summarize shared secrets "Matched" flags. 315 * 316 * 1 at appropriate bit means that the secret, locally computed by your ZRTP endpoint is equal 317 * to the secret, received from the remote endpoint. Secrets may not match if one of the 318 * endpoints doesn't use cache of the shared secrets, if the cache was deleted or in case of 319 * an attack. 320 * Use ZRTP_BIT_RS1, ZRTP_BIT_RS2, ZRTP_BIT_AUX and ZRTP_BIT_PBX bit-masks to get "cached" value 321 * for the appropriate secret. 322 */ 323 uint32_t matches_flags; 324 325 /** 326 * \brief Bit-map to summarize shared secrets "Wrong" flags. 327 * 328 * 1 at appropriate bit means that the secret was restored from the cache, but doesn't match 329 * to the remote endpoint's secret. Such situation may happen if the remote endpoint lost cache 330 * or in case of attach. 331 * Use ZRTP_BIT_RS1, ZRTP_BIT_RS2, ZRTP_BIT_AUX and ZRTP_BIT_PBX bit-masks to get "cached" value 332 * for the appropriate secret. 333 */ 334 uint32_t wrongs_flags; 335 336 /** 337 * \brief SAS Verification flag. 338 * 339 * The SAS Verified flag (V) is set based on the user indicating that SAS comparison has been 340 * successfully performed. Each party sends the SAS Verified flag from the previous session in 341 * the Confirm message of the current session. 342 * \sa 343 * - ZRTP RFC section. "7.1. SAS Verified Flag" for more information about Verification Flag. 344 * - zrtp_verified_set() 345 */ 346 uint32_t sas_is_verified; 347 348 /** \brief Indicates base256 SAS encoding */ 349 uint8_t sas_is_base256; 350 351 /** 352 * \brief actual lifetime of the secrets 353 * 354 * This variable contains the interval for retaining secrets within an established session. In 355 * accordance with ZRTP RFC this value is calculated as the minimal of local and remote TTLs 356 * after confirmation. Value is given in seconds and can be read in the SECURE state. 357 */ 358 uint32_t secrets_ttl; 359 360 /** \brief Hash crypto component name used in ZRTP calculations. */ 361 zrtp_string32_t hash_name; 362 363 /** \brief Cipher crypto component name used in ZRTP encryption. */ 364 zrtp_string32_t cipher_name; 365 366 /** \brief SRTP Authentication crypto component name used in ZRTP exchange. */ 367 zrtp_string32_t auth_name; 368 369 /** \brief SAS scheme crypto component name used in ZRTP exchange. */ 370 zrtp_string32_t sas_name; 371 372 /** \brief Publik Key Exchange name used in ZRTP exchange. */ 373 zrtp_string32_t pk_name; 374 }; 375 376 /* \} */ 377 378 379 /*======================================================================*/ 380 /* libzrtp Public API: Streams management */ 381 /*======================================================================*/ 382 383 384 #if defined(__cplusplus) 385 extern "C" 386 { 387 #endif 388 389 /** 390 * \defgroup zrtp_main_init Initalization and Configuration 391 * \ingroup zrtp_api 392 * \{ 393 */ 394 395 /** 396 * \brief Initializes libzrtp global config 397 * 398 * zrtp_config_defaults() prepares all fields of zrtp_config_t for further usage in zrtp_init(). 399 * This function allocates all necessary resources and initialize zrtp_config_t#cb with default 400 * implementations. 401 * 402 * \param config - libzrtp config for initialization. 403 * \warning this function must be used before start operating with the config. 404 */ 405 void zrtp_config_defaults(zrtp_config_t* config); 406 407 /** 408 * \brief Initializing libzrtp 409 * 410 * This function initializes the library and all its components. zrtp_init() initialize global data 411 * for all sessions and streams. Fields of the global zrtp context are initialized automatically and 412 * shouldn't be modified. For correct memory management, global context should be released by 413 * calling zrtp_down(). 414 * 415 * \param config - libzrtp inital parameters 416 * \param zrtp - out parameter, pointer to allocated zrtp global context structure; 417 * \warning this function \b must be called before any operation with libzrtp. 418 * \return 419 * - zrtp_status_ok in successfully initialized or one of zrtp status errors in other case. 420 * \sa zrtp_down() 421 */ 422 zrtp_status_t zrtp_init(zrtp_config_t* config, zrtp_global_t** zrtp); 423 424 /*! 425 * \brief Shutting down the library 426 * 427 * Frees all allocated structures and resources. This function \b must be called at the end of use 428 * to stop libzrtp correctly. zrtp_down() doesn't stop in-progress ZRTP streams. To avoid mistakes, 429 * close all sessions before library deinitialization. 430 * 431 * \param zrtp - global ZRTP context previously allocated by zrtp_init(); 432 * \return 433 * - zrtp_status_ok if successfully shut down; 434 * - zrtp_status_fail if an error occurred. 435 * \sa zrtp_init() 436 */ 437 zrtp_status_t zrtp_down(zrtp_global_t* zrtp); 438 439 /* \} */ 440 441 /** 442 * \defgroup zrtp_main_management ZRTP Connections 443 * \ingroup zrtp_api 444 * \{ 445 */ 446 447 /** 448 * \brief ZRTP Session Initialization. 449 * 450 * This function allocates and initializes the internal session context data. The given context is 451 * associated with the specified ZRTP identifier. Only after initialization does the session contain 452 * ZRTP_MAX_STREAMS_PER_SESSION streams ready to be used. 453 * 454 * After successfully initialization, configuration will be done according to the relevant profile 455 * \c profile. Profile will be applyed to every stream allocated within this session. Before using 456 * the profile, call zrtp_profile_check() function to make sure that the profile you are applying 457 * is correct. 458 * 459 * \warning Don't call zrtp_session_init() in parallel with other operations on this session. 460 * \param zrtp - global libzrtp context; 461 * \param profile - the session configuration profile. If value of this parameter is NULL, default 462 * profile will be used. NULL profile usage is equivalent to calling zrtp_profile_defaults(). 463 * \param zid - ZRTP peer identificator. 464 * \param role - identifies if the endpoint was the signaling initiator of the call. Used to 465 * provide Passive Mode options to the developer. If your application doesn't control signaling 466 * or you don't want to support Passive Mode features - set it to ZRTP_SIGNALING_ROLE_UNKNOWN. 467 * \param session - allocated session structure. 468 * \return 469 * - zrtp_status_ok if initialization is successful; 470 * - zrtp_status_fail if an error occurs. 471 * \sa zrtp_session_down() 472 */ 473 zrtp_status_t zrtp_session_init( zrtp_global_t* zrtp, 474 zrtp_profile_t* profile, 475 zrtp_zid_t zid, 476 zrtp_signaling_role_t role, 477 zrtp_session_t **session); 478 /** 479 * \brief ZRTP Session context deinitialization 480 * 481 * This function releases all resources allocated for internal context operations by zrtp_init(). 482 * 483 * \warning Don't call zrtp_session_init() in parallel with other operations on this session. 484 * \param session - session for deinitialization. 485 * \sa zrtp_session_init() 486 */ 487 void zrtp_session_down(zrtp_session_t *session); 488 489 490 /** 491 * \brief Obtain information about ZRTP session 492 * 493 * Function initialize and fills all fields of zrtp_session_info_t structure according to 494 * the current state of ZRTP session. 495 * 496 * \param session - zrtp session which parameters should be extracted; 497 * \param info - out structure to be initialized. 498 * \return 499 * - zrtp_status_ok in case of success. 500 * - zrtp_status_fail if an error occurs. 501 */ 502 zrtp_status_t zrtp_session_get(zrtp_session_t *session, zrtp_session_info_t *info); 503 504 /** 505 * \brief Allow user to associate some data with current zrtp session. 506 * \param session - zrtp session to attach data to. 507 * \param udata - pointer to the user-data context. 508 * \sa zrtp_session_get_userdata() 509 */ 510 void zrtp_session_set_userdata(zrtp_session_t *session, void* udata); 511 512 /** 513 * \brief Return user data associated with the zrtp session 514 * \param session - zrtp session to extract user data. 515 * \return 516 * - pointer to the user-data context previously set by zrtp_session_set_userdata(). 517 * - NULL if the user data unavailable. 518 * \sa zrtp_session_set_userdata() 519 */ 520 void* zrtp_session_get_userdata(zrtp_session_t *session); 521 522 /** 523 * \brief Attaching a new stream to the session 524 * 525 * This function call initializes a ZRTP stream and prepares it for use within the specified 526 * session. The maximum number of streams for one session is defined by the 527 * ZRTP_MAX_STREAMS_PER_SESSION variable. All newly created streams are equivalent and have 528 * ZRTP_STREAM_MODE_CLEAR mode and ZRTP_ACTIVE state. Only after attaching a stream, ZRTP protocol 529 * can be initiated. 530 * 531 * \param session - the ZRTP session within which a new stream is to be 532 * \param stream - out parameter, attached stream will be stored there 533 * \return 534 * - zrtp_status_ok if stream was attached successfully 535 * - one of zrtp_status_t errors in case of failure 536 * \sa zrtp_stream_start() zrtp_stream_stop() 537 */ 538 zrtp_status_t zrtp_stream_attach(zrtp_session_t *session, zrtp_stream_t** stream); 539 540 /** 541 * \brief Starting a ZRTP stream 542 * 543 * ZRTP stream setup is initiated by calling this function. Exchange of command packets begins 544 * immediately according to protocol. If the option "autosecure" is on, calling this function is the 545 * only requirement for setting up the ZRTP connection within a stream. If "autosecure" mode is not 546 * available, calling this function activates only connection within a ZRTP stream. A connection can 547 * be established manually later by calling zrtp_stream_secure(). 548 * 549 * Setup of the stream/connection takes a certain interval of time. This function just initiates 550 * this process. The system of callbacks informs the user about the progress of libzrtp protocol. 551 * 552 * \param stream - ZRTP stream to be started. 553 * \param ssrc - ssrc which will be used in ZRTP protocol messages. It should match with ssrc of 554 * appropriate RTP stream which will be encrypted by this ZRTP stream. 555 * \return 556 * - zrtp_status_ok in case of success; 557 * - one of zrtp_status_t errors in case of failure 558 * \sa 559 * - \ref XXX_GUIDE_CB \ref XXX_GUIDE_MANAGEMENT 560 * - zrtp_stream_stop() zrtp_stream_secure() zrtp_stream_clear() 561 */ 562 zrtp_status_t zrtp_stream_start(zrtp_stream_t* stream, 563 uint32_t ssrc); 564 565 /** 566 * \brief ZRTP protocol stopping 567 * 568 * This function stops all protocol operations for the specified stream, releases resources 569 * allocated on the zrtp_stream_start() and prepares the stream structure for the next use. 570 * 571 * This function will stop the protocol at any stage: all delayed tasks are canceled, and the 572 * protocol packet exchange and encryption is stopped. After this function call it is necessary to 573 * stop processing traffic using the zrtp_process_xxx() function. 574 * 575 * \param stream - the stream being shutdown. 576 * \return 577 * - zrtp_status_ok in case of success; 578 * - one of zrtp_status_t errors in case of failure 579 * \sa 580 * - \ref XXX_GUIDE_CB \ref XXX_GUIDE_MANAGEMENT 581 * - zrtp_stream_start() zrtp_stream_secure() zrtp_stream_clear() 582 */ 583 zrtp_status_t zrtp_stream_stop(zrtp_stream_t* stream); 584 585 /*! 586 * \brief Initiating an interruption of the secure connection 587 * 588 * This function initiates the shutting down of the ZRTP connection within a stream. In other words, 589 * after successfully switching to secure mode (\ref XXX SECURE state, fig. 1.5), calling this 590 * function begins the exchange of packets switching back to insecure (CLEAR) mode. 591 * 592 * This function can only be implemented from the SECURE state. Attempt to call this function from 593 * any other state will end in failure. The client application is informed about protocol 594 * progress through a system of callbacks. 595 * 596 * \param stream - ZRTP stream . 597 * \return 598 * - zrtp_status_ok - if shutting down the connection is started successfully. 599 * - zrtp_status_fail - if shutting down the connection is initiated from an incorrect state. 600 * \sa 601 * - \ref XXX_GUIDE_CB \ref XXX_GUIDE_MANAGEMENT 602 * - zrtp_stream_start() zrtp_stream_secure() zrtp_stream_clear() 603 */ 604 zrtp_status_t zrtp_stream_clear(zrtp_stream_t *stream); 605 606 /** 607 * \brief Initiating a secure connection setup 608 * 609 * The function initiates a ZRTP connection setup within a stream. In other words, after the 610 * protocol has started and Discovery phase have been successfully accomplished, calling this 611 * function will begin the exchange of packets for switching to SECURE mode. 612 * 613 * This function can be successfully performed only from the CLEAR state (\ref XXX Figure 1.6). 614 * Attempting to call this function from any other state will result in failure. The client 615 * application is informed about protocol progress through a system of callbacks. 616 * 617 * \param stream - ZRTP stream to be secured. 618 * \return 619 * - zrtp_status_ok - if switching to secure mode started successfully. 620 * - zrtp_status_fail - if switching to secure mode is initiated from a state other than CLEAR. 621 * \sa 622 * - \ref XXX_GUIDE_CB \ref XXX_GUIDE_MANAGEMENT. 623 * - zrtp_stream_start() zrtp_stream_clear(). 624 */ 625 zrtp_status_t zrtp_stream_secure(zrtp_stream_t *stream); 626 627 /** 628 * \brief Obtain information about zrtp stream 629 * 630 * Function initialize and fills all fields of zrtp_stream_info_t structure accordint to 631 * current state of zrtp stream. 632 * 633 * \param stream - zrtp stream which parameters should be extracted 634 * \param info - out structure to be initialized 635 * \return 636 * - zrtp_status_ok in case of success. 637 * - zrtp_status_fail if an error occurs. 638 */ 639 zrtp_status_t zrtp_stream_get(zrtp_stream_t *stream, zrtp_stream_info_t *info); 640 641 /** 642 * @brief Allow user to associate some data with zrtp stream. 643 * @param stream - zrtp stream to attach data to. 644 * @param udata - pointer to the user-data context. 645 * @sa zrtp_stream_get_userdata() 646 */ 647 void zrtp_stream_set_userdata(zrtp_stream_t *stream, void* udata); 648 649 /** 650 * \brief Return user data associated with the zrtp stream 651 * \return 652 * - pointer to the user-data context previously set by zrtp_stream_set_userdata() 653 * - NULL if user data unavailable; 654 * \sa zrtp_stream_set_userdata() 655 */ 656 void* zrtp_stream_get_userdata(const zrtp_stream_t *stream); 657 658 /* \} */ 659 660 /*======================================================================*/ 661 /* libzrtp Public API: Encryption */ 662 /*======================================================================*/ 663 664 /** 665 * \defgroup zrtp_main_proto Traffic Processing 666 * \ingroup zrtp_api 667 * \{ 668 */ 669 670 /** 671 * \brief Processing outgoing RTP packets 672 * 673 * This is the main function for processing outgoing RTP packets. As soon as the protocol is 674 * started, each outgoing RTP packet (not encrypted) has to go through this function. 675 * 676 * It performs different actions depending on the connection state and packet type: 677 * - In setup ZRTP connection mode, it encrypts outgoing RTP packets. The packet is encrypted right 678 * in the transferred buffer; 679 * - Protects codec and data privacy by deleting certain packets from the stream. In this case the 680 * body and the length of the packet remain unchanged. 681 * 682 * \param stream - ZRTP stream to process RTP packet; 683 * \param packet - buffer storing the RTP packet for encryption. After processing, the encrypted 684 * packet is stored in the same buffer. 685 * \param length - the length of the buffered packet. After processing, the length of encrypted 686 * packet is stored here. 687 * \warning During encryption, the data length increases in comparison to the source data. Because 688 * the function uses the same buffer both for incoming and resulting values, the length of the 689 * buffer must be larger than size of source packet. 690 * \return 691 * - zrtp_status_ok if encryption is successful. The packet should be sent to the recipient. 692 * - zrtp_status_fail if there was an error during encryption. The packet should be rejected. 693 * - zrtp_status_drop if there was interference in the VoIP client codec protection mechanism. The 694 * packet should be rejected. 695 * \sa zrtp_process_srtp() zrtp_process_rtcp() zrtp_process_srtcp() 696 */ 697 zrtp_status_t zrtp_process_rtp( zrtp_stream_t *stream, 698 char* packet, 699 unsigned int* length); 700 701 /** 702 * \brief Processing incoming RTP packets 703 * 704 * This is the main function for incoming RTP packets processing. It is an analogue of 705 * zrtp_process_rtp() but for an incoming stream. After the protocol is started, each (encrypted) 706 * incoming RTP packet has to go through this function. 707 * 708 * It performs different actions depending on the connection state and packet type: 709 * - during setup/interruption of ZRTP connection, processes incoming protocol packets. The body 710 * and length of the packet remain unchanged; 711 * - in setup ZRTP connection mode, decrypts incoming RTP packet. The packet is decrypted right in 712 * the transferred buffer; 713 * - protects codec and data privacy by deleting certain packets from the stream. In this case the 714 * body and the length of the packet remain unchanged. 715 * 716 * \param stream - ZRTP stream for processing 717 * \param packet - buffer storing the packet for decrypting. After processing, the decrypted packet 718 * is stored in the same buffer; 719 * \param length - the length of the buffered packet. After processing, the length of decrypted 720 * packet is stored here; 721 * \return 722 * - zrtp_status_ok if decrypting is successful. Such a packet should be sent to the recipient; 723 * - zrtp_status_fail if an error occurred during decrypting or command packet processing. The 724 * packet should be rejected; 725 * - zrtp_status_drop if the command packet processing is successful or if there was interference 726 * in the VoIP client codec protection mechanism. The packet should be rejected in either case; 727 * \sa zrtp_process_rtp() zrtp_process_rtcp() zrtp_process_srtcp() 728 */ 729 zrtp_status_t zrtp_process_srtp( zrtp_stream_t *stream, 730 char* packet, 731 unsigned int* length); 732 733 /*! 734 * \brief Processing outgoing RTCP packets 735 * 736 * This is the main function for processing outgoing RTCP packets. The function behavior is similar 737 * to that of zrtp_process_rtp(): 738 * - In SECURE mode, encrypts outgoing RTCP packets. The packet is encrypted right in the 739 * transferred buffer. The length of encrypted packet is returned in the \c length variable; 740 * - protects codec and data privacy by deleting certain packets from the stream. In this case the 741 * body and the length of the packet remain unchanged. 742 * 743 * \param stream - ZRTP session for processing; 744 * \param packet - buffer storing RTCP packet; 745 * \param length - length of the buffered packet. 746 * \return 747 * - zrtp_status_ok if encryption is successful. The packet should be sent to the recipient. 748 * - zrtp_status_fail if there was an error during encryption. The packet should be rejected. 749 * - zrtp_status_drop if there was interference in the VoIP client codec protection mechanism. The 750 * packet should be rejected. 751 * \sa zrtp_process_srtp() zrtp_process_rtp() zrtp_process_srtcp() 752 */ 753 zrtp_status_t zrtp_process_rtcp( zrtp_stream_t *stream, 754 char* packet, 755 unsigned int* length); 756 757 /** 758 * \brief Processing incoming RTCP packets 759 * 760 * This is the main function for processing incoming RTCP packets. The function behavior is similar 761 * to that of zrtp_process_srtp(): 762 * - In SECURE mode, decrypts incoming RTCP packets. The packet is decrypted right in the 763 * transferred buffer. The length of the encrypted packet is returned in the \c length variable; 764 * - In transition states, drops all incoming RTCP traffic. In this case the body and the length of 765 * the packet remain unchanged. 766 * 767 * \param stream - ZRTP stream for processing; 768 * \param packet - buffer storing the RTCP packet; 769 * \param length - length of the buffered packet. 770 * \return 771 * - zrtp_status_ok if decrypting is successful. Such a packet should be sent to the recipient; 772 * - zrtp_status_drop if the command packet processing is successful or if there was interference 773 * in the VoIP client codec protection mechanism. The packet should be rejected in either case; 774 * - zrtp_status_fail if there was an error during encryption. The packet should be rejected. 775 * \sa zrtp_process_srtp() zrtp_process_rtp() zrtp_process_rtcp() 776 */ 777 zrtp_status_t zrtp_process_srtcp( zrtp_stream_t *stream, 778 char* packet, 779 unsigned int* length); 780 781 /* \} */ 782 783 /** 784 * \defgroup zrtp_main_utils Utilities 785 * \ingroup zrtp_api 786 * \{ 787 */ 788 789 /** 790 * \brief Specifies the hash of the peer Hello message for verification. 791 * 792 * In accordance with the ZRTP RFC sec. 9, this protocol can prevent DOS attacks by verification of 793 * the Hello message hash sent through the signaling protocol. 794 * 795 * This function allows the user to specify the Hello hash for verification. If after the 796 * discovering phase the Hello hashes don't match, libzrtp raises the 797 * zrtp_event_t#ZRTP_EVENT_WRONG_SIGNALING_HASH event. This function should only be called before 798 * starting the protocol from the ZRTP_STATE_ACTIVE state. 799 * 800 * \param stream - stream for operating with; 801 * \param hash_buff - signaling hash buffer. Function accepts string, not a binary value!; 802 * \param hash_buff_length - signaling hash length in bytes, must be ZRTP_SIGN_ZRTP_HASH_LENGTH bytes; 803 * \return: 804 * - zrtp_status_ok if the operation finished successfully 805 * - one of the errors otherwise 806 * \sa 807 * - ZRTP RFC. sec 8; 808 * - zrtp_signaling_hash_get() 809 */ 810 zrtp_status_t zrtp_signaling_hash_set( zrtp_stream_t* stream, 811 const char *hash_buff, 812 uint32_t hash_buff_length); 813 814 /** 815 * \brief Returns the hash of the Hello message to be transferred in signaling. 816 * 817 * To prevent DOS attacks, the hash of the Hello message may be sent through signaling. 818 * zrtp_signaling_hash_get() may be called after attaching the stream to receive the value of this 819 * hash. 820 * 821 * \param stream - stream for operating with 822 * \param hash_buff - buffer for storing signaling hash. Function returns already parsed hex string. 823 * String is null-terminated. Buffer must be at least ZRTP_SIGN_ZRTP_HASH_LENGTH bytes length. 824 * \param hash_buff_length - buffer length in bytes, non less than ZRTP_SIGN_ZRTP_HASH_LENGTH bytes. 825 * \return: 826 * - zrtp_status_ok if the operation finished successfully 827 * - one of the errors otherwise 828 * \sa 829 * - ZRTP RFC. sec 8; 830 * - zrtp_signaling_hash_set() 831 */ 832 zrtp_status_t zrtp_signaling_hash_get(zrtp_stream_t* stream, 833 char* hash_buff, 834 uint32_t hash_buff_length); 835 836 /** 837 * \brief Changing the value of the secret's verification flag 838 * 839 * This function is used to change (set, unset) the secret's verification flag. zrtp_verified_set() 840 * changes the relevant internal data and stores a flag in the cache. 841 * \note 842 * Special synchronization mechanisms are provided to protect the cache from race conditions. Don't 843 * change the verified flag directly in the cache - use this function. 844 * 845 * \param zrtp - zrtp global data; 846 * \param zid1 - ZID of the first party; 847 * \param zid2 - ZID of the second party; 848 * \param verified - Boolean value of the verified flag. 849 * \return 850 * - zrtp_status_ok - if successful; 851 * - one of zrtp_status_t errors if fails. 852 */ 853 zrtp_status_t zrtp_verified_set( zrtp_global_t *zrtp, 854 zrtp_string16_t *zid1, 855 zrtp_string16_t *zid2, 856 uint8_t verified); 857 858 /** 859 * \brief Verifying the ZRTP profile 860 * 861 * zrtp_profile_check() checks the correctness of the values in the profile. The following checks 862 * are performed: 863 * - the number of components in each group does not exceed ZRTP_MAX_COMP_COUNT; 864 * - the components declared are supported by the library kernel. 865 * - presence of the set of obligatory components defined by ZRTP RFC. 866 * 867 * \param profile - ZRTP profile for validation; 868 * \param zrtp - global ZRTP context. 869 * \return 870 * - zrtp_status_ok - if profile passed all available tests; 871 * - one of ZRTP errors - if there are mistakes in the profile. See debug logging for additional 872 * information. 873 */ 874 zrtp_status_t zrtp_profile_check(const zrtp_profile_t* profile, zrtp_global_t* zrtp); 875 876 /** 877 * \brief Configure the default ZRTP profile 878 * 879 * These options are used: 880 * \code 881 * "active" is enabled; 882 * "allowclear" is disabled by default and enabled for Zfone only; 883 * "autosecure" is enabled; 884 * "disclose_bit" is disabled; 885 * cache_ttl = ZRTP_CACHE_DEFAULT_TTL defined by ZRTP RFC; 886 * 887 * [sas_schemes] = ZRTP_SAS_BASE256, ZRTP_SAS_BASE32; 888 * [cipher_types] = ZRTP_CIPHER_AES128; 889 * [pk_schemes] = ZRTP_PKTYPE_DH3072; 890 * [auth_tag_lens] = ZRTP_ATL_HS32; 891 * [hash_schemes] = ZRTP_HASH_SHA256; 892 * \endcode 893 * 894 * \param profile - ZRTP stream profile for filling; 895 * \param zrtp - libzrtp global context. 896 */ 897 void zrtp_profile_defaults(zrtp_profile_t* profile, zrtp_global_t* zrtp); 898 899 /** 900 * \brief Search for a component in the profile by ID 901 * 902 * The utility function returning the position of an element of the specified type in the profile. 903 * Used by libZRTP kernel and for external use. 904 * 905 * \param profile - ZRTP profile; 906 * \param type - sought component type; 907 * \param id - sought component ID. 908 * \return 909 * - component position - if component was found; 910 * -1 - if the component with the specified ID can't be found in profile. 911 */ 912 int zrtp_profile_find(const zrtp_profile_t* profile, zrtp_crypto_comp_t type, uint8_t id); 913 914 /* \} */ 915 916 /** 917 * \defgroup zrtp_main_rng Random Number Generation 918 * \ingroup zrtp_api 919 * \{ 920 * The generation of cryptographic key material is a highly sensitive process. To do this, you need 921 * high entropy random numbers that an attacker cannot predict. This section \ref rng gives basic 922 * knowliges andbot the RNG and it's implementation in libzrtp. 923 * \warning 924 * \ref rng \c MUST be read by every developer using libzrtp. 925 */ 926 927 /** 928 * \brief Entropy accumulation routine 929 * 930 * The random number generation scheme is described in detail in chapter \ref XXX. This function 931 * gets \c length bytes of entropy from \c buffer and hashes it into the special storage. This 932 * function should be called periodically from the user's space to increase entropy quality. 933 * \warning 934 * RNG is a very important and sensitive component of the crypto-system. Please, pay attention to 935 * \ref rng. 936 * \param zrtp - libzrtp global context; 937 * \param buffer - pointer to the buffer with entropy for accumulating; 938 * \param length - entropy size in bytes. 939 * \return: number of hashed bytes. 940 */ 941 int zrtp_entropy_add(zrtp_global_t* zrtp, const unsigned char *buffer, uint32_t length); 942 943 /** 944 * \brief Random string generation 945 * 946 * zrtp_randstr() generates \c length bytes of "random" data. We say "random" because the 947 * "randomness" of the generated sequence depends on the quality of the entropy passed to 948 * zrtp_entropy_add(). If the user provides "good" entropy, zrtp_randstr() generates sufficiently 949 * "random" data. 950 * 951 * \param zrtp - libzrtp global context; 952 * \param buffer - buffer into which random data will be generated; 953 * \param length - length of required sequence in bytes. 954 * \return 955 * - length of generated sequence in bytes or -1 in case of error 956 * \sa \ref rng 957 */ 958 int zrtp_randstr(zrtp_global_t* zrtp, unsigned char *buffer, uint32_t length); 959 960 int zrtp_randstr2(unsigned char *buffer, uint32_t length); 961 962 /* \} */ 963 964 #if defined(__cplusplus) 965 } 966 #endif 967 968 #endif /* __ZRTP_H__ */ 969