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