libzrtp: libZRTP main functions

Collaboration diagram for libZRTP main functions:


Functions
void	zrtp_config_defaults (zrtp_config_t *config)
	Initializes libzrtp global config zrtp_config_defaults prepares all fields of zrtp_config_t for further usage. If the developer uses "enterprise" version of the libzrtp - zrtp_config_t::cb will be initialized with built-in realizations.
zrtp_global_ctx_t *	zrtp_init (zrtp_config_t *config)
	Initializing libzrtp This function initializes the library and all its components. libzrtp will upload all available crypto-components implementations: hash type calculation scheme (ZRTP_HASH_SHA256) encryption schemes (ZRTP_CIPHER_AES128, ZRTP_CIPHER_AES256); public key exchange scheme (ZRTP_PKTYPE_PRESH, ZRTP_PKTYPE_DH3072, ZRTP_PKTYPE_DH4096); SAS schemes (ZRTP_SAS_BASE32, ZRTP_SAS_BASE256); authentication schemes (ZRTP_ATL_HS32, ZRTP_ATL_HS80). zrtp_init() initialize global data for all sessions and streams. Fields of the global context are initialized automatically and shouldn't be modified. For correct memory management, global context should be released by calling zrtp_down().
zrtp_status_t	zrtp_down (zrtp_global_ctx_t *zrtp_global)
	Shutting down the ZRTP library Frees all allocated structures and resources. This function 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.
zrtp_status_t	zrtp_init_session_ctx (zrtp_conn_ctx_t session_ctx, zrtp_global_ctx_t zrtp_global, zrtp_profile_t *profile, zrtp_zid_t zid, uint8_t is_initiator)
	ZRTP Session context initialization. As explained in 3. Data structures, the session context is created in two steps: memory allocation for the external structure and internal data 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 `profile`. Profile will be applyed to every stream allocated within this session. Profile must contain lists of the crypto-components and other required information. Applying the profile entails: filling of all necessary structures; HELLO packet construction; priority range specification in the crypto components usage. Before the applying the profile, call zrtp_check_profile() function to make sure that the profile you are applying correct.
void	zrtp_done_session_ctx (zrtp_conn_ctx_t *ctx)
	ZRTP Session context deinitialization Session context deinitialization also requires two steps: deinitializing internal context data and releasing upper-level structure memory. This function releases all resources allocated for internal context operations. The upper-level structure can be destroyed only after calling this function.
zrtp_stream_ctx_t *	zrtp_attach_stream (zrtp_conn_ctx_t *session_ctx, uint32_t rtp_ssrc)
	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 types::ZRTP_MAX_STREAMS_PER_SESSION variable. All newly created streams are equivalent and have ZRTP_STREAM_MODE_CLEAR type mode. Only after attaching a stream can the ZRTP protocol be initiated.
zrtp_status_t	zrtp_set_signaling_hash (zrtp_stream_ctx_t stream_ctx, const char hash_buff, uint32_t hash_buff_length)
	Specifies the hash of the peer Hello message for verification. In accordance with the ZRTP ID sec. 9.1, 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.
zrtp_status_t	zrtp_get_signaling_hash (zrtp_stream_ctx_t stream_ctx, char hash_buff, uint32_t hash_buff_length)
	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_get_signaling_hash() may be called after attaching the stream to receive the value of this hash.
void	zrtp_start_stream (zrtp_stream_ctx_t *stream_ctx)
	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 first ZRTP connection within a stream. If "autosecure" mode is not available, calling this function activates only ZRTP stream. A connection can be activated manually by calling zrtp_secure_stream(). Within one stream several ZRTP connections can be setup and interrupted consecutively by calling zrtp_secure_stream() and zrtp_clear_stream(). 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. Stream and connection initialization are described in section 7 Connection life-cycle and management in detail.
void	zrtp_stop_stream (zrtp_stream_ctx_t *stream_ctx)
	ZRTP protocol stopping This function stops all protocol operations for the specified stream, releases resources allocated on the zrtp_start_stream() 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.
zrtp_status_t	zrtp_clear_stream (zrtp_stream_ctx_t *stream_ctx)
	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 (SECURE state, fig. 1.5), calling this function begins the exchange of packets switching 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.
zrtp_status_t	zrtp_secure_stream (zrtp_stream_ctx_t *stream_ctx)
	Initiating a secure connection setup The function initiates a ZRTP connection setup within a stream. In other words, after the protocol has started and HELLO packets are successfully exchanged, 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 (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.
zrtp_status_t	zrtp_process_rtp (zrtp_stream_ctx_t stream_ctx, char packet, unsigned int *length)
	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.
zrtp_status_t	zrtp_process_srtp (zrtp_stream_ctx_t stream_ctx, char packet, unsigned int *length)
	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. .
zrtp_status_t	zrtp_process_rtcp (zrtp_stream_ctx_t stream_ctx, char packet, unsigned int *length)
	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 `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.
zrtp_status_t	zrtp_process_srtcp (zrtp_stream_ctx_t stream_ctx, char packet, unsigned int *length)
	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 `length` variable; In transition states, drops all incoming RTCP traffic. In this case the body and the length of the packet remain unchanged.
zrtp_status_t	zrtp_set_verified (zrtp_global_ctx_t zrtp, zrtp_string16_t zid1, zrtp_string16_t *zid2, uint8_t verified)
	Changing the value of the secret's verification flag This function is used to change (set, unset) the secret's verification flag. zrtp_set_verified() changes the relevant internal data and stores a flag in the cache. 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.
zrtp_status_t	zrtp_check_profile (const zrtp_profile_t profile, zrtp_global_ctx_t zrtp_global)
	Verifying the ZRTP profile zrtp_check_profile() checks the correctness of the values in the profile. This function is called automatically when zrtp_apply_profile() is called. 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 Internet Draft.
void	zrtp_profile_autoload (zrtp_profile_t profile, zrtp_global_ctx_t zrtp_global)
	Configure the default ZRTP profile These options are used:.
int	zrtp_find_in_profile (const zrtp_profile_t *profile, zrtp_crypto_comp_t type, uint8_t id)
	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.
int	zrtp_add_entropy (zrtp_global_ctx_t zrtp_global, const unsigned char buffer, uint32_t length)
	Entropy accumulation The random number generation scheme is described in detail in chapter 5 Random number generation. This function gets `length` bytes of entropy from `buffer` and hashes it into the special storage. This function should be called periodically from the user's space to increase entropy quality.
int	zrtp_randstr (zrtp_global_ctx_t zrtp_global, unsigned char buffer, uint32_t length)
	Random string generation zrtp_randstr() generates `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_add_entropy(). If the user provides "good" entropy, zrtp_randstr() generates sufficiently "random" data.

Detailed Description

Function Documentation

int zrtp_add_entropy	(	zrtp_global_ctx_t *	zrtp_global,
		const unsigned char *	buffer,
		uint32_t	length
	)

Entropy accumulation The random number generation scheme is described in detail in chapter 5 Random number generation. This function gets length bytes of entropy from 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 5 Random number generation.

Parameters:

	zrtp_global	- libzrtp global context;
	buffer	- pointer to the buffer with entropy for accumulating;
	length	- entropy size in bytes.

zrtp_stream_ctx_t* zrtp_attach_stream	(	zrtp_conn_ctx_t *	session_ctx,
		uint32_t	rtp_ssrc
	)

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 types::ZRTP_MAX_STREAMS_PER_SESSION variable. All newly created streams are equivalent and have ZRTP_STREAM_MODE_CLEAR type mode. Only after attaching a stream can the ZRTP protocol be initiated.

Parameters:

	session_ctx	- the ZRTP session within which a new stream is to be allocated.
	rtp_ssrc	- the SSRC number of the RTP media stream that this ZRTP stream corresponds to. ( In host byte order )

See also:: zrtp_start_stream() zrtp_stop_stream()

zrtp_status_t zrtp_check_profile	(	const zrtp_profile_t *	profile,
		zrtp_global_ctx_t *	zrtp_global
	)

Verifying the ZRTP profile zrtp_check_profile() checks the correctness of the values in the profile. This function is called automatically when zrtp_apply_profile() is called.
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 Internet Draft.

Parameters:

	profile	- ZRTP profile for validation;
	zrtp_global	- global ZRTP context.

Returns:

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_clear_stream ( zrtp_stream_ctx_t * stream_ctx )

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 (SECURE state, fig. 1.5), calling this function begins the exchange of packets switching 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.

Parameters:

stream_ctx

- context defining the ZRTP stream

Returns:

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.

See also:: zrtp_start_stream() zrtp_secure_stream()

void zrtp_config_defaults ( zrtp_config_t * config )

Initializes libzrtp global config zrtp_config_defaults prepares all fields of zrtp_config_t for further usage. If the developer uses "enterprise" version of the libzrtp - zrtp_config_t::cb will be initialized with built-in realizations.

Warning:: Use this function before start operating with the config.

void zrtp_done_session_ctx ( zrtp_conn_ctx_t * ctx )

ZRTP Session context deinitialization Session context deinitialization also requires two steps: deinitializing internal context data and releasing upper-level structure memory. This function releases all resources allocated for internal context operations. The upper-level structure can be destroyed only after calling this function.

Warning:: Don't call zrtp_init_session_ctx() in parallel with other operations on this session. (stream attaching, destroying etc)

Parameters:

ctx

- context for deinitialization.

See also:: zrtp_init_session_ctx()

zrtp_status_t zrtp_down ( zrtp_global_ctx_t * zrtp_global )

Shutting down the ZRTP library Frees all allocated structures and resources. This function 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.

Parameters:

zrtp_global

- global ZRTP context;

Returns:

zrtp_status_ok if successfully shut down;
zrtp_status_fail if an error occurred.

See also:: zrtp_init()

int zrtp_find_in_profile	(	const zrtp_profile_t *	profile,
		zrtp_crypto_comp_t	type,
		uint8_t	id
	)

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.

Parameters:

	profile	- ZRTP profile;
	type	- sought component type;
	id	- sought component ID.

Returns:

component position - if component was found; -1 - if the component with the specified ID can't be found in profile.

zrtp_status_t zrtp_get_signaling_hash	(	zrtp_stream_ctx_t *	stream_ctx,
		char *	hash_buff,
		uint32_t	hash_buff_length
	)

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_get_signaling_hash() may be called after attaching the stream to receive the value of this hash.

See also:: ZRTP Internet Draft sec 10

Parameters:

	stream_ctx	- stream for operating with
	hash_buff	- buffer for storing signaling hash. Function returns already parsed hex string, not a binary value!
	hash_buff_length	- buffer length in bytes (not shorter than 34 bytes)

Returns:

zrtp_status_ok if the operation finished successfully
one of the errors otherwise

zrtp_global_ctx_t* zrtp_init ( zrtp_config_t * config )

Initializing libzrtp This function initializes the library and all its components. libzrtp will upload all available crypto-components implementations:

hash type calculation scheme (ZRTP_HASH_SHA256)
encryption schemes (ZRTP_CIPHER_AES128, ZRTP_CIPHER_AES256);
public key exchange scheme (ZRTP_PKTYPE_PRESH, ZRTP_PKTYPE_DH3072, ZRTP_PKTYPE_DH4096);
SAS schemes (ZRTP_SAS_BASE32, ZRTP_SAS_BASE256);
authentication schemes (ZRTP_ATL_HS32, ZRTP_ATL_HS80). zrtp_init() initialize global data for all sessions and streams. Fields of the global context are initialized automatically and shouldn't be modified. For correct memory management, global context should be released by calling zrtp_down().

Parameters:

config

- libzrtp inital parameters

Warning:: this function must be called before any operation with libzrtp.

Returns:

pointer to allocated zrtp global context structure;
NULL - if error occurred.

See also:: zrtp_down()

zrtp_status_t zrtp_init_session_ctx	(	zrtp_conn_ctx_t *	session_ctx,
		zrtp_global_ctx_t *	zrtp_global,
		zrtp_profile_t *	profile,
		zrtp_zid_t	zid,
		uint8_t	is_initiator
	)

ZRTP Session context initialization. As explained in 3. Data structures, the session context is created in two steps: memory allocation for the external structure and internal data 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 profile. Profile will be applyed to every stream allocated within this session. Profile must contain lists of the crypto-components and other required information. Applying the profile entails:

filling of all necessary structures;
HELLO packet construction;
priority range specification in the crypto components usage. Before the applying the profile, call zrtp_check_profile() function to make sure that the profile you are applying correct.

Warning:: Don't call zrtp_init_session_ctx() in parallel with other operations on this session (stream attaching, destroying etc).

Parameters:

	zrtp_global	- global ZRTP context;
	session_ctx	- session context for initialization;
	profile	- the stream configuration profile. If value of this parameter is NULL, default profile will be used. NULL profile usage is equivalent to calling zrtp_profile_autoload()
	zid	- ZRTP peer identification.
	is_initiator	- identifies if the endpoint was the signaling initator of the call. Used to provide Passive Mode options to the developer. If you'r application doesn't control signaling or you don't want to support Passive Mode features - set this flag to 1.

Returns:

zrtp_status_ok if initialization is successful;
zrtp_status_fail if an error occurs.

See also:: zrtp_done_session_ctx()

zrtp_status_t zrtp_process_rtcp	(	zrtp_stream_ctx_t *	stream_ctx,
		char *	packet,
		unsigned int *	length
	)

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 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.

Parameters:

	stream_ctx	- context associated with the current ZRTP session;
	packet	- buffer storing RTCP packet;
	length	- length of the buffered packet.

Returns:

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.

See also:: zrtp_process_srtp() zrtp_process_rtp() zrtp_process_srtcp()

zrtp_status_t zrtp_process_rtp	(	zrtp_stream_ctx_t *	stream_ctx,
		char *	packet,
		unsigned int *	length
	)

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.

Parameters:

	stream_ctx	- context associated with the current ZRTP stream;
	packet	- buffer storing the RTP packet for encryption. After processing, the encrypted packet is stored in the same buffer.
	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.

Returns:

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.

See also:: zrtp_process_srtp() zrtp_process_rtcp() zrtp_process_srtcp()

zrtp_status_t zrtp_process_srtcp	(	zrtp_stream_ctx_t *	stream_ctx,
		char *	packet,
		unsigned int *	length
	)

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 length variable;
In transition states, drops all incoming RTCP traffic. In this case the body and the length of the packet remain unchanged.

Parameters:

	stream_ctx	- context associated with the current ZRTP stream;
	packet	- buffer storing the RTCP packet;
	length	- length of the buffered packet.

Returns:

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.
See also:
zrtp_process_srtp() zrtp_process_rtp() zrtp_process_rtcp()

zrtp_status_t zrtp_process_srtp	(	zrtp_stream_ctx_t *	stream_ctx,
		char *	packet,
		unsigned int *	length
	)

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.
.

Parameters:

	stream_ctx	- context associated with the current ZRTP stream
	packet	- buffer storing the packet for decrypting. After processing, the decrypted packet is stored in the same buffer;
	length	- the length of the buffered packet. After processing, the length of decrypted packet is stored here;

Returns:

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;
zrtp_status_forward reflects that the outgoing command packet is forwarded to the incoming stream. The packet should be forwarded along the previous path.

See also:: zrtp_process_rtp() zrtp_process_rtcp() zrtp_process_srtcp()

void zrtp_profile_autoload	(	zrtp_profile_t *	profile,
		zrtp_global_ctx_t *	zrtp_global
	)

Configure the default ZRTP profile These options are used:.

 "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 Internet draft;

 [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;

Parameters:

	profile	- ZRTP stream profile for filling;
	zrtp_global	- libzrtp global context.

int zrtp_randstr	(	zrtp_global_ctx_t *	zrtp_global,
		unsigned char *	buffer,
		uint32_t	length
	)

Random string generation zrtp_randstr() generates 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_add_entropy(). If the user provides "good" entropy, zrtp_randstr() generates sufficiently "random" data.

Random bits in libzrtp are produced as follows: First stir new entropy into the random state (zrtp_global->rand_ctx). Then make a copy of the random context and finalize it. Use the digest to seed an AES-256 context and, if space remains, to initialize a counter. Then encrypt the counter with the AES-256 context, incrementing it per block, until the desired quantity of data is produced.

See also:: 5 Random number generation

Parameters:

	zrtp_global	- libzrtp global context;
	buffer	- buffer into which random data will be generated;
	length	- length of required sequence in bytes.

Returns:

length of generated sequence in bytes or -1 in case of error

zrtp_status_t zrtp_secure_stream ( zrtp_stream_ctx_t * stream_ctx )

Initiating a secure connection setup The function initiates a ZRTP connection setup within a stream. In other words, after the protocol has started and HELLO packets are successfully exchanged, 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 (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.

Parameters:

stream_ctx

- context defining the ZRTP stream

Returns:

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.

See also:: zrtp_start_stream() zrtp_clear_stream()

zrtp_status_t zrtp_set_signaling_hash	(	zrtp_stream_ctx_t *	stream_ctx,
		const char *	hash_buff,
		uint32_t	hash_buff_length
	)

Specifies the hash of the peer Hello message for verification. In accordance with the ZRTP ID sec. 9.1, 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.

See also:: ZRTP Internet Draft sec 10;

Parameters:

	stream_ctx	- stream for operating with;
	hash_buff	- signaling hash buffer. Function accpt string, not a binary value!;
	hash_buff_length	- signaling hash length in bytes (should be 34 bytes);

Returns:

zrtp_status_ok if the operation finished successfully
one of the errors otherwise

zrtp_status_t zrtp_set_verified	(	zrtp_global_ctx_t *	zrtp,
		zrtp_string16_t *	zid1,
		zrtp_string16_t *	zid2,
		uint8_t	verified
	)

Changing the value of the secret's verification flag This function is used to change (set, unset) the secret's verification flag. zrtp_set_verified() changes the relevant internal data and stores a flag in the cache. 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.

Parameters:

	zrtp	- zrtp global data;
	zid1	- ZID of the first party;
	zid2	- ZID of the second party;
	verified	- Boolean value of the verified flag.

Returns:

zrtp_status_ok - if successful;
- one of zrtp_status_t errors if fails.

void zrtp_start_stream ( zrtp_stream_ctx_t * stream_ctx )

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 first ZRTP connection within a stream. If "autosecure" mode is not available, calling this function activates only ZRTP stream. A connection can be activated manually by calling zrtp_secure_stream(). Within one stream several ZRTP connections can be setup and interrupted consecutively by calling zrtp_secure_stream() and zrtp_clear_stream(). 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. Stream and connection initialization are described in section 7 Connection life-cycle and management in detail.

See also:: 2.3 Callback conventions 8 Stream usage and options

Parameters:

stream_ctx

- context within which the ZRTP stream/connection is setup.

void zrtp_stop_stream ( zrtp_stream_ctx_t * stream_ctx )

ZRTP protocol stopping This function stops all protocol operations for the specified stream, releases resources allocated on the zrtp_start_stream() 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.

See also:: callbacks

Parameters:

stream_ctx

- context, associated with the stream being shutdown.

libZRTP main functions [ZRTP API REFERENCE]

Functions

Detailed Description

Function Documentation

libZRTP main functions
[ZRTP API REFERENCE]