freeswitch/libs/libzrtp/include/zrtp.h

/*
 * 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 <v.krikun at zfoneproject.com> 
 */

/**
 * \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__ */