certificate.h
Go to the documentation of this file.
1 
8 /*
9  *
10  * purple
11  *
12  * Purple is the legal property of its developers, whose names are too numerous
13  * to list here. Please refer to the COPYRIGHT file distributed with this
14  * source distribution.
15  *
16  * This program is free software; you can redistribute it and/or modify
17  * it under the terms of the GNU General Public License as published by
18  * the Free Software Foundation; either version 2 of the License, or
19  * (at your option) any later version.
20  *
21  * This program is distributed in the hope that it will be useful,
22  * but WITHOUT ANY WARRANTY; without even the implied warranty of
23  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24  * GNU General Public License for more details.
25  *
26  * You should have received a copy of the GNU General Public License
27  * along with this program; if not, write to the Free Software
28  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
29  */
30 
31 #ifndef _PURPLE_CERTIFICATE_H
32 #define _PURPLE_CERTIFICATE_H
33 
34 #include <time.h>
35 
36 #include <glib.h>
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif /* __cplusplus */
41 
42 
43 typedef enum
44 {
45  PURPLE_CERTIFICATE_INVALID = 0,
46  PURPLE_CERTIFICATE_VALID = 1
47 } PurpleCertificateVerificationStatus;
48 
49 /*
50  * TODO: Merge this with PurpleCertificateVerificationStatus for 3.0.0 */
51 typedef enum {
52  PURPLE_CERTIFICATE_UNKNOWN_ERROR = -1,
53 
54  /* Not an error */
55  PURPLE_CERTIFICATE_NO_PROBLEMS = 0,
56 
57  /* Non-fatal */
58  PURPLE_CERTIFICATE_NON_FATALS_MASK = 0x0000FFFF,
59 
60  /* The certificate is self-signed. */
61  PURPLE_CERTIFICATE_SELF_SIGNED = 0x01,
62 
63  /* The CA is not in libpurple's pool of certificates. */
64  PURPLE_CERTIFICATE_CA_UNKNOWN = 0x02,
65 
66  /* The current time is before the certificate's specified
67  * activation time.
68  */
69  PURPLE_CERTIFICATE_NOT_ACTIVATED = 0x04,
70 
71  /* The current time is after the certificate's specified expiration time */
72  PURPLE_CERTIFICATE_EXPIRED = 0x08,
73 
74  /* The certificate's subject name doesn't match the expected */
75  PURPLE_CERTIFICATE_NAME_MISMATCH = 0x10,
76 
77  /* No CA pool was found. This shouldn't happen... */
78  PURPLE_CERTIFICATE_NO_CA_POOL = 0x20,
79 
80  /* Fatal */
81  PURPLE_CERTIFICATE_FATALS_MASK = 0xFFFF0000,
82 
83  /* The signature chain could not be validated. Due to limitations in the
84  * the current API, this also indicates one of the CA certificates in the
85  * chain is expired (or not yet activated). FIXME 3.0.0 */
86  PURPLE_CERTIFICATE_INVALID_CHAIN = 0x10000,
87 
88  /* The signature has been revoked. */
89  PURPLE_CERTIFICATE_REVOKED = 0x20000,
90 
91  PURPLE_CERTIFICATE_LAST = 0x40000,
92 } PurpleCertificateInvalidityFlags;
93 
99 
105 typedef void (*PurpleCertificateVerifiedCallback)
106  (PurpleCertificateVerificationStatus st,
107  gpointer userdata);
108 
115 {
119  gpointer data;
120 };
121 
129 {
131  gchar *scheme_name;
133  gchar *name;
134 
140  gchar *fullname;
141 
143  gpointer data;
144 
152  gboolean (* init)(void);
153 
159  void (* uninit)(void);
160 
162  gboolean (* cert_in_pool)(const gchar *id);
164  PurpleCertificate * (* get_cert)(const gchar *id);
169  gboolean (* put_cert)(const gchar *id, PurpleCertificate *crt);
171  gboolean (* delete_cert)(const gchar *id);
172 
174  GList * (* get_idlist)(void);
175 
176  void (*_purple_reserved1)(void);
177  void (*_purple_reserved2)(void);
178  void (*_purple_reserved3)(void);
179  void (*_purple_reserved4)(void);
180 };
181 
191 {
197  gchar * name;
198 
204  gchar * fullname;
205 
212  PurpleCertificate * (* import_certificate)(const gchar * filename);
213 
222  gboolean (* export_certificate)(const gchar *filename, PurpleCertificate *crt);
223 
232  PurpleCertificate * (* copy_certificate)(PurpleCertificate *crt);
233 
244 
248  gboolean (*signed_by)(PurpleCertificate *crt, PurpleCertificate *issuer);
256  GByteArray * (* get_fingerprint_sha1)(PurpleCertificate *crt);
257 
265  gchar * (* get_unique_id)(PurpleCertificate *crt);
266 
274  gchar * (* get_issuer_unique_id)(PurpleCertificate *crt);
275 
287  gchar * (* get_subject_name)(PurpleCertificate *crt);
288 
294  gboolean (* check_subject_name)(PurpleCertificate *crt, const gchar *name);
295 
297  gboolean (* get_times)(PurpleCertificate *crt, time_t *activation, time_t *expiration);
298 
305  GSList * (* import_certificates)(const gchar * filename);
306 
310  gboolean (* register_trusted_tls_cert)(PurpleCertificate *crt, gboolean ca);
311 
316  void (* verify_cert)(PurpleCertificateVerificationRequest *vrq, PurpleCertificateInvalidityFlags *flags);
317 
318  void (*_purple_reserved3)(void);
319 };
320 
331 {
337  gchar *scheme_name;
338 
340  gchar *name;
341 
353 
363 
364  void (*_purple_reserved1)(void);
365  void (*_purple_reserved2)(void);
366  void (*_purple_reserved3)(void);
367  void (*_purple_reserved4)(void);
368 };
369 
376 {
384 
390  gchar *subject_name;
391 
397  GList *cert_chain;
398 
400  gpointer data;
401 
405  gpointer cb_data;
406 };
407 
408 /*****************************************************************************/
410 /*****************************************************************************/
436 void
438  const gchar *subject_name, GList *cert_chain,
440  gpointer cb_data);
441 
449 void
451  PurpleCertificateVerificationStatus st);
452 
455 /*****************************************************************************/
457 /*****************************************************************************/
468 
475 GList *
476 purple_certificate_copy_list(GList *crt_list);
477 
483 void
485 
491 void
492 purple_certificate_destroy_list (GList * crt_list);
493 
504 gboolean
506 
525 gboolean
527  PurpleCertificate **failing);
528 
543 gboolean
545 
554 purple_certificate_import(PurpleCertificateScheme *scheme, const gchar *filename);
555 
563 GSList *
564 purple_certificates_import(PurpleCertificateScheme *scheme, const gchar *filename);
565 
573 gboolean
574 purple_certificate_export(const gchar *filename, PurpleCertificate *crt);
575 
576 
585 GByteArray *
587 
594 gchar *
596 
604 gchar *
606 
616 gchar *
618 
625 gboolean
627 
638 gboolean
639 purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration);
640 
643 /*****************************************************************************/
645 /*****************************************************************************/
658 gchar *
660 
670 gboolean
672 
683 
690 gboolean
692 
702 
713 gboolean
715 
723 gboolean
725 
733 GList *
735 
741 void
743 
746 /*****************************************************************************/
748 /*****************************************************************************/
754 void
756 
760 void
762 
766 gpointer
768 
774 purple_certificate_find_scheme(const gchar *name);
775 
782 GList *
784 
793 gboolean
795 
803 gboolean
805 
812 purple_certificate_find_verifier(const gchar *scheme_name, const gchar *ver_name);
813 
820 GList *
822 
829 gboolean
831 
838 gboolean
840 
847 purple_certificate_find_pool(const gchar *scheme_name, const gchar *pool_name);
848 
855 GList *
857 
864 gboolean
866 
873 gboolean
875 
885 void
887 
893 void purple_certificate_add_ca_search_path(const char *path);
894 
895 #ifdef __cplusplus
896 }
897 #endif /* __cplusplus */
898 
899 #endif /* _PURPLE_CERTIFICATE_H */
gboolean(* get_times)(PurpleCertificate *crt, time_t *activation, time_t *expiration)
Retrieve the certificate activation/expiration times.
Definition: certificate.h:297
A set of operations used to provide logic for verifying a Certificate's authenticity.
Definition: certificate.h:330
gboolean purple_certificate_register_scheme(PurpleCertificateScheme *scheme)
Register a CertificateScheme with libpurple.
PurpleCertificate * purple_certificate_import(PurpleCertificateScheme *scheme, const gchar *filename)
Imports a PurpleCertificate from a file.
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.
gboolean(* init)(void)
Set up the Pool's internal state.
Definition: certificate.h:152
PurpleCertificate * purple_certificate_copy(PurpleCertificate *crt)
Makes a duplicate of a certificate.
PurpleCertificatePool * purple_certificate_find_pool(const gchar *scheme_name, const gchar *pool_name)
Look up a registered PurpleCertificatePool by scheme and name.
void(* uninit)(void)
Uninit the Pool's internal state.
Definition: certificate.h:159
gboolean(* signed_by)(PurpleCertificate *crt, PurpleCertificate *issuer)
Find whether "crt" has a valid signature from "issuer," including appropriate values for the CA flag ...
Definition: certificate.h:248
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:397
gpointer data
Opaque pointer to internal data.
Definition: certificate.h:119
Structure for a single certificate request.
Definition: certificate.h:375
void purple_certificate_init(void)
Initialize the certificate system.
void purple_certificate_add_ca_search_path(const char *path)
Add a search path for certificates.
gchar * scheme_name
Name of the scheme this Verifier operates on.
Definition: certificate.h:337
gboolean purple_certificate_register_pool(PurpleCertificatePool *pool)
Register a CertificatePool with libpurple and call its init function.
gboolean purple_certificate_check_signature_chain(GList *chain)
Check that a certificate chain is valid.
GList * purple_certificate_pool_get_idlist(PurpleCertificatePool *pool)
Get the list of IDs currently in the pool.
gchar * purple_certificate_pool_mkpath(PurpleCertificatePool *pool, const gchar *id)
Helper function for generating file paths in ~/.purple/certificates for CertificatePools that use the...
void(* destroy_certificate)(PurpleCertificate *crt)
Destroys and frees a Certificate structure.
Definition: certificate.h:243
GList * purple_certificate_get_schemes(void)
Get all registered CertificateSchemes.
gchar * purple_certificate_get_issuer_unique_id(PurpleCertificate *crt)
Get a unique identifier for the certificate's issuer.
GList * purple_certificate_get_pools(void)
Get the list of registered Pools.
gboolean purple_certificate_unregister_scheme(PurpleCertificateScheme *scheme)
Unregister a CertificateScheme from libpurple.
gboolean purple_certificate_unregister_pool(PurpleCertificatePool *pool)
Unregister a CertificatePool with libpurple and call its uninit function.
gboolean purple_certificate_signed_by(PurpleCertificate *crt, PurpleCertificate *issuer)
Check whether 'crt' has a valid signature made by 'issuer'.
void purple_certificate_destroy_list(GList *crt_list)
Destroy an entire list of Certificate instances and the containing list.
PurpleCertificateScheme * purple_certificate_find_scheme(const gchar *name)
Look up a registered CertificateScheme by name.
gboolean purple_certificate_register_verifier(PurpleCertificateVerifier *vr)
Register a CertificateVerifier with libpurple.
gboolean purple_certificate_pool_store(PurpleCertificatePool *pool, const gchar *id, PurpleCertificate *crt)
Add a certificate to a pool.
gboolean purple_certificate_pool_contains(PurpleCertificatePool *pool, const gchar *id)
Check for presence of an ID in a pool.
void purple_certificate_destroy(PurpleCertificate *crt)
Destroys and free()'s a Certificate.
gboolean(* register_trusted_tls_cert)(PurpleCertificate *crt, gboolean ca)
Register a certificate as "trusted.".
Definition: certificate.h:310
gboolean(* put_cert)(const gchar *id, PurpleCertificate *crt)
Add a certificate to the pool.
Definition: certificate.h:169
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
PurpleCertificateScheme * scheme
Reference to the scheme used.
Definition: certificate.h:383
gchar * fullname
User-friendly name for this type ex: N_("X.509 Certificates") When this is displayed anywhere...
Definition: certificate.h:204
GSList * purple_certificates_import(PurpleCertificateScheme *scheme, const gchar *filename)
Imports a list of PurpleCertificates from a file.
gboolean(* check_subject_name)(PurpleCertificate *crt, const gchar *name)
Check the subject name against that on the certificate.
Definition: certificate.h:294
gchar * name
Name of the certificate type ex: "x509", "pgp", etc.
Definition: certificate.h:197
gchar * purple_certificate_get_subject_name(PurpleCertificate *crt)
Gets the certificate subject's name.
GList * purple_certificate_get_verifiers(void)
Get the list of registered CertificateVerifiers.
void purple_certificate_pool_destroy_idlist(GList *idlist)
Destroys the result given by purple_certificate_pool_get_idlist()
gboolean(* cert_in_pool)(const gchar *id)
Check for presence of a certificate in the pool using unique ID.
Definition: certificate.h:162
gpointer data
Internal data used by the Verifier code.
Definition: certificate.h:400
gpointer data
Internal pool data.
Definition: certificate.h:143
gchar * purple_certificate_get_unique_id(PurpleCertificate *crt)
Get a unique identifier for the certificate.
gboolean purple_certificate_check_subject_name(PurpleCertificate *crt, const gchar *name)
Check the subject name against that on the certificate.
A certificate type.
Definition: certificate.h:190
void(* destroy_request)(PurpleCertificateVerificationRequest *vrq)
Destroy a completed Request under this Verifier The function pointed to here is only responsible for ...
Definition: certificate.h:362
gboolean purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration)
Get the expiration/activation times.
gchar * subject_name
Name to check that the certificate is issued to.
Definition: certificate.h:390
gchar * scheme_name
Scheme this Pool operates for.
Definition: certificate.h:131
gpointer cb_data
Data to pass to the post-verification callback.
Definition: certificate.h:405
GList * purple_certificate_copy_list(GList *crt_list)
Duplicates an entire list of certificates.
void(* start_verification)(PurpleCertificateVerificationRequest *vrq)
Start the verification process.
Definition: certificate.h:352
gboolean purple_certificate_unregister_verifier(PurpleCertificateVerifier *vr)
Unregister a CertificateVerifier with libpurple.
void purple_certificate_uninit(void)
Un-initialize the certificate system.
gboolean purple_certificate_export(const gchar *filename, PurpleCertificate *crt)
Exports a PurpleCertificate to a file.
gchar * name
Internal name to refer to the pool by.
Definition: certificate.h:133
PurpleCertificateVerifier * verifier
Reference to the verification logic used.
Definition: certificate.h:378
gboolean(* export_certificate)(const gchar *filename, PurpleCertificate *crt)
Exports a certificate to a file.
Definition: certificate.h:222
gboolean purple_certificate_pool_usable(PurpleCertificatePool *pool)
Determines whether a pool can be used.
PurpleCertificateScheme * purple_certificate_pool_get_scheme(PurpleCertificatePool *pool)
Looks up the scheme the pool operates under.
gpointer purple_certificate_get_handle(void)
Get the Certificate subsystem handle for signalling purposes.
PurpleCertificate * purple_certificate_pool_retrieve(PurpleCertificatePool *pool, const gchar *id)
Retrieve a certificate from a pool.
PurpleCertificateVerifier * purple_certificate_find_verifier(const gchar *scheme_name, const gchar *ver_name)
Look up a registered PurpleCertificateVerifier by scheme and name.
void(* verify_cert)(PurpleCertificateVerificationRequest *vrq, PurpleCertificateInvalidityFlags *flags)
Verify that a certificate is valid, performing all necessary checks including date range...
Definition: certificate.h:316
gboolean(* delete_cert)(const gchar *id)
Delete a certificate from the pool.
Definition: certificate.h:171
PurpleCertificateVerifiedCallback cb
Function to call with the verification result.
Definition: certificate.h:403
Database for retrieval or storage of Certificates.
Definition: certificate.h:128
gboolean purple_certificate_pool_delete(PurpleCertificatePool *pool, const gchar *id)
Remove a certificate from a pool.
A certificate instance.
Definition: certificate.h:114
GByteArray * purple_certificate_get_fingerprint_sha1(PurpleCertificate *crt)
Retrieves the certificate public key fingerprint using SHA1.
PurpleCertificateScheme * scheme
Scheme this certificate is under.
Definition: certificate.h:117
void(* PurpleCertificateVerifiedCallback)(PurpleCertificateVerificationStatus st, gpointer userdata)
Callback function for the results of a verification check.
Definition: certificate.h:106
void purple_certificate_display_x509(PurpleCertificate *crt)
Displays a window showing X.509 certificate information.
void purple_certificate_verify_complete(PurpleCertificateVerificationRequest *vrq, PurpleCertificateVerificationStatus st)
Completes and destroys a VerificationRequest.
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.
gchar * name
Name of the Verifier - case insensitive.
Definition: certificate.h:340