libzrtp  1.2.0
ZRTP VoIP security
zrtp.h
Go to the documentation of this file.
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 
15 #ifndef __ZRTP_H__
16 #define __ZRTP_H__
17 
18 #include "zrtp_config.h"
19 #include "zrtp_base.h"
20 #include "zrtp_error.h"
21 #include "zrtp_types.h"
22 #include "zrtp_protocol.h"
23 #include "zrtp_engine.h"
24 #include "zrtp_crypto.h"
25 #include "zrtp_iface.h"
26 #include "zrtp_iface_system.h"
27 #include "zrtp_iface_scheduler.h"
28 #include "zrtp_list.h"
29 #include "zrtp_legal.h"
30 #include "zrtp_log.h"
31 #include "zrtp_srtp.h"
32 #include "zrtp_srtp_builtin.h"
33 #include "zrtp_string.h"
34 #include "zrtp_pbx.h"
35 #include "zrtp_legal.h"
36 #include "zrtp_version.h"
37 #include "zrtp_cache.h"
38 #include "zrtp_cache_file.h"
39 #if (defined(ZRTP_ENABLE_EC) && (ZRTP_ENABLE_EC == 1))
40 #include "zrtp_ec.h"
41 #endif
42 
43 #if defined ZRTP_HAVE_SQLITE
44 #include "zrtp_cache_db.h"
45 #endif
46 
47 
71 /*======================================================================*/
72 /* Public ZRTP libzrtp datatypes */
73 /*======================================================================*/
74 
75 
90 #define ZRTP_SIGN_ZRTP_HASH_LENGTH (ZRTP_MESSAGE_HASH_SIZE*2)
91 
116 {
124 
133 {
140  ZRTP_SIGNALING_ROLE_COUNT
142 
143 
145 typedef unsigned char zrtp_zid_t[12];
146 
148 typedef char zrtp_client_id_t[16];
149 
155 typedef struct zrtp_config_t
156 {
159 
162 
165 
167  uint8_t is_mitm;
168 
171 
173  zrtp_cache_type_t cache_type;
174 
176  zrtp_cache_file_config_t cache_file_cfg;
177 #if defined ZRTP_HAVE_SQLITE
178 
179  zrtp_cache_db_config_t cache_db_cfg;
180 #endif
181 } zrtp_config_t;
182 
193 {
195  zrtp_id_t id;
196 
198  zrtp_session_t* session;
199 
202 
204  zrtp_mitm_mode_t mitm_mode;
205 
208 
215 
222  uint8_t peer_passive;
223 
230  uint8_t res_allowclear;
231 
239  uint8_t peer_disclose;
240 
247  uint8_t peer_mitm;
248 };
249 
259 {
261  zrtp_id_t id;
262 
270 
278 
281 
284 
291  uint8_t sas_is_ready;
292 
295 
303 
306 
316  uint32_t cached_flags;
317 
328  uint32_t matches_flags;
329 
339  uint32_t wrongs_flags;
340 
351  uint32_t sas_is_verified;
352 
354  uint8_t sas_is_base256;
355 
363  uint32_t secrets_ttl;
364 
367 
370 
373 
376 
379 };
380 
381 /* \} */
382 
383 
384 /*======================================================================*/
385 /* libzrtp Public API: Streams management */
386 /*======================================================================*/
387 
388 
389 #if defined(__cplusplus)
390 extern "C"
391 {
392 #endif
393 
410 void zrtp_config_defaults(zrtp_config_t* config);
411 
427 zrtp_status_t zrtp_init(zrtp_config_t* config, zrtp_global_t** zrtp);
428 
442 zrtp_status_t zrtp_down(zrtp_global_t* zrtp);
443 
444 /* \} */
445 
477 zrtp_status_t zrtp_session_init( zrtp_global_t* zrtp,
478  zrtp_profile_t* profile,
480  zrtp_session_t **session);
490 void zrtp_session_down(zrtp_session_t *session);
491 
492 
505 zrtp_status_t zrtp_session_get(zrtp_session_t *session, zrtp_session_info_t *info);
506 
513 void zrtp_session_set_userdata(zrtp_session_t *session, void* udata);
514 
523 void* zrtp_session_get_userdata(zrtp_session_t *session);
524 
541 zrtp_status_t zrtp_stream_attach(zrtp_session_t *session, zrtp_stream_t** stream);
542 
565 zrtp_status_t zrtp_stream_start(zrtp_stream_t* stream,
566  uint32_t ssrc);
567 
586 zrtp_status_t zrtp_stream_stop(zrtp_stream_t* stream);
587 
607 zrtp_status_t zrtp_stream_clear(zrtp_stream_t *stream);
608 
628 zrtp_status_t zrtp_stream_secure(zrtp_stream_t *stream);
629 
642 zrtp_status_t zrtp_stream_get(zrtp_stream_t *stream, zrtp_stream_info_t *info);
643 
650 void zrtp_stream_set_userdata(zrtp_stream_t *stream, void* udata);
651 
659 void* zrtp_stream_get_userdata(const zrtp_stream_t *stream);
660 
661 /* \} */
662 
663 /*======================================================================*/
664 /* libzrtp Public API: Encryption */
665 /*======================================================================*/
666 
700 zrtp_status_t zrtp_process_rtp( zrtp_stream_t *stream,
701  char* packet,
702  unsigned int* length);
703 
732 zrtp_status_t zrtp_process_srtp( zrtp_stream_t *stream,
733  char* packet,
734  unsigned int* length);
735 
756 zrtp_status_t zrtp_process_rtcp( zrtp_stream_t *stream,
757  char* packet,
758  unsigned int* length);
759 
780 zrtp_status_t zrtp_process_srtcp( zrtp_stream_t *stream,
781  char* packet,
782  unsigned int* length);
783 
784 /* \} */
785 
813 zrtp_status_t zrtp_signaling_hash_set( zrtp_stream_t* stream,
814  const char *hash_buff,
815  uint32_t hash_buff_length);
816 
835 zrtp_status_t zrtp_signaling_hash_get(zrtp_stream_t* stream,
836  char* hash_buff,
837  uint32_t hash_buff_length);
838 
856 zrtp_status_t zrtp_verified_set( zrtp_global_t *zrtp,
857  zrtp_string16_t *zid1,
858  zrtp_string16_t *zid2,
859  uint8_t verified);
860 
877 zrtp_status_t zrtp_profile_check(const zrtp_profile_t* profile, zrtp_global_t* zrtp);
878 
900 void zrtp_profile_defaults(zrtp_profile_t* profile, zrtp_global_t* zrtp);
901 
915 int zrtp_profile_find(const zrtp_profile_t* profile, zrtp_crypto_comp_t type, uint8_t id);
916 
917 /* \} */
918 
944 int zrtp_entropy_add(zrtp_global_t* zrtp, const unsigned char *buffer, uint32_t length);
945 
961 int zrtp_randstr(zrtp_global_t* zrtp, unsigned char *buffer, uint32_t length);
962 
963 int zrtp_randstr2(unsigned char *buffer, uint32_t length);
964 
965 /* \} */
966 
967 #if defined(__cplusplus)
968 }
969 #endif
970 
971 #endif /* __ZRTP_H__ */
void zrtp_session_set_userdata(zrtp_session_t *session, void *udata)
Allow user to associate some data with current zrtp session.
zrtp_status_t
libzrtp functions statuses.
Definition: zrtp_error.h:72
Signaling Initiator.
Definition: zrtp.h:137
zrtp_status_t zrtp_stream_secure(zrtp_stream_t *stream)
Initiating a secure connection setup.
zrtp_status_t zrtp_process_srtcp(zrtp_stream_t *stream, char *packet, unsigned int *length)
Processing incoming RTCP packets.
zrtp_string32_t hash_name
Hash crypto component name used in ZRTP calculations.
Definition: zrtp.h:366
zrtp_session_t * session
Pointer to the parent zrtp session.
Definition: zrtp.h:198
zrtp_status_t zrtp_process_srtp(zrtp_stream_t *stream, char *packet, unsigned int *length)
Processing incoming RTP packets.
zrtp_status_t zrtp_stream_clear(zrtp_stream_t *stream)
Initiating an interruption of the secure connection.
zrtp_status_t zrtp_down(zrtp_global_t *zrtp)
Shutting down the library.
ZRTP global configuration options.
Definition: zrtp.h:155
Will initiate ZRTP exchange, but only to non-Passive ZRTP partners.
Definition: zrtp.h:120
Definition: zrtp_string.h:52
zrtp_zid_t zid
local endpoint ZID
Definition: zrtp.h:158
zrtp_status_t zrtp_process_rtp(zrtp_stream_t *stream, char *packet, unsigned int *length)
Processing outgoing RTP packets.
uint32_t secrets_ttl
actual lifetime of the secrets
Definition: zrtp.h:363
zrtp_id_t id
Stream unique identifier for debug purposes.
Definition: zrtp.h:195
Unknown Signaling role, should be used when the app can't determine the role.
Definition: zrtp.h:135
uint32_t matches_flags
Bit-map to summarize shared secrets "Matched" flags.
Definition: zrtp.h:328
zrtp_status_t zrtp_signaling_hash_get(zrtp_stream_t *stream, char *hash_buff, uint32_t hash_buff_length)
Returns the hash of the Hello message to be transferred in signaling.
zrtp_status_t zrtp_process_rtcp(zrtp_stream_t *stream, char *packet, unsigned int *length)
Processing outgoing RTCP packets.
zrtp_status_t zrtp_stream_stop(zrtp_stream_t *stream)
ZRTP protocol stopping.
zrtp_string16_t sas1
First Short Authentication String.
Definition: zrtp.h:294
struct zrtp_config_t zrtp_config_t
ZRTP global configuration options.
zrtp_string16_t peer_zid
Remote ZID.
Definition: zrtp.h:277
uint8_t peer_passive
Remote passive flag.
Definition: zrtp.h:222
void * zrtp_session_get_userdata(zrtp_session_t *session)
Return user data associated with the zrtp session.
zrtp_state_t state
Reflects current state of ZRTP protocol.
Definition: zrtp.h:207
zrtp_signaling_role_t
Enumeration to define Signaling initiator/responder roles.
Definition: zrtp.h:132
zrtp_string32_t sas_name
SAS scheme crypto component name used in ZRTP exchange.
Definition: zrtp.h:375
zrtp_string32_t cipher_name
Cipher crypto component name used in ZRTP encryption.
Definition: zrtp.h:369
int zrtp_randstr(zrtp_global_t *zrtp, unsigned char *buffer, uint32_t length)
Random string generation.
int zrtp_profile_find(const zrtp_profile_t *profile, zrtp_crypto_comp_t type, uint8_t id)
Search for a component in the profile by ID.
zrtp_status_t zrtp_stream_start(zrtp_stream_t *stream, uint32_t ssrc)
Starting a ZRTP stream.
Will send a Commit message to any ZRTP partner, Passive or non-Passive.
Definition: zrtp.h:122
zrtp_status_t zrtp_signaling_hash_set(zrtp_stream_t *stream, const char *hash_buff, uint32_t hash_buff_length)
Specifies the hash of the peer Hello message for verification.
Never send a Commit message, and thus can never be the initiator.
Definition: zrtp.h:118
zrtp_cache_file_config_t cache_file_cfg
Definition: zrtp.h:176
zrtp_stream_mode_t
Enumeration for ZRTP stream mode definition.
Definition: zrtp_types.h:69
void zrtp_config_defaults(zrtp_config_t *config)
Initializes libzrtp global config.
zrtp_license_mode_t
Enumeration for ZRTP Licensing modesA ZRTP endpoint that is Passive will never send a Commit message...
Definition: zrtp.h:115
unsigned char zrtp_zid_t[12]
12-byte ZID for unique ZRTP endpoint identification.
Definition: zrtp.h:145
zrtp_string16_t sas2
Second Short Authentication string.
Definition: zrtp.h:302
zrtp_mitm_mode_t mitm_mode
Defines ZRTP Trusted mitm mode for the current session.
Definition: zrtp.h:204
zrtp_state_t
Defines ZRTP state-machine statesThe conditions for switching from one state to another, and libzrtp behavior in every state is described in detail in XXX and depicted in diagram XXX and XXX.
Definition: zrtp_types.h:35
void * zrtp_stream_get_userdata(const zrtp_stream_t *stream)
Return user data associated with the zrtp stream.
zrtp_status_t zrtp_session_init(zrtp_global_t *zrtp, zrtp_profile_t *profile, zrtp_signaling_role_t role, zrtp_session_t **session)
ZRTP Session Initialization.
char zrtp_client_id_t[16]
16-byte ID for ZRTP endpoint's software identification.
Definition: zrtp.h:148
uint32_t wrongs_flags
Bit-map to summarize shared secrets "Wrong" flags.
Definition: zrtp.h:339
zrtp_status_t zrtp_stream_get(zrtp_stream_t *stream, zrtp_stream_info_t *info)
Obtain information about zrtp stream.
libzrtp errors definitions
int zrtp_entropy_add(zrtp_global_t *zrtp, const unsigned char *buffer, uint32_t length)
Entropy accumulation routine.
zrtp_cache_type_t cache_type
Definition: zrtp.h:173
zrtp stream information structurelibzrtp, since v0.80 takes data encapsulating approach and hides all...
Definition: zrtp.h:192
uint8_t res_allowclear
Allowclear flag.
Definition: zrtp.h:230
Definition: zrtp_string.h:59
zrtp_stream_mode_t mode
Stream mode. Defines libzrtp behavior related to specified contexts.
Definition: zrtp.h:201
void zrtp_profile_defaults(zrtp_profile_t *profile, zrtp_global_t *zrtp)
Configure the default ZRTP profile.
void zrtp_session_down(zrtp_session_t *session)
ZRTP Session context deinitialization.
libzrtp platform-dependent routine
zrtp_status_t zrtp_init(zrtp_config_t *config, zrtp_global_t **zrtp)
Initializing libzrtp.
zrtp_status_t zrtp_stream_attach(zrtp_session_t *session, zrtp_stream_t **stream)
Attaching a new stream to the session.
zrtp_status_t zrtp_profile_check(const zrtp_profile_t *profile, zrtp_global_t *zrtp)
Verifying the ZRTP profile.
uint32_t sas_is_verified
SAS Verification flag.
Definition: zrtp.h:351
zrtp session information structurelibzrtp, since v0.80 takes data incapsulating approach and hides al...
Definition: zrtp.h:258
zrtp_string32_t auth_name
SRTP Authentication crypto component name used in ZRTP exchange.
Definition: zrtp.h:372
zrtp_status_t zrtp_session_get(zrtp_session_t *session, zrtp_session_info_t *info)
Obtain information about ZRTP session.
zrtp_status_t zrtp_verified_set(zrtp_global_t *zrtp, zrtp_string16_t *zid1, zrtp_string16_t *zid2, uint8_t verified)
Changing the value of the secret's verification flag.
Defines basic Functions to work with MiTM endpoints.
void zrtp_stream_set_userdata(zrtp_stream_t *stream, void *udata)
Allow user to associate some data with zrtp stream.
zrtp_callback_t cb
Set of interfaces required to operate with libzrtp.
Definition: zrtp.h:170
uint8_t sas_is_base256
Indicates base256 SAS encoding.
Definition: zrtp.h:354
zrtp_license_mode_t lic_mode
libzrtp license mode defined protocol behavior
Definition: zrtp.h:164
zrtp_string16_t peer_clientid
Character name identified remote ZRTP endpoint.
Definition: zrtp.h:280
zrtp_client_id_t client_id
Symbolic client identifier.
Definition: zrtp.h:161
zrtp_string16_t peer_version
ZRTP Protocol version supported by the remote endpoint.
Definition: zrtp.h:283
uint8_t peer_mitm
Defines that remote party is ZRTP MiTM endpoint.
Definition: zrtp.h:247
ZRTP feedback interface and application dependent routine.
Definition: zrtp_iface.h:468
zrtp_string16_t zid
Local ZID.
Definition: zrtp.h:269
uint8_t peer_disclose
Peer disclose bit flag.
Definition: zrtp.h:239
uint32_t cached_flags
Bit-map to summarize shared secrets "Cached" flags.
Definition: zrtp.h:316
libzrtp product-dependent functions
zrtp_string32_t pk_name
Publik Key Exchange name used in ZRTP exchange.
Definition: zrtp.h:378
zrtp_protocol_error_t
Define protocol error codes according to ZRTP RFC sec. 5.9.
Definition: zrtp_error.h:34
ZRTP session profileZRTP Sessions are configured with a profile scheme. Each profile is defined by a ...
Definition: zrtp_types.h:105
zrtp_protocol_error_t last_error
Last protocol error code.
Definition: zrtp.h:214
uint8_t is_mitm
Set this flag to 1 if you product is MiTM box.
Definition: zrtp.h:167
uint8_t sas_is_ready
Indicates that SAS related data is available for reading.
Definition: zrtp.h:291
zrtp_string32_t sasbin
Binary SAS digest (ZRTP_SAS_DIGEST_LENGTH bytes)
Definition: zrtp.h:305
Signaling Responder.
Definition: zrtp.h:139
zrtp_id_t id
Session unique identifier for debug purposes.
Definition: zrtp.h:261