libpurple/certificate.h

   1 /**
   2  * @file certificate.h Public-Key Certificate API
   3  * @ingroup core
   4  * @see @ref certificate-signals
   5  * @since 2.2.0
   6  */
   7
   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 typedef struct _PurpleCertificate PurpleCertificate;
  50 typedef struct _PurpleCertificatePool PurpleCertificatePool;
  51 typedef struct _PurpleCertificateScheme PurpleCertificateScheme;
  52 typedef struct _PurpleCertificateVerifier PurpleCertificateVerifier;
  53 typedef struct _PurpleCertificateVerificationRequest PurpleCertificateVerificationRequest;
  54
  55 /**
  56  * Callback function for the results of a verification check
  57  * @param st       Status code
  58  * @param userdata User-defined data
  59  */
  60 typedef void (*PurpleCertificateVerifiedCallback)
  61                 (PurpleCertificateVerificationStatus st,
  62                  gpointer userdata);
  63
  64 /** A certificate instance
  65  *
  66  *  An opaque data structure representing a single certificate under some
  67  *  CertificateScheme
  68  */
  69 struct _PurpleCertificate
  70 {
  71         /** Scheme this certificate is under */
  72         PurpleCertificateScheme * scheme;
  73         /** Opaque pointer to internal data */
  74         gpointer data;
  75 };
  76
  77 /**
  78  * Database for retrieval or storage of Certificates
  79  *
  80  * More or less a hash table; all lookups and writes are controlled by a string
  81  * key.
  82  */
  83 struct _PurpleCertificatePool
  84 {
  85         /** Scheme this Pool operates for */
  86         gchar *scheme_name;
  87         /** Internal name to refer to the pool by */
  88         gchar *name;
  89
  90         /** User-friendly name for this type
  91          *  ex: N_("SSL Servers")
  92          *  When this is displayed anywhere, it should be i18ned
  93          *  ex: _(pool->fullname)
  94          */
  95         gchar *fullname;
  96
  97         /** Internal pool data */
  98         gpointer data;
  99
 100         /**
 101          * Set up the Pool's internal state
 102          *
 103          * Upon calling purple_certificate_register_pool() , this function will
 104          * be called. May be NULL.
 105          * @return TRUE if the initialization succeeded, otherwise FALSE
 106          */
 107         gboolean (* init)(void);
 108
 109         /**
 110          * Uninit the Pool's internal state
 111          *
 112          * Will be called by purple_certificate_unregister_pool() . May be NULL
 113          */
 114         void (* uninit)(void);
 115
 116         /** Check for presence of a certificate in the pool using unique ID */
 117         gboolean (* cert_in_pool)(const gchar *id);
 118         /** Retrieve a PurpleCertificate from the pool */
 119         PurpleCertificate * (* get_cert)(const gchar *id);
 120         /** Add a certificate to the pool. Must overwrite any other
 121          *  certificates sharing the same ID in the pool.
 122          *  @return TRUE if the operation succeeded, otherwise FALSE
 123          */
 124         gboolean (* put_cert)(const gchar *id, PurpleCertificate *crt);
 125         /** Delete a certificate from the pool */
 126         gboolean (* delete_cert)(const gchar *id);
 127
 128         /** Returns a list of IDs stored in the pool */
 129         GList * (* get_idlist)(void);
 130
 131         void (*_purple_reserved1)(void);
 132         void (*_purple_reserved2)(void);
 133         void (*_purple_reserved3)(void);
 134         void (*_purple_reserved4)(void);
 135 };
 136
 137 /** A certificate type
 138  *
 139  *  A CertificateScheme must implement all of the fields in the structure,
 140  *  and register it using purple_certificate_register_scheme()
 141  *
 142  *  There may be only ONE CertificateScheme provided for each certificate
 143  *  type, as specified by the "name" field.
 144  */
 145 struct _PurpleCertificateScheme
 146 {
 147         /** Name of the certificate type
 148          *  ex: "x509", "pgp", etc.
 149          *  This must be globally unique - you may not register more than one
 150          *  CertificateScheme of the same name at a time.
 151          */
 152         gchar * name;
 153
 154         /** User-friendly name for this type
 155          *  ex: N_("X.509 Certificates")
 156          *  When this is displayed anywhere, it should be i18ned
 157          *  ex: _(scheme->fullname)
 158          */
 159         gchar * fullname;
 160
 161         /** Imports a certificate from a file
 162          *
 163          *  @param filename   File to import the certificate from
 164          *  @return           Pointer to the newly allocated Certificate struct
 165          *                    or NULL on failure.
 166          */
 167         PurpleCertificate * (* import_certificate)(const gchar * filename);
 168
 169         /**
 170          * Exports a certificate to a file
 171          *
 172          * @param filename    File to export the certificate to
 173          * @param crt         Certificate to export
 174          * @return TRUE if the export succeeded, otherwise FALSE
 175          * @see purple_certificate_export()
 176          */
 177         gboolean (* export_certificate)(const gchar *filename, PurpleCertificate *crt);
 178
 179         /**
 180          * Duplicates a certificate
 181          *
 182          * Certificates are generally assumed to be read-only, so feel free to
 183          * do any sort of reference-counting magic you want here. If this ever
 184          * changes, please remember to change the magic accordingly.
 185          * @return Reference to the new copy
 186          */
 187         PurpleCertificate * (* copy_certificate)(PurpleCertificate *crt);
 188
 189         /** Destroys and frees a Certificate structure
 190          *
 191          *  Destroys a Certificate's internal data structures and calls
 192          *  free(crt)
 193          *
 194          *  @param crt  Certificate instance to be destroyed. It WILL NOT be
 195          *              destroyed if it is not of the correct
 196          *              CertificateScheme. Can be NULL
 197          */
 198         void (* destroy_certificate)(PurpleCertificate * crt);
 199
 200         /** Find whether "crt" has a valid signature from issuer "issuer"
 201          *  @see purple_certificate_signed_by() */
 202         gboolean (*signed_by)(PurpleCertificate *crt, PurpleCertificate *issuer);
 203         /**
 204          * Retrieves the certificate public key fingerprint using SHA1
 205          *
 206          * @param crt   Certificate instance
 207          * @return Binary representation of SHA1 hash - must be freed using
 208          *         g_byte_array_free()
 209          */
 210         GByteArray * (* get_fingerprint_sha1)(PurpleCertificate *crt);
 211
 212         /**
 213          * Retrieves a unique certificate identifier
 214          *
 215          * @param crt   Certificate instance
 216          * @return Newly allocated string that can be used to uniquely
 217          *         identify the certificate.
 218          */
 219         gchar * (* get_unique_id)(PurpleCertificate *crt);
 220
 221         /**
 222          * Retrieves a unique identifier for the certificate's issuer
 223          *
 224          * @param crt   Certificate instance
 225          * @return Newly allocated string that can be used to uniquely
 226          *         identify the issuer's certificate.
 227          */
 228         gchar * (* get_issuer_unique_id)(PurpleCertificate *crt);
 229
 230         /**
 231          * Gets the certificate subject's name
 232          *
 233          * For X.509, this is the "Common Name" field, as we're only using it
 234          * for hostname verification at the moment
 235          *
 236          * @see purple_certificate_get_subject_name()
 237          *
 238          * @param crt   Certificate instance
 239          * @return Newly allocated string with the certificate subject.
 240          */
 241         gchar * (* get_subject_name)(PurpleCertificate *crt);
 242
 243         /**
 244          * Check the subject name against that on the certificate
 245          * @see purple_certificate_check_subject_name()
 246          * @return TRUE if it is a match, else FALSE
 247          */
 248         gboolean (* check_subject_name)(PurpleCertificate *crt, const gchar *name);
 249
 250         /** Retrieve the certificate activation/expiration times */
 251         gboolean (* get_times)(PurpleCertificate *crt, time_t *activation, time_t *expiration);
 252
 253         /** Imports certificates from a file
 254          *
 255          *  @param filename   File to import the certificates from
 256          *  @return           GSList of pointers to the newly allocated Certificate structs
 257          *                    or NULL on failure.
 258          */
 259         GSList * (* import_certificates)(const gchar * filename);
 260
 261         void (*_purple_reserved1)(void);
 262         void (*_purple_reserved2)(void);
 263         void (*_purple_reserved3)(void);
 264 };
 265
 266 /** A set of operations used to provide logic for verifying a Certificate's
 267  *  authenticity.
 268  *
 269  * A Verifier provider must fill out these fields, then register it using
 270  * purple_certificate_register_verifier()
 271  *
 272  * The (scheme_name, name) value must be unique for each Verifier - you may not
 273  * register more than one Verifier of the same name for each Scheme
 274  */
 275 struct _PurpleCertificateVerifier
 276 {
 277         /** Name of the scheme this Verifier operates on
 278          *
 279          * The scheme will be looked up by name when a Request is generated
 280          * using this Verifier
 281          */
 282         gchar *scheme_name;
 283
 284         /** Name of the Verifier - case insensitive */
 285         gchar *name;
 286
 287         /**
 288          * Start the verification process
 289          *
 290          * To be called from purple_certificate_verify once it has
 291          * constructed the request. This will use the information in the
 292          * given VerificationRequest to check the certificate and callback
 293          * the requester with the verification results.
 294          *
 295          * @param vrq      Request to process
 296          */
 297         void (* start_verification)(PurpleCertificateVerificationRequest *vrq);
 298
 299         /**
 300          * Destroy a completed Request under this Verifier
 301          * The function pointed to here is only responsible for cleaning up
 302          * whatever PurpleCertificateVerificationRequest::data points to.
 303          * It should not call free(vrq)
 304          *
 305          * @param vrq       Request to destroy
 306          */
 307         void (* destroy_request)(PurpleCertificateVerificationRequest *vrq);
 308
 309         void (*_purple_reserved1)(void);
 310         void (*_purple_reserved2)(void);
 311         void (*_purple_reserved3)(void);
 312         void (*_purple_reserved4)(void);
 313 };
 314
 315 /** Structure for a single certificate request
 316  *
 317  *  Useful for keeping track of the state of a verification that involves
 318  *  several steps
 319  */
 320 struct _PurpleCertificateVerificationRequest
 321 {
 322         /** Reference to the verification logic used */
 323         PurpleCertificateVerifier *verifier;
 324         /** Reference to the scheme used.
 325          *
 326          * This is looked up from the Verifier when the Request is generated
 327          */
 328         PurpleCertificateScheme *scheme;
 329
 330         /**
 331          * Name to check that the certificate is issued to
 332          *
 333          * For X.509 certificates, this is the Common Name
 334          */
 335         gchar *subject_name;
 336
 337         /** List of certificates in the chain to be verified (such as that returned by purple_ssl_get_peer_certificates )
 338          *
 339          * This is most relevant for X.509 certificates used in SSL sessions.
 340          * The list order should be: certificate, issuer, issuer's issuer, etc.
 341          */
 342         GList *cert_chain;
 343
 344         /** Internal data used by the Verifier code */
 345         gpointer data;
 346
 347         /** Function to call with the verification result */
 348         PurpleCertificateVerifiedCallback cb;
 349         /** Data to pass to the post-verification callback */
 350         gpointer cb_data;
 351 };
 352
 353 /*****************************************************************************/
 354 /** @name Certificate Verification Functions                                 */
 355 /*****************************************************************************/
 356 /*@{*/
 357
 358 /**
 359  * Constructs a verification request and passed control to the specified Verifier
 360  *
 361  * It is possible that the callback will be called immediately upon calling
 362  * this function. Plan accordingly.
 363  *
 364  * @param verifier      Verification logic to use.
 365  *                      @see purple_certificate_find_verifier()
 366  *
 367  * @param subject_name  Name that should match the first certificate in the
 368  *                      chain for the certificate to be valid. Will be strdup'd
 369  *                      into the Request struct
 370  *
 371  * @param cert_chain    Certificate chain to check. If there is more than one
 372  *                      certificate in the chain (X.509), the peer's
 373  *                      certificate comes first, then the issuer/signer's
 374  *                      certificate, etc. The whole list is duplicated into the
 375  *                      Request struct.
 376  *
 377  * @param cb            Callback function to be called with whether the
 378  *                      certificate was approved or not.
 379  * @param cb_data       User-defined data for the above.
 380  */
 381 void
 382 purple_certificate_verify (PurpleCertificateVerifier *verifier,
 383                            const gchar *subject_name, GList *cert_chain,
 384                            PurpleCertificateVerifiedCallback cb,
 385                            gpointer cb_data);
 386
 387 /**
 388  * Completes and destroys a VerificationRequest
 389  *
 390  * @param vrq           Request to conclude
 391  * @param st            Success/failure code to pass to the request's
 392  *                      completion callback.
 393  */
 394 void
 395 purple_certificate_verify_complete(PurpleCertificateVerificationRequest *vrq,
 396                                    PurpleCertificateVerificationStatus st);
 397
 398 /*@}*/
 399
 400 /*****************************************************************************/
 401 /** @name Certificate Functions                                              */
 402 /*****************************************************************************/
 403 /*@{*/
 404
 405 /**
 406  * Makes a duplicate of a certificate
 407  *
 408  * @param crt        Instance to duplicate
 409  * @return Pointer to new instance
 410  */
 411 PurpleCertificate *
 412 purple_certificate_copy(PurpleCertificate *crt);
 413
 414 /**
 415  * Duplicates an entire list of certificates
 416  *
 417  * @param crt_list   List to duplicate
 418  * @return New list copy
 419  */
 420 GList *
 421 purple_certificate_copy_list(GList *crt_list);
 422
 423 /**
 424  * Destroys and free()'s a Certificate
 425  *
 426  * @param crt        Instance to destroy. May be NULL.
 427  */
 428 void
 429 purple_certificate_destroy (PurpleCertificate *crt);
 430
 431 /**
 432  * Destroy an entire list of Certificate instances and the containing list
 433  *
 434  * @param crt_list   List of certificates to destroy. May be NULL.
 435  */
 436 void
 437 purple_certificate_destroy_list (GList * crt_list);
 438
 439 /**
 440  * Check whether 'crt' has a valid signature made by 'issuer'
 441  *
 442  * @param crt        Certificate instance to check signature of
 443  * @param issuer     Certificate thought to have signed 'crt'
 444  *
 445  * @return TRUE if 'crt' has a valid signature made by 'issuer',
 446  *         otherwise FALSE
 447  * @todo Find a way to give the reason (bad signature, not the issuer, etc.)
 448  */
 449 gboolean
 450 purple_certificate_signed_by(PurpleCertificate *crt, PurpleCertificate *issuer);
 451
 452 /**
 453  * Check that a certificate chain is valid and, if not, the failing certificate.
 454  *
 455  * Uses purple_certificate_signed_by() to verify that each PurpleCertificate
 456  * in the chain carries a valid signature from the next. A single-certificate
 457  * chain is considered to be valid.
 458  *
 459  * @param chain      List of PurpleCertificate instances comprising the chain,
 460  *                   in the order certificate, issuer, issuer's issuer, etc.
 461  * @param failing    A pointer to a PurpleCertificate*. If not NULL, if the
 462  *                   chain fails to validate, this will be set to the
 463  *                   certificate whose signature could not be validated.
 464  * @return TRUE if the chain is valid. See description.
 465  *
 466  * @since 2.6.0
 467  * @deprecated  This function will become
 468  *              purple_certificate_check_signature_chain in 3.0.0
 469  */
 470 gboolean
 471 purple_certificate_check_signature_chain_with_failing(GList *chain,
 472                 PurpleCertificate **failing);
 473
 474 /**
 475  * Check that a certificate chain is valid
 476  *
 477  * Uses purple_certificate_signed_by() to verify that each PurpleCertificate
 478  * in the chain carries a valid signature from the next. A single-certificate
 479  * chain is considered to be valid.
 480  *
 481  * @param chain      List of PurpleCertificate instances comprising the chain,
 482  *                   in the order certificate, issuer, issuer's issuer, etc.
 483  * @return TRUE if the chain is valid. See description.
 484  * @todo Specify which certificate in the chain caused a failure
 485  * @deprecated  This function will be removed in 3.0.0 and replaced with
 486  *              purple_certificate_check_signature_chain_with_failing
 487  */
 488 gboolean
 489 purple_certificate_check_signature_chain(GList *chain);
 490
 491 /**
 492  * Imports a PurpleCertificate from a file
 493  *
 494  * @param scheme      Scheme to import under
 495  * @param filename    File path to import from
 496  * @return Pointer to a new PurpleCertificate, or NULL on failure
 497  */
 498 PurpleCertificate *
 499 purple_certificate_import(PurpleCertificateScheme *scheme, const gchar *filename);
 500
 501 /**
 502  * Imports a list of PurpleCertificates from a file
 503  *
 504  * @param scheme      Scheme to import under
 505  * @param filename    File path to import from
 506  * @return Pointer to a GSList of new PurpleCertificates, or NULL on failure
 507  */
 508 GSList *
 509 purple_certificates_import(PurpleCertificateScheme *scheme, const gchar *filename);
 510
 511 /**
 512  * Exports a PurpleCertificate to a file
 513  *
 514  * @param filename    File to export the certificate to
 515  * @param crt         Certificate to export
 516  * @return TRUE if the export succeeded, otherwise FALSE
 517  */
 518 gboolean
 519 purple_certificate_export(const gchar *filename, PurpleCertificate *crt);
 520
 521
 522 /**
 523  * Retrieves the certificate public key fingerprint using SHA1.
 524  *
 525  * @param crt        Certificate instance
 526  * @return Binary representation of the hash. You are responsible for free()ing
 527  *         this.
 528  * @see purple_base16_encode_chunked()
 529  */
 530 GByteArray *
 531 purple_certificate_get_fingerprint_sha1(PurpleCertificate *crt);
 532
 533 /**
 534  * Get a unique identifier for the certificate
 535  *
 536  * @param crt        Certificate instance
 537  * @return String representing the certificate uniquely. Must be g_free()'ed
 538  */
 539 gchar *
 540 purple_certificate_get_unique_id(PurpleCertificate *crt);
 541
 542 /**
 543  * Get a unique identifier for the certificate's issuer
 544  *
 545  * @param crt        Certificate instance
 546  * @return String representing the certificate's issuer uniquely. Must be
 547  *         g_free()'ed
 548  */
 549 gchar *
 550 purple_certificate_get_issuer_unique_id(PurpleCertificate *crt);
 551
 552 /**
 553  * Gets the certificate subject's name
 554  *
 555  * For X.509, this is the "Common Name" field, as we're only using it
 556  * for hostname verification at the moment
 557  *
 558  * @param crt   Certificate instance
 559  * @return Newly allocated string with the certificate subject.
 560  */
 561 gchar *
 562 purple_certificate_get_subject_name(PurpleCertificate *crt);
 563
 564 /**
 565  * Check the subject name against that on the certificate
 566  * @param crt   Certificate instance
 567  * @param name  Name to check.
 568  * @return TRUE if it is a match, else FALSE
 569  */
 570 gboolean
 571 purple_certificate_check_subject_name(PurpleCertificate *crt, const gchar *name);
 572
 573 /**
 574  * Get the expiration/activation times.
 575  *
 576  * @param crt          Certificate instance
 577  * @param activation   Reference to store the activation time at. May be NULL
 578  *                     if you don't actually want it.
 579  * @param expiration   Reference to store the expiration time at. May be NULL
 580  *                     if you don't actually want it.
 581  * @return TRUE if the requested values were obtained, otherwise FALSE.
 582  */
 583 gboolean
 584 purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration);
 585
 586 /*@}*/
 587
 588 /*****************************************************************************/
 589 /** @name Certificate Pool Functions                                         */
 590 /*****************************************************************************/
 591 /*@{*/
 592 /**
 593  * Helper function for generating file paths in ~/.purple/certificates for
 594  * CertificatePools that use them.
 595  *
 596  * All components will be escaped for filesystem friendliness.
 597  *
 598  * @param pool   CertificatePool to build a path for
 599  * @param id     Key to look up a Certificate by. May be NULL.
 600  * @return A newly allocated path of the form
 601  *         ~/.purple/certificates/scheme_name/pool_name/unique_id
 602  */
 603 gchar *
 604 purple_certificate_pool_mkpath(PurpleCertificatePool *pool, const gchar *id);
 605
 606 /**
 607  * Determines whether a pool can be used.
 608  *
 609  * Checks whether the associated CertificateScheme is loaded.
 610  *
 611  * @param pool   Pool to check
 612  *
 613  * @return TRUE if the pool can be used, otherwise FALSE
 614  */
 615 gboolean
 616 purple_certificate_pool_usable(PurpleCertificatePool *pool);
 617
 618 /**
 619  * Looks up the scheme the pool operates under
 620  *
 621  * @param pool   Pool to get the scheme of
 622  *
 623  * @return Pointer to the pool's scheme, or NULL if it isn't loaded.
 624  * @see purple_certificate_pool_usable()
 625  */
 626 PurpleCertificateScheme *
 627 purple_certificate_pool_get_scheme(PurpleCertificatePool *pool);
 628
 629 /**
 630  * Check for presence of an ID in a pool.
 631  * @param pool   Pool to look in
 632  * @param id     ID to look for
 633  * @return TRUE if the ID is in the pool, else FALSE
 634  */
 635 gboolean
 636 purple_certificate_pool_contains(PurpleCertificatePool *pool, const gchar *id);
 637
 638 /**
 639  * Retrieve a certificate from a pool.
 640  * @param pool   Pool to fish in
 641  * @param id     ID to look up
 642  * @return Retrieved certificate, or NULL if it wasn't there
 643  */
 644 PurpleCertificate *
 645 purple_certificate_pool_retrieve(PurpleCertificatePool *pool, const gchar *id);
 646
 647 /**
 648  * Add a certificate to a pool
 649  *
 650  * Any pre-existing certificate of the same ID will be overwritten.
 651  *
 652  * @param pool   Pool to add to
 653  * @param id     ID to store the certificate with
 654  * @param crt    Certificate to store
 655  * @return TRUE if the operation succeeded, otherwise FALSE
 656  */
 657 gboolean
 658 purple_certificate_pool_store(PurpleCertificatePool *pool, const gchar *id, PurpleCertificate *crt);
 659
 660 /**
 661  * Remove a certificate from a pool
 662  *
 663  * @param pool   Pool to remove from
 664  * @param id     ID to remove
 665  * @return TRUE if the operation succeeded, otherwise FALSE
 666  */
 667 gboolean
 668 purple_certificate_pool_delete(PurpleCertificatePool *pool, const gchar *id);
 669
 670 /**
 671  * Get the list of IDs currently in the pool.
 672  *
 673  * @param pool   Pool to enumerate
 674  * @return GList pointing to newly-allocated id strings. Free using
 675  *         purple_certificate_pool_destroy_idlist()
 676  */
 677 GList *
 678 purple_certificate_pool_get_idlist(PurpleCertificatePool *pool);
 679
 680 /**
 681  * Destroys the result given by purple_certificate_pool_get_idlist()
 682  *
 683  * @param idlist ID List to destroy
 684  */
 685 void
 686 purple_certificate_pool_destroy_idlist(GList *idlist);
 687
 688 /*@}*/
 689
 690 /*****************************************************************************/
 691 /** @name Certificate Subsystem API                                          */
 692 /*****************************************************************************/
 693 /*@{*/
 694
 695 /**
 696  * Initialize the certificate system
 697  */
 698 void
 699 purple_certificate_init(void);
 700
 701 /**
 702  * Un-initialize the certificate system
 703  */
 704 void
 705 purple_certificate_uninit(void);
 706
 707 /**
 708  * Get the Certificate subsystem handle for signalling purposes
 709  */
 710 gpointer
 711 purple_certificate_get_handle(void);
 712
 713 /** Look up a registered CertificateScheme by name
 714  * @param name   The scheme name. Case insensitive.
 715  * @return Pointer to the located Scheme, or NULL if it isn't found.
 716  */
 717 PurpleCertificateScheme *
 718 purple_certificate_find_scheme(const gchar *name);
 719
 720 /**
 721  * Get all registered CertificateSchemes
 722  *
 723  * @return GList pointing to all registered CertificateSchemes . This value
 724  *         is owned by libpurple
 725  */
 726 GList *
 727 purple_certificate_get_schemes(void);
 728
 729 /** Register a CertificateScheme with libpurple
 730  *
 731  * No two schemes can be registered with the same name; this function enforces
 732  * that.
 733  *
 734  * @param scheme  Pointer to the scheme to register.
 735  * @return TRUE if the scheme was successfully added, otherwise FALSE
 736  */
 737 gboolean
 738 purple_certificate_register_scheme(PurpleCertificateScheme *scheme);
 739
 740 /** Unregister a CertificateScheme from libpurple
 741  *
 742  * @param scheme    Scheme to unregister.
 743  *                  If the scheme is not registered, this is a no-op.
 744  *
 745  * @return TRUE if the unregister completed successfully
 746  */
 747 gboolean
 748 purple_certificate_unregister_scheme(PurpleCertificateScheme *scheme);
 749
 750 /** Look up a registered PurpleCertificateVerifier by scheme and name
 751  * @param scheme_name  Scheme name. Case insensitive.
 752  * @param ver_name     The verifier name. Case insensitive.
 753  * @return Pointer to the located Verifier, or NULL if it isn't found.
 754  */
 755 PurpleCertificateVerifier *
 756 purple_certificate_find_verifier(const gchar *scheme_name, const gchar *ver_name);
 757
 758 /**
 759  * Get the list of registered CertificateVerifiers
 760  *
 761  * @return GList of all registered PurpleCertificateVerifier. This value
 762  *         is owned by libpurple
 763  */
 764 GList *
 765 purple_certificate_get_verifiers(void);
 766
 767 /**
 768  * Register a CertificateVerifier with libpurple
 769  *
 770  * @param vr     Verifier to register.
 771  * @return TRUE if register succeeded, otherwise FALSE
 772  */
 773 gboolean
 774 purple_certificate_register_verifier(PurpleCertificateVerifier *vr);
 775
 776 /**
 777  * Unregister a CertificateVerifier with libpurple
 778  *
 779  * @param vr     Verifier to unregister.
 780  * @return TRUE if unregister succeeded, otherwise FALSE
 781  */
 782 gboolean
 783 purple_certificate_unregister_verifier(PurpleCertificateVerifier *vr);
 784
 785 /** Look up a registered PurpleCertificatePool by scheme and name
 786  * @param scheme_name  Scheme name. Case insensitive.
 787  * @param pool_name    Pool name. Case insensitive.
 788  * @return Pointer to the located Pool, or NULL if it isn't found.
 789  */
 790 PurpleCertificatePool *
 791 purple_certificate_find_pool(const gchar *scheme_name, const gchar *pool_name);
 792
 793 /**
 794  * Get the list of registered Pools
 795  *
 796  * @return GList of all registered PurpleCertificatePool s. This value
 797  *         is owned by libpurple
 798  */
 799 GList *
 800 purple_certificate_get_pools(void);
 801
 802 /**
 803  * Register a CertificatePool with libpurple and call its init function
 804  *
 805  * @param pool   Pool to register.
 806  * @return TRUE if the register succeeded, otherwise FALSE
 807  */
 808 gboolean
 809 purple_certificate_register_pool(PurpleCertificatePool *pool);
 810
 811 /**
 812  * Unregister a CertificatePool with libpurple and call its uninit function
 813  *
 814  * @param pool   Pool to unregister.
 815  * @return TRUE if the unregister succeeded, otherwise FALSE
 816  */
 817 gboolean
 818 purple_certificate_unregister_pool(PurpleCertificatePool *pool);
 819
 820 /*@}*/
 821
 822
 823 /**
 824  * Displays a window showing X.509 certificate information
 825  *
 826  * @param crt    Certificate under an "x509" Scheme
 827  * @todo Will break on CA certs, as they have no Common Name
 828  */
 829 void
 830 purple_certificate_display_x509(PurpleCertificate *crt);
 831
 832 /**
 833  * Add a search path for certificates.
 834  *
 835  * @param path   Path to search for certificates.
 836  */
 837 void purple_certificate_add_ca_search_path(const char *path);
 838
 839 #ifdef __cplusplus
 840 }
 841 #endif /* __cplusplus */
 842
 843 #endif /* _PURPLE_CERTIFICATE_H */