Alexandre Lision | 51140e1 | 2013-12-02 10:54:09 -0500 | [diff] [blame^] | 1 | /* |
| 2 | Copyright (C) 2006-2010 Werner Dittmann |
| 3 | |
| 4 | This program is free software: you can redistribute it and/or modify |
| 5 | it under the terms of the GNU General Public License as published by |
| 6 | the Free Software Foundation, either version 3 of the License, or |
| 7 | (at your option) any later version. |
| 8 | |
| 9 | This program is distributed in the hope that it will be useful, |
| 10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 12 | GNU General Public License for more details. |
| 13 | |
| 14 | You should have received a copy of the GNU General Public License |
| 15 | along with this program. If not, see <http://www.gnu.org/licenses/>. |
| 16 | */ |
| 17 | |
| 18 | #ifndef _ZRTPCALLBACK_H_ |
| 19 | #define _ZRTPCALLBACK_H_ |
| 20 | |
| 21 | /** |
| 22 | * @file ZrtpCallback.h |
| 23 | * @brief Callback interface between ZRTP and the RTP stack implementation |
| 24 | * @ingroup GNU_ZRTP |
| 25 | * @{ |
| 26 | */ |
| 27 | |
| 28 | #include <string> |
| 29 | #include <stdint.h> |
| 30 | #include <libzrtpcpp/ZrtpCodes.h> |
| 31 | |
| 32 | #ifndef __EXPORT |
| 33 | #if __GNUC__ >= 4 |
| 34 | #define __EXPORT __attribute__ ((visibility("default"))) |
| 35 | #define __LOCAL __attribute__ ((visibility("hidden"))) |
| 36 | #elif defined _WIN32 || defined __CYGWIN__ |
| 37 | #define __EXPORT __declspec(dllimport) |
| 38 | #define __LOCAL |
| 39 | #else |
| 40 | #define __EXPORT |
| 41 | #define __LOCAL |
| 42 | #endif |
| 43 | #endif |
| 44 | |
| 45 | /** |
| 46 | * This enum defines which role a ZRTP peer has. |
| 47 | * |
| 48 | * According to the ZRTP specification the role determines which keys to |
| 49 | * use to encrypt or decrypt SRTP data. |
| 50 | * |
| 51 | * <ul> |
| 52 | * <li> The Initiator encrypts SRTP data using the <em>keyInitiator</em> and the |
| 53 | * <em>saltInitiator</em> data, the Responder uses these data to decrypt. |
| 54 | * </li> |
| 55 | * <li> The Responder encrypts SRTP data using the <em>keyResponder</em> and the |
| 56 | * <em>saltResponder</em> data, the Initiator uses these data to decrypt. |
| 57 | * </li> |
| 58 | * </ul> |
| 59 | */ |
| 60 | typedef enum { |
| 61 | Responder = 1, ///< This client is in ZRTP Responder mode |
| 62 | Initiator ///< This client is in ZRTP Initiator mode |
| 63 | } Role; |
| 64 | |
| 65 | /// The algorihms that we support in SRTP and that ZRTP can negotiate. |
| 66 | typedef enum { |
| 67 | None, |
| 68 | Aes = 1, ///< Use AES as symmetrical cipher algorithm |
| 69 | TwoFish, ///< Use TwoFish as symmetrical cipher algorithm |
| 70 | Sha1, ///< Use Sha1 as authentication algorithm |
| 71 | Skein ///< Use Skein as authentication algorithm |
| 72 | } SrtpAlgorithms; |
| 73 | |
| 74 | /** |
| 75 | * This structure contains pointers to the SRTP secrets and the role info. |
| 76 | * |
| 77 | * About the role and what the meaning of the role is refer to the |
| 78 | * of the enum Role. The pointers to the secrets are valid as long as |
| 79 | * the ZRtp object is active. To use these data after the ZRtp object's |
| 80 | * lifetime you may copy the data into a save place. The destructor |
| 81 | * of ZRtp clears the data. |
| 82 | */ |
| 83 | typedef struct srtpSecrets { |
| 84 | SrtpAlgorithms symEncAlgorithm; ///< symmetrical cipher algorithm |
| 85 | const uint8_t* keyInitiator; ///< Initiator's key |
| 86 | int32_t initKeyLen; ///< Initiator's key length |
| 87 | const uint8_t* saltInitiator; ///< Initiator's salt |
| 88 | int32_t initSaltLen; ///< Initiator's salt length |
| 89 | const uint8_t* keyResponder; ///< Responder's key |
| 90 | int32_t respKeyLen; ///< Responder's key length |
| 91 | const uint8_t* saltResponder; ///< Responder's salt |
| 92 | int32_t respSaltLen; ///< Responder's salt length |
| 93 | SrtpAlgorithms authAlgorithm; ///< SRTP authentication algorithm |
| 94 | int32_t srtpAuthTagLen; ///< SRTP authentication length |
| 95 | std::string sas; ///< The SAS string |
| 96 | Role role; ///< ZRTP role of this client |
| 97 | } SrtpSecret_t; |
| 98 | |
| 99 | enum EnableSecurity { |
| 100 | ForReceiver = 1, ///< Enable security for SRTP receiver |
| 101 | ForSender = 2 ///< Enable security for SRTP sender |
| 102 | }; |
| 103 | |
| 104 | /** |
| 105 | * This abstract class defines the callback functions required by GNU ZRTP. |
| 106 | * |
| 107 | * This class is a pure abstract class, aka Interface in Java, that |
| 108 | * defines the callback interface that the specific part of a GNU ZRTP |
| 109 | * must implement. The generic part of GNU ZRTP uses these mehtods |
| 110 | * to communicate with the specific part, for example to send data |
| 111 | * via the RTP/SRTP stack, to set timers and cancel timer and so on. |
| 112 | * |
| 113 | * The generiy part of GNU ZRTP needs only a few callback methods to |
| 114 | * be implemented by the specific part. |
| 115 | * |
| 116 | * @author Werner Dittmann <Werner.Dittmann@t-online.de> |
| 117 | */ |
| 118 | |
| 119 | class __EXPORT ZrtpCallback { |
| 120 | |
| 121 | protected: |
| 122 | friend class ZRtp; |
| 123 | |
| 124 | virtual ~ZrtpCallback() {}; |
| 125 | |
| 126 | /** |
| 127 | * Send a ZRTP packet via RTP. |
| 128 | * |
| 129 | * ZRTP calls this method to send a ZRTP packet via the RTP session. |
| 130 | * |
| 131 | * @param data |
| 132 | * Points to ZRTP packet to send. |
| 133 | * @param length |
| 134 | * The length in bytes of the data |
| 135 | * @return |
| 136 | * zero if sending failed, one if packet was send |
| 137 | */ |
| 138 | virtual int32_t sendDataZRTP(const uint8_t* data, int32_t length) =0; |
| 139 | |
| 140 | /** |
| 141 | * Activate timer. |
| 142 | * |
| 143 | * @param time |
| 144 | * The time in ms for the timer |
| 145 | * @return |
| 146 | * zero if activation failed, one if timer was activated |
| 147 | */ |
| 148 | virtual int32_t activateTimer(int32_t time) =0; |
| 149 | |
| 150 | /** |
| 151 | * Cancel the active timer. |
| 152 | * |
| 153 | * @return |
| 154 | * zero if cancel action failed, one if timer was canceled |
| 155 | */ |
| 156 | virtual int32_t cancelTimer() =0; |
| 157 | |
| 158 | /** |
| 159 | * Send information messages to the hosting environment. |
| 160 | * |
| 161 | * The ZRTP implementation uses this method to send information |
| 162 | * messages to the host. Along with the message ZRTP provides a |
| 163 | * severity indicator that defines: Info, Warning, Error, |
| 164 | * Alert. Refer to the <code>MessageSeverity</code> enum above. |
| 165 | * |
| 166 | * @param severity |
| 167 | * This defines the message's severity |
| 168 | * @param subCode |
| 169 | * The subcode identifying the reason. |
| 170 | * @see ZrtpCodes#MessageSeverity |
| 171 | */ |
| 172 | virtual void sendInfo(GnuZrtpCodes::MessageSeverity severity, int32_t subCode) =0; |
| 173 | |
| 174 | /** |
| 175 | * SRTP crypto data ready for the sender or receiver. |
| 176 | * |
| 177 | * The ZRTP implementation calls this method right after all SRTP |
| 178 | * secrets are computed and ready to be used. The parameter points |
| 179 | * to a structure that contains pointers to the SRTP secrets and a |
| 180 | * <code>enum Role</code>. The called method (the implementation |
| 181 | * of this abstract method) must either copy the pointers to the SRTP |
| 182 | * data or the SRTP data itself to a save place. The SrtpSecret_t |
| 183 | * structure is destroyed after the callback method returns to the |
| 184 | * ZRTP implementation. |
| 185 | * |
| 186 | * The SRTP data themselfs are ontained in the ZRtp object and are |
| 187 | * valid as long as the ZRtp object is active. TheZRtp's |
| 188 | * destructor clears the secrets. Thus the called method needs to |
| 189 | * save the pointers only, ZRtp takes care of the data. |
| 190 | * |
| 191 | * The implementing class may enable SRTP processing in this |
| 192 | * method or delay it to srtpSecertsOn(). |
| 193 | * |
| 194 | * @param secrets A pointer to a SrtpSecret_t structure that |
| 195 | * contains all necessary data. |
| 196 | * |
| 197 | * @param part for which part (Sender or Receiver) this data is |
| 198 | * valid. |
| 199 | * |
| 200 | * @return Returns false if something went wrong during |
| 201 | * initialization of SRTP context, for example memory shortage. |
| 202 | */ |
| 203 | virtual bool srtpSecretsReady(SrtpSecret_t* secrets, EnableSecurity part) =0; |
| 204 | |
| 205 | /** |
| 206 | * Switch off the security for the defined part. |
| 207 | * |
| 208 | * @param part Defines for which part (sender or receiver) to |
| 209 | * switch on security |
| 210 | */ |
| 211 | virtual void srtpSecretsOff(EnableSecurity part) =0; |
| 212 | |
| 213 | /** |
| 214 | * Switch on the security. |
| 215 | * |
| 216 | * ZRTP calls this method after it has computed the SAS and check |
| 217 | * if it is verified or not. In addition ZRTP provides information |
| 218 | * about the cipher algorithm and key length for the SRTP session. |
| 219 | * |
| 220 | * This method must enable SRTP processing if it was not enabled |
| 221 | * during sertSecretsReady(). |
| 222 | * |
| 223 | * @param c The name of the used cipher algorithm and mode, or |
| 224 | * NULL |
| 225 | * |
| 226 | * @param s The SAS string |
| 227 | * |
| 228 | * @param verified if <code>verified</code> is true then SAS was |
| 229 | * verified by both parties during a previous call. |
| 230 | */ |
| 231 | virtual void srtpSecretsOn(std::string c, std::string s, bool verified) =0; |
| 232 | |
| 233 | /** |
| 234 | * This method handles GoClear requests. |
| 235 | * |
| 236 | * According to the ZRTP specification the user must be informed about |
| 237 | * a GoClear request because the ZRTP implementation switches off security |
| 238 | * if it could authenticate the GoClear packet. |
| 239 | * |
| 240 | * <b>Note:</b> GoClear is not yet implemented in GNU ZRTP. |
| 241 | * |
| 242 | */ |
| 243 | virtual void handleGoClear() =0; |
| 244 | |
| 245 | /** |
| 246 | * Handle ZRTP negotiation failed. |
| 247 | * |
| 248 | * ZRTP calls this method in case ZRTP negotiation failed. The |
| 249 | * parameters show the severity as well as the reason. |
| 250 | * |
| 251 | * @param severity |
| 252 | * This defines the message's severity |
| 253 | * @param subCode |
| 254 | * The subcode identifying the reason. |
| 255 | * @see ZrtpCodes#MessageSeverity |
| 256 | */ |
| 257 | virtual void zrtpNegotiationFailed(GnuZrtpCodes::MessageSeverity severity, int32_t subCode) =0; |
| 258 | |
| 259 | /** |
| 260 | * ZRTP calls this method if the other side does not support ZRTP. |
| 261 | * |
| 262 | * If the other side does not answer the ZRTP <em>Hello</em> packets then |
| 263 | * ZRTP calls this method, |
| 264 | * |
| 265 | */ |
| 266 | virtual void zrtpNotSuppOther() =0; |
| 267 | |
| 268 | /** |
| 269 | * Enter synchronization mutex. |
| 270 | * |
| 271 | * GNU ZRTP requires one mutes to synchronize its |
| 272 | * processing. Because mutex implementations depend on the |
| 273 | * underlying infrastructure, for example operating system or |
| 274 | * thread implementation, GNU ZRTP delegates mutex handling to the |
| 275 | * spcific part of its implementation. |
| 276 | */ |
| 277 | virtual void synchEnter() =0; |
| 278 | |
| 279 | /** |
| 280 | * Leave synchronization mutex. |
| 281 | */ |
| 282 | virtual void synchLeave() =0; |
| 283 | |
| 284 | /** |
| 285 | * Inform about a PBX enrollment request. |
| 286 | * |
| 287 | * Please refer to chapter 8.3 ff to get more details about PBX |
| 288 | * enrollment and SAS relay. |
| 289 | * |
| 290 | * <b>Note:</b> PBX enrollement is not yet fully supported by GNU |
| 291 | * ZRTP. |
| 292 | * |
| 293 | * @param info Give some information to the user about the PBX |
| 294 | * requesting an enrollment. |
| 295 | */ |
| 296 | virtual void zrtpAskEnrollment(GnuZrtpCodes::InfoEnrollment info) =0; |
| 297 | |
| 298 | /** |
| 299 | * Inform about PBX enrollment result. |
| 300 | * |
| 301 | * Informs the use about the acceptance or denial of an PBX enrollment |
| 302 | * request |
| 303 | * |
| 304 | * <b>Note:</b> PBX enrollement is not yet fully supported by GNU |
| 305 | * ZRTP. |
| 306 | * |
| 307 | * @param info information to the user about the result |
| 308 | * of an enrollment. |
| 309 | */ |
| 310 | virtual void zrtpInformEnrollment(GnuZrtpCodes::InfoEnrollment info) =0; |
| 311 | |
| 312 | /** |
| 313 | * Request a SAS signature. |
| 314 | * |
| 315 | * After ZRTP was able to compute the Short Authentication String |
| 316 | * (SAS) it calls this method. The client may now use an |
| 317 | * approriate method to sign the SAS. The client may use |
| 318 | * ZrtpQueue#setSignatureData() to store the signature data an |
| 319 | * enable signature transmission to the other peer. Refer to |
| 320 | * chapter 8.2 of ZRTP specification. |
| 321 | * |
| 322 | * <b>Note:</b> SAS signing is not yet fully supported by GNU |
| 323 | * ZRTP. |
| 324 | * |
| 325 | * @param sasHash |
| 326 | * The SAS hash to sign. |
| 327 | * |
| 328 | */ |
| 329 | virtual void signSAS(uint8_t* sasHash) =0; |
| 330 | |
| 331 | /** |
| 332 | * ZRTPQueue calls this method to request a SAS signature check. |
| 333 | * |
| 334 | * After ZRTP received a SAS signature in one of the Confirm packets it |
| 335 | * call this method. The client may use <code>getSignatureLength()</code> |
| 336 | * and <code>getSignatureData()</code>of ZrtpQueue to get the signature |
| 337 | * data and perform the signature check. Refer to chapter 8.2 of ZRTP |
| 338 | * specification. |
| 339 | * |
| 340 | * If the signature check fails the client may return false to ZRTP. In |
| 341 | * this case ZRTP signals an error to the other peer and terminates |
| 342 | * the ZRTP handshake. |
| 343 | * |
| 344 | * <b>Note:</b> SAS signing is not yet fully supported by GNU |
| 345 | * ZRTP. |
| 346 | * |
| 347 | * @param sasHash |
| 348 | * The SAS hash that was signed by the other peer. |
| 349 | * @return |
| 350 | * true if the signature was ok, false otherwise. |
| 351 | * |
| 352 | */ |
| 353 | virtual bool checkSASSignature(uint8_t* sasHash) =0; |
| 354 | }; |
| 355 | |
| 356 | #endif // ZRTPCALLBACK |
| 357 | |
| 358 | /** |
| 359 | * @} |
| 360 | */ |
| 361 | /** EMACS ** |
| 362 | * Local variables: |
| 363 | * mode: c++ |
| 364 | * c-default-style: ellemtel |
| 365 | * c-basic-offset: 4 |
| 366 | * End: |
| 367 | */ |