PBX related functions and data types
[API]

Collaboration diagram for PBX related functions and data types:

Functions
zrtp_status_t	zrtp_stream_registration_start (zrtp_stream_t *stream, uint32_t ssrc)
	Start ZRTP enrollment ritual on Server side.
zrtp_status_t	zrtp_stream_registration_secure (zrtp_stream_t *stream)
	Continue ZRTP enrollment ritual (from CLEAR state) on Server side.
zrtp_status_t	zrtp_register_with_trusted_mitm (zrtp_stream_t *stream)
	Confirms enrollment ritual on Client side.
zrtp_status_t	zrtp_resolve_mitm_call (zrtp_stream_t *stream1, zrtp_stream_t *stream2)
	Automatically handle ZRTP call in PBX environment.
zrtp_status_t	zrtp_update_remote_options (zrtp_stream_t *stream, zrtp_sas_id_t transf_sas_scheme, zrtp_string32_t *transf_sas_value, uint8_t transf_ac_flag, uint8_t transf_d_flag)
	Updates remote-side SAS value and rendering scheme.
uint8_t	zrtp_is_user_enrolled (zrtp_stream_t *stream)
	Check if user at the end of the stream stream is enrolled.
zrtp_stream_t *	zrtp_choose_one_enrolled (zrtp_stream_t *stream1, zrtp_stream_t *stream2)
	Choose single enrolled stream from two enrolled.

---

Detailed Description

In this section the basic functions for using the library in MiTM mode environment. Asterisk PBX, for example.

---

Function Documentation

zrtp_stream_t* zrtp_choose_one_enrolled	(	zrtp_stream_t *	stream1,
		zrtp_stream_t *	stream2
	)

Choose single enrolled stream from two enrolled.

This function may be used to resolve ambiguity with call transferring between two enrolled users.

Returns:

stream which shuld be used for SAS transferring

uint8_t zrtp_is_user_enrolled

(

zrtp_stream_t *

stream

)

Check if user at the end of the stream stream is enrolled.

Parameters:

stream

- stream for examining.

Returns:

: 1 if user is enrolled and 0 in other case

zrtp_status_t zrtp_register_with_trusted_mitm

(

zrtp_stream_t *

stream

)

Confirms enrollment ritual on Client side.

Invocation of this function by event zrtp_protocol_event_t::ZRTP_EVENT_IS_CLIENT_ENROLLMENT confirms enrollment process; libzrtp generates special secret which will be used to "Sign" all further calls with the trusted MiTM.

Returns:

• zrtp_status_ok - in case when enrollment was completed successfully;
• zrtp_status_fail - in case of error: wrong protocol state or system error.

zrtp_status_t zrtp_resolve_mitm_call	(	zrtp_stream_t *	stream1,
		zrtp_stream_t *	stream2
	)

Automatically handle ZRTP call in PBX environment.

This function may be called to handle ZRTP call between two ZRTP endpoints through PBX. As described in ID sec 8.3., there are several problems with ZRTP in PBX environment. zrtp_resolve_mitm_call() implements several steps to resolve such problems:

• detect enrolled and non enrolled endpoint. If both sides are enrolled - one side for the SAS transfer will be chousen automatically;
• start SAS transfer with the enrolled endpoint;
• update flags and SAS rendering scheme if necessary. In other words: After switching to SECURE state, this is the one function which ZRTP MiTM endpoint should call to handle ZRTP call correctly. If you want to have more flexability in MiTM mode - resolve ambiguity manually using functions listed below.

  Parameters:

  	stream1	- one party of ZRTP call (must be in secure state already);
  	stream2	- other party of ZRTP call (must be in secure state already).

  Returns:

• zrtp_status_ok - if operation started successfully;
• one of zrtp_status_t errors in other case. XXX_DRAFT, XXX_GUIDE

zrtp_status_t zrtp_stream_registration_secure

(

zrtp_stream_t *

stream

)

Continue ZRTP enrollment ritual (from CLEAR state) on Server side.

This is equivalent to zrtp_stream_secure() but with enrollment ritual. Use this function instead of zrtp_stream_registration_start() in case when "autosecure" option is disabled for some reason.

Returns:

• zrtp_status_ok - if operation started successfully;
• one of zrtp_status_t errorrs in other case.

zrtp_status_t zrtp_stream_registration_start	(	zrtp_stream_t *	stream,
		uint32_t	ssrc
	)

Start ZRTP enrollment ritual on Server side.

This is the equivalent of zrtp_stream_start() but for MiTM endpoints. By calling zrtp_stream_registration_start() libzrtp prepares to engage in the enrollment ritual: send special flag in Confirm packet and prepare for generating the MiTM secret.

Returns:

• zrtp_status_ok - if operation started successfully;
• one of zrtp_status_t errorrs in other case.

See also:

zrtp_callback_event_t::on_zrtp_protocol_event

zrtp_event_t (PBX related definitions)

zrtp_status_t zrtp_update_remote_options	(	zrtp_stream_t *	stream,
		zrtp_sas_id_t	transf_sas_scheme,
		zrtp_string32_t *	transf_sas_value,
		uint8_t	transf_ac_flag,
		uint8_t	transf_d_flag
	)

Updates remote-side SAS value and rendering scheme.

zrtp_update_remote_sas() initiates process of "SAS transferring" between trusted MiTM and user. It allows to change as SAS rendering scheme as a SAS value and related flags as well. It the MiTM needs to update just one of the parameters - the other one should be set to NULL. libzrtp informs about status of the SAS updating through zrtp_protocol_event_t::ZRTP_EVENT_REMOTE_SAS_UPDATED. Call this function in SECURE state only.

Parameters:

	stream	- zrtp endpoint stream to update;
	transf_sas_scheme	- chosen SAS rendering scheme;
	transf_sas_value	- relaying SAS value (full sas hash);
	transf_ac_flag	- relaying "allowclear" flag;
	transf_d_flag	- relaying "disclose" flag.

Returns:

• zrtp_status_ok - if operation started successfully;
• one of zrtp_status_t errors in other case.