zrtp_engine.h File Reference

#include "zrtp_types.h"
#include "zrtp_crypto.h"

Go to the source code of this file.

Defines

#define ZRTP_IS_STREAM_DH(stream)   (stream->mode == ZRTP_STREAM_MODE_DH)

#define ZRTP_IS_STREAM_FAST(stream)   (stream->mode != ZRTP_STREAM_MODE_DH)

#define ZRTP_IS_STREAM_MULT(stream)   (stream->mode == ZRTP_STREAM_MODE_MULT)

#define ZRTP_IS_STREAM_PRESH(stream)   (stream->mode == ZRTP_STREAM_MODE_PRESHARED)

#define ZRTP_PASSIVE1_TEST(stream)

Test Passive Rule N1 A passive endpoint never sends a Commit message. Semi-active endpoint does not send a commit to a passive endpoint. Return 1 if the tast have been passed successfully and 0 in other case.

#define ZRTP_PASSIVE2_TEST(stream)

Test Passive Rule N2 A passive phone, if acting as a SIP initiator (meaning it initiated the call), rejects all commit packets from everyone. Return 1 if the tast have been passed successfully and 0 in other case.

#define ZRTP_PASSIVE3_TEST(stream)

Test Passive Rule N3 A passive phone rejects all commit messages from a PBX. Return 1 if the tast have been passed successfully and 0 in other case.

Functions

zrtp_shared_secret_t * _zrtp_alloc_shared_secret (zrtp_conn_ctx_t *session)

Allocate shared secret structure This function allocates memory for a zrtp_shared_secret_t and initializes the secret value using a zrtp_fill_shared_secret() function call. Used in protocol allocating.

zrtp_status_t _zrtp_prepare_secrets (zrtp_conn_ctx_t *session)

Restores secrets from the cache Uploads retained secrets from the cache and initializes secret flags. If the secret has expired (is_expired flag is set), its value will be randomly regenerated. _zrtp_prepare_secrets() is called after the discovery phase on the setting up the very first stream. After secrets are uploaded the zrtp_secrets_t::_is_ready flag is enabled to prevent secrets from reinitialization on setting up the next stream. Like all other operations with the cache this one is protected by the mutex zrtp_global_ctx_t::_cache_protector.

int _zrtp_can_start_stream (zrtp_stream_ctx_t *stream, zrtp_stream_ctx_t **conc, zrtp_stream_mode_t mode)

Check availability to start stream (DH or Preshared) The ZRTP specification says that only one DH stream can be run at a time between two ZRTP endpoints. So _zrtp_can_start_stream(DH) looks over all sessions between two ZIDs and if any other stream is running it denies the start of another DH stream in parallel. Although the ZRTP standard says that Preshared or Multistream stream can't be run in parallel with DH streams between two ZRTP endpoints. So _zrtp_can_start_stream(PRESH) looks over all sessions between two ZIDs and if any other DH stream is running it denies the start of Preshared/Multistream stream in parallel. All operations with sessions and streams are protected by mutexes. Call this function every time before starting "initiating secure" process. For internal use only.

uint8_t _zrtp_choose_best_comp (zrtp_profile_t *profile, zrtp_packet_Hello_t *peer_hello, zrtp_crypto_comp_t type)

Chooses the best crypto component of the given type Selects the crypto component according to the local initiator's profile and the remote responder's Hello.

int _zrtp_validate_message_hmac (zrtp_stream_ctx_t *stream, zrtp_msg_hdr_t *msg2check, char *hmackey)

zrtp_status_t _zrtp_compute_preshared_key (zrtp_conn_ctx_t *session, zrtp_stringn_t *key, zrtp_stringn_t *key_id, zrtp_stringn_t *rs1, zrtp_stringn_t *auxs, zrtp_stringn_t *pbxs)

zrtp_status_t _zrtp_attach_protocol (zrtp_stream_ctx_t *stream_ctx, uint8_t is_initiator)

Allocate ZRTP protocol structure Allocates and initializes all necessary data according to the protocol mode. Initializes required DH crypto context info and generates secret IDs.

void _zrtp_free_protocol (zrtp_protocol_t *proto)

Release protocol structure Stops all replay tasks, clears all crypto sources and SRTP engine, and releases memory. The protocol should be destroyed on: stream closing, or switching to CLEAR or ERROR states.

uint32_t _zrtp_get_timeout (uint32_t curr_timeout, zrtp_msg_type_t msg)

Computes replay timeouts This function computes messages replays schedule. There are some recomended values by ZRTP specification, but in some network environments values may be sligh different.

void _zrtp_cancel_send_packet_later (zrtp_stream_ctx_t *ctx, zrtp_msg_type_t type)

Terminates retransmission task This function is a wrapper around zrtp_cancele_send_packet_later() which unsets the zrtp_retry_task_t::_is_enabled flag to prevent the scheduler from re-adding tasks after their termination.

void _zrtp_change_state (zrtp_stream_ctx_t *stream, zrtp_state_t state)

state switcher This function changes stream state to state, makes a backup of the previous state at zrtp_stream_ctx_t::_prev_state and prints debug information.

zrtp_status_t _zrtp_preparse_packet (zrtp_stream_ctx_t *stream, char *packet, uint32_t *length, zrtp_rtp_info_t *info, uint8_t is_input)

Prepare RTP/ZRTP media packet for the further processing. This function defines the packet type, parses SSRC and makes the sequence number implicit. If it is a ZRTP message, packet length correctness and CRC are checked as well.

zrtp_status_t _zrtp_fill_msg_hdr (zrtp_stream_ctx_t *stream, zrtp_msg_type_t type, uint16_t body_length, zrtp_msg_hdr_t *hdr)

Fills ZRTP message header and computes messages HMAC _zrtp_fill_msg_hdr() prepares a ZRTP message header for sending. It calculates the total message length in 4-byte words and fills the message type block.

ZRTP_INLINE void * _zrtp_get_msg_hdr (zrtp_rtp_info_t *packet)

Returns a pointer to ZRTP message body.

int _zrtp_send_zrtp_packet (zrtp_stream_ctx_t *ctx, zrtp_msg_type_t type, const void *message)

Sends ZRTP message onto the network _zrtp_send_zrtp_packet constructs a ZRTP header and prepares packet for sending, computes CRC and injects the packet into the network using the interface function zrtp_send_rtp().

zrtp_msg_type_t zrtp_get_packet_type (zrtp_rtp_hdr_t UNALIGNED *hdr, uint32_t length)

Returns ZRTP message type by symbolic name in header.

void _zrtp_insert_crc (zrtp_rtp_info_t *packet)

Insert CRC32 to ZRTP packets This function computes the 32 bit ZRTP packet checksum according to RFC 3309. As specified at "ZRTP Internet Draft", CRC32 is appended to the end of the extension for every ZRTP packet.

int8_t _zrtp_validate_crc (const zrtp_rtp_info_t *packet)

Validate ZRTP packet CRC.

zrtp_status_t enter_state_pendingsecure (zrtp_stream_ctx_t *stream, zrtp_rtp_info_t *commit)

zrtp_status_t enter_state_initiatingsecure (zrtp_stream_ctx_t *stream)

zrtp_status_t enter_state_secure (zrtp_stream_ctx_t *stream)

void enter_state_initiatingerror (zrtp_stream_ctx_t *stream, zrtp_protocol_error_t code, uint8_t notif)

zrtp_status_t _start_initiating_secure (zrtp_stream_ctx_t *stream)

zrtp_status_t enter_state_pendingclear (zrtp_stream_ctx_t *stream)

zrtp_status_t _zrtp_create_confirm (zrtp_stream_ctx_t *stream, zrtp_packet_Confirm_t *confirm)

zrtp_status_t _zrtp_process_incoming_confirm (zrtp_stream_ctx_t *stream, zrtp_packet_Confirm_t *confirm)

zrtp_status_t _process_incoming_goclear (zrtp_stream_ctx_t *stream, zrtp_rtp_info_t *packet)

zrtp_statemachine_type_t _zrtp_preparse_commit (zrtp_stream_ctx_t *stream, zrtp_rtp_info_t *packet)

zrtp_statemachine_type_t _zrtp_preparse_init_commit (zrtp_stream_ctx_t *stream, zrtp_rtp_info_t *packet)

zrtp_status_t _zrtp_set_public_value (zrtp_stream_ctx_t *stream_ctx, int is_initiator)

zrtp_stream_mode_t _zrtp_define_stream_mode (zrtp_stream_ctx_t *stream)

Function Documentation

zrtp_status_t _process_incoming_goclear	(	zrtp_stream_ctx_t *	stream,
		zrtp_rtp_info_t *	packet
	)

zrtp_status_t _start_initiating_secure ( zrtp_stream_ctx_t * stream )

zrtp_status_t _zrtp_create_confirm	(	zrtp_stream_ctx_t *	stream,
		zrtp_packet_Confirm_t *	confirm
	)

zrtp_stream_mode_t _zrtp_define_stream_mode ( zrtp_stream_ctx_t * stream )

zrtp_statemachine_type_t _zrtp_preparse_commit	(	zrtp_stream_ctx_t *	stream,
		zrtp_rtp_info_t *	packet
	)

zrtp_statemachine_type_t _zrtp_preparse_init_commit	(	zrtp_stream_ctx_t *	stream,
		zrtp_rtp_info_t *	packet
	)

zrtp_status_t _zrtp_process_incoming_confirm	(	zrtp_stream_ctx_t *	stream,
		zrtp_packet_Confirm_t *	confirm
	)

zrtp_status_t _zrtp_set_public_value	(	zrtp_stream_ctx_t *	stream_ctx,
		int	is_initiator
	)

void enter_state_initiatingerror	(	zrtp_stream_ctx_t *	stream,
		zrtp_protocol_error_t	code,
		uint8_t	notif
	)

zrtp_status_t enter_state_initiatingsecure ( zrtp_stream_ctx_t * stream )

zrtp_status_t enter_state_pendingclear ( zrtp_stream_ctx_t * stream )

zrtp_status_t enter_state_pendingsecure	(	zrtp_stream_ctx_t *	stream,
		zrtp_rtp_info_t *	commit
	)

zrtp_status_t enter_state_secure ( zrtp_stream_ctx_t * stream )

This file is part of the documentation for Zfone.


Defines
#define	ZRTP_IS_STREAM_DH(stream) (stream->mode == ZRTP_STREAM_MODE_DH)
#define	ZRTP_IS_STREAM_FAST(stream) (stream->mode != ZRTP_STREAM_MODE_DH)
#define	ZRTP_IS_STREAM_MULT(stream) (stream->mode == ZRTP_STREAM_MODE_MULT)
#define	ZRTP_IS_STREAM_PRESH(stream) (stream->mode == ZRTP_STREAM_MODE_PRESHARED)
#define	ZRTP_PASSIVE1_TEST(stream)
	Test Passive Rule N1 A passive endpoint never sends a Commit message. Semi-active endpoint does not send a commit to a passive endpoint. Return 1 if the tast have been passed successfully and 0 in other case.
#define	ZRTP_PASSIVE2_TEST(stream)
	Test Passive Rule N2 A passive phone, if acting as a SIP initiator (meaning it initiated the call), rejects all commit packets from everyone. Return 1 if the tast have been passed successfully and 0 in other case.
#define	ZRTP_PASSIVE3_TEST(stream)
	Test Passive Rule N3 A passive phone rejects all commit messages from a PBX. Return 1 if the tast have been passed successfully and 0 in other case.
Functions
zrtp_shared_secret_t *	_zrtp_alloc_shared_secret (zrtp_conn_ctx_t *session)
	Allocate shared secret structure This function allocates memory for a zrtp_shared_secret_t and initializes the secret value using a zrtp_fill_shared_secret() function call. Used in protocol allocating.
zrtp_status_t	_zrtp_prepare_secrets (zrtp_conn_ctx_t *session)
	Restores secrets from the cache Uploads retained secrets from the cache and initializes secret flags. If the secret has expired (is_expired flag is set), its value will be randomly regenerated. _zrtp_prepare_secrets() is called after the discovery phase on the setting up the very first stream. After secrets are uploaded the zrtp_secrets_t::_is_ready flag is enabled to prevent secrets from reinitialization on setting up the next stream. Like all other operations with the cache this one is protected by the mutex zrtp_global_ctx_t::_cache_protector.
int	_zrtp_can_start_stream (zrtp_stream_ctx_t stream, zrtp_stream_ctx_t *conc, zrtp_stream_mode_t mode)
	Check availability to start stream (DH or Preshared) The ZRTP specification says that only one DH stream can be run at a time between two ZRTP endpoints. So _zrtp_can_start_stream(DH) looks over all sessions between two ZIDs and if any other stream is running it denies the start of another DH stream in parallel. Although the ZRTP standard says that Preshared or Multistream stream can't be run in parallel with DH streams between two ZRTP endpoints. So _zrtp_can_start_stream(PRESH) looks over all sessions between two ZIDs and if any other DH stream is running it denies the start of Preshared/Multistream stream in parallel. All operations with sessions and streams are protected by mutexes. Call this function every time before starting "initiating secure" process. For internal use only.
uint8_t	_zrtp_choose_best_comp (zrtp_profile_t profile, zrtp_packet_Hello_t peer_hello, zrtp_crypto_comp_t type)
	Chooses the best crypto component of the given type Selects the crypto component according to the local initiator's profile and the remote responder's Hello.
int	_zrtp_validate_message_hmac (zrtp_stream_ctx_t stream, zrtp_msg_hdr_t msg2check, char *hmackey)
zrtp_status_t	_zrtp_compute_preshared_key (zrtp_conn_ctx_t session, zrtp_stringn_t key, zrtp_stringn_t key_id, zrtp_stringn_t rs1, zrtp_stringn_t auxs, zrtp_stringn_t pbxs)
zrtp_status_t	_zrtp_attach_protocol (zrtp_stream_ctx_t *stream_ctx, uint8_t is_initiator)
	Allocate ZRTP protocol structure Allocates and initializes all necessary data according to the protocol mode. Initializes required DH crypto context info and generates secret IDs.
void	_zrtp_free_protocol (zrtp_protocol_t *proto)
	Release protocol structure Stops all replay tasks, clears all crypto sources and SRTP engine, and releases memory. The protocol should be destroyed on: stream closing, or switching to CLEAR or ERROR states.
uint32_t	_zrtp_get_timeout (uint32_t curr_timeout, zrtp_msg_type_t msg)
	Computes replay timeouts This function computes messages replays schedule. There are some recomended values by ZRTP specification, but in some network environments values may be sligh different.
void	_zrtp_cancel_send_packet_later (zrtp_stream_ctx_t *ctx, zrtp_msg_type_t type)
	Terminates retransmission task This function is a wrapper around zrtp_cancele_send_packet_later() which unsets the zrtp_retry_task_t::_is_enabled flag to prevent the scheduler from re-adding tasks after their termination.
void	_zrtp_change_state (zrtp_stream_ctx_t *stream, zrtp_state_t state)
	state switcher This function changes stream state to `state`, makes a backup of the previous state at zrtp_stream_ctx_t::_prev_state and prints debug information.
zrtp_status_t	_zrtp_preparse_packet (zrtp_stream_ctx_t stream, char packet, uint32_t length, zrtp_rtp_info_t info, uint8_t is_input)
	Prepare RTP/ZRTP media packet for the further processing. This function defines the packet type, parses SSRC and makes the sequence number implicit. If it is a ZRTP message, packet length correctness and CRC are checked as well.
zrtp_status_t	_zrtp_fill_msg_hdr (zrtp_stream_ctx_t stream, zrtp_msg_type_t type, uint16_t body_length, zrtp_msg_hdr_t hdr)
	Fills ZRTP message header and computes messages HMAC _zrtp_fill_msg_hdr() prepares a ZRTP message header for sending. It calculates the total message length in 4-byte words and fills the message type block.
ZRTP_INLINE void *	_zrtp_get_msg_hdr (zrtp_rtp_info_t *packet)
	Returns a pointer to ZRTP message body.
int	_zrtp_send_zrtp_packet (zrtp_stream_ctx_t ctx, zrtp_msg_type_t type, const void message)
	Sends ZRTP message onto the network _zrtp_send_zrtp_packet constructs a ZRTP header and prepares packet for sending, computes CRC and injects the packet into the network using the interface function zrtp_send_rtp().
zrtp_msg_type_t	zrtp_get_packet_type (zrtp_rtp_hdr_t UNALIGNED *hdr, uint32_t length)
	Returns ZRTP message type by symbolic name in header.
void	_zrtp_insert_crc (zrtp_rtp_info_t *packet)
	Insert CRC32 to ZRTP packets This function computes the 32 bit ZRTP packet checksum according to RFC 3309. As specified at "ZRTP Internet Draft", CRC32 is appended to the end of the extension for every ZRTP packet.
int8_t	_zrtp_validate_crc (const zrtp_rtp_info_t *packet)
	Validate ZRTP packet CRC.
zrtp_status_t	enter_state_pendingsecure (zrtp_stream_ctx_t stream, zrtp_rtp_info_t commit)
zrtp_status_t	enter_state_initiatingsecure (zrtp_stream_ctx_t *stream)
zrtp_status_t	enter_state_secure (zrtp_stream_ctx_t *stream)
void	enter_state_initiatingerror (zrtp_stream_ctx_t *stream, zrtp_protocol_error_t code, uint8_t notif)
zrtp_status_t	_start_initiating_secure (zrtp_stream_ctx_t *stream)
zrtp_status_t	enter_state_pendingclear (zrtp_stream_ctx_t *stream)
zrtp_status_t	_zrtp_create_confirm (zrtp_stream_ctx_t stream, zrtp_packet_Confirm_t confirm)
zrtp_status_t	_zrtp_process_incoming_confirm (zrtp_stream_ctx_t stream, zrtp_packet_Confirm_t confirm)
zrtp_status_t	_process_incoming_goclear (zrtp_stream_ctx_t stream, zrtp_rtp_info_t packet)
zrtp_statemachine_type_t	_zrtp_preparse_commit (zrtp_stream_ctx_t stream, zrtp_rtp_info_t packet)
zrtp_statemachine_type_t	_zrtp_preparse_init_commit (zrtp_stream_ctx_t stream, zrtp_rtp_info_t packet)
zrtp_status_t	_zrtp_set_public_value (zrtp_stream_ctx_t *stream_ctx, int is_initiator)
zrtp_stream_mode_t	_zrtp_define_stream_mode (zrtp_stream_ctx_t *stream)