## soup-ssl

soup-ssl — SSL/TLS handling

## Synopsis

    extern              gboolean soup_ssl_supported;

    enum                SoupSSLType;
    typedef             SoupSSLCredentials;
    SoupSSLCredentials* soup_ssl_get_client_credentials     (const char *ca_file);
    void                soup_ssl_free_client_credentials    (SoupSSLCredentials *creds);
    SoupSSLCredentials* soup_ssl_get_server_credentials     (const char *cert_file,
                                                             const char *key_file);
    void                soup_ssl_free_server_credentials    (SoupSSLCredentials *creds);
    GIOChannel*         soup_ssl_wrap_iochannel             (GIOChannel *sock,
                                                             SoupSSLType type,
                                                             const char *remote_host,
                                                             SoupSSLCredentials *creds);
    #define             SOUP_SSL_ERROR
    GQuark              soup_ssl_error_quark                (void);
    enum                SoupSocketError;

## Description

## Details

### soup_ssl_supported

    extern gboolean soup_ssl_supported;

Can be used to test if libsoup was compiled with ssl support.

### enum SoupSSLType

    typedef enum {
    	SOUP_SSL_TYPE_CLIENT = 0,
    	SOUP_SSL_TYPE_SERVER
    } SoupSSLType;

What kind of SSL connection this is.

`SOUP_SSL_TYPE_CLIENT` | the client side of an SSL connection
`SOUP_SSL_TYPE_SERVER` | the server side of an SSL connection

### SoupSSLCredentials

    typedef struct SoupSSLCredentials SoupSSLCredentials;

### soup_ssl_get_client_credentials ()

    SoupSSLCredentials* soup_ssl_get_client_credentials     (const char *ca_file);

Creates an opaque client credentials object which can later be passed to `soup_ssl_wrap_iochannel()`.

If `ca_file` is non-`NULL`, any certificate received from a server must be signed by one of the CAs in the file, or an error will be returned.

`ca_file` : | path to a file containing X509-encoded Certificate Authority certificates.
Returns : | the client credentials, which must be freed with `soup_ssl_free_client_credentials()`.

### soup_ssl_free_client_credentials ()

    void                soup_ssl_free_client_credentials    (SoupSSLCredentials *creds);

Frees `creds`.

`creds` : | a client credentials structure returned by `soup_ssl_get_client_credentials()`.

### soup_ssl_get_server_credentials ()

    SoupSSLCredentials* soup_ssl_get_server_credentials     (const char *cert_file,
                                                             const char *key_file);

Creates an opaque server credentials object which can later be passed to `soup_ssl_wrap_iochannel()`.

`cert_file` : | path to a file containing an X509-encoded server certificate
`key_file` : | path to a file containing an X509-encoded key for `cert_file`.
Returns : | the server credentials, which must be freed with `soup_ssl_free_server_credentials()`.

### soup_ssl_free_server_credentials ()

    void                soup_ssl_free_server_credentials    (SoupSSLCredentials *creds);

Frees `creds`.

`creds` : | a server credentials structure returned by `soup_ssl_get_server_credentials()`.

### soup_ssl_wrap_iochannel ()

    GIOChannel*         soup_ssl_wrap_iochannel             (GIOChannel *sock,
                                                             SoupSSLType type,
                                                             const char *remote_host,
                                                             SoupSSLCredentials *creds);

This attempts to wrap a new GIOChannel around `sock` that will SSL-encrypt/decrypt all traffic through it.

`sock` : | a GIOChannel wrapping a TCP socket.
`type` : | whether this is a client or server socket
`remote_host` : | the hostname of the remote machine
`creds` : | a client or server credentials structure
Returns : | an SSL-encrypting GIOChannel, or `NULL` on failure.

### SOUP_SSL_ERROR

    #define SOUP_SSL_ERROR soup_ssl_error_quark()

### soup_ssl_error_quark ()

    GQuark              soup_ssl_error_quark                (void);

Returns : | The quark used as `SOUP_SSL_ERROR`

### enum SoupSocketError

    typedef enum {
    	SOUP_SSL_ERROR_HANDSHAKE_NEEDS_READ,
    	SOUP_SSL_ERROR_HANDSHAKE_NEEDS_WRITE,
    	SOUP_SSL_ERROR_CERTIFICATE,
    } SoupSocketError;