Wocky OpenSSL TLS

## Wocky OpenSSL TLS Wocky OpenSSL TLS — Establish TLS sessions |

## Synopsis

    #define             WOCKY_TYPE_TLS_CONNECTION
    #define             WOCKY_TYPE_TLS_SESSION
    #define             WOCKY_TLS_SESSION                   (inst)
    #define             WOCKY_TLS_CONNECTION                (inst)
                        WockyTLSConnection;
                        WockyTLSSession;
    enum                WockyTLSVerificationLevel;
    GQuark              wocky_tls_cert_error_quark          (void);
    #define             WOCKY_TLS_CERT_ERROR
    GQuark              wocky_tls_error_quark               (void);
    #define             WOCKY_TLS_ERROR
    enum                WockyTLSCertStatus;
    enum                WockyTLSCertType;
    GType               wocky_tls_connection_get_type       (void);
    GType               wocky_tls_session_get_type          (void);
    int                 wocky_tls_session_verify_peer       (WockyTLSSession *session,
                                                             const gchar *peername,
                                                             WockyTLSVerificationLevel level,
                                                             WockyTLSCertStatus *status);
    GPtrArray *         wocky_tls_session_get_peers_certificate
                                                            (WockyTLSSession *session,
                                                             WockyTLSCertType *type);
    WockyTLSConnection * wocky_tls_session_handshake        (WockyTLSSession *session,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                wocky_tls_session_handshake_async   (WockyTLSSession *session,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    WockyTLSConnection * wocky_tls_session_handshake_finish (WockyTLSSession *session,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                wocky_tls_session_add_ca            (WockyTLSSession *session,
                                                             const gchar *path);
    void                wocky_tls_session_add_crl           (WockyTLSSession *session,
                                                             const gchar *path);
    WockyTLSSession *   wocky_tls_session_new               (GIOStream *stream);
    WockyTLSSession *   wocky_tls_session_server_new        (GIOStream *stream,
                                                             guint dhbits,
                                                             const gchar *key,
                                                             const gchar *cert);

## Object Hierarchy

      GObject
       +----GIOStream
             +----WockyTLSConnection

      GObject
       +----WockyTLSSession

## Properties

      "session"                  WockyTLSSession*      : Write / Construct Only
      "base-stream"              GIOStream*            : Write / Construct Only
      "dh-bits"                  guint                 : Write / Construct Only
      "server"                   gboolean              : Write / Construct Only
      "x509-cert"                gchar*                : Write / Construct Only
      "x509-key"                 gchar*                : Write / Construct Only

## Description

The WOCKY_TLS_DEBUG_LEVEL environment variable can be used to print debug output from OpenSSL. To enable it, set it to a value from 1 to 9. Higher values will print more information.

Increasing the value past certain thresholds will also trigger increased debugging output from within wocky-openssl.c as well.

## Details

### WOCKY_TYPE_TLS_CONNECTION

    #define WOCKY_TYPE_TLS_CONNECTION (wocky_tls_connection_get_type ())

### WOCKY_TYPE_TLS_SESSION

    #define WOCKY_TYPE_TLS_SESSION    (wocky_tls_session_get_type ())

### WOCKY_TLS_SESSION()

    #define             WOCKY_TLS_SESSION(inst)

`inst` : |

### WOCKY_TLS_CONNECTION()

    #define             WOCKY_TLS_CONNECTION(inst)

`inst` : |

### WockyTLSConnection

    typedef struct _WockyTLSConnection WockyTLSConnection;

### WockyTLSSession

    typedef struct _WockyTLSSession WockyTLSSession;

### enum WockyTLSVerificationLevel

    typedef enum
    {
      WOCKY_TLS_VERIFY_STRICT = 0,
      WOCKY_TLS_VERIFY_NORMAL,
      WOCKY_TLS_VERIFY_LENIENT,
    } WockyTLSVerificationLevel;

### wocky_tls_cert_error_quark ()

    GQuark              wocky_tls_cert_error_quark          (void);

Returns : |

### WOCKY_TLS_CERT_ERROR

    #define WOCKY_TLS_CERT_ERROR (wocky_tls_cert_error_quark ())

### wocky_tls_error_quark ()

    GQuark              wocky_tls_error_quark               (void);

Returns : |

### WOCKY_TLS_ERROR

    #define WOCKY_TLS_ERROR (wocky_tls_error_quark ())

### enum WockyTLSCertStatus

    typedef enum
    {
      WOCKY_TLS_CERT_OK = 0,
      WOCKY_TLS_CERT_INVALID,
      WOCKY_TLS_CERT_NAME_MISMATCH,
      WOCKY_TLS_CERT_REVOKED,
      WOCKY_TLS_CERT_SIGNER_UNKNOWN,
      WOCKY_TLS_CERT_SIGNER_UNAUTHORISED,
      WOCKY_TLS_CERT_INSECURE,
      WOCKY_TLS_CERT_NOT_ACTIVE,
      WOCKY_TLS_CERT_EXPIRED,
      WOCKY_TLS_CERT_NO_CERTIFICATE,
      WOCKY_TLS_CERT_MAYBE_DOS,
      WOCKY_TLS_CERT_INTERNAL_ERROR,
      WOCKY_TLS_CERT_UNKNOWN_ERROR,
    } WockyTLSCertStatus;

### enum WockyTLSCertType

    typedef enum
    {
      WOCKY_TLS_CERT_TYPE_NONE = 0,
      WOCKY_TLS_CERT_TYPE_X509,
      WOCKY_TLS_CERT_TYPE_OPENPGP,
    } WockyTLSCertType;

### wocky_tls_connection_get_type ()

    GType               wocky_tls_connection_get_type       (void);

Returns : |

### wocky_tls_session_get_type ()

    GType               wocky_tls_session_get_type          (void);

Returns : |

### wocky_tls_session_verify_peer ()

    int                 wocky_tls_session_verify_peer       (WockyTLSSession *session,
                                                             const gchar *peername,
                                                             WockyTLSVerificationLevel level,
                                                             WockyTLSCertStatus *status);

`session` : |
`peername` : |
`level` : |
`status` : |
Returns : |

### wocky_tls_session_get_peers_certificate ()

    GPtrArray *         wocky_tls_session_get_peers_certificate
                                                            (WockyTLSSession *session,
                                                             WockyTLSCertType *type);

`session` : |
`type` : |
Returns : |

### wocky_tls_session_handshake ()

    WockyTLSConnection * wocky_tls_session_handshake        (WockyTLSSession *session,
                                                             GCancellable *cancellable,
                                                             GError **error);

`session` : |
`cancellable` : |
`error` : |
Returns : |

### wocky_tls_session_handshake_async ()

    void                wocky_tls_session_handshake_async   (WockyTLSSession *session,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

`session` : |
`io_priority` : |
`cancellable` : |
`callback` : |
`user_data` : |

### wocky_tls_session_handshake_finish ()

    WockyTLSConnection * wocky_tls_session_handshake_finish (WockyTLSSession *session,
                                                             GAsyncResult *result,
                                                             GError **error);

`session` : |
`result` : |
`error` : |
Returns : |

### wocky_tls_session_add_ca ()

    void                wocky_tls_session_add_ca            (WockyTLSSession *session,
                                                             const gchar *path);

`session` : |
`path` : |

### wocky_tls_session_add_crl ()

    void                wocky_tls_session_add_crl           (WockyTLSSession *session,
                                                             const gchar *path);

`session` : |
`path` : |

### wocky_tls_session_new ()

    WockyTLSSession *   wocky_tls_session_new               (GIOStream *stream);

`stream` : |
Returns : |

### wocky_tls_session_server_new ()

    WockyTLSSession *   wocky_tls_session_server_new        (GIOStream *stream,
                                                             guint dhbits,
                                                             const gchar *key,
                                                             const gchar *cert);

Create a new TLS server session

`stream` : | a GIOStream on which we expect to receive the client TLS handshake
`dhbits` : | size of the DH parameters
`key` : | the path to the X509 PEM key file
`cert` : | the path to the X509 PEM certificate
Returns : | a WockyTLSSession object

## Property Details

### The `"session"` property

      "session"                  WockyTLSSession*      : Write / Construct Only

the TLS session object for this connection.

### The `"base-stream"` property

      "base-stream"              GIOStream*            : Write / Construct Only

the stream that TLS communicates over.

### The `"dh-bits"` property

      "dh-bits"                  guint                 : Write / Construct Only

Diffie-Hellmann bits: 768, 1024, 2048, 3072 0r 4096.

Allowed values: [768,4096]

Default value: 1024

### The `"server"` property

      "server"                   gboolean              : Write / Construct Only

whether this is a server.

Default value: FALSE

### The `"x509-cert"` property

      "x509-cert"                gchar*                : Write / Construct Only

x509 PEM certificate file.

Default value: NULL

### The `"x509-key"` property

      "x509-key"                 gchar*                : Write / Construct Only

x509 PEM key file.

Default value: NULL