Wocky GnuTLS TLS

Wocky GnuTLS 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)
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);
                    WockyTLSSession;
                    WockyTLSConnection;

Object Hierarchy

  GEnum
   +----WockyTLSVerificationLevel
  GEnum
   +----WockyTLSCertStatus
  GEnum
   +----WockyTLSCertType
  GObject
   +----WockyTLSSession
  GObject
   +----GIOStream
         +----WockyTLSConnection

Properties

  "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
  "session"                  WockyTLSSession*      : Write / Construct Only

Description

The WOCKY_TLS_DEBUG_LEVEL environment variable can be used to print debug output from GNU TLS. To enable it, set it to a value from 1 to 9. Higher values will print more information. See the documentation of gnutls_global_set_log_level for more details.

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

The WOCKY_GNUTLS_OPTIONS environment variable can be set to a gnutls priority string [See gnutls-cli(1) or the gnutls_priority_init docs] to control most tls protocol details. An empty or unset value is roughly equivalent to a priority string of "SECURE:+COMP-DEFLATE".

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)


WOCKY_TLS_CONNECTION()

#define             WOCKY_TLS_CONNECTION(inst)


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);


WOCKY_TLS_CERT_ERROR

#define WOCKY_TLS_CERT_ERROR (wocky_tls_cert_error_quark ())


wocky_tls_error_quark ()

GQuark              wocky_tls_error_quark               (void);


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);


wocky_tls_session_get_type ()

GType               wocky_tls_session_get_type          (void);


wocky_tls_session_verify_peer ()

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


wocky_tls_session_get_peers_certificate ()

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


wocky_tls_session_handshake ()

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


wocky_tls_session_handshake_async ()

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


wocky_tls_session_handshake_finish ()

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


wocky_tls_session_add_ca ()

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


wocky_tls_session_add_crl ()

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


wocky_tls_session_new ()

WockyTLSSession *   wocky_tls_session_new               (GIOStream *stream);


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 (see gnutls for valid settings)

key :

the path to the X509 PEM key file

cert :

the path to the X509 PEM certificate

Returns :

a WockyTLSSession object

WockyTLSSession

typedef struct _WockyTLSSession WockyTLSSession;


WockyTLSConnection

typedef struct _WockyTLSConnection WockyTLSConnection;

Property Details

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


The "session" property

  "session"                  WockyTLSSession*      : Write / Construct Only

the TLS session object for this connection.