bZRTP
bZRTP is an opensource implementation of ZRTP keys exchange protocol
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Functions
packetParser.h File Reference

Go to the source code of this file.

Data Structures

struct  bzrtpPacket_struct
 Store all zrtpPacket informations according to type a specific structure type is mapped to the void * data pointer. More...
 
struct  bzrtpHelloMessage_struct
 Hello Message rfc 5.2. More...
 
struct  bzrtpCommitMessage_struct
 Hello ACK Message rfc 5.3 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet. More...
 
struct  bzrtpDHPartMessage_struct
 DHPart Message rfc 5.5 and rfc 5.6 DHPart1 and DHPart2 message have the same structure DHPart1 is generated by the responder, and DHPart2 by the initiator. More...
 
struct  bzrtpConfirmMessage_struct
 Confirm Message rfc 5.7 Confirm1 and Confirm2 messages have the same structure Confirm1 is generated by the responder and Confirm2 by the initiator Part of the message is encrypted using the negotiated block cipher for media encryption. Keys ares zrtpkeyr for responder and zrtpkeyi for initiator. More...
 
struct  bzrtpGoClearMessage_struct
 Conf2 ACK Message rfc 5.8 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet. More...
 
struct  bzrtpSASRelayMessage_struct
 Clear ACK Message rfc 5.12 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet. More...
 
struct  bzrtpPingMessage_struct
 Relay ACK Message rfc 5.14 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet. More...
 
struct  bzrtpPingAckMessage_struct
 PingAck Message The Ping and PingACK messages are unrelated to the rest of the ZRTP protocol. No ZRTP endpoint is required to generate a Ping message, but every ZRTP endpoint MUST respond to a Ping message with a PingACK message. More...
 

Macros

#define ZRTP_PACKET_HEADER_LENGTH   12
 
#define ZRTP_FRAGMENTEDPACKET_HEADER_LENGTH   20
 
#define ZRTP_PACKET_CRC_LENGTH   4
 
#define ZRTP_PACKET_OVERHEAD   (ZRTP_PACKET_HEADER_LENGTH + ZRTP_PACKET_CRC_LENGTH)
 
#define ZRTP_FRAGMENTEDPACKET_OVERHEAD   (ZRTP_FRAGMENTEDPACKET_HEADER_LENGTH + ZRTP_PACKET_CRC_LENGTH)
 
#define BZRTP_PARSER_ERROR_INVALIDCRC   0xa001
 
#define BZRTP_PARSER_ERROR_INVALIDPACKET   0xa002
 
#define BZRTP_PARSER_ERROR_OUTOFORDER   0xa004
 
#define BZRTP_PARSER_ERROR_INVALIDMESSAGE   0xa008
 
#define BZRTP_PARSER_ERROR_INVALIDCONTEXT   0xa010
 
#define BZRTP_PARSER_ERROR_UNMATCHINGCONFIRMMAC   0xa020
 
#define BZRTP_PARSER_ERROR_UNMATCHINGSSRC   0xa040
 
#define BZRTP_PARSER_ERROR_UNMATCHINGHASHCHAIN   0xa080
 
#define BZRTP_PARSER_ERROR_UNMATCHINGMAC   0xa100
 
#define BZRTP_PARSER_ERROR_UNEXPECTEDMESSAGE   0xa200
 
#define BZRTP_PARSER_ERROR_UNMATCHINGHVI   0xa400
 
#define BZRTP_PARSER_INFO_PACKETFRAGMENT   0xa800
 
#define BZRTP_BUILDER_ERROR_INVALIDPACKET   0x5001
 
#define BZRTP_BUILDER_ERROR_INVALIDMESSAGE   0x5002
 
#define BZRTP_BUILDER_ERROR_INVALIDMESSAGETYPE   0x5004
 
#define BZRTP_BUILDER_ERROR_UNKNOWN   0x5008
 
#define BZRTP_BUILDER_ERROR_INVALIDCONTEXT   0x5010
 
#define BZRTP_BUILDER_ERROR_UNABLETOFRAGMENT   0x5020
 
#define BZRTP_CREATE_ERROR_INVALIDMESSAGETYPE   0x0a01
 
#define BZRTP_CREATE_ERROR_UNABLETOCREATECRYPTOCONTEXT   0x0a02
 
#define BZRTP_CREATE_ERROR_INVALIDCONTEXT   0x0a04
 
#define MSGTYPE_INVALID   0x00
 
#define MSGTYPE_HELLO   0x01
 
#define MSGTYPE_HELLOACK   0x02
 
#define MSGTYPE_COMMIT   0x03
 
#define MSGTYPE_DHPART1   0x04
 
#define MSGTYPE_DHPART2   0x05
 
#define MSGTYPE_CONFIRM1   0x06
 
#define MSGTYPE_CONFIRM2   0x07
 
#define MSGTYPE_CONF2ACK   0x08
 
#define MSGTYPE_ERROR   0x10
 
#define MSGTYPE_ERRORACK   0x11
 
#define MSGTYPE_GOCLEAR   0x12
 
#define MSGTYPE_CLEARACK   0x13
 
#define MSGTYPE_SASRELAY   0x14
 
#define MSGTYPE_RELAYACK   0x15
 
#define MSGTYPE_PING   0x16
 
#define MSGTYPE_PINGACK   0x17
 
#define MSGTYPE_FRAGMENT   0xff
 
#define ZRTP_KEMPART2_NONCE_SIZE   16
 

Typedefs

typedef struct bzrtpPacket_struct bzrtpPacket_t
 Store all zrtpPacket informations according to type a specific structure type is mapped to the void * data pointer.
 
typedef struct bzrtpHelloMessage_struct bzrtpHelloMessage_t
 Hello Message rfc 5.2.
 
typedef struct bzrtpCommitMessage_struct bzrtpCommitMessage_t
 Hello ACK Message rfc 5.3 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet.
 
typedef struct bzrtpDHPartMessage_struct bzrtpDHPartMessage_t
 DHPart Message rfc 5.5 and rfc 5.6 DHPart1 and DHPart2 message have the same structure DHPart1 is generated by the responder, and DHPart2 by the initiator.
 
typedef struct bzrtpConfirmMessage_struct bzrtpConfirmMessage_t
 Confirm Message rfc 5.7 Confirm1 and Confirm2 messages have the same structure Confirm1 is generated by the responder and Confirm2 by the initiator Part of the message is encrypted using the negotiated block cipher for media encryption. Keys ares zrtpkeyr for responder and zrtpkeyi for initiator.
 
typedef struct bzrtpGoClearMessage_struct bzrtpGoClearMessage_t
 Conf2 ACK Message rfc 5.8 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet.
 
typedef struct bzrtpSASRelayMessage_struct bzrtpSASRelayMessage_t
 Clear ACK Message rfc 5.12 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet.
 
typedef struct bzrtpPingMessage_struct bzrtpPingMessage_t
 Relay ACK Message rfc 5.14 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet.
 
typedef struct bzrtpPingAckMessage_struct bzrtpPingAckMessage_t
 PingAck Message The Ping and PingACK messages are unrelated to the rest of the ZRTP protocol. No ZRTP endpoint is required to generate a Ping message, but every ZRTP endpoint MUST respond to a Ping message with a PingACK message.
 

Functions

BZRTP_EXPORT bzrtpPacket_tbzrtp_packetCheck (uint8_t **inputPtr, uint16_t *inputLength, bzrtpChannelContext_t *zrtpChannelContext, int *exitCode)
 Parse a string which shall be a valid ZRTP packet Check validity and allocate the bzrtpPacket structure but do not parse the message except for type and length. messageData structure field is not allocated by this function (use then bzrtp_packetParse for that). The packet check and actual message parsing are split in two functions to avoid useless parsing when message is to be discarded as the check will give message type (in case of message repetition for example)
 
BZRTP_EXPORT int bzrtp_packetParser (bzrtpContext_t *zrtpContext, bzrtpChannelContext_t *zrtpChannelContext, const uint8_t *input, uint16_t inputLength, bzrtpPacket_t *zrtpPacket)
 Parse the packet to extract the message and allocate the matching message structure if needed.
 
BZRTP_EXPORT bzrtpPacket_tbzrtp_createZrtpPacket (bzrtpContext_t *zrtpContext, bzrtpChannelContext_t *zrtpChannelContext, uint32_t messageType, int *exitCode)
 Create an empty packet and allocate the messageData according to requested packetType.
 
BZRTP_EXPORT int bzrtp_packetBuild (bzrtpContext_t *zrtpContext, bzrtpChannelContext_t *zrtpChannelContext, bzrtpPacket_t *zrtpPacket)
 Create a ZRTP packet string from the ZRTP packet values present in the structure messageType, messageData and sourceIdentifier in zrtpPacket must have been correctly set before calling this function The packet is not ready to be sent at that stage, sequenceNumber and CRC must be set using bzrtp_packetSetSequenceNumber.
 
BZRTP_EXPORT void bzrtp_freeZrtpPacket (bzrtpPacket_t *zrtpPacket)
 Deallocate zrtp Packet.
 
BZRTP_EXPORT int bzrtp_packetSetSequenceNumber (bzrtpPacket_t *zrtpPacket, uint16_t sequenceNumber)
 Set the current sequence number of the packet in the packetString and sequenceNumber fields The CRC at the end of packetString is also computed.
 

Macro Definition Documentation

◆ BZRTP_BUILDER_ERROR_INVALIDCONTEXT

#define BZRTP_BUILDER_ERROR_INVALIDCONTEXT   0x5010

◆ BZRTP_BUILDER_ERROR_INVALIDMESSAGE

#define BZRTP_BUILDER_ERROR_INVALIDMESSAGE   0x5002

◆ BZRTP_BUILDER_ERROR_INVALIDMESSAGETYPE

#define BZRTP_BUILDER_ERROR_INVALIDMESSAGETYPE   0x5004

◆ BZRTP_BUILDER_ERROR_INVALIDPACKET

#define BZRTP_BUILDER_ERROR_INVALIDPACKET   0x5001

◆ BZRTP_BUILDER_ERROR_UNABLETOFRAGMENT

#define BZRTP_BUILDER_ERROR_UNABLETOFRAGMENT   0x5020

◆ BZRTP_BUILDER_ERROR_UNKNOWN

#define BZRTP_BUILDER_ERROR_UNKNOWN   0x5008

◆ BZRTP_CREATE_ERROR_INVALIDCONTEXT

#define BZRTP_CREATE_ERROR_INVALIDCONTEXT   0x0a04

◆ BZRTP_CREATE_ERROR_INVALIDMESSAGETYPE

#define BZRTP_CREATE_ERROR_INVALIDMESSAGETYPE   0x0a01

◆ BZRTP_CREATE_ERROR_UNABLETOCREATECRYPTOCONTEXT

#define BZRTP_CREATE_ERROR_UNABLETOCREATECRYPTOCONTEXT   0x0a02

◆ BZRTP_PARSER_ERROR_INVALIDCONTEXT

#define BZRTP_PARSER_ERROR_INVALIDCONTEXT   0xa010

◆ BZRTP_PARSER_ERROR_INVALIDCRC

#define BZRTP_PARSER_ERROR_INVALIDCRC   0xa001

◆ BZRTP_PARSER_ERROR_INVALIDMESSAGE

#define BZRTP_PARSER_ERROR_INVALIDMESSAGE   0xa008

◆ BZRTP_PARSER_ERROR_INVALIDPACKET

#define BZRTP_PARSER_ERROR_INVALIDPACKET   0xa002

◆ BZRTP_PARSER_ERROR_OUTOFORDER

#define BZRTP_PARSER_ERROR_OUTOFORDER   0xa004

◆ BZRTP_PARSER_ERROR_UNEXPECTEDMESSAGE

#define BZRTP_PARSER_ERROR_UNEXPECTEDMESSAGE   0xa200

◆ BZRTP_PARSER_ERROR_UNMATCHINGCONFIRMMAC

#define BZRTP_PARSER_ERROR_UNMATCHINGCONFIRMMAC   0xa020

◆ BZRTP_PARSER_ERROR_UNMATCHINGHASHCHAIN

#define BZRTP_PARSER_ERROR_UNMATCHINGHASHCHAIN   0xa080

◆ BZRTP_PARSER_ERROR_UNMATCHINGHVI

#define BZRTP_PARSER_ERROR_UNMATCHINGHVI   0xa400

◆ BZRTP_PARSER_ERROR_UNMATCHINGMAC

#define BZRTP_PARSER_ERROR_UNMATCHINGMAC   0xa100

◆ BZRTP_PARSER_ERROR_UNMATCHINGSSRC

#define BZRTP_PARSER_ERROR_UNMATCHINGSSRC   0xa040

◆ BZRTP_PARSER_INFO_PACKETFRAGMENT

#define BZRTP_PARSER_INFO_PACKETFRAGMENT   0xa800

◆ MSGTYPE_CLEARACK

#define MSGTYPE_CLEARACK   0x13

◆ MSGTYPE_COMMIT

#define MSGTYPE_COMMIT   0x03

◆ MSGTYPE_CONF2ACK

#define MSGTYPE_CONF2ACK   0x08

◆ MSGTYPE_CONFIRM1

#define MSGTYPE_CONFIRM1   0x06

◆ MSGTYPE_CONFIRM2

#define MSGTYPE_CONFIRM2   0x07

◆ MSGTYPE_DHPART1

#define MSGTYPE_DHPART1   0x04

◆ MSGTYPE_DHPART2

#define MSGTYPE_DHPART2   0x05

◆ MSGTYPE_ERROR

#define MSGTYPE_ERROR   0x10

◆ MSGTYPE_ERRORACK

#define MSGTYPE_ERRORACK   0x11

◆ MSGTYPE_FRAGMENT

#define MSGTYPE_FRAGMENT   0xff

◆ MSGTYPE_GOCLEAR

#define MSGTYPE_GOCLEAR   0x12

◆ MSGTYPE_HELLO

#define MSGTYPE_HELLO   0x01

◆ MSGTYPE_HELLOACK

#define MSGTYPE_HELLOACK   0x02

◆ MSGTYPE_INVALID

#define MSGTYPE_INVALID   0x00

◆ MSGTYPE_PING

#define MSGTYPE_PING   0x16

◆ MSGTYPE_PINGACK

#define MSGTYPE_PINGACK   0x17

◆ MSGTYPE_RELAYACK

#define MSGTYPE_RELAYACK   0x15

◆ MSGTYPE_SASRELAY

#define MSGTYPE_SASRELAY   0x14

◆ ZRTP_FRAGMENTEDPACKET_HEADER_LENGTH

#define ZRTP_FRAGMENTEDPACKET_HEADER_LENGTH   20

◆ ZRTP_FRAGMENTEDPACKET_OVERHEAD

#define ZRTP_FRAGMENTEDPACKET_OVERHEAD   (ZRTP_FRAGMENTEDPACKET_HEADER_LENGTH + ZRTP_PACKET_CRC_LENGTH)

◆ ZRTP_KEMPART2_NONCE_SIZE

#define ZRTP_KEMPART2_NONCE_SIZE   16

◆ ZRTP_PACKET_CRC_LENGTH

#define ZRTP_PACKET_CRC_LENGTH   4

◆ ZRTP_PACKET_HEADER_LENGTH

#define ZRTP_PACKET_HEADER_LENGTH   12

◆ ZRTP_PACKET_OVERHEAD

#define ZRTP_PACKET_OVERHEAD   (ZRTP_PACKET_HEADER_LENGTH + ZRTP_PACKET_CRC_LENGTH)

Typedef Documentation

◆ bzrtpCommitMessage_t

Hello ACK Message rfc 5.3 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet.

Commit Message rfc 5.4 This message can be of 3 different types: DHM, PreShared and Multistream, some field of it may be used only by certain type of message It is generated by the initiator (see section 4.2 for commit contention)

◆ bzrtpConfirmMessage_t

Confirm Message rfc 5.7 Confirm1 and Confirm2 messages have the same structure Confirm1 is generated by the responder and Confirm2 by the initiator Part of the message is encrypted using the negotiated block cipher for media encryption. Keys ares zrtpkeyr for responder and zrtpkeyi for initiator.

◆ bzrtpDHPartMessage_t

DHPart Message rfc 5.5 and rfc 5.6 DHPart1 and DHPart2 message have the same structure DHPart1 is generated by the responder, and DHPart2 by the initiator.

◆ bzrtpGoClearMessage_t

Conf2 ACK Message rfc 5.8 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet.

Error Message rfc section 5.9 The Error message is sent to terminate an in-process ZRTP key agreement exchange due to an error. There is no need to define a structure for this packet as it contains length and message type which are stored in the bzrtpPacket_t structure and a 32 bits integer error code only

Error ACK Message rfc 5.10 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet

GoClear Message rfc 5.11 Support for the GoClear message is OPTIONAL in the protocol, and it is sent to switch from SRTP to RTP.

◆ bzrtpHelloMessage_t

Hello Message rfc 5.2.

Structure definition for all zrtp message type according to rfc section 5.2 to 5.16

◆ bzrtpPacket_t

Store all zrtpPacket informations according to type a specific structure type is mapped to the void * data pointer.

◆ bzrtpPingAckMessage_t

PingAck Message The Ping and PingACK messages are unrelated to the rest of the ZRTP protocol. No ZRTP endpoint is required to generate a Ping message, but every ZRTP endpoint MUST respond to a Ping message with a PingACK message.

◆ bzrtpPingMessage_t

Relay ACK Message rfc 5.14 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet.

Ping Message The Ping and PingACK messages are unrelated to the rest of the ZRTP protocol. No ZRTP endpoint is required to generate a Ping message, but every ZRTP endpoint MUST respond to a Ping message with a PingACK message.

◆ bzrtpSASRelayMessage_t

Clear ACK Message rfc 5.12 This message contains no data but only a length and message type which are stored in the bzrtpPacket_t structure There the no need to define a structure type for this packet.

SASRelay Message rfc 5.13 The SASrelay message is sent by a trusted MiTM, most often a PBX. It is not sent as a response to a packet, but is sent as a self-initiated packet by the trusted MiTM (Section 7.3). It can only be sent after the rest of the ZRTP key negotiations have completed, after the Confirm messages and their ACKs. It can only be sent after the trusted MiTM has finished key negotiations with the other party, because it is the other party's SAS that is being relayed. It is sent with retry logic until a RelayACK message (Section 5.14) is received or the retry schedule has been exhausted. Part of the message is encrypted using the negotiated block cipher for media encryption. Depending on whether the trusted MiTM had taken the role of the initiator or the responder during the ZRTP key negotiation, the SASrelay message is encrypted with zrtpkeyi or zrtpkeyr.

Function Documentation

◆ bzrtp_createZrtpPacket()

BZRTP_EXPORT bzrtpPacket_t * bzrtp_createZrtpPacket ( bzrtpContext_t zrtpContext,
bzrtpChannelContext_t zrtpChannelContext,
uint32_t  messageType,
int *  exitCode 
)

Create an empty packet and allocate the messageData according to requested packetType.

Parameters
[in]zrtpContextThe current ZRTP context, some data (H chain or others, may be needed to create messages)
[in]zrtpChannelContextThe channel context this packet is intended to
[in]messageTypeThe 32bit integer mapped to the message type to be created
[out]exitCode0 on success, error code otherwise
Returns
An empty packet initialised to get data for the requested paquet tyep. NULL on error

◆ bzrtp_freeZrtpPacket()

BZRTP_EXPORT void bzrtp_freeZrtpPacket ( bzrtpPacket_t zrtpPacket)

Deallocate zrtp Packet.

Parameters
[in]zrtpPacketThe packet to be freed

◆ bzrtp_packetBuild()

BZRTP_EXPORT int bzrtp_packetBuild ( bzrtpContext_t zrtpContext,
bzrtpChannelContext_t zrtpChannelContext,
bzrtpPacket_t zrtpPacket 
)

Create a ZRTP packet string from the ZRTP packet values present in the structure messageType, messageData and sourceIdentifier in zrtpPacket must have been correctly set before calling this function The packet is not ready to be sent at that stage, sequenceNumber and CRC must be set using bzrtp_packetSetSequenceNumber.

Parameters
[in]zrtpContextA zrtp context where to find H0-H3 to compute MAC requested by some paquets or encryption's key for commit/SASRelay packet
[in]zrtpChannelContextThe channel context this packet is intended to
[in,out]zrtpPacketThe zrtpPacket structure containing the message Data structure, output is stored in ->packetString
Returns
0 on success, error code otherwise

◆ bzrtp_packetCheck()

BZRTP_EXPORT bzrtpPacket_t * bzrtp_packetCheck ( uint8_t **  inputPtr,
uint16_t inputLength,
bzrtpChannelContext_t zrtpChannelContext,
int *  exitCode 
)

Parse a string which shall be a valid ZRTP packet Check validity and allocate the bzrtpPacket structure but do not parse the message except for type and length. messageData structure field is not allocated by this function (use then bzrtp_packetParse for that). The packet check and actual message parsing are split in two functions to avoid useless parsing when message is to be discarded as the check will give message type (in case of message repetition for example)

Parameters
[in/out]inputPtr The string buffer storing the complete ZRTP packet. Modified if we complete a fragmented packet
[in/out]inputLength Input length in bytes. Modified if we complete a fragmented packet
[in/out]zrtpChannelContext The channel context this packet is intended to(channel context and packet must match peer SSRC).
[out]exitCode0 on success, BZRTP_PARSER_INFO_PACKETFRAGMENT when a fragment of incomplete packet is received, error code otherwise
Returns
The create bzrtpPacket structure(to be freed using bzrtp_freeZrtpPacket). NULL on error

◆ bzrtp_packetParser()

BZRTP_EXPORT int bzrtp_packetParser ( bzrtpContext_t zrtpContext,
bzrtpChannelContext_t zrtpChannelContext,
const uint8_t input,
uint16_t  inputLength,
bzrtpPacket_t zrtpPacket 
)

Parse the packet to extract the message and allocate the matching message structure if needed.

Parameters
[in]zrtpContextThe current ZRTP context, some parameters(key agreement algorithm) may be needed to parse packet.
[in]zrtpChannelContextThe channel context this packet is intended to(channel context and packet must match peer SSRC).
[in]inputThe string buffer storing the complete ZRTP packet
[in]inputLengthInput length in bytes
[in]zrtpPacketThe zrtpPacket structure allocated by previous call to bzrtpPacketCheck
Returns
0 on sucess, error code otherwise

◆ bzrtp_packetSetSequenceNumber()

BZRTP_EXPORT int bzrtp_packetSetSequenceNumber ( bzrtpPacket_t zrtpPacket,
uint16_t  sequenceNumber 
)

Set the current sequence number of the packet in the packetString and sequenceNumber fields The CRC at the end of packetString is also computed.

param[in,out] zrtpPacket The zrtpPacket, the packetString must have been generated by a call to bzrtp_packetBuild on this packet param[in] sequenceNumber The sequence number to insert in the packetString

return 0 on succes, error code otherwise

Set the current sequence number of the packet in the packetString and sequenceNumber fields The CRC at the end of packetString is also computed.

param[in,out] zrtpPacket The zrtpPacket to modify, the packetString must have been generated by a call to bzrtp_packetBuild on this packet param[in] sequenceNumber The sequence number to insert in the packetString

return 0 on succes, error code otherwise