1 /* 2 * libZRTP SDK library, implements the ZRTP secure VoIP protocol. 3 * Copyright (c) 2006-2009 Philip R. Zimmermann. All rights reserved. 4 * Contact: http://philzimmermann.com 5 * For licensing and other legal details, see the file zrtp_legal.c. 6 * 7 * Viktor Krykun <v.krikun at zfoneproject.com> 8 */ 9 10 #ifndef __ZRTP_PROTOCOL_H__ 11 #define __ZRTP_PROTOCOL_H__ 12 13 #include "zrtp_config.h" 14 #include "zrtp_types.h" 15 #include "zrtp_error.h" 16 17 #if defined(_MSC_VER) 18 #pragma warning(disable:4214) 19 #endif 20 21 /*! 22 * \defgroup dev_protocol Protocol related data types and definitions 23 * \ingroup zrtp_dev 24 * \{ 25 */ 26 27 /*! ZRTP Protocol version, retransmitted in HELLO packets */ 28 #define ZRTP_PROTOCOL_VERSION "1.10" 29 #define ZRTP_PROTOCOL_VERSION_VALUE 110 30 31 #define ZRTP_ZFONE_PROTOCOL_VERSION "0.10" 32 #define ZRTP_ZFONE_PROTOCOL_VERSION_VALUE 10 33 34 /* 35 * Protocol constants and definitions. All these values are defined by the ZRTP 36 * specification <A HREF="http://zfoneproject.com/zrtp_ietf.html">"ZRTP Internet Draft"</A>. 37 * Don't change them! 38 */ 39 #define ZRTP_S384 "S384" 40 #define ZRTP_S256 "S256" 41 #define ZRTP_S160 "S160" 42 #define ZRTP_AES1 "AES1" 43 #define ZRTP_AES3 "AES3" 44 #define ZRTP_HS32 "HS32" 45 #define ZRTP_HS80 "HS80" 46 #define ZRTP_DH2K "DH2k" 47 #define ZRTP_DH3K "DH3k" 48 #define ZRTP_EC256P "EC25" 49 #define ZRTP_EC384P "EC38" 50 #define ZRTP_EC521P "EC52" 51 #define ZRTP_MULT "Mult" 52 #define ZRTP_PRESHARED "Prsh" 53 #define ZRTP_B32 "B32 " 54 #define ZRTP_B256 "B256" 55 56 #define ZRTP_ROLE_INITIATOR "Initiator" 57 #define ZRTP_ROLE_RESPONDER "Responder" 58 #define ZRTP_INITIATOR_HMAKKEY_STR "Initiator HMAC key" 59 #define ZRTP_RESPONDER_HMAKKEY_STR "Responder HMAC key" 60 #define ZRTP_GOCLEAR_STR "GoClear" 61 #define ZRTP_INITIATOR_KEY_STR "Initiator SRTP master key" 62 #define ZRTP_INITIATOR_SALT_STR "Initiator SRTP master salt" 63 #define ZRTP_RESPONDER_KEY_STR "Responder SRTP master key" 64 #define ZRTP_RESPONDER_SALT_STR "Responder SRTP master salt" 65 #define ZRTP_SKEY_STR "ZRTP Session Key" 66 #define ZRTP_SAS_STR "SAS" 67 #define ZRTP_RS_STR "retained secret" 68 #define ZRTP_INITIATOR_ZRTPKEY_STR "Initiator ZRTP key" 69 #define ZRTP_RESPONDER_ZRTPKEY_STR "Responder ZRTP key" 70 #define ZRTP_CLEAR_HMAC_STR "GoClear" 71 #define ZRTP_KDF_STR "ZRTP-HMAC-KDF" 72 #define ZRTP_SESS_STR "ZRTP Session Key" 73 #define ZRTP_MULTI_STR "ZRTP MSK" 74 #define ZRTP_PRESH_STR "ZRTP PSK" 75 #define ZRTP_TRUSTMITMKEY_STR "Trusted MiTM key" 76 #define ZRTP_COMMIT_HV_KEY_STR "Prsh" 77 78 #define ZRTP_CACHE_DEFAULT_TTL (30*24*60*60) 79 80 /** ZRTP Message magic Cookie */ 81 #define ZRTP_PACKETS_MAGIC 0x5a525450L 82 /** Defines ZRTP extension type for RTP protocol */ 83 #define ZRTP_MESSAGE_MAGIC 0x505a 84 85 86 /** 87 * @brief Retransmission timer T1 in milliseconds 88 * T1 is used for the retransmission of Hello messages. The HELLO timeout is 89 * doubled each time a resend occurs. The gain (max timeout value) is limited 90 * by @ref ZRTP_T1_CAPPING. After reaching \c ZRTP_T1_CAPPING, the state machine 91 * keeps resending HELLO packets until the resend count is less than \ref 92 * ZRTP_T1_MAX_COUNT 93 * @sa ZRTP_T1_MAX_COUNT ZRTP_T1_CAPPING 94 */ 95 96 #define ZRTP_T1 50 97 98 /*! 99 * \brief Max resends count value for T1 timer 100 * This is the threshold value for HELLO replays. See \ref ZRTP_T1 ZRTP_T1 for 101 * details. If the resend count exceeds the value of ZRTP_T1_MAX_COUNT then 102 * the state machine calls _zrtp_machine_enter_initiatingerror() with error code \ref 103 * zrtp_protocol_error_t#zrtp_error_timeout and ZRTP session establishment is 104 * failed. 105 */ 106 #define ZRTP_T1_MAX_COUNT 20 107 108 /*! 109 * \brief Max resends count value for T1 timer for cases when local side have 110 * received remote Hello. Libzrtp uses this extended number of retries when there 111 * is an evidence, that remote side supports ZRTP protocol (remote Hello received). 112 * This approach allows to eliminate problem when ZRTP state-machine switches to 113 * NO_ZRTP state while remote side is computing his initial DH value. (especially 114 * important for slow devices) 115 */ 116 #define ZRTP_T1_MAX_COUNT_EXT 60 117 118 /*! Hello retries counter for ZRTP_EVENT_NO_ZRTP_QUICK event */ 119 #define ZRTP_NO_ZRTP_FAST_COUNT 5 120 121 /*! 122 * \brief Max T1 timeout 123 * ZRTP_T1_MAX_COUNT is the threshold for the growth of the timeout value of 124 * HELLO resends. See \ref ZRTP_T1 for details. 125 */ 126 #define ZRTP_T1_CAPPING 200 127 128 /*! 129 * \brief ZRTP stream initiation period in milliseconds 130 * If for some reason the initiation of a secure ZRTP stream can't be performed 131 * at a given time (there are no retained secrets for the session, or the 132 * concurrent stream is being processed in "DH" mode) the next attempt will be 133 * done in ZRTP_PROCESS_T1 milliseconds. If at the end of ZRTP_PROCESS_T1_MAX_COUNT 134 * attempts the necessary conditions haven't been reached, the task is canceled. 135 * The mechanism of delayed execution is the same as the mechanism of delayed 136 * packet sending. \sa ZRTP_PROCESS_T1_MAX_COUNT 137 */ 138 #define ZRTP_PROCESS_T1 50 139 140 /*! 141 * \brief Max recall count value 142 * This is the threshold value for ZRTP stream initiation tries. See \ref 143 * ZRTP_PROCESS_T1 for details. 144 */ 145 #define ZRTP_PROCESS_T1_MAX_COUNT 20000 146 147 /*! 148 * \brief Retransmission timer T2 in milliseconds 149 * T2 is used for the retransmission of all ZRTP messages except HELLO. The 150 * timeout value is doubled after every retransmission. The gain (max timeout's 151 * value) is limited by \ref ZRTP_T2_CAPPING. \ref ZRTP_T2_MAX_COUNT is the limit 152 * for packets resent as for \ref ZRTP_T1. 153 */ 154 #define ZRTP_T2 150 155 156 /*! 157 * \brief Max retransmissions for non-HELLO packets 158 * ZRTP_T2_MAX_COUNT limits number of resends for the non-HELLO/GOCLEAR packets. 159 * When exceeded, call_is_on_error() is called and the error code is set to 160 * \ref zrtp_protocol_error_t#zrtp_error_timeout 161 */ 162 #define ZRTP_T2_MAX_COUNT 10 163 164 165 /*! 166 * \brief Max timeout value for protocol packets (except HELLO and GOCLEAR) 167 * The resend timeout value grows until it reaches ZRTP_T2_CAPPING. After that 168 * the state machine keeps resending until the resend count hits the limit of 169 * \ref ZRTP_T2_MAX_COUNT 170 */ 171 #define ZRTP_T2_CAPPING 1200 172 173 /*! 174 * \brief Retransmission timer for GoClear resending in milliseconds. 175 * To prevent pinholes from closing or NAT bindings from expiring, the GoClear 176 * message should be resent every N seconds while waiting for confirmation from 177 * the user. GoClear replays are endless. 178 */ 179 #define ZRTP_T3 300 180 181 /*! 182 * \brief Set of timeouts for Error packet replays. 183 * The meaning of these fields are the same as in the T1 group but for 184 * Error/ErrorAck packets. The values of these options are not strongly 185 * defined by the draft. We use empirical values. 186 */ 187 #define ZRTP_ET 150 188 #define ZRTP_ETI_MAX_COUNT 10 189 #define ZRTP_ETR_MAX_COUNT 3 190 191 /* ZRTP Retries schedule for slow CSD channel */ 192 #define ZRTP_CSD_T4PROC 2000 193 194 #define ZRTP_CSD_T1 400 + ZRTP_CSD_T4PROC 195 #define ZRTP_CSD_T2 900 + ZRTP_CSD_T4PROC 196 #define ZRTP_CSD_T3 900 + ZRTP_CSD_T4PROC 197 #define ZRTP_CSD_T4 200 + ZRTP_CSD_T4PROC 198 #define ZRTP_CSD_ET 200 + ZRTP_CSD_T4PROC 199 200 201 /*! Defines the max component number which can be used in a HELLO agreement */ 202 #define ZRTP_MAX_COMP_COUNT 7 203 204 205 /* 206 * Some definitions of protocol structure sizes. To simplify sizeof() constructions 207 */ 208 #define ZRTP_VERSION_SIZE 4 209 #define ZRTP_ZID_SIZE 12 210 #define ZRTP_CLIENTID_SIZE 16 211 #define ZRTP_COMP_TYPE_SIZE 4 212 #define ZRTP_RS_SIZE 32 213 #define ZRTP_RSID_SIZE 8 214 #define ZRTP_PACKET_TYPE_SIZE 8 215 #define RTP_V2_HDR_SIZE 12 216 #define RTP_HDR_SIZE RTP_V2_HDR_SIZE 217 #define RTCP_HDR_SIZE 8 218 #define ZRTP_HV_SIZE 32 219 #define ZRTP_HV_NONCE_SIZE 16 220 #define ZRTP_HV_KEY_SIZE 8 221 #define ZRTP_HMAC_SIZE 8 222 #define ZRTP_CFBIV_SIZE 16 223 #define ZRTP_MITM_SAS_SIZE 4 224 #define ZRTP_MESSAGE_HASH_SIZE 32 225 #define ZRTP_HASH_SIZE 32 226 227 /* Without header and HMAC: <verison> + <client ID> + <hash> + <ZID> + <components length> */ 228 #define ZRTP_HELLO_STATIC_SIZE (ZRTP_VERSION_SIZE + ZRTP_CLIENTID_SIZE + 32 + ZRTP_ZID_SIZE + 4) 229 230 /* Without header and HMAC: <hash> + <secrets IDs> */ 231 #define ZRTP_DH_STATIC_SIZE (32 + 4*8) 232 233 /* Without header and HMAC: <hash> + <ZID> + <components definitions> */ 234 #define ZRTP_COMMIT_STATIC_SIZE (32 + ZRTP_ZID_SIZE + 4*5) 235 236 /* <RTP> + <ext. header> + <ZRTP message type> + CRC32 */ 237 #define ZRTP_MIN_PACKET_LENGTH (RTP_HDR_SIZE + 4 + 8 + 4) 238 239 240 #if ( ZRTP_PLATFORM != ZP_SYMBIAN ) 241 #pragma pack(push,1) 242 #endif 243 244 245 246 /** Base ZRTP messages header */ 247 typedef struct zrtp_msg_hdr 248 { 249 /** ZRTP magic cookie */ 250 uint16_t magic; 251 252 /** ZRTP message length in 4-byte words */ 253 uint16_t length; 254 255 /** ZRTP message type */ 256 zrtp_uchar8_t type; 257 } zrtp_msg_hdr_t; 258 259 /*! 260 * \brief ZRTP HELLO packet data 261 * Contains fields needed to construct/store a ZRTP HELLO packet 262 */ 263 typedef struct zrtp_packet_Hello 264 { 265 zrtp_msg_hdr_t hdr; 266 /** ZRTP protocol version */ 267 zrtp_uchar4_t version; 268 269 /** ZRTP client ID */ 270 zrtp_uchar16_t cliend_id; 271 272 /*!< Hash to prevent DOS attacks */ 273 zrtp_uchar32_t hash; 274 275 /** Endpoint unique ID */ 276 zrtp_uchar12_t zid; 277 #if ZRTP_BYTE_ORDER == ZBO_LITTLE_ENDIAN 278 uint8_t padding2:4; 279 280 /** Passive flag */ 281 uint8_t pasive:1; 282 283 /** M flag */ 284 uint8_t mitmflag:1; 285 286 /** Signature support flag */ 287 uint8_t sigflag:1; 288 289 uint8_t uflag:1; 290 291 /** Hash scheme count */ 292 uint8_t hc:4; 293 uint8_t padding3:4; 294 295 /** Cipher count */ 296 uint8_t ac:4; 297 298 /** Hash scheme count */ 299 uint8_t cc:4; 300 301 /** SAS scheme count */ 302 uint8_t sc:4; 303 304 /** PK Type count */ 305 uint8_t kc:4; 306 #elif ZRTP_BYTE_ORDER == ZBO_BIG_ENDIAN 307 uint8_t uflag:1; 308 uint8_t sigflag:1; 309 uint8_t mitmflag:1; 310 uint8_t pasive:1; 311 uint8_t padding2:4; 312 uint8_t padding3:4; 313 uint8_t hc:4; 314 uint8_t cc:4; 315 uint8_t ac:4; 316 uint8_t kc:4; 317 uint8_t sc:4; 318 #endif 319 320 zrtp_uchar4_t comp[ZRTP_MAX_COMP_COUNT*5]; 321 zrtp_uchar8_t hmac; 322 } zrtp_packet_Hello_t; 323 324 325 /** 326 * @brief ZRTP COMMIT packet data 327 * Contains information to build/store a ZRTP commit packet. 328 */ 329 typedef struct zrtp_packet_Commit 330 { 331 zrtp_msg_hdr_t hdr; 332 333 /** Hash to prevent DOS attacks */ 334 zrtp_uchar32_t hash; 335 336 /** ZRTP endpoint unique ID */ 337 zrtp_uchar12_t zid; 338 339 /** hash calculations schemes selected by ZRTP endpoint */ 340 zrtp_uchar4_t hash_type; 341 342 /** cipher types selected by ZRTP endpoint */ 343 zrtp_uchar4_t cipher_type; 344 345 /** SRTP auth tag lengths selected by ZRTP endpoint */ 346 zrtp_uchar4_t auth_tag_length; 347 348 /** session key exchange schemes selected by endpoints */ 349 zrtp_uchar4_t public_key_type; 350 351 /** SAS calculation schemes selected by endpoint*/ 352 zrtp_uchar4_t sas_type; 353 /** hvi. See <A HREF="http://zfoneproject.com/zrtp_ietf.html">"ZRTP Internet Draft"</A> */ 354 zrtp_uchar32_t hv; 355 zrtp_uchar8_t hmac; 356 } zrtp_packet_Commit_t; 357 358 359 /** 360 * @brief ZRTP DH1/2 packets data 361 * Contains fields needed to constructing/storing ZRTP DH1/2 packet. 362 */ 363 typedef struct zrtp_packet_DHPart 364 { 365 zrtp_msg_hdr_t hdr; 366 367 /** Hash to prevent DOS attacks */ 368 zrtp_uchar32_t hash; 369 370 /** hash of retained shared secret 1 */ 371 zrtp_uchar8_t rs1ID; 372 373 /** hash of retained shared secret 2 */ 374 zrtp_uchar8_t rs2ID; 375 376 /** hash of user-defined secret */ 377 zrtp_uchar8_t auxsID; 378 379 /** hash of PBX secret */ 380 zrtp_uchar8_t pbxsID; 381 382 /** pvi/pvr or nonce field depends on stream mode */ 383 zrtp_uchar1024_t pv; 384 zrtp_uchar8_t hmac; 385 } zrtp_packet_DHPart_t; 386 387 388 /** 389 * @brief ZRTP Confirm1/Confirm2 packets data 390 */ 391 typedef struct zrtp_packet_Confirm 392 { 393 zrtp_msg_hdr_t hdr; 394 395 /** HMAC of preceding parameters */ 396 zrtp_uchar8_t hmac; 397 398 /** The CFB Initialization Vector is a 128 bit random nonce */ 399 zrtp_uchar16_t iv; 400 401 /** Hash to prevent DOS attacks */ 402 zrtp_uchar32_t hash; 403 404 /** Unused (Set to zero and ignored) */ 405 uint8_t pad[2]; 406 407 /** Length of optional signature field */ 408 uint8_t sig_length; 409 410 /** boolean flags for allowclear, SAS verified and disclose */ 411 uint8_t flags; 412 413 /** how long (seconds) to cache shared secret */ 414 uint32_t expired_interval; 415 } zrtp_packet_Confirm_t; 416 417 418 /** 419 * @brief ZRTP Confirm1/Confirm2 packets data 420 */ 421 typedef struct zrtp_packet_SASRelay 422 { 423 zrtp_msg_hdr_t hdr; 424 425 /** HMAC of preceding parameters */ 426 zrtp_uchar8_t hmac; 427 428 /** The CFB Initialization Vector is a 128 bit random nonce */ 429 zrtp_uchar16_t iv; 430 431 /** Unused (Set to zero and ignored) */ 432 uint8_t pad[2]; 433 434 /** Length of optionas signature field */ 435 uint8_t sig_length; 436 437 /** boolean flags for allowclear, SAS verified and disclose */ 438 uint8_t flags; 439 440 /** Rendering scheme of relayed sasvalue (for trusted MitMs) */ 441 zrtp_uchar4_t sas_scheme; 442 443 /** Trusted MITM relayed sashash */ 444 uint8_t sashash[32]; 445 } zrtp_packet_SASRelay_t; 446 447 448 /** 449 * @brief GoClear packet structure according to ZRTP specification 450 */ 451 typedef struct zrtp_packet_GoClear 452 { 453 zrtp_msg_hdr_t hdr; 454 455 /** Clear HMAC to protect SRTP session from accidental termination */ 456 zrtp_uchar8_t clear_hmac; 457 } zrtp_packet_GoClear_t; 458 459 460 /** 461 * @brief Error packet structure in accordance with ZRTP specification 462 */ 463 typedef struct zrtp_packet_Error 464 { 465 zrtp_msg_hdr_t hdr; 466 467 /** ZRTP error code defined by draft and \ref zrtp_protocol_error_t */ 468 uint32_t code; 469 } zrtp_packet_Error_t; 470 471 /** ZFone Ping Message. Similar to ZRTP protocol packet format */ 472 typedef struct 473 { 474 zrtp_msg_hdr_t hdr; 475 zrtp_uchar4_t version; /** Zfone discovery protocol version */ 476 zrtp_uchar8_t endpointhash; /** Zfone endpoint unique identifier */ 477 } zrtp_packet_zfoneping_t; 478 479 /** ZFone Ping MessageAck. Similar to ZRTP protocol packet format */ 480 typedef struct 481 { 482 zrtp_msg_hdr_t hdr; 483 zrtp_uchar4_t version; /** Zfone discovery protocol version */ 484 zrtp_uchar8_t endpointhash; /** Zfone endpoint unique identifier */ 485 zrtp_uchar8_t peerendpointhash; /** EndpointHash copied from Ping message */ 486 uint32_t peerssrc; 487 } zrtp_packet_zfonepingack_t; 488 489 /*! \} */ 490 491 #if ( ZRTP_PLATFORM != ZP_SYMBIAN ) 492 #pragma pack(pop) 493 #endif 494 495 #endif /*__ZRTP_PROTOCOL_H__*/ 496