TDE core libraries
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

kssl.h 7.9KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300
  1. /* This file is part of the KDE project
  2. *
  3. * Copyright (C) 2000-2003 George Staikos <staikos@kde.org>
  4. *
  5. * This library is free software; you can redistribute it and/or
  6. * modify it under the terms of the GNU Library General Public
  7. * License as published by the Free Software Foundation; either
  8. * version 2 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. * Library General Public License for more details.
  14. *
  15. * You should have received a copy of the GNU Library General Public License
  16. * along with this library; see the file COPYING.LIB. If not, write to
  17. * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18. * Boston, MA 02110-1301, USA.
  19. */
  20. #ifndef _KSSL_H
  21. #define _KSSL_H
  22. #include <ksslsettings.h>
  23. #include <ksslpeerinfo.h>
  24. #include <ksslconnectioninfo.h>
  25. class KSSLPrivate;
  26. class KSSLCertificate;
  27. class KSSLPKCS12;
  28. class KSSLSession;
  29. /**
  30. * KDE SSL Wrapper Class
  31. *
  32. * This class implements KDE's SSL support by wrapping OpenSSL.
  33. *
  34. * @author George Staikos <staikos@kde.org>
  35. * @see KExtendedSocket, TCPSlaveBase
  36. * @short KDE SSL Class
  37. */
  38. class TDEIO_EXPORT KSSL {
  39. public:
  40. /**
  41. * Construct a KSSL object
  42. *
  43. * @param init Set this to false if you do not want this class to
  44. * immediately initialize OpenSSL.
  45. */
  46. KSSL(bool init = true);
  47. /**
  48. * Destroy this KSSL object
  49. *
  50. * Does not close any socket.
  51. */
  52. ~KSSL();
  53. /**
  54. * Determine if SSL is available and works.
  55. *
  56. * @return true is SSL is available and usable
  57. */
  58. static bool doesSSLWork();
  59. /**
  60. * Initialize OpenSSL.
  61. *
  62. * @return true on success
  63. *
  64. * This will do nothing if it is already initialized.
  65. * @see reInitialize
  66. */
  67. bool initialize();
  68. /**
  69. * This is used for applicationss which do STARTTLS or something
  70. * similar. It creates a TLS method regardless of the user's settings.
  71. *
  72. * @return true if TLS is successfully initialized
  73. */
  74. bool TLSInit();
  75. /**
  76. * Set an SSL session to use. This takes the session from the original
  77. * KSSL object, so it is in fact a session move operation.
  78. *
  79. * @param session A valid session to reuse. If 0L, it will clear the
  80. * session ID in memory.
  81. *
  82. * @return true on success
  83. */
  84. bool takeSession(KSSLSession *session);
  85. /**
  86. * Close the SSL session.
  87. */
  88. void close();
  89. /**
  90. * Reinitialize OpenSSL.
  91. *
  92. * @return true on success
  93. *
  94. * This is not generally needed unless you are reusing the KSSL object
  95. * for a new session.
  96. * @see initialize
  97. */
  98. bool reInitialize();
  99. /**
  100. * Trigger a reread of KSSL configuration and reInitialize() KSSL.
  101. *
  102. * @return true on successful reinitalizations
  103. *
  104. * If you setAutoReconfig() to false, then this will simply
  105. * reInitialize() and not read in the new configuration.
  106. * @see setAutoReconfig
  107. */
  108. bool reconfig();
  109. /**
  110. * Enable or disable automatic reconfiguration on initialize().
  111. *
  112. * @param ar Set to false in order to disable auto-reloading of the
  113. * KSSL configuration during initialize().
  114. *
  115. * By default, KSSL will read its configuration on initialize(). You
  116. * might want to disable this for performance reasons.
  117. */
  118. void setAutoReconfig(bool ar);
  119. /**
  120. * This will reseed the pseudo-random number generator with the EGD
  121. * (entropy gathering daemon) if the EGD is configured and enabled.
  122. * You don't need to call this yourself normally.
  123. *
  124. * @return 0 on success
  125. */
  126. int seedWithEGD();
  127. /**
  128. * Set a new KSSLSettings instance as the settings. This deletes the
  129. * current instance of KSSLSettings.
  130. *
  131. * @param settings A new, valid settings object.
  132. *
  133. * @return true on success
  134. */
  135. bool setSettings(KSSLSettings *settings);
  136. /**
  137. * One is built by the constructor, so this will only return a NULL
  138. * pointer if you set one with setSettings().
  139. *
  140. * @return the current settings instance
  141. */
  142. KSSLSettings * settings() { return m_cfg; }
  143. /**
  144. * Use this to set the certificate to send to the server.
  145. * Do NOT delete the KSSLPKCS12 object until you are done with the
  146. * session. It is not defined when KSSL will be done with this.
  147. *
  148. * @param pkcs the valid PKCS#12 object to send.
  149. *
  150. * @return true if the certificate was properly set to the session.
  151. */
  152. bool setClientCertificate(KSSLPKCS12 *pkcs);
  153. /**
  154. * Set the status of the connection with respect to proxies.
  155. *
  156. * @param active is not used
  157. * @param realIP is the IP address of the host you're connecting to
  158. * @param realPort is the port of the host you're connecting to
  159. * @param proxy is the IP or hostname of the proxy server
  160. * @deprecated
  161. */
  162. void setProxyUse(bool active, TQString realIP = TQString::null, int realPort = 0, TQString proxy = TQString::null) KDE_DEPRECATED;
  163. /**
  164. * Set the peer hostname to be used for certificate verification.
  165. *
  166. * @param realHost the remote hostname as the user believes to be
  167. * connecting to
  168. */
  169. void setPeerHost(TQString realHost = TQString::null);
  170. /**
  171. * Connect the SSL session to the remote host using the provided
  172. * socket descriptor.
  173. *
  174. * @param sock the socket descriptor to connect with. This must be
  175. * an already connected socket.
  176. * @return 1 on success, 0 on error setting the file descriptor,
  177. * -1 on other error.
  178. */
  179. int connect(int sock);
  180. /**
  181. * Connect the SSL session to the remote host using the provided
  182. * socket descriptor. This is for use with an SSL server application.
  183. *
  184. * @param sock the socket descriptor to connect with. This must be
  185. * an already connected socket.
  186. * @return 1 on success, 0 on error setting the file descriptor,
  187. * -1 on other error.
  188. */
  189. int accept(int sock);
  190. /**
  191. * Read data from the remote host via SSL.
  192. *
  193. * @param buf the buffer to read the data into.
  194. * @param len the maximum length of data to read.
  195. * @return the number of bytes read, 0 on an exception, or -1 on error.
  196. */
  197. int read(void *buf, int len);
  198. /**
  199. * Peek at available data from the remote host via SSL.
  200. *
  201. * @param buf the buffer to read the data into.
  202. * @param len the maximum length of data to read.
  203. * @return the number of bytes read, 0 on an exception, or -1 on error.
  204. */
  205. int peek(void *buf, int len);
  206. /**
  207. * Write data to the remote host via SSL.
  208. *
  209. * @param buf the buffer to read the data from.
  210. * @param len the length of data to send from the buffer.
  211. * @return the number of bytes written, 0 on an exception,
  212. * or -1 on error.
  213. */
  214. int write(const void *buf, int len);
  215. /**
  216. * Determine if data is waiting to be read.
  217. *
  218. * @return -1 on error, 0 if no data is waiting, > 0 if data is waiting.
  219. */
  220. int pending();
  221. /**
  222. * Obtain a reference to the connection information.
  223. *
  224. * @return a reference to the connection information,
  225. * valid after connected
  226. * @see KSSLConnectionInfo
  227. */
  228. KSSLConnectionInfo& connectionInfo();
  229. /**
  230. * Obtain a reference to the information about the peer.
  231. *
  232. * @return a reference to the peer information,
  233. * valid after connected
  234. * @see KSSLPeerInfo
  235. */
  236. KSSLPeerInfo& peerInfo();
  237. /**
  238. * Obtain a pointer to the session information.
  239. *
  240. * @return a pointer to the session information.
  241. * This is valid after connected, while connected.
  242. * It is deleted by the KSSL object which returns it.
  243. * May return 0L if no valid session exists.
  244. * @see KSSLSession
  245. */
  246. const KSSLSession* session() const;
  247. /**
  248. * Determine if we are currently reusing an SSL session ID.
  249. *
  250. * @return true if we are reusing a session ID.
  251. */
  252. bool reusingSession() const;
  253. private:
  254. static bool m_bSSLWorks;
  255. bool m_bInit;
  256. bool m_bAutoReconfig;
  257. KSSLSettings *m_cfg;
  258. KSSLConnectionInfo m_ci;
  259. KSSLPeerInfo m_pi;
  260. KSSLPrivate *d;
  261. void setConnectionInfo();
  262. void setPeerInfo();
  263. bool setVerificationLogic();
  264. };
  265. #endif