blob: 0ad5b955f98e6155e199a509ef9b60b1bfe8e804 [file] [log] [blame]
Alexandre Lision51140e12013-12-02 10:54:09 -05001/*
2 This file defines the GNU ZRTP C-to-C++ wrapper.
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -05003 Copyright (C) 2013 Werner Dittmann
Alexandre Lision51140e12013-12-02 10:54:09 -05004
5 This program is free software: you can redistribute it and/or modify
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -05006 it under the terms of the GNU Lesser General Public License as published by
Alexandre Lision51140e12013-12-02 10:54:09 -05007 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
17
18*/
19
20#ifndef ZRTPCWRAPPER_H
21#define ZRTPCWRAPPER_H
22
23/**
24 *
25 * @file ZrtpCWrapper.h
26 * @brief The GNU ZRTP C-to-C++ wrapper.
27 *
28 * To avoid any include of C++ header files some structure, defines, and
29 * enumerations are repeated in this file. Refer to the inline comments if
30 * you modify the file.
31 *
32 * @ingroup GNU_ZRTP
33 * @{
34 *
35 * @see ZRtp
36 */
37
38#include <stdint.h>
39
40/**
41 * Defines to specify the role a ZRTP peer has.
42 *
43 * According to the ZRTP specification the role determines which keys to
44 * use to encrypt or decrypt SRTP data.
45 *
46 * <ul>
47 * <li> The Initiator encrypts SRTP data using the <em>keyInitiator</em> and the
48 * <em>saltInitiator</em> data, the Responder uses these data to decrypt.
49 * </li>
50 * <li> The Responder encrypts SRTP data using the <em>keyResponder</em> and the
51 * <em>saltResponder</em> data, the Initiator uses these data to decrypt.
52 * </li>
53 * </ul>
54 */
55/*
56 * Keep the following defines in sync with Role enumeration in ZrtpCallback.h
57 */
58#define Responder 1 /*!< This client is in ZRTP Responder mode */
59#define Initiator 2 /*!< This client is in ZRTP Initiator mode */
60
61#define CRC_SIZE 4 /*!< Size of CRC code of a ZRTP packet */
62#define ZRTP_MAGIC 0x5a525450 /*!< The magic code that identifies a ZRTP packet */
63#define MAX_ZRTP_SIZE 3072 /*!< The biggest ZRTP packet ever possible */
64
65/*
66 * IMPORTANT: keep the following enums in synch with ZrtpCodes. We copy them here
67 * to avoid any C++ header includes and defines. The protocol states are located
68 * ZrtpStateClass.h .
69 */
70/**
71 * This enum defines the information message severity.
72 *
73 * The ZRTP implementation issues information messages to inform the user
74 * about ongoing processing, unusual behavior, or alerts in case of severe
75 * problems. Each main severity code a number of sub-codes exist that
76 * specify the exact nature of the problem.
77 *
78 * An application gets message severity codes and the associated sub-codes
79 * via the ZrtpUserCallback#showMessage method.
80 *
81 * The severity levels and their meaning are:
82 *
83 * <dl>
84 * <dt>Info</dt> <dd>keeps the user informed about ongoing processing and
85 * security setup. The enumeration InfoCodes defines the subcodes.
86 * </dd>
87 * <dt>Warning</dt> <dd>is an information about some security issues, e.g. if
88 * an AES 256 encryption is request but only DH 3072 as public key scheme
89 * is supported. ZRTP will establish a secure session (SRTP). The
90 * enumeration WarningCodes defines the sub-codes.
91 * </dd>
92 * <dt>Severe</dt> <dd>is used if an error occured during ZRTP protocol usage.
93 * In case of <em>Severe</em> ZRTP will <b>not</b> establish a secure session.
94 * The enumeration SevereCodes defines the sub-codes.
95 * </dd>
96 * <dt>Zrtp</dt> <dd>shows a ZRTP security problem. Refer to the enumeration
97 * ZrtpErrorCodes for sub-codes. GNU ZRTP of course will <b>not</b>
98 * establish a secure session.
99 * </dd>
100 * </dl>
101 *
102 */
103enum zrtp_MessageSeverity {
104 zrtp_Info = 1, /*!< Just an info message */
105 zrtp_Warning, /*!< A Warning message - security can be established */
106 zrtp_Severe, /*!< Severe error, security will not be established */
107 zrtp_ZrtpError /*!< ZRTP error, security will not be established */
108};
109
110/**
111 * Sub-codes for Info
112 */
113enum zrtp_InfoCodes {
114 zrtp_InfoHelloReceived = 1, /*!< Hello received, preparing a Commit */
115 zrtp_InfoCommitDHGenerated, /*!< Commit: Generated a public DH key */
116 zrtp_InfoRespCommitReceived, /*!< Responder: Commit received, preparing DHPart1 */
117 zrtp_InfoDH1DHGenerated, /*!< DH1Part: Generated a public DH key */
118 zrtp_InfoInitDH1Received, /*!< Initiator: DHPart1 received, preparing DHPart2 */
119 zrtp_InfoRespDH2Received, /*!< Responder: DHPart2 received, preparing Confirm1 */
120 zrtp_InfoInitConf1Received, /*!< Initiator: Confirm1 received, preparing Confirm2 */
121 zrtp_InfoRespConf2Received, /*!< Responder: Confirm2 received, preparing Conf2Ack */
122 zrtp_InfoRSMatchFound, /*!< At least one retained secrets matches - security OK */
123 zrtp_InfoSecureStateOn, /*!< Entered secure state */
124 zrtp_InfoSecureStateOff /*!< No more security for this session */
125};
126
127/**
128 * Sub-codes for Warning
129 */
130enum zrtp_WarningCodes {
131 zrtp_WarningDHAESmismatch = 1, /*!< Commit contains an AES256 cipher but does not offer a Diffie-Helman 4096 */
132 zrtp_WarningGoClearReceived, /*!< Received a GoClear message */
133 zrtp_WarningDHShort, /*!< Hello offers an AES256 cipher but does not offer a Diffie-Helman 4096 */
134 zrtp_WarningNoRSMatch, /*!< No retained shared secrets available - must verify SAS */
135 zrtp_WarningCRCmismatch, /*!< Internal ZRTP packet checksum mismatch - packet dropped */
136 zrtp_WarningSRTPauthError, /*!< Dropping packet because SRTP authentication failed! */
137 zrtp_WarningSRTPreplayError, /*!< Dropping packet because SRTP replay check failed! */
138 zrtp_WarningNoExpectedRSMatch /*!< Valid retained shared secrets availabe but no matches found - must verify SAS */
139};
140
141/**
142 * Sub-codes for Severe
143 */
144enum zrtp_SevereCodes {
145 zrtp_SevereHelloHMACFailed = 1, /*!< Hash HMAC check of Hello failed! */
146 zrtp_SevereCommitHMACFailed, /*!< Hash HMAC check of Commit failed! */
147 zrtp_SevereDH1HMACFailed, /*!< Hash HMAC check of DHPart1 failed! */
148 zrtp_SevereDH2HMACFailed, /*!< Hash HMAC check of DHPart2 failed! */
149 zrtp_SevereCannotSend, /*!< Cannot send data - connection or peer down? */
150 zrtp_SevereProtocolError, /*!< Internal protocol error occured! */
151 zrtp_SevereNoTimer, /*!< Cannot start a timer - internal resources exhausted? */
152 zrtp_SevereTooMuchRetries /*!< Too much retries during ZRTP negotiation - connection or peer down? */
153};
154
155/**
156 * Error codes according to the ZRTP specification chapter 6.9
157 *
158 * GNU ZRTP uses these error codes in two ways: to fill the appropriate
159 * field ing the ZRTP Error packet and as sub-code in
160 * ZrtpUserCallback#showMessage(). GNU ZRTP uses thes error codes also
161 * to report received Error packts, in this case the sub-codes are their
162 * negative values.
163 *
164 * The enumeration member comments are copied from the ZRTP specification.
165 */
166enum zrtp_ZrtpErrorCodes {
167 zrtp_MalformedPacket = 0x10, /*!< Malformed packet (CRC OK, but wrong structure) */
168 zrtp_CriticalSWError = 0x20, /*!< Critical software error */
169 zrtp_UnsuppZRTPVersion = 0x30, /*!< Unsupported ZRTP version */
170 zrtp_HelloCompMismatch = 0x40, /*!< Hello components mismatch */
171 zrtp_UnsuppHashType = 0x51, /*!< Hash type not supported */
172 zrtp_UnsuppCiphertype = 0x52, /*!< Cipher type not supported */
173 zrtp_UnsuppPKExchange = 0x53, /*!< Public key exchange not supported */
174 zrtp_UnsuppSRTPAuthTag = 0x54, /*!< SRTP auth. tag not supported */
175 zrtp_UnsuppSASScheme = 0x55, /*!< SAS scheme not supported */
176 zrtp_NoSharedSecret = 0x56, /*!< No shared secret available, DH mode required */
177 zrtp_DHErrorWrongPV = 0x61, /*!< DH Error: bad pvi or pvr ( == 1, 0, or p-1) */
178 zrtp_DHErrorWrongHVI = 0x62, /*!< DH Error: hvi != hashed data */
179 zrtp_SASuntrustedMiTM = 0x63, /*!< Received relayed SAS from untrusted MiTM */
180 zrtp_ConfirmHMACWrong = 0x70, /*!< Auth. Error: Bad Confirm pkt HMAC */
181 zrtp_NonceReused = 0x80, /*!< Nonce reuse */
182 zrtp_EqualZIDHello = 0x90, /*!< Equal ZIDs in Hello */
183 zrtp_GoCleatNotAllowed = 0x100, /*!< GoClear packet received, but not allowed */
184 zrtp_IgnorePacket = 0x7fffffff /*!< Internal state, not reported */
185};
186
187/**
188 * Information codes for the Enrollment user callbacks.
189 */
190enum zrtp_InfoEnrollment {
191 zrtp_EnrollmentRequest, //!< Aks user to confirm or deny an Enrollemnt request
192 zrtp_EnrollmentCanceled, //!< User did not confirm the PBX enrollement
193 zrtp_EnrollmentFailed, //!< Enrollment process failed, no PBX secret available
194 zrtp_EnrollmentOk //!< Enrollment process for this PBX was ok
195};
196
197/* The ZRTP protocol states */
198enum zrtpStates {
199 Initial, /*!< Initial state after starting the state engine */
200 Detect, /*!< State sending Hello, try to detect answer message */
201 AckDetected, /*!< HelloAck received */
202 AckSent, /*!< HelloAck sent after Hello received */
203 WaitCommit, /*!< Wait for a Commit message */
204 CommitSent, /*!< Commit message sent */
205 WaitDHPart2, /*!< Wait for a DHPart2 message */
206 WaitConfirm1, /*!< Wait for a Confirm1 message */
207 WaitConfirm2, /*!< Wait for a confirm2 message */
208 WaitConfAck, /*!< Wait for Conf2Ack */
209 WaitClearAck, /*!< Wait for clearAck - not used */
210 SecureState, /*!< This is the secure state - SRTP active */
211 WaitErrorAck, /*!< Wait for ErrorAck message */
212 numberOfStates /*!< Gives total number of protocol states */
213};
214
215/*! The algorihms that we support in SRTP and that ZRTP can negotiate. */
216typedef enum {
217 zrtp_Aes = 1, /*!< Use AES as symmetrical cipher algorithm */
218 zrtp_TwoFish, /*!< Use TwoFish as symmetrical cipher algorithm */
219 zrtp_Sha1, /*!< Use Sha1 as authentication algorithm */
220 zrtp_Skein /*!< Use Skein as authentication algorithm */
221} zrtp_SrtpAlgorithms;
222
223/**
224 * This structure contains pointers to the SRTP secrets and the role info.
225 *
226 * About the role and what the meaning of the role is refer to the
227 * of the enum Role. The pointers to the secrets are valid as long as
228 * the ZRtp object is active. To use these data after the ZRtp object's
229 * lifetime you may copy the data into a save place.
230 */
231typedef struct c_srtpSecrets
232{
233 zrtp_SrtpAlgorithms symEncAlgorithm;/*!< symmetrical cipher algorithm */
234 const uint8_t* keyInitiator; /*!< Initiator's key */
235 int32_t initKeyLen; /*!< Initiator's key length */
236 const uint8_t* saltInitiator; /*!< Initiator's salt */
237 int32_t initSaltLen; /*!< Initiator's salt length */
238 const uint8_t* keyResponder; /*!< Responder's key */
239 int32_t respKeyLen; /*!< Responder's key length */
240 const uint8_t* saltResponder; /*!< Responder's salt */
241 int32_t respSaltLen; /*!< Responder's salt length */
242 zrtp_SrtpAlgorithms authAlgorithm; /*!< SRTP authentication algorithm */
243 int32_t srtpAuthTagLen; /*!< SRTP authentication length */
244 char* sas; /*!< The SAS string */
245 int32_t role; /*!< ZRTP role of this client */
246} C_SrtpSecret_t;
247
248/*
249 * Keep the following defines in sync with enum EnableSecurity in ZrtpCallback.h
250 */
251#define ForReceiver 1 /*!< Enable security for SRTP receiver */
252#define ForSender 2 /*!< Enable security for SRTP sender */
253
254#ifdef __cplusplus
255#pragma GCC visibility push(default)
256extern "C"
257{
258#endif
259
260 typedef struct ZRtp ZRtp;
261 typedef struct ZrtpCallbackWrapper ZrtpCallbackWrapper;
262 typedef struct ZrtpConfigure ZrtpConfigure;
263
264
265 typedef struct zrtpContext
266 {
267 ZRtp* zrtpEngine; /*!< Holds the real ZRTP engine */
268 ZrtpCallbackWrapper* zrtpCallback; /*!< Help class Callback wrapper */
269 ZrtpConfigure* configure; /*!< Optional configuration data */
270 void* userData; /*!< User data, set by application */
271 } ZrtpContext;
272
273 /**
274 * This structure defines the callback functions required by GNU ZRTP.
275 *
276 * The RTP stack specific part must implement the callback methods.
277 * The generic part of GNU ZRTP uses these mehtods
278 * to communicate with the specific part, for example to send data
279 * via the RTP/SRTP stack, to set timers and cancel timer and so on.
280 *
281 * The generiy part of GNU ZRTP needs only a few callback methods to
282 * be implemented by the specific part.
283 *
284 * @author Werner Dittmann <Werner.Dittmann@t-online.de>
285 */
286
287 /**
288 * The following methods define the GNU ZRTP callback interface.
289 * For detailed documentation refer to file ZrtpCallback.h, each C
290 * method has "zrtp_" prepended to the C++ name.
291 *
292 * @see ZrtpCallback
293 */
294 typedef struct zrtp_Callbacks
295 {
296 /**
297 * Send a ZRTP packet via RTP.
298 *
299 * ZRTP calls this method to send a ZRTP packet via the RTP session.
300 * The ZRTP packet will have to be created using the provided ZRTP message.
301 *
302 * @param ctx
303 * Pointer to the opaque ZrtpContext structure.
304 * @param data
305 * Points to ZRTP message to send.
306 * @param length
307 * The length in bytes of the data
308 * @return
309 * zero if sending failed, one if packet was sent
310 */
311 int32_t (*zrtp_sendDataZRTP) (ZrtpContext* ctx, const uint8_t* data, int32_t length ) ;
312
313 /**
314 * Activate timer.
315 *
316 * @param ctx
317 * Pointer to the opaque ZrtpContext structure.
318 * @param time
319 * The time in ms for the timer
320 * @return
321 * zero if activation failed, one if timer was activated
322 */
323 int32_t (*zrtp_activateTimer) (ZrtpContext* ctx, int32_t time ) ;
324
325 /**
326 * Cancel the active timer.
327 *
328 * @param ctx
329 * Pointer to the opaque ZrtpContext structure.
330 * @return
331 * zero if cancel action failed, one if timer was canceled
332 */
333 int32_t (*zrtp_cancelTimer)(ZrtpContext* ctx) ;
334
335 /**
336 * Send information messages to the hosting environment.
337 *
338 * The ZRTP implementation uses this method to send information
339 * messages to the host. Along with the message ZRTP provides a
340 * severity indicator that defines: Info, Warning, Error,
341 * Alert. Refer to the <code>MessageSeverity</code> enum above.
342 *
343 * @param ctx
344 * Pointer to the opaque ZrtpContext structure.
345 * @param severity
346 * This defines the message's severity
347 * @param subCode
348 * The subcode identifying the reason.
349 * @see ZrtpCodes#MessageSeverity
350 */
351 void (*zrtp_sendInfo) (ZrtpContext* ctx, int32_t severity, int32_t subCode ) ;
352
353 /**
354 * SRTP crypto data ready for the sender or receiver.
355 *
356 * The ZRTP implementation calls this method right after all SRTP
357 * secrets are computed and ready to be used. The parameter points
358 * to a structure that contains pointers to the SRTP secrets and a
359 * <code>enum Role</code>. The called method (the implementation
360 * of this abstract method) must either copy the pointers to the SRTP
361 * data or the SRTP data itself to a save place. The SrtpSecret_t
362 * structure is destroyed after the callback method returns to the
363 * ZRTP implementation.
364 *
365 * The SRTP data themselves are obtained in the ZRtp object and are
366 * valid as long as the ZRtp object is active. TheZRtp's
367 * destructor clears the secrets. Thus the called method needs to
368 * save the pointers only, ZRtp takes care of the data.
369 *
370 * The implementing class may enable SRTP processing in this
371 * method or delay it to srtpSecertsOn().
372 *
373 * @param ctx
374 * Pointer to the opaque ZrtpContext structure.
375 * @param secrets A pointer to a SrtpSecret_t structure that
376 * contains all necessary data.
377 *
378 * @param part for which part (Sender or Receiver) this data is
379 * valid.
380 *
381 * @return Returns false if something went wrong during
382 * initialization of SRTP context, for example memory shortage.
383 */
384 int32_t (*zrtp_srtpSecretsReady) (ZrtpContext* ctx, C_SrtpSecret_t* secrets, int32_t part ) ;
385
386 /**
387 * Switch off the security for the defined part.
388 *
389 * @param ctx
390 * Pointer to the opaque ZrtpContext structure.
391 * @param part Defines for which part (sender or receiver) to
392 * switch on security
393 */
394 void (*zrtp_srtpSecretsOff) (ZrtpContext* ctx, int32_t part ) ;
395
396 /**
397 * Switch on the security.
398 *
399 * ZRTP calls this method after it has computed the SAS and check
400 * if it is verified or not. In addition ZRTP provides information
401 * about the cipher algorithm and key length for the SRTP session.
402 *
403 * This method must enable SRTP processing if it was not enabled
404 * during sertSecretsReady().
405 *
406 * @param ctx
407 * Pointer to the opaque ZrtpContext structure.
408 * @param c The name of the used cipher algorithm and mode, or
409 * NULL
410 *
411 * @param s The SAS string
412 *
413 * @param verified if <code>verified</code> is true then SAS was
414 * verified by both parties during a previous call.
415 */
416 void (*zrtp_rtpSecretsOn) (ZrtpContext* ctx, char* c, char* s, int32_t verified ) ;
417
418 /**
419 * This method handles GoClear requests.
420 *
421 * According to the ZRTP specification the user must be informed about
422 * a GoClear request because the ZRTP implementation switches off security
423 * if it could authenticate the GoClear packet.
424 *
425 * <b>Note:</b> GoClear is not yet implemented in GNU ZRTP.
426 *
427 * @param ctx
428 * Pointer to the opaque ZrtpContext structure.
429 */
430 void (*zrtp_handleGoClear)(ZrtpContext* ctx) ;
431
432 /**
433 * Handle ZRTP negotiation failed.
434 *
435 * ZRTP calls this method in case ZRTP negotiation failed. The
436 * parameters show the severity as well as the reason.
437 *
438 * @param ctx
439 * Pointer to the opaque ZrtpContext structure.
440 * @param severity
441 * This defines the message's severity
442 * @param subCode
443 * The subcode identifying the reason.
444 * @see ZrtpCodes#MessageSeverity
445 */
446 void (*zrtp_zrtpNegotiationFailed) (ZrtpContext* ctx, int32_t severity, int32_t subCode ) ;
447
448 /**
449 * ZRTP calls this method if the other side does not support ZRTP.
450 *
451 * @param ctx
452 * Pointer to the opaque ZrtpContext structure.
453 * If the other side does not answer the ZRTP <em>Hello</em> packets then
454 * ZRTP calls this method,
455 *
456 */
457 void (*zrtp_zrtpNotSuppOther)(ZrtpContext* ctx) ;
458
459 /**
460 * Enter synchronization mutex.
461 *
462 * GNU ZRTP requires one mutex to synchronize its
463 * processing. Because mutex implementations depend on the
464 * underlying infrastructure, for example operating system or
465 * thread implementation, GNU ZRTP delegates mutex handling to the
466 * specific part of its implementation.
467 *
468 * @param ctx
469 * Pointer to the opaque ZrtpContext structure.
470 */
471 void (*zrtp_synchEnter)(ZrtpContext* ctx) ;
472
473 /**
474 * Leave synchronization mutex.
475 *
476 * @param ctx
477 * Pointer to the opaque ZrtpContext structure.
478 */
479 void (*zrtp_synchLeave)(ZrtpContext* ctx) ;
480
481 /**
482 * Inform about a PBX enrollment request.
483 *
484 * Please refer to chapter 8.3 ff to get more details about PBX
485 * enrollment and SAS relay.
486 *
487 * <b>Note:</b> PBX enrollement is not yet fully supported by GNU
488 * ZRTP.
489 *
490 * @param ctx
491 * Pointer to the opaque ZrtpContext structure.
492 * @param info Give some information to the user about the PBX
493 * requesting an enrollment.
494 */
495 void (*zrtp_zrtpAskEnrollment) (ZrtpContext* ctx, int32_t info) ;
496
497 /**
498 * Inform about PBX enrollment result.
499 *
500 * Informs the use about the acceptance or denial of an PBX enrollment
501 * request
502 *
503 * <b>Note:</b> PBX enrollement is not yet fully supported by GNU
504 * ZRTP.
505 *
506 * @param ctx
507 * Pointer to the opaque ZrtpContext structure.
508 * @param info Give some information to the user about the result
509 * of an enrollment.
510 */
511 void (*zrtp_zrtpInformEnrollment) (ZrtpContext* ctx, int32_t info ) ;
512
513 /**
514 * Request a SAS signature.
515 *
516 * After ZRTP was able to compute the Short Authentication String
517 * (SAS) it calls this method. The client may now use an
518 * approriate method to sign the SAS. The client may use
519 * ZrtpQueue#setSignatureData() to store the signature data and
520 * enable signature transmission to the other peer. Refer to
521 * chapter 8.2 of ZRTP specification.
522 *
523 * <b>Note:</b> SAS signing is not yet fully supported by GNU
524 * ZRTP.
525 *
526 * @param ctx
527 * Pointer to the opaque ZrtpContext structure.
528 * @param sas
529 * Pointer to the 32 byte SAS hash to sign.
530 *
531 */
532 void (*zrtp_signSAS)(ZrtpContext* ctx, uint8_t* sas) ;
533
534 /**
535 * ZRTPQueue calls this method to request a SAS signature check.
536 *
537 * After ZRTP received a SAS signature in one of the Confirm packets it
538 * call this method. The client may use <code>getSignatureLength()</code>
539 * and <code>getSignatureData()</code>of ZrtpQueue to get the signature
540 * data and perform the signature check. Refer to chapter 8.2 of ZRTP
541 * specification.
542 *
543 * If the signature check fails the client may return false to ZRTP. In
544 * this case ZRTP signals an error to the other peer and terminates
545 * the ZRTP handshake.
546 *
547 * <b>Note:</b> SAS signing is not yet fully supported by GNU
548 * ZRTP.
549 *
550 * @param ctx
551 * Pointer to the opaque ZrtpContext structure.
552 * @param sas
553 * Pointer to the 32 byte SAS hash that was signed by the other peer.
554 * @return
555 * true if the signature was ok, false otherwise.
556 *
557 */
558 int32_t (*zrtp_checkSASSignature) (ZrtpContext* ctx, uint8_t* sas ) ;
559 } zrtp_Callbacks;
560
561 /**
562 * Create the GNU ZRTP C wrapper.
563 *
564 * This wrapper implements the C interface to the C++ based GNU ZRTP.
565 * @returns
566 * Pointer to the ZrtpContext
567 */
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -0500568 ZrtpContext* zrtp_CreateWrapper(void);
Alexandre Lision51140e12013-12-02 10:54:09 -0500569
570 /**
571 * Initialize the ZRTP protocol engine.
572 *
573 * This method initialized the GNU ZRTP protocol engine. An application
574 * calls this method to actually create the ZRTP protocol engine and
575 * initialize its configuration data. This method does not start the
576 * protocol engine.
577 *
578 * If an application requires a specific algorithm configuration then it
579 * must set the algorithm configuration data before it initializes the
580 * ZRTP protocol engine.
581 *
582 * @param zrtpContext
583 * Pointer to the opaque ZrtpContext structure.
584 * @param cb
585 * The callback structure that holds the addresses of the callback
586 * methods.
587 * @param id
588 * A C string that holds the ZRTP client id, only the first 16 chars
589 * are used.
590 * @param zidFilename
591 * The name of the ZID file. This file holds some parameters and
592 * other data like additional shared secrets.
593 * @param userData
594 * A pointer to user data. The wrapper just stores this pointer in
595 * the ZrtpContext and the application may use it for its purposes.
596 * @param mitmMode
597 * A trusted Mitm (PBX) must set this to true. The ZRTP engine sets
598 * the M Flag in the Hello packet to announce a trusted MitM.
599 * @returns
600 * Pointer to the ZrtpContext
601 *
602 * @see zrtp_InitializeConfig
603 */
604 void zrtp_initializeZrtpEngine(ZrtpContext* zrtpContext,
605 zrtp_Callbacks *cb,
606 const char* id,
607 const char* zidFilename,
608 void* userData,
609 int32_t mitmMode);
610
611 /**
612 * Destroy the ZRTP wrapper and its underlying objects.
613 */
614 void zrtp_DestroyWrapper (ZrtpContext* zrtpContext);
615
616 /**
617 * Computes the ZRTP checksum over a received ZRTP packet buffer and
618 * compares the result with received checksum.
619 *
620 * @param buffer
621 * Pointer to ZRTP packet buffer
622 * @param length
623 * Length of the packet buffer excluding received CRC data
624 * @param crc
625 * The received CRC data.
626 * @returns
627 * True if CRC matches, false otherwise.
628 */
629 int32_t zrtp_CheckCksum(uint8_t* buffer, uint16_t length, uint32_t crc);
630
631 /**
632 * Computes the ZRTP checksum over a newly created ZRTP packet buffer.
633 *
634 * @param buffer
635 * Pointer to the created ZRTP packet buffer
636 * @param length
637 * Length of the packet buffer
638 * @returns
639 * The computed CRC.
640 */
641 uint32_t zrtp_GenerateCksum(uint8_t* buffer, uint16_t length);
642
643 /**
644 * Prepares the ZRTP checksum for appending to ZRTP packet.
645 * @param crc
646 * The computed CRC data.
647 * @returns
648 * Prepared CRC data in host order
649 */
650 uint32_t zrtp_EndCksum(uint32_t crc);
651
652 /**
653 * Kick off the ZRTP protocol engine.
654 *
655 * This method calls the ZrtpStateClass#evInitial() state of the state
656 * engine. After this call we are able to process ZRTP packets
657 * from our peer and to process them.
658 *
659 * <b>NOTE: application shall never call this method directly but use the
660 * appropriate method provided by the RTP implementation. </b>
661 *
662 * @param zrtpContext
663 * Pointer to the opaque ZrtpContext structure.
664 */
665 void zrtp_startZrtpEngine(ZrtpContext* zrtpContext);
666
667 /**
668 * Stop ZRTP security.
669 *
670 * <b>NOTE: An application shall never call this method directly but use the
671 * appropriate method provided by the RTP implementation. </b>
672 *
673 * @param zrtpContext
674 * Pointer to the opaque ZrtpContext structure.
675 */
676 void zrtp_stopZrtpEngine(ZrtpContext* zrtpContext);
677
678 /**
679 * Process RTP extension header.
680 *
681 * This method expects to get a pointer to the message part of
682 * a ZRTP packet.
683 *
684 * <b>NOTE: An application shall never call this method directly. Only
685 * the module that implements the RTP binding shall use this method</b>
686 *
687 * @param zrtpContext
688 * Pointer to the opaque ZrtpContext structure.
689 * @param extHeader
690 * A pointer to the first byte of the ZRTP message part.
691 * @param peerSSRC
692 * The peer's SSRC.
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -0500693 * @param length of the received data packet - used to do santity checks.
694 *
Alexandre Lision51140e12013-12-02 10:54:09 -0500695 * @return
696 * Code indicating further packet handling, see description above.
697 */
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -0500698 void zrtp_processZrtpMessage(ZrtpContext* zrtpContext, uint8_t *extHeader, uint32_t peerSSRC, size_t length);
Alexandre Lision51140e12013-12-02 10:54:09 -0500699
700 /**
701 * Process a timeout event.
702 *
703 * We got a timeout from the timeout provider. Forward it to the
704 * protocol state engine.
705 *
706 * <b>NOTE: application shall never call this method directly. Only
707 * the module that implements the RTP binding shall use this method</b>
708 *
709 * @param zrtpContext
710 * Pointer to the opaque ZrtpContext structure.
711 */
712 void zrtp_processTimeout(ZrtpContext* zrtpContext);
713
714 /*
715 * Check for and handle GoClear ZRTP packet header.
716 *
717 * This method checks if this is a GoClear packet. If not, just return
718 * false. Otherwise handle it according to the specification.
719 *
720 * @param zrtpContext
721 * Pointer to the opaque ZrtpContext structure.
722 * @param extHeader
723 * A pointer to the first byte of the extension header. Refer to
724 * RFC3550.
725 * @return
726 * False if not a GoClear, true otherwise.
727 *
728 int32_t zrtp_handleGoClear(ZrtpContext* zrtpContext, uint8_t *extHeader);
729 */
730
731 /**
732 * Set the auxilliary secret.
733 *
734 * Use this method to set the auxilliary secret data. Refer to ZRTP
735 * specification, chapter 4.3 ff
736 *
737 * @param zrtpContext
738 * Pointer to the opaque ZrtpContext structure.
739 * @param data
740 * Points to the secret data.
741 * @param length
742 * Length of the auxilliary secrect in bytes
743 */
744 void zrtp_setAuxSecret(ZrtpContext* zrtpContext, uint8_t* data, int32_t length);
745
746 /**
747 * Check current state of the ZRTP state engine
748 *
749 * <b>NOTE: application usually don't call this method. Only
750 * the m-odule that implements the RTP binding shall use this method</b>
751 *
752 * @param zrtpContext
753 * Pointer to the opaque ZrtpContext structure.
754 * @param state
755 * The state to check.
756 * @return
757 * Returns true if ZRTP engine is in the given state, false otherwise.
758 */
759 int32_t zrtp_inState(ZrtpContext* zrtpContext, int32_t state);
760
761 /**
762 * Set SAS as verified.
763 *
764 * Call this method if the user confirmed (verfied) the SAS. ZRTP
765 * remembers this together with the retained secrets data.
766 *
767 * @param zrtpContext
768 * Pointer to the opaque ZrtpContext structure.
769 */
770 void zrtp_SASVerified(ZrtpContext* zrtpContext);
771
772 /**
773 * Reset the SAS verfied flag for the current active user's retained secrets.
774 *
775 * @param zrtpContext
776 * Pointer to the opaque ZrtpContext structure.
777 */
778 void zrtp_resetSASVerified(ZrtpContext* zrtpContext);
779
780 /**
781 * Get the ZRTP Hello Hash data.
782 *
783 * Use this method to get the ZRTP Hello Hash data. The method
784 * returns the data as a string containing the ZRTP protocol version and
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -0500785 * hex-digits.
786
787 * The index defines which Hello packet to use. Each supported ZRTP procol version
788 * uses a different Hello packet and thus computes different hashes.
Alexandre Lision51140e12013-12-02 10:54:09 -0500789 *
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -0500790 * Refer to ZRTP specification, chapter 8.
791 *
792 * @param index
793 * Hello hash of the Hello packet identfied by index. Index must be 0 <= index < zrtp_getNumberSupportedVersions().
Alexandre Lision51140e12013-12-02 10:54:09 -0500794 *
795 * @param zrtpContext
796 * Pointer to the opaque ZrtpContext structure.
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -0500797 *
Alexandre Lision51140e12013-12-02 10:54:09 -0500798 * @return
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -0500799 * a pointer to a C-string that contains the Hello hash formatted according to RFC6189 section 8
800 * without the leading 'a=zrtp-hash:' SDP attribute identifier. The hello hash is available
801 * immediately after @c zrtp_CreateWrapper. The caller must @c free() if it does not use the
Alexandre Lision51140e12013-12-02 10:54:09 -0500802 * hello hash C-string anymore.
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -0500803 *
804 * @see zrtp_getNumberSupportedVersions()
Alexandre Lision51140e12013-12-02 10:54:09 -0500805 */
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -0500806 char* zrtp_getHelloHash(ZrtpContext* zrtpContext, int32_t index);
Alexandre Lision51140e12013-12-02 10:54:09 -0500807
808 /**
809 * Get the peer's ZRTP Hello Hash data.
810 *
811 * Use this method to get the peer's ZRTP Hello Hash data. The method
812 * returns the data as a string containing the ZRTP protocol version and
813 * hex-digits.
814 *
815 * The peer's hello hash is available only after ZRTP received a hello. If
816 * no data is available the function returns an empty string.
817 *
818 * Refer to ZRTP specification, chapter 8.
819 *
820 * @return
821 * a std:string containing the Hello version and the hello hash as hex digits.
822 */
823 char* zrtp_getPeerHelloHash(ZrtpContext* zrtpContext);
824
825 /**
826 * Get Multi-stream parameters.
827 *
828 * Use this method to get the Multi-stream parameters that were computed
829 * during the ZRTP handshake. An application may use these parameters to
830 * enable multi-stream processing for an associated SRTP session.
831 *
832 * The application must not modify the contents of returned char array, it
833 * is opaque data. The application may hand over this string to a new ZRTP
834 * instance to enable multi-stream processing for this new session.
835 *
836 * Refer to chapter 4.4.2 in the ZRTP specification for further details
837 * and restriction how and when to use multi-stream mode.
838 *
839 * @param zrtpContext
840 * Pointer to the opaque ZrtpContext structure.
841 * @param length
842 * Pointer to an integer that receives the length of the char array
843 * @return
844 * a char array that contains the multi-stream parameters.
845 * If ZRTP was not started or ZRTP is not yet in secure state the method
846 * returns NULL and a length of 0.
847 */
848 char* zrtp_getMultiStrParams(ZrtpContext* zrtpContext, int32_t *length);
849
850 /**
851 * Set Multi-stream parameters.
852 *
853 * Use this method to set the parameters required to enable Multi-stream
854 * processing of ZRTP. The multi-stream parameters must be set before the
855 * application starts the ZRTP protocol engine.
856 *
857 * Refer to chapter 4.4.2 in the ZRTP specification for further details
858 * of multi-stream mode.
859 *
860 * @param zrtpContext
861 * Pointer to the opaque ZrtpContext structure.
862 * @param length
863 * The integer that contains the length of the char array
864 * @param parameters
865 * A char array that contains the multi-stream parameters that this
866 * new ZRTP instance shall use. See also
867 * <code>getMultiStrParams()</code>
868 */
869 void zrtp_setMultiStrParams(ZrtpContext* zrtpContext, char* parameters, int32_t length);
870
871 /**
872 * Check if this ZRTP session is a Multi-stream session.
873 *
874 * Use this method to check if this ZRTP instance uses multi-stream.
875 * Refer to chapters 4.2 and 4.4.2 in the ZRTP.
876 *
877 * @param zrtpContext
878 * Pointer to the opaque ZrtpContext structure.
879 * @return
880 * True if multi-stream is used, false otherwise.
881 */
882 int32_t zrtp_isMultiStream(ZrtpContext* zrtpContext);
883
884 /**
885 * Check if the other ZRTP client supports Multi-stream.
886 *
887 * Use this method to check if the other ZRTP client supports
888 * Multi-stream mode.
889 *
890 * @param zrtpContext
891 * Pointer to the opaque ZrtpContext structure.
892 * @return
893 * True if multi-stream is available, false otherwise.
894 */
895 int32_t zrtp_isMultiStreamAvailable(ZrtpContext* zrtpContext);
896
897 /**
898 * Accept a PBX enrollment request.
899 *
900 * If a PBX service asks to enroll the PBX trusted MitM key and the user
901 * accepts this request, for example by pressing an OK button, the client
902 * application shall call this method and set the parameter
903 * <code>accepted</code> to true. If the user does not accept the request
904 * set the parameter to false.
905 *
906 * @param zrtpContext
907 * Pointer to the opaque ZrtpContext structure.
908 * @param accepted
909 * True if the enrollment request is accepted, false otherwise.
910 */
911 void zrtp_acceptEnrollment(ZrtpContext* zrtpContext, int32_t accepted);
912
913 /**
914 * Check the state of the enrollment mode.
915 *
916 * If true then we will set the enrollment flag (E) in the confirm
917 * packets and performs the enrollment actions. A MitM (PBX) enrollment service
918 * started this ZRTP session. Can be set to true only if mitmMode is also true.
919 *
920 * @param zrtpContext
921 * Pointer to the opaque ZrtpContext structure.
922 * @return status of the enrollmentMode flag.
923 */
924 int32_t zrtp_isEnrollmentMode(ZrtpContext* zrtpContext);
925
926 /**
927 * Check the state of the enrollment mode.
928 *
929 * If true then we will set the enrollment flag (E) in the confirm
930 * packets and perform the enrollment actions. A MitM (PBX) enrollment
931 * service must sets this mode to true.
932 *
933 * Can be set to true only if mitmMode is also true.
934 *
935 * @param zrtpContext
936 * Pointer to the opaque ZrtpContext structure.
937 * @param enrollmentMode defines the new state of the enrollmentMode flag
938 */
939 void zrtp_setEnrollmentMode(ZrtpContext* zrtpContext, int32_t enrollmentMode);
940
941 /**
942 * Check if a peer's cache entry has a vaild MitM key.
943 *
944 * If true then the other peer ha a valid MtiM key, i.e. the peer has performed
945 * the enrollment procedure. A PBX ZRTP Back-2-Back application can use this function
946 * to check which of the peers is enrolled.
947 *
948 * @return True if the other peer has a valid Mitm key (is enrolled).
949 */
950 int32_t isPeerEnrolled(ZrtpContext* zrtpContext);
951
952 /**
953 * Send the SAS relay packet.
954 *
955 * The method creates and sends a SAS relay packet according to the ZRTP
956 * specifications. Usually only a MitM capable user agent (PBX) uses this
957 * function.
958 *
959 * @param zrtpContext
960 * Pointer to the opaque ZrtpContext structure.
961 * @param sh the full SAS hash value
962 * @param render the SAS rendering algorithm
963 */
964 int32_t zrtp_sendSASRelayPacket(ZrtpContext* zrtpContext, uint8_t* sh, char* render);
965
966 /**
967 * Get the commited SAS rendering algorithm for this ZRTP session.
968 *
969 * @param zrtpContext
970 * Pointer to the opaque ZrtpContext structure.
971 * @return the commited SAS rendering algorithm
972 */
973 const char* zrtp_getSasType(ZrtpContext* zrtpContext);
974
975 /**
976 * Get the computed SAS hash for this ZRTP session.
977 *
978 * A PBX ZRTP back-to-Back function uses this function to get the SAS
979 * hash of an enrolled client to construct the SAS relay packet for
980 * the other client.
981 *
982 * @param zrtpContext
983 * Pointer to the opaque ZrtpContext structure.
984 * @return a pointer to the byte array that contains the full
985 * SAS hash.
986 */
987 uint8_t* zrtp_getSasHash(ZrtpContext* zrtpContext);
988
989 /**
990 * Set signature data
991 *
992 * This functions stores signature data and transmitts it during ZRTP
993 * processing to the other party as part of the Confirm packets. Refer to
994 * chapters 5.7 and 7.2.
995 *
996 * The signature data must be set before ZRTP the application calls
997 * <code>start()</code>.
998 *
999 * @param zrtpContext
1000 * Pointer to the opaque ZrtpContext structure.
1001 * @param data
1002 * The signature data including the signature type block. The method
1003 * copies this data into the Confirm packet at signature type block.
1004 * @param length
1005 * The length of the signature data in bytes. This length must be
1006 * multiple of 4.
1007 * @return
1008 * True if the method stored the data, false otherwise.
1009 */
1010 int32_t zrtp_setSignatureData(ZrtpContext* zrtpContext, uint8_t* data, int32_t length);
1011
1012 /**
1013 * Get signature data
1014 *
1015 * This functions returns signature data that was receivied during ZRTP
1016 * processing. Refer to chapters 5.7 and 7.2.
1017 *
1018 * The signature data can be retrieved after ZRTP enters secure state.
1019 * <code>start()</code>.
1020 *
1021 * @param zrtpContext
1022 * Pointer to the opaque ZrtpContext structure.
1023 * @return
1024 * Number of bytes copied into the data buffer
1025 */
1026 const uint8_t* zrtp_getSignatureData(ZrtpContext* zrtpContext);
1027
1028 /**
1029 * Get length of signature data
1030 *
1031 * This functions returns the length of signature data that was receivied
1032 * during ZRTP processing. Refer to chapters 5.7 and 7.2.
1033 *
1034 * @param zrtpContext
1035 * Pointer to the opaque ZrtpContext structure.
1036 * @return
1037 * Length in bytes of the received signature data. The method returns
1038 * zero if no signature data avilable.
1039 */
1040 int32_t zrtp_getSignatureLength(ZrtpContext* zrtpContext);
1041
1042 /**
1043 * Emulate a Conf2Ack packet.
1044 *
1045 * This method emulates a Conf2Ack packet. According to ZRTP specification
1046 * the first valid SRTP packet that the Initiator receives must switch
1047 * on secure mode. Refer to chapter 4 in the specificaton
1048 *
1049 * <b>NOTE: application shall never call this method directly. Only
1050 * the module that implements the RTP binding shall use this method</b>
1051 *
1052 * @param zrtpContext
1053 * Pointer to the opaque ZrtpContext structure.
1054 */
1055 void zrtp_conf2AckSecure(ZrtpContext* zrtpContext);
1056
1057 /**
1058 * Get other party's ZID (ZRTP Identifier) data
1059 *
1060 * This functions returns the other party's ZID that was receivied
1061 * during ZRTP processing.
1062 *
1063 * The ZID data can be retrieved after ZRTP receive the first Hello
1064 * packet from the other party. The application may call this method
1065 * for example during SAS processing in showSAS(...) user callback
1066 * method.
1067 *
1068 * @param zrtpContext
1069 * Pointer to the opaque ZrtpContext structure.
1070 * @param data
1071 * Pointer to a data buffer. This buffer must have a size of
1072 * at least 12 bytes (96 bit) (ZRTP Identifier, see chap. 4.9)
1073 * @return
1074 * Number of bytes copied into the data buffer - must be equivalent
1075 * to 12 bytes.
1076 */
1077 int32_t zrtp_getPeerZid(ZrtpContext* zrtpContext, uint8_t* data);
1078
1079
Alexandre Lision7fd5d3d2013-12-04 13:06:40 -05001080 /**
1081 * Get number of supported ZRTP protocol versions.
1082 *
1083 * @param zrtpContext
1084 * Pointer to the opaque ZrtpContext structure.
1085 *
1086 * @return the number of supported ZRTP protocol versions.
1087 */
1088 int32_t zrtp_getNumberSupportedVersions(ZrtpContext* zrtpContext);
1089
1090 /**
1091 * Get negotiated ZRTP protocol versions.
1092 *
1093 * @param zrtpContext
1094 * Pointer to the opaque ZrtpContext structure.
1095 *
1096 * @return the integer representation of the negotiated ZRTP protocol version.
1097 */
1098 int32_t zrtp_getCurrentProtocolVersion(ZrtpContext* zrtpContext);
1099
1100 /**
Alexandre Lision51140e12013-12-02 10:54:09 -05001101 * This enumerations list all configurable algorithm types.
1102 */
1103
1104 /* Keep in synch with enumeration in ZrtpConfigure.h */
1105
1106 typedef enum zrtp_AlgoTypes {
1107 zrtp_HashAlgorithm = 1, zrtp_CipherAlgorithm, zrtp_PubKeyAlgorithm, zrtp_SasType, zrtp_AuthLength
1108 } Zrtp_AlgoTypes;
1109
1110 /**
1111 * Initialize the GNU ZRTP Configure data.
1112 *
1113 * Initializing and setting a ZRTP configuration is optional. GNU ZRTP
1114 * uses a sensible default if an application does not define its own
1115 * ZRTP configuration.
1116 *
1117 * If an application initialize th configure data it must set the
1118 * configuration data.
1119 *
1120 * The ZRTP specification, chapters 5.1.2 through 5.1.6 defines the
1121 * algorithm names and their meaning.
1122 *
1123 * The current ZRTP implementation implements all mandatory algorithms
1124 * plus a set of the optional algorithms. An application shall use
1125 * @c zrtp_getAlgorithmNames to get the names of the available algorithms.
1126 *
1127 * @param zrtpContext
1128 * Pointer to the opaque ZrtpContext structure.
1129 * @returns
1130 * Pointer to the ZrtpConfCtx
1131 *
1132 * @see zrtp_getAlgorithmNames
1133 */
1134 int32_t zrtp_InitializeConfig (ZrtpContext* zrtpContext);
1135
1136 /**
1137 * Get names of all available algorithmes of a given algorithm type.
1138 *
1139 * The algorithm names are as specified in the ZRTP specification, chapters
1140 * 5.1.2 through 5.1.6 .
1141 *
1142 * @param zrtpContext
1143 * Pointer to the opaque ZrtpContext structure.
1144 * @param type
1145 * The algorithm type.
1146 * @returns
1147 * A NULL terminated array of character pointers.
1148 */
1149 char** zrtp_getAlgorithmNames(ZrtpContext* zrtpContext, Zrtp_AlgoTypes type);
1150
1151 /**
1152 * Free storage used to store the algorithm names.
1153 *
1154 * If an application does not longer require the algoritm names it should
1155 * free the space.
1156 *
1157 * @param names
1158 * The NULL terminated array of character pointers.
1159 */
1160 void zrtp_freeAlgorithmNames(char** names);
1161
1162 /**
1163 * Convenience function that sets a pre-defined standard configuration.
1164 *
1165 * The standard configuration consists of the following algorithms:
1166 * <ul>
1167 * <li> Hash: SHA256 </li>
1168 * <li> Symmetric Cipher: AES 128, AES 256 </li>
1169 * <li> Public Key Algorithm: DH2048, DH3027, MultiStream </li>
1170 * <li> SAS type: libase 32 </li>
1171 * <li> SRTP Authentication lengths: 32, 80 </li>
1172 *</ul>
1173 *
1174 * @param zrtpContext
1175 * Pointer to the opaque ZrtpContext structure.
1176 */
1177 void zrtp_setStandardConfig(ZrtpContext* zrtpContext);
1178
1179 /**
1180 * Convenience function that sets the mandatory algorithms only.
1181 *
1182 * Mandatory algorithms are:
1183 * <ul>
1184 * <li> Hash: SHA256 </li>
1185 * <li> Symmetric Cipher: AES 128 </li>
1186 * <li> Public Key Algorithm: DH3027, MultiStream </li>
1187 * <li> SAS type: libase 32 </li>
1188 * <li> SRTP Authentication lengths: 32, 80 </li>
1189 *</ul>
1190 *
1191 * @param zrtpContext
1192 * Pointer to the opaque ZrtpContext structure.
1193 */
1194 void zrtp_setMandatoryOnly(ZrtpContext* zrtpContext);
1195
1196 /**
1197 * Clear all configuration data.
1198 *
1199 * The functions clears all configuration data.
1200 *
1201 * @param zrtpContext
1202 * Pointer to the opaque ZrtpContext structure.
1203 */
1204 void zrtp_confClear(ZrtpContext* zrtpContext);
1205
1206 /**
1207 * Add an algorithm to configuration data.
1208 *
1209 * Adds the specified algorithm to the configuration data.
1210 * If no free configuration data slot is available the
1211 * function does not add the algorithm and returns -1. The
1212 * methods appends the algorithm to the existing algorithms.
1213 *
1214 * @param zrtpContext
1215 * Pointer to the opaque ZrtpContext structure.
1216 * @param algoType
1217 * Specifies which algorithm type to select
1218 * @param algo
1219 * The name of the algorithm to add.
1220 * @return
1221 * Number of free configuration data slots or -1 on error
1222 */
1223 int32_t zrtp_addAlgo(ZrtpContext* zrtpContext, Zrtp_AlgoTypes algoType, const char* algo);
1224
1225 /**
1226 * Add an algorithm to configuration data at given index
1227 *
1228 * Adds the specified algorithm to the configuration data vector
1229 * at a given index. If the index is larger than the actual size
1230 * of the configuration vector the method just appends the algorithm.
1231 *
1232 * @param zrtpContext
1233 * Pointer to the opaque ZrtpContext structure.
1234 * @param algoType
1235 * Specifies which algorithm type to select
1236 * @param algo
1237 * The name of the algorithm to add.
1238 * @param index
1239 * The index where to add the algorihm
1240 * @return
1241 * Number of free configuration data slots or -1 on error
1242 */
1243 int32_t zrtp_addAlgoAt(ZrtpContext* zrtpContext, Zrtp_AlgoTypes algoType, const char* algo, int32_t index);
1244
1245 /**
1246 * Remove a algorithm from configuration data.
1247 *
1248 * Removes the specified algorithm from configuration data. If
1249 * the algorithm was not configured previously the function does
1250 * not modify the configuration data and returns the number of
1251 * free configuration data slots.
1252 *
1253 * If an application removes all algorithms then ZRTP does not
1254 * include any algorithm into the hello message and falls back
1255 * to a predefined mandatory algorithm.
1256 *
1257 * @param zrtpContext
1258 * Pointer to the opaque ZrtpContext structure.
1259 * @param algoType
1260 * Specifies which algorithm type to select
1261 * @param algo
1262 * The name of the algorithm to remove.
1263 * @return
1264 * Number of free configuration slots.
1265 */
1266 int32_t zrtp_removeAlgo(ZrtpContext* zrtpContext, Zrtp_AlgoTypes algoType, const char* algo);
1267
1268 /**
1269 * Returns the number of configured algorithms.
1270 *
1271 * @param zrtpContext
1272 * Pointer to the opaque ZrtpContext structure.
1273 * @param algoType
1274 * Specifies which algorithm type to select
1275 * @return
1276 * The number of configured algorithms (used configuration
1277 * data slots)
1278 */
1279 int32_t zrtp_getNumConfiguredAlgos(ZrtpContext* zrtpContext, Zrtp_AlgoTypes algoType);
1280
1281 /**
1282 * Returns the identifier of the algorithm at index.
1283 *
1284 * @param zrtpContext
1285 * Pointer to the opaque ZrtpContext structure.
1286 * @param algoType
1287 * Specifies which algorithm type to select
1288 * @param index
1289 * The index in the list of the algorihm type
1290 * @return
1291 * A pointer to the algorithm name. If the index
1292 * does not point to a configured slot then the function
1293 * returns NULL.
1294 *
1295 */
1296 const char* zrtp_getAlgoAt(ZrtpContext* zrtpContext, Zrtp_AlgoTypes algoType, int32_t index);
1297
1298 /**
1299 * Checks if the configuration data of the algorihm type already contains
1300 * a specific algorithms.
1301 *
1302 * @param zrtpContext
1303 * Pointer to the opaque ZrtpContext structure.
1304 * @param algoType
1305 * Specifies which algorithm type to select
1306 * @param algo
1307 * The name of the algorithm to check
1308 * @return
1309 * True if the algorithm was found, false otherwise.
1310 *
1311 */
1312 int32_t zrtp_containsAlgo(ZrtpContext* zrtpContext, Zrtp_AlgoTypes algoType, const char* algo);
1313
1314 /**
1315 * Enables or disables trusted MitM processing.
1316 *
1317 * For further details of trusted MitM processing refer to ZRTP
1318 * specification, chapter 7.3
1319 *
1320 * @param zrtpContext
1321 * Pointer to the opaque ZrtpContext structure.
1322 * @param yesNo
1323 * If set to true then trusted MitM processing is enabled.
1324 */
1325 void zrtp_setTrustedMitM(ZrtpContext* zrtpContext, int32_t yesNo);
1326
1327 /**
1328 * Check status of trusted MitM processing.
1329 *
1330 * @param zrtpContext
1331 * Pointer to the opaque ZrtpContext structure.
1332 * @return
1333 * Returns true if trusted MitM processing is enabled.
1334 */
1335 int32_t zrtp_isTrustedMitM(ZrtpContext* zrtpContext);
1336
1337 /**
1338 * Enables or disables SAS signature processing.
1339 *
1340 * For further details of trusted MitM processing refer to ZRTP
1341 * specification, chapter 7.2
1342 *
1343 * @param zrtpContext
1344 * Pointer to the opaque ZrtpContext structure.
1345 * @param yesNo
1346 * If true then certificate processing is enabled.
1347 */
1348 void zrtp_setSasSignature(ZrtpContext* zrtpContext, int32_t yesNo);
1349
1350 /**
1351 * Check status of SAS signature processing.
1352 *
1353 * @param zrtpContext
1354 * Pointer to the opaque ZrtpContext structure.
1355 * @return
1356 * Returns true if certificate processing is enabled.
1357 */
1358 int32_t zrtp_isSasSignature(ZrtpContext* zrtpContext);
1359
1360#ifdef __cplusplus
1361}
1362#pragma GCC visibility pop
1363#endif
1364
1365/**
1366 * @}
1367 */
1368#endif