libzrtp  1.2.0
ZRTP VoIP security
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
Utilities
API

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.
 

Detailed Description

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. Buffer must be at least ZRTP_SIGN_ZRTP_HASH_LENGTH bytes length.
hash_buff_length- buffer length in bytes, non less than ZRTP_SIGN_ZRTP_HASH_LENGTH bytes.
Returns
:
  • zrtp_status_ok if the operation finished successfully
  • one of the errors otherwise
See Also
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 accepts string, not a binary value!;
hash_buff_length- signaling hash length in bytes, must be ZRTP_SIGN_ZRTP_HASH_LENGTH bytes;
Returns
:
  • zrtp_status_ok if the operation finished successfully
  • one of the errors otherwise
See Also
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.