libpurple/sslconn.h

   1 /**
   2  * @file sslconn.h SSL API
   3  * @ingroup core
   4  */
   5
   6 /* purple
   7  *
   8  * Purple is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26 #ifndef _PURPLE_SSLCONN_H_
  27 #define _PURPLE_SSLCONN_H_
  28
  29 /** Possible SSL errors. */
  30 typedef enum
  31 {
  32         PURPLE_SSL_HANDSHAKE_FAILED = 1,
  33         PURPLE_SSL_CONNECT_FAILED = 2,
  34         PURPLE_SSL_CERTIFICATE_INVALID = 3
  35 } PurpleSslErrorType;
  36
  37 #include "certificate.h"
  38 #include "proxy.h"
  39
  40 #define PURPLE_SSL_DEFAULT_PORT 443
  41
  42 /** @copydoc _PurpleSslConnection */
  43 typedef struct _PurpleSslConnection PurpleSslConnection;
  44
  45 typedef void (*PurpleSslInputFunction)(gpointer, PurpleSslConnection *,
  46                                                                          PurpleInputCondition);
  47 typedef void (*PurpleSslErrorFunction)(PurpleSslConnection *, PurpleSslErrorType,
  48                                                                          gpointer);
  49
  50 struct _PurpleSslConnection
  51 {
  52         /** Hostname to which the SSL connection will be made */
  53         char *host;
  54         /** Port to connect to */
  55         int port;
  56         /** Data to pass to PurpleSslConnection::connect_cb() */
  57         void *connect_cb_data;
  58         /** Callback triggered once the SSL handshake is complete */
  59         PurpleSslInputFunction connect_cb;
  60         /** Callback triggered if there is an error during connection */
  61         PurpleSslErrorFunction error_cb;
  62         /** Data passed to PurpleSslConnection::recv_cb() */
  63         void *recv_cb_data;
  64         /** User-defined callback executed when the SSL connection receives data */
  65         PurpleSslInputFunction recv_cb;
  66
  67         /** File descriptor used to refer to the socket */
  68         int fd;
  69         /** Glib event source ID; used to refer to the received data callback
  70          * in the glib eventloop */
  71         guint inpa;
  72         /** Data related to the underlying TCP connection */
  73         PurpleProxyConnectData *connect_data;
  74
  75         /** Internal connection data managed by the SSL backend (GnuTLS/LibNSS/whatever) */
  76         void *private_data;
  77
  78         /** Verifier to use in authenticating the peer */
  79         PurpleCertificateVerifier *verifier;
  80 };
  81
  82 /**
  83  * SSL implementation operations structure.
  84  *
  85  * Every SSL implementation must provide all of these and register it via purple_ssl_set_ops()
  86  * These should not be called directly! Instead, use the purple_ssl_* functions.
  87  */
  88 typedef struct
  89 {
  90         /** Initializes the SSL system provided.
  91          *  @return @a TRUE if initialization succeeded
  92          *  @see purple_ssl_init
  93          */
  94         gboolean (*init)(void);
  95         /** Unloads the SSL system. Inverse of PurpleSslOps::init.
  96          *  @see purple_ssl_uninit
  97          */
  98         void (*uninit)(void);
  99         /** Sets up the SSL connection for a #PurpleSslConnection once
 100          *  the TCP connection has been established
 101          *  @see purple_ssl_connect
 102          */
 103         void (*connectfunc)(PurpleSslConnection *gsc);
 104         /** Destroys the internal data of the SSL connection provided.
 105          *  Freeing gsc itself is left to purple_ssl_close()
 106          *  @see purple_ssl_close
 107          */
 108         void (*close)(PurpleSslConnection *gsc);
 109         /** Reads data from a connection (like POSIX read())
 110          * @param gsc   Connection context
 111          * @param data  Pointer to buffer to drop data into
 112          * @param len   Maximum number of bytes to read
 113          * @return      Number of bytes actually written into @a data (which may be
 114          *              less than @a len), or <0 on error
 115          * @see purple_ssl_read
 116         */
 117         size_t (*read)(PurpleSslConnection *gsc, void *data, size_t len);
 118         /** Writes data to a connection (like POSIX send())
 119         * @param gsc    Connection context
 120         * @param data   Data buffer to send data from
 121         * @param len    Number of bytes to send from buffer
 122         * @return       The number of bytes written to @a data (may be less than
 123         *               @a len) or <0 on error
 124         * @see purple_ssl_write
 125         */
 126         size_t (*write)(PurpleSslConnection *gsc, const void *data, size_t len);
 127         /** Obtains the certificate chain provided by the peer
 128          *
 129          * @param gsc   Connection context
 130          * @return      A newly allocated list containing the certificates
 131          *              the peer provided.
 132          * @see PurpleCertificate
 133          * @todo        Decide whether the ordering of certificates in this
 134          *              list can be guaranteed.
 135          */
 136         GList * (* get_peer_certificates)(PurpleSslConnection * gsc);
 137
 138         void (*_purple_reserved2)(void);
 139         void (*_purple_reserved3)(void);
 140         void (*_purple_reserved4)(void);
 141 } PurpleSslOps;
 142
 143 #ifdef __cplusplus
 144 extern "C" {
 145 #endif
 146
 147 /**************************************************************************/
 148 /** @name SSL API                                                         */
 149 /**************************************************************************/
 150 /*@{*/
 151
 152 /**
 153  * Returns whether or not SSL is currently supported.
 154  *
 155  * @return @a TRUE if SSL is supported, or @a FALSE otherwise.
 156  */
 157 gboolean purple_ssl_is_supported(void);
 158
 159 /**
 160  * Returns a human-readable string for an SSL error.
 161  *
 162  * @param error      Error code
 163  * @return Human-readable error explanation
 164  */
 165 const gchar * purple_ssl_strerror(PurpleSslErrorType error);
 166
 167 /**
 168  * Makes a SSL connection to the specified host and port.  The caller
 169  * should keep track of the returned value and use it to cancel the
 170  * connection, if needed.
 171  *
 172  * @param account    The account making the connection.
 173  * @param host       The destination host.
 174  * @param port       The destination port.
 175  * @param func       The SSL input handler function.
 176  * @param error_func The SSL error handler function.  This function
 177  *                   should <strong>NOT</strong> call purple_ssl_close().  In
 178  *                   the event of an error the #PurpleSslConnection will be
 179  *                   destroyed for you.
 180  * @param data       User-defined data.
 181  *
 182  * @return The SSL connection handle.
 183  */
 184 PurpleSslConnection *purple_ssl_connect(PurpleAccount *account, const char *host,
 185                                                                         int port, PurpleSslInputFunction func,
 186                                                                         PurpleSslErrorFunction error_func,
 187                                                                         void *data);
 188
 189 /**
 190  * Makes a SSL connection to the specified host and port, using the separate
 191  * name to verify with the certificate.  The caller should keep track of the
 192  * returned value and use it to cancel the connection, if needed.
 193  *
 194  * @param account    The account making the connection.
 195  * @param host       The destination host.
 196  * @param port       The destination port.
 197  * @param func       The SSL input handler function.
 198  * @param error_func The SSL error handler function.  This function
 199  *                   should <strong>NOT</strong> call purple_ssl_close().  In
 200  *                   the event of an error the #PurpleSslConnection will be
 201  *                   destroyed for you.
 202  * @param ssl_host   The hostname of the other peer (to verify the CN)
 203  * @param data       User-defined data.
 204  *
 205  * @return The SSL connection handle.
 206  * @since 2.6.0
 207  */
 208 PurpleSslConnection *purple_ssl_connect_with_ssl_cn(PurpleAccount *account, const char *host,
 209                                                                         int port, PurpleSslInputFunction func,
 210                                                                         PurpleSslErrorFunction error_func,
 211                                                                         const char *ssl_host,
 212                                                                         void *data);
 213
 214 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_SSLCONN_C_)
 215 /**
 216  * Makes a SSL connection using an already open file descriptor.
 217  *
 218  * @deprecated Use purple_ssl_connect_with_host_fd() instead.
 219  *
 220  * @param account    The account making the connection.
 221  * @param fd         The file descriptor.
 222  * @param func       The SSL input handler function.
 223  * @param error_func The SSL error handler function.
 224  * @param data       User-defined data.
 225  *
 226  * @return The SSL connection handle.
 227  */
 228 PurpleSslConnection *purple_ssl_connect_fd(PurpleAccount *account, int fd,
 229                                                                            PurpleSslInputFunction func,
 230                                                                            PurpleSslErrorFunction error_func,
 231                                                                            void *data);
 232 #endif
 233
 234 /**
 235  * Makes a SSL connection using an already open file descriptor.
 236  *
 237  * @param account    The account making the connection.
 238  * @param fd         The file descriptor.
 239  * @param func       The SSL input handler function.
 240  * @param error_func The SSL error handler function.
 241  * @param host       The hostname of the other peer (to verify the CN)
 242  * @param data       User-defined data.
 243  *
 244  * @return The SSL connection handle.
 245  *
 246  * @since 2.2.0
 247  */
 248 PurpleSslConnection *purple_ssl_connect_with_host_fd(PurpleAccount *account, int fd,
 249                                            PurpleSslInputFunction func,
 250                                            PurpleSslErrorFunction error_func,
 251                                            const char *host,
 252                                            void *data);
 253
 254 /**
 255  * Adds an input watcher for the specified SSL connection.
 256  * Once the SSL handshake is complete, use this to watch for actual data across it.
 257  *
 258  * @param gsc   The SSL connection handle.
 259  * @param func  The callback function.
 260  * @param data  User-defined data.
 261  */
 262 void purple_ssl_input_add(PurpleSslConnection *gsc, PurpleSslInputFunction func,
 263                                                 void *data);
 264
 265 /**
 266  * Closes a SSL connection.
 267  *
 268  * @param gsc The SSL connection to close.
 269  */
 270 void purple_ssl_close(PurpleSslConnection *gsc);
 271
 272 /**
 273  * Reads data from an SSL connection.
 274  *
 275  * @param gsc    The SSL connection handle.
 276  * @param buffer The destination buffer.
 277  * @param len    The maximum number of bytes to read.
 278  *
 279  * @return The number of bytes read.
 280  */
 281 size_t purple_ssl_read(PurpleSslConnection *gsc, void *buffer, size_t len);
 282
 283 /**
 284  * Writes data to an SSL connection.
 285  *
 286  * @param gsc    The SSL connection handle.
 287  * @param buffer The buffer to write.
 288  * @param len    The length of the data to write.
 289  *
 290  * @return The number of bytes written.
 291  */
 292 size_t purple_ssl_write(PurpleSslConnection *gsc, const void *buffer, size_t len);
 293
 294 /**
 295  * Obtains the peer's presented certificates
 296  *
 297  * @param gsc    The SSL connection handle
 298  *
 299  * @return The peer certificate chain, in the order of certificate, issuer,
 300  *         issuer's issuer, etc. @a NULL if no certificates have been provided,
 301  *
 302  * @since 2.2.0
 303  */
 304 GList * purple_ssl_get_peer_certificates(PurpleSslConnection *gsc);
 305
 306 /*@}*/
 307
 308 /**************************************************************************/
 309 /** @name Subsystem API                                                   */
 310 /**************************************************************************/
 311 /*@{*/
 312
 313 /**
 314  * Sets the current SSL operations structure.
 315  *
 316  * @param ops The SSL operations structure to assign.
 317  */
 318 void purple_ssl_set_ops(PurpleSslOps *ops);
 319
 320 /**
 321  * Returns the current SSL operations structure.
 322  *
 323  * @return The SSL operations structure.
 324  */
 325 PurpleSslOps *purple_ssl_get_ops(void);
 326
 327 /**
 328  * Initializes the SSL subsystem.
 329  */
 330 void purple_ssl_init(void);
 331
 332 /**
 333  * Uninitializes the SSL subsystem.
 334  */
 335 void purple_ssl_uninit(void);
 336
 337 /*@}*/
 338
 339 #ifdef __cplusplus
 340 }
 341 #endif
 342
 343 #endif /* _PURPLE_SSLCONN_H_ */