bZRTP
bZRTP is an opensource implementation of ZRTP keys exchange protocol
Loading...
Searching...
No Matches
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_S512   0x13
 
#define ZRTP_HASH_N256   0x14
 
#define ZRTP_HASH_N384   0x15
 
#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_K255   0x43
 
#define ZRTP_KEYAGREEMENT_EC25   0x44
 
#define ZRTP_KEYAGREEMENT_X448   0x45
 
#define ZRTP_KEYAGREEMENT_K448   0x46
 
#define ZRTP_KEYAGREEMENT_DH3k   0x47
 
#define ZRTP_KEYAGREEMENT_EC38   0x48
 
#define ZRTP_KEYAGREEMENT_EC52   0x49
 
#define ZRTP_KEYAGREEMENT_KYB1   0x4a
 
#define ZRTP_KEYAGREEMENT_KYB2   0x4b
 
#define ZRTP_KEYAGREEMENT_KYB3   0x4c
 
#define ZRTP_KEYAGREEMENT_HQC1   0x4d
 
#define ZRTP_KEYAGREEMENT_HQC2   0x4e
 
#define ZRTP_KEYAGREEMENT_HQC3   0x4f
 
#define ZRTP_KEYAGREEMENT_K255_KYB512   0x51
 
#define ZRTP_KEYAGREEMENT_K255_HQC128   0x52
 
#define ZRTP_KEYAGREEMENT_K448_KYB1024   0x53
 
#define ZRTP_KEYAGREEMENT_K448_HQC256   0x54
 
#define ZRTP_KEYAGREEMENT_K255_KYB512_HQC128   0x55
 
#define ZRTP_KEYAGREEMENT_K448_KYB1024_HQC256   0x56
 
#define ZRTP_KEYAGREEMENT_Prsh   0x9e
 
#define ZRTP_KEYAGREEMENT_Mult   0x9f
 
#define ZRTP_SAS_B32   0xa1
 
#define ZRTP_SAS_B256   0xa2
 
#define ZRTP_SRTP_SECRETS_FOR_SENDER   0x01
 
#define ZRTP_SRTP_SECRETS_FOR_RECEIVER   0x02
 
#define BZRTP_IS_INITIALISED   0x00
 
#define BZRTP_IS_SECURE   0x01
 
#define BZRTP_PEER_SUPPORT_MULTICHANNEL   0x02
 
#define BZRTP_SELF_ACCEPT_GOCLEAR   0x03
 
#define BZRTP_PEER_ACCEPT_GOCLEAR   0x04
 
#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 BZRTP_MESSAGE_PEERREQUESTGOCLEAR   0x04
 
#define BZRTP_MESSAGE_PEERACKGOCLEAR   0x05
 
#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_ERROR_INVALIDCLEARMAC   0x1000
 
#define BZRTP_ERROR_PEERDOESNTACCEPTGOCLEAR   0x2000
 
#define BZRTP_ERROR_GOCLEARDISABLED   0x4000
 
#define BZRTP_ERROR_INVALIDARGUMENT   0x8000
 
#define BZRTP_CHANNEL_NOTFOUND   0x1000
 
#define BZRTP_CHANNEL_INITIALISED   0x1001
 
#define BZRTP_CHANNEL_ONGOING   0x1002
 
#define BZRTP_CHANNEL_SECURE   0x1004
 
#define BZRTP_CHANNEL_CLEAR   0x1010
 
#define BZRTP_CHANNEL_ERROR   0x1008
 
#define BZRTP_ROLE_INITIATOR   0
 
#define BZRTP_ROLE_RESPONDER   1
 
#define BZRTP_RECEPTION_UNKNOWN   0
 
#define BZRTP_RECEPTION_YES   1
 
#define BZRTP_RECEPTION_NO   2
 
#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.
 
typedef struct bzrtpContext_struct bzrtpContext_t
 bzrtpContext_t The ZRTP engine context Store current state, timers, HMAC and encryption keys
 

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

Macro Definition Documentation

◆ BZRTP_AUXSECRET_MATCH

#define BZRTP_AUXSECRET_MATCH   0x00

◆ BZRTP_AUXSECRET_MISMATCH

#define BZRTP_AUXSECRET_MISMATCH   0x01

◆ BZRTP_AUXSECRET_UNSET

#define BZRTP_AUXSECRET_UNSET   0x02

◆ BZRTP_CACHE_DATA_NOTFOUND

#define BZRTP_CACHE_DATA_NOTFOUND   0x2002

◆ BZRTP_CACHE_PEER_STATUS_INVALID

#define BZRTP_CACHE_PEER_STATUS_INVALID   0x2012

◆ BZRTP_CACHE_PEER_STATUS_UNKNOWN

#define BZRTP_CACHE_PEER_STATUS_UNKNOWN   0x2010

◆ BZRTP_CACHE_PEER_STATUS_VALID

#define BZRTP_CACHE_PEER_STATUS_VALID   0x2011

◆ BZRTP_CACHE_SETUP

#define BZRTP_CACHE_SETUP   0x2000

◆ BZRTP_CACHE_UPDATE

#define BZRTP_CACHE_UPDATE   0x2001

◆ BZRTP_CHANNEL_CLEAR

#define BZRTP_CHANNEL_CLEAR   0x1010

◆ BZRTP_CHANNEL_ERROR

#define BZRTP_CHANNEL_ERROR   0x1008

◆ BZRTP_CHANNEL_INITIALISED

#define BZRTP_CHANNEL_INITIALISED   0x1001

◆ BZRTP_CHANNEL_NOTFOUND

#define BZRTP_CHANNEL_NOTFOUND   0x1000

◆ BZRTP_CHANNEL_ONGOING

#define BZRTP_CHANNEL_ONGOING   0x1002

◆ BZRTP_CHANNEL_SECURE

#define BZRTP_CHANNEL_SECURE   0x1004

◆ BZRTP_DEPRECATED

#define BZRTP_DEPRECATED   __attribute__ ((deprecated))

◆ BZRTP_ERROR_CACHE_PEERNOTFOUND

#define BZRTP_ERROR_CACHE_PEERNOTFOUND   0x0800

◆ BZRTP_ERROR_CACHEDISABLED

#define BZRTP_ERROR_CACHEDISABLED   0x0200

◆ BZRTP_ERROR_CACHEMIGRATIONFAILED

#define BZRTP_ERROR_CACHEMIGRATIONFAILED   0x0400

◆ BZRTP_ERROR_CHANNELALREADYSTARTED

#define BZRTP_ERROR_CHANNELALREADYSTARTED   0x0100

◆ BZRTP_ERROR_CONTEXTNOTREADY

#define BZRTP_ERROR_CONTEXTNOTREADY   0x0002

◆ BZRTP_ERROR_GOCLEARDISABLED

#define BZRTP_ERROR_GOCLEARDISABLED   0x4000

◆ BZRTP_ERROR_HELLOHASH_MISMATCH

#define BZRTP_ERROR_HELLOHASH_MISMATCH   0x0080

◆ BZRTP_ERROR_INVALIDARGUMENT

#define BZRTP_ERROR_INVALIDARGUMENT   0x8000

◆ BZRTP_ERROR_INVALIDCALLBACKID

#define BZRTP_ERROR_INVALIDCALLBACKID   0x0001

◆ BZRTP_ERROR_INVALIDCLEARMAC

#define BZRTP_ERROR_INVALIDCLEARMAC   0x1000

◆ BZRTP_ERROR_INVALIDCONTEXT

#define BZRTP_ERROR_INVALIDCONTEXT   0x0004

◆ BZRTP_ERROR_MULTICHANNELNOTSUPPORTEDBYPEER

#define BZRTP_ERROR_MULTICHANNELNOTSUPPORTEDBYPEER   0x0008

◆ BZRTP_ERROR_OUTPUTBUFFER_LENGTH

#define BZRTP_ERROR_OUTPUTBUFFER_LENGTH   0x0040

◆ BZRTP_ERROR_PEERDOESNTACCEPTGOCLEAR

#define BZRTP_ERROR_PEERDOESNTACCEPTGOCLEAR   0x2000

◆ BZRTP_ERROR_UNABLETOADDCHANNEL

#define BZRTP_ERROR_UNABLETOADDCHANNEL   0x0010

◆ BZRTP_ERROR_UNABLETOSTARTCHANNEL

#define BZRTP_ERROR_UNABLETOSTARTCHANNEL   0x0020

◆ BZRTP_EXPORT

#define BZRTP_EXPORT   __attribute__ ((visibility ("default")))

◆ BZRTP_IS_INITIALISED

#define BZRTP_IS_INITIALISED   0x00

◆ BZRTP_IS_SECURE

#define BZRTP_IS_SECURE   0x01

◆ BZRTP_MESSAGE_CACHEMISMATCH

#define BZRTP_MESSAGE_CACHEMISMATCH   0x01

◆ BZRTP_MESSAGE_DEBUG

#define BZRTP_MESSAGE_DEBUG   0x03

◆ BZRTP_MESSAGE_ERROR

#define BZRTP_MESSAGE_ERROR   0x00

◆ BZRTP_MESSAGE_LOG

#define BZRTP_MESSAGE_LOG   0x02

◆ BZRTP_MESSAGE_PEERACKGOCLEAR

#define BZRTP_MESSAGE_PEERACKGOCLEAR   0x05

◆ BZRTP_MESSAGE_PEERNOTBZRTP

#define BZRTP_MESSAGE_PEERNOTBZRTP   0x03

◆ BZRTP_MESSAGE_PEERREQUESTGOCLEAR

#define BZRTP_MESSAGE_PEERREQUESTGOCLEAR   0x04

◆ BZRTP_MESSAGE_PEERVERSIONOBSOLETE

#define BZRTP_MESSAGE_PEERVERSIONOBSOLETE   0x02

◆ BZRTP_MESSAGE_WARNING

#define BZRTP_MESSAGE_WARNING   0x01

◆ BZRTP_PEER_ACCEPT_GOCLEAR

#define BZRTP_PEER_ACCEPT_GOCLEAR   0x04

◆ BZRTP_PEER_SUPPORT_MULTICHANNEL

#define BZRTP_PEER_SUPPORT_MULTICHANNEL   0x02

◆ BZRTP_RECEPTION_NO

#define BZRTP_RECEPTION_NO   2

◆ BZRTP_RECEPTION_UNKNOWN

#define BZRTP_RECEPTION_UNKNOWN   0

◆ BZRTP_RECEPTION_YES

#define BZRTP_RECEPTION_YES   1

◆ BZRTP_ROLE_INITIATOR

#define BZRTP_ROLE_INITIATOR   0

◆ BZRTP_ROLE_RESPONDER

#define BZRTP_ROLE_RESPONDER   1

◆ BZRTP_SELF_ACCEPT_GOCLEAR

#define BZRTP_SELF_ACCEPT_GOCLEAR   0x03

◆ BZRTP_ZIDCACHE_BADINPUTDATA

#define BZRTP_ZIDCACHE_BADINPUTDATA   0x2105

◆ BZRTP_ZIDCACHE_INVALID_CACHE

#define BZRTP_ZIDCACHE_INVALID_CACHE   0x2102

◆ BZRTP_ZIDCACHE_INVALID_CONTEXT

#define BZRTP_ZIDCACHE_INVALID_CONTEXT   0x2101

◆ BZRTP_ZIDCACHE_RUNTIME_CACHELESS

#define BZRTP_ZIDCACHE_RUNTIME_CACHELESS   0x2110

◆ BZRTP_ZIDCACHE_UNABLETOREAD

#define BZRTP_ZIDCACHE_UNABLETOREAD   0x2104

◆ BZRTP_ZIDCACHE_UNABLETOUPDATE

#define BZRTP_ZIDCACHE_UNABLETOUPDATE   0x2103

◆ ZRTP_AUTHTAG_HS32

#define ZRTP_AUTHTAG_HS32   0x31

◆ ZRTP_AUTHTAG_HS80

#define ZRTP_AUTHTAG_HS80   0x32

◆ ZRTP_AUTHTAG_SK32

#define ZRTP_AUTHTAG_SK32   0x33

◆ ZRTP_AUTHTAG_SK64

#define ZRTP_AUTHTAG_SK64   0x34

◆ ZRTP_AUTHTAG_TYPE

#define ZRTP_AUTHTAG_TYPE   0x04

◆ ZRTP_CIPHER_2FS1

#define ZRTP_CIPHER_2FS1   0x24

◆ ZRTP_CIPHER_2FS2

#define ZRTP_CIPHER_2FS2   0x25

◆ ZRTP_CIPHER_2FS3

#define ZRTP_CIPHER_2FS3   0x26

◆ ZRTP_CIPHER_AES1

#define ZRTP_CIPHER_AES1   0x21

◆ ZRTP_CIPHER_AES2

#define ZRTP_CIPHER_AES2   0x22

◆ ZRTP_CIPHER_AES3

#define ZRTP_CIPHER_AES3   0x23

◆ ZRTP_CIPHERBLOCK_TYPE

#define ZRTP_CIPHERBLOCK_TYPE   0x02

◆ ZRTP_HASH_N256

#define ZRTP_HASH_N256   0x14

◆ ZRTP_HASH_N384

#define ZRTP_HASH_N384   0x15

◆ ZRTP_HASH_S256

#define ZRTP_HASH_S256   0x11

◆ ZRTP_HASH_S384

#define ZRTP_HASH_S384   0x12

◆ ZRTP_HASH_S512

#define ZRTP_HASH_S512   0x13

◆ ZRTP_HASH_TYPE

#define ZRTP_HASH_TYPE   0x01

Define different types of crypto functions

◆ ZRTP_KEYAGREEMENT_DH2k

#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)

◆ ZRTP_KEYAGREEMENT_DH3k

#define ZRTP_KEYAGREEMENT_DH3k   0x47

◆ ZRTP_KEYAGREEMENT_EC25

#define ZRTP_KEYAGREEMENT_EC25   0x44

◆ ZRTP_KEYAGREEMENT_EC38

#define ZRTP_KEYAGREEMENT_EC38   0x48

◆ ZRTP_KEYAGREEMENT_EC52

#define ZRTP_KEYAGREEMENT_EC52   0x49

◆ ZRTP_KEYAGREEMENT_HQC1

#define ZRTP_KEYAGREEMENT_HQC1   0x4d

◆ ZRTP_KEYAGREEMENT_HQC2

#define ZRTP_KEYAGREEMENT_HQC2   0x4e

◆ ZRTP_KEYAGREEMENT_HQC3

#define ZRTP_KEYAGREEMENT_HQC3   0x4f

◆ ZRTP_KEYAGREEMENT_K255

#define ZRTP_KEYAGREEMENT_K255   0x43

◆ ZRTP_KEYAGREEMENT_K255_HQC128

#define ZRTP_KEYAGREEMENT_K255_HQC128   0x52

◆ ZRTP_KEYAGREEMENT_K255_KYB512

#define ZRTP_KEYAGREEMENT_K255_KYB512   0x51

◆ ZRTP_KEYAGREEMENT_K255_KYB512_HQC128

#define ZRTP_KEYAGREEMENT_K255_KYB512_HQC128   0x55

◆ ZRTP_KEYAGREEMENT_K448

#define ZRTP_KEYAGREEMENT_K448   0x46

◆ ZRTP_KEYAGREEMENT_K448_HQC256

#define ZRTP_KEYAGREEMENT_K448_HQC256   0x54

◆ ZRTP_KEYAGREEMENT_K448_KYB1024

#define ZRTP_KEYAGREEMENT_K448_KYB1024   0x53

◆ ZRTP_KEYAGREEMENT_K448_KYB1024_HQC256

#define ZRTP_KEYAGREEMENT_K448_KYB1024_HQC256   0x56

◆ ZRTP_KEYAGREEMENT_KYB1

#define ZRTP_KEYAGREEMENT_KYB1   0x4a

◆ ZRTP_KEYAGREEMENT_KYB2

#define ZRTP_KEYAGREEMENT_KYB2   0x4b

◆ ZRTP_KEYAGREEMENT_KYB3

#define ZRTP_KEYAGREEMENT_KYB3   0x4c

◆ ZRTP_KEYAGREEMENT_Mult

#define ZRTP_KEYAGREEMENT_Mult   0x9f

◆ ZRTP_KEYAGREEMENT_Prsh

#define ZRTP_KEYAGREEMENT_Prsh   0x9e

◆ ZRTP_KEYAGREEMENT_TYPE

#define ZRTP_KEYAGREEMENT_TYPE   0x08

◆ ZRTP_KEYAGREEMENT_X255

#define ZRTP_KEYAGREEMENT_X255   0x42

◆ ZRTP_KEYAGREEMENT_X448

#define ZRTP_KEYAGREEMENT_X448   0x45

◆ ZRTP_MAGIC_COOKIE

#define ZRTP_MAGIC_COOKIE   0x5a525450

◆ ZRTP_SAS_B256

#define ZRTP_SAS_B256   0xa2

◆ ZRTP_SAS_B32

#define ZRTP_SAS_B32   0xa1

◆ ZRTP_SAS_TYPE

#define ZRTP_SAS_TYPE   0x10

◆ ZRTP_SRTP_SECRETS_FOR_RECEIVER

#define ZRTP_SRTP_SECRETS_FOR_RECEIVER   0x02

◆ ZRTP_SRTP_SECRETS_FOR_SENDER

#define ZRTP_SRTP_SECRETS_FOR_SENDER   0x01

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

◆ ZRTP_UNSET_ALGO

#define ZRTP_UNSET_ALGO   0x00

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

◆ ZRTP_VERSION

#define ZRTP_VERSION   "1.10"

Typedef Documentation

◆ bzrtpCallbacks_t

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

◆ bzrtpContext_t

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

◆ 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

◆ zrtpFreeBuffer_callback

typedef void(* zrtpFreeBuffer_callback) (void *)

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

Function Documentation

◆ bzrtp_addChannel()

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

BZRTP_EXPORT const char * bzrtp_algoToString ( uint8_t  algo)

Retrieve the name of the algo in string.

Parameters
[in]algoId of the algo
Returns
The of the algo in string

◆ bzrtp_available_key_agreement()

BZRTP_EXPORT uint8_t bzrtp_available_key_agreement ( uint8_t  availableTypes[256])

Retrieve the list of available key agreements algorithms.

Parameters
[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
Returns
The number of available key agreement algorithms

◆ bzrtp_backToSecureMode()

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.

Parameters
zrtpContextThe ZRTP context we're dealing with
selfSSRCThe SSRC identifying the channel
Returns
  • BZRTP_ERROR_INVALIDCONTEXT : The context is invalid
  • Return value of the state machine

◆ bzrtp_cache_getPeerStatus_lock()

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

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

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

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

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

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

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.

Parameters
[in]contextThe ZRTP context we're dealing with
[in]selfSSRCThe SSRC identifying the channel
Returns
one of :
  • BZRTP_ERROR_INVALIDCONTEXT : The context is invalid
  • Return value of the state machine

◆ bzrtp_createBzrtpContext()

BZRTP_EXPORT bzrtpContext_t * bzrtp_createBzrtpContext ( void  )

Create context structure and initialise it

Returns
The ZRTP engine context data

◆ bzrtp_destroyBzrtpContext()

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

BZRTP_EXPORT int bzrtp_exportKey ( bzrtpContext_t zrtpContext,
char *  label,
size_t  labelLength,
uint8_t derivedKey,
size_t *  derivedKeyLength 
)

◆ bzrtp_get_MTU()

BZRTP_EXPORT size_t bzrtp_get_MTU ( bzrtpContext_t zrtpContext)

get the maximum size of a ZRTP packet generated locally

Parameters
[in]zrtpContextThe ZRTP context we're dealing with
Returns
the maximum size in bytes of a ZRTP packet generated locally

◆ bzrtp_getAuxiliarySharedSecretMismatch()

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

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

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

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

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

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

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

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

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

BZRTP_EXPORT bool_t bzrtp_is_PQ_available ( void  )

check is Post Quantum algorithms are available

Returns
TRUE when PQ key exchange algorithms are available, FALSE otherwise

◆ bzrtp_iterate()

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

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

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
Returns
0 on success, error code otherwise

◆ bzrtp_resetSASVerified()

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

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

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.

Parameters
[in]contextThe ZRTP context we're dealing with
[in]selfSSRCThe SSRC identifying the channel
Returns
one of :
  • BZRTP_ERROR_INVALIDCONTEXT : The context is invalid or the channel is not in secure state
  • Return value of the state machine

◆ bzrtp_set_MTU()

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

Parameters
[in]zrtpContextThe ZRTP context we're dealing with
[in]mtuThe 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
Returns
0 on succes, error code otherwise

◆ bzrtp_setAuxiliarySharedSecret()

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

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

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

BZRTP_EXPORT int bzrtp_setFlags ( bzrtpContext_t zrtpContext,
uint8_t  flagId,
uint8_t  value 
)

Set the selfAcceptGoClear flag.

Parameters
[in,out]zrtpContextThe ZRTP context we're dealing with
[in]flagIdmapped to defines, must be BZRTP_SELF_ACCEPT_GOCLEAR
[in]valueFlag value

◆ bzrtp_setPeerHelloHash()

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

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.

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
Returns
0 on success, error code otherwise

set the supported crypto types. This function must be called before the context is initialised, just after creation.

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

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

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

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