Bayonne2 / Common C++ 2 Framework
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Data Structures
ZrtpCWrapper.h File Reference

The GNU ZRTP C-to-C++ wrapper. More...

#include <stdint.h>
Include dependency graph for ZrtpCWrapper.h:

Go to the source code of this file.

Data Structures

struct  c_srtpSecrets
 This structure contains pointers to the SRTP secrets and the role info. More...
 
struct  zrtpContext
 
struct  zrtp_Callbacks
 This structure defines the callback functions required by GNU ZRTP. More...
 
#define Responder   1
 Defines to specify the role a ZRTP peer has. More...
 
#define Initiator   2
 
#define CRC_SIZE   4
 
#define ZRTP_MAGIC   0x5a525450
 
#define MAX_ZRTP_SIZE   3072
 
#define ForReceiver   1
 
#define ForSender   2
 
enum  zrtp_MessageSeverity { zrtp_Info = 1, zrtp_Warning, zrtp_Severe, zrtp_ZrtpError }
 This enum defines the information message severity. More...
 
enum  zrtp_InfoCodes {
  zrtp_InfoHelloReceived = 1, zrtp_InfoCommitDHGenerated, zrtp_InfoRespCommitReceived, zrtp_InfoDH1DHGenerated,
  zrtp_InfoInitDH1Received, zrtp_InfoRespDH2Received, zrtp_InfoInitConf1Received, zrtp_InfoRespConf2Received,
  zrtp_InfoRSMatchFound, zrtp_InfoSecureStateOn, zrtp_InfoSecureStateOff
}
 Sub-codes for Info. More...
 
enum  zrtp_WarningCodes {
  zrtp_WarningDHAESmismatch = 1, zrtp_WarningGoClearReceived, zrtp_WarningDHShort, zrtp_WarningNoRSMatch,
  zrtp_WarningCRCmismatch, zrtp_WarningSRTPauthError, zrtp_WarningSRTPreplayError, zrtp_WarningNoExpectedRSMatch
}
 Sub-codes for Warning. More...
 
enum  zrtp_SevereCodes {
  zrtp_SevereHelloHMACFailed = 1, zrtp_SevereCommitHMACFailed, zrtp_SevereDH1HMACFailed, zrtp_SevereDH2HMACFailed,
  zrtp_SevereCannotSend, zrtp_SevereProtocolError, zrtp_SevereNoTimer, zrtp_SevereTooMuchRetries
}
 Sub-codes for Severe. More...
 
enum  zrtp_ZrtpErrorCodes {
  zrtp_MalformedPacket = 0x10, zrtp_CriticalSWError = 0x20, zrtp_UnsuppZRTPVersion = 0x30, zrtp_HelloCompMismatch = 0x40,
  zrtp_UnsuppHashType = 0x51, zrtp_UnsuppCiphertype = 0x52, zrtp_UnsuppPKExchange = 0x53, zrtp_UnsuppSRTPAuthTag = 0x54,
  zrtp_UnsuppSASScheme = 0x55, zrtp_NoSharedSecret = 0x56, zrtp_DHErrorWrongPV = 0x61, zrtp_DHErrorWrongHVI = 0x62,
  zrtp_SASuntrustedMiTM = 0x63, zrtp_ConfirmHMACWrong = 0x70, zrtp_NonceReused = 0x80, zrtp_EqualZIDHello = 0x90,
  zrtp_GoCleatNotAllowed = 0x100, zrtp_IgnorePacket = 0x7fffffff
}
 Error codes according to the ZRTP specification chapter 6.9. More...
 
enum  zrtp_InfoEnrollment { zrtp_EnrollmentRequest, zrtp_EnrollmentCanceled, zrtp_EnrollmentFailed, zrtp_EnrollmentOk }
 Information codes for the Enrollment user callbacks. More...
 
enum  zrtpStates {
  Initial, Detect, AckDetected, AckSent,
  WaitCommit, CommitSent, WaitDHPart2, WaitConfirm1,
  WaitConfirm2, WaitConfAck, WaitClearAck, SecureState,
  WaitErrorAck, numberOfStates
}
 
enum  zrtp_SrtpAlgorithms { zrtp_Aes = 1, zrtp_TwoFish, zrtp_Sha1, zrtp_Skein }
 
enum  zrtp_AlgoTypes {
  zrtp_HashAlgorithm = 1, zrtp_CipherAlgorithm, zrtp_PubKeyAlgorithm, zrtp_SasType,
  zrtp_AuthLength
}
 This enumerations list all configurable algorithm types. More...
 
typedef struct c_srtpSecrets C_SrtpSecret_t
 This structure contains pointers to the SRTP secrets and the role info. More...
 
typedef struct ZRtp ZRtp
 
typedef struct ZrtpCallbackWrapper ZrtpCallbackWrapper
 
typedef struct ZrtpConfigure ZrtpConfigure
 
typedef struct zrtpContext ZrtpContext
 
typedef struct zrtp_Callbacks zrtp_Callbacks
 This structure defines the callback functions required by GNU ZRTP. More...
 
typedef enum zrtp_AlgoTypes Zrtp_AlgoTypes
 This enumerations list all configurable algorithm types. More...
 
ZrtpContextzrtp_CreateWrapper ()
 Create the GNU ZRTP C wrapper. More...
 
void zrtp_initializeZrtpEngine (ZrtpContext *zrtpContext, zrtp_Callbacks *cb, const char *id, const char *zidFilename, void *userData, int32_t mitmMode)
 Initialize the ZRTP protocol engine. More...
 
void zrtp_DestroyWrapper (ZrtpContext *zrtpContext)
 Destroy the ZRTP wrapper and its underlying objects. More...
 
int32_t zrtp_CheckCksum (uint8_t *buffer, uint16_t length, uint32_t crc)
 Computes the ZRTP checksum over a received ZRTP packet buffer and compares the result with received checksum. More...
 
uint32_t zrtp_GenerateCksum (uint8_t *buffer, uint16_t length)
 Computes the ZRTP checksum over a newly created ZRTP packet buffer. More...
 
uint32_t zrtp_EndCksum (uint32_t crc)
 Prepares the ZRTP checksum for appending to ZRTP packet. More...
 
void zrtp_startZrtpEngine (ZrtpContext *zrtpContext)
 Kick off the ZRTP protocol engine. More...
 
void zrtp_stopZrtpEngine (ZrtpContext *zrtpContext)
 Stop ZRTP security. More...
 
void zrtp_processZrtpMessage (ZrtpContext *zrtpContext, uint8_t *extHeader, uint32_t peerSSRC)
 Process RTP extension header. More...
 
void zrtp_processTimeout (ZrtpContext *zrtpContext)
 Process a timeout event. More...
 
void zrtp_setAuxSecret (ZrtpContext *zrtpContext, uint8_t *data, int32_t length)
 Set the auxilliary secret. More...
 
int32_t zrtp_inState (ZrtpContext *zrtpContext, int32_t state)
 Check current state of the ZRTP state engine. More...
 
void zrtp_SASVerified (ZrtpContext *zrtpContext)
 Set SAS as verified. More...
 
void zrtp_resetSASVerified (ZrtpContext *zrtpContext)
 Reset the SAS verfied flag for the current active user's retained secrets. More...
 
char * zrtp_getHelloHash (ZrtpContext *zrtpContext)
 Get the ZRTP Hello Hash data. More...
 
char * zrtp_getPeerHelloHash (ZrtpContext *zrtpContext)
 Get the peer's ZRTP Hello Hash data. More...
 
char * zrtp_getMultiStrParams (ZrtpContext *zrtpContext, int32_t *length)
 Get Multi-stream parameters. More...
 
void zrtp_setMultiStrParams (ZrtpContext *zrtpContext, char *parameters, int32_t length)
 Set Multi-stream parameters. More...
 
int32_t zrtp_isMultiStream (ZrtpContext *zrtpContext)
 Check if this ZRTP session is a Multi-stream session. More...
 
int32_t zrtp_isMultiStreamAvailable (ZrtpContext *zrtpContext)
 Check if the other ZRTP client supports Multi-stream. More...
 
void zrtp_acceptEnrollment (ZrtpContext *zrtpContext, int32_t accepted)
 Accept a PBX enrollment request. More...
 
int32_t zrtp_isEnrollmentMode (ZrtpContext *zrtpContext)
 Check the state of the enrollment mode. More...
 
void zrtp_setEnrollmentMode (ZrtpContext *zrtpContext, int32_t enrollmentMode)
 Check the state of the enrollment mode. More...
 
int32_t isPeerEnrolled (ZrtpContext *zrtpContext)
 Check if a peer's cache entry has a vaild MitM key. More...
 
int32_t zrtp_sendSASRelayPacket (ZrtpContext *zrtpContext, uint8_t *sh, char *render)
 Send the SAS relay packet. More...
 
const char * zrtp_getSasType (ZrtpContext *zrtpContext)
 Get the commited SAS rendering algorithm for this ZRTP session. More...
 
uint8_t * zrtp_getSasHash (ZrtpContext *zrtpContext)
 Get the computed SAS hash for this ZRTP session. More...
 
int32_t zrtp_setSignatureData (ZrtpContext *zrtpContext, uint8_t *data, int32_t length)
 Set signature data. More...
 
const uint8_t * zrtp_getSignatureData (ZrtpContext *zrtpContext)
 Get signature data. More...
 
int32_t zrtp_getSignatureLength (ZrtpContext *zrtpContext)
 Get length of signature data. More...
 
void zrtp_conf2AckSecure (ZrtpContext *zrtpContext)
 Emulate a Conf2Ack packet. More...
 
int32_t zrtp_getPeerZid (ZrtpContext *zrtpContext, uint8_t *data)
 Get other party's ZID (ZRTP Identifier) data. More...
 
int32_t zrtp_InitializeConfig (ZrtpContext *zrtpContext)
 Initialize the GNU ZRTP Configure data. More...
 
char ** zrtp_getAlgorithmNames (ZrtpContext *zrtpContext, Zrtp_AlgoTypes type)
 Get names of all available algorithmes of a given algorithm type. More...
 
void zrtp_freeAlgorithmNames (char **names)
 Free storage used to store the algorithm names. More...
 
void zrtp_setStandardConfig (ZrtpContext *zrtpContext)
 Convenience function that sets a pre-defined standard configuration. More...
 
void zrtp_setMandatoryOnly (ZrtpContext *zrtpContext)
 Convenience function that sets the mandatory algorithms only. More...
 
void zrtp_confClear (ZrtpContext *zrtpContext)
 Clear all configuration data. More...
 
int32_t zrtp_addAlgo (ZrtpContext *zrtpContext, Zrtp_AlgoTypes algoType, const char *algo)
 Add an algorithm to configuration data. More...
 
int32_t zrtp_addAlgoAt (ZrtpContext *zrtpContext, Zrtp_AlgoTypes algoType, const char *algo, int32_t index)
 Add an algorithm to configuration data at given index. More...
 
int32_t zrtp_removeAlgo (ZrtpContext *zrtpContext, Zrtp_AlgoTypes algoType, const char *algo)
 Remove a algorithm from configuration data. More...
 
int32_t zrtp_getNumConfiguredAlgos (ZrtpContext *zrtpContext, Zrtp_AlgoTypes algoType)
 Returns the number of configured algorithms. More...
 
const char * zrtp_getAlgoAt (ZrtpContext *zrtpContext, Zrtp_AlgoTypes algoType, int32_t index)
 Returns the identifier of the algorithm at index. More...
 
int32_t zrtp_containsAlgo (ZrtpContext *zrtpContext, Zrtp_AlgoTypes algoType, const char *algo)
 Checks if the configuration data of the algorihm type already contains a specific algorithms. More...
 
void zrtp_setTrustedMitM (ZrtpContext *zrtpContext, int32_t yesNo)
 Enables or disables trusted MitM processing. More...
 
int32_t zrtp_isTrustedMitM (ZrtpContext *zrtpContext)
 Check status of trusted MitM processing. More...
 
void zrtp_setSasSignature (ZrtpContext *zrtpContext, int32_t yesNo)
 Enables or disables SAS signature processing. More...
 
int32_t zrtp_isSasSignature (ZrtpContext *zrtpContext)
 Check status of SAS signature processing. More...
 

Detailed Description

The GNU ZRTP C-to-C++ wrapper.

To avoid any include of C++ header files some structure, defines, and enumerations are repeated in this file. Refer to the inline comments if you modify the file.

See Also
ZRtp

Definition in file ZrtpCWrapper.h.

Macro Definition Documentation

#define CRC_SIZE   4

Size of CRC code of a ZRTP packet

Definition at line 61 of file ZrtpCWrapper.h.

#define ForReceiver   1

Enable security for SRTP receiver

Definition at line 251 of file ZrtpCWrapper.h.

#define ForSender   2

Enable security for SRTP sender

Definition at line 252 of file ZrtpCWrapper.h.

#define Initiator   2

This client is in ZRTP Initiator mode

Definition at line 59 of file ZrtpCWrapper.h.

#define MAX_ZRTP_SIZE   3072

The biggest ZRTP packet ever possible

Definition at line 63 of file ZrtpCWrapper.h.

#define Responder   1

Defines to specify the role a ZRTP peer has.

According to the ZRTP specification the role determines which keys to use to encrypt or decrypt SRTP data.

  • The Initiator encrypts SRTP data using the keyInitiator and the saltInitiator data, the Responder uses these data to decrypt.
  • The Responder encrypts SRTP data using the keyResponder and the saltResponder data, the Initiator uses these data to decrypt.

This client is in ZRTP Responder mode

Definition at line 58 of file ZrtpCWrapper.h.

#define ZRTP_MAGIC   0x5a525450

The magic code that identifies a ZRTP packet

Definition at line 62 of file ZrtpCWrapper.h.

Typedef Documentation

typedef struct c_srtpSecrets C_SrtpSecret_t

This structure contains pointers to the SRTP secrets and the role info.

About the role and what the meaning of the role is refer to the of the enum Role. The pointers to the secrets are valid as long as the ZRtp object is active. To use these data after the ZRtp object's lifetime you may copy the data into a save place.

typedef struct ZRtp ZRtp

Definition at line 260 of file ZrtpCWrapper.h.

This enumerations list all configurable algorithm types.

This structure defines the callback functions required by GNU ZRTP.

The RTP stack specific part must implement the callback methods. The generic part of GNU ZRTP uses these mehtods to communicate with the specific part, for example to send data via the RTP/SRTP stack, to set timers and cancel timer and so on.

The generiy part of GNU ZRTP needs only a few callback methods to be implemented by the specific part.

Author
Werner Dittmann Werne.nosp@m.r.Di.nosp@m.ttman.nosp@m.n@t-.nosp@m.onlin.nosp@m.e.de The following methods define the GNU ZRTP callback interface. For detailed documentation refer to file ZrtpCallback.h, each C method has "zrtp_" prepended to the C++ name.
See Also
ZrtpCallback

Definition at line 261 of file ZrtpCWrapper.h.

typedef struct ZrtpConfigure ZrtpConfigure

Definition at line 262 of file ZrtpCWrapper.h.

typedef struct zrtpContext ZrtpContext

Enumeration Type Documentation

This enumerations list all configurable algorithm types.

Enumerator
zrtp_HashAlgorithm 
zrtp_CipherAlgorithm 
zrtp_PubKeyAlgorithm 
zrtp_SasType 
zrtp_AuthLength 

Definition at line 1077 of file ZrtpCWrapper.h.

Sub-codes for Info.

Enumerator
zrtp_InfoHelloReceived 

Hello received, preparing a Commit

zrtp_InfoCommitDHGenerated 

Commit: Generated a public DH key

zrtp_InfoRespCommitReceived 

Responder: Commit received, preparing DHPart1

zrtp_InfoDH1DHGenerated 

DH1Part: Generated a public DH key

zrtp_InfoInitDH1Received 

Initiator: DHPart1 received, preparing DHPart2

zrtp_InfoRespDH2Received 

Responder: DHPart2 received, preparing Confirm1

zrtp_InfoInitConf1Received 

Initiator: Confirm1 received, preparing Confirm2

zrtp_InfoRespConf2Received 

Responder: Confirm2 received, preparing Conf2Ack

zrtp_InfoRSMatchFound 

At least one retained secrets matches - security OK

zrtp_InfoSecureStateOn 

Entered secure state

zrtp_InfoSecureStateOff 

No more security for this session

Definition at line 113 of file ZrtpCWrapper.h.

Information codes for the Enrollment user callbacks.

Enumerator
zrtp_EnrollmentRequest 

Aks user to confirm or deny an Enrollemnt request.

zrtp_EnrollmentCanceled 

User did not confirm the PBX enrollement.

zrtp_EnrollmentFailed 

Enrollment process failed, no PBX secret available.

zrtp_EnrollmentOk 

Enrollment process for this PBX was ok.

Definition at line 190 of file ZrtpCWrapper.h.

This enum defines the information message severity.

The ZRTP implementation issues information messages to inform the user about ongoing processing, unusual behavior, or alerts in case of severe problems. Each main severity code a number of sub-codes exist that specify the exact nature of the problem.

An application gets message severity codes and the associated sub-codes via the ZrtpUserCallback::showMessage method.

The severity levels and their meaning are:

Info
keeps the user informed about ongoing processing and security setup. The enumeration InfoCodes defines the subcodes.
Warning
is an information about some security issues, e.g. if an AES 256 encryption is request but only DH 3072 as public key scheme is supported. ZRTP will establish a secure session (SRTP). The enumeration WarningCodes defines the sub-codes.
Severe
is used if an error occured during ZRTP protocol usage. In case of Severe ZRTP will not establish a secure session. The enumeration SevereCodes defines the sub-codes.
Zrtp
shows a ZRTP security problem. Refer to the enumeration ZrtpErrorCodes for sub-codes. GNU ZRTP of course will not establish a secure session.
Enumerator
zrtp_Info 

Just an info message

zrtp_Warning 

A Warning message - security can be established

zrtp_Severe 

Severe error, security will not be established

zrtp_ZrtpError 

ZRTP error, security will not be established

Definition at line 103 of file ZrtpCWrapper.h.

Sub-codes for Severe.

Enumerator
zrtp_SevereHelloHMACFailed 

Hash HMAC check of Hello failed!

zrtp_SevereCommitHMACFailed 

Hash HMAC check of Commit failed!

zrtp_SevereDH1HMACFailed 

Hash HMAC check of DHPart1 failed!

zrtp_SevereDH2HMACFailed 

Hash HMAC check of DHPart2 failed!

zrtp_SevereCannotSend 

Cannot send data - connection or peer down?

zrtp_SevereProtocolError 

Internal protocol error occured!

zrtp_SevereNoTimer 

Cannot start a timer - internal resources exhausted?

zrtp_SevereTooMuchRetries 

Too much retries during ZRTP negotiation - connection or peer down?

Definition at line 144 of file ZrtpCWrapper.h.

The algorihms that we support in SRTP and that ZRTP can negotiate.

Enumerator
zrtp_Aes 

Use AES as symmetrical cipher algorithm

zrtp_TwoFish 

Use TwoFish as symmetrical cipher algorithm

zrtp_Sha1 

Use Sha1 as authentication algorithm

zrtp_Skein 

Use Skein as authentication algorithm

Definition at line 216 of file ZrtpCWrapper.h.

Sub-codes for Warning.

Enumerator
zrtp_WarningDHAESmismatch 

Commit contains an AES256 cipher but does not offer a Diffie-Helman 4096

zrtp_WarningGoClearReceived 

Received a GoClear message

zrtp_WarningDHShort 

Hello offers an AES256 cipher but does not offer a Diffie-Helman 4096

zrtp_WarningNoRSMatch 

No retained shared secrets available - must verify SAS

zrtp_WarningCRCmismatch 

Internal ZRTP packet checksum mismatch - packet dropped

zrtp_WarningSRTPauthError 

Dropping packet because SRTP authentication failed!

zrtp_WarningSRTPreplayError 

Dropping packet because SRTP replay check failed!

zrtp_WarningNoExpectedRSMatch 

Valid retained shared secrets availabe but no matches found - must verify SAS

Definition at line 130 of file ZrtpCWrapper.h.

Error codes according to the ZRTP specification chapter 6.9.

GNU ZRTP uses these error codes in two ways: to fill the appropriate field ing the ZRTP Error packet and as sub-code in ZrtpUserCallback::showMessage(). GNU ZRTP uses thes error codes also to report received Error packts, in this case the sub-codes are their negative values.

The enumeration member comments are copied from the ZRTP specification.

Enumerator
zrtp_MalformedPacket 

Malformed packet (CRC OK, but wrong structure)

zrtp_CriticalSWError 

Critical software error

zrtp_UnsuppZRTPVersion 

Unsupported ZRTP version

zrtp_HelloCompMismatch 

Hello components mismatch

zrtp_UnsuppHashType 

Hash type not supported

zrtp_UnsuppCiphertype 

Cipher type not supported

zrtp_UnsuppPKExchange 

Public key exchange not supported

zrtp_UnsuppSRTPAuthTag 

SRTP auth. tag not supported

zrtp_UnsuppSASScheme 

SAS scheme not supported

zrtp_NoSharedSecret 

No shared secret available, DH mode required

zrtp_DHErrorWrongPV 

DH Error: bad pvi or pvr ( == 1, 0, or p-1)

zrtp_DHErrorWrongHVI 

DH Error: hvi != hashed data

zrtp_SASuntrustedMiTM 

Received relayed SAS from untrusted MiTM

zrtp_ConfirmHMACWrong 

Auth. Error: Bad Confirm pkt HMAC

zrtp_NonceReused 

Nonce reuse

zrtp_EqualZIDHello 

Equal ZIDs in Hello

zrtp_GoCleatNotAllowed 

GoClear packet received, but not allowed

zrtp_IgnorePacket 

Internal state, not reported

Definition at line 166 of file ZrtpCWrapper.h.

enum zrtpStates
Enumerator
Initial 

Initial state after starting the state engine

Detect 

State sending Hello, try to detect answer message

AckDetected 

HelloAck received

AckSent 

HelloAck sent after Hello received

WaitCommit 

Wait for a Commit message

CommitSent 

Commit message sent

WaitDHPart2 

Wait for a DHPart2 message

WaitConfirm1 

Wait for a Confirm1 message

WaitConfirm2 

Wait for a confirm2 message

WaitConfAck 

Wait for Conf2Ack

WaitClearAck 

Wait for clearAck - not used

SecureState 

This is the secure state - SRTP active

WaitErrorAck 

Wait for ErrorAck message

numberOfStates 

Gives total number of protocol states

Definition at line 198 of file ZrtpCWrapper.h.

Function Documentation

int32_t isPeerEnrolled ( ZrtpContext zrtpContext)

Check if a peer's cache entry has a vaild MitM key.

If true then the other peer ha a valid MtiM key, i.e. the peer has performed the enrollment procedure. A PBX ZRTP Back-2-Back application can use this function to check which of the peers is enrolled.

Returns
True if the other peer has a valid Mitm key (is enrolled).
void zrtp_acceptEnrollment ( ZrtpContext zrtpContext,
int32_t  accepted 
)

Accept a PBX enrollment request.

If a PBX service asks to enroll the PBX trusted MitM key and the user accepts this request, for example by pressing an OK button, the client application shall call this method and set the parameter accepted to true. If the user does not accept the request set the parameter to false.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
acceptedTrue if the enrollment request is accepted, false otherwise.
int32_t zrtp_addAlgo ( ZrtpContext zrtpContext,
Zrtp_AlgoTypes  algoType,
const char *  algo 
)

Add an algorithm to configuration data.

Adds the specified algorithm to the configuration data. If no free configuration data slot is available the function does not add the algorithm and returns -1. The methods appends the algorithm to the existing algorithms.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
algoTypeSpecifies which algorithm type to select
algoThe name of the algorithm to add.
Returns
Number of free configuration data slots or -1 on error
int32_t zrtp_addAlgoAt ( ZrtpContext zrtpContext,
Zrtp_AlgoTypes  algoType,
const char *  algo,
int32_t  index 
)

Add an algorithm to configuration data at given index.

Adds the specified algorithm to the configuration data vector at a given index. If the index is larger than the actual size of the configuration vector the method just appends the algorithm.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
algoTypeSpecifies which algorithm type to select
algoThe name of the algorithm to add.
indexThe index where to add the algorihm
Returns
Number of free configuration data slots or -1 on error
int32_t zrtp_CheckCksum ( uint8_t *  buffer,
uint16_t  length,
uint32_t  crc 
)

Computes the ZRTP checksum over a received ZRTP packet buffer and compares the result with received checksum.

Parameters
bufferPointer to ZRTP packet buffer
lengthLength of the packet buffer excluding received CRC data
crcThe received CRC data.
Returns
True if CRC matches, false otherwise.
void zrtp_conf2AckSecure ( ZrtpContext zrtpContext)

Emulate a Conf2Ack packet.

This method emulates a Conf2Ack packet. According to ZRTP specification the first valid SRTP packet that the Initiator receives must switch on secure mode. Refer to chapter 4 in the specificaton

NOTE: application shall never call this method directly. Only the module that implements the RTP binding shall use this method

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
void zrtp_confClear ( ZrtpContext zrtpContext)

Clear all configuration data.

The functions clears all configuration data.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
int32_t zrtp_containsAlgo ( ZrtpContext zrtpContext,
Zrtp_AlgoTypes  algoType,
const char *  algo 
)

Checks if the configuration data of the algorihm type already contains a specific algorithms.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
algoTypeSpecifies which algorithm type to select
algoThe name of the algorithm to check
Returns
True if the algorithm was found, false otherwise.
ZrtpContext* zrtp_CreateWrapper ( )

Create the GNU ZRTP C wrapper.

This wrapper implements the C interface to the C++ based GNU ZRTP.

Returns
Pointer to the ZrtpContext
void zrtp_DestroyWrapper ( ZrtpContext zrtpContext)

Destroy the ZRTP wrapper and its underlying objects.

uint32_t zrtp_EndCksum ( uint32_t  crc)

Prepares the ZRTP checksum for appending to ZRTP packet.

Parameters
crcThe computed CRC data.
Returns
Prepared CRC data in host order
void zrtp_freeAlgorithmNames ( char **  names)

Free storage used to store the algorithm names.

If an application does not longer require the algoritm names it should free the space.

Parameters
namesThe NULL terminated array of character pointers.
uint32_t zrtp_GenerateCksum ( uint8_t *  buffer,
uint16_t  length 
)

Computes the ZRTP checksum over a newly created ZRTP packet buffer.

Parameters
bufferPointer to the created ZRTP packet buffer
lengthLength of the packet buffer
Returns
The computed CRC.
const char* zrtp_getAlgoAt ( ZrtpContext zrtpContext,
Zrtp_AlgoTypes  algoType,
int32_t  index 
)

Returns the identifier of the algorithm at index.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
algoTypeSpecifies which algorithm type to select
indexThe index in the list of the algorihm type
Returns
A pointer to the algorithm name. If the index does not point to a configured slot then the function returns NULL.
char** zrtp_getAlgorithmNames ( ZrtpContext zrtpContext,
Zrtp_AlgoTypes  type 
)

Get names of all available algorithmes of a given algorithm type.

The algorithm names are as specified in the ZRTP specification, chapters 5.1.2 through 5.1.6 .

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
typeThe algorithm type.
Returns
A NULL terminated array of character pointers.
char* zrtp_getHelloHash ( ZrtpContext zrtpContext)

Get the ZRTP Hello Hash data.

Use this method to get the ZRTP Hello Hash data. The method returns the data as a string containing the ZRTP protocol version and hex-digits. Refer to ZRTP specification, chapter 8.

NOTE: An application may call this method if it needs this information. Usually it is not necessary.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
Returns
a pointer to a C-string that contains the Hello hash value as hex-digits. The hello hash is available immediately after zrtp_CreateWrapper . The caller must free() if it does not use the hello hash C-string anymore.
char* zrtp_getMultiStrParams ( ZrtpContext zrtpContext,
int32_t *  length 
)

Get Multi-stream parameters.

Use this method to get the Multi-stream parameters that were computed during the ZRTP handshake. An application may use these parameters to enable multi-stream processing for an associated SRTP session.

The application must not modify the contents of returned char array, it is opaque data. The application may hand over this string to a new ZRTP instance to enable multi-stream processing for this new session.

Refer to chapter 4.4.2 in the ZRTP specification for further details and restriction how and when to use multi-stream mode.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
lengthPointer to an integer that receives the length of the char array
Returns
a char array that contains the multi-stream parameters. If ZRTP was not started or ZRTP is not yet in secure state the method returns NULL and a length of 0.
int32_t zrtp_getNumConfiguredAlgos ( ZrtpContext zrtpContext,
Zrtp_AlgoTypes  algoType 
)

Returns the number of configured algorithms.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
algoTypeSpecifies which algorithm type to select
Returns
The number of configured algorithms (used configuration data slots)
char* zrtp_getPeerHelloHash ( ZrtpContext zrtpContext)

Get the peer's ZRTP Hello Hash data.

Use this method to get the peer's ZRTP Hello Hash data. The method returns the data as a string containing the ZRTP protocol version and hex-digits.

The peer's hello hash is available only after ZRTP received a hello. If no data is available the function returns an empty string.

Refer to ZRTP specification, chapter 8.

Returns
a std:string containing the Hello version and the hello hash as hex digits.
int32_t zrtp_getPeerZid ( ZrtpContext zrtpContext,
uint8_t *  data 
)

Get other party's ZID (ZRTP Identifier) data.

This functions returns the other party's ZID that was receivied during ZRTP processing.

The ZID data can be retrieved after ZRTP receive the first Hello packet from the other party. The application may call this method for example during SAS processing in showSAS(...) user callback method.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
dataPointer to a data buffer. This buffer must have a size of at least 12 bytes (96 bit) (ZRTP Identifier, see chap. 4.9)
Returns
Number of bytes copied into the data buffer - must be equivalent to 12 bytes.
uint8_t* zrtp_getSasHash ( ZrtpContext zrtpContext)

Get the computed SAS hash for this ZRTP session.

A PBX ZRTP back-to-Back function uses this function to get the SAS hash of an enrolled client to construct the SAS relay packet for the other client.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
Returns
a pointer to the byte array that contains the full SAS hash.
const char* zrtp_getSasType ( ZrtpContext zrtpContext)

Get the commited SAS rendering algorithm for this ZRTP session.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
Returns
the commited SAS rendering algorithm
const uint8_t* zrtp_getSignatureData ( ZrtpContext zrtpContext)

Get signature data.

This functions returns signature data that was receivied during ZRTP processing. Refer to chapters 5.7 and 7.2.

The signature data can be retrieved after ZRTP enters secure state. start().

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
Returns
Number of bytes copied into the data buffer
int32_t zrtp_getSignatureLength ( ZrtpContext zrtpContext)

Get length of signature data.

This functions returns the length of signature data that was receivied during ZRTP processing. Refer to chapters 5.7 and 7.2.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
Returns
Length in bytes of the received signature data. The method returns zero if no signature data avilable.
int32_t zrtp_InitializeConfig ( ZrtpContext zrtpContext)

Initialize the GNU ZRTP Configure data.

Initializing and setting a ZRTP configuration is optional. GNU ZRTP uses a sensible default if an application does not define its own ZRTP configuration.

If an application initialize th configure data it must set the configuration data.

The ZRTP specification, chapters 5.1.2 through 5.1.6 defines the algorithm names and their meaning.

The current ZRTP implementation implements all mandatory algorithms plus a set of the optional algorithms. An application shall use zrtp_getAlgorithmNames to get the names of the available algorithms.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
Returns
Pointer to the ZrtpConfCtx
See Also
zrtp_getAlgorithmNames
void zrtp_initializeZrtpEngine ( ZrtpContext zrtpContext,
zrtp_Callbacks cb,
const char *  id,
const char *  zidFilename,
void *  userData,
int32_t  mitmMode 
)

Initialize the ZRTP protocol engine.

This method initialized the GNU ZRTP protocol engine. An application calls this method to actually create the ZRTP protocol engine and initialize its configuration data. This method does not start the protocol engine.

If an application requires a specific algorithm configuration then it must set the algorithm configuration data before it initializes the ZRTP protocol engine.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
cbThe callback structure that holds the addresses of the callback methods.
idA C string that holds the ZRTP client id, only the first 16 chars are used.
zidFilenameThe name of the ZID file. This file holds some parameters and other data like additional shared secrets.
userDataA pointer to user data. The wrapper just stores this pointer in the ZrtpContext and the application may use it for its purposes.
mitmModeA trusted Mitm (PBX) must set this to true. The ZRTP engine sets the M Flag in the Hello packet to announce a trusted MitM.
Returns
Pointer to the ZrtpContext
See Also
zrtp_InitializeConfig
int32_t zrtp_inState ( ZrtpContext zrtpContext,
int32_t  state 
)

Check current state of the ZRTP state engine.

NOTE: application usually don't call this method. Only the m-odule that implements the RTP binding shall use this method

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
stateThe state to check.
Returns
Returns true if ZRTP engine is in the given state, false otherwise.
int32_t zrtp_isEnrollmentMode ( ZrtpContext zrtpContext)

Check the state of the enrollment mode.

If true then we will set the enrollment flag (E) in the confirm packets and performs the enrollment actions. A MitM (PBX) enrollment service started this ZRTP session. Can be set to true only if mitmMode is also true.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
Returns
status of the enrollmentMode flag.
int32_t zrtp_isMultiStream ( ZrtpContext zrtpContext)

Check if this ZRTP session is a Multi-stream session.

Use this method to check if this ZRTP instance uses multi-stream. Refer to chapters 4.2 and 4.4.2 in the ZRTP.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
Returns
True if multi-stream is used, false otherwise.
int32_t zrtp_isMultiStreamAvailable ( ZrtpContext zrtpContext)

Check if the other ZRTP client supports Multi-stream.

Use this method to check if the other ZRTP client supports Multi-stream mode.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
Returns
True if multi-stream is available, false otherwise.
int32_t zrtp_isSasSignature ( ZrtpContext zrtpContext)

Check status of SAS signature processing.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
Returns
Returns true if certificate processing is enabled.
int32_t zrtp_isTrustedMitM ( ZrtpContext zrtpContext)

Check status of trusted MitM processing.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
Returns
Returns true if trusted MitM processing is enabled.
void zrtp_processTimeout ( ZrtpContext zrtpContext)

Process a timeout event.

We got a timeout from the timeout provider. Forward it to the protocol state engine.

NOTE: application shall never call this method directly. Only the module that implements the RTP binding shall use this method

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
void zrtp_processZrtpMessage ( ZrtpContext zrtpContext,
uint8_t *  extHeader,
uint32_t  peerSSRC 
)

Process RTP extension header.

This method expects to get a pointer to the message part of a ZRTP packet.

NOTE: An application shall never call this method directly. Only the module that implements the RTP binding shall use this method

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
extHeaderA pointer to the first byte of the ZRTP message part.
peerSSRCThe peer's SSRC.
Returns
Code indicating further packet handling, see description above.
int32_t zrtp_removeAlgo ( ZrtpContext zrtpContext,
Zrtp_AlgoTypes  algoType,
const char *  algo 
)

Remove a algorithm from configuration data.

Removes the specified algorithm from configuration data. If the algorithm was not configured previously the function does not modify the configuration data and returns the number of free configuration data slots.

If an application removes all algorithms then ZRTP does not include any algorithm into the hello message and falls back to a predefined mandatory algorithm.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
algoTypeSpecifies which algorithm type to select
algoThe name of the algorithm to remove.
Returns
Number of free configuration slots.
void zrtp_resetSASVerified ( ZrtpContext zrtpContext)

Reset the SAS verfied flag for the current active user's retained secrets.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
void zrtp_SASVerified ( ZrtpContext zrtpContext)

Set SAS as verified.

Call this method if the user confirmed (verfied) the SAS. ZRTP remembers this together with the retained secrets data.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
int32_t zrtp_sendSASRelayPacket ( ZrtpContext zrtpContext,
uint8_t *  sh,
char *  render 
)

Send the SAS relay packet.

The method creates and sends a SAS relay packet according to the ZRTP specifications. Usually only a MitM capable user agent (PBX) uses this function.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
shthe full SAS hash value
renderthe SAS rendering algorithm
void zrtp_setAuxSecret ( ZrtpContext zrtpContext,
uint8_t *  data,
int32_t  length 
)

Set the auxilliary secret.

Use this method to set the auxilliary secret data. Refer to ZRTP specification, chapter 4.3 ff

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
dataPoints to the secret data.
lengthLength of the auxilliary secrect in bytes
void zrtp_setEnrollmentMode ( ZrtpContext zrtpContext,
int32_t  enrollmentMode 
)

Check the state of the enrollment mode.

If true then we will set the enrollment flag (E) in the confirm packets and perform the enrollment actions. A MitM (PBX) enrollment service must sets this mode to true.

Can be set to true only if mitmMode is also true.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
enrollmentModedefines the new state of the enrollmentMode flag
void zrtp_setMandatoryOnly ( ZrtpContext zrtpContext)

Convenience function that sets the mandatory algorithms only.

Mandatory algorithms are:

  • Hash: SHA256
  • Symmetric Cipher: AES 128
  • Public Key Algorithm: DH3027, MultiStream
  • SAS type: libase 32
  • SRTP Authentication lengths: 32, 80
Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
void zrtp_setMultiStrParams ( ZrtpContext zrtpContext,
char *  parameters,
int32_t  length 
)

Set Multi-stream parameters.

Use this method to set the parameters required to enable Multi-stream processing of ZRTP. The multi-stream parameters must be set before the application starts the ZRTP protocol engine.

Refer to chapter 4.4.2 in the ZRTP specification for further details of multi-stream mode.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
lengthThe integer that contains the length of the char array
parametersA char array that contains the multi-stream parameters that this new ZRTP instance shall use. See also getMultiStrParams()
void zrtp_setSasSignature ( ZrtpContext zrtpContext,
int32_t  yesNo 
)

Enables or disables SAS signature processing.

For further details of trusted MitM processing refer to ZRTP specification, chapter 7.2

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
yesNoIf true then certificate processing is enabled.
int32_t zrtp_setSignatureData ( ZrtpContext zrtpContext,
uint8_t *  data,
int32_t  length 
)

Set signature data.

This functions stores signature data and transmitts it during ZRTP processing to the other party as part of the Confirm packets. Refer to chapters 5.7 and 7.2.

The signature data must be set before ZRTP the application calls start().

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
dataThe signature data including the signature type block. The method copies this data into the Confirm packet at signature type block.
lengthThe length of the signature data in bytes. This length must be multiple of 4.
Returns
True if the method stored the data, false otherwise.
void zrtp_setStandardConfig ( ZrtpContext zrtpContext)

Convenience function that sets a pre-defined standard configuration.

The standard configuration consists of the following algorithms:

  • Hash: SHA256
  • Symmetric Cipher: AES 128, AES 256
  • Public Key Algorithm: DH2048, DH3027, MultiStream
  • SAS type: libase 32
  • SRTP Authentication lengths: 32, 80
Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
void zrtp_setTrustedMitM ( ZrtpContext zrtpContext,
int32_t  yesNo 
)

Enables or disables trusted MitM processing.

For further details of trusted MitM processing refer to ZRTP specification, chapter 7.3

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
yesNoIf set to true then trusted MitM processing is enabled.
void zrtp_startZrtpEngine ( ZrtpContext zrtpContext)

Kick off the ZRTP protocol engine.

This method calls the ZrtpStateClass::evInitial() state of the state engine. After this call we are able to process ZRTP packets from our peer and to process them.

NOTE: application shall never call this method directly but use the appropriate method provided by the RTP implementation.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.
void zrtp_stopZrtpEngine ( ZrtpContext zrtpContext)

Stop ZRTP security.

NOTE: An application shall never call this method directly but use the appropriate method provided by the RTP implementation.

Parameters
zrtpContextPointer to the opaque ZrtpContext structure.