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 11 #ifndef __ZRTP_ENGINE_H__ 12 #define __ZRTP_ENGINE_H__ 13 14 #include "zrtp_config.h" 15 #include "zrtp_types.h" 16 #include "zrtp_crypto.h" 17 18 19 #if defined(__cplusplus) 20 extern "C" 21 { 22 #endif 23 24 /** 25 * @defgroup engine_dev ZRTP Engine related types and functions 26 * @ingroup zrtp_dev 27 * \{ 28 */ 29 30 #define ZRTP_IS_STREAM_DH(stream) \ 31 (stream->mode == ZRTP_STREAM_MODE_DH) 32 33 #define ZRTP_IS_STREAM_FAST(stream) \ 34 (stream->mode != ZRTP_STREAM_MODE_DH) 35 36 #define ZRTP_IS_STREAM_MULT(stream) \ 37 (stream->mode == ZRTP_STREAM_MODE_MULT) 38 39 #define ZRTP_IS_STREAM_PRESH(stream) \ 40 (stream->mode == ZRTP_STREAM_MODE_PRESHARED) 41 42 43 /** 44 * @brief Test Passive Rule N1 45 * A passive endpoint never sends a Commit message. Semi-active endpoint does 46 * not send a commit to a passive endpoint. 47 * Return 1 if the tast have been passed successfully and 0 in other case. 48 */ 49 #define ZRTP_PASSIVE1_TEST(stream) \ 50 ( (ZRTP_LICENSE_MODE_UNLIMITED == stream->zrtp->lic_mode) || \ 51 ((ZRTP_LICENSE_MODE_ACTIVE == stream->zrtp->lic_mode) && (!stream->messages.peer_hello.pasive)) ) 52 53 /** 54 * @brief Test Passive Rule N2 55 * A passive phone, if acting as a SIP initiator (meaning it initiated the call), 56 * rejects all commit packets from everyone. 57 * Return 1 if the tast have been passed successfully and 0 in other case 58 */ 59 #define ZRTP_PASSIVE2_TEST(stream) \ 60 ( !((ZRTP_LICENSE_MODE_PASSIVE == stream->zrtp->lic_mode) && \ 61 (stream->session->signaling_role == ZRTP_SIGNALING_ROLE_INITIATOR)) ) 62 63 /** 64 * @brief Test Passive Rule N3 65 * A passive phone rejects all commit messages from a PBX. 66 * Return 1 if the tast have been passed successfully and 0 in other case 67 */ 68 #define ZRTP_PASSIVE3_TEST(stream) \ 69 ( !(!stream->zrtp->is_mitm && stream->peer_mitm_flag && \ 70 (ZRTP_LICENSE_MODE_PASSIVE == stream->zrtp->lic_mode)) ) 71 72 73 /*===========================================================================*/ 74 /* PROTOCOL Logic */ 75 /*===========================================================================*/ 76 77 /** 78 * @brief Allocate ZRTP protocol structure 79 * Allocates and initializes all necessary data according to the protocol mode. 80 * Initializes required DH crypto context info and generates secret IDs. 81 * @param stream - stream context in which protocol should be allocated; 82 * @param is_initiator - defines protocol type (1 - initiator, 0 - responder). 83 * @exception SOFTWARE exceptions. 84 */ 85 zrtp_status_t _zrtp_protocol_init( zrtp_stream_t *stream, 86 uint8_t is_initiator, 87 zrtp_protocol_t **proto); 88 89 /** 90 * @brief Release protocol structure 91 * Stops all replay tasks, clears all crypto sources and SRTP engine, and 92 * releases memory. The protocol should be destroyed on: stream closing, or 93 * switching to CLEAR or ERROR states. 94 */ 95 void _zrtp_protocol_destroy(zrtp_protocol_t *proto); 96 97 /** 98 * @brief Encrypts RTP/RTCP media 99 * After switching to Secure, the protocol structure is able to encrypt 100 * media using the SRTP crypto-engine. 101 * @param self - self-pointer to protocol instance; 102 * @param packet - media packet for encryption; 103 * @param is_rtp - defines type of media for encryption; value equal to 1 104 * means RTP packet, 0 - RTCP. 105 * @return 106 * - zrtp_status_ok - if successfully encrypted; 107 * - one of zrtp_status_t errors otherwise. 108 */ 109 zrtp_status_t _zrtp_protocol_encrypt( zrtp_protocol_t *proto, 110 zrtp_rtp_info_t *packet, 111 uint8_t is_rtp); 112 113 /** 114 * @brief Decrypts RTP/RTCP media 115 * After switching to Secure, the protocol structure is able to decrypt 116 * media using the SRTP crypto-engine. 117 * @param self - self-pointer to protocol instance; 118 * @param packet - media packet for decryption; 119 * @param is_rtp - defines type of media for decryption; value equal to 1 120 * means RTP packet, 0 - RTCP. 121 * @return 122 * - zrtp_status_ok - if successfully decrypted; 123 * - one of zrtp_status_t errors otherwise. 124 */ 125 zrtp_status_t _zrtp_protocol_decrypt( zrtp_protocol_t *self, 126 zrtp_rtp_info_t *packet, 127 uint8_t is_rtp); 128 129 130 /*===========================================================================*/ 131 /* CRTPTO Utilities */ 132 /*===========================================================================*/ 133 134 /** 135 * ZRTP KDF function. 136 * KDF(KI, Label, Context, L) = HMAC(KI, i | Label | 0x00 | Context | L). See 137 * Section "4.5.1. The ZRTP Key Derivation Function" in ZRTP RFC for more info. 138 * @param stream - used to obtain negotiated HMAC function and other parameters; 139 * @param ki- secret key derivation key that is unknown to the wiretapper 140 * (for example, s0); 141 * @param label - string of nonzero octets that identifies the purpose for the 142 * derived keying material; 143 * @param context - includes ZIDi, ZIDr, and some optional nonce material; 144 * @param length - needed digest length. (The output of the KDF is truncated to 145 * the leftmost length bits); 146 * @param digest - destination buffer. 147 */ 148 zrtp_status_t _zrtp_kdf( zrtp_stream_t* stream, 149 zrtp_stringn_t* ki, 150 zrtp_stringn_t* label, 151 zrtp_stringn_t* context, 152 uint32_t length, 153 zrtp_stringn_t* digest); 154 155 /*! 156 * \brief Allocate shared secret structure 157 * This function allocates memory for a zrtp_shared_secret_t and initializes 158 * the secret value using a zrtp_fill_shared_secret() function call. Used in 159 * protocol allocating. 160 * \param session - ZRTP session for access to global data. 161 * \return 162 * - allocated secrets - on success; 163 * - NULL - if allocation fails. 164 */ 165 zrtp_shared_secret_t *_zrtp_alloc_shared_secret(zrtp_session_t* session); 166 167 /*! 168 * \brief Restores secrets from the cache 169 * Uploads retained secrets from the cache and initializes secret flags. If 170 * the secret has expired (is_expired flag is set), its value will be randomly 171 * regenerated. _zrtp_prepare_secrets() is called after the discovery phase on 172 * the setting up the very first stream. After secrets are uploaded the 173 * zrtp_secrets_t#_is_ready flag is enabled to prevent secrets from reinitialization 174 * on setting up the next stream. 175 * \param session - ZRTP session in which secrets should be restored. 176 * - zrtp_status_ok - if secrets were restored successfully; 177 * - one of zrtp_status_t errors in case of failure. 178 */ 179 zrtp_status_t _zrtp_prepare_secrets(zrtp_session_t* session); 180 181 /** 182 * @brief Validate confirm chmac message. 183 * In case of chmac failure it switches to Initiating Error state and generate 184 * ZRTP_EVENT_WRONG_MESSAGE_HMAC security event. 185 * @return 186 * -1 - in case of error and 0 - on success. 187 */ 188 int _zrtp_validate_message_hmac(zrtp_stream_t *stream, zrtp_msg_hdr_t* msg2check, char* hmackey); 189 190 /** 191 * @brief Computes preshared key using available secrets. 192 * hash(len(rs1) | rs1 | len(auxsecret) | auxsecret | len(pbxsecret) | pbxsecret) 193 * Result key stored in key variable, if key_id not NULL - hmac 194 * of the preshared_key will be stored. 195 * return 196 * - zrtp_status_ok on success and one of libzrtp errors in case of failure 197 */ 198 zrtp_status_t _zrtp_compute_preshared_key( zrtp_session_t *session, 199 zrtp_stringn_t* rs1, 200 zrtp_stringn_t* auxs, 201 zrtp_stringn_t* pbxs, 202 zrtp_stringn_t* key, 203 zrtp_stringn_t* key_id); 204 205 /** @brief Perform Key generation according to ZRTp RFC sec. 5.6 */ 206 zrtp_status_t _zrtp_set_public_value(zrtp_stream_t *stream, int is_initiator); 207 208 209 /*===========================================================================*/ 210 /* PROTOCOL Utilites */ 211 /*===========================================================================*/ 212 213 /*! 214 * \brief Check availability to start stream (DH or Preshared) 215 * The ZRTP specification says that only one DH stream can be run at a time between 216 * two ZRTP endpoints. So _zrtp_can_start_stream(DH) looks over all sessions 217 * between two ZIDs and if any other stream is running it denies the start of 218 * another DH stream in parallel. Although the ZRTP standard says that Preshared 219 * or Multistream stream can't be run in parallel with DH streams between two 220 * ZRTP endpoints. So _zrtp_can_start_stream(PRESH) looks over all sessions between 221 * two ZIDs and if any other DH stream is running it denies the start of 222 * Preshared/Multistream stream in parallel. All operations with sessions and 223 * streams are protected by mutexes. Call this function every time before starting 224 * "initiating secure" process. For internal use only. 225 * \sa "break the tie schemes" internal document. 226 * \param stream - ZRTP stream which going to be started; 227 * \param conc - in this variable _zrtp_can_start_stream() returns pointer to the 228 * concurrent DH stream if it's in progress. It's used in "breaking the tie" 229 * scheme. 230 * \param mode - stream mode. 231 * \return 232 * - 1 if stream can be started; 233 * - 0 - if stream can't be started and should wait for concurrent stream 234 * establishment. 235 */ 236 int _zrtp_can_start_stream( zrtp_stream_t* stream, 237 zrtp_stream_t** conc, 238 zrtp_stream_mode_t mode); 239 240 /** Return ZRTP Stream mode which should be used for current stream. */ 241 zrtp_stream_mode_t _zrtp_define_stream_mode(zrtp_stream_t* stream); 242 243 /*! 244 * \brief Chooses the best crypto component of the given type 245 * Selects the crypto component according to the local initiator's profile and 246 * the remote responder's Hello. 247 * \param profile - local profile; 248 * \param peer_hello - Hello packet, received from the remote peer; 249 * \param type - type of the crypto component to be chosen. 250 * \return: 251 * - identifier of the chosen component (according to type); 252 * - ZRTP_COMP_UNKN in case of error. 253 */ 254 uint8_t _zrtp_choose_best_comp( zrtp_profile_t* profile, 255 zrtp_packet_Hello_t* peer_hello, 256 zrtp_crypto_comp_t type); 257 258 /*! 259 * \brief Computes replay timeouts 260 * This function computes messages replays schedule. There are some recommended 261 * values by ZRTP specification, but in some network environments values may be 262 * sligh different 263 */ 264 uint32_t _zrtp_get_timeout(uint32_t curr_timeout, zrtp_msg_type_t msg); 265 266 267 /*! 268 * \brief Terminates retransmission task 269 * This function is a wrapper around zrtp_cancele_send_packet_later() which 270 * unsets the zrtp_retry_task_t#_is_enabled flag to prevent the scheduler from 271 * re-adding tasks after their termination. 272 */ 273 void _zrtp_cancel_send_packet_later( zrtp_stream_t* stream, 274 zrtp_msg_type_t type); 275 276 /*! 277 * \brief state switcher 278 * This function changes stream state to \c state, makes a backup of the previous 279 * state at zrtp_stream_t#_prev_state and prints debug information. 280 * \warning Don't change the stream state directly. Use this function. 281 * \param stream - ZRTP stream to be changed; 282 * \param state - new state. 283 */ 284 void _zrtp_change_state( zrtp_stream_t* stream, zrtp_state_t state); 285 286 287 /*===========================================================================*/ 288 /* Shared STATE-MACHINE Routine */ 289 /*===========================================================================*/ 290 291 // TODO: clean this up 292 zrtp_status_t _zrtp_machine_enter_pendingsecure(zrtp_stream_t* stream, zrtp_rtp_info_t* commit); 293 zrtp_status_t _zrtp_machine_enter_initiatingsecure(zrtp_stream_t* stream); 294 zrtp_status_t _zrtp_machine_enter_secure(zrtp_stream_t* stream); 295 zrtp_status_t _zrtp_machine_enter_pendingclear(zrtp_stream_t* stream); 296 zrtp_status_t _zrtp_machine_enter_initiatingerror( zrtp_stream_t *stream, 297 zrtp_protocol_error_t code, 298 uint8_t notif); 299 300 zrtp_status_t _zrtp_machine_create_confirm(zrtp_stream_t *stream, zrtp_packet_Confirm_t* confirm); 301 zrtp_status_t _zrtp_machine_process_confirm(zrtp_stream_t *stream, zrtp_packet_Confirm_t *confirm); 302 zrtp_status_t _zrtp_machine_process_goclear(zrtp_stream_t* stream, zrtp_rtp_info_t* packet); 303 304 zrtp_status_t _zrtp_machine_start_initiating_secure(zrtp_stream_t *stream); 305 zrtp_statemachine_type_t _zrtp_machine_preparse_commit(zrtp_stream_t *stream, zrtp_rtp_info_t* packet); 306 307 308 /*===========================================================================*/ 309 /* PARSERS */ 310 /*===========================================================================*/ 311 312 /*! 313 * \brief Prepare RTP/ZRTP media packet for the further processing. 314 * This function defines the packet type, parses SSRC and makes the sequence 315 * number implicit. If it is a ZRTP message, packet length correctness and CRC 316 * are checked as well. 317 * \param stream - ZRTP stream associated with this packet; 318 * \param packet - packet for preparing; 319 * \param length - packet length; 320 * \param info - resulting packet structure; 321 * \param is_input - 1 - assumes incoming and 0 - outgoing packet direction. 322 */ 323 zrtp_status_t _zrtp_packet_preparse( zrtp_stream_t* stream, 324 char* packet, 325 uint32_t *length, 326 zrtp_rtp_info_t* info, 327 uint8_t is_input); 328 329 /*! 330 * \brief Fills ZRTP message header and computes messages HMAC 331 * _zrtp_packet_fill_msg_hdr() prepares a ZRTP message header for sending. It calculates 332 * the total message length in 4-byte words and fills the message type block. 333 * \param stream - stream within in the operation will be performed 334 * \param type - ZRTP message type; 335 * \param body_length - message body length (without header); 336 * \param hdr - message ZRTP header 337 * \return 338 * - zrtp_status_ok - if success; 339 * - zrtp_status_bad_param - if message \c type is unknown. 340 */ 341 zrtp_status_t _zrtp_packet_fill_msg_hdr( zrtp_stream_t *stream, 342 zrtp_msg_type_t type, 343 uint16_t body_length, 344 zrtp_msg_hdr_t *hdr); 345 346 /** 347 * @brief Sends ZRTP message onto the network 348 * _zrtp_packet_send_message constructs a ZRTP header and prepares packet for sending, 349 * computes CRC and injects the packet into the network using the interface 350 * function zrtp_send_rtp(). 351 * @param ctx - ZRTP stream context; 352 * @param type - packet type to construct primitive ZRTP messages; 353 * @param message - ZRTP message for sending. 354 * @return 355 * - 0 - if sent successfully; 356 * - -1 - if error. 357 */ 358 int _zrtp_packet_send_message( zrtp_stream_t *stream, 359 zrtp_msg_type_t type, 360 const void *message); 361 362 /** @brief Returns ZRTP message type by symbolic name in header. */ 363 zrtp_msg_type_t _zrtp_packet_get_type(ZRTP_UNALIGNED(zrtp_rtp_hdr_t)*hdr, uint32_t length); 364 365 /** 366 * @brief Insert CRC32 to ZRTP packets 367 * This function computes the 32 bit ZRTP packet checksum according to RFC 3309. 368 * As specified at ZRTP RFC, CRC32 is appended to the end of the extension for every ZRTP packet. 369 * @param packet - zrtp packet wrapper structure. 370 */ 371 void _zrtp_packet_insert_crc(char* packet, uint32_t length); 372 373 /** 374 * @brief Validate ZRTP packet CRC 375 * @return 376 * - 0 if correct CRC; 377 * - -1 if CRC validation failed. 378 */ 379 int8_t _zrtp_packet_validate_crc(const char* packet, uint32_t length); 380 381 /* \} */ 382 383 #if defined(__cplusplus) 384 } 385 #endif 386 387 #endif /* __ZRTP_ENGINE_H__ */ 388