1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/sslconn.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,343 @@
1.4 +/**
1.5 + * @file sslconn.h SSL API
1.6 + * @ingroup core
1.7 + */
1.8 +
1.9 +/* purple
1.10 + *
1.11 + * Purple is the legal property of its developers, whose names are too numerous
1.12 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.13 + * source distribution.
1.14 + *
1.15 + * This program is free software; you can redistribute it and/or modify
1.16 + * it under the terms of the GNU General Public License as published by
1.17 + * the Free Software Foundation; either version 2 of the License, or
1.18 + * (at your option) any later version.
1.19 + *
1.20 + * This program is distributed in the hope that it will be useful,
1.21 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.22 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.23 + * GNU General Public License for more details.
1.24 + *
1.25 + * You should have received a copy of the GNU General Public License
1.26 + * along with this program; if not, write to the Free Software
1.27 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.28 + */
1.29 +#ifndef _PURPLE_SSLCONN_H_
1.30 +#define _PURPLE_SSLCONN_H_
1.31 +
1.32 +/** Possible SSL errors. */
1.33 +typedef enum
1.34 +{
1.35 + PURPLE_SSL_HANDSHAKE_FAILED = 1,
1.36 + PURPLE_SSL_CONNECT_FAILED = 2,
1.37 + PURPLE_SSL_CERTIFICATE_INVALID = 3
1.38 +} PurpleSslErrorType;
1.39 +
1.40 +#include "certificate.h"
1.41 +#include "proxy.h"
1.42 +
1.43 +#define PURPLE_SSL_DEFAULT_PORT 443
1.44 +
1.45 +/** @copydoc _PurpleSslConnection */
1.46 +typedef struct _PurpleSslConnection PurpleSslConnection;
1.47 +
1.48 +typedef void (*PurpleSslInputFunction)(gpointer, PurpleSslConnection *,
1.49 + PurpleInputCondition);
1.50 +typedef void (*PurpleSslErrorFunction)(PurpleSslConnection *, PurpleSslErrorType,
1.51 + gpointer);
1.52 +
1.53 +struct _PurpleSslConnection
1.54 +{
1.55 + /** Hostname to which the SSL connection will be made */
1.56 + char *host;
1.57 + /** Port to connect to */
1.58 + int port;
1.59 + /** Data to pass to PurpleSslConnection::connect_cb() */
1.60 + void *connect_cb_data;
1.61 + /** Callback triggered once the SSL handshake is complete */
1.62 + PurpleSslInputFunction connect_cb;
1.63 + /** Callback triggered if there is an error during connection */
1.64 + PurpleSslErrorFunction error_cb;
1.65 + /** Data passed to PurpleSslConnection::recv_cb() */
1.66 + void *recv_cb_data;
1.67 + /** User-defined callback executed when the SSL connection receives data */
1.68 + PurpleSslInputFunction recv_cb;
1.69 +
1.70 + /** File descriptor used to refer to the socket */
1.71 + int fd;
1.72 + /** Glib event source ID; used to refer to the received data callback
1.73 + * in the glib eventloop */
1.74 + guint inpa;
1.75 + /** Data related to the underlying TCP connection */
1.76 + PurpleProxyConnectData *connect_data;
1.77 +
1.78 + /** Internal connection data managed by the SSL backend (GnuTLS/LibNSS/whatever) */
1.79 + void *private_data;
1.80 +
1.81 + /** Verifier to use in authenticating the peer */
1.82 + PurpleCertificateVerifier *verifier;
1.83 +};
1.84 +
1.85 +/**
1.86 + * SSL implementation operations structure.
1.87 + *
1.88 + * Every SSL implementation must provide all of these and register it via purple_ssl_set_ops()
1.89 + * These should not be called directly! Instead, use the purple_ssl_* functions.
1.90 + */
1.91 +typedef struct
1.92 +{
1.93 + /** Initializes the SSL system provided.
1.94 + * @return @a TRUE if initialization succeeded
1.95 + * @see purple_ssl_init
1.96 + */
1.97 + gboolean (*init)(void);
1.98 + /** Unloads the SSL system. Inverse of PurpleSslOps::init.
1.99 + * @see purple_ssl_uninit
1.100 + */
1.101 + void (*uninit)(void);
1.102 + /** Sets up the SSL connection for a #PurpleSslConnection once
1.103 + * the TCP connection has been established
1.104 + * @see purple_ssl_connect
1.105 + */
1.106 + void (*connectfunc)(PurpleSslConnection *gsc);
1.107 + /** Destroys the internal data of the SSL connection provided.
1.108 + * Freeing gsc itself is left to purple_ssl_close()
1.109 + * @see purple_ssl_close
1.110 + */
1.111 + void (*close)(PurpleSslConnection *gsc);
1.112 + /** Reads data from a connection (like POSIX read())
1.113 + * @param gsc Connection context
1.114 + * @param data Pointer to buffer to drop data into
1.115 + * @param len Maximum number of bytes to read
1.116 + * @return Number of bytes actually written into @a data (which may be
1.117 + * less than @a len), or <0 on error
1.118 + * @see purple_ssl_read
1.119 + */
1.120 + size_t (*read)(PurpleSslConnection *gsc, void *data, size_t len);
1.121 + /** Writes data to a connection (like POSIX send())
1.122 + * @param gsc Connection context
1.123 + * @param data Data buffer to send data from
1.124 + * @param len Number of bytes to send from buffer
1.125 + * @return The number of bytes written to @a data (may be less than
1.126 + * @a len) or <0 on error
1.127 + * @see purple_ssl_write
1.128 + */
1.129 + size_t (*write)(PurpleSslConnection *gsc, const void *data, size_t len);
1.130 + /** Obtains the certificate chain provided by the peer
1.131 + *
1.132 + * @param gsc Connection context
1.133 + * @return A newly allocated list containing the certificates
1.134 + * the peer provided.
1.135 + * @see PurpleCertificate
1.136 + * @todo Decide whether the ordering of certificates in this
1.137 + * list can be guaranteed.
1.138 + */
1.139 + GList * (* get_peer_certificates)(PurpleSslConnection * gsc);
1.140 +
1.141 + void (*_purple_reserved2)(void);
1.142 + void (*_purple_reserved3)(void);
1.143 + void (*_purple_reserved4)(void);
1.144 +} PurpleSslOps;
1.145 +
1.146 +#ifdef __cplusplus
1.147 +extern "C" {
1.148 +#endif
1.149 +
1.150 +/**************************************************************************/
1.151 +/** @name SSL API */
1.152 +/**************************************************************************/
1.153 +/*@{*/
1.154 +
1.155 +/**
1.156 + * Returns whether or not SSL is currently supported.
1.157 + *
1.158 + * @return @a TRUE if SSL is supported, or @a FALSE otherwise.
1.159 + */
1.160 +gboolean purple_ssl_is_supported(void);
1.161 +
1.162 +/**
1.163 + * Returns a human-readable string for an SSL error.
1.164 + *
1.165 + * @param error Error code
1.166 + * @return Human-readable error explanation
1.167 + */
1.168 +const gchar * purple_ssl_strerror(PurpleSslErrorType error);
1.169 +
1.170 +/**
1.171 + * Makes a SSL connection to the specified host and port. The caller
1.172 + * should keep track of the returned value and use it to cancel the
1.173 + * connection, if needed.
1.174 + *
1.175 + * @param account The account making the connection.
1.176 + * @param host The destination host.
1.177 + * @param port The destination port.
1.178 + * @param func The SSL input handler function.
1.179 + * @param error_func The SSL error handler function. This function
1.180 + * should <strong>NOT</strong> call purple_ssl_close(). In
1.181 + * the event of an error the #PurpleSslConnection will be
1.182 + * destroyed for you.
1.183 + * @param data User-defined data.
1.184 + *
1.185 + * @return The SSL connection handle.
1.186 + */
1.187 +PurpleSslConnection *purple_ssl_connect(PurpleAccount *account, const char *host,
1.188 + int port, PurpleSslInputFunction func,
1.189 + PurpleSslErrorFunction error_func,
1.190 + void *data);
1.191 +
1.192 +/**
1.193 + * Makes a SSL connection to the specified host and port, using the separate
1.194 + * name to verify with the certificate. The caller should keep track of the
1.195 + * returned value and use it to cancel the connection, if needed.
1.196 + *
1.197 + * @param account The account making the connection.
1.198 + * @param host The destination host.
1.199 + * @param port The destination port.
1.200 + * @param func The SSL input handler function.
1.201 + * @param error_func The SSL error handler function. This function
1.202 + * should <strong>NOT</strong> call purple_ssl_close(). In
1.203 + * the event of an error the #PurpleSslConnection will be
1.204 + * destroyed for you.
1.205 + * @param ssl_host The hostname of the other peer (to verify the CN)
1.206 + * @param data User-defined data.
1.207 + *
1.208 + * @return The SSL connection handle.
1.209 + * @since 2.6.0
1.210 + */
1.211 +PurpleSslConnection *purple_ssl_connect_with_ssl_cn(PurpleAccount *account, const char *host,
1.212 + int port, PurpleSslInputFunction func,
1.213 + PurpleSslErrorFunction error_func,
1.214 + const char *ssl_host,
1.215 + void *data);
1.216 +
1.217 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_SSLCONN_C_)
1.218 +/**
1.219 + * Makes a SSL connection using an already open file descriptor.
1.220 + *
1.221 + * @deprecated Use purple_ssl_connect_with_host_fd() instead.
1.222 + *
1.223 + * @param account The account making the connection.
1.224 + * @param fd The file descriptor.
1.225 + * @param func The SSL input handler function.
1.226 + * @param error_func The SSL error handler function.
1.227 + * @param data User-defined data.
1.228 + *
1.229 + * @return The SSL connection handle.
1.230 + */
1.231 +PurpleSslConnection *purple_ssl_connect_fd(PurpleAccount *account, int fd,
1.232 + PurpleSslInputFunction func,
1.233 + PurpleSslErrorFunction error_func,
1.234 + void *data);
1.235 +#endif
1.236 +
1.237 +/**
1.238 + * Makes a SSL connection using an already open file descriptor.
1.239 + *
1.240 + * @param account The account making the connection.
1.241 + * @param fd The file descriptor.
1.242 + * @param func The SSL input handler function.
1.243 + * @param error_func The SSL error handler function.
1.244 + * @param host The hostname of the other peer (to verify the CN)
1.245 + * @param data User-defined data.
1.246 + *
1.247 + * @return The SSL connection handle.
1.248 + *
1.249 + * @since 2.2.0
1.250 + */
1.251 +PurpleSslConnection *purple_ssl_connect_with_host_fd(PurpleAccount *account, int fd,
1.252 + PurpleSslInputFunction func,
1.253 + PurpleSslErrorFunction error_func,
1.254 + const char *host,
1.255 + void *data);
1.256 +
1.257 +/**
1.258 + * Adds an input watcher for the specified SSL connection.
1.259 + * Once the SSL handshake is complete, use this to watch for actual data across it.
1.260 + *
1.261 + * @param gsc The SSL connection handle.
1.262 + * @param func The callback function.
1.263 + * @param data User-defined data.
1.264 + */
1.265 +void purple_ssl_input_add(PurpleSslConnection *gsc, PurpleSslInputFunction func,
1.266 + void *data);
1.267 +
1.268 +/**
1.269 + * Closes a SSL connection.
1.270 + *
1.271 + * @param gsc The SSL connection to close.
1.272 + */
1.273 +void purple_ssl_close(PurpleSslConnection *gsc);
1.274 +
1.275 +/**
1.276 + * Reads data from an SSL connection.
1.277 + *
1.278 + * @param gsc The SSL connection handle.
1.279 + * @param buffer The destination buffer.
1.280 + * @param len The maximum number of bytes to read.
1.281 + *
1.282 + * @return The number of bytes read.
1.283 + */
1.284 +size_t purple_ssl_read(PurpleSslConnection *gsc, void *buffer, size_t len);
1.285 +
1.286 +/**
1.287 + * Writes data to an SSL connection.
1.288 + *
1.289 + * @param gsc The SSL connection handle.
1.290 + * @param buffer The buffer to write.
1.291 + * @param len The length of the data to write.
1.292 + *
1.293 + * @return The number of bytes written.
1.294 + */
1.295 +size_t purple_ssl_write(PurpleSslConnection *gsc, const void *buffer, size_t len);
1.296 +
1.297 +/**
1.298 + * Obtains the peer's presented certificates
1.299 + *
1.300 + * @param gsc The SSL connection handle
1.301 + *
1.302 + * @return The peer certificate chain, in the order of certificate, issuer,
1.303 + * issuer's issuer, etc. @a NULL if no certificates have been provided,
1.304 + *
1.305 + * @since 2.2.0
1.306 + */
1.307 +GList * purple_ssl_get_peer_certificates(PurpleSslConnection *gsc);
1.308 +
1.309 +/*@}*/
1.310 +
1.311 +/**************************************************************************/
1.312 +/** @name Subsystem API */
1.313 +/**************************************************************************/
1.314 +/*@{*/
1.315 +
1.316 +/**
1.317 + * Sets the current SSL operations structure.
1.318 + *
1.319 + * @param ops The SSL operations structure to assign.
1.320 + */
1.321 +void purple_ssl_set_ops(PurpleSslOps *ops);
1.322 +
1.323 +/**
1.324 + * Returns the current SSL operations structure.
1.325 + *
1.326 + * @return The SSL operations structure.
1.327 + */
1.328 +PurpleSslOps *purple_ssl_get_ops(void);
1.329 +
1.330 +/**
1.331 + * Initializes the SSL subsystem.
1.332 + */
1.333 +void purple_ssl_init(void);
1.334 +
1.335 +/**
1.336 + * Uninitializes the SSL subsystem.
1.337 + */
1.338 +void purple_ssl_uninit(void);
1.339 +
1.340 +/*@}*/
1.341 +
1.342 +#ifdef __cplusplus
1.343 +}
1.344 +#endif
1.345 +
1.346 +#endif /* _PURPLE_SSLCONN_H_ */