sslconn.h File Reference
libpurple

SSL API. More...

`#include "certificate.h"`
`#include "proxy.h"`

Go to the source code of this file.

## Data Structures

struct | _PurpleSslConnection
struct | PurpleSslOps
| SSL implementation operations structure. More...

## Macros

#define | PURPLE_SSL_DEFAULT_PORT 443

## Typedefs

typedef struct _PurpleSslConnection | PurpleSslConnection
typedef void(* | PurpleSslInputFunction) (gpointer, PurpleSslConnection *, PurpleInputCondition)
typedef void(* | PurpleSslErrorFunction) (PurpleSslConnection *, PurpleSslErrorType, gpointer)

## Enumerations

enum | PurpleSslErrorType { PURPLE_SSL_HANDSHAKE_FAILED = 1 , PURPLE_SSL_CONNECT_FAILED = 2 , PURPLE_SSL_CERTIFICATE_INVALID = 3 }
| Possible SSL errors.

## Functions

SSL API <br>
gboolean | purple_ssl_is_supported (void)
| Returns whether or not SSL is currently supported. More...
const gchar * | purple_ssl_strerror (PurpleSslErrorType error)
| Returns a human-readable string for an SSL error. More...
PurpleSslConnection * | purple_ssl_connect (PurpleAccount *account, const char *host, int port, PurpleSslInputFunction func, PurpleSslErrorFunction error_func, void *data)
| Makes a SSL connection to the specified host and port. More...
PurpleSslConnection * | purple_ssl_connect_with_ssl_cn (PurpleAccount *account, const char *host, int port, PurpleSslInputFunction func, PurpleSslErrorFunction error_func, const char *ssl_host, void *data)
| Makes a SSL connection to the specified host and port, using the separate name to verify with the certificate. More...
PurpleSslConnection * | purple_ssl_connect_fd (PurpleAccount *account, int fd, PurpleSslInputFunction func, PurpleSslErrorFunction error_func, void *data)
| Makes a SSL connection using an already open file descriptor. More...
PurpleSslConnection * | purple_ssl_connect_with_host_fd (PurpleAccount *account, int fd, PurpleSslInputFunction func, PurpleSslErrorFunction error_func, const char *host, void *data)
| Makes a SSL connection using an already open file descriptor. More...
void | purple_ssl_input_add (PurpleSslConnection *gsc, PurpleSslInputFunction func, void *data)
| Adds an input watcher for the specified SSL connection. More...
void | purple_ssl_close (PurpleSslConnection *gsc)
| Closes a SSL connection. More...
size_t | purple_ssl_read (PurpleSslConnection *gsc, void *buffer, size_t len)
| Reads data from an SSL connection. More...
size_t | purple_ssl_write (PurpleSslConnection *gsc, const void *buffer, size_t len)
| Writes data to an SSL connection. More...
GList * | purple_ssl_get_peer_certificates (PurpleSslConnection *gsc)
| Obtains the peer's presented certificates. More...
Subsystem API <br>
void | purple_ssl_set_ops (PurpleSslOps *ops)
| Sets the current SSL operations structure. More...
PurpleSslOps * | purple_ssl_get_ops (void)
| Returns the current SSL operations structure. More...
void | purple_ssl_init (void)
| Initializes the SSL subsystem.
void | purple_ssl_uninit (void)
| Uninitializes the SSL subsystem.

## Detailed Description

SSL API.

Definition in file sslconn.h.

## Typedef Documentation

## PurpleSslConnection

typedef struct _PurpleSslConnection PurpleSslConnection

Definition at line 1 of file sslconn.h.

## Function Documentation

## purple_ssl_close()

void purple_ssl_close | ( | PurpleSslConnection * | gsc | ) |

Closes a SSL connection.

Parameters

  gsc | The SSL connection to close.

## purple_ssl_connect()

PurpleSslConnection* purple_ssl_connect | ( | PurpleAccount * | account,
|  | const char * | host,
|  | int | port,
|  | PurpleSslInputFunction | func,
|  | PurpleSslErrorFunction | error_func,
|  | void * | data
| ) |  |

Makes a SSL connection to the specified host and port.

The caller should keep track of the returned value and use it to cancel the connection, if needed.

Parameters

  account | The account making the connection.
  host | The destination host.
  port | The destination port.
  func | The SSL input handler function.
  error_func | The SSL error handler function. This function should NOT call purple_ssl_close(). In the event of an error the PurpleSslConnection will be destroyed for you.
  data | User-defined data.

Returns
  The SSL connection handle.

## purple_ssl_connect_fd()

PurpleSslConnection* purple_ssl_connect_fd | ( | PurpleAccount * | account,
|  | int | fd,
|  | PurpleSslInputFunction | func,
|  | PurpleSslErrorFunction | error_func,
|  | void * | data
| ) |  |

Makes a SSL connection using an already open file descriptor.

Deprecated:
  Use purple_ssl_connect_with_host_fd() instead.

Parameters

  account | The account making the connection.
  fd | The file descriptor.
  func | The SSL input handler function.
  error_func | The SSL error handler function.
  data | User-defined data.

Returns
  The SSL connection handle.

## purple_ssl_connect_with_host_fd()

PurpleSslConnection* purple_ssl_connect_with_host_fd | ( | PurpleAccount * | account,
|  | int | fd,
|  | PurpleSslInputFunction | func,
|  | PurpleSslErrorFunction | error_func,
|  | const char * | host,
|  | void * | data
| ) |  |

Makes a SSL connection using an already open file descriptor.

Parameters

  account | The account making the connection.
  fd | The file descriptor.
  func | The SSL input handler function.
  error_func | The SSL error handler function.
  host | The hostname of the other peer (to verify the CN)
  data | User-defined data.

Returns
  The SSL connection handle.

Since
  2.2.0

## purple_ssl_connect_with_ssl_cn()

PurpleSslConnection* purple_ssl_connect_with_ssl_cn | ( | PurpleAccount * | account,
|  | const char * | host,
|  | int | port,
|  | PurpleSslInputFunction | func,
|  | PurpleSslErrorFunction | error_func,
|  | const char * | ssl_host,
|  | void * | data
| ) |  |

Makes a SSL connection to the specified host and port, using the separate name to verify with the certificate.

The caller should keep track of the returned value and use it to cancel the connection, if needed.

Parameters

  account | The account making the connection.
  host | The destination host.
  port | The destination port.
  func | The SSL input handler function.
  error_func | The SSL error handler function. This function should NOT call purple_ssl_close(). In the event of an error the PurpleSslConnection will be destroyed for you.
  ssl_host | The hostname of the other peer (to verify the CN)
  data | User-defined data.

Returns
  The SSL connection handle.

Since
  2.6.0

## purple_ssl_get_ops()

PurpleSslOps* purple_ssl_get_ops | ( | void |  | ) |

Returns the current SSL operations structure.

Returns
  The SSL operations structure.

## purple_ssl_get_peer_certificates()

GList* purple_ssl_get_peer_certificates | ( | PurpleSslConnection * | gsc | ) |

Obtains the peer's presented certificates.

Parameters

  gsc | The SSL connection handle

Returns
  The peer certificate chain, in the order of certificate, issuer, issuer's issuer, etc. NULL if no certificates have been provided,

Since
  2.2.0

## purple_ssl_input_add()

void purple_ssl_input_add | ( | PurpleSslConnection * | gsc,
|  | PurpleSslInputFunction | func,
|  | void * | data
| ) |  |

Adds an input watcher for the specified SSL connection.

Once the SSL handshake is complete, use this to watch for actual data across it.

Parameters

  gsc | The SSL connection handle.
  func | The callback function.
  data | User-defined data.

## purple_ssl_is_supported()

gboolean purple_ssl_is_supported | ( | void |  | ) |

Returns whether or not SSL is currently supported.

Returns
  TRUE if SSL is supported, or FALSE otherwise.

## purple_ssl_read()

size_t purple_ssl_read | ( | PurpleSslConnection * | gsc,
|  | void * | buffer,
|  | size_t | len
| ) |  |

Reads data from an SSL connection.

Parameters

  gsc | The SSL connection handle.
  buffer | The destination buffer.
  len | The maximum number of bytes to read.

Returns
  The number of bytes read.

## purple_ssl_set_ops()

void purple_ssl_set_ops | ( | PurpleSslOps * | ops | ) |

Sets the current SSL operations structure.

Parameters

  ops | The SSL operations structure to assign.

## purple_ssl_strerror()

const gchar* purple_ssl_strerror | ( | PurpleSslErrorType | error | ) |

Returns a human-readable string for an SSL error.

Parameters

  error | Error code

Returns
  Human-readable error explanation

## purple_ssl_write()

size_t purple_ssl_write | ( | PurpleSslConnection * | gsc,
|  | const void * | buffer,
|  | size_t | len
| ) |  |

Writes data to an SSL connection.

Parameters

  gsc | The SSL connection handle.
  buffer | The buffer to write.
  len | The length of the data to write.

Returns
  The number of bytes written.