diff options
author | Mark Purcell <msp@debian.org> | 2013-07-09 15:55:55 +0100 |
---|---|---|
committer | Mark Purcell <msp@debian.org> | 2013-07-09 15:55:55 +0100 |
commit | 669109e369a1be69ff7c4108eb545eff4c5c26d9 (patch) | |
tree | 73c117a2e7dd22a7a6ee315101f6357ab43386ec /src/libzrtpcpp/ZrtpCallback.h |
libzrtpcpp (2.3.4-1) unstable; urgency=medium
* New upstream release
- Fixes "CVE-2013-2221 CVE-2013-2222 CVE-2013-2223" (Closes: #714650)
# imported from the archive
Diffstat (limited to 'src/libzrtpcpp/ZrtpCallback.h')
-rw-r--r-- | src/libzrtpcpp/ZrtpCallback.h | 367 |
1 files changed, 367 insertions, 0 deletions
diff --git a/src/libzrtpcpp/ZrtpCallback.h b/src/libzrtpcpp/ZrtpCallback.h new file mode 100644 index 0000000..957c4dd --- /dev/null +++ b/src/libzrtpcpp/ZrtpCallback.h @@ -0,0 +1,367 @@ +/* + Copyright (C) 2006-2010 Werner Dittmann + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see <http://www.gnu.org/licenses/>. +*/ + +#ifndef _ZRTPCALLBACK_H_ +#define _ZRTPCALLBACK_H_ + +/** + * @file ZrtpCallback.h + * @brief Callback interface between ZRTP and the RTP stack implementation + * @ingroup GNU_ZRTP + * @{ + */ + +#include <string> +#include <stdint.h> +#include <libzrtpcpp/ZrtpCodes.h> + +#ifndef __EXPORT + #if __GNUC__ >= 4 + #define __EXPORT __attribute__ ((visibility("default"))) + #define __LOCAL __attribute__ ((visibility("hidden"))) + #elif defined _WIN32 || defined __CYGWIN__ + #define __EXPORT __declspec(dllimport) + #define __LOCAL + #else + #define __EXPORT + #define __LOCAL + #endif +#endif + +/** + * This enum defines which role a ZRTP peer has. + * + * According to the ZRTP specification the role determines which keys to + * use to encrypt or decrypt SRTP data. + * + * <ul> + * <li> The Initiator encrypts SRTP data using the <em>keyInitiator</em> and the + * <em>saltInitiator</em> data, the Responder uses these data to decrypt. + * </li> + * <li> The Responder encrypts SRTP data using the <em>keyResponder</em> and the + * <em>saltResponder</em> data, the Initiator uses these data to decrypt. + * </li> + * </ul> + */ +typedef enum { + Responder = 1, ///< This client is in ZRTP Responder mode + Initiator ///< This client is in ZRTP Initiator mode +} Role; + +/// The algorihms that we support in SRTP and that ZRTP can negotiate. +typedef enum { + None, + Aes = 1, ///< Use AES as symmetrical cipher algorithm + TwoFish, ///< Use TwoFish as symmetrical cipher algorithm + Sha1, ///< Use Sha1 as authentication algorithm + Skein ///< Use Skein as authentication algorithm +} SrtpAlgorithms; + +/** + * This structure contains pointers to the SRTP secrets and the role info. + * + * About the role and what the meaning of the role is refer to the + * of the enum Role. The pointers to the secrets are valid as long as + * the ZRtp object is active. To use these data after the ZRtp object's + * lifetime you may copy the data into a save place. The destructor + * of ZRtp clears the data. + */ +typedef struct srtpSecrets { + SrtpAlgorithms symEncAlgorithm; ///< symmetrical cipher algorithm + const uint8_t* keyInitiator; ///< Initiator's key + int32_t initKeyLen; ///< Initiator's key length + const uint8_t* saltInitiator; ///< Initiator's salt + int32_t initSaltLen; ///< Initiator's salt length + const uint8_t* keyResponder; ///< Responder's key + int32_t respKeyLen; ///< Responder's key length + const uint8_t* saltResponder; ///< Responder's salt + int32_t respSaltLen; ///< Responder's salt length + SrtpAlgorithms authAlgorithm; ///< SRTP authentication algorithm + int32_t srtpAuthTagLen; ///< SRTP authentication length + std::string sas; ///< The SAS string + Role role; ///< ZRTP role of this client +} SrtpSecret_t; + +enum EnableSecurity { + ForReceiver = 1, ///< Enable security for SRTP receiver + ForSender = 2 ///< Enable security for SRTP sender +}; + +/** + * This abstract class defines the callback functions required by GNU ZRTP. + * + * This class is a pure abstract class, aka Interface in Java, that + * defines the callback interface that the specific part of a GNU ZRTP + * must implement. The generic part of GNU ZRTP uses these mehtods + * to communicate with the specific part, for example to send data + * via the RTP/SRTP stack, to set timers and cancel timer and so on. + * + * The generiy part of GNU ZRTP needs only a few callback methods to + * be implemented by the specific part. + * + * @author Werner Dittmann <Werner.Dittmann@t-online.de> + */ + +class __EXPORT ZrtpCallback { + +protected: + friend class ZRtp; + + virtual ~ZrtpCallback() {}; + + /** + * Send a ZRTP packet via RTP. + * + * ZRTP calls this method to send a ZRTP packet via the RTP session. + * + * @param data + * Points to ZRTP packet to send. + * @param length + * The length in bytes of the data + * @return + * zero if sending failed, one if packet was send + */ + virtual int32_t sendDataZRTP(const uint8_t* data, int32_t length) =0; + + /** + * Activate timer. + * + * @param time + * The time in ms for the timer + * @return + * zero if activation failed, one if timer was activated + */ + virtual int32_t activateTimer(int32_t time) =0; + + /** + * Cancel the active timer. + * + * @return + * zero if cancel action failed, one if timer was canceled + */ + virtual int32_t cancelTimer() =0; + + /** + * Send information messages to the hosting environment. + * + * The ZRTP implementation uses this method to send information + * messages to the host. Along with the message ZRTP provides a + * severity indicator that defines: Info, Warning, Error, + * Alert. Refer to the <code>MessageSeverity</code> enum above. + * + * @param severity + * This defines the message's severity + * @param subCode + * The subcode identifying the reason. + * @see ZrtpCodes#MessageSeverity + */ + virtual void sendInfo(GnuZrtpCodes::MessageSeverity severity, int32_t subCode) =0; + + /** + * SRTP crypto data ready for the sender or receiver. + * + * The ZRTP implementation calls this method right after all SRTP + * secrets are computed and ready to be used. The parameter points + * to a structure that contains pointers to the SRTP secrets and a + * <code>enum Role</code>. The called method (the implementation + * of this abstract method) must either copy the pointers to the SRTP + * data or the SRTP data itself to a save place. The SrtpSecret_t + * structure is destroyed after the callback method returns to the + * ZRTP implementation. + * + * The SRTP data themselfs are ontained in the ZRtp object and are + * valid as long as the ZRtp object is active. TheZRtp's + * destructor clears the secrets. Thus the called method needs to + * save the pointers only, ZRtp takes care of the data. + * + * The implementing class may enable SRTP processing in this + * method or delay it to srtpSecertsOn(). + * + * @param secrets A pointer to a SrtpSecret_t structure that + * contains all necessary data. + * + * @param part for which part (Sender or Receiver) this data is + * valid. + * + * @return Returns false if something went wrong during + * initialization of SRTP context, for example memory shortage. + */ + virtual bool srtpSecretsReady(SrtpSecret_t* secrets, EnableSecurity part) =0; + + /** + * Switch off the security for the defined part. + * + * @param part Defines for which part (sender or receiver) to + * switch on security + */ + virtual void srtpSecretsOff(EnableSecurity part) =0; + + /** + * Switch on the security. + * + * ZRTP calls this method after it has computed the SAS and check + * if it is verified or not. In addition ZRTP provides information + * about the cipher algorithm and key length for the SRTP session. + * + * This method must enable SRTP processing if it was not enabled + * during sertSecretsReady(). + * + * @param c The name of the used cipher algorithm and mode, or + * NULL + * + * @param s The SAS string + * + * @param verified if <code>verified</code> is true then SAS was + * verified by both parties during a previous call. + */ + virtual void srtpSecretsOn(std::string c, std::string s, bool verified) =0; + + /** + * This method handles GoClear requests. + * + * According to the ZRTP specification the user must be informed about + * a GoClear request because the ZRTP implementation switches off security + * if it could authenticate the GoClear packet. + * + * <b>Note:</b> GoClear is not yet implemented in GNU ZRTP. + * + */ + virtual void handleGoClear() =0; + + /** + * Handle ZRTP negotiation failed. + * + * ZRTP calls this method in case ZRTP negotiation failed. The + * parameters show the severity as well as the reason. + * + * @param severity + * This defines the message's severity + * @param subCode + * The subcode identifying the reason. + * @see ZrtpCodes#MessageSeverity + */ + virtual void zrtpNegotiationFailed(GnuZrtpCodes::MessageSeverity severity, int32_t subCode) =0; + + /** + * ZRTP calls this method if the other side does not support ZRTP. + * + * If the other side does not answer the ZRTP <em>Hello</em> packets then + * ZRTP calls this method, + * + */ + virtual void zrtpNotSuppOther() =0; + + /** + * Enter synchronization mutex. + * + * GNU ZRTP requires one mutes to synchronize its + * processing. Because mutex implementations depend on the + * underlying infrastructure, for example operating system or + * thread implementation, GNU ZRTP delegates mutex handling to the + * spcific part of its implementation. + */ + virtual void synchEnter() =0; + + /** + * Leave synchronization mutex. + */ + virtual void synchLeave() =0; + + /** + * Inform about a PBX enrollment request. + * + * Please refer to chapter 8.3 ff to get more details about PBX + * enrollment and SAS relay. + * + * <b>Note:</b> PBX enrollement is not yet fully supported by GNU + * ZRTP. + * + * @param info Give some information to the user about the PBX + * requesting an enrollment. + */ + virtual void zrtpAskEnrollment(GnuZrtpCodes::InfoEnrollment info) =0; + + /** + * Inform about PBX enrollment result. + * + * Informs the use about the acceptance or denial of an PBX enrollment + * request + * + * <b>Note:</b> PBX enrollement is not yet fully supported by GNU + * ZRTP. + * + * @param info information to the user about the result + * of an enrollment. + */ + virtual void zrtpInformEnrollment(GnuZrtpCodes::InfoEnrollment info) =0; + + /** + * Request a SAS signature. + * + * After ZRTP was able to compute the Short Authentication String + * (SAS) it calls this method. The client may now use an + * approriate method to sign the SAS. The client may use + * ZrtpQueue#setSignatureData() to store the signature data an + * enable signature transmission to the other peer. Refer to + * chapter 8.2 of ZRTP specification. + * + * <b>Note:</b> SAS signing is not yet fully supported by GNU + * ZRTP. + * + * @param sasHash + * The SAS hash to sign. + * + */ + virtual void signSAS(uint8_t* sasHash) =0; + + /** + * ZRTPQueue calls this method to request a SAS signature check. + * + * After ZRTP received a SAS signature in one of the Confirm packets it + * call this method. The client may use <code>getSignatureLength()</code> + * and <code>getSignatureData()</code>of ZrtpQueue to get the signature + * data and perform the signature check. Refer to chapter 8.2 of ZRTP + * specification. + * + * If the signature check fails the client may return false to ZRTP. In + * this case ZRTP signals an error to the other peer and terminates + * the ZRTP handshake. + * + * <b>Note:</b> SAS signing is not yet fully supported by GNU + * ZRTP. + * + * @param sasHash + * The SAS hash that was signed by the other peer. + * @return + * true if the signature was ok, false otherwise. + * + */ + virtual bool checkSASSignature(uint8_t* sasHash) =0; +}; + +#endif // ZRTPCALLBACK + +/** + * @} + */ +/** EMACS ** + * Local variables: + * mode: c++ + * c-default-style: ellemtel + * c-basic-offset: 4 + * End: + */ |