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

Macros

#define BZRTP_ERROR_INVALIDCHANNELCONTEXT   0x8001
 

Functions

static int bzrtp_initChannelContext (bzrtpContext_t *zrtpContext, bzrtpChannelContext_t *zrtpChannelContext, uint32_t selfSSRC, uint8_t isMain)
 Initialise the context of a channel and create and store the Hello packet Initialise some vectors.
 
static void bzrtp_destroyChannelContext (bzrtpContext_t *zrtpContext, bzrtpChannelContext_t *zrtpChannelContext)
 Destroy the context of a channel Free allocated buffers, destroy keys.
 
static bzrtpChannelContext_tgetChannelContext (bzrtpContext_t *zrtpContext, uint32_t selfSSRC)
 Look in the given ZRTP context for a channel referenced with given SSRC.
 
static uint8_t copyCryptoTypes (uint8_t destination[7], uint8_t source[7], uint8_t size)
 
bzrtpContext_tbzrtp_createBzrtpContext (void)
 
int bzrtp_setZIDCache (bzrtpContext_t *context, void *zidCache, const char *selfURI, const char *peerURI)
 Set the pointer allowing cache access.
 
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.
 
int bzrtp_initBzrtpContext (bzrtpContext_t *context, uint32_t selfSSRC)
 Perform some initialisation which can't be done without some callback functions: This function is called once per session when the first channel is created. It must be called after the cache access pointer have been set.
 
int bzrtp_destroyBzrtpContext (bzrtpContext_t *context, uint32_t selfSSRC)
 
int bzrtp_setCallbacks (bzrtpContext_t *context, const bzrtpCallbacks_t *cbs)
 Allocate a function pointer to the callback function identified by his id.
 
int bzrtp_addChannel (bzrtpContext_t *zrtpContext, uint32_t selfSSRC)
 Add a channel to an existing context, this can be done only if the first channel has concluded a DH key agreement.
 
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.
 
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.
 
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)
 
int bzrtp_processMessage (bzrtpContext_t *zrtpContext, uint32_t selfSSRC, uint8_t *zrtpPacketString, uint16_t zrtpPacketStringLength)
 Process a received message.
 
void bzrtp_SASVerified (bzrtpContext_t *zrtpContext)
 Called by user when the SAS has been verified.
 
void bzrtp_resetSASVerified (bzrtpContext_t *zrtpContext)
 Called by user when the SAS has been set to unverified.
 
int bzrtp_exportKey (bzrtpContext_t *zrtpContext, char *label, size_t labelLength, uint8_t *derivedKey, size_t *derivedKeyLength)
 
int bzrtp_resetRetransmissionTimer (bzrtpContext_t *zrtpContext, uint32_t selfSSRC)
 Reset the retransmission timer of a given channel. Packets will be sent again if appropriate:
 
uint8_t bzrtp_getSupportedCryptoTypes (bzrtpContext_t *zrtpContext, uint8_t algoType, uint8_t supportedTypes[7])
 Get the supported crypto types.
 
int bzrtp_setSupportedCryptoTypes (bzrtpContext_t *zrtpContext, uint8_t algoType, uint8_t supportedTypes[7], uint8_t supportedTypesCount)
 set the supported crypto types
 
int bzrtp_setFlags (bzrtpContext_t *zrtpContext, uint8_t flagId, uint8_t value)
 Set the selfAcceptGoClear flag.
 
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.
 
int bzrtp_getSelfHelloHash (bzrtpContext_t *zrtpContext, uint32_t selfSSRC, uint8_t *output, size_t outputLength)
 Get the self hello hash from ZRTP channel.
 
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.
 
uint8_t bzrtp_getAuxiliarySharedSecretMismatch (bzrtpContext_t *zrtpContext)
 Get the ZRTP auxiliary shared secret mismatch status.
 
int bzrtp_getChannelStatus (bzrtpContext_t *zrtpContext, uint32_t selfSSRC)
 Get the channel status.
 
const char * bzrtp_algoToString (uint8_t algo)
 Retrieve the name of the algo in string.
 
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
 
size_t bzrtp_get_MTU (bzrtpContext_t *zrtpContext)
 get the maximum size of a ZRTP packet generated locally
 
int bzrtp_sendGoClear (bzrtpContext_t *zrtpContext, 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.
 
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.
 
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_ERROR_INVALIDCHANNELCONTEXT

#define BZRTP_ERROR_INVALIDCHANNELCONTEXT   0x8001

Function Documentation

◆ bzrtp_addChannel()

int bzrtp_addChannel ( bzrtpContext_t zrtpContext,
uint32_t  selfSSRC 
)

Add a channel to an existing context, this can be done only if the first channel has concluded a DH key agreement.

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

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

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

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

bzrtpContext_t * bzrtp_createBzrtpContext ( void  )

Create context structure and initialise it

Returns
The ZRTP engine context data

◆ bzrtp_destroyBzrtpContext()

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

static void bzrtp_destroyChannelContext ( bzrtpContext_t zrtpContext,
bzrtpChannelContext_t zrtpChannelContext 
)
static

Destroy the context of a channel Free allocated buffers, destroy keys.

Parameters
[in]zrtpContextThe zrtpContext hosting this channel, needed to acces the RNG
[in]zrtpChannelContextThe channel context to be destroyed

◆ bzrtp_exportKey()

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

◆ bzrtp_get_MTU()

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

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

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

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

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

int bzrtp_initBzrtpContext ( bzrtpContext_t context,
uint32_t  selfSSRC 
)

Perform some initialisation which can't be done without some callback functions: This function is called once per session when the first channel is created. It must be called after the cache access pointer have been set.

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

static int bzrtp_initChannelContext ( bzrtpContext_t zrtpContext,
bzrtpChannelContext_t zrtpChannelContext,
uint32_t  selfSSRC,
uint8_t  isMain 
)
static

Initialise the context of a channel and create and store the Hello packet Initialise some vectors.

Parameters
[in]zrtpContextThe zrtpContext hosting this channel, needed to acces the RNG
[out]zrtpChannelContextThe channel context to be initialised
[in]selfSSRCThe SSRC allocated to this channel
[in]isMainThis channel is channel 0 or an additional channel
Returns
0 on success, error code otherwise

◆ bzrtp_iterate()

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

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

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

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

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

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

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

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

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

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

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

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

int bzrtp_setSupportedCryptoTypes ( bzrtpContext_t zrtpContext,
uint8_t  algoType,
uint8_t  supportedTypes[7],
uint8_t  supportedTypesCount 
)

set the supported crypto types

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

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

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

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

◆ copyCryptoTypes()

static uint8_t copyCryptoTypes ( uint8_t  destination[7],
uint8_t  source[7],
uint8_t  size 
)
static

◆ getChannelContext()

static bzrtpChannelContext_t * getChannelContext ( bzrtpContext_t zrtpContext,
uint32_t  selfSSRC 
)
static

Look in the given ZRTP context for a channel referenced with given SSRC.

Parameters
[in]zrtpContextThe zrtp context which shall contain the channel context we are looking for
[in]selfSSRCThe SSRC identifying the channel context
Returns
a pointer to the channel context, NULL if the context is invalid or channel not found