The GNU ZRTP C-to-C++ wrapper. More...
#include <stdint.h>Go to the source code of this file.
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.
Definition in file ZrtpCWrapper.h.
Size of CRC code of a ZRTP packet
Definition at line 61 of file ZrtpCWrapper.h.
Enable security for SRTP receiver
Definition at line 251 of file ZrtpCWrapper.h.
Enable security for SRTP sender
Definition at line 252 of file ZrtpCWrapper.h.
This client is in ZRTP Initiator mode
Definition at line 59 of file ZrtpCWrapper.h.
The biggest ZRTP packet ever possible
Definition at line 63 of file ZrtpCWrapper.h.
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.
This client is in ZRTP Responder mode
Definition at line 58 of file ZrtpCWrapper.h.
The magic code that identifies a ZRTP packet
Definition at line 62 of file ZrtpCWrapper.h.
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.
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.
Definition at line 261 of file ZrtpCWrapper.h.
Definition at line 262 of file ZrtpCWrapper.h.
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:
| 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.
| 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.
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.
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.
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.
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.
Computes the ZRTP checksum over a received ZRTP packet buffer and compares the result with received checksum.
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
Clear all configuration data.
The functions clears all configuration data.
Checks if the configuration data of the algorihm type already contains a specific algorithms.
Create the GNU ZRTP C wrapper.
This wrapper implements the C interface to the C++ based GNU ZRTP.
Destroy the ZRTP wrapper and its underlying objects.
Prepares the ZRTP checksum for appending to ZRTP packet.
Free storage used to store the algorithm names.
If an application does not longer require the algoritm names it should free the space.
Computes the ZRTP checksum over a newly created ZRTP packet buffer.
Returns the identifier of the algorithm at index.
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 .
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.
zrtp_CreateWrapper . The caller must free() if it does not use the hello hash C-string anymore. 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.
Returns the number of configured algorithms.
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.
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.
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.
Get the commited SAS rendering algorithm for this ZRTP session.
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().
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.
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.
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.
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
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.
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.
Check if the other ZRTP client supports Multi-stream.
Use this method to check if the other ZRTP client supports Multi-stream mode.
Check status of SAS signature processing.
Check status of trusted MitM processing.
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
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
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.
Reset the SAS verfied flag for the current active user's retained secrets.
Set SAS as verified.
Call this method if the user confirmed (verfied) the SAS. ZRTP remembers this together with the retained secrets data.
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.
Set the auxilliary secret.
Use this method to set the auxilliary secret data. Refer to ZRTP specification, chapter 4.3 ff
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.
Convenience function that sets the mandatory algorithms only.
Mandatory algorithms are:
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.
getMultiStrParams() Enables or disables SAS signature processing.
For further details of trusted MitM processing refer to ZRTP specification, chapter 7.2
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().
Convenience function that sets a pre-defined standard configuration.
The standard configuration consists of the following algorithms:
Enables or disables trusted MitM processing.
For further details of trusted MitM processing refer to ZRTP specification, chapter 7.3
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.
Stop ZRTP security.
NOTE: An application shall never call this method directly but use the appropriate method provided by the RTP implementation.