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

#include <stdint.h>

Include dependency graph for ZrtpCWrapper.h:

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

ZrtpContext *	zrtp_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.

typedef enum zrtp_AlgoTypes Zrtp_AlgoTypes

This enumerations list all configurable algorithm types.

typedef struct zrtp_Callbacks zrtp_Callbacks

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

typedef struct ZrtpCallbackWrapper ZrtpCallbackWrapper

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

enum zrtp_AlgoTypes

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.

enum zrtp_InfoCodes

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.

enum zrtp_InfoEnrollment

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.

enum zrtp_MessageSeverity

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.

enum zrtp_SevereCodes

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.

enum zrtp_SrtpAlgorithms

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.

enum zrtp_WarningCodes

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.

enum zrtp_ZrtpErrorCodes

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

zrtpContext	Pointer to the opaque ZrtpContext structure.
accepted	True 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
algoType	Specifies which algorithm type to select
algo	The 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
algoType	Specifies which algorithm type to select
algo	The name of the algorithm to add.
index	The 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

buffer	Pointer to ZRTP packet buffer
length	Length of the packet buffer excluding received CRC data
crc	The 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

zrtpContext Pointer to the opaque ZrtpContext structure.

void zrtp_confClear ( ZrtpContext * zrtpContext )

Clear all configuration data.

The functions clears all configuration data.

Parameters

zrtpContext Pointer 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
algoType	Specifies which algorithm type to select
algo	The 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

crc	The 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

names The 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

buffer	Pointer to the created ZRTP packet buffer
length	Length 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
algoType	Specifies which algorithm type to select
index	The 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
type	The 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

zrtpContext Pointer 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
length	Pointer 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
algoType	Specifies 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
data	Pointer 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

zrtpContext Pointer 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

zrtpContext Pointer 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

zrtpContext Pointer 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

zrtpContext Pointer 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

zrtpContext Pointer 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
cb	The callback structure that holds the addresses of the callback methods.
id	A C string that holds the ZRTP client id, only the first 16 chars are used.
zidFilename	The name of the ZID file. This file holds some parameters and other data like additional shared secrets.
userData	A pointer to user data. The wrapper just stores this pointer in the ZrtpContext and the application may use it for its purposes.
mitmMode	A 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
state	The 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

zrtpContext Pointer 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

zrtpContext Pointer 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

zrtpContext Pointer 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

zrtpContext Pointer 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

zrtpContext Pointer 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

zrtpContext Pointer 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
extHeader	A pointer to the first byte of the ZRTP message part.
peerSSRC	The 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
algoType	Specifies which algorithm type to select
algo	The 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

zrtpContext Pointer 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

zrtpContext Pointer 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
sh	the full SAS hash value
render	the 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
data	Points to the secret data.
length	Length 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
enrollmentMode	defines 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

zrtpContext Pointer 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
length	The integer that contains the length of the char array
parameters	A 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
yesNo	If 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
data	The signature data including the signature type block. The method copies this data into the Confirm packet at signature type block.
length	The 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

zrtpContext Pointer 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

zrtpContext	Pointer to the opaque ZrtpContext structure.
yesNo	If 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

zrtpContext Pointer 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

zrtpContext Pointer to the opaque ZrtpContext structure.

Data Structures

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation