bZRTP
bZRTP is an opensource implementation of ZRTP keys exchange protocol
Loading...
Searching...
No Matches
Functions
zidCache.c File Reference

Functions

static int bzrtp_getSelfZID_impl (void *dbPointer, const char *selfURI, uint8_t selfZID[12], bctbx_rng_context_t *RNGContext)
 
int bzrtp_getSelfZID (void *dbPointer, 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)
 
int bzrtp_getSelfZID_lock (void *dbPointer, 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
 
int bzrtp_getPeerAssociatedSecrets (bzrtpContext_t *context, uint8_t peerZID[12])
 Parse the cache to find secrets associated to the given ZID, set them and their length in the context if they are found Note: this function also retrieve zuid(set in the context) wich allow successive calls to cache operation to be faster.
 
int bzrtp_cache_write_active (bzrtpContext_t *context, const char *tableName, const char **columns, uint8_t **values, size_t *lengths, uint8_t columnsCount)
 This is a convenience wrapper to the bzrtp_cache_write function which will also take care of setting the ziduri table 'active' flag to one for the current row and reset all other rows with matching peeruri.
 
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.
 
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.
 
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.
 
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.
 
int bzrtp_cache_migration (void *cacheXml, 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.
 
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.
 
int bzrtp_cache_getZuid (void *dbPointer, const char *selfURI, const char *peerURI, const uint8_t peerZID[12], const uint8_t insertFlag, int *zuid, bctbx_mutex_t *zidCacheMutex)
 

Function Documentation

◆ bzrtp_cache_getPeerStatus_lock()

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_cache_getZuid()

int bzrtp_cache_getZuid ( void *  dbPointer,
const char *  selfURI,
const char *  peerURI,
const uint8_t  peerZID[12],
const uint8_t  insertFlag,
int *  zuid,
bctbx_mutex_t *  zidCacheMutex 
)

◆ bzrtp_cache_migration()

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_cache_read()

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_cache_read_lock()

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_cache_write()

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_cache_write_active()

int bzrtp_cache_write_active ( bzrtpContext_t context,
const char *  tableName,
const char **  columns,
uint8_t **  values,
size_t *  lengths,
uint8_t  columnsCount 
)

This is a convenience wrapper to the bzrtp_cache_write function which will also take care of setting the ziduri table 'active' flag to one for the current row and reset all other rows with matching peeruri.

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]contextthe current context, used to get the cache db pointer, zuid and cache mutex
[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_cache_write_lock()

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_getPeerAssociatedSecrets()

int bzrtp_getPeerAssociatedSecrets ( bzrtpContext_t context,
uint8_t  peerZID[12] 
)

Parse the cache to find secrets associated to the given ZID, set them and their length in the context if they are found Note: this function also retrieve zuid(set in the context) wich allow successive calls to cache operation to be faster.

Parameters
[in,out]contextthe current context, used to get the cache db pointer, self and peer URI and store results
[in]peerZIDa byte array of the peer ZID

return 0 on succes, error code otherwise

◆ bzrtp_getSelfZID()

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_getSelfZID_impl()

static int bzrtp_getSelfZID_impl ( void *  dbPointer,
const char *  selfURI,
uint8_t  selfZID[12],
bctbx_rng_context_t *  RNGContext 
)
static

◆ bzrtp_getSelfZID_lock()

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