bZRTP
bZRTP is an opensource implementation of ZRTP keys exchange protocol
|
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... | |
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. | |
typedef struct bzrtpContext_struct | bzrtpContext_t |
bzrtpContext_t The ZRTP engine context Store current state, timers, HMAC and encryption keys | |
Functions | |
BZRTP_EXPORT bzrtpContext_t * | bzrtp_createBzrtpContext (void) |
BZRTP_EXPORT int | bzrtp_initBzrtpContext (bzrtpContext_t *context, uint32_t selfSSRC) |
Perform initialisation which can't be done without ZIDcache acces. | |
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. | |
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. | |
BZRTP_EXPORT int | bzrtp_setZIDCache (bzrtpContext_t *context, void *zidCache, const char *selfURI, const char *peerURI) |
Set the pointer allowing cache access. | |
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) | |
BZRTP_EXPORT int | bzrtp_addChannel (bzrtpContext_t *zrtpContext, uint32_t selfSSRC) |
Add a channel to an existing context. | |
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. | |
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. | |
BZRTP_EXPORT int | bzrtp_processMessage (bzrtpContext_t *zrtpContext, uint32_t selfSSRC, uint8_t *zrtpPacketString, uint16_t zrtpPacketStringLength) |
Process a received message. | |
BZRTP_EXPORT void | bzrtp_SASVerified (bzrtpContext_t *zrtpContext) |
Called by user when the SAS has been verified. | |
BZRTP_EXPORT void | bzrtp_resetSASVerified (bzrtpContext_t *zrtpContext) |
Called by user when the SAS has been set to unverified. | |
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: | |
BZRTP_EXPORT uint8_t | bzrtp_getSupportedCryptoTypes (bzrtpContext_t *zrtpContext, uint8_t algoType, uint8_t supportedTypes[7]) |
Get the supported crypto types. | |
BZRTP_EXPORT int | bzrtp_setSupportedCryptoTypes (bzrtpContext_t *zrtpContext, uint8_t algoType, uint8_t supportedTypes[7], uint8_t supportedTypesCount) |
set the supported crypto types. This function must be called before the context is initialised, just after creation. | |
BZRTP_EXPORT int | bzrtp_setFlags (bzrtpContext_t *zrtpContext, uint8_t flagId, uint8_t value) |
Set the selfAcceptGoClear flag. | |
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. | |
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. | |
BZRTP_EXPORT int | bzrtp_getChannelStatus (bzrtpContext_t *zrtpContext, uint32_t selfSSRC) |
Get the channel status. | |
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. | |
BZRTP_EXPORT uint8_t | bzrtp_getAuxiliarySharedSecretMismatch (bzrtpContext_t *zrtpContext) |
Get the ZRTP auxiliary shared secret mismatch status. | |
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. | |
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. | |
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) | |
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 | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
BZRTP_EXPORT const char * | bzrtp_algoToString (uint8_t algo) |
Retrieve the name of the algo in string. | |
BZRTP_EXPORT int | bzrtp_set_MTU (bzrtpContext_t *zrtpContext, size_t mtu) |
set the maximum size of a ZRTP packet generated locally MTU must be at least 600 bytes to avoid useless fragmentation of small packets | |
BZRTP_EXPORT size_t | bzrtp_get_MTU (bzrtpContext_t *zrtpContext) |
get the maximum size of a ZRTP packet generated locally | |
BZRTP_EXPORT uint8_t | bzrtp_available_key_agreement (uint8_t availableTypes[256]) |
Retrieve the list of available key agreements algorithms. | |
BZRTP_EXPORT bool_t | bzrtp_is_PQ_available (void) |
check is Post Quantum algorithms are available | |
BZRTP_EXPORT int | bzrtp_sendGoClear (bzrtpContext_t *context, uint32_t selfSSRC) |
Create a GoClear event and send it to the state machine The user is in secure state. He decided to change his encryption mode by clicking on a button for example. The end point continues to send SRTP packets. On ClearACK reception the end point deletes all key materials. | |
BZRTP_EXPORT int | bzrtp_confirmGoClear (bzrtpContext_t *zrtpContext, uint32_t selfSSRC) |
Create a acceptGoClear event and send it to the state machine The user received a valid GoClear packet and sent a ClearACK message (so the end point stops to send SRTP packets). He agrees to change the encryption mode by clicking on a button for example. The the sending of RTP packets may begin. | |
BZRTP_EXPORT int | bzrtp_backToSecureMode (bzrtpContext_t *zrtpContext, uint32_t selfSSRC) |
Create a BackToSecure event and send it to the state machine The user has a clear channel. He decided to resume the secure mode by clicking on a button for example. | |
#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_CLEAR 0x1010 |
#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_GOCLEARDISABLED 0x4000 |
#define BZRTP_ERROR_HELLOHASH_MISMATCH 0x0080 |
#define BZRTP_ERROR_INVALIDARGUMENT 0x8000 |
#define BZRTP_ERROR_INVALIDCALLBACKID 0x0001 |
#define BZRTP_ERROR_INVALIDCLEARMAC 0x1000 |
#define BZRTP_ERROR_INVALIDCONTEXT 0x0004 |
#define BZRTP_ERROR_MULTICHANNELNOTSUPPORTEDBYPEER 0x0008 |
#define BZRTP_ERROR_OUTPUTBUFFER_LENGTH 0x0040 |
#define BZRTP_ERROR_PEERDOESNTACCEPTGOCLEAR 0x2000 |
#define BZRTP_ERROR_UNABLETOADDCHANNEL 0x0010 |
#define BZRTP_ERROR_UNABLETOSTARTCHANNEL 0x0020 |
#define BZRTP_EXPORT __attribute__ ((visibility ("default"))) |
#define BZRTP_IS_INITIALISED 0x00 |
#define BZRTP_IS_SECURE 0x01 |
#define BZRTP_MESSAGE_CACHEMISMATCH 0x01 |
#define BZRTP_MESSAGE_DEBUG 0x03 |
#define BZRTP_MESSAGE_ERROR 0x00 |
#define BZRTP_MESSAGE_LOG 0x02 |
#define BZRTP_MESSAGE_PEERACKGOCLEAR 0x05 |
#define BZRTP_MESSAGE_PEERNOTBZRTP 0x03 |
#define BZRTP_MESSAGE_PEERREQUESTGOCLEAR 0x04 |
#define BZRTP_MESSAGE_PEERVERSIONOBSOLETE 0x02 |
#define BZRTP_MESSAGE_WARNING 0x01 |
#define BZRTP_PEER_ACCEPT_GOCLEAR 0x04 |
#define BZRTP_PEER_SUPPORT_MULTICHANNEL 0x02 |
#define BZRTP_RECEPTION_NO 2 |
#define BZRTP_RECEPTION_UNKNOWN 0 |
#define BZRTP_RECEPTION_YES 1 |
#define BZRTP_ROLE_INITIATOR 0 |
#define BZRTP_ROLE_RESPONDER 1 |
#define BZRTP_SELF_ACCEPT_GOCLEAR 0x03 |
#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 0x14 |
#define ZRTP_HASH_N384 0x15 |
#define ZRTP_HASH_S256 0x11 |
#define ZRTP_HASH_S384 0x12 |
#define ZRTP_HASH_S512 0x13 |
#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 0x47 |
#define ZRTP_KEYAGREEMENT_EC25 0x44 |
#define ZRTP_KEYAGREEMENT_EC38 0x48 |
#define ZRTP_KEYAGREEMENT_EC52 0x49 |
#define ZRTP_KEYAGREEMENT_HQC1 0x4d |
#define ZRTP_KEYAGREEMENT_HQC2 0x4e |
#define ZRTP_KEYAGREEMENT_HQC3 0x4f |
#define ZRTP_KEYAGREEMENT_K255 0x43 |
#define ZRTP_KEYAGREEMENT_K255_HQC128 0x52 |
#define ZRTP_KEYAGREEMENT_K255_KYB512 0x51 |
#define ZRTP_KEYAGREEMENT_K255_KYB512_HQC128 0x55 |
#define ZRTP_KEYAGREEMENT_K448 0x46 |
#define ZRTP_KEYAGREEMENT_K448_HQC256 0x54 |
#define ZRTP_KEYAGREEMENT_K448_KYB1024 0x53 |
#define ZRTP_KEYAGREEMENT_K448_KYB1024_HQC256 0x56 |
#define ZRTP_KEYAGREEMENT_KYB1 0x4a |
#define ZRTP_KEYAGREEMENT_KYB2 0x4b |
#define ZRTP_KEYAGREEMENT_KYB3 0x4c |
#define ZRTP_KEYAGREEMENT_Mult 0x9f |
#define ZRTP_KEYAGREEMENT_Prsh 0x9e |
#define ZRTP_KEYAGREEMENT_TYPE 0x08 |
#define ZRTP_KEYAGREEMENT_X255 0x42 |
#define ZRTP_KEYAGREEMENT_X448 0x45 |
#define ZRTP_MAGIC_COOKIE 0x5a525450 |
#define ZRTP_SAS_B256 0xa2 |
#define ZRTP_SAS_B32 0xa1 |
#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 struct bzrtpCallbacks_struct bzrtpCallbacks_t |
All the callback functions provided by the client needed by the ZRTP engine.
typedef struct bzrtpContext_struct bzrtpContext_t |
bzrtpContext_t The ZRTP engine context Store current state, timers, HMAC and encryption keys
typedef struct bzrtpSrtpSecrets_struct bzrtpSrtpSecrets_t |
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.
BZRTP_EXPORT int bzrtp_addChannel | ( | bzrtpContext_t * | zrtpContext, |
uint32_t | selfSSRC | ||
) |
Add a channel to an existing context.
[in,out] | zrtpContext | The zrtp context who will get the additionnal channel |
[in] | selfSSRC | The SSRC given to the channel context |
Add a channel to an existing context.
[in,out] | zrtpContext | The zrtp context who will get the additionnal channel. Must be in secure state. |
[in] | selfSSRC | The SSRC given to the channel context |
BZRTP_EXPORT const char * bzrtp_algoToString | ( | uint8_t | algo | ) |
Retrieve the name of the algo in string.
[in] | algo | Id of the algo |
BZRTP_EXPORT uint8_t bzrtp_available_key_agreement | ( | uint8_t | availableTypes[256] | ) |
Retrieve the list of available key agreements algorithms.
[in/out] | algos an array containing the list of available algorithms mapped on uint8 as defined in this header(ZRTP_KEYAGREEMENT_<ID>). Caller is responsible for the array allocation |
BZRTP_EXPORT int bzrtp_backToSecureMode | ( | bzrtpContext_t * | zrtpContext, |
uint32_t | selfSSRC | ||
) |
Create a BackToSecure event and send it to the state machine The user has a clear channel. He decided to resume the secure mode by clicking on a button for example.
zrtpContext | The ZRTP context we're dealing with |
selfSSRC | The SSRC identifying the channel |
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:
This function is intended for use in a mono-device environment.
[in] | dbPointer | Pointer to an already opened sqlite db |
[in] | peerURI | The peer sip:uri we're interested in |
[in] | zidCacheMutex | Points to a mutex used to lock zidCache database access, ignored if NULL |
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.
[in] | cacheXmlPtr | a pointer to an xmlDocPtr structure containing the old cache to be migrated |
[in,out] | cacheSqlite | a pointer to an sqlite3 structure containing a cache initialised using bzrtp_cache_init function |
[in] | selfURI | default sip URI for this end point, NULL terminated char |
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.
[in,out] | dbPointer | Pointer to an already opened sqlite db |
[in] | zuid | The DB internal id to adress the correct row(binding between local uri and peer ZID+URI) |
[in] | tableName | The name of the table to read in the db. Null terminated string |
[in] | columns | An array of null terminated strings containing the name of the columns to read, the array's length is columnsCount |
[out] | values | An array of uint8_t pointers, each one will be allocated to the read value and they must be freed by caller |
[out] | lengths | An array of integer containing the lengths of values array buffer read |
[in] | columnsCount | length common to columns,values and lengths arrays |
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.
[in,out] | dbPointer | Pointer to an already opened sqlite db |
[in] | zuid | The DB internal id to adress the correct row(binding between local uri and peer ZID+URI) |
[in] | tableName | The name of the table to read in the db. Null terminated string |
[in] | columns | An array of null terminated strings containing the name of the columns to read, the array's length is columnsCount |
[out] | values | An array of uint8_t pointers, each one will be allocated to the read value and they must be freed by caller |
[out] | lengths | An array of integer containing the lengths of values array buffer read |
[in] | columnsCount | length common to columns,values and lengths arrays |
[in] | zidCacheMutex | Points to a mutex used to lock zidCache database access, ignored if NULL |
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.
[in,out] | dbPointer | Pointer to an already opened sqlite db |
[in] | zuid | The DB internal id to adress the correct row(binding between local uri and peer ZID+URI) |
[in] | tableName | The name of the table to write in the db, must already exists. Null terminated string |
[in] | columns | An array of null terminated strings containing the name of the columns to update |
[in] | values | An array of buffers containing the values to insert/update matching the order of columns array |
[in] | lengths | An array of integer containing the lengths of values array buffer matching the order of columns array |
[in] | columnsCount | length common to columns,values and lengths arrays |
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.
[in,out] | dbPointer | Pointer to an already opened sqlite db |
[in] | zuid | The DB internal id to adress the correct row(binding between local uri and peer ZID+URI) |
[in] | tableName | The name of the table to write in the db, must already exists. Null terminated string |
[in] | columns | An array of null terminated strings containing the name of the columns to update |
[in] | values | An array of buffers containing the values to insert/update matching the order of columns array |
[in] | lengths | An array of integer containing the lengths of values array buffer matching the order of columns array |
[in] | columnsCount | length common to columns,values and lengths arrays |
[in] | zidCacheMutex | Points to a mutex used to lock zidCache database access, ignored if NULL |
BZRTP_EXPORT int bzrtp_confirmGoClear | ( | bzrtpContext_t * | zrtpContext, |
uint32_t | selfSSRC | ||
) |
Create a acceptGoClear event and send it to the state machine The user received a valid GoClear packet and sent a ClearACK message (so the end point stops to send SRTP packets). He agrees to change the encryption mode by clicking on a button for example. The the sending of RTP packets may begin.
[in] | context | The ZRTP context we're dealing with |
[in] | selfSSRC | The SSRC identifying the channel |
BZRTP_EXPORT bzrtpContext_t * bzrtp_createBzrtpContext | ( | void | ) |
Create context structure and initialise it
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
[in] | context | Context hosting the channel to be destroyed.(note: the context zrtp context itself is destroyed with the last channel) |
[in] | selfSSRC | The SSRC identifying the channel to be destroyed |
BZRTP_EXPORT int bzrtp_exportKey | ( | bzrtpContext_t * | zrtpContext, |
char * | label, | ||
size_t | labelLength, | ||
uint8_t * | derivedKey, | ||
size_t * | derivedKeyLength | ||
) |
BZRTP_EXPORT size_t bzrtp_get_MTU | ( | bzrtpContext_t * | zrtpContext | ) |
get the maximum size of a ZRTP packet generated locally
[in] | zrtpContext | The ZRTP context we're dealing with |
BZRTP_EXPORT uint8_t bzrtp_getAuxiliarySharedSecretMismatch | ( | bzrtpContext_t * | zrtpContext | ) |
Get the ZRTP auxiliary shared secret mismatch status.
[in] | zrtpContext | The ZRTP context we're dealing with |
BZRTP_EXPORT int bzrtp_getChannelStatus | ( | bzrtpContext_t * | zrtpContext, |
uint32_t | selfSSRC | ||
) |
Get the channel status.
[in] | zrtpContext | The ZRTP context we're dealing with |
[in] | selfSSRC | The SSRC identifying the 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.
[in,out] | zrtpContext | The ZRTP context we're dealing with |
[in] | selfSSRC | The SSRC identifying the channel |
[out] | output | A 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] | outputLength | Length of output buffer, shall be at least 70 : 5 chars for version, 64 for the hash itself, SHA256), NULL termination |
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)
[in,out] | db | sqlite3 database(or NULL if we don't use cache at runtime) Use a void * to keep this API when building cacheless |
[in] | selfURI | the sip uri of local user, NULL terminated string |
[out] | selfZID | the ZID, retrieved from cache or randomly generated |
[in] | RNGContext | A RNG context used to generate ZID if needed |
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
[in,out] | db | sqlite3 database(or NULL if we don't use cache at runtime) Use a void * to keep this API when building cacheless |
[in] | selfURI | the sip uri of local user, NULL terminated string |
[out] | selfZID | the ZID, retrieved from cache or randomly generated |
[in] | RNGContext | A RNG context used to generate ZID if needed |
[in] | zidCacheMutex | Points to a mutex used to lock zidCache database access, ignored if NULL |
BZRTP_EXPORT uint8_t bzrtp_getSupportedCryptoTypes | ( | bzrtpContext_t * | zrtpContext, |
uint8_t | algoType, | ||
uint8_t | supportedTypes[7] | ||
) |
Get the supported crypto types.
[in] | zrtpContext | The ZRTP context we're dealing with |
[in] | algoType | mapped to defines, must be in [ZRTP_HASH_TYPE, ZRTP_CIPHERBLOCK_TYPE, ZRTP_AUTHTAG_TYPE, ZRTP_KEYAGREEMENT_TYPE or ZRTP_SAS_TYPE] |
[out] | supportedTypes | mapped 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 |
BZRTP_EXPORT int bzrtp_initBzrtpContext | ( | bzrtpContext_t * | context, |
uint32_t | selfSSRC | ||
) |
Perform initialisation which can't be done without ZIDcache acces.
[in] | context | The context to initialise |
[in] | selfSSRC | The SSRC given to the first channel context created within the zrtpContext |
Perform initialisation which can't be done without ZIDcache acces.
[in] | context | The context to initialise |
[in] | selfSSRC | SSRC of the first channel |
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.
[in,out] | db | Pointer to the sqlite3 db open connection Use a void * to keep this API when building cacheless |
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
[in,out] | db | Pointer to the sqlite3 db open connection Use a void * to keep this API when building cacheless |
[in] | zidCacheMutex | Points to a mutex used to lock zidCache database access, ignored if NULL |
BZRTP_EXPORT bool_t bzrtp_is_PQ_available | ( | void | ) |
check is Post Quantum algorithms are available
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.
[in,out] | zrtpContext | The ZRTP context hosting the channel |
[in] | selfSSRC | The SSRC identifying the channel |
[in] | timeReference | The current time in ms |
BZRTP_EXPORT int bzrtp_processMessage | ( | bzrtpContext_t * | zrtpContext, |
uint32_t | selfSSRC, | ||
uint8_t * | zrtpPacketString, | ||
uint16_t | zrtpPacketStringLength | ||
) |
Process a received message.
[in,out] | zrtpContext | The ZRTP context we're dealing with |
[in] | selfSSRC | The SSRC identifying the channel receiving the message |
[in] | zrtpPacketString | The packet received |
[in] | zrtpPacketStringLength | Length of the packet in bytes |
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:
[in,out] | zrtpContext | The ZRTP context we're dealing with |
[in] | selfSSRC | The SSRC identifying the channel to reset |
BZRTP_EXPORT void bzrtp_resetSASVerified | ( | bzrtpContext_t * | zrtpContext | ) |
Called by user when the SAS has been set to unverified.
[in,out] | zrtpContext | The ZRTP context we're dealing with |
BZRTP_EXPORT void bzrtp_SASVerified | ( | bzrtpContext_t * | zrtpContext | ) |
Called by user when the SAS has been verified.
[in,out] | zrtpContext | The ZRTP context we're dealing with |
BZRTP_EXPORT int bzrtp_sendGoClear | ( | bzrtpContext_t * | context, |
uint32_t | selfSSRC | ||
) |
Create a GoClear event and send it to the state machine The user is in secure state. He decided to change his encryption mode by clicking on a button for example. The end point continues to send SRTP packets. On ClearACK reception the end point deletes all key materials.
[in] | context | The ZRTP context we're dealing with |
[in] | selfSSRC | The SSRC identifying the channel |
BZRTP_EXPORT int bzrtp_set_MTU | ( | bzrtpContext_t * | zrtpContext, |
size_t | mtu | ||
) |
set the maximum size of a ZRTP packet generated locally MTU must be at least 600 bytes to avoid useless fragmentation of small packets
[in] | zrtpContext | The ZRTP context we're dealing with |
[in] | mtu | The size in bytes of the maximum allowed for a ZRTP packet. If this parameter is less than 600, the actual MTU is set to 600 |
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.
[in] | zrtpContext | The ZRTP context we're dealing with |
[in] | auxSecret | A buffer holding the auxiliary shared secret to use (see RFC 6189 section 4.3) |
[in] | auxSecretLength | lenght of the previous buffer |
BZRTP_EXPORT int bzrtp_setCallbacks | ( | bzrtpContext_t * | context, |
const bzrtpCallbacks_t * | cbs | ||
) |
Allocate a function pointer to the callback function identified by his id.
[in,out] | context | The zrtp context to set the callback function |
[in] | cbs | A structure containing all the callbacks to supply. |
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)
[in,out] | zrtpContext | The ZRTP context we're dealing with |
[in] | selfSSRC | The SSRC identifying the channel to be linked to the client Data |
[in] | clientData | The clientData pointer, casted to a (void *) |
BZRTP_EXPORT int bzrtp_setFlags | ( | bzrtpContext_t * | zrtpContext, |
uint8_t | flagId, | ||
uint8_t | value | ||
) |
Set the selfAcceptGoClear flag.
[in,out] | zrtpContext | The ZRTP context we're dealing with |
[in] | flagId | mapped to defines, must be BZRTP_SELF_ACCEPT_GOCLEAR |
[in] | value | Flag value |
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.
[in,out] | zrtpContext | The ZRTP context we're dealing with |
[in] | selfSSRC | The SSRC identifying the channel |
[in] | peerHelloHashHexString | A NULL terminated string containing the hexadecimal form of the hash received in signaling, may contain ZRTP version as header. |
[in] | peerHelloHashHexStringLength | Length of hash string (shall be at least 64 as the hash is a SHA256 so 32 bytes, more if it contains the version header) |
[in,out] | zrtpContext | The ZRTP context we're dealing with |
[in] | selfSSRC | The SSRC identifying the channel |
[out] | peerHelloHashHexString | A NULL terminated string containing the hexadecimal form of the hash received in signaling, may contain ZRTP version as header. |
[in] | peerHelloHashHexStringLength | Length of hash string (shall be at least 64 as the hash is a SHA256 so 32 bytes, more if it contains the version header) |
BZRTP_EXPORT int bzrtp_setSupportedCryptoTypes | ( | bzrtpContext_t * | zrtpContext, |
uint8_t | algoType, | ||
uint8_t | supportedTypes[7], | ||
uint8_t | supportedTypesCount | ||
) |
set the supported crypto types. This function must be called before the context is initialised, just after creation.
[in,out] | zrtpContext | The ZRTP context we're dealing with |
[in] | algoType | mapped to defines, must be in [ZRTP_HASH_TYPE, ZRTP_CIPHERBLOCK_TYPE, ZRTP_AUTHTAG_TYPE, ZRTP_KEYAGREEMENT_TYPE or ZRTP_SAS_TYPE] |
[in] | supportedTypes | mapped 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] | supportedTypesCount | number of supported crypto types |
set the supported crypto types. This function must be called before the context is initialised, just after creation.
[in,out] | zrtpContext | The ZRTP context we're dealing with |
[in] | algoType | mapped to defines, must be in [ZRTP_HASH_TYPE, ZRTP_CIPHERBLOCK_TYPE, ZRTP_AUTHTAG_TYPE, ZRTP_KEYAGREEMENT_TYPE or ZRTP_SAS_TYPE] |
[in] | supportedTypes | mapped 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] | supportedTypesCount | number 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.
[in,out] | context | The ZRTP context we're dealing with |
[in] | zidCache | Used by internal function to access cache: turn into a sqlite3 pointer if cache is enabled |
[in] | selfURI | Local URI used for this communication, needed to perform cache operation, NULL terminated string, duplicated by this function |
[in] | peerURI | Peer URI used for this communication, needed to perform cache operation, NULL terminated string, duplicated by this function |
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.
[in,out] | context | The ZRTP context we're dealing with |
[in] | zidCache | Used by internal function to access cache: turn into a sqlite3 pointer if cache is enabled |
[in] | selfURI | Local URI used for this communication, needed to perform cache operation, NULL terminated string, duplicated by this function |
[in] | peerURI | Peer URI used for this communication, needed to perform cache operation, NULL terminated string, duplicated by this function |
[in] | zidCacheMutex | Points to a mutex used to lock zidCache database access |
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.
[in,out] | zrtpContext | The ZRTP context hosting the channel to be started |
[in] | selfSSRC | The SSRC identifying the channel to be started(will start sending Hello packets and listening for some) |