1 /* 2 Copyright (c) 2007-2019 by Jakob Schröter <js@camaya.net> 3 This file is part of the gloox library. http://camaya.net/gloox 4 5 This software is distributed under a license. The full license 6 agreement can be found in the file LICENSE in this distribution. 7 This software may not be copied, modified, sold or distributed 8 other than expressed in the named license agreement. 9 10 This software is distributed without any warranty. 11 */ 12 13 14 15 #ifndef TLSBASE_H__ 16 #define TLSBASE_H__ 17 18 #include "gloox.h" 19 #include "mutex.h" 20 #include "tlshandler.h" 21 22 namespace gloox 23 { 24 25 /** 26 * @brief An abstract base class for TLS implementations. 27 * 28 * @author Jakob Schröter <js@camaya.net> 29 * @since 0.9 30 */ 31 class GLOOX_API TLSBase 32 { 33 public: 34 /** 35 * Constructor. 36 * @param th The TLSHandler to handle TLS-related events. 37 * @param server The server to use in certificate verification. 38 */ TLSBase(TLSHandler * th,const std::string server)39 TLSBase( TLSHandler* th, const std::string server ) 40 : m_handler( th ), m_server( server ), m_secure( false ), m_valid( false ), m_initLib( true ) 41 {} 42 43 /** 44 * Virtual destructor. 45 */ ~TLSBase()46 virtual ~TLSBase() {} 47 48 /** 49 * Initializes the TLS module. This function must be called (and execute successfully) 50 * before the module can be used. 51 * @param clientKey The absolute path to the user's private key in PEM format. 52 * @param clientCerts A path to a certificate bundle in PEM format. 53 * @param cacerts A list of absolute paths to CA root certificate files in PEM format. 54 * @return @b False if initialization failed, @b true otherwise. 55 * @since 1.0 56 */ 57 virtual bool init( const std::string& clientKey = EmptyString, 58 const std::string& clientCerts = EmptyString, 59 const StringList& cacerts = StringList() ) = 0; 60 61 /** 62 * Enables/disables initialization of the underlying TLS library. By default, 63 * initialization is performed. You may want to switch it off if the TLS library 64 * is used elsewhere in your application as well and you have no control over the 65 * initialization. 66 * @param init Whether or not to intialize the underlying TLS library. 67 */ setInitLib(bool init)68 void setInitLib( bool init ) { m_initLib = init; } 69 70 /** 71 * Use this function to feed unencrypted data to the encryption implementation. 72 * The encrypted result will be pushed to the TLSHandler's handleEncryptedData() function. 73 * @param data The data to encrypt. 74 * @return Whether or not the data was used successfully. 75 */ 76 virtual bool encrypt( const std::string& data ) = 0; 77 78 /** 79 * Use this function to feed encrypted data or received handshake data to the 80 * encryption implementation. Handshake data will be eaten, unencrypted data 81 * will be pushed to the TLSHandler's handleDecryptedData() function. 82 * @param data The data to decrypt. 83 * @return The number of bytes used from the input. 84 */ 85 virtual int decrypt( const std::string& data ) = 0; 86 87 /** 88 * This function performs internal cleanup and will be called after a failed handshake attempt. 89 */ 90 virtual void cleanup() = 0; 91 92 /** 93 * This functiopn performs the TLS handshake. Handshake data from the server side should be 94 * fed in using decrypt(). Handshake data that is to be sent to the other side is pushed through 95 * TLSBase's handleEncryptedData(). 96 * @return @b True if the handshake was successful or if more input is needed, @b false if the 97 * handshake failed. 98 */ 99 virtual bool handshake() = 0; 100 101 /** 102 * Returns the state of the encryption. 103 * @return The state of the encryption. 104 */ isSecure()105 virtual bool isSecure() const { return m_secure; } 106 107 /** 108 * This function indicates whether the underlying TLS implementation supports channel binding (used in e.g. SASL SCRAM-SHA-1-PLUS). 109 * @return @b True if channel binding is supported, @b false otherwise. 110 */ hasChannelBinding()111 virtual bool hasChannelBinding() const { return false; } 112 113 /** 114 * Returns the channel binding data for the established connection. 115 * @return The channel binding data, if any, or the empty string. 116 */ channelBinding()117 virtual const std::string channelBinding() const { return EmptyString; } 118 119 /** 120 * Use this function to set a number of trusted root CA certificates which shall be 121 * used to verify a servers certificate. 122 * @param cacerts A list of absolute paths to CA root certificate files in PEM format. 123 */ 124 virtual void setCACerts( const StringList& cacerts ) = 0; 125 126 /** 127 * This function is used to retrieve certificate and connection info of a encrypted connection. 128 * @return Certificate information. 129 */ fetchTLSInfo()130 virtual const CertInfo& fetchTLSInfo() const { return m_certInfo; } 131 132 /** 133 * Use this function to set the user's certificate and private key. The certificate will 134 * be presented to the server upon request and can be used for SASL EXTERNAL authentication. 135 * The user's certificate file should be a bundle of more than one certificate in PEM format. 136 * The first one in the file should be the user's certificate, each cert following that one 137 * should have signed the previous one. 138 * @note These certificates are not necessarily the same as those used to verify the server's 139 * certificate. 140 * @param clientKey The absolute path to the user's private key in PEM format. 141 * @param clientCerts A path to a certificate bundle in PEM format. 142 */ 143 virtual void setClientCert( const std::string& clientKey, const std::string& clientCerts ) = 0; 144 145 protected: 146 TLSHandler* m_handler; 147 StringList m_cacerts; 148 std::string m_clientKey; 149 std::string m_clientCerts; 150 std::string m_server; 151 CertInfo m_certInfo; 152 util::Mutex m_mutex; 153 bool m_secure; 154 bool m_valid; 155 bool m_initLib; 156 157 }; 158 159 } 160 161 #endif // TLSBASE_H__ 162