Utilites
[API]

Collaboration diagram for Utilites:

Functions
zrtp_status_t	zrtp_signaling_hash_set (zrtp_stream_t *stream, const char *hash_buff, uint32_t hash_buff_length)
	Specifies the hash of the peer Hello message for verification.
zrtp_status_t	zrtp_signaling_hash_get (zrtp_stream_t *stream, char *hash_buff, uint32_t hash_buff_length)
	Returns the hash of the Hello message to be transferred in signaling.
zrtp_status_t	zrtp_verified_set (zrtp_global_t *zrtp, zrtp_string16_t *zid1, zrtp_string16_t *zid2, uint8_t verified)
	Changing the value of the secret's verification flag.
zrtp_status_t	zrtp_profile_check (const zrtp_profile_t *profile, zrtp_global_t *zrtp)
	Verifying the ZRTP profile.
void	zrtp_profile_defaults (zrtp_profile_t *profile, zrtp_global_t *zrtp)
	Configure the default ZRTP profile.
int	zrtp_profile_find (const zrtp_profile_t *profile, zrtp_crypto_comp_t type, uint8_t id)
	Search for a component in the profile by ID.

---

Function Documentation

zrtp_status_t zrtp_profile_check	(	const zrtp_profile_t *	profile,
		zrtp_global_t *	zrtp
	)

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.

Parameters:

	profile	- ZRTP profile for validation;
	zrtp	- 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.

void zrtp_profile_defaults	(	zrtp_profile_t *	profile,
		zrtp_global_t *	zrtp
	)

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

Parameters:

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

int zrtp_profile_find	(	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_signaling_hash_get	(	zrtp_stream_t *	stream,
		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_signaling_hash_get() may be called after attaching the stream to receive the value of this hash.

Parameters:

	stream	- stream for operating with
	hash_buff	- buffer for storing signaling hash. Function returns already parsed hex string. String is null-terminated.
	hash_buff_length	- buffer length in bytes (not shorter than 65 bytes)

Returns:

:

• zrtp_status_ok if the operation finished successfully
• one of the errors otherwise

See also:

• ZRTP RFC. sec 8;
• zrtp_signaling_hash_set()

zrtp_status_t zrtp_signaling_hash_set	(	zrtp_stream_t *	stream,
		const char *	hash_buff,
		uint32_t	hash_buff_length
	)

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.

Parameters:

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

Returns:

:

• zrtp_status_ok if the operation finished successfully
• one of the errors otherwise

See also:

• ZRTP RFC. sec 8;
• zrtp_signaling_hash_get()

zrtp_status_t zrtp_verified_set	(	zrtp_global_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_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.

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.