libpurple/sslconn.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef _PURPLE_SSLCONN_H_
  23 #define _PURPLE_SSLCONN_H_
  24 /**
  25  * SECTION:sslconn
  26  * @section_id: libpurple-sslconn
  27  * @short_description: <filename>sslconn.h</filename>
  28  * @title: SSL API
  29  */
  30
  31 /**
  32  * PurpleSslErrorType:
  33  * @PURPLE_SSL_HANDSHAKE_FAILED: The handshake failed
  34  * @PURPLE_SSL_CONNECT_FAILED: The connection failed
  35  * @PURPLE_SSL_CERTIFICATE_INVALID: The certificated is invalid
  36  *
  37  * Possible SSL errors.
  38  */
  39 typedef enum
  40 {
  41         PURPLE_SSL_HANDSHAKE_FAILED = 1,
  42         PURPLE_SSL_CONNECT_FAILED = 2,
  43         PURPLE_SSL_CERTIFICATE_INVALID = 3
  44 } PurpleSslErrorType;
  45
  46 #include <gio/gio.h>
  47 #include "proxy.h"
  48
  49 #define PURPLE_SSL_DEFAULT_PORT 443
  50
  51 typedef struct _PurpleSslConnection PurpleSslConnection;
  52
  53 typedef void (*PurpleSslInputFunction)(gpointer, PurpleSslConnection *,
  54                                                                          PurpleInputCondition);
  55 typedef void (*PurpleSslErrorFunction)(PurpleSslConnection *, PurpleSslErrorType,
  56                                                                          gpointer);
  57
  58 /**
  59  * PurpleSslConnection:
  60  * @host:            Hostname to which the SSL connection will be made
  61  * @port:            Port to connect to
  62  * @connect_cb_data: Data to pass to @connect_cb
  63  * @connect_cb:      Callback triggered once the SSL handshake is complete
  64  * @error_cb:        Callback triggered if there is an error during connection
  65  * @recv_cb_data:    Data passed to @recv_cb
  66  * @recv_cb:         User-defined callback executed when the SSL connection
  67  *                   receives data
  68  * @fd:              File descriptor used to refer to the socket
  69  * @inpa:            Glib event source ID; used to refer to the received data
  70  *                   callback in the glib eventloop
  71  * @connect_data:    Data related to the underlying TCP connection
  72  * @conn:            The underlying #GTlsConnection
  73  * @cancellable:     A cancellable to call when cancelled
  74  * @private_data:    Internal connection data managed by the SSL backend
  75  *                   (GnuTLS/LibNSS/whatever)
  76  */
  77 struct _PurpleSslConnection
  78 {
  79         char *host;
  80         int port;
  81         void *connect_cb_data;
  82         PurpleSslInputFunction connect_cb;
  83         PurpleSslErrorFunction error_cb;
  84         void *recv_cb_data;
  85         PurpleSslInputFunction recv_cb;
  86
  87         int fd;
  88         guint inpa;
  89         PurpleProxyConnectData *connect_data;
  90
  91         GTlsConnection *conn;
  92         GCancellable *cancellable;
  93
  94         void *private_data;
  95 };
  96
  97 G_BEGIN_DECLS
  98
  99 /**************************************************************************/
 100 /* SSL API                                                                */
 101 /**************************************************************************/
 102
 103 /**
 104  * purple_ssl_strerror:
 105  * @error:      Error code
 106  *
 107  * Returns a human-readable string for an SSL error.
 108  *
 109  * Returns: Human-readable error explanation
 110  */
 111 const gchar * purple_ssl_strerror(PurpleSslErrorType error);
 112
 113 /**
 114  * purple_ssl_connect:
 115  * @account:    The account making the connection.
 116  * @host:       The destination host.
 117  * @port:       The destination port.
 118  * @func:       The SSL input handler function.
 119  * @error_func: The SSL error handler function.  This function
 120  *              should <emphasis>NOT</emphasis> call purple_ssl_close(). In
 121  *              the event of an error the #PurpleSslConnection will be
 122  *              destroyed for you.
 123  * @data:       User-defined data.
 124  *
 125  * Makes a SSL connection to the specified host and port.  The caller
 126  * should keep track of the returned value and use it to cancel the
 127  * connection, if needed.
 128  *
 129  * Returns: The SSL connection handle.
 130  */
 131 PurpleSslConnection *purple_ssl_connect(PurpleAccount *account, const char *host,
 132                                                                         int port, PurpleSslInputFunction func,
 133                                                                         PurpleSslErrorFunction error_func,
 134                                                                         void *data);
 135
 136 /**
 137  * purple_ssl_connect_with_ssl_cn:
 138  * @account:    The account making the connection.
 139  * @host:       The destination host.
 140  * @port:       The destination port.
 141  * @func:       The SSL input handler function.
 142  * @error_func: The SSL error handler function.  This function
 143  *              should <emphasis>NOT</emphasis> call purple_ssl_close(). In
 144  *              the event of an error the #PurpleSslConnection will be
 145  *              destroyed for you.
 146  * @ssl_host:   The hostname of the other peer (to verify the CN)
 147  * @data:       User-defined data.
 148  *
 149  * Makes a SSL connection to the specified host and port, using the separate
 150  * name to verify with the certificate.  The caller should keep track of the
 151  * returned value and use it to cancel the connection, if needed.
 152  *
 153  * Returns: The SSL connection handle.
 154  */
 155 PurpleSslConnection *purple_ssl_connect_with_ssl_cn(PurpleAccount *account, const char *host,
 156                                                                         int port, PurpleSslInputFunction func,
 157                                                                         PurpleSslErrorFunction error_func,
 158                                                                         const char *ssl_host,
 159                                                                         void *data);
 160
 161 /**
 162  * purple_ssl_connect_with_host_fd:
 163  * @account:    The account making the connection.
 164  * @fd:         The file descriptor.
 165  * @func:       The SSL input handler function.
 166  * @error_func: The SSL error handler function.
 167  * @host:       The hostname of the other peer (to verify the CN)
 168  * @data:       User-defined data.
 169  *
 170  * Makes a SSL connection using an already open file descriptor.
 171  *
 172  * Returns: The SSL connection handle.
 173  */
 174 PurpleSslConnection *purple_ssl_connect_with_host_fd(PurpleAccount *account, int fd,
 175                                            PurpleSslInputFunction func,
 176                                            PurpleSslErrorFunction error_func,
 177                                            const char *host,
 178                                            void *data);
 179
 180 /**
 181  * purple_ssl_input_add:
 182  * @gsc:   The SSL connection handle.
 183  * @func:  The callback function.
 184  * @data:  User-defined data.
 185  *
 186  * Adds an input watcher for the specified SSL connection.
 187  * Once the SSL handshake is complete, use this to watch for actual data across it.
 188  */
 189 void purple_ssl_input_add(PurpleSslConnection *gsc, PurpleSslInputFunction func,
 190                                                 void *data);
 191
 192 /**
 193  * purple_ssl_input_remove:
 194  * @gsc: The SSL connection handle.
 195  *
 196  * Removes an input watcher, added with purple_ssl_input_add().
 197  *
 198  * If there is no input watcher set, does nothing.
 199  */
 200 void
 201 purple_ssl_input_remove(PurpleSslConnection *gsc);
 202
 203 /**
 204  * purple_ssl_close:
 205  * @gsc: The SSL connection to close.
 206  *
 207  * Closes a SSL connection.
 208  */
 209 void purple_ssl_close(PurpleSslConnection *gsc);
 210
 211 /**
 212  * purple_ssl_read:
 213  * @gsc:    The SSL connection handle.
 214  * @buffer: The destination buffer.
 215  * @len:    The maximum number of bytes to read.
 216  *
 217  * Reads data from an SSL connection.
 218  *
 219  * Returns: The number of bytes read.
 220  */
 221 size_t purple_ssl_read(PurpleSslConnection *gsc, void *buffer, size_t len);
 222
 223 /**
 224  * purple_ssl_write:
 225  * @gsc:    The SSL connection handle.
 226  * @buffer: The buffer to write.
 227  * @len:    The length of the data to write.
 228  *
 229  * Writes data to an SSL connection.
 230  *
 231  * Returns: The number of bytes written.
 232  */
 233 size_t purple_ssl_write(PurpleSslConnection *gsc, const void *buffer, size_t len);
 234
 235 /**
 236  * purple_ssl_get_peer_certificates:
 237  * @gsc:    The SSL connection handle
 238  *
 239  * Obtains the peer's presented certificates
 240  *
 241  * Returns: The peer certificate chain, in the order of certificate, issuer,
 242  *         issuer's issuer, etc. %NULL if no certificates have been provided,
 243  */
 244 GList * purple_ssl_get_peer_certificates(PurpleSslConnection *gsc);
 245
 246 /**************************************************************************/
 247 /* Subsystem API                                                          */
 248 /**************************************************************************/
 249
 250 /**
 251  * purple_ssl_init:
 252  *
 253  * Initializes the SSL subsystem.
 254  */
 255 void purple_ssl_init(void);
 256
 257 /**
 258  * purple_ssl_uninit:
 259  *
 260  * Uninitializes the SSL subsystem.
 261  */
 262 void purple_ssl_uninit(void);
 263
 264 G_END_DECLS
 265
 266 #endif /* _PURPLE_SSLCONN_H_ */