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