certificate.h
Go to the documentation of this file.
/*
*
* purple
*
* Purple is the legal property of its developers, whose names are too numerous
* to list here. Please refer to the COPYRIGHT file distributed with this
* source distribution.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*/
#ifndef _PURPLE_CERTIFICATE_H
#define _PURPLE_CERTIFICATE_H
#include <time.h>
#include <glib.h>
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
typedef enum
{
PURPLE_CERTIFICATE_INVALID = 0,
PURPLE_CERTIFICATE_VALID = 1
} PurpleCertificateVerificationStatus;
/*
* TODO: Merge this with PurpleCertificateVerificationStatus for 3.0.0 */
typedef enum {
PURPLE_CERTIFICATE_UNKNOWN_ERROR = -1,
/* Not an error */
PURPLE_CERTIFICATE_NO_PROBLEMS = 0,
/* Non-fatal */
PURPLE_CERTIFICATE_NON_FATALS_MASK = 0x0000FFFF,
/* The certificate is self-signed. */
PURPLE_CERTIFICATE_SELF_SIGNED = 0x01,
/* The CA is not in libpurple's pool of certificates. */
PURPLE_CERTIFICATE_CA_UNKNOWN = 0x02,
/* The current time is before the certificate's specified
* activation time.
*/
PURPLE_CERTIFICATE_NOT_ACTIVATED = 0x04,
/* The current time is after the certificate's specified expiration time */
PURPLE_CERTIFICATE_EXPIRED = 0x08,
/* The certificate's subject name doesn't match the expected */
PURPLE_CERTIFICATE_NAME_MISMATCH = 0x10,
/* No CA pool was found. This shouldn't happen... */
PURPLE_CERTIFICATE_NO_CA_POOL = 0x20,
/* Fatal */
PURPLE_CERTIFICATE_FATALS_MASK = 0xFFFF0000,
/* The signature chain could not be validated. Due to limitations in the
* the current API, this also indicates one of the CA certificates in the
* chain is expired (or not yet activated). FIXME 3.0.0 */
PURPLE_CERTIFICATE_INVALID_CHAIN = 0x10000,
/* The signature has been revoked. */
PURPLE_CERTIFICATE_REVOKED = 0x20000,
PURPLE_CERTIFICATE_LAST = 0x40000,
} PurpleCertificateInvalidityFlags;
typedef struct _PurpleCertificate PurpleCertificate;
typedef struct _PurpleCertificatePool PurpleCertificatePool;
typedef struct _PurpleCertificateScheme PurpleCertificateScheme;
typedef struct _PurpleCertificateVerifier PurpleCertificateVerifier;
typedef struct _PurpleCertificateVerificationRequest PurpleCertificateVerificationRequest;
typedef void (*PurpleCertificateVerifiedCallback)
(PurpleCertificateVerificationStatus st,
gpointer userdata);
struct _PurpleCertificate
{
PurpleCertificateScheme * scheme;
gpointer data;
};
struct _PurpleCertificatePool
{
gchar *scheme_name;
gchar *name;
gchar *fullname;
gpointer data;
gboolean (* init)(void);
void (* uninit)(void);
gboolean (* cert_in_pool)(const gchar *id);
PurpleCertificate * (* get_cert)(const gchar *id);
gboolean (* put_cert)(const gchar *id, PurpleCertificate *crt);
gboolean (* delete_cert)(const gchar *id);
GList * (* get_idlist)(void);
void (*_purple_reserved1)(void);
void (*_purple_reserved2)(void);
void (*_purple_reserved3)(void);
void (*_purple_reserved4)(void);
};
struct _PurpleCertificateScheme
{
gchar * name;
gchar * fullname;
PurpleCertificate * (* import_certificate)(const gchar * filename);
gboolean (* export_certificate)(const gchar *filename, PurpleCertificate *crt);
PurpleCertificate * (* copy_certificate)(PurpleCertificate *crt);
void (* destroy_certificate)(PurpleCertificate * crt);
gboolean (*signed_by)(PurpleCertificate *crt, PurpleCertificate *issuer);
GByteArray * (* get_fingerprint_sha1)(PurpleCertificate *crt);
gchar * (* get_unique_id)(PurpleCertificate *crt);
gchar * (* get_issuer_unique_id)(PurpleCertificate *crt);
gchar * (* get_subject_name)(PurpleCertificate *crt);
gboolean (* check_subject_name)(PurpleCertificate *crt, const gchar *name);
gboolean (* get_times)(PurpleCertificate *crt, time_t *activation, time_t *expiration);
GSList * (* import_certificates)(const gchar * filename);
gboolean (* register_trusted_tls_cert)(PurpleCertificate *crt, gboolean ca);
void (* verify_cert)(PurpleCertificateVerificationRequest *vrq, PurpleCertificateInvalidityFlags *flags);
unsigned long struct_size;
GByteArray * (* get_fingerprint_sha256)(PurpleCertificate *crt);
gboolean (* compare_pubkeys)(PurpleCertificate *crt1, PurpleCertificate *crt2);
};
#define PURPLE_CERTIFICATE_SCHEME_HAS_FUNC(obj, member) \
(((G_STRUCT_OFFSET(PurpleCertificateScheme, member) < G_STRUCT_OFFSET(PurpleCertificateScheme, struct_size)) \
|| (G_STRUCT_OFFSET(PurpleCertificateScheme, member) < obj->struct_size)) && \
obj->member != NULL)
struct _PurpleCertificateVerifier
{
gchar *scheme_name;
gchar *name;
void (* start_verification)(PurpleCertificateVerificationRequest *vrq);
void (* destroy_request)(PurpleCertificateVerificationRequest *vrq);
void (*_purple_reserved1)(void);
void (*_purple_reserved2)(void);
void (*_purple_reserved3)(void);
void (*_purple_reserved4)(void);
};
struct _PurpleCertificateVerificationRequest
{
PurpleCertificateVerifier *verifier;
PurpleCertificateScheme *scheme;
gchar *subject_name;
GList *cert_chain;
gpointer data;
PurpleCertificateVerifiedCallback cb;
gpointer cb_data;
};
/*****************************************************************************/
/*****************************************************************************/
void
purple_certificate_verify (PurpleCertificateVerifier *verifier,
const gchar *subject_name, GList *cert_chain,
PurpleCertificateVerifiedCallback cb,
gpointer cb_data);
void
purple_certificate_verify_complete(PurpleCertificateVerificationRequest *vrq,
PurpleCertificateVerificationStatus st);
/*****************************************************************************/
/*****************************************************************************/
PurpleCertificate *
purple_certificate_copy(PurpleCertificate *crt);
GList *
purple_certificate_copy_list(GList *crt_list);
void
purple_certificate_destroy (PurpleCertificate *crt);
void
purple_certificate_destroy_list (GList * crt_list);
gboolean
purple_certificate_signed_by(PurpleCertificate *crt, PurpleCertificate *issuer);
gboolean
purple_certificate_check_signature_chain_with_failing(GList *chain,
PurpleCertificate **failing);
gboolean
purple_certificate_check_signature_chain(GList *chain);
PurpleCertificate *
purple_certificate_import(PurpleCertificateScheme *scheme, const gchar *filename);
GSList *
purple_certificates_import(PurpleCertificateScheme *scheme, const gchar *filename);
gboolean
purple_certificate_export(const gchar *filename, PurpleCertificate *crt);
GByteArray *
purple_certificate_get_fingerprint_sha1(PurpleCertificate *crt);
GByteArray *
purple_certificate_get_fingerprint_sha256(PurpleCertificate *crt, gboolean sha1_fallback);
gchar *
purple_certificate_get_unique_id(PurpleCertificate *crt);
gchar *
purple_certificate_get_issuer_unique_id(PurpleCertificate *crt);
gchar *
purple_certificate_get_subject_name(PurpleCertificate *crt);
gboolean
purple_certificate_check_subject_name(PurpleCertificate *crt, const gchar *name);
gboolean
purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration);
gboolean
purple_certificate_compare_pubkeys(PurpleCertificate *crt1, PurpleCertificate *crt2);
/*****************************************************************************/
/*****************************************************************************/
gchar *
purple_certificate_pool_mkpath(PurpleCertificatePool *pool, const gchar *id);
gboolean
purple_certificate_pool_usable(PurpleCertificatePool *pool);
PurpleCertificateScheme *
purple_certificate_pool_get_scheme(PurpleCertificatePool *pool);
gboolean
purple_certificate_pool_contains(PurpleCertificatePool *pool, const gchar *id);
PurpleCertificate *
purple_certificate_pool_retrieve(PurpleCertificatePool *pool, const gchar *id);
gboolean
purple_certificate_pool_store(PurpleCertificatePool *pool, const gchar *id, PurpleCertificate *crt);
gboolean
purple_certificate_pool_delete(PurpleCertificatePool *pool, const gchar *id);
GList *
purple_certificate_pool_get_idlist(PurpleCertificatePool *pool);
void
purple_certificate_pool_destroy_idlist(GList *idlist);
/*****************************************************************************/
/*****************************************************************************/
void
purple_certificate_init(void);
void
purple_certificate_uninit(void);
gpointer
purple_certificate_get_handle(void);
PurpleCertificateScheme *
purple_certificate_find_scheme(const gchar *name);
GList *
purple_certificate_get_schemes(void);
gboolean
purple_certificate_register_scheme(PurpleCertificateScheme *scheme);
gboolean
purple_certificate_unregister_scheme(PurpleCertificateScheme *scheme);
PurpleCertificateVerifier *
purple_certificate_find_verifier(const gchar *scheme_name, const gchar *ver_name);
GList *
purple_certificate_get_verifiers(void);
gboolean
purple_certificate_register_verifier(PurpleCertificateVerifier *vr);
gboolean
purple_certificate_unregister_verifier(PurpleCertificateVerifier *vr);
PurpleCertificatePool *
purple_certificate_find_pool(const gchar *scheme_name, const gchar *pool_name);
GList *
purple_certificate_get_pools(void);
gboolean
purple_certificate_register_pool(PurpleCertificatePool *pool);
gboolean
purple_certificate_unregister_pool(PurpleCertificatePool *pool);
void
purple_certificate_display_x509(PurpleCertificate *crt);
void purple_certificate_add_ca_search_path(const char *path);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* _PURPLE_CERTIFICATE_H */
_PurpleCertificateVerifier
A set of operations used to provide logic for verifying a Certificate&#39;s authenticity.
Definition: certificate.h:362
purple_certificate_register_scheme
gboolean purple_certificate_register_scheme(PurpleCertificateScheme *scheme)
Register a CertificateScheme with libpurple.
purple_certificate_import
PurpleCertificate * purple_certificate_import(PurpleCertificateScheme *scheme, const gchar *filename)
Imports a PurpleCertificate from a file.
purple_certificate_check_signature_chain_with_failing
gboolean purple_certificate_check_signature_chain_with_failing(GList *chain, PurpleCertificate **failing)
Check that a certificate chain is valid and, if not, the failing certificate.
purple_certificate_copy
PurpleCertificate * purple_certificate_copy(PurpleCertificate *crt)
Makes a duplicate of a certificate.
purple_certificate_find_pool
PurpleCertificatePool * purple_certificate_find_pool(const gchar *scheme_name, const gchar *pool_name)
Look up a registered PurpleCertificatePool by scheme and name.
_PurpleCertificateVerificationRequest::cert_chain
GList * cert_chain
List of certificates in the chain to be verified (such as that returned by purple_ssl_get_peer_certif...
Definition: certificate.h:429
_PurpleCertificate::data
gpointer data
Opaque pointer to internal data.
Definition: certificate.h:119
_PurpleCertificateVerificationRequest
Structure for a single certificate request.
Definition: certificate.h:407
purple_certificate_init
void purple_certificate_init(void)
Initialize the certificate system.
purple_certificate_add_ca_search_path
void purple_certificate_add_ca_search_path(const char *path)
Add a search path for certificates.
_PurpleCertificateVerifier::scheme_name
gchar * scheme_name
Name of the scheme this Verifier operates on.
Definition: certificate.h:369
purple_certificate_register_pool
gboolean purple_certificate_register_pool(PurpleCertificatePool *pool)
Register a CertificatePool with libpurple and call its init function.
_PurpleCertificateScheme::struct_size
unsigned long struct_size
The size of the PurpleCertificateScheme.
Definition: certificate.h:324
purple_certificate_check_signature_chain
gboolean purple_certificate_check_signature_chain(GList *chain)
Check that a certificate chain is valid.
purple_certificate_pool_get_idlist
GList * purple_certificate_pool_get_idlist(PurpleCertificatePool *pool)
Get the list of IDs currently in the pool.
purple_certificate_pool_mkpath
gchar * purple_certificate_pool_mkpath(PurpleCertificatePool *pool, const gchar *id)
Helper function for generating file paths in ~/.purple/certificates for CertificatePools that use the...
purple_certificate_get_schemes
GList * purple_certificate_get_schemes(void)
Get all registered CertificateSchemes.
purple_certificate_get_issuer_unique_id
gchar * purple_certificate_get_issuer_unique_id(PurpleCertificate *crt)
Get a unique identifier for the certificate&#39;s issuer.
purple_certificate_get_pools
GList * purple_certificate_get_pools(void)
Get the list of registered Pools.
purple_certificate_get_fingerprint_sha256
GByteArray * purple_certificate_get_fingerprint_sha256(PurpleCertificate *crt, gboolean sha1_fallback)
Retrieves the certificate public key fingerprint using SHA256.
purple_certificate_unregister_scheme
gboolean purple_certificate_unregister_scheme(PurpleCertificateScheme *scheme)
Unregister a CertificateScheme from libpurple.
purple_certificate_unregister_pool
gboolean purple_certificate_unregister_pool(PurpleCertificatePool *pool)
Unregister a CertificatePool with libpurple and call its uninit function.
purple_certificate_signed_by
gboolean purple_certificate_signed_by(PurpleCertificate *crt, PurpleCertificate *issuer)
Check whether &#39;crt&#39; has a valid signature made by &#39;issuer&#39;.
purple_certificate_destroy_list
void purple_certificate_destroy_list(GList *crt_list)
Destroy an entire list of Certificate instances and the containing list.
purple_certificate_find_scheme
PurpleCertificateScheme * purple_certificate_find_scheme(const gchar *name)
Look up a registered CertificateScheme by name.
purple_certificate_register_verifier
gboolean purple_certificate_register_verifier(PurpleCertificateVerifier *vr)
Register a CertificateVerifier with libpurple.
purple_certificate_pool_store
gboolean purple_certificate_pool_store(PurpleCertificatePool *pool, const gchar *id, PurpleCertificate *crt)
Add a certificate to a pool.
purple_certificate_pool_contains
gboolean purple_certificate_pool_contains(PurpleCertificatePool *pool, const gchar *id)
Check for presence of an ID in a pool.
purple_certificate_destroy
void purple_certificate_destroy(PurpleCertificate *crt)
Destroys and free()&#39;s a Certificate.
_PurpleCertificatePool::fullname
gchar * fullname
User-friendly name for this type ex: N_("SSL Servers") When this is displayed anywhere, it should be i18ned ex: _(pool->fullname)
Definition: certificate.h:140
_PurpleCertificateVerificationRequest::scheme
PurpleCertificateScheme * scheme
Reference to the scheme used.
Definition: certificate.h:415
_PurpleCertificateScheme::fullname
gchar * fullname
User-friendly name for this type ex: N_("X.509 Certificates") When this is displayed anywhere...
Definition: certificate.h:204
purple_certificates_import
GSList * purple_certificates_import(PurpleCertificateScheme *scheme, const gchar *filename)
Imports a list of PurpleCertificates from a file.
_PurpleCertificateScheme::name
gchar * name
Name of the certificate type ex: "x509", "pgp", etc.
Definition: certificate.h:197
purple_certificate_get_subject_name
gchar * purple_certificate_get_subject_name(PurpleCertificate *crt)
Gets the certificate subject&#39;s name.
purple_certificate_get_verifiers
GList * purple_certificate_get_verifiers(void)
Get the list of registered CertificateVerifiers.
purple_certificate_pool_destroy_idlist
void purple_certificate_pool_destroy_idlist(GList *idlist)
Destroys the result given by purple_certificate_pool_get_idlist()
_PurpleCertificateVerificationRequest::data
gpointer data
Internal data used by the Verifier code.
Definition: certificate.h:432
_PurpleCertificatePool::data
gpointer data
Internal pool data.
Definition: certificate.h:143
purple_certificate_get_unique_id
gchar * purple_certificate_get_unique_id(PurpleCertificate *crt)
Get a unique identifier for the certificate.
purple_certificate_check_subject_name
gboolean purple_certificate_check_subject_name(PurpleCertificate *crt, const gchar *name)
Check the subject name against that on the certificate.
_PurpleCertificateScheme
A certificate type.
Definition: certificate.h:190
purple_certificate_get_times
gboolean purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration)
Get the expiration/activation times.
_PurpleCertificateVerificationRequest::subject_name
gchar * subject_name
Name to check that the certificate is issued to.
Definition: certificate.h:422
_PurpleCertificatePool::scheme_name
gchar * scheme_name
Scheme this Pool operates for.
Definition: certificate.h:131
_PurpleCertificateVerificationRequest::cb_data
gpointer cb_data
Data to pass to the post-verification callback.
Definition: certificate.h:437
purple_certificate_copy_list
GList * purple_certificate_copy_list(GList *crt_list)
Duplicates an entire list of certificates.
purple_certificate_unregister_verifier
gboolean purple_certificate_unregister_verifier(PurpleCertificateVerifier *vr)
Unregister a CertificateVerifier with libpurple.
purple_certificate_uninit
void purple_certificate_uninit(void)
Un-initialize the certificate system.
purple_certificate_export
gboolean purple_certificate_export(const gchar *filename, PurpleCertificate *crt)
Exports a PurpleCertificate to a file.
_PurpleCertificatePool::name
gchar * name
Internal name to refer to the pool by.
Definition: certificate.h:133
_PurpleCertificateVerificationRequest::verifier
PurpleCertificateVerifier * verifier
Reference to the verification logic used.
Definition: certificate.h:410
purple_certificate_pool_usable
gboolean purple_certificate_pool_usable(PurpleCertificatePool *pool)
Determines whether a pool can be used.
purple_certificate_pool_get_scheme
PurpleCertificateScheme * purple_certificate_pool_get_scheme(PurpleCertificatePool *pool)
Looks up the scheme the pool operates under.
purple_certificate_get_handle
gpointer purple_certificate_get_handle(void)
Get the Certificate subsystem handle for signalling purposes.
purple_certificate_pool_retrieve
PurpleCertificate * purple_certificate_pool_retrieve(PurpleCertificatePool *pool, const gchar *id)
Retrieve a certificate from a pool.
purple_certificate_find_verifier
PurpleCertificateVerifier * purple_certificate_find_verifier(const gchar *scheme_name, const gchar *ver_name)
Look up a registered PurpleCertificateVerifier by scheme and name.
_PurpleCertificateVerificationRequest::cb
PurpleCertificateVerifiedCallback cb
Function to call with the verification result.
Definition: certificate.h:435
_PurpleCertificatePool
Database for retrieval or storage of Certificates.
Definition: certificate.h:128
purple_certificate_pool_delete
gboolean purple_certificate_pool_delete(PurpleCertificatePool *pool, const gchar *id)
Remove a certificate from a pool.
_PurpleCertificate
A certificate instance.
Definition: certificate.h:114
purple_certificate_get_fingerprint_sha1
GByteArray * purple_certificate_get_fingerprint_sha1(PurpleCertificate *crt)
Retrieves the certificate public key fingerprint using SHA1.
_PurpleCertificate::scheme
PurpleCertificateScheme * scheme
Scheme this certificate is under.
Definition: certificate.h:117
PurpleCertificateVerifiedCallback
void(* PurpleCertificateVerifiedCallback)(PurpleCertificateVerificationStatus st, gpointer userdata)
Callback function for the results of a verification check.
Definition: certificate.h:106
purple_certificate_display_x509
void purple_certificate_display_x509(PurpleCertificate *crt)
Displays a window showing X.509 certificate information.
purple_certificate_compare_pubkeys
gboolean purple_certificate_compare_pubkeys(PurpleCertificate *crt1, PurpleCertificate *crt2)
Compares the public keys of two certificates.
purple_certificate_verify_complete
void purple_certificate_verify_complete(PurpleCertificateVerificationRequest *vrq, PurpleCertificateVerificationStatus st)
Completes and destroys a VerificationRequest.
purple_certificate_verify
void purple_certificate_verify(PurpleCertificateVerifier *verifier, const gchar *subject_name, GList *cert_chain, PurpleCertificateVerifiedCallback cb, gpointer cb_data)
Constructs a verification request and passed control to the specified Verifier.
_PurpleCertificateVerifier::name
gchar * name
Name of the Verifier - case insensitive.
Definition: certificate.h:372