bzrtp.h 23.8 KB
Newer Older
johan's avatar
johan committed
1 2 3 4 5 6 7
/**
 @file bzrtp.h

 @brief Public entry points to the ZRTP implementation

 @author Johan Pascal

8
 @copyright Copyright (C) 2017 Belledonne Communications, Grenoble, France
johan's avatar
johan committed
9 10 11 12 13 14 15 16 17 18 19 20 21
 
 This program is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation; either version 2
 of the License, or (at your option) any later version.
 
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
22
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
johan's avatar
johan committed
23 24 25
 */
#ifndef BZRTP_H
#define BZRTP_H
26

johan's avatar
johan committed
27
#include <stdint.h>
johan's avatar
johan committed
28
#include "bctoolbox/crypto.h"
johan's avatar
johan committed
29

30
#ifdef _MSC_VER
31 32 33 34 35 36 37 38 39
	#ifdef BZRTP_STATIC
		#define BZRTP_EXPORT
	#else
		#ifdef BZRTP_EXPORTS
			#define BZRTP_EXPORT __declspec(dllexport)
		#else
			#define BZRTP_EXPORT __declspec(dllimport)
		#endif
	#endif
40
#else
41
	#define BZRTP_EXPORT __attribute__ ((visibility ("default")))
42 43
#endif

johan's avatar
johan committed
44
/**
45 46 47 48 49 50 51 52 53 54
 * Define different types of crypto functions */
#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

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

johan's avatar
johan committed
55 56
#define ZRTP_UNSET_ALGO			0x00

57 58 59 60 61
#define	ZRTP_HASH_S256			0x11
#define	ZRTP_HASH_S384			0x12
#define	ZRTP_HASH_N256			0x13
#define	ZRTP_HASH_N384			0x14

johan's avatar
johan committed
62 63 64 65 66 67 68 69 70 71 72 73
#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

74 75 76 77 78
/**
 * 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_DH2k	0x41
79 80 81 82 83 84 85 86 87
#define ZRTP_KEYAGREEMENT_X255	0x42
#define ZRTP_KEYAGREEMENT_EC25	0x43
#define ZRTP_KEYAGREEMENT_X448	0x44
#define ZRTP_KEYAGREEMENT_DH3k	0x45
#define ZRTP_KEYAGREEMENT_EC38	0x46
#define ZRTP_KEYAGREEMENT_EC52	0x47

#define ZRTP_KEYAGREEMENT_Prsh	0x4e
#define ZRTP_KEYAGREEMENT_Mult	0x4f
88 89 90 91 92

#define ZRTP_SAS_B32			0x51
#define ZRTP_SAS_B256			0x52


johan's avatar
johan committed
93 94 95 96 97 98
/**
 * Define to give client indication on which srtp secrets are valid when given
 */
#define ZRTP_SRTP_SECRETS_FOR_SENDER	0x01
#define ZRTP_SRTP_SECRETS_FOR_RECEIVER	0x02

johan's avatar
johan committed
99
/**
100 101
 * 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 */
johan's avatar
johan committed
102 103 104 105 106 107 108 109 110
typedef struct bzrtpSrtpSecrets_struct  {
	uint8_t *selfSrtpKey; /**< The key used by local part to encrypt */
	uint8_t selfSrtpKeyLength; /**< The length in byte of the key */
	uint8_t *selfSrtpSalt; /**< The salt used by local part to encrypt */
	uint8_t selfSrtpSaltLength; /**< The length in byte of the salt */
	uint8_t *peerSrtpKey; /**< The key used by local part to decrypt */
	uint8_t peerSrtpKeyLength; /**< The length in byte of the key */
	uint8_t *peerSrtpSalt; /**< The salt used by local part to decrypt */
	uint8_t peerSrtpSaltLength; /**< The length in byte of the salt */
111
	uint8_t cipherAlgo; /**< The cipher block algorithm selected durign ZRTP negotiation and used by srtp */
johan's avatar
johan committed
112 113
	uint8_t cipherKeyLength; /**< The key length in bytes for the cipher block algorithm used by srtp */
	uint8_t authTagAlgo; /**< srtp authentication tag algorithm agreed on after Hello packet exchange */
114
	char *sas; /**< a null terminated char containing the Short Authentication String */
115
	uint8_t sasLength; /**< The length of sas, including the termination character */
116 117 118
	uint8_t hashAlgo; /**< The hash algo selected during ZRTP negotiation */
	uint8_t keyAgreementAlgo; /**< The key agreement algo selected during ZRTP negotiation */
	uint8_t sasAlgo; /**< The SAS rendering algo selected during ZRTP negotiation */
johan's avatar
johan committed
119
	uint8_t cacheMismatch; /**< Flag set to 1 in case of ZRTP cache mismatch, may occurs only on first channel(the one computing SAS) */
120
	uint8_t auxSecretMismatch; /**< Flag set to 1 in case of auxiliary secret mismatch, may occurs only on first channel(the one computing SAS), in case of mismatch it is just ignored and we can still validate the SAS */
johan's avatar
johan committed
121 122
} bzrtpSrtpSecrets_t;

johan's avatar
johan committed
123 124 125 126 127 128 129 130

/* define message levels */
#define BZRTP_MESSAGE_ERROR	0x00
#define BZRTP_MESSAGE_WARNING	0x01
#define BZRTP_MESSAGE_LOG	0x02
#define BZRTP_MESSAGE_DEBUG	0x03

/* define message codes */
johan's avatar
johan committed
131 132
#define BZRTP_MESSAGE_CACHEMISMATCH 		0x01
#define BZRTP_MESSAGE_PEERVERSIONOBSOLETE	0x02
133
#define BZRTP_MESSAGE_PEERNOTBZRTP		0x03
johan's avatar
johan committed
134

Simon Morlat's avatar
Simon Morlat committed
135 136 137 138 139 140 141 142
/**
 * Function pointer used by bzrtp to free memory allocated by callbacks.
**/
typedef void (*zrtpFreeBuffer_callback)(void *);
/**
 * @brief All the callback functions provided by the client needed by the ZRTP engine
 */
typedef struct bzrtpCallbacks_struct {
johan's avatar
johan committed
143
	/* messaging status and warnings */
johan's avatar
johan committed
144
	int (* bzrtp_statusMessage)(void *clientData, const uint8_t messageLevel, const uint8_t messageId, const char *messageString); /**< Sending messages to caller: error, warnings, logs, the messageString can be NULL or a NULL terminated string */
johan's avatar
johan committed
145
	int bzrtp_messageLevel; /**< Filter calls to this callback to levels inferiors to this setting (BZRTP_MESSAGE_ERROR, BZRTP_MESSAGE_WARNING, BZRTP_MESSAGE_LOG, BZRTP_MESSAGE_DEBUG )*/
Simon Morlat's avatar
Simon Morlat committed
146 147 148 149 150

	/* sending packets */
	int (* bzrtp_sendData)(void *clientData, const uint8_t *packetString, uint16_t packetLength); /**< Send a ZRTP packet to peer. Shall return 0 on success */

	/* dealing with SRTP session */
151 152
	int (* bzrtp_srtpSecretsAvailable)(void *clientData, const bzrtpSrtpSecrets_t *srtpSecrets, uint8_t part); /**< Send the srtp secrets to the client, for either sender, receiver or both according to the part parameter value. Client may wait for the end of ZRTP process before using it */
	int (* bzrtp_startSrtpSession)(void *clientData, const bzrtpSrtpSecrets_t *srtpSecrets, int32_t verified); /**< ZRTP process ended well, client is given the SAS and informations about the crypto algo used during ZRTP negotiation. He may start his SRTP session if not done when calling srtpSecretsAvailable */
Simon Morlat's avatar
Simon Morlat committed
153 154

	/* ready for exported keys */
johan's avatar
johan committed
155
	int (* bzrtp_contextReadyForExportedKeys)(void *clientData, int zuid, uint8_t role); /**< Tell the client that this is the time to create any exported keys, s0 is erased just after the call to this callback. Callback is given the peerZID and zuid to adress the correct node in cache and current role which is needed to set a pair of keys for IM encryption */
Simon Morlat's avatar
Simon Morlat committed
156 157
} bzrtpCallbacks_t;

johan's avatar
johan committed
158 159
#define ZRTP_MAGIC_COOKIE 0x5a525450
#define ZRTP_VERSION	"1.10"
160

johan's avatar
johan committed
161
/* error code definition */
johan's avatar
johan committed
162 163 164 165 166
#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
167
#define BZRTP_ERROR_UNABLETOSTARTCHANNEL			0x0020
168 169
#define BZRTP_ERROR_OUTPUTBUFFER_LENGTH				0x0040
#define BZRTP_ERROR_HELLOHASH_MISMATCH				0x0080
170
#define BZRTP_ERROR_CHANNELALREADYSTARTED			0x0100
johan's avatar
johan committed
171
#define BZRTP_ERROR_CACHEDISABLED				0x0200
172
#define BZRTP_ERROR_CACHEMIGRATIONFAILED			0x0400
173

174 175 176 177 178
/* channel status definition */
#define BZRTP_CHANNEL_NOTFOUND						0x1000
#define BZRTP_CHANNEL_INITIALISED					0x1001
#define BZRTP_CHANNEL_ONGOING						0x1002
#define BZRTP_CHANNEL_SECURE						0x1004
johan's avatar
johan committed
179 180 181 182 183
#define BZRTP_CHANNEL_ERROR						0x1008

/* role mapping */
#define BZRTP_ROLE_INITIATOR	0
#define	BZRTP_ROLE_RESPONDER	1
184

johan's avatar
johan committed
185 186 187 188
/* cache related value */
#define BZRTP_CACHE_SETUP		0x2000
#define BZRTP_CACHE_UPDATE		0x2001
#define BZRTP_CACHE_DATA_NOTFOUND	0x2002
johan's avatar
johan committed
189 190 191 192 193 194
/**
 * @brief bzrtpContext_t The ZRTP engine context
 * Store current state, timers, HMAC and encryption keys
*/
typedef struct bzrtpContext_struct bzrtpContext_t;

195 196 197 198 199

#ifdef __cplusplus
extern "C" {
#endif

johan's avatar
johan committed
200
/**
johan's avatar
johan committed
201 202
 * Create context structure and initialise it
 *
johan's avatar
johan committed
203 204 205
 * @return The ZRTP engine context data
 *                                                                        
*/
206
BZRTP_EXPORT bzrtpContext_t *bzrtp_createBzrtpContext(void);
johan's avatar
johan committed
207 208

/**
johan's avatar
johan committed
209
 * @brief Perform initialisation which can't be done without ZIDcache acces
210
 * - get ZID and create the first channel context
johan's avatar
johan committed
211
 *
212 213
 *   @param[in]		context		The context to initialise
 *   @param[in]		selfSSRC	The SSRC given to the first channel context created within the zrtpContext
johan's avatar
johan committed
214 215
 *
 *   @return 0 on success
johan's avatar
johan committed
216
 */
johan's avatar
johan committed
217
BZRTP_EXPORT int bzrtp_initBzrtpContext(bzrtpContext_t *context, uint32_t selfSSRC);
johan's avatar
johan committed
218 219

/**
johan's avatar
johan committed
220 221 222
 * Free memory of context structure to a channel, if all channels are freed, free the global zrtp context
 * @param[in]	context		Context hosting the channel to be destroyed.(note: the context zrtp context itself is destroyed with the last channel)
 * @param[in]	selfSSRC	The SSRC identifying the channel to be destroyed
johan's avatar
johan committed
223
 *                                                                           
224
 * @return the number of channel still active in this ZRTP context
johan's avatar
johan committed
225
*/
226
BZRTP_EXPORT int bzrtp_destroyBzrtpContext(bzrtpContext_t *context, uint32_t selfSSRC);
johan's avatar
johan committed
227 228 229

/**
 * @brief Allocate a function pointer to the callback function identified by his id 
230
 * @param[in/out]	context				The zrtp context to set the callback function
Simon Morlat's avatar
Simon Morlat committed
231
 * @param[in] 		cbs 				A structure containing all the callbacks to supply.
johan's avatar
johan committed
232 233 234 235
 *
 * @return 0 on success
 *                                                                           
*/
Simon Morlat's avatar
Simon Morlat committed
236
BZRTP_EXPORT int bzrtp_setCallbacks(bzrtpContext_t *context, const bzrtpCallbacks_t *cbs);
johan's avatar
johan committed
237

johan's avatar
johan committed
238 239
/**
 * @brief Set the pointer allowing cache access
240
 *
johan's avatar
johan committed
241 242 243
 * @param[in]	zidCachePointer		Used by internal function to access cache: turn into a sqlite3 pointer if cache is enabled
 * @param[in]   selfURI			Local URI used for this communication, needed to perform cache operation, NULL terminated string, duplicated by this function
 * @param[in]   peerURI			Peer URI used for this communication, needed to perform cache operation, NULL terminated string, duplicated by this function
244
 *
johan's avatar
johan committed
245
 * @return 0 or BZRTP_CACHE_SETUP(if cache is populated by this call) on success, error code otherwise
246
*/
johan's avatar
johan committed
247 248
BZRTP_EXPORT int bzrtp_setZIDCache(bzrtpContext_t *context, void *zidCache, const char *selfURI, const char *peerURI);

249 250 251 252 253 254 255 256 257 258
/**
 * @brief 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)
 * @param[in/out]	zrtpContext		The ZRTP context we're dealing with
 * @param[in]		selfSSRC		The SSRC identifying the channel to be linked to the client Data
 * @param[in]		clientData		The clientData pointer, casted to a (void *)
 *
 * @return 0 on success
 *                                                                           
*/
259
BZRTP_EXPORT int bzrtp_setClientData(bzrtpContext_t *zrtpContext, uint32_t selfSSRC, void *clientData);
260

johan's avatar
johan committed
261
/**
262
 * @brief Add a channel to an existing context
johan's avatar
johan committed
263
 *
264
 * @param[in/out]	zrtpContext	The zrtp context who will get the additionnal channel
265
 * @param[in]		selfSSRC	The SSRC given to the channel context
johan's avatar
johan committed
266 267 268
 *
 * @return 0 on succes, error code otherwise
 */
269
BZRTP_EXPORT int bzrtp_addChannel(bzrtpContext_t *zrtpContext, uint32_t selfSSRC);
johan's avatar
johan committed
270

271 272 273

/**
 * @brief Start the state machine of the specified channel
274
 * To be able to start an addional channel, we must be in secure state
275 276 277 278 279 280
 *
 * @param[in/out]	zrtpContext			The ZRTP context hosting the channel to be started
 * @param[in]		selfSSRC			The SSRC identifying the channel to be started(will start sending Hello packets and listening for some)
 *
 * @return			0 on succes, error code otherwise
 */
281
BZRTP_EXPORT int bzrtp_startChannelEngine(bzrtpContext_t *zrtpContext, uint32_t selfSSRC);
282 283 284 285 286 287 288 289 290 291

/**
 * @brief Send the current time to a specified channel, it will check if it has to trig some timer
 *
 * @param[in/out]	zrtpContext			The ZRTP context hosting the channel
 * @param[in]		selfSSRC			The SSRC identifying the channel
 * @param[in]		timeReference		The current time in ms
 *
 * @return			0 on succes, error code otherwise
 */
292
BZRTP_EXPORT int bzrtp_iterate(bzrtpContext_t *zrtpContext, uint32_t selfSSRC, uint64_t timeReference);
293 294 295 296 297 298 299 300 301 302 303

/**
 * @brief Process a received message
 *
 * @param[in/out]	zrtpContext				The ZRTP context we're dealing with
 * @param[in]		selfSSRC				The SSRC identifying the channel receiving the message
 * @param[in]		zrtpPacketString		The packet received
 * @param[in]		zrtpPacketStringLength	Length of the packet in bytes
 *
 * @return 	0 on success, errorcode otherwise
 */
304
BZRTP_EXPORT int bzrtp_processMessage(bzrtpContext_t *zrtpContext, uint32_t selfSSRC, uint8_t *zrtpPacketString, uint16_t zrtpPacketStringLength);
305

johan's avatar
johan committed
306 307 308 309 310
/**
 * @brief Called by user when the SAS has been verified
 *
 * @param[in/out]	zrtpContext				The ZRTP context we're dealing with
 */
311
BZRTP_EXPORT void bzrtp_SASVerified(bzrtpContext_t *zrtpContext); 
johan's avatar
johan committed
312 313 314 315 316 317

/**
 * @brief Called by user when the SAS has been set to unverified
 *
 * @param[in/out]	zrtpContext				The ZRTP context we're dealing with
 */
318
BZRTP_EXPORT void bzrtp_resetSASVerified(bzrtpContext_t *zrtpContext);
319

320 321 322 323 324 325 326 327 328 329 330
/**
 * @brief 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.
 *
 * @param[in/out]	zrtpContext				The ZRTP context we're dealing with
 * @param[in]		selfSSRC				The SSRC identifying the channel to reset
 *
 * return 0 on success, error code otherwise
 */
331
BZRTP_EXPORT int bzrtp_resetRetransmissionTimer(bzrtpContext_t *zrtpContext, uint32_t selfSSRC);
332

333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353
/**
 * @brief Get the supported crypto types
 *
 * @param[int]		zrtpContext				The ZRTP context we're dealing with
 * @param[in]		algoType				mapped to defines, must be in [ZRTP_HASH_TYPE, ZRTP_CIPHERBLOCK_TYPE, ZRTP_AUTHTAG_TYPE, ZRTP_KEYAGREEMENT_TYPE or ZRTP_SAS_TYPE]
 * @param[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
 *
 * @return number of supported types, 0 on error
 */
BZRTP_EXPORT uint8_t bzrtp_getSupportedCryptoTypes(bzrtpContext_t *zrtpContext, uint8_t algoType, uint8_t supportedTypes[7]);

/**
 * @brief set the supported crypto types
 *
 * @param[int/out]	zrtpContext				The ZRTP context we're dealing with
 * @param[in]		algoType				mapped to defines, must be in [ZRTP_HASH_TYPE, ZRTP_CIPHERBLOCK_TYPE, ZRTP_AUTHTAG_TYPE, ZRTP_KEYAGREEMENT_TYPE or ZRTP_SAS_TYPE]
 * @param[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
 * @param[in]		supportedTypesCount		number of supported crypto types
 */
BZRTP_EXPORT void bzrtp_setSupportedCryptoTypes(bzrtpContext_t *zrtpContext, uint8_t algoType, uint8_t supportedTypes[7], uint8_t supportedTypesCount);

354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379
/**
 * @brief Set the peer hello hash given by signaling to a ZRTP channel
 *
 * @param[in/out]	zrtpContext						The ZRTP context we're dealing with
 * @param[in]		selfSSRC						The SSRC identifying the channel
 * @param[in]		peerHelloHashHexString			A NULL terminated string containing the hexadecimal form of the hash received in signaling,
 * 													may contain ZRTP version as header.
 * @param[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)
 *
 * @return 	0 on success, errorcode otherwise
 */
BZRTP_EXPORT int bzrtp_setPeerHelloHash(bzrtpContext_t *zrtpContext, uint32_t selfSSRC, uint8_t *peerHelloHashHexString, size_t peerHelloHashHexStringLength);

/**
 * @brief Get the self hello hash from ZRTP channel
 *
 * @param[in/out]	zrtpContext			The ZRTP context we're dealing with
 * @param[in]		selfSSRC			The SSRC identifying the channel
 * @param[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.
 * @param[in]		outputLength		Length of output buffer, shall be at least 70 : 5 chars for version, 64 for the hash itself, SHA256), NULL termination
 *
 * @return 	0 on success, errorcode otherwise
 */
BZRTP_EXPORT int bzrtp_getSelfHelloHash(bzrtpContext_t *zrtpContext, uint32_t selfSSRC, uint8_t *output, size_t outputLength);
380

381 382 383 384 385 386 387 388 389 390 391 392
/**
 * @brief Get the channel status
 *
 * @param[in]		zrtpContext			The ZRTP context we're dealing with
 * @param[in]		selfSSRC			The SSRC identifying the channel
 *
 * @return	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
 */
393
BZRTP_EXPORT int bzrtp_getChannelStatus(bzrtpContext_t *zrtpContext, uint32_t selfSSRC);
394

395 396 397 398 399 400 401 402 403 404 405 406 407 408

/**
 * @brief 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
 *
 * @param[in]		zrtpContext	The ZRTP context we're dealing with
 * @param[in]		auxSecret	A buffer holding the auxiliary shared secret to use (see RFC 6189 section 4.3)
 * @param[in]		auxSecretLength	lenght of the previous buffer
 *
 * @return 0 on success, error code otherwise
 */
BZRTP_EXPORT int bzrtp_setAuxiliarySharedSecret(bzrtpContext_t *zrtpContext, const uint8_t *auxSecret, size_t auxSecretLength);

johan's avatar
johan committed
409 410 411 412 413 414 415
/*** Cache related functions ***/
/**
 * @brief Check the given sqlite3 DB and create requested tables if needed
 * 	Also manage DB schema upgrade
 * @param[in/out]	db	Pointer to the sqlite3 db open connection
 * 				Use a void * to keep this API when building cacheless
 *
johan's avatar
johan committed
416
 * @return 0 on success, BZRTP_CACHE_SETUP if cache was empty, BZRTP_CACHE_UPDATE if db structure was updated, error code otherwise
johan's avatar
johan committed
417 418
 */
BZRTP_EXPORT int bzrtp_initCache(void *db);
419

johan's avatar
johan committed
420 421 422 423 424 425 426 427 428 429 430 431 432 433
/**
 * @brief : 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)
 *
 * @param[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
 * @param[in]		selfURI		the sip uri of local user, NULL terminated string
 * @param[out]		selfZID		the ZID, retrieved from cache or randomly generated
 * @param[in]		RNGContext	A RNG context used to generate ZID if needed
 *
 * @return		0 on success, or BZRTP_CACHE_DATA_NOTFOUND if no ZID matching the URI was found and no RNGContext is given to generate one
 */
BZRTP_EXPORT int bzrtp_getSelfZID(void *db, const char *selfURI, uint8_t selfZID[12], bctbx_rng_context_t *RNGContext);
434

johan's avatar
johan committed
435 436 437 438 439 440 441 442 443 444 445 446 447 448
/**
 * @brief get the cache internal id used to bind local uri(hence local ZID associated to it)<->peer uri/peer ZID.
 *	Providing a valid local URI(already present in cache), a peer ZID and peer URI will return the zuid creating it if needed
 *	Any pair ZID/sipURI shall identify an account on a device.
 *
 * @param[in/out]	db		the opened sqlite database pointer
 * @param[in]		selfURI		local URI, must be already associated to a ZID in the DB(association is performed by any call of getSelfZID on this URI)
 * @param[in]		peerURI		peer URI
 * @param[in]		peerZID		peer ZID
 * @param[out]		zuid		the internal db reference to the data row matching this particular pair of correspondant
 *
 * @return 0 on success, error code otherwise
 */
BZRTP_EXPORT int bzrtp_cache_getZuid(void *dbPointer, const char *selfURI, const char *peerURI, const uint8_t peerZID[12], int *zuid);
449 450

/**
johan's avatar
johan committed
451 452 453 454
 * @brief 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
455
 *
johan's avatar
johan committed
456 457 458 459 460 461 462 463 464 465
 * @param[in/out]	dbPointer	Pointer to an already opened sqlite db
 * @param[in]		zuid		The DB internal id to adress the correct row(binding between local uri and peer ZID+URI)
 * @param[in]		tableName	The name of the table to write in the db, must already exists. Null terminated string
 * @param[in]		columns		An array of null terminated strings containing the name of the columns to update
 * @param[in]		values		An array of buffers containing the values to insert/update matching the order of columns array
 * @param[in]		lengths		An array of integer containing the lengths of values array buffer matching the order of columns array
 * @param[in]		columnsCount	length common to columns,values and lengths arrays
 *
 * @return 0 on succes, error code otherwise
 */
466
BZRTP_EXPORT int bzrtp_cache_write(void *dbPointer, int zuid, const char *tableName, const char **columns, uint8_t **values, size_t *lengths, uint8_t columnsCount);
johan's avatar
johan committed
467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483

/**
 * @brief 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
 *
 * @param[in/out]	dbPointer	Pointer to an already opened sqlite db
 * @param[in]		zuid		The DB internal id to adress the correct row(binding between local uri and peer ZID+URI)
 * @param[in]		tableName	The name of the table to read in the db. Null terminated string
 * @param[in]		columns		An array of null terminated strings containing the name of the columns to read, the array's length  is columnsCount
 * @param[out]		values		An array of uint8_t pointers, each one will be allocated to the read value and they must be freed by caller
 * @param[out]		lengths		An array of integer containing the lengths of values array buffer read
 * @param[in]		columnsCount	length common to columns,values and lengths arrays
 *
 * @return 0 on succes, error code otherwise
 */
484
BZRTP_EXPORT int bzrtp_cache_read(void *dbPointer, int zuid, const char *tableName, const char **columns, uint8_t **values, size_t *lengths, uint8_t columnsCount);
johan's avatar
johan committed
485

486 487 488 489 490 491 492 493 494 495 496 497
/**
 * @brief 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
 * @param[in]		cacheXml	a pointer to an xmlDocPtr structure containing the old cache to be migrated
 * @param[in/out]	cacheSqlite	a pointer to an sqlite3 structure containing a cache initialised using bzrtp_cache_init function
 * @param[in]		selfURI		default sip URI for this end point, NULL terminated char
 *
 * @return	0 on success, BZRTP_ERROR_CACHEDISABLED when bzrtp was not compiled with cache enabled, BZRTP_ERROR_CACHEMIGRATIONFAILED on error during migration
 */
BZRTP_EXPORT int bzrtp_cache_migration(void *cacheXmlPtr, void *cacheSqlite, const char *selfURI);

johan's avatar
johan committed
498 499 500 501 502 503 504 505 506 507 508 509
/*
 * @brief  Allow client to compute an exported according to RFC section 4.5.2
 *		Check the context is ready(we already have a master exported key and KDF context)
 * 		and run KDF(master exported key, "Label", KDF_Context, negotiated hash Length)
 *
 * @param[in]		zrtpContext		The ZRTP context we're dealing with
 * @param[in]		label			Label used in the KDF
 * @param[in]		labelLength		Length of previous buffer
 * @param[out]		derivedKey		Buffer to store the derived key
 * @param[in/out]	derivedKeyLength	Length of previous buffer(updated to fit actual length of data produced if too long)
 *
 * @return 0 on succes, error code otherwise
510
 */
Ghislain MARY's avatar
Ghislain MARY committed
511
BZRTP_EXPORT int bzrtp_exportKey(bzrtpContext_t *zrtpContext, char *label, size_t labelLength, uint8_t *derivedKey, size_t *derivedKeyLength);
johan's avatar
johan committed
512

513 514 515 516
#ifdef __cplusplus
}
#endif

johan's avatar
johan committed
517
#endif /* ifndef BZRTP_H */