libpurple/tls-certificate.h

   1 /*
   2  *
   3  * purple
   4  *
   5  * Purple is the legal property of its developers, whose names are too numerous
   6  * to list here.  Please refer to the COPYRIGHT file distributed with this
   7  * source distribution.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  22  */
  23
  24 #ifndef _PURPLE_TLS_CERTIFICATE_H
  25 #define _PURPLE_TLS_CERTIFICATE_H
  26 /**
  27  * SECTION:tls-certificate
  28  * @section_id: libpurple-tls-certificate
  29  * @short_description: TLS certificate trust and storage API
  30  * @title: TLS Certificate API
  31  *
  32  * The TLS Certificate API provides functions for trusting and storing
  33  * certificates for use with TLS/SSL connections. This allows certificates,
  34  * which aren't considered valid by the TLS implementation, to be manually
  35  * trusted by the user, distrusted at a later time, and queried by the UI.
  36  * It also provides functions to simply wire this system into Gio.
  37  */
  38
  39 #include <gio/gio.h>
  40
  41 /**
  42  * purple_tls_certificate_list_ids:
  43  *
  44  * Returns a list of the IDs for certificates trusted with
  45  * purple_tls_certificate_trust() and friends. These IDs can then be passed
  46  * to purple_tls_certificate_new_from_id() or used directly, if desired.
  47  *
  48  * Returns: (transfer full) (element-type utf8): #GList of IDs described above
  49  *          Free with purple_tls_certificate_free_ids()
  50  */
  51 GList *
  52 purple_tls_certificate_list_ids(void);
  53
  54 /**
  55  * purple_tls_certificate_free_ids:
  56  * @ids: (transfer full) (element-type utf8): List of ids retrieved from
  57  *       purple_tls_certificate_list_ids()
  58  *
  59  * Frees the list of IDs returned from purple_tls_certificate_list_ids().
  60  */
  61 void
  62 purple_tls_certificate_free_ids(GList *ids);
  63
  64 /**
  65  * purple_tls_certificate_new_from_id:
  66  * @id: ID of certificate to load
  67  * @error: A GError location to store the error occurring, or NULL to ignore
  68  *
  69  * Loads the certificate referenced by ID into a #GTlsCertificate object.
  70  *
  71  * Returns: (transfer full): #GTlsCertificate loaded from ID
  72  */
  73 GTlsCertificate *
  74 purple_tls_certificate_new_from_id(const gchar *id, GError **error);
  75
  76 /**
  77  * purple_tls_certificate_trust:
  78  * @id: ID to associate with the certificate
  79  * @certificate: Certificate to trust for TLS operations
  80  * @error: A GError location to store the error occurring, or NULL to ignore
  81  *
  82  * Trusts the certificate to be allowed for TLS operations even if
  83  * it would otherwise fail.
  84  *
  85  * Returns: #TRUE on success, #FALSE otherwise
  86  */
  87 gboolean
  88 purple_tls_certificate_trust(const gchar *id, GTlsCertificate *certificate,
  89                 GError **error);
  90
  91 /**
  92  * purple_tls_certificate_distrust:
  93  * @id: ID associated with the certificate to distrust
  94  * @error: A GError location to store the error occurring, or NULL to ignore
  95  *
  96  * Revokes full trust of certificate. The certificate will be accepted
  97  * in TLS operations only if it passes normal validation.
  98  *
  99  * Returns: #TRUE on success, #FALSE otherwise
 100  */
 101 gboolean
 102 purple_tls_certificate_distrust(const gchar *id, GError **error);
 103
 104
 105 /**
 106  * purple_tls_certificate_attach_to_tls_connection:
 107  * @conn: #GTlsConnection to connect to
 108  *
 109  * Connects the Purple TLS certificate subsystem to @conn so it will accept
 110  * certificates trusted by purple_tls_certificate_trust() and friends.
 111  *
 112  * Returns: (transfer none) (type GObject.Object): @conn, similar to
 113  *          g_object_connect()
 114  */
 115 gpointer
 116 purple_tls_certificate_attach_to_tls_connection(GTlsConnection *conn);
 117
 118 /**
 119  * purple_tls_certificate_attach_to_socket_client:
 120  * @client: #GSocketClient to connect to
 121  *
 122  * Connects the Purple TLS certificate subsystem to @client so any TLS
 123  * connections it creates will accept certificates trusted by
 124  * purple_tls_certificate_trust() and friends.
 125  *
 126  * Returns: (transfer none) (type GObject.Object): @client, similar to
 127  *          g_object_connect()
 128  */
 129 gpointer
 130 purple_tls_certificate_attach_to_socket_client(GSocketClient *client);
 131
 132 G_END_DECLS
 133
 134 #endif /* _PURPLE_TLS_CERTIFICATE_H */