libzrtp  1.2.0
ZRTP VoIP security
Data Structures | Typedefs | Enumerations
ZRTP Protocol Feedback

Data Structures

struct  zrtp_callback_event_t
 Callbacks definitions. More...
 

Typedefs

typedef enum zrtp_protocol_event_t zrtp_protocol_event_t
 ZRTP Protocol events. More...
 
typedef enum zrtp_security_event_t zrtp_security_event_t
 ZRTP Protocol Errors and Warnings. More...
 
typedef struct zrtp_callback_event_t zrtp_callback_event_t
 Callbacks definitions. More...
 

Enumerations

enum  zrtp_protocol_event_t {
  ZRTP_EVENT_UNSUPPORTED = 0, ZRTP_EVENT_IS_CLEAR, ZRTP_EVENT_IS_INITIATINGSECURE, ZRTP_EVENT_IS_PENDINGSECURE,
  ZRTP_EVENT_IS_PENDINGCLEAR, ZRTP_EVENT_NO_ZRTP, ZRTP_EVENT_NO_ZRTP_QUICK, ZRTP_EVENT_IS_CLIENT_ENROLLMENT,
  ZRTP_EVENT_NEW_USER_ENROLLED, ZRTP_EVENT_USER_ALREADY_ENROLLED, ZRTP_EVENT_USER_UNENROLLED, ZRTP_EVENT_LOCAL_SAS_UPDATED,
  ZRTP_EVENT_REMOTE_SAS_UPDATED, ZRTP_EVENT_IS_SECURE, ZRTP_EVENT_IS_SECURE_DONE, ZRTP_EVENT_IS_PASSIVE_RESTRICTION,
  ZRTP_EVENT_COUNT
}
 ZRTP Protocol events. More...
 
enum  zrtp_security_event_t { ZRTP_EVENT_PROTOCOL_ERROR = ZRTP_EVENT_COUNT, ZRTP_EVENT_WRONG_SIGNALING_HASH, ZRTP_EVENT_WRONG_MESSAGE_HMAC, ZRTP_EVENT_MITM_WARNING }
 ZRTP Protocol Errors and Warnings. More...
 

Detailed Description

This section defines ZRTP protcol events. Detail description of ZRTP state-machine is defined in XXX.

Typedef Documentation

Callbacks definitions.

This section lists callback functions informing the user about the protocol status. These callbacks must be defined in the user application.

ZRTP Protocol events.

For additional information see XXX

ZRTP Protocol Errors and Warnings.

For additional information see XXX

Enumeration Type Documentation

ZRTP Protocol events.

For additional information see XXX

Enumerator
ZRTP_EVENT_UNSUPPORTED 

Just a stub for error detection.

ZRTP_EVENT_IS_CLEAR 

Switching to CLEAR state.

ZRTP_EVENT_IS_INITIATINGSECURE 

Switching to INITIATING_SECURE state.

ZRTP_EVENT_IS_PENDINGSECURE 

Switching to PENDING_SECURE state.

ZRTP_EVENT_IS_PENDINGCLEAR 

Switching to PENDING_CLEAR state.

ZRTP_EVENT_NO_ZRTP 

Switching to NO_ZRTP state.

Hello packet undelivered - no ZRTP endpoint and other end

ZRTP_EVENT_NO_ZRTP_QUICK 

First N Hello packet undelivered - probably, no ZRTP endpoint and other end.

Libzrtp raises this event after few Hello have been send without receiving response from the remote endpoint. User application may use this event to stop Securing ritual if connection lag is important.

Developer should take into account that delays in Hello receiving may be conditioned by interruptions in media channel

Warning
Don't handle this event unless necessary
ZRTP_EVENT_IS_CLIENT_ENROLLMENT 

MiTM Enrollment with MiTM endpoint.

Informs the Client-side endpoint of receiving a registration invitation from the MiTM. Libzrtp raises this event after switching to the Secure state (ZRTP_EVENT_IS_SECURE). The user may accept the invitation using a zrtp_register_with_trusted_mitm() call.

ZRTP_EVENT_NEW_USER_ENROLLED 

New user has registered to the MitM.

Informs MitM of the registration of a new user. Libzrtp raises this event when a user calls the special registration number and has switched to the secure state.

ZRTP_EVENT_USER_ALREADY_ENROLLED 

New user has already registered with the MiTM.

Notifies the MiTM of an attempt to register from a user that is already registered. In this case a new MiTM secret will not be generated and the user may be informed by voice prompt. Libzrtp raises this event from the SECURE state.

ZRTP_EVENT_USER_UNENROLLED 

User has cancelled registration.

Libzrtp may raise this event during regular calls when it discovers that the user has removed its MiTM secret. This event informs the MiTM that the SAS can no longer be transferred to this user.

ZRTP_EVENT_LOCAL_SAS_UPDATED 

SAS value and/or rendering scheme was updated.

LibZRTP raises this event when the SAS value is transferred from the trusted MiTM. The value is rendered automatically according to the rendering scheme specified by the trusted MiTM. (it may be different than that of the previous one).

On receiving this event, the Client application should replace the old SAS with the new one and ask the user to verify it. This event is called from the Secure state only.

ZRTP_EVENT_REMOTE_SAS_UPDATED 

SAS transfer was accepted by the remote side.

Libzrtp raises this event to inform the Server-side about accepting the change of SAS value and/or rendering scheme by the remote client. This event is called from the Secure state only.

ZRTP_EVENT_IS_SECURE 

Swishing to SECURE state.

Duplicates zrtp_callback_event_t::on_zrtp_secure for more thin adjustments.

ZRTP_EVENT_IS_SECURE_DONE 

Swishing to SECURE state is finished.

Equal to ZRTP_EVENT_IS_SECURE but called when the Securing process is completely finished: new RS secret is generate, cache flags updated and etc. Can be used in extended application for more thin adjustments.

ZRTP_EVENT_IS_PASSIVE_RESTRICTION 

Indicates DRM restriction. Stream can't go Secure.

Libzrtp generate this event if DRM rules don't allow to switch to Secure mode:

  • A passive endpoint never sends a Commit message. Semi-active endpoint does not send a Commit to a passive endpoint
  • A passive phone, if acting as a SIP initiator r ejects all commit packets from everyone.
  • A passive phone rejects all commit messages from a PBX.

ZRTP Protocol Errors and Warnings.

For additional information see XXX

Enumerator
ZRTP_EVENT_PROTOCOL_ERROR 

Switching to ERROR state.

The exact error code can be found at zrtp_stream_info_t::last_error. Use zrtp_log_error2str() to get error description in text mode.

ZRTP_EVENT_WRONG_SIGNALING_HASH 

Hello Hash is different from that received in signaling.

In accordance with sec. 8.1 of the ZRTP RFC, libzrtp provides the ability to prevent DOS attacks. libzrtp can detect an attack in which the hash of the remote Hello was received through signaling and added to the ZRTP context (zrtp_signaling_hash_set()).

When the hash of the incoming Hello doesn't match the hash from signaling, the ZRTP_EVENT_WRONG_SIGNALING_HASH event is raised and the connection MAY be terminated manually.

ZRTP_EVENT_WRONG_MESSAGE_HMAC 

Hmac of the received packet is different from the hmac value earlier received.

If the Hello hash is sent through protected signaling, libzrtp provides the ability to prevent protocol packets from modification and even eliminates comparing the SAS. To do this, libzrtp compares the message Hmac with the Hmac received in the previous message.

If the Hmacs don't match, the ZRTP_EVENT_WRONG_MESSAGE_HMAC event is raised and the connection MAY be terminated manually.

ZRTP_EVENT_MITM_WARNING 

Retain secret was found in the cache but it doesn't match with the remote one.

The library rises this event when non-expired secret have been found in the cache but value of the secret doesn't match with the remote side secret. Such situation may happen in case of MiTM attack or when remote side lost it's cache.

Recommended behavior: the application should notify user about the situation and ask him to verify the SAS. If SAS is different - it indicates the attack.