bZRTP
bZRTP is an opensource implementation of ZRTP keys exchange protocol
Data Structures | Macros | Typedefs | Functions
bzrtp.h File Reference

Go to the source code of this file.

Data Structures

struct  bzrtpSrtpSecrets_struct
 
struct  bzrtpCallbacks_struct
 All the callback functions provided by the client needed by the ZRTP engine. More...
 

Macros

#define BZRTP_EXPORT   __attribute__ ((visibility ("default")))
 
#define BZRTP_DEPRECATED   __attribute__ ((deprecated))
 
#define ZRTP_HASH_TYPE   0x01
 
#define ZRTP_CIPHERBLOCK_TYPE   0x02
 
#define ZRTP_AUTHTAG_TYPE   0x04
 
#define ZRTP_KEYAGREEMENT_TYPE   0x08
 
#define ZRTP_SAS_TYPE   0x10
 
#define ZRTP_UNSET_ALGO   0x00
 
#define ZRTP_HASH_S256   0x11
 
#define ZRTP_HASH_S384   0x12
 
#define ZRTP_HASH_N256   0x13
 
#define ZRTP_HASH_N384   0x14
 
#define ZRTP_CIPHER_AES1   0x21
 
#define ZRTP_CIPHER_AES2   0x22
 
#define ZRTP_CIPHER_AES3   0x23
 
#define ZRTP_CIPHER_2FS1   0x24
 
#define ZRTP_CIPHER_2FS2   0x25
 
#define ZRTP_CIPHER_2FS3   0x26
 
#define ZRTP_AUTHTAG_HS32   0x31
 
#define ZRTP_AUTHTAG_HS80   0x32
 
#define ZRTP_AUTHTAG_SK32   0x33
 
#define ZRTP_AUTHTAG_SK64   0x34
 
#define ZRTP_KEYAGREEMENT_DH2k   0x41
 
#define ZRTP_KEYAGREEMENT_X255   0x42
 
#define ZRTP_KEYAGREEMENT_EC25   0x43
 
#define ZRTP_KEYAGREEMENT_X448   0x44
 
#define ZRTP_KEYAGREEMENT_DH3k   0x45
 
#define ZRTP_KEYAGREEMENT_EC38   0x46
 
#define ZRTP_KEYAGREEMENT_EC52   0x47
 
#define ZRTP_KEYAGREEMENT_Prsh   0x4e
 
#define ZRTP_KEYAGREEMENT_Mult   0x4f
 
#define ZRTP_SAS_B32   0x51
 
#define ZRTP_SAS_B256   0x52
 
#define ZRTP_SRTP_SECRETS_FOR_SENDER   0x01
 
#define ZRTP_SRTP_SECRETS_FOR_RECEIVER   0x02
 
#define BZRTP_AUXSECRET_MATCH   0x00
 
#define BZRTP_AUXSECRET_MISMATCH   0x01
 
#define BZRTP_AUXSECRET_UNSET   0x02
 
#define BZRTP_MESSAGE_ERROR   0x00
 
#define BZRTP_MESSAGE_WARNING   0x01
 
#define BZRTP_MESSAGE_LOG   0x02
 
#define BZRTP_MESSAGE_DEBUG   0x03
 
#define BZRTP_MESSAGE_CACHEMISMATCH   0x01
 
#define BZRTP_MESSAGE_PEERVERSIONOBSOLETE   0x02
 
#define BZRTP_MESSAGE_PEERNOTBZRTP   0x03
 
#define ZRTP_MAGIC_COOKIE   0x5a525450
 
#define ZRTP_VERSION   "1.10"
 
#define BZRTP_ERROR_INVALIDCALLBACKID   0x0001
 
#define BZRTP_ERROR_CONTEXTNOTREADY   0x0002
 
#define BZRTP_ERROR_INVALIDCONTEXT   0x0004
 
#define BZRTP_ERROR_MULTICHANNELNOTSUPPORTEDBYPEER   0x0008
 
#define BZRTP_ERROR_UNABLETOADDCHANNEL   0x0010
 
#define BZRTP_ERROR_UNABLETOSTARTCHANNEL   0x0020
 
#define BZRTP_ERROR_OUTPUTBUFFER_LENGTH   0x0040
 
#define BZRTP_ERROR_HELLOHASH_MISMATCH   0x0080
 
#define BZRTP_ERROR_CHANNELALREADYSTARTED   0x0100
 
#define BZRTP_ERROR_CACHEDISABLED   0x0200
 
#define BZRTP_ERROR_CACHEMIGRATIONFAILED   0x0400
 
#define BZRTP_ERROR_CACHE_PEERNOTFOUND   0x0800
 
#define BZRTP_CHANNEL_NOTFOUND   0x1000
 
#define BZRTP_CHANNEL_INITIALISED   0x1001
 
#define BZRTP_CHANNEL_ONGOING   0x1002
 
#define BZRTP_CHANNEL_SECURE   0x1004
 
#define BZRTP_CHANNEL_ERROR   0x1008
 
#define BZRTP_ROLE_INITIATOR   0
 
#define BZRTP_ROLE_RESPONDER   1
 
#define BZRTP_CACHE_SETUP   0x2000
 
#define BZRTP_CACHE_UPDATE   0x2001
 
#define BZRTP_CACHE_DATA_NOTFOUND   0x2002
 
#define BZRTP_CACHE_PEER_STATUS_UNKNOWN   0x2010
 
#define BZRTP_CACHE_PEER_STATUS_VALID   0x2011
 
#define BZRTP_CACHE_PEER_STATUS_INVALID   0x2012
 
#define BZRTP_ZIDCACHE_INVALID_CONTEXT   0x2101
 
#define BZRTP_ZIDCACHE_INVALID_CACHE   0x2102
 
#define BZRTP_ZIDCACHE_UNABLETOUPDATE   0x2103
 
#define BZRTP_ZIDCACHE_UNABLETOREAD   0x2104
 
#define BZRTP_ZIDCACHE_BADINPUTDATA   0x2105
 
#define BZRTP_ZIDCACHE_RUNTIME_CACHELESS   0x2110
 

Typedefs

typedef struct bzrtpSrtpSecrets_struct bzrtpSrtpSecrets_t
 
typedef void(* zrtpFreeBuffer_callback) (void *)
 
typedef struct bzrtpCallbacks_struct bzrtpCallbacks_t
 All the callback functions provided by the client needed by the ZRTP engine. More...
 
typedef struct bzrtpContext_struct bzrtpContext_t
 bzrtpContext_t The ZRTP engine context Store current state, timers, HMAC and encryption keys More...
 

Functions

BZRTP_EXPORT bzrtpContext_tbzrtp_createBzrtpContext (void)
 
BZRTP_EXPORT int bzrtp_initBzrtpContext (bzrtpContext_t *context, uint32_t selfSSRC)
 Perform initialisation which can't be done without ZIDcache acces. More...
 
BZRTP_EXPORT void bzrtp_resetBzrtpContext (bzrtpContext_t *context)
 
BZRTP_EXPORT int bzrtp_destroyBzrtpContext (bzrtpContext_t *context, uint32_t selfSSRC)
 
BZRTP_EXPORT int bzrtp_setCallbacks (bzrtpContext_t *context, const bzrtpCallbacks_t *cbs)
 Allocate a function pointer to the callback function identified by his id. More...
 
BZRTP_EXPORT int bzrtp_setZIDCache_lock (bzrtpContext_t *context, void *zidCache, const char *selfURI, const char *peerURI, bctbx_mutex_t *zidCacheMutex)
 Set the pointer allowing cache access, this version of the function get a mutex to lock the cache when accessing it. More...
 
BZRTP_EXPORT int bzrtp_setZIDCache (bzrtpContext_t *context, void *zidCache, const char *selfURI, const char *peerURI)
 Set the pointer allowing cache access. More...
 
BZRTP_EXPORT int bzrtp_setClientData (bzrtpContext_t *zrtpContext, uint32_t selfSSRC, void *clientData)
 Set the client data pointer in a channel context This pointer is returned to the client by the callbacks function, used to store associated contexts (RTP session) More...
 
BZRTP_EXPORT int bzrtp_addChannel (bzrtpContext_t *zrtpContext, uint32_t selfSSRC)
 Add a channel to an existing context. More...
 
BZRTP_EXPORT int bzrtp_startChannelEngine (bzrtpContext_t *zrtpContext, uint32_t selfSSRC)
 Start the state machine of the specified channel To be able to start an addional channel, we must be in secure state. More...
 
BZRTP_EXPORT int bzrtp_iterate (bzrtpContext_t *zrtpContext, uint32_t selfSSRC, uint64_t timeReference)
 Send the current time to a specified channel, it will check if it has to trig some timer. More...
 
BZRTP_EXPORT int bzrtp_processMessage (bzrtpContext_t *zrtpContext, uint32_t selfSSRC, uint8_t *zrtpPacketString, uint16_t zrtpPacketStringLength)
 Process a received message. More...
 
BZRTP_EXPORT void bzrtp_SASVerified (bzrtpContext_t *zrtpContext)
 Called by user when the SAS has been verified. More...
 
BZRTP_EXPORT void bzrtp_resetSASVerified (bzrtpContext_t *zrtpContext)
 Called by user when the SAS has been set to unverified. More...
 
BZRTP_EXPORT int bzrtp_resetRetransmissionTimer (bzrtpContext_t *zrtpContext, uint32_t selfSSRC)
 Reset the retransmission timer of a given channel. Packets will be sent again if appropriate: More...
 
BZRTP_EXPORT uint8_t bzrtp_getSupportedCryptoTypes (bzrtpContext_t *zrtpContext, uint8_t algoType, uint8_t supportedTypes[7])
 Get the supported crypto types. More...
 
BZRTP_EXPORT void bzrtp_setSupportedCryptoTypes (bzrtpContext_t *zrtpContext, uint8_t algoType, uint8_t supportedTypes[7], uint8_t supportedTypesCount)
 set the supported crypto types More...
 
BZRTP_EXPORT int bzrtp_setPeerHelloHash (bzrtpContext_t *zrtpContext, uint32_t selfSSRC, uint8_t *peerHelloHashHexString, size_t peerHelloHashHexStringLength)
 Set the peer hello hash given by signaling to a ZRTP channel. More...
 
BZRTP_EXPORT int bzrtp_getSelfHelloHash (bzrtpContext_t *zrtpContext, uint32_t selfSSRC, uint8_t *output, size_t outputLength)
 Get the self hello hash from ZRTP channel. More...
 
BZRTP_EXPORT int bzrtp_getChannelStatus (bzrtpContext_t *zrtpContext, uint32_t selfSSRC)
 Get the channel status. More...
 
BZRTP_EXPORT int bzrtp_setAuxiliarySharedSecret (bzrtpContext_t *zrtpContext, const uint8_t *auxSecret, size_t auxSecretLength)
 Set Auxiliary Secret for this channel(shall be used only on primary audio channel) The given auxSecret is appended to any aux secret found in ZIDcache This function must be called before reception of peerHello packet. More...
 
BZRTP_EXPORT uint8_t bzrtp_getAuxiliarySharedSecretMismatch (bzrtpContext_t *zrtpContext)
 Get the ZRTP auxiliary shared secret mismatch status. More...
 
BZRTP_EXPORT BZRTP_DEPRECATED int bzrtp_initCache (void *db)
 Check the given sqlite3 DB and create requested tables if needed Also manage DB schema upgrade. More...
 
BZRTP_EXPORT int bzrtp_initCache_lock (void *db, bctbx_mutex_t *zidCacheMutex)
 Check the given sqlite3 DB and create requested tables if needed Also manage DB schema upgrade. More...
 
BZRTP_EXPORT BZRTP_DEPRECATED int bzrtp_getSelfZID (void *db, const char *selfURI, uint8_t selfZID[12], bctbx_rng_context_t *RNGContext)
 : retrieve ZID from cache ZID is randomly generated if cache is empty or inexistant ZID is randomly generated in case of cacheless implementation(db argument is NULL) More...
 
BZRTP_EXPORT int bzrtp_getSelfZID_lock (void *db, const char *selfURI, uint8_t selfZID[12], bctbx_rng_context_t *RNGContext, bctbx_mutex_t *zidCacheMutex)
 : retrieve ZID from cache ZID is randomly generated if cache is empty or inexistant ZID is randomly generated in case of cacheless implementation(db argument is NULL) this version of the function gets a mutex to lock the cache when accessing it More...
 
BZRTP_EXPORT BZRTP_DEPRECATED int bzrtp_cache_write (void *dbPointer, int zuid, const char *tableName, const char **columns, uint8_t **values, size_t *lengths, uint8_t columnsCount)
 Write(insert or update) data in cache, adressing it by zuid (ZID/URI binding id used in cache) Get arrays of column names, values to be inserted, lengths of theses values All three arrays must be the same lenght: columnsCount If the row isn't present in the given table, it will be inserted. More...
 
BZRTP_EXPORT int bzrtp_cache_write_lock (void *dbPointer, int zuid, const char *tableName, const char **columns, uint8_t **values, size_t *lengths, uint8_t columnsCount, bctbx_mutex_t *zidCacheMutex)
 Write(insert or update) data in cache, adressing it by zuid (ZID/URI binding id used in cache) Get arrays of column names, values to be inserted, lengths of theses values All three arrays must be the same lenght: columnsCount If the row isn't present in the given table, it will be inserted this version of the function gets a mutex to lock the cache when accessing it. More...
 
BZRTP_EXPORT BZRTP_DEPRECATED int bzrtp_cache_read (void *dbPointer, int zuid, const char *tableName, const char **columns, uint8_t **values, size_t *lengths, uint8_t columnsCount)
 Read data from specified table/columns from cache adressing it by zuid (ZID/URI binding id used in cache) Get arrays of column names, values to be read, and the number of colums to be read Produce an array of values(uint8_t arrays) and a array of corresponding lengths Values memory is allocated by this function and must be freed by caller. More...
 
BZRTP_EXPORT int bzrtp_cache_read_lock (void *dbPointer, int zuid, const char *tableName, const char **columns, uint8_t **values, size_t *lengths, uint8_t columnsCount, bctbx_mutex_t *zidCacheMutex)
 Read data from specified table/columns from cache adressing it by zuid (ZID/URI binding id used in cache) Get arrays of column names, values to be read, and the number of colums to be read Produce an array of values(uint8_t arrays) and a array of corresponding lengths Values memory is allocated by this function and must be freed by caller this version of the function gets a mutex to lock the cache when accessing it. More...
 
BZRTP_EXPORT int bzrtp_cache_migration (void *cacheXmlPtr, void *cacheSqlite, const char *selfURI)
 Perform migration from xml version to sqlite3 version of cache Warning: new version of cache associate a ZID to each local URI, the old one did not the migration function will associate any data in the cache to the sip URI given in parameter which shall be the default URI. More...
 
BZRTP_EXPORT int bzrtp_exportKey (bzrtpContext_t *zrtpContext, char *label, size_t labelLength, uint8_t *derivedKey, size_t *derivedKeyLength)
 
BZRTP_EXPORT int bzrtp_cache_getPeerStatus_lock (void *dbPointer, const char *peerURI, bctbx_mutex_t *zidCacheMutex)
 Retrieve from bzrtp cache the trust status(based on the previously verified flag) of a peer URI. More...
 

Macro Definition Documentation

#define BZRTP_AUXSECRET_MATCH   0x00
#define BZRTP_AUXSECRET_MISMATCH   0x01
#define BZRTP_AUXSECRET_UNSET   0x02
#define BZRTP_CACHE_DATA_NOTFOUND   0x2002
#define BZRTP_CACHE_PEER_STATUS_INVALID   0x2012
#define BZRTP_CACHE_PEER_STATUS_UNKNOWN   0x2010
#define BZRTP_CACHE_PEER_STATUS_VALID   0x2011
#define BZRTP_CACHE_SETUP   0x2000
#define BZRTP_CACHE_UPDATE   0x2001
#define BZRTP_CHANNEL_ERROR   0x1008
#define BZRTP_CHANNEL_INITIALISED   0x1001
#define BZRTP_CHANNEL_NOTFOUND   0x1000
#define BZRTP_CHANNEL_ONGOING   0x1002
#define BZRTP_CHANNEL_SECURE   0x1004
#define BZRTP_DEPRECATED   __attribute__ ((deprecated))
#define BZRTP_ERROR_CACHE_PEERNOTFOUND   0x0800
#define BZRTP_ERROR_CACHEDISABLED   0x0200
#define BZRTP_ERROR_CACHEMIGRATIONFAILED   0x0400
#define BZRTP_ERROR_CHANNELALREADYSTARTED   0x0100
#define BZRTP_ERROR_CONTEXTNOTREADY   0x0002
#define BZRTP_ERROR_HELLOHASH_MISMATCH   0x0080
#define BZRTP_ERROR_INVALIDCALLBACKID   0x0001
#define BZRTP_ERROR_INVALIDCONTEXT   0x0004
#define BZRTP_ERROR_MULTICHANNELNOTSUPPORTEDBYPEER   0x0008
#define BZRTP_ERROR_OUTPUTBUFFER_LENGTH   0x0040
#define BZRTP_ERROR_UNABLETOADDCHANNEL   0x0010
#define BZRTP_ERROR_UNABLETOSTARTCHANNEL   0x0020
#define BZRTP_EXPORT   __attribute__ ((visibility ("default")))
#define BZRTP_MESSAGE_CACHEMISMATCH   0x01
#define BZRTP_MESSAGE_DEBUG   0x03
#define BZRTP_MESSAGE_ERROR   0x00
#define BZRTP_MESSAGE_LOG   0x02
#define BZRTP_MESSAGE_PEERNOTBZRTP   0x03
#define BZRTP_MESSAGE_PEERVERSIONOBSOLETE   0x02
#define BZRTP_MESSAGE_WARNING   0x01
#define BZRTP_ROLE_INITIATOR   0
#define BZRTP_ROLE_RESPONDER   1
#define BZRTP_ZIDCACHE_BADINPUTDATA   0x2105
#define BZRTP_ZIDCACHE_INVALID_CACHE   0x2102
#define BZRTP_ZIDCACHE_INVALID_CONTEXT   0x2101
#define BZRTP_ZIDCACHE_RUNTIME_CACHELESS   0x2110
#define BZRTP_ZIDCACHE_UNABLETOREAD   0x2104
#define BZRTP_ZIDCACHE_UNABLETOUPDATE   0x2103
#define ZRTP_AUTHTAG_HS32   0x31
#define ZRTP_AUTHTAG_HS80   0x32
#define ZRTP_AUTHTAG_SK32   0x33
#define ZRTP_AUTHTAG_SK64   0x34
#define ZRTP_AUTHTAG_TYPE   0x04
#define ZRTP_CIPHER_2FS1   0x24
#define ZRTP_CIPHER_2FS2   0x25
#define ZRTP_CIPHER_2FS3   0x26
#define ZRTP_CIPHER_AES1   0x21
#define ZRTP_CIPHER_AES2   0x22
#define ZRTP_CIPHER_AES3   0x23
#define ZRTP_CIPHERBLOCK_TYPE   0x02
#define ZRTP_HASH_N256   0x13
#define ZRTP_HASH_N384   0x14
#define ZRTP_HASH_S256   0x11
#define ZRTP_HASH_S384   0x12
#define ZRTP_HASH_TYPE   0x01

Define different types of crypto functions

#define ZRTP_KEYAGREEMENT_DH2k   0x41

WARNING : it is very important to keep the key agreement defined in that order as it is used to easily sort them from faster(DH2k) to slower(EC52)

#define ZRTP_KEYAGREEMENT_DH3k   0x45
#define ZRTP_KEYAGREEMENT_EC25   0x43
#define ZRTP_KEYAGREEMENT_EC38   0x46
#define ZRTP_KEYAGREEMENT_EC52   0x47
#define ZRTP_KEYAGREEMENT_Mult   0x4f
#define ZRTP_KEYAGREEMENT_Prsh   0x4e
#define ZRTP_KEYAGREEMENT_TYPE   0x08
#define ZRTP_KEYAGREEMENT_X255   0x42
#define ZRTP_KEYAGREEMENT_X448   0x44
#define ZRTP_MAGIC_COOKIE   0x5a525450
#define ZRTP_SAS_B256   0x52
#define ZRTP_SAS_B32   0x51
#define ZRTP_SAS_TYPE   0x10
#define ZRTP_SRTP_SECRETS_FOR_RECEIVER   0x02
#define ZRTP_SRTP_SECRETS_FOR_SENDER   0x01

Define to give client indication on which srtp secrets are valid when given

#define ZRTP_UNSET_ALGO   0x00

map the differents algorithm (some may not be available) to integer

#define ZRTP_VERSION   "1.10"

Typedef Documentation

All the callback functions provided by the client needed by the ZRTP engine.

bzrtpContext_t The ZRTP engine context Store current state, timers, HMAC and encryption keys

brief The data structure containing the keys and algorithms to be used by srtp Also stores SAS and informations about the crypto algorithms selected during ZRTP negotiation

typedef void(* zrtpFreeBuffer_callback) (void *)

Function pointer used by bzrtp to free memory allocated by callbacks.

Function Documentation

BZRTP_EXPORT int bzrtp_addChannel ( bzrtpContext_t zrtpContext,
uint32_t  selfSSRC 
)

Add a channel to an existing context.

Parameters
[in,out]zrtpContextThe zrtp context who will get the additionnal channel
[in]selfSSRCThe SSRC given to the channel context
Returns
0 on succes, error code otherwise

Add a channel to an existing context.

Parameters
[in,out]zrtpContextThe zrtp context who will get the additionnal channel. Must be in secure state.
[in]selfSSRCThe SSRC given to the channel context
Returns
0 on succes, error code otherwise
BZRTP_EXPORT int bzrtp_cache_getPeerStatus_lock ( void *  dbPointer,
const char *  peerURI,
bctbx_mutex_t *  zidCacheMutex 
)

Retrieve from bzrtp cache the trust status(based on the previously verified flag) of a peer URI.

This function will return the SAS validation status of the active device associated to the given peerURI.

Important note about the active device:

  • any ZRTP exchange with a peer device will set it to be the active one for its sip:uri
  • the concept of active device is shared between local accounts if there are several of them, it means that :
    • if you have several local users on your device, each of them may have an entry in the ZRTP cache with a particular peer sip:uri (if they ever got in contact with it) but only one of this entry is set to active
    • this function will return the status associated to the last updated entry without any consideration for the local users it is associated with
  • any call where the SAS was neither accepted or rejected will not update the trust status but will set as active device for the peer sip:uri the one involved in the call

This function is intended for use in a mono-device environment.

Parameters
[in]dbPointerPointer to an already opened sqlite db
[in]peerURIThe peer sip:uri we're interested in
[in]zidCacheMutexPoints to a mutex used to lock zidCache database access, ignored if NULL
Returns
one of:
  • BZRTP_CACHE_PEER_STATUS_UNKNOWN : this uri is not present in cache OR during calls with the active device, SAS never was validated or rejected Note: once the SAS has been validated or rejected, the status will never return to UNKNOWN(unless you delete your cache)
  • BZRTP_CACHE_PEER_STATUS_VALID : the active device status is set to valid
  • BZRTP_CACHE_PEER_STATUS_INVALID : the active peer device status is set to invalid
BZRTP_EXPORT int bzrtp_cache_migration ( void *  cacheXmlPtr,
void *  cacheSqlite,
const char *  selfURI 
)

Perform migration from xml version to sqlite3 version of cache Warning: new version of cache associate a ZID to each local URI, the old one did not the migration function will associate any data in the cache to the sip URI given in parameter which shall be the default URI.

Parameters
[in]cacheXmlPtra pointer to an xmlDocPtr structure containing the old cache to be migrated
[in,out]cacheSqlitea pointer to an sqlite3 structure containing a cache initialised using bzrtp_cache_init function
[in]selfURIdefault sip URI for this end point, NULL terminated char
Returns
0 on success, BZRTP_ERROR_CACHEDISABLED when bzrtp was not compiled with cache enabled, BZRTP_ERROR_CACHEMIGRATIONFAILED on error during migration
BZRTP_EXPORT BZRTP_DEPRECATED int bzrtp_cache_read ( void *  dbPointer,
int  zuid,
const char *  tableName,
const char **  columns,
uint8_t **  values,
size_t *  lengths,
uint8_t  columnsCount 
)

Read data from specified table/columns from cache adressing it by zuid (ZID/URI binding id used in cache) Get arrays of column names, values to be read, and the number of colums to be read Produce an array of values(uint8_t arrays) and a array of corresponding lengths Values memory is allocated by this function and must be freed by caller.

Parameters
[in,out]dbPointerPointer to an already opened sqlite db
[in]zuidThe DB internal id to adress the correct row(binding between local uri and peer ZID+URI)
[in]tableNameThe name of the table to read in the db. Null terminated string
[in]columnsAn array of null terminated strings containing the name of the columns to read, the array's length is columnsCount
[out]valuesAn array of uint8_t pointers, each one will be allocated to the read value and they must be freed by caller
[out]lengthsAn array of integer containing the lengths of values array buffer read
[in]columnsCountlength common to columns,values and lengths arrays
Returns
0 on succes, error code otherwise
BZRTP_EXPORT int bzrtp_cache_read_lock ( void *  dbPointer,
int  zuid,
const char *  tableName,
const char **  columns,
uint8_t **  values,
size_t *  lengths,
uint8_t  columnsCount,
bctbx_mutex_t *  zidCacheMutex 
)

Read data from specified table/columns from cache adressing it by zuid (ZID/URI binding id used in cache) Get arrays of column names, values to be read, and the number of colums to be read Produce an array of values(uint8_t arrays) and a array of corresponding lengths Values memory is allocated by this function and must be freed by caller this version of the function gets a mutex to lock the cache when accessing it.

Parameters
[in,out]dbPointerPointer to an already opened sqlite db
[in]zuidThe DB internal id to adress the correct row(binding between local uri and peer ZID+URI)
[in]tableNameThe name of the table to read in the db. Null terminated string
[in]columnsAn array of null terminated strings containing the name of the columns to read, the array's length is columnsCount
[out]valuesAn array of uint8_t pointers, each one will be allocated to the read value and they must be freed by caller
[out]lengthsAn array of integer containing the lengths of values array buffer read
[in]columnsCountlength common to columns,values and lengths arrays
[in]zidCacheMutexPoints to a mutex used to lock zidCache database access, ignored if NULL
Returns
0 on succes, error code otherwise
BZRTP_EXPORT BZRTP_DEPRECATED int bzrtp_cache_write ( void *  dbPointer,
int  zuid,
const char *  tableName,
const char **  columns,
uint8_t **  values,
size_t *  lengths,
uint8_t  columnsCount 
)

Write(insert or update) data in cache, adressing it by zuid (ZID/URI binding id used in cache) Get arrays of column names, values to be inserted, lengths of theses values All three arrays must be the same lenght: columnsCount If the row isn't present in the given table, it will be inserted.

Parameters
[in,out]dbPointerPointer to an already opened sqlite db
[in]zuidThe DB internal id to adress the correct row(binding between local uri and peer ZID+URI)
[in]tableNameThe name of the table to write in the db, must already exists. Null terminated string
[in]columnsAn array of null terminated strings containing the name of the columns to update
[in]valuesAn array of buffers containing the values to insert/update matching the order of columns array
[in]lengthsAn array of integer containing the lengths of values array buffer matching the order of columns array
[in]columnsCountlength common to columns,values and lengths arrays
Returns
0 on succes, error code otherwise
BZRTP_EXPORT int bzrtp_cache_write_lock ( void *  dbPointer,
int  zuid,
const char *  tableName,
const char **  columns,
uint8_t **  values,
size_t *  lengths,
uint8_t  columnsCount,
bctbx_mutex_t *  zidCacheMutex 
)

Write(insert or update) data in cache, adressing it by zuid (ZID/URI binding id used in cache) Get arrays of column names, values to be inserted, lengths of theses values All three arrays must be the same lenght: columnsCount If the row isn't present in the given table, it will be inserted this version of the function gets a mutex to lock the cache when accessing it.

Parameters
[in,out]dbPointerPointer to an already opened sqlite db
[in]zuidThe DB internal id to adress the correct row(binding between local uri and peer ZID+URI)
[in]tableNameThe name of the table to write in the db, must already exists. Null terminated string
[in]columnsAn array of null terminated strings containing the name of the columns to update
[in]valuesAn array of buffers containing the values to insert/update matching the order of columns array
[in]lengthsAn array of integer containing the lengths of values array buffer matching the order of columns array
[in]columnsCountlength common to columns,values and lengths arrays
[in]zidCacheMutexPoints to a mutex used to lock zidCache database access, ignored if NULL
Returns
0 on succes, error code otherwise
BZRTP_EXPORT bzrtpContext_t* bzrtp_createBzrtpContext ( void  )

Create context structure and initialise it

Returns
The ZRTP engine context data
BZRTP_EXPORT int bzrtp_destroyBzrtpContext ( bzrtpContext_t context,
uint32_t  selfSSRC 
)

Free memory of context structure to a channel, if all channels are freed, free the global zrtp context

Parameters
[in]contextContext hosting the channel to be destroyed.(note: the context zrtp context itself is destroyed with the last channel)
[in]selfSSRCThe SSRC identifying the channel to be destroyed
Returns
the number of channel still active in this ZRTP context
BZRTP_EXPORT int bzrtp_exportKey ( bzrtpContext_t zrtpContext,
char *  label,
size_t  labelLength,
uint8_t derivedKey,
size_t *  derivedKeyLength 
)
BZRTP_EXPORT uint8_t bzrtp_getAuxiliarySharedSecretMismatch ( bzrtpContext_t zrtpContext)

Get the ZRTP auxiliary shared secret mismatch status.

Parameters
[in]zrtpContextThe ZRTP context we're dealing with
Returns
BZRTP_AUXSECRET_MATCH on match, BZRTP_AUXSECRET_MISMATCH on mismatch, BZRTP_AUXSECRET_UNSET if auxiliary shared secret is unused
BZRTP_EXPORT int bzrtp_getChannelStatus ( bzrtpContext_t zrtpContext,
uint32_t  selfSSRC 
)

Get the channel status.

Parameters
[in]zrtpContextThe ZRTP context we're dealing with
[in]selfSSRCThe SSRC identifying the channel
Returns
BZRTP_CHANNEL_NOTFOUND no channel matching this SSRC doesn't exists in the zrtp context BZRTP_CHANNEL_INITIALISED channel initialised but not started BZRTP_CHANNEL_ONGOING ZRTP key exchange in ongoing BZRTP_CHANNEL_SECURE Channel is secure BZRTP_CHANNEL_ERROR An error occured on this channel
BZRTP_EXPORT int bzrtp_getSelfHelloHash ( bzrtpContext_t zrtpContext,
uint32_t  selfSSRC,
uint8_t output,
size_t  outputLength 
)

Get the self hello hash from ZRTP channel.

Parameters
[in,out]zrtpContextThe ZRTP context we're dealing with
[in]selfSSRCThe SSRC identifying the channel
[out]outputA NULL terminated string containing the hexadecimal form of the hash received in signaling, contain ZRTP version as header. Buffer must be allocated by caller.
[in]outputLengthLength of output buffer, shall be at least 70 : 5 chars for version, 64 for the hash itself, SHA256), NULL termination
Returns
0 on success, errorcode otherwise
BZRTP_EXPORT BZRTP_DEPRECATED int bzrtp_getSelfZID ( void *  db,
const char *  selfURI,
uint8_t  selfZID[12],
bctbx_rng_context_t *  RNGContext 
)

: retrieve ZID from cache ZID is randomly generated if cache is empty or inexistant ZID is randomly generated in case of cacheless implementation(db argument is NULL)

Parameters
[in,out]dbsqlite3 database(or NULL if we don't use cache at runtime) Use a void * to keep this API when building cacheless
[in]selfURIthe sip uri of local user, NULL terminated string
[out]selfZIDthe ZID, retrieved from cache or randomly generated
[in]RNGContextA RNG context used to generate ZID if needed
Returns
0 on success, or BZRTP_CACHE_DATA_NOTFOUND if no ZID matching the URI was found and no RNGContext is given to generate one
BZRTP_EXPORT int bzrtp_getSelfZID_lock ( void *  db,
const char *  selfURI,
uint8_t  selfZID[12],
bctbx_rng_context_t *  RNGContext,
bctbx_mutex_t *  zidCacheMutex 
)

: retrieve ZID from cache ZID is randomly generated if cache is empty or inexistant ZID is randomly generated in case of cacheless implementation(db argument is NULL) this version of the function gets a mutex to lock the cache when accessing it

Parameters
[in,out]dbsqlite3 database(or NULL if we don't use cache at runtime) Use a void * to keep this API when building cacheless
[in]selfURIthe sip uri of local user, NULL terminated string
[out]selfZIDthe ZID, retrieved from cache or randomly generated
[in]RNGContextA RNG context used to generate ZID if needed
[in]zidCacheMutexPoints to a mutex used to lock zidCache database access, ignored if NULL
Returns
0 on success, or BZRTP_CACHE_DATA_NOTFOUND if no ZID matching the URI was found and no RNGContext is given to generate one
BZRTP_EXPORT uint8_t bzrtp_getSupportedCryptoTypes ( bzrtpContext_t zrtpContext,
uint8_t  algoType,
uint8_t  supportedTypes[7] 
)

Get the supported crypto types.

Parameters
[in]zrtpContextThe ZRTP context we're dealing with
[in]algoTypemapped to defines, must be in [ZRTP_HASH_TYPE, ZRTP_CIPHERBLOCK_TYPE, ZRTP_AUTHTAG_TYPE, ZRTP_KEYAGREEMENT_TYPE or ZRTP_SAS_TYPE]
[out]supportedTypesmapped to uint8_t value of the 4 char strings giving the supported types as string according to rfc section 5.1.2 to 5.1.6
Returns
number of supported types, 0 on error
BZRTP_EXPORT int bzrtp_initBzrtpContext ( bzrtpContext_t context,
uint32_t  selfSSRC 
)

Perform initialisation which can't be done without ZIDcache acces.

  • get ZID and create the first channel context

    Parameters
    [in]contextThe context to initialise
    [in]selfSSRCThe SSRC given to the first channel context created within the zrtpContext
    Returns
    0 on success

    Perform initialisation which can't be done without ZIDcache acces.

    • Get ZID from cache or generate a random ZID
    • Initialise the first channel
    Parameters
    [in]contextThe context to initialise
    [in]selfSSRCSSRC of the first channel
    Returns
    0 on success
BZRTP_EXPORT BZRTP_DEPRECATED int bzrtp_initCache ( void *  db)

Check the given sqlite3 DB and create requested tables if needed Also manage DB schema upgrade.

Parameters
[in,out]dbPointer to the sqlite3 db open connection Use a void * to keep this API when building cacheless
Returns
0 on success, BZRTP_CACHE_SETUP if cache was empty, BZRTP_CACHE_UPDATE if db structure was updated, error code otherwise
BZRTP_EXPORT int bzrtp_initCache_lock ( void *  db,
bctbx_mutex_t *  zidCacheMutex 
)

Check the given sqlite3 DB and create requested tables if needed Also manage DB schema upgrade.

this version of the function gets a mutex to lock the cache when accessing it

Parameters
[in,out]dbPointer to the sqlite3 db open connection Use a void * to keep this API when building cacheless
[in]zidCacheMutexPoints to a mutex used to lock zidCache database access, ignored if NULL
Returns
0 on success, BZRTP_CACHE_SETUP if cache was empty, BZRTP_CACHE_UPDATE if db structure was updated, error code otherwise
BZRTP_EXPORT int bzrtp_iterate ( bzrtpContext_t zrtpContext,
uint32_t  selfSSRC,
uint64_t  timeReference 
)

Send the current time to a specified channel, it will check if it has to trig some timer.

Parameters
[in,out]zrtpContextThe ZRTP context hosting the channel
[in]selfSSRCThe SSRC identifying the channel
[in]timeReferenceThe current time in ms
Returns
0 on succes, error code otherwise
BZRTP_EXPORT int bzrtp_processMessage ( bzrtpContext_t zrtpContext,
uint32_t  selfSSRC,
uint8_t zrtpPacketString,
uint16_t  zrtpPacketStringLength 
)

Process a received message.

Parameters
[in,out]zrtpContextThe ZRTP context we're dealing with
[in]selfSSRCThe SSRC identifying the channel receiving the message
[in]zrtpPacketStringThe packet received
[in]zrtpPacketStringLengthLength of the packet in bytes
Returns
0 on success, errorcode otherwise
BZRTP_EXPORT void bzrtp_resetBzrtpContext ( bzrtpContext_t context)
BZRTP_EXPORT int bzrtp_resetRetransmissionTimer ( bzrtpContext_t zrtpContext,
uint32_t  selfSSRC 
)

Reset the retransmission timer of a given channel. Packets will be sent again if appropriate:

  • when in responder role, zrtp engine only answer to packets sent by the initiator.
  • if we are still in discovery phase, Hello or Commit packets will be resent.
Parameters
[in,out]zrtpContextThe ZRTP context we're dealing with
[in]selfSSRCThe SSRC identifying the channel to reset

return 0 on success, error code otherwise

BZRTP_EXPORT void bzrtp_resetSASVerified ( bzrtpContext_t zrtpContext)

Called by user when the SAS has been set to unverified.

Parameters
[in,out]zrtpContextThe ZRTP context we're dealing with
BZRTP_EXPORT void bzrtp_SASVerified ( bzrtpContext_t zrtpContext)

Called by user when the SAS has been verified.

Parameters
[in,out]zrtpContextThe ZRTP context we're dealing with
BZRTP_EXPORT int bzrtp_setAuxiliarySharedSecret ( bzrtpContext_t zrtpContext,
const uint8_t auxSecret,
size_t  auxSecretLength 
)

Set Auxiliary Secret for this channel(shall be used only on primary audio channel) The given auxSecret is appended to any aux secret found in ZIDcache This function must be called before reception of peerHello packet.

Parameters
[in]zrtpContextThe ZRTP context we're dealing with
[in]auxSecretA buffer holding the auxiliary shared secret to use (see RFC 6189 section 4.3)
[in]auxSecretLengthlenght of the previous buffer
Returns
0 on success, error code otherwise
Note
The auxiliary shared secret mechanic is used by LIMEv2 for encryption security purposes but might be used for its original purpose in a regular ZRTP session if it becomes necessary in the future, or by another encryption engine for example. In that case the API will need an adaptation work.
BZRTP_EXPORT int bzrtp_setCallbacks ( bzrtpContext_t context,
const bzrtpCallbacks_t cbs 
)

Allocate a function pointer to the callback function identified by his id.

Parameters
[in,out]contextThe zrtp context to set the callback function
[in]cbsA structure containing all the callbacks to supply.
Returns
0 on success
BZRTP_EXPORT int bzrtp_setClientData ( bzrtpContext_t zrtpContext,
uint32_t  selfSSRC,
void *  clientData 
)

Set the client data pointer in a channel context This pointer is returned to the client by the callbacks function, used to store associated contexts (RTP session)

Parameters
[in,out]zrtpContextThe ZRTP context we're dealing with
[in]selfSSRCThe SSRC identifying the channel to be linked to the client Data
[in]clientDataThe clientData pointer, casted to a (void *)
Returns
0 on success
BZRTP_EXPORT int bzrtp_setPeerHelloHash ( bzrtpContext_t zrtpContext,
uint32_t  selfSSRC,
uint8_t peerHelloHashHexString,
size_t  peerHelloHashHexStringLength 
)

Set the peer hello hash given by signaling to a ZRTP channel.

Parameters
[in,out]zrtpContextThe ZRTP context we're dealing with
[in]selfSSRCThe SSRC identifying the channel
[in]peerHelloHashHexStringA NULL terminated string containing the hexadecimal form of the hash received in signaling, may contain ZRTP version as header.
[in]peerHelloHashHexStringLengthLength of hash string (shall be at least 64 as the hash is a SHA256 so 32 bytes, more if it contains the version header)
Returns
0 on success, errorcode otherwise
Parameters
[in,out]zrtpContextThe ZRTP context we're dealing with
[in]selfSSRCThe SSRC identifying the channel
[out]peerHelloHashHexStringA NULL terminated string containing the hexadecimal form of the hash received in signaling, may contain ZRTP version as header.
[in]peerHelloHashHexStringLengthLength of hash string (shall be at least 64 as the hash is a SHA256 so 32 bytes, more if it contains the version header)
Returns
0 on success, errorcode otherwise
BZRTP_EXPORT void bzrtp_setSupportedCryptoTypes ( bzrtpContext_t zrtpContext,
uint8_t  algoType,
uint8_t  supportedTypes[7],
uint8_t  supportedTypesCount 
)

set the supported crypto types

Parameters
[in,out]zrtpContextThe ZRTP context we're dealing with
[in]algoTypemapped to defines, must be in [ZRTP_HASH_TYPE, ZRTP_CIPHERBLOCK_TYPE, ZRTP_AUTHTAG_TYPE, ZRTP_KEYAGREEMENT_TYPE or ZRTP_SAS_TYPE]
[in]supportedTypesmapped to uint8_t value of the 4 char strings giving the supported types as string according to rfc section 5.1.2 to 5.1.6
[in]supportedTypesCountnumber of supported crypto types
BZRTP_EXPORT int bzrtp_setZIDCache ( bzrtpContext_t context,
void *  zidCache,
const char *  selfURI,
const char *  peerURI 
)

Set the pointer allowing cache access.

Parameters
[in,out]contextThe ZRTP context we're dealing with
[in]zidCacheUsed by internal function to access cache: turn into a sqlite3 pointer if cache is enabled
[in]selfURILocal URI used for this communication, needed to perform cache operation, NULL terminated string, duplicated by this function
[in]peerURIPeer URI used for this communication, needed to perform cache operation, NULL terminated string, duplicated by this function
Returns
0 or BZRTP_CACHE_SETUP(if cache is populated by this call) on success, error code otherwise
BZRTP_EXPORT int bzrtp_setZIDCache_lock ( bzrtpContext_t context,
void *  zidCache,
const char *  selfURI,
const char *  peerURI,
bctbx_mutex_t *  zidCacheMutex 
)

Set the pointer allowing cache access, this version of the function get a mutex to lock the cache when accessing it.

Parameters
[in,out]contextThe ZRTP context we're dealing with
[in]zidCacheUsed by internal function to access cache: turn into a sqlite3 pointer if cache is enabled
[in]selfURILocal URI used for this communication, needed to perform cache operation, NULL terminated string, duplicated by this function
[in]peerURIPeer URI used for this communication, needed to perform cache operation, NULL terminated string, duplicated by this function
[in]zidCacheMutexPoints to a mutex used to lock zidCache database access
Returns
0 or BZRTP_CACHE_SETUP(if cache is populated by this call) on success, error code otherwise
BZRTP_EXPORT int bzrtp_startChannelEngine ( bzrtpContext_t zrtpContext,
uint32_t  selfSSRC 
)

Start the state machine of the specified channel To be able to start an addional channel, we must be in secure state.

Parameters
[in,out]zrtpContextThe ZRTP context hosting the channel to be started
[in]selfSSRCThe SSRC identifying the channel to be started(will start sending Hello packets and listening for some)
Returns
0 on succes, error code otherwise