pidgin  2.14.10
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 
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 
324  unsigned long struct_size;
325 
334  GByteArray * (* get_fingerprint_sha256)(PurpleCertificate *crt);
335 
345 };
346 
347 #define PURPLE_CERTIFICATE_SCHEME_HAS_FUNC(obj, member) \
348  (((G_STRUCT_OFFSET(PurpleCertificateScheme, member) < G_STRUCT_OFFSET(PurpleCertificateScheme, struct_size)) \
349  || (G_STRUCT_OFFSET(PurpleCertificateScheme, member) < obj->struct_size)) && \
350  obj->member != NULL)
351 
352 
363 {
369  gchar *scheme_name;
370 
372  gchar *name;
373 
385 
395 
396  void (*_purple_reserved1)(void);
397  void (*_purple_reserved2)(void);
398  void (*_purple_reserved3)(void);
399  void (*_purple_reserved4)(void);
400 };
401 
408 {
416 
422  gchar *subject_name;
423 
429  GList *cert_chain;
430 
432  gpointer data;
433 
437  gpointer cb_data;
438 };
439 
440 /*****************************************************************************/
442 /*****************************************************************************/
468 void
470  const gchar *subject_name, GList *cert_chain,
472  gpointer cb_data);
473 
481 void
483  PurpleCertificateVerificationStatus st);
484 
487 /*****************************************************************************/
489 /*****************************************************************************/
500 
507 GList *
509 
515 void
517 
523 void
525 
536 gboolean
538 
557 gboolean
559  PurpleCertificate **failing);
560 
575 gboolean
577 
586 purple_certificate_import(PurpleCertificateScheme *scheme, const gchar *filename);
587 
595 GSList *
596 purple_certificates_import(PurpleCertificateScheme *scheme, const gchar *filename);
597 
605 gboolean
606 purple_certificate_export(const gchar *filename, PurpleCertificate *crt);
607 
608 
618 GByteArray *
620 
631 GByteArray *
633 
640 gchar *
642 
650 gchar *
652 
662 gchar *
664 
671 gboolean
673 
684 gboolean
685 purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration);
686 
698 gboolean
700 
703 /*****************************************************************************/
705 /*****************************************************************************/
718 gchar *
720 
730 gboolean
732 
743 
750 gboolean
752 
762 
773 gboolean
775 
783 gboolean
785 
793 GList *
795 
801 void
803 
806 /*****************************************************************************/
808 /*****************************************************************************/
814 void
816 
820 void
822 
826 gpointer
828 
835 
842 GList *
844 
853 gboolean
855 
863 gboolean
865 
872 purple_certificate_find_verifier(const gchar *scheme_name, const gchar *ver_name);
873 
880 GList *
882 
889 gboolean
891 
898 gboolean
900 
907 purple_certificate_find_pool(const gchar *scheme_name, const gchar *pool_name);
908 
915 GList *
917 
924 gboolean
926 
933 gboolean
935 
945 void
947 
954 
955 #ifdef __cplusplus
956 }
957 #endif /* __cplusplus */
958 
959 #endif /* _PURPLE_CERTIFICATE_H */
void purple_certificate_pool_destroy_idlist(GList *idlist)
Destroys the result given by purple_certificate_pool_get_idlist()
PurpleCertificateVerifier * purple_certificate_find_verifier(const gchar *scheme_name, const gchar *ver_name)
Look up a registered PurpleCertificateVerifier by scheme and name.
GList * purple_certificate_get_schemes(void)
Get all registered CertificateSchemes.
gboolean purple_certificate_register_pool(PurpleCertificatePool *pool)
Register a CertificatePool with libpurple and call its init function.
PurpleCertificate * purple_certificate_import(PurpleCertificateScheme *scheme, const gchar *filename)
Imports a PurpleCertificate from a file.
gboolean purple_certificate_unregister_scheme(PurpleCertificateScheme *scheme)
Unregister a CertificateScheme from libpurple.
void purple_certificate_init(void)
Initialize the certificate system.
GByteArray * purple_certificate_get_fingerprint_sha1(PurpleCertificate *crt)
Retrieves the certificate public key fingerprint using SHA1.
PurpleCertificateScheme * purple_certificate_find_scheme(const gchar *name)
Look up a registered CertificateScheme by name.
void purple_certificate_destroy_list(GList *crt_list)
Destroy an entire list of Certificate instances and the containing list.
PurpleCertificate * purple_certificate_pool_retrieve(PurpleCertificatePool *pool, const gchar *id)
Retrieve a certificate from a pool.
void(* PurpleCertificateVerifiedCallback)(PurpleCertificateVerificationStatus st, gpointer userdata)
Callback function for the results of a verification check.
Definition: certificate.h:106
gchar * purple_certificate_get_unique_id(PurpleCertificate *crt)
Get a unique identifier for the certificate.
PurpleCertificate * purple_certificate_copy(PurpleCertificate *crt)
Makes a duplicate of a certificate.
gchar * purple_certificate_pool_mkpath(PurpleCertificatePool *pool, const gchar *id)
Helper function for generating file paths in ~/.purple/certificates for CertificatePools that use the...
gboolean purple_certificate_pool_delete(PurpleCertificatePool *pool, const gchar *id)
Remove a certificate from a pool.
gboolean purple_certificate_pool_contains(PurpleCertificatePool *pool, const gchar *id)
Check for presence of an ID in a pool.
gboolean purple_certificate_check_signature_chain(GList *chain)
Check that a certificate chain is valid.
gboolean purple_certificate_export(const gchar *filename, PurpleCertificate *crt)
Exports a PurpleCertificate to a file.
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.
GList * purple_certificate_pool_get_idlist(PurpleCertificatePool *pool)
Get the list of IDs currently in the pool.
GByteArray * purple_certificate_get_fingerprint_sha256(PurpleCertificate *crt, gboolean sha1_fallback)
Retrieves the certificate public key fingerprint using SHA256.
GSList * purple_certificates_import(PurpleCertificateScheme *scheme, const gchar *filename)
Imports a list of PurpleCertificates from a file.
void purple_certificate_verify_complete(PurpleCertificateVerificationRequest *vrq, PurpleCertificateVerificationStatus st)
Completes and destroys a VerificationRequest.
PurpleCertificateScheme * purple_certificate_pool_get_scheme(PurpleCertificatePool *pool)
Looks up the scheme the pool operates under.
GList * purple_certificate_get_pools(void)
Get the list of registered Pools.
gchar * purple_certificate_get_subject_name(PurpleCertificate *crt)
Gets the certificate subject's name.
void purple_certificate_add_ca_search_path(const char *path)
Add a search path for certificates.
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 purple_certificate_unregister_pool(PurpleCertificatePool *pool)
Unregister a CertificatePool with libpurple and call its uninit function.
gboolean purple_certificate_compare_pubkeys(PurpleCertificate *crt1, PurpleCertificate *crt2)
Compares the public keys of two certificates.
GList * purple_certificate_get_verifiers(void)
Get the list of registered CertificateVerifiers.
gboolean purple_certificate_pool_store(PurpleCertificatePool *pool, const gchar *id, PurpleCertificate *crt)
Add a certificate to a pool.
gpointer purple_certificate_get_handle(void)
Get the Certificate subsystem handle for signalling purposes.
GList * purple_certificate_copy_list(GList *crt_list)
Duplicates an entire list of certificates.
gboolean purple_certificate_pool_usable(PurpleCertificatePool *pool)
Determines whether a pool can be used.
PurpleCertificatePool * purple_certificate_find_pool(const gchar *scheme_name, const gchar *pool_name)
Look up a registered PurpleCertificatePool by scheme and name.
gboolean purple_certificate_check_subject_name(PurpleCertificate *crt, const gchar *name)
Check the subject name against that on the certificate.
void purple_certificate_display_x509(PurpleCertificate *crt)
Displays a window showing X.509 certificate information.
gboolean purple_certificate_signed_by(PurpleCertificate *crt, PurpleCertificate *issuer)
Check whether 'crt' has a valid signature made by 'issuer'.
gboolean purple_certificate_register_verifier(PurpleCertificateVerifier *vr)
Register a CertificateVerifier with libpurple.
gboolean purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration)
Get the expiration/activation times.
void purple_certificate_uninit(void)
Un-initialize the certificate system.
gboolean purple_certificate_register_scheme(PurpleCertificateScheme *scheme)
Register a CertificateScheme with libpurple.
gboolean purple_certificate_unregister_verifier(PurpleCertificateVerifier *vr)
Unregister a CertificateVerifier with libpurple.
gchar * purple_certificate_get_issuer_unique_id(PurpleCertificate *crt)
Get a unique identifier for the certificate's issuer.
void purple_certificate_destroy(PurpleCertificate *crt)
Destroys and free()'s a Certificate.
Database for retrieval or storage of Certificates.
Definition: certificate.h:129
gboolean(* cert_in_pool)(const gchar *id)
Check for presence of a certificate in the pool using unique ID.
Definition: certificate.h:162
gboolean(* delete_cert)(const gchar *id)
Delete a certificate from the pool.
Definition: certificate.h:171
gchar * name
Internal name to refer to the pool by.
Definition: certificate.h:133
gchar * fullname
User-friendly name for this type ex: N_("SSL Servers") When this is displayed anywhere,...
Definition: certificate.h:140
gchar * scheme_name
Scheme this Pool operates for.
Definition: certificate.h:131
gboolean(* init)(void)
Set up the Pool's internal state.
Definition: certificate.h:152
void(* uninit)(void)
Uninit the Pool's internal state.
Definition: certificate.h:159
gpointer data
Internal pool data.
Definition: certificate.h:143
gboolean(* put_cert)(const gchar *id, PurpleCertificate *crt)
Add a certificate to the pool.
Definition: certificate.h:169
A certificate type.
Definition: certificate.h:191
gchar * fullname
User-friendly name for this type ex: N_("X.509 Certificates") When this is displayed anywhere,...
Definition: certificate.h:204
gboolean(* check_subject_name)(PurpleCertificate *crt, const gchar *name)
Check the subject name against that on the certificate.
Definition: certificate.h:294
void(* destroy_certificate)(PurpleCertificate *crt)
Destroys and frees a Certificate structure.
Definition: certificate.h:243
unsigned long struct_size
The size of the PurpleCertificateScheme.
Definition: certificate.h:324
gboolean(* export_certificate)(const gchar *filename, PurpleCertificate *crt)
Exports a certificate to a file.
Definition: certificate.h:222
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
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(* get_times)(PurpleCertificate *crt, time_t *activation, time_t *expiration)
Retrieve the certificate activation/expiration times.
Definition: certificate.h:297
gboolean(* compare_pubkeys)(PurpleCertificate *crt1, PurpleCertificate *crt2)
Compares the public keys of two certificates.
Definition: certificate.h:344
gchar * name
Name of the certificate type ex: "x509", "pgp", etc.
Definition: certificate.h:197
gboolean(* register_trusted_tls_cert)(PurpleCertificate *crt, gboolean ca)
Register a certificate as "trusted.".
Definition: certificate.h:310
Structure for a single certificate request.
Definition: certificate.h:408
PurpleCertificateVerifier * verifier
Reference to the verification logic used.
Definition: certificate.h:410
gpointer data
Internal data used by the Verifier code.
Definition: certificate.h:432
gpointer cb_data
Data to pass to the post-verification callback.
Definition: certificate.h:437
gchar * subject_name
Name to check that the certificate is issued to.
Definition: certificate.h:422
PurpleCertificateScheme * scheme
Reference to the scheme used.
Definition: certificate.h:415
PurpleCertificateVerifiedCallback cb
Function to call with the verification result.
Definition: certificate.h:435
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
A set of operations used to provide logic for verifying a Certificate's authenticity.
Definition: certificate.h:363
void(* start_verification)(PurpleCertificateVerificationRequest *vrq)
Start the verification process.
Definition: certificate.h:384
void(* destroy_request)(PurpleCertificateVerificationRequest *vrq)
Destroy a completed Request under this Verifier The function pointed to here is only responsible for ...
Definition: certificate.h:394
gchar * scheme_name
Name of the scheme this Verifier operates on.
Definition: certificate.h:369
gchar * name
Name of the Verifier - case insensitive.
Definition: certificate.h:372
A certificate instance.
Definition: certificate.h:115
gpointer data
Opaque pointer to internal data.
Definition: certificate.h:119
PurpleCertificateScheme * scheme
Scheme this certificate is under.
Definition: certificate.h:117