/* * libZRTP SDK library, implements the ZRTP secure VoIP protocol. * Copyright (c) 2006-2009 Philip R. Zimmermann. All rights reserved. * Contact: http://philzimmermann.com * For licensing and other legal details, see the file zrtp_legal.c. * * Viktor Krykun */ /** * \file zrtp.h * \brief Defines basic libzrtp functions and data types */ #ifndef __ZRTP_H__ #define __ZRTP_H__ #include "zrtp_config.h" #include "zrtp_base.h" #include "zrtp_error.h" #include "zrtp_types.h" #include "zrtp_protocol.h" #include "zrtp_engine.h" #include "zrtp_crypto.h" #include "zrtp_iface.h" #include "zrtp_iface_system.h" #include "zrtp_iface_scheduler.h" #include "zrtp_list.h" #include "zrtp_legal.h" #include "zrtp_log.h" #include "zrtp_srtp.h" #include "zrtp_srtp_builtin.h" #include "zrtp_string.h" #include "zrtp_pbx.h" #include "zrtp_legal.h" #include "zrtp_version.h" #include "zrtp_iface_cache.h" #include "zrtp_ec.h" /** * \defgroup zrtp_api API * * In this section the basic functions for using the library are defined. They include * initialization and deinitialization functions, functions for session and stream management and * functions for RTP traffic management. * * In most cases this section is all you need to start working with libzrtp. The typical simplified * order of operations in using libzrtp is the following: * -# library configuration * -# library initialization; * -# ZRTP session creation and configuration; * -# ZRTP stream attaching and Protocol initiation; * -# RTP stream processing; * -# ZRTP protocol stopping and releasing resources. * For each of these actions there is a set of corresponding functions. * \sa * - \ref howto * - \ref XXX_GUIDE */ /*======================================================================*/ /* Public ZRTP libzrtp datatypes */ /*======================================================================*/ /** * \defgroup zrtp_types Types and Definitions * \ingroup zrtp_api * The data types used in libzrtp are defined in this section * \{ * */ /** * \typedef typedef uint32_t zrtp_id_t; * \brief libzrtp general identifier used to debug connections management. * \ingroup zrtp_main_init */ /** Length of "zrtp-hash-value", RFC 6189 sec 8. @sa zrtp_signaling_hash_get(); */ #define ZRTP_SIGN_ZRTP_HASH_LENGTH (ZRTP_MESSAGE_HASH_SIZE*2) /** * \brief Enumeration for ZRTP Licensing modes * \ingroup zrtp_main_init * * A ZRTP endpoint that is Passive will never send a Commit message, which means that it cannot be * the initiator in the ZRTP exchange. Since at least one of the two parties must be the initiator, * two Passive endpoints cannot make a secure connection. However, a non-Passive ZRTP endpoint can * send a Commit message, enabling it to act as the initiator in a ZRTP exchange. This allows it to * make a secure connection to a Passive endpoint, or to another non-Passive endpoint. * * In addition, a Passive ZRTP endpoint declares that it is Passive by setting the passive flag in * the Hello message, which means the other party will recognize it as Passive. This allows for a * Passive mode and two forms of Active mode-- Active, or Unlimited. These three possible behaviors * for a ZRTP endpoint are defined as: * - \b Passive: Never send a Commit message, and thus can never be the initiator. * - \b Active: Will send a Commit message, but only to non-Passive ZRTP partners. * - \b Unlimited: Will send a Commit message to any ZRTP partner, Passive or non-Passive. * * This can be used to provide three classes of service, which can be licensed t different price * points. Passive can be used in freeware for widest possible deployment, Active can be used in * discount products that can only talk to non-freeware, and Unlimited can be used in full-price * products that will benefit from the network effect of widely deployed Passive freeware. */ typedef enum zrtp_license_mode_t { /** @brief Never send a Commit message, and thus can never be the initiator. */ ZRTP_LICENSE_MODE_PASSIVE = 0, /** @brief Will initiate ZRTP exchange, but only to non-Passive ZRTP partners. */ ZRTP_LICENSE_MODE_ACTIVE, /** @brief Will send a Commit message to any ZRTP partner, Passive or non-Passive. */ ZRTP_LICENSE_MODE_UNLIMITED } zrtp_license_mode_t; /** * @brief Enumeration to define Signaling initiator/responder roles. * * Used by libzrtp to optimize some internal processes and protocol handshake. * * @sas zrtp_stream_start(). */ typedef enum zrtp_signaling_role_t { /** @brief Unknown Signaling role, should be used when the app can't determine the role. */ ZRTP_SIGNALING_ROLE_UNKNOWN = 0, /** @brief Signaling Initiator. */ ZRTP_SIGNALING_ROLE_INITIATOR, /** @brief Signaling Responder. */ ZRTP_SIGNALING_ROLE_RESPONDER, ZRTP_SIGNALING_ROLE_COUNT } zrtp_signaling_role_t; /** @brief 12-byte ZID for unique ZRTP endpoint identification. */ typedef unsigned char zrtp_zid_t[12]; /** \brief 16-byte ID for ZRTP endpoint's software identification. */ typedef char zrtp_client_id_t[16]; /** * @brief ZRTP global configuration options * @ingroup zrtp_main_init * @warning Use \ref zrtp_config_defaults() before start configuring this structure. */ typedef struct zrtp_config_t { /** @brief Symbolic client identifier */ zrtp_client_id_t client_id; /** @brief libzrtp license mode defined protocol behavior */ zrtp_license_mode_t lic_mode; /** @brief Set this flag to 1 if you product is MiTM box */ uint8_t is_mitm; /** @brief Set of interfaces required to operate with libzrtp */ zrtp_callback_t cb; /** @brief Path to zrtp cache file (set if you use built-in realization) */ zrtp_string256_t def_cache_path; /** * @brief Flush the cache automatically * Set to 1 if you want libzrtp to flush the cache to the persistent storage * right after it is modified. If cache_auto_store is 0, libzrtp will flush * the cache on going down only and the app is responsible for storing the * cache in unexpected situations. Enabled by default. * * @sa zrtp_def_cache_store() */ unsigned cache_auto_store; } zrtp_config_t; /** * \brief zrtp stream information structure * \ingroup zrtp_main_management * * libzrtp, since v0.80 takes data encapsulating approach and hides all private data inside * zrtp_stream_t structure. Developers shouldn't access them directly. \ref zrtp_stream_get() should * be used instead to fill zrtp_stream_info_t structure. zrtp_stream_info_t contains all needed * information in safe and easy to use form. */ struct zrtp_stream_info_t { /** \brief Stream unique identifier for debug purposes */ zrtp_id_t id; /** \brief Pointer to the parent zrtp session */ zrtp_session_t* session; /** \brief Stream mode. Defines libzrtp behavior related to specified contexts. */ zrtp_stream_mode_t mode; /** \brief Defines ZRTP Trusted mitm mode for the current session. */ zrtp_mitm_mode_t mitm_mode; /** \brief Reflects current state of ZRTP protocol */ zrtp_state_t state; /** * \brief Last protocol error code * * Available for reading in ERROR state on zrtp_security_event_t#ZRTP_EVENT_PROTOCOL_ERROR. */ zrtp_protocol_error_t last_error; /** * \brief Remote passive flag * * This flag shows when remote side is "passive" (has license mode PASSIVE) available in CLEAR * state and later. */ uint8_t peer_passive; /** * \brief Allowclear flag. * * Current value of "allowclear" option exchanged during ZRTP negotiation. Available in SECURE * state. */ uint8_t res_allowclear; /** * \brief Peer disclose bit flag * * Indicates the ability of the remote side to disclose its session key. Specifies that the * remote side allows call monitoring. If this flag is set, the end user must be informed. It * can be read in the SECURE state. */ uint8_t peer_disclose; /** * \brief Defines that remote party is ZRTP MiTM endpoint * * Enabled by (Asterisk PBX, UMLab SIP Firewall or etc.) Available for reading in CLEAR state * ande later. */ uint8_t peer_mitm; }; /** * \brief zrtp session information structure * \ingroup zrtp_main_management * libzrtp, since v0.80 takes data incapsulating approach and hides all private date inside * zrtp_session_t structure. Developers shouldn't access them directly. \ref zrtp_session_get() * should be used instead to fill zrtp_session_info_t structure. zrtp_session_info_t contains all * needed information in safe and easy to use form. */ struct zrtp_session_info_t { /** \brief Session unique identifier for debug purposes */ zrtp_id_t id; /** * \brief Local ZID * The unique 12-characters string that identifies the local ZRTP endpoint.This ID allows remote * peers to recognize this ZRTP endpoint. */ zrtp_string16_t zid; /** * \brief Remote ZID * * Extracted from the Hello packet of the very first ZRTP stream. Uniquely identifies the remote * ZRTP peer. */ zrtp_string16_t peer_zid; /** \brief Character name identified remote ZRTP endpoint.*/ zrtp_string16_t peer_clientid; /** \brief ZRTP Protocol version supported by the remote endpoint. */ zrtp_string16_t peer_version; /** * \brief Indicates that SAS related data is available for reading. * \note * As SAS is computed in SECURE state only, it may contain unknown values in other states. Check * sas_is_ready before displaying SAS to the user. */ uint8_t sas_is_ready; /** \brief First Short Authentication String */ zrtp_string16_t sas1; /** * \brief Second Short Authentication string. * \note * Second SAS is available for \c base256 authentication only (\c sas_is_base256 is set). In * other case, \c sas1 contains \c base32 value and \c sas2 is empty. */ zrtp_string16_t sas2; /** \brief Binary SAS digest (ZRTP_SAS_DIGEST_LENGTH bytes) */ zrtp_string32_t sasbin; /** * \brief Bit-map to summarize shared secrets "Cached" flags. * * 1 at appropriate bit means that the secrets was found in the cache and restored successfully. * Value equal to 0 indicates that secret for the remote endpoint was not found in the cache * and was generated randomly. * Use ZRTP_BIT_RS1, ZRTP_BIT_RS2, ZRTP_BIT_AUX and ZRTP_BIT_PBX bit-masks to get "cached" value * for the appropriate secret. */ uint32_t cached_flags; /** * \brief Bit-map to summarize shared secrets "Matched" flags. * * 1 at appropriate bit means that the secret, locally computed by your ZRTP endpoint is equal * to the secret, received from the remote endpoint. Secrets may not match if one of the * endpoints doesn't use cache of the shared secrets, if the cache was deleted or in case of * an attack. * Use ZRTP_BIT_RS1, ZRTP_BIT_RS2, ZRTP_BIT_AUX and ZRTP_BIT_PBX bit-masks to get "cached" value * for the appropriate secret. */ uint32_t matches_flags; /** * \brief Bit-map to summarize shared secrets "Wrong" flags. * * 1 at appropriate bit means that the secret was restored from the cache, but doesn't match * to the remote endpoint's secret. Such situation may happen if the remote endpoint lost cache * or in case of attach. * Use ZRTP_BIT_RS1, ZRTP_BIT_RS2, ZRTP_BIT_AUX and ZRTP_BIT_PBX bit-masks to get "cached" value * for the appropriate secret. */ uint32_t wrongs_flags; /** * \brief SAS Verification flag. * * The SAS Verified flag (V) is set based on the user indicating that SAS comparison has been * successfully performed. Each party sends the SAS Verified flag from the previous session in * the Confirm message of the current session. * \sa * - ZRTP RFC section. "7.1. SAS Verified Flag" for more information about Verification Flag. * - zrtp_verified_set() */ uint32_t sas_is_verified; /** \brief Indicates base256 SAS encoding */ uint8_t sas_is_base256; /** * \brief actual lifetime of the secrets * * This variable contains the interval for retaining secrets within an established session. In * accordance with ZRTP RFC this value is calculated as the minimal of local and remote TTLs * after confirmation. Value is given in seconds and can be read in the SECURE state. */ uint32_t secrets_ttl; /** \brief Hash crypto component name used in ZRTP calculations. */ zrtp_string32_t hash_name; /** \brief Cipher crypto component name used in ZRTP encryption. */ zrtp_string32_t cipher_name; /** \brief SRTP Authentication crypto component name used in ZRTP exchange. */ zrtp_string32_t auth_name; /** \brief SAS scheme crypto component name used in ZRTP exchange. */ zrtp_string32_t sas_name; /** \brief Publik Key Exchange name used in ZRTP exchange. */ zrtp_string32_t pk_name; }; /* \} */ /*======================================================================*/ /* libzrtp Public API: Streams management */ /*======================================================================*/ #if defined(__cplusplus) extern "C" { #endif /** * \defgroup zrtp_main_init Initalization and Configuration * \ingroup zrtp_api * \{ */ /** * \brief Initializes libzrtp global config * * zrtp_config_defaults() prepares all fields of zrtp_config_t for further usage in zrtp_init(). * This function allocates all necessary resources and initialize zrtp_config_t#cb with default * implementations. * * \param config - libzrtp config for initialization. * \warning this function must be used before start operating with the config. */ void zrtp_config_defaults(zrtp_config_t* config); /** * \brief Initializing libzrtp * * This function initializes the library and all its components. zrtp_init() initialize global data * for all sessions and streams. Fields of the global zrtp context are initialized automatically and * shouldn't be modified. For correct memory management, global context should be released by * calling zrtp_down(). * * \param config - libzrtp inital parameters * \param zrtp - out parameter, pointer to allocated zrtp global context structure; * \warning this function \b must be called before any operation with libzrtp. * \return * - zrtp_status_ok in successfully initialized or one of zrtp status errors in other case. * \sa zrtp_down() */ zrtp_status_t zrtp_init(zrtp_config_t* config, zrtp_global_t** zrtp); /*! * \brief Shutting down the library * * Frees all allocated structures and resources. This function \b must be called at the end of use * to stop libzrtp correctly. zrtp_down() doesn't stop in-progress ZRTP streams. To avoid mistakes, * close all sessions before library deinitialization. * * \param zrtp - global ZRTP context previously allocated by zrtp_init(); * \return * - zrtp_status_ok if successfully shut down; * - zrtp_status_fail if an error occurred. * \sa zrtp_init() */ zrtp_status_t zrtp_down(zrtp_global_t* zrtp); /* \} */ /** * \defgroup zrtp_main_management ZRTP Connections * \ingroup zrtp_api * \{ */ /** * \brief ZRTP Session Initialization. * * This function allocates and initializes the internal session context data. The given context is * associated with the specified ZRTP identifier. Only after initialization does the session contain * ZRTP_MAX_STREAMS_PER_SESSION streams ready to be used. * * After successfully initialization, configuration will be done according to the relevant profile * \c profile. Profile will be applyed to every stream allocated within this session. Before using * the profile, call zrtp_profile_check() function to make sure that the profile you are applying * is correct. * * \warning Don't call zrtp_session_init() in parallel with other operations on this session. * \param zrtp - global libzrtp context; * \param profile - the session configuration profile. If value of this parameter is NULL, default * profile will be used. NULL profile usage is equivalent to calling zrtp_profile_defaults(). * \param zid - ZRTP peer identificator. * \param role - identifies if the endpoint was the signaling initiator of the call. Used to * provide Passive Mode options to the developer. If your application doesn't control signaling * or you don't want to support Passive Mode features - set it to ZRTP_SIGNALING_ROLE_UNKNOWN. * \param session - allocated session structure. * \return * - zrtp_status_ok if initialization is successful; * - zrtp_status_fail if an error occurs. * \sa zrtp_session_down() */ zrtp_status_t zrtp_session_init( zrtp_global_t* zrtp, zrtp_profile_t* profile, zrtp_zid_t zid, zrtp_signaling_role_t role, zrtp_session_t **session); /** * \brief ZRTP Session context deinitialization * * This function releases all resources allocated for internal context operations by zrtp_init(). * * \warning Don't call zrtp_session_init() in parallel with other operations on this session. * \param session - session for deinitialization. * \sa zrtp_session_init() */ void zrtp_session_down(zrtp_session_t *session); /** * \brief Obtain information about ZRTP session * * Function initialize and fills all fields of zrtp_session_info_t structure according to * the current state of ZRTP session. * * \param session - zrtp session which parameters should be extracted; * \param info - out structure to be initialized. * \return * - zrtp_status_ok in case of success. * - zrtp_status_fail if an error occurs. */ zrtp_status_t zrtp_session_get(zrtp_session_t *session, zrtp_session_info_t *info); /** * \brief Allow user to associate some data with current zrtp session. * \param session - zrtp session to attach data to. * \param udata - pointer to the user-data context. * \sa zrtp_session_get_userdata() */ void zrtp_session_set_userdata(zrtp_session_t *session, void* udata); /** * \brief Return user data associated with the zrtp session * \param session - zrtp session to extract user data. * \return * - pointer to the user-data context previously set by zrtp_session_set_userdata(). * - NULL if the user data unavailable. * \sa zrtp_session_set_userdata() */ void* zrtp_session_get_userdata(zrtp_session_t *session); /** * \brief Attaching a new stream to the session * * This function call initializes a ZRTP stream and prepares it for use within the specified * session. The maximum number of streams for one session is defined by the * ZRTP_MAX_STREAMS_PER_SESSION variable. All newly created streams are equivalent and have * ZRTP_STREAM_MODE_CLEAR mode and ZRTP_ACTIVE state. Only after attaching a stream, ZRTP protocol * can be initiated. * * \param session - the ZRTP session within which a new stream is to be * \param stream - out parameter, attached stream will be stored there * \return * - zrtp_status_ok if stream was attached successfully * - one of zrtp_status_t errors in case of failure * \sa zrtp_stream_start() zrtp_stream_stop() */ zrtp_status_t zrtp_stream_attach(zrtp_session_t *session, zrtp_stream_t** stream); /** * \brief Starting a ZRTP stream * * ZRTP stream setup is initiated by calling this function. Exchange of command packets begins * immediately according to protocol. If the option "autosecure" is on, calling this function is the * only requirement for setting up the ZRTP connection within a stream. If "autosecure" mode is not * available, calling this function activates only connection within a ZRTP stream. A connection can * be established manually later by calling zrtp_stream_secure(). * * Setup of the stream/connection takes a certain interval of time. This function just initiates * this process. The system of callbacks informs the user about the progress of libzrtp protocol. * * \param stream - ZRTP stream to be started. * \param ssrc - ssrc which will be used in ZRTP protocol messages. It should match with ssrc of * appropriate RTP stream which will be encrypted by this ZRTP stream. * \return * - zrtp_status_ok in case of success; * - one of zrtp_status_t errors in case of failure * \sa * - \ref XXX_GUIDE_CB \ref XXX_GUIDE_MANAGEMENT * - zrtp_stream_stop() zrtp_stream_secure() zrtp_stream_clear() */ zrtp_status_t zrtp_stream_start(zrtp_stream_t* stream, uint32_t ssrc); /** * \brief ZRTP protocol stopping * * This function stops all protocol operations for the specified stream, releases resources * allocated on the zrtp_stream_start() and prepares the stream structure for the next use. * * This function will stop the protocol at any stage: all delayed tasks are canceled, and the * protocol packet exchange and encryption is stopped. After this function call it is necessary to * stop processing traffic using the zrtp_process_xxx() function. * * \param stream - the stream being shutdown. * \return * - zrtp_status_ok in case of success; * - one of zrtp_status_t errors in case of failure * \sa * - \ref XXX_GUIDE_CB \ref XXX_GUIDE_MANAGEMENT * - zrtp_stream_start() zrtp_stream_secure() zrtp_stream_clear() */ zrtp_status_t zrtp_stream_stop(zrtp_stream_t* stream); /*! * \brief Initiating an interruption of the secure connection * * This function initiates the shutting down of the ZRTP connection within a stream. In other words, * after successfully switching to secure mode (\ref XXX SECURE state, fig. 1.5), calling this * function begins the exchange of packets switching back to insecure (CLEAR) mode. * * This function can only be implemented from the SECURE state. Attempt to call this function from * any other state will end in failure. The client application is informed about protocol * progress through a system of callbacks. * * \param stream - ZRTP stream . * \return * - zrtp_status_ok - if shutting down the connection is started successfully. * - zrtp_status_fail - if shutting down the connection is initiated from an incorrect state. * \sa * - \ref XXX_GUIDE_CB \ref XXX_GUIDE_MANAGEMENT * - zrtp_stream_start() zrtp_stream_secure() zrtp_stream_clear() */ zrtp_status_t zrtp_stream_clear(zrtp_stream_t *stream); /** * \brief Initiating a secure connection setup * * The function initiates a ZRTP connection setup within a stream. In other words, after the * protocol has started and Discovery phase have been successfully accomplished, calling this * function will begin the exchange of packets for switching to SECURE mode. * * This function can be successfully performed only from the CLEAR state (\ref XXX Figure 1.6). * Attempting to call this function from any other state will result in failure. The client * application is informed about protocol progress through a system of callbacks. * * \param stream - ZRTP stream to be secured. * \return * - zrtp_status_ok - if switching to secure mode started successfully. * - zrtp_status_fail - if switching to secure mode is initiated from a state other than CLEAR. * \sa * - \ref XXX_GUIDE_CB \ref XXX_GUIDE_MANAGEMENT. * - zrtp_stream_start() zrtp_stream_clear(). */ zrtp_status_t zrtp_stream_secure(zrtp_stream_t *stream); /** * \brief Obtain information about zrtp stream * * Function initialize and fills all fields of zrtp_stream_info_t structure accordint to * current state of zrtp stream. * * \param stream - zrtp stream which parameters should be extracted * \param info - out structure to be initialized * \return * - zrtp_status_ok in case of success. * - zrtp_status_fail if an error occurs. */ zrtp_status_t zrtp_stream_get(zrtp_stream_t *stream, zrtp_stream_info_t *info); /** * @brief Allow user to associate some data with zrtp stream. * @param stream - zrtp stream to attach data to. * @param udata - pointer to the user-data context. * @sa zrtp_stream_get_userdata() */ void zrtp_stream_set_userdata(zrtp_stream_t *stream, void* udata); /** * \brief Return user data associated with the zrtp stream * \return * - pointer to the user-data context previously set by zrtp_stream_set_userdata() * - NULL if user data unavailable; * \sa zrtp_stream_set_userdata() */ void* zrtp_stream_get_userdata(const zrtp_stream_t *stream); /* \} */ /*======================================================================*/ /* libzrtp Public API: Encryption */ /*======================================================================*/ /** * \defgroup zrtp_main_proto Traffic Processing * \ingroup zrtp_api * \{ */ /** * \brief Processing outgoing RTP packets * * This is the main function for processing outgoing RTP packets. As soon as the protocol is * started, each outgoing RTP packet (not encrypted) has to go through this function. * * It performs different actions depending on the connection state and packet type: * - In setup ZRTP connection mode, it encrypts outgoing RTP packets. The packet is encrypted right * in the transferred buffer; * - Protects codec and data privacy by deleting certain packets from the stream. In this case the * body and the length of the packet remain unchanged. * * \param stream - ZRTP stream to process RTP packet; * \param packet - buffer storing the RTP packet for encryption. After processing, the encrypted * packet is stored in the same buffer. * \param length - the length of the buffered packet. After processing, the length of encrypted * packet is stored here. * \warning During encryption, the data length increases in comparison to the source data. Because * the function uses the same buffer both for incoming and resulting values, the length of the * buffer must be larger than size of source packet. * \return * - zrtp_status_ok if encryption is successful. The packet should be sent to the recipient. * - zrtp_status_fail if there was an error during encryption. The packet should be rejected. * - zrtp_status_drop if there was interference in the VoIP client codec protection mechanism. The * packet should be rejected. * \sa zrtp_process_srtp() zrtp_process_rtcp() zrtp_process_srtcp() */ zrtp_status_t zrtp_process_rtp( zrtp_stream_t *stream, char* packet, unsigned int* length); /** * \brief Processing incoming RTP packets * * This is the main function for incoming RTP packets processing. It is an analogue of * zrtp_process_rtp() but for an incoming stream. After the protocol is started, each (encrypted) * incoming RTP packet has to go through this function. * * It performs different actions depending on the connection state and packet type: * - during setup/interruption of ZRTP connection, processes incoming protocol packets. The body * and length of the packet remain unchanged; * - in setup ZRTP connection mode, decrypts incoming RTP packet. The packet is decrypted right in * the transferred buffer; * - protects codec and data privacy by deleting certain packets from the stream. In this case the * body and the length of the packet remain unchanged. * * \param stream - ZRTP stream for processing * \param packet - buffer storing the packet for decrypting. After processing, the decrypted packet * is stored in the same buffer; * \param length - the length of the buffered packet. After processing, the length of decrypted * packet is stored here; * \return * - zrtp_status_ok if decrypting is successful. Such a packet should be sent to the recipient; * - zrtp_status_fail if an error occurred during decrypting or command packet processing. The * packet should be rejected; * - zrtp_status_drop if the command packet processing is successful or if there was interference * in the VoIP client codec protection mechanism. The packet should be rejected in either case; * \sa zrtp_process_rtp() zrtp_process_rtcp() zrtp_process_srtcp() */ zrtp_status_t zrtp_process_srtp( zrtp_stream_t *stream, char* packet, unsigned int* length); /*! * \brief Processing outgoing RTCP packets * * This is the main function for processing outgoing RTCP packets. The function behavior is similar * to that of zrtp_process_rtp(): * - In SECURE mode, encrypts outgoing RTCP packets. The packet is encrypted right in the * transferred buffer. The length of encrypted packet is returned in the \c length variable; * - protects codec and data privacy by deleting certain packets from the stream. In this case the * body and the length of the packet remain unchanged. * * \param stream - ZRTP session for processing; * \param packet - buffer storing RTCP packet; * \param length - length of the buffered packet. * \return * - zrtp_status_ok if encryption is successful. The packet should be sent to the recipient. * - zrtp_status_fail if there was an error during encryption. The packet should be rejected. * - zrtp_status_drop if there was interference in the VoIP client codec protection mechanism. The * packet should be rejected. * \sa zrtp_process_srtp() zrtp_process_rtp() zrtp_process_srtcp() */ zrtp_status_t zrtp_process_rtcp( zrtp_stream_t *stream, char* packet, unsigned int* length); /** * \brief Processing incoming RTCP packets * * This is the main function for processing incoming RTCP packets. The function behavior is similar * to that of zrtp_process_srtp(): * - In SECURE mode, decrypts incoming RTCP packets. The packet is decrypted right in the * transferred buffer. The length of the encrypted packet is returned in the \c length variable; * - In transition states, drops all incoming RTCP traffic. In this case the body and the length of * the packet remain unchanged. * * \param stream - ZRTP stream for processing; * \param packet - buffer storing the RTCP packet; * \param length - length of the buffered packet. * \return * - zrtp_status_ok if decrypting is successful. Such a packet should be sent to the recipient; * - zrtp_status_drop if the command packet processing is successful or if there was interference * in the VoIP client codec protection mechanism. The packet should be rejected in either case; * - zrtp_status_fail if there was an error during encryption. The packet should be rejected. * \sa zrtp_process_srtp() zrtp_process_rtp() zrtp_process_rtcp() */ zrtp_status_t zrtp_process_srtcp( zrtp_stream_t *stream, char* packet, unsigned int* length); /* \} */ /** * \defgroup zrtp_main_utils Utilities * \ingroup zrtp_api * \{ */ /** * \brief Specifies the hash of the peer Hello message for verification. * * In accordance with the ZRTP RFC sec. 9, this protocol can prevent DOS attacks by verification of * the Hello message hash sent through the signaling protocol. * * This function allows the user to specify the Hello hash for verification. If after the * discovering phase the Hello hashes don't match, libzrtp raises the * zrtp_event_t#ZRTP_EVENT_WRONG_SIGNALING_HASH event. This function should only be called before * starting the protocol from the ZRTP_STATE_ACTIVE state. * * \param stream - stream for operating with; * \param hash_buff - signaling hash buffer. Function accepts string, not a binary value!; * \param hash_buff_length - signaling hash length in bytes, must be ZRTP_SIGN_ZRTP_HASH_LENGTH bytes; * \return: * - zrtp_status_ok if the operation finished successfully * - one of the errors otherwise * \sa * - ZRTP RFC. sec 8; * - zrtp_signaling_hash_get() */ zrtp_status_t zrtp_signaling_hash_set( zrtp_stream_t* stream, const char *hash_buff, uint32_t hash_buff_length); /** * \brief Returns the hash of the Hello message to be transferred in signaling. * * To prevent DOS attacks, the hash of the Hello message may be sent through signaling. * zrtp_signaling_hash_get() may be called after attaching the stream to receive the value of this * hash. * * \param stream - stream for operating with * \param hash_buff - buffer for storing signaling hash. Function returns already parsed hex string. * String is null-terminated. Buffer must be at least ZRTP_SIGN_ZRTP_HASH_LENGTH bytes length. * \param hash_buff_length - buffer length in bytes, non less than ZRTP_SIGN_ZRTP_HASH_LENGTH bytes. * \return: * - zrtp_status_ok if the operation finished successfully * - one of the errors otherwise * \sa * - ZRTP RFC. sec 8; * - zrtp_signaling_hash_set() */ zrtp_status_t zrtp_signaling_hash_get(zrtp_stream_t* stream, char* hash_buff, uint32_t hash_buff_length); /** * \brief Changing the value of the secret's verification flag * * This function is used to change (set, unset) the secret's verification flag. zrtp_verified_set() * changes the relevant internal data and stores a flag in the cache. * \note * Special synchronization mechanisms are provided to protect the cache from race conditions. Don't * change the verified flag directly in the cache - use this function. * * \param zrtp - zrtp global data; * \param zid1 - ZID of the first party; * \param zid2 - ZID of the second party; * \param verified - Boolean value of the verified flag. * \return * - zrtp_status_ok - if successful; * - one of zrtp_status_t errors if fails. */ zrtp_status_t zrtp_verified_set( zrtp_global_t *zrtp, zrtp_string16_t *zid1, zrtp_string16_t *zid2, uint8_t verified); /** * \brief Verifying the ZRTP profile * * zrtp_profile_check() checks the correctness of the values in the profile. The following checks * are performed: * - the number of components in each group does not exceed ZRTP_MAX_COMP_COUNT; * - the components declared are supported by the library kernel. * - presence of the set of obligatory components defined by ZRTP RFC. * * \param profile - ZRTP profile for validation; * \param zrtp - global ZRTP context. * \return * - zrtp_status_ok - if profile passed all available tests; * - one of ZRTP errors - if there are mistakes in the profile. See debug logging for additional * information. */ zrtp_status_t zrtp_profile_check(const zrtp_profile_t* profile, zrtp_global_t* zrtp); /** * \brief Configure the default ZRTP profile * * These options are used: * \code * "active" is enabled; * "allowclear" is disabled by default and enabled for Zfone only; * "autosecure" is enabled; * "disclose_bit" is disabled; * cache_ttl = ZRTP_CACHE_DEFAULT_TTL defined by ZRTP RFC; * * [sas_schemes] = ZRTP_SAS_BASE256, ZRTP_SAS_BASE32; * [cipher_types] = ZRTP_CIPHER_AES128; * [pk_schemes] = ZRTP_PKTYPE_DH3072; * [auth_tag_lens] = ZRTP_ATL_HS32; * [hash_schemes] = ZRTP_HASH_SHA256; * \endcode * * \param profile - ZRTP stream profile for filling; * \param zrtp - libzrtp global context. */ void zrtp_profile_defaults(zrtp_profile_t* profile, zrtp_global_t* zrtp); /** * \brief Search for a component in the profile by ID * * The utility function returning the position of an element of the specified type in the profile. * Used by libZRTP kernel and for external use. * * \param profile - ZRTP profile; * \param type - sought component type; * \param id - sought component ID. * \return * - component position - if component was found; * -1 - if the component with the specified ID can't be found in profile. */ int zrtp_profile_find(const zrtp_profile_t* profile, zrtp_crypto_comp_t type, uint8_t id); /* \} */ /** * \defgroup zrtp_main_rng Random Number Generation * \ingroup zrtp_api * \{ * 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 \ref rng gives basic * knowliges andbot the RNG and it's implementation in libzrtp. * \warning * \ref rng \c MUST be read by every developer using libzrtp. */ /** * \brief Entropy accumulation routine * * The random number generation scheme is described in detail in chapter \ref XXX. This function * gets \c length bytes of entropy from \c buffer and hashes it into the special storage. This * function should be called periodically from the user's space to increase entropy quality. * \warning * RNG is a very important and sensitive component of the crypto-system. Please, pay attention to * \ref rng. * \param zrtp - libzrtp global context; * \param buffer - pointer to the buffer with entropy for accumulating; * \param length - entropy size in bytes. * \return: number of hashed bytes. */ int zrtp_entropy_add(zrtp_global_t* zrtp, const unsigned char *buffer, uint32_t length); /** * \brief Random string generation * * zrtp_randstr() generates \c length bytes of "random" data. We say "random" because the * "randomness" of the generated sequence depends on the quality of the entropy passed to * zrtp_entropy_add(). If the user provides "good" entropy, zrtp_randstr() generates sufficiently * "random" data. * * \param zrtp - libzrtp global context; * \param buffer - buffer into which random data will be generated; * \param length - length of required sequence in bytes. * \return * - length of generated sequence in bytes or -1 in case of error * \sa \ref rng */ int zrtp_randstr(zrtp_global_t* zrtp, unsigned char *buffer, uint32_t length); int zrtp_randstr2(unsigned char *buffer, uint32_t length); /* \} */ #if defined(__cplusplus) } #endif #endif /* __ZRTP_H__ */