1 /* 2 mediastreamer2 library - modular sound and video processing and streaming 3 Copyright (C) 2014 Belledonne Communications 4 5 This library is free software; you can redistribute it and/or 6 modify it under the terms of the GNU Lesser General Public 7 License as published by the Free Software Foundation; either 8 version 2.1 of the License, or (at your option) any later version. 9 10 This library is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Lesser General Public License for more details. 14 15 You should have received a copy of the GNU Lesser General Public 16 License along with this library; if not, write to the Free Software 17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 */ 19 20 #ifndef ms_zrtp_h 21 #define ms_zrtp_h 22 23 #include <ortp/rtpsession.h> 24 #include "mediastreamer2/mscommon.h" 25 26 #ifdef __cplusplus 27 extern "C"{ 28 #endif 29 30 /* defined in mediastream.h */ 31 struct _MSMediaStreamSessions; 32 33 34 /* Error codes */ 35 #define MSZRTP_ERROR_CHANNEL_ALREADY_STARTED -0x0001 36 37 #define MS_MAX_ZRTP_CRYPTO_TYPES 7 38 39 /* cache related function return codes */ 40 #define MSZRTP_CACHE_ERROR -0x1000 41 #define MSZRTP_CACHE_SETUP 0x2000 42 #define MSZRTP_CACHE_UPDATE 0x2001 43 #define MSZRTP_ERROR_CACHEDISABLED -0x0200 44 #define MSZRTP_ERROR_CACHEMIGRATIONFAILED -0x0400 45 46 47 48 typedef uint8_t MsZrtpCryptoTypesCount; 49 50 typedef enum _MSZrtpHash{ 51 MS_ZRTP_HASH_INVALID, 52 MS_ZRTP_HASH_S256, 53 MS_ZRTP_HASH_S384, 54 MS_ZRTP_HASH_N256, 55 MS_ZRTP_HASH_N384 56 } MSZrtpHash; 57 58 typedef enum _MSZrtpCipher{ 59 MS_ZRTP_CIPHER_INVALID, 60 MS_ZRTP_CIPHER_AES1, 61 MS_ZRTP_CIPHER_AES2, 62 MS_ZRTP_CIPHER_AES3, 63 MS_ZRTP_CIPHER_2FS1, 64 MS_ZRTP_CIPHER_2FS2, 65 MS_ZRTP_CIPHER_2FS3 66 } MSZrtpCipher; 67 68 typedef enum _MSZrtpAuthTag{ 69 MS_ZRTP_AUTHTAG_INVALID, 70 MS_ZRTP_AUTHTAG_HS32, 71 MS_ZRTP_AUTHTAG_HS80, 72 MS_ZRTP_AUTHTAG_SK32, 73 MS_ZRTP_AUTHTAG_SK64 74 } MSZrtpAuthTag; 75 76 typedef enum _MSZrtpKeyAgreement{ 77 MS_ZRTP_KEY_AGREEMENT_INVALID, 78 MS_ZRTP_KEY_AGREEMENT_DH2K, 79 MS_ZRTP_KEY_AGREEMENT_DH3K, 80 MS_ZRTP_KEY_AGREEMENT_EC25, 81 MS_ZRTP_KEY_AGREEMENT_EC38, 82 MS_ZRTP_KEY_AGREEMENT_EC52 83 } MSZrtpKeyAgreement; 84 85 typedef enum _MSZrtpSasType{ 86 MS_ZRTP_SAS_INVALID, 87 MS_ZRTP_SAS_B32, 88 MS_ZRTP_SAS_B256 89 } MSZrtpSasType; 90 91 typedef struct MSZrtpParams { 92 void *zidCacheDB; /**< a pointer to an sqlite database holding all zrtp related information */ 93 const char *selfUri; /* our sip URI, needed for zrtp Cache */ 94 const char *peerUri; /* the sip URI of correspondant, needed for zrtp Cache */ 95 uint32_t limeKeyTimeSpan; /**< amount in seconds of the lime key life span, set to 0 for infinite life span **/ 96 97 /* activated crypto types */ 98 MSZrtpHash hashes[MS_MAX_ZRTP_CRYPTO_TYPES]; 99 MsZrtpCryptoTypesCount hashesCount ; 100 MSZrtpCipher ciphers[MS_MAX_ZRTP_CRYPTO_TYPES]; 101 MsZrtpCryptoTypesCount ciphersCount; 102 MSZrtpAuthTag authTags[MS_MAX_ZRTP_CRYPTO_TYPES]; 103 MsZrtpCryptoTypesCount authTagsCount; 104 MSZrtpKeyAgreement keyAgreements[MS_MAX_ZRTP_CRYPTO_TYPES]; 105 MsZrtpCryptoTypesCount keyAgreementsCount; 106 MSZrtpSasType sasTypes[MS_MAX_ZRTP_CRYPTO_TYPES]; 107 MsZrtpCryptoTypesCount sasTypesCount; 108 } MSZrtpParams; 109 110 typedef struct _MSZrtpContext MSZrtpContext ; 111 112 /** 113 * check if ZRTP is available 114 * @return TRUE if it is available, FALSE if not 115 */ 116 MS2_PUBLIC bool_t ms_zrtp_available(void); 117 118 /** 119 * Create an initialise a ZRTP context 120 * @param[in] stream_sessions A link to the stream sessions structures, used to get rtp session to add transport modifier and needed to set SRTP sessions when keys are ready 121 * @param[in] params ZID cache filename and peer sip uri 122 * @return a pointer to the opaque context structure needed by MSZRTP 123 */ 124 MS2_PUBLIC MSZrtpContext* ms_zrtp_context_new(struct _MSMediaStreamSessions *stream_sessions, MSZrtpParams *params); 125 126 /** 127 * Create an initialise a ZRTP context on a channel when a ZRTP exchange was already performed on an other one 128 * @param[in] stream_sessions A link to the stream sessions structures, used to get rtp session to add transport modifier and needed to set SRTP sessions when keys are ready 129 * @param[in] activeContext The MSZRTP context of the already active session, used to pass to lib bzrtp its own context which shall remain unique. 130 * @return a pointer to the opaque context structure needed by MSZRTP 131 */ 132 MS2_PUBLIC MSZrtpContext* ms_zrtp_multistream_new(struct _MSMediaStreamSessions *stream_sessions, MSZrtpContext* activeContext); 133 134 /*** 135 * Start a previously created ZRTP channel, ZRTP engine will start sending Hello packets 136 * @param[in] ctx Context previously created using ms_zrtp_context_new or ms_zrtp_multistream_new 137 * @return 0 on success 138 */ 139 MS2_PUBLIC int ms_zrtp_channel_start(MSZrtpContext *ctx); 140 141 /** 142 * Free ressources used by ZRTP context 143 * it will also free the libbzrtp context if no more channel are active 144 * @param[in/out] context the opaque MSZRTP context 145 */ 146 MS2_PUBLIC void ms_zrtp_context_destroy(MSZrtpContext *ctx); 147 148 /** 149 * can be used to give more time for establishing zrtp session 150 * @param[in] ctx The MSZRTP context 151 * */ 152 MS2_PUBLIC void ms_zrtp_reset_transmition_timer(MSZrtpContext* ctx); 153 154 /** 155 * Tell the MSZRTP context that SAS was controlled by user, it will trigger a ZID cache update 156 * @param[in] ctx MSZRTP context, used to retrieve cache and update it 157 */ 158 MS2_PUBLIC void ms_zrtp_sas_verified(MSZrtpContext* ctx); 159 160 /** 161 * Tell the MSZRTP context that user have requested the SAS verified status to be reseted, it will trigger a ZID cache update 162 * @param[in] ctx MSZRTP context, used to retrieve cache and update it 163 */ 164 MS2_PUBLIC void ms_zrtp_sas_reset_verified(MSZrtpContext* ctx); 165 166 /** 167 * Get the ZRTP Hello Hash from the given context 168 * @param[in] ctx MSZRTP context 169 * @param[out] The Zrtp Hello Hash as defined in RFC6189 section 8 170 */ 171 MS2_PUBLIC int ms_zrtp_getHelloHash(MSZrtpContext* ctx, uint8_t *output, size_t outputLength); 172 173 /** 174 * Set the peer ZRTP Hello Hash to the given context 175 * @param[in] ctx MSZRTP context 176 * @param[in] The Zrtp Hello Hash as defined in RFC6189 section 8 177 * @param[in] The Zrtp Hello Hash length 178 * 179 * @return 0 on succes, Error code otherwise 180 */ 181 MS2_PUBLIC int ms_zrtp_setPeerHelloHash(MSZrtpContext *ctx, uint8_t *peerHelloHashHexString, size_t peerHelloHashHexStringLength); 182 183 /** 184 * from_string and to_string for enums: MSZrtpHash, MSZrtpCipher, MSZrtpAuthTag, MSZrtpKeyAgreement, MSZrtpSasType 185 */ 186 MS2_PUBLIC MSZrtpHash ms_zrtp_hash_from_string(const char* str); 187 MS2_PUBLIC const char* ms_zrtp_hash_to_string(const MSZrtpHash hash); 188 MS2_PUBLIC MSZrtpCipher ms_zrtp_cipher_from_string(const char* str); 189 MS2_PUBLIC const char* ms_zrtp_cipher_to_string(const MSZrtpCipher cipher); 190 MS2_PUBLIC MSZrtpAuthTag ms_zrtp_auth_tag_from_string(const char* str); 191 MS2_PUBLIC const char* ms_zrtp_auth_tag_to_string(const MSZrtpAuthTag authTag); 192 MS2_PUBLIC MSZrtpKeyAgreement ms_zrtp_key_agreement_from_string(const char* str); 193 MS2_PUBLIC const char* ms_zrtp_key_agreement_to_string(const MSZrtpKeyAgreement keyAgreement); 194 MS2_PUBLIC MSZrtpSasType ms_zrtp_sas_type_from_string(const char* str); 195 MS2_PUBLIC const char* ms_zrtp_sas_type_to_string(const MSZrtpSasType sasType); 196 197 /* Cache wrapper functions : functions needed by liblinphone wrapped to avoid direct dependence of linphone on bzrtp */ 198 /** 199 * @brief Check the given sqlite3 DB and create requested tables if needed 200 * Also manage DB schema upgrade 201 * @param[in/out] db Pointer to the sqlite3 db open connection 202 * Use a void * to keep this API when building cacheless 203 * 204 * @return 0 on succes, MSZRTP_CACHE_SETUP if cache was empty, MSZRTP_CACHE_UPDATE if db structure was updated error code otherwise 205 */ 206 MS2_PUBLIC int ms_zrtp_initCache(void *db); 207 208 /** 209 * @brief Perform migration from xml version to sqlite3 version of cache 210 * Warning: new version of cache associate a ZID to each local URI, the old one did not 211 * the migration function will associate any data in the cache to the sip URI given in parameter which shall be the default URI 212 * @param[in] cacheXml a pointer to an xmlDocPtr structure containing the old cache to be migrated 213 * @param[in/out] cacheSqlite a pointer to an sqlite3 structure containing a cache initialised using ms_zrtp_cache_init function 214 * @param[in] selfURI default sip URI for this end point, NULL terminated char 215 * 216 * @return 0 on success, MSZRTP_ERROR_CACHEDISABLED when bzrtp was not compiled with cache enabled, MSZRTP_ERROR_CACHEMIGRATIONFAILED on error during migration 217 */ 218 MS2_PUBLIC int ms_zrtp_cache_migration(void *cacheXmlPtr, void *cacheSqlite, const char *selfURI); 219 220 #ifdef __cplusplus 221 } 222 #endif 223 224 #endif /* ms_zrtp_h */ 225