certificate.h
Go to the documentation of this file.
00001 
00008 /*
00009  *
00010  * purple
00011  *
00012  * Purple is the legal property of its developers, whose names are too numerous
00013  * to list here.  Please refer to the COPYRIGHT file distributed with this
00014  * source distribution.
00015  *
00016  * This program is free software; you can redistribute it and/or modify
00017  * it under the terms of the GNU General Public License as published by
00018  * the Free Software Foundation; either version 2 of the License, or
00019  * (at your option) any later version.
00020  *
00021  * This program is distributed in the hope that it will be useful,
00022  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00023  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00024  * GNU General Public License for more details.
00025  *
00026  * You should have received a copy of the GNU General Public License
00027  * along with this program; if not, write to the Free Software
00028  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
00029  */
00030 
00031 #ifndef _PURPLE_CERTIFICATE_H
00032 #define _PURPLE_CERTIFICATE_H
00033 
00034 #include <time.h>
00035 
00036 #include <glib.h>
00037 
00038 #ifdef __cplusplus
00039 extern "C" {
00040 #endif /* __cplusplus */
00041 
00042 
00043 typedef enum
00044 {
00045     PURPLE_CERTIFICATE_INVALID = 0,
00046     PURPLE_CERTIFICATE_VALID = 1
00047 } PurpleCertificateVerificationStatus;
00048 
00049 /*
00050  * TODO: Merge this with PurpleCertificateVerificationStatus for 3.0.0 */
00051 typedef enum {
00052     PURPLE_CERTIFICATE_UNKNOWN_ERROR = -1,
00053 
00054     /* Not an error */
00055     PURPLE_CERTIFICATE_NO_PROBLEMS = 0,
00056 
00057     /* Non-fatal */
00058     PURPLE_CERTIFICATE_NON_FATALS_MASK = 0x0000FFFF,
00059 
00060     /* The certificate is self-signed. */
00061     PURPLE_CERTIFICATE_SELF_SIGNED = 0x01,
00062 
00063     /* The CA is not in libpurple's pool of certificates. */
00064     PURPLE_CERTIFICATE_CA_UNKNOWN = 0x02,
00065 
00066     /* The current time is before the certificate's specified
00067      * activation time.
00068      */
00069     PURPLE_CERTIFICATE_NOT_ACTIVATED = 0x04,
00070 
00071     /* The current time is after the certificate's specified expiration time */
00072     PURPLE_CERTIFICATE_EXPIRED = 0x08,
00073 
00074     /* The certificate's subject name doesn't match the expected */
00075     PURPLE_CERTIFICATE_NAME_MISMATCH = 0x10,
00076 
00077     /* No CA pool was found. This shouldn't happen... */
00078     PURPLE_CERTIFICATE_NO_CA_POOL = 0x20,
00079 
00080     /* Fatal */
00081     PURPLE_CERTIFICATE_FATALS_MASK = 0xFFFF0000,
00082 
00083     /* The signature chain could not be validated. Due to limitations in the
00084      * the current API, this also indicates one of the CA certificates in the
00085      * chain is expired (or not yet activated). FIXME 3.0.0 */
00086     PURPLE_CERTIFICATE_INVALID_CHAIN = 0x10000,
00087 
00088     /* The signature has been revoked. */
00089     PURPLE_CERTIFICATE_REVOKED = 0x20000,
00090 
00091     PURPLE_CERTIFICATE_LAST = 0x40000,
00092 } PurpleCertificateInvalidityFlags;
00093 
00094 typedef struct _PurpleCertificate PurpleCertificate;
00095 typedef struct _PurpleCertificatePool PurpleCertificatePool;
00096 typedef struct _PurpleCertificateScheme PurpleCertificateScheme;
00097 typedef struct _PurpleCertificateVerifier PurpleCertificateVerifier;
00098 typedef struct _PurpleCertificateVerificationRequest PurpleCertificateVerificationRequest;
00099 
00105 typedef void (*PurpleCertificateVerifiedCallback)
00106         (PurpleCertificateVerificationStatus st,
00107          gpointer userdata);
00108 
00114 struct _PurpleCertificate
00115 {
00117     PurpleCertificateScheme * scheme;
00119     gpointer data;
00120 };
00121 
00128 struct _PurpleCertificatePool
00129 {
00131     gchar *scheme_name;
00133     gchar *name;
00134 
00140     gchar *fullname;
00141 
00143     gpointer data;
00144 
00152     gboolean (* init)(void);
00153 
00159     void (* uninit)(void);
00160 
00162     gboolean (* cert_in_pool)(const gchar *id);
00164     PurpleCertificate * (* get_cert)(const gchar *id);
00169     gboolean (* put_cert)(const gchar *id, PurpleCertificate *crt);
00171     gboolean (* delete_cert)(const gchar *id);
00172 
00174     GList * (* get_idlist)(void);
00175 
00176     void (*_purple_reserved1)(void);
00177     void (*_purple_reserved2)(void);
00178     void (*_purple_reserved3)(void);
00179     void (*_purple_reserved4)(void);
00180 };
00181 
00190 struct _PurpleCertificateScheme
00191 {
00197     gchar * name;
00198 
00204     gchar * fullname;
00205 
00212     PurpleCertificate * (* import_certificate)(const gchar * filename);
00213 
00222     gboolean (* export_certificate)(const gchar *filename, PurpleCertificate *crt);
00223 
00232     PurpleCertificate * (* copy_certificate)(PurpleCertificate *crt);
00233 
00243     void (* destroy_certificate)(PurpleCertificate * crt);
00244 
00248     gboolean (*signed_by)(PurpleCertificate *crt, PurpleCertificate *issuer);
00256     GByteArray * (* get_fingerprint_sha1)(PurpleCertificate *crt);
00257 
00265     gchar * (* get_unique_id)(PurpleCertificate *crt);
00266 
00274     gchar * (* get_issuer_unique_id)(PurpleCertificate *crt);
00275 
00287     gchar * (* get_subject_name)(PurpleCertificate *crt);
00288 
00294     gboolean (* check_subject_name)(PurpleCertificate *crt, const gchar *name);
00295 
00297     gboolean (* get_times)(PurpleCertificate *crt, time_t *activation, time_t *expiration);
00298 
00305     GSList * (* import_certificates)(const gchar * filename);
00306 
00310     gboolean (* register_trusted_tls_cert)(PurpleCertificate *crt, gboolean ca);
00311 
00316     void (* verify_cert)(PurpleCertificateVerificationRequest *vrq, PurpleCertificateInvalidityFlags *flags);
00317 
00318     void (*_purple_reserved3)(void);
00319 };
00320 
00330 struct _PurpleCertificateVerifier
00331 {
00337     gchar *scheme_name;
00338 
00340     gchar *name;
00341 
00352     void (* start_verification)(PurpleCertificateVerificationRequest *vrq);
00353 
00362     void (* destroy_request)(PurpleCertificateVerificationRequest *vrq);
00363 
00364     void (*_purple_reserved1)(void);
00365     void (*_purple_reserved2)(void);
00366     void (*_purple_reserved3)(void);
00367     void (*_purple_reserved4)(void);
00368 };
00369 
00375 struct _PurpleCertificateVerificationRequest
00376 {
00378     PurpleCertificateVerifier *verifier;
00383     PurpleCertificateScheme *scheme;
00384 
00390     gchar *subject_name;
00391 
00397     GList *cert_chain;
00398 
00400     gpointer data;
00401 
00403     PurpleCertificateVerifiedCallback cb;
00405     gpointer cb_data;
00406 };
00407 
00408 /*****************************************************************************/
00410 /*****************************************************************************/
00436 void
00437 purple_certificate_verify (PurpleCertificateVerifier *verifier,
00438                const gchar *subject_name, GList *cert_chain,
00439                PurpleCertificateVerifiedCallback cb,
00440                gpointer cb_data);
00441 
00449 void
00450 purple_certificate_verify_complete(PurpleCertificateVerificationRequest *vrq,
00451                    PurpleCertificateVerificationStatus st);
00452 
00455 /*****************************************************************************/
00457 /*****************************************************************************/
00466 PurpleCertificate *
00467 purple_certificate_copy(PurpleCertificate *crt);
00468 
00475 GList *
00476 purple_certificate_copy_list(GList *crt_list);
00477 
00483 void
00484 purple_certificate_destroy (PurpleCertificate *crt);
00485 
00491 void
00492 purple_certificate_destroy_list (GList * crt_list);
00493 
00504 gboolean
00505 purple_certificate_signed_by(PurpleCertificate *crt, PurpleCertificate *issuer);
00506 
00525 gboolean
00526 purple_certificate_check_signature_chain_with_failing(GList *chain,
00527         PurpleCertificate **failing);
00528 
00543 gboolean
00544 purple_certificate_check_signature_chain(GList *chain);
00545 
00553 PurpleCertificate *
00554 purple_certificate_import(PurpleCertificateScheme *scheme, const gchar *filename);
00555 
00563 GSList *
00564 purple_certificates_import(PurpleCertificateScheme *scheme, const gchar *filename);
00565 
00573 gboolean
00574 purple_certificate_export(const gchar *filename, PurpleCertificate *crt);
00575 
00576 
00585 GByteArray *
00586 purple_certificate_get_fingerprint_sha1(PurpleCertificate *crt);
00587 
00594 gchar *
00595 purple_certificate_get_unique_id(PurpleCertificate *crt);
00596 
00604 gchar *
00605 purple_certificate_get_issuer_unique_id(PurpleCertificate *crt);
00606 
00616 gchar *
00617 purple_certificate_get_subject_name(PurpleCertificate *crt);
00618 
00625 gboolean
00626 purple_certificate_check_subject_name(PurpleCertificate *crt, const gchar *name);
00627 
00638 gboolean
00639 purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration);
00640 
00643 /*****************************************************************************/
00645 /*****************************************************************************/
00658 gchar *
00659 purple_certificate_pool_mkpath(PurpleCertificatePool *pool, const gchar *id);
00660 
00670 gboolean
00671 purple_certificate_pool_usable(PurpleCertificatePool *pool);
00672 
00681 PurpleCertificateScheme *
00682 purple_certificate_pool_get_scheme(PurpleCertificatePool *pool);
00683 
00690 gboolean
00691 purple_certificate_pool_contains(PurpleCertificatePool *pool, const gchar *id);
00692 
00699 PurpleCertificate *
00700 purple_certificate_pool_retrieve(PurpleCertificatePool *pool, const gchar *id);
00701 
00712 gboolean
00713 purple_certificate_pool_store(PurpleCertificatePool *pool, const gchar *id, PurpleCertificate *crt);
00714 
00722 gboolean
00723 purple_certificate_pool_delete(PurpleCertificatePool *pool, const gchar *id);
00724 
00732 GList *
00733 purple_certificate_pool_get_idlist(PurpleCertificatePool *pool);
00734 
00740 void
00741 purple_certificate_pool_destroy_idlist(GList *idlist);
00742 
00745 /*****************************************************************************/
00747 /*****************************************************************************/
00753 void
00754 purple_certificate_init(void);
00755 
00759 void
00760 purple_certificate_uninit(void);
00761 
00765 gpointer
00766 purple_certificate_get_handle(void);
00767 
00772 PurpleCertificateScheme *
00773 purple_certificate_find_scheme(const gchar *name);
00774 
00781 GList *
00782 purple_certificate_get_schemes(void);
00783 
00792 gboolean
00793 purple_certificate_register_scheme(PurpleCertificateScheme *scheme);
00794 
00802 gboolean
00803 purple_certificate_unregister_scheme(PurpleCertificateScheme *scheme);
00804 
00810 PurpleCertificateVerifier *
00811 purple_certificate_find_verifier(const gchar *scheme_name, const gchar *ver_name);
00812 
00819 GList *
00820 purple_certificate_get_verifiers(void);
00821 
00828 gboolean
00829 purple_certificate_register_verifier(PurpleCertificateVerifier *vr);
00830 
00837 gboolean
00838 purple_certificate_unregister_verifier(PurpleCertificateVerifier *vr);
00839 
00845 PurpleCertificatePool *
00846 purple_certificate_find_pool(const gchar *scheme_name, const gchar *pool_name);
00847 
00854 GList *
00855 purple_certificate_get_pools(void);
00856 
00863 gboolean
00864 purple_certificate_register_pool(PurpleCertificatePool *pool);
00865 
00872 gboolean
00873 purple_certificate_unregister_pool(PurpleCertificatePool *pool);
00874 
00884 void
00885 purple_certificate_display_x509(PurpleCertificate *crt);
00886 
00892 void purple_certificate_add_ca_search_path(const char *path);
00893 
00894 #ifdef __cplusplus
00895 }
00896 #endif /* __cplusplus */
00897 
00898 #endif /* _PURPLE_CERTIFICATE_H */