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 
00324     unsigned long struct_size;
00325 
00334     GByteArray * (* get_fingerprint_sha256)(PurpleCertificate *crt);
00335 
00344     gboolean (* compare_pubkeys)(PurpleCertificate *crt1, PurpleCertificate *crt2);
00345 };
00346 
00347 #define PURPLE_CERTIFICATE_SCHEME_HAS_FUNC(obj, member) \
00348     (((G_STRUCT_OFFSET(PurpleCertificateScheme, member) < G_STRUCT_OFFSET(PurpleCertificateScheme, struct_size)) \
00349       || (G_STRUCT_OFFSET(PurpleCertificateScheme, member) < obj->struct_size)) && \
00350      obj->member != NULL)
00351 
00352 
00362 struct _PurpleCertificateVerifier
00363 {
00369     gchar *scheme_name;
00370 
00372     gchar *name;
00373 
00384     void (* start_verification)(PurpleCertificateVerificationRequest *vrq);
00385 
00394     void (* destroy_request)(PurpleCertificateVerificationRequest *vrq);
00395 
00396     void (*_purple_reserved1)(void);
00397     void (*_purple_reserved2)(void);
00398     void (*_purple_reserved3)(void);
00399     void (*_purple_reserved4)(void);
00400 };
00401 
00407 struct _PurpleCertificateVerificationRequest
00408 {
00410     PurpleCertificateVerifier *verifier;
00415     PurpleCertificateScheme *scheme;
00416 
00422     gchar *subject_name;
00423 
00429     GList *cert_chain;
00430 
00432     gpointer data;
00433 
00435     PurpleCertificateVerifiedCallback cb;
00437     gpointer cb_data;
00438 };
00439 
00440 /*****************************************************************************/
00442 /*****************************************************************************/
00468 void
00469 purple_certificate_verify (PurpleCertificateVerifier *verifier,
00470                const gchar *subject_name, GList *cert_chain,
00471                PurpleCertificateVerifiedCallback cb,
00472                gpointer cb_data);
00473 
00481 void
00482 purple_certificate_verify_complete(PurpleCertificateVerificationRequest *vrq,
00483                    PurpleCertificateVerificationStatus st);
00484 
00487 /*****************************************************************************/
00489 /*****************************************************************************/
00498 PurpleCertificate *
00499 purple_certificate_copy(PurpleCertificate *crt);
00500 
00507 GList *
00508 purple_certificate_copy_list(GList *crt_list);
00509 
00515 void
00516 purple_certificate_destroy (PurpleCertificate *crt);
00517 
00523 void
00524 purple_certificate_destroy_list (GList * crt_list);
00525 
00536 gboolean
00537 purple_certificate_signed_by(PurpleCertificate *crt, PurpleCertificate *issuer);
00538 
00557 gboolean
00558 purple_certificate_check_signature_chain_with_failing(GList *chain,
00559         PurpleCertificate **failing);
00560 
00575 gboolean
00576 purple_certificate_check_signature_chain(GList *chain);
00577 
00585 PurpleCertificate *
00586 purple_certificate_import(PurpleCertificateScheme *scheme, const gchar *filename);
00587 
00595 GSList *
00596 purple_certificates_import(PurpleCertificateScheme *scheme, const gchar *filename);
00597 
00605 gboolean
00606 purple_certificate_export(const gchar *filename, PurpleCertificate *crt);
00607 
00608 
00618 GByteArray *
00619 purple_certificate_get_fingerprint_sha1(PurpleCertificate *crt);
00620 
00631 GByteArray *
00632 purple_certificate_get_fingerprint_sha256(PurpleCertificate *crt, gboolean sha1_fallback);
00633 
00640 gchar *
00641 purple_certificate_get_unique_id(PurpleCertificate *crt);
00642 
00650 gchar *
00651 purple_certificate_get_issuer_unique_id(PurpleCertificate *crt);
00652 
00662 gchar *
00663 purple_certificate_get_subject_name(PurpleCertificate *crt);
00664 
00671 gboolean
00672 purple_certificate_check_subject_name(PurpleCertificate *crt, const gchar *name);
00673 
00684 gboolean
00685 purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration);
00686 
00698 gboolean
00699 purple_certificate_compare_pubkeys(PurpleCertificate *crt1, PurpleCertificate *crt2);
00700 
00703 /*****************************************************************************/
00705 /*****************************************************************************/
00718 gchar *
00719 purple_certificate_pool_mkpath(PurpleCertificatePool *pool, const gchar *id);
00720 
00730 gboolean
00731 purple_certificate_pool_usable(PurpleCertificatePool *pool);
00732 
00741 PurpleCertificateScheme *
00742 purple_certificate_pool_get_scheme(PurpleCertificatePool *pool);
00743 
00750 gboolean
00751 purple_certificate_pool_contains(PurpleCertificatePool *pool, const gchar *id);
00752 
00760 PurpleCertificate *
00761 purple_certificate_pool_retrieve(PurpleCertificatePool *pool, const gchar *id);
00762 
00773 gboolean
00774 purple_certificate_pool_store(PurpleCertificatePool *pool, const gchar *id, PurpleCertificate *crt);
00775 
00783 gboolean
00784 purple_certificate_pool_delete(PurpleCertificatePool *pool, const gchar *id);
00785 
00793 GList *
00794 purple_certificate_pool_get_idlist(PurpleCertificatePool *pool);
00795 
00801 void
00802 purple_certificate_pool_destroy_idlist(GList *idlist);
00803 
00806 /*****************************************************************************/
00808 /*****************************************************************************/
00814 void
00815 purple_certificate_init(void);
00816 
00820 void
00821 purple_certificate_uninit(void);
00822 
00826 gpointer
00827 purple_certificate_get_handle(void);
00828 
00833 PurpleCertificateScheme *
00834 purple_certificate_find_scheme(const gchar *name);
00835 
00842 GList *
00843 purple_certificate_get_schemes(void);
00844 
00853 gboolean
00854 purple_certificate_register_scheme(PurpleCertificateScheme *scheme);
00855 
00863 gboolean
00864 purple_certificate_unregister_scheme(PurpleCertificateScheme *scheme);
00865 
00871 PurpleCertificateVerifier *
00872 purple_certificate_find_verifier(const gchar *scheme_name, const gchar *ver_name);
00873 
00880 GList *
00881 purple_certificate_get_verifiers(void);
00882 
00889 gboolean
00890 purple_certificate_register_verifier(PurpleCertificateVerifier *vr);
00891 
00898 gboolean
00899 purple_certificate_unregister_verifier(PurpleCertificateVerifier *vr);
00900 
00906 PurpleCertificatePool *
00907 purple_certificate_find_pool(const gchar *scheme_name, const gchar *pool_name);
00908 
00915 GList *
00916 purple_certificate_get_pools(void);
00917 
00924 gboolean
00925 purple_certificate_register_pool(PurpleCertificatePool *pool);
00926 
00933 gboolean
00934 purple_certificate_unregister_pool(PurpleCertificatePool *pool);
00935 
00945 void
00946 purple_certificate_display_x509(PurpleCertificate *crt);
00947 
00953 void purple_certificate_add_ca_search_path(const char *path);
00954 
00955 #ifdef __cplusplus
00956 }
00957 #endif /* __cplusplus */
00958 
00959 #endif /* _PURPLE_CERTIFICATE_H */