1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/certificate.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,826 @@
1.4 +/**
1.5 + * @file certificate.h Public-Key Certificate API
1.6 + * @ingroup core
1.7 + * @see @ref certificate-signals
1.8 + * @since 2.2.0
1.9 + */
1.10 +
1.11 +/*
1.12 + *
1.13 + * purple
1.14 + *
1.15 + * Purple is the legal property of its developers, whose names are too numerous
1.16 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.17 + * source distribution.
1.18 + *
1.19 + * This program is free software; you can redistribute it and/or modify
1.20 + * it under the terms of the GNU General Public License as published by
1.21 + * the Free Software Foundation; either version 2 of the License, or
1.22 + * (at your option) any later version.
1.23 + *
1.24 + * This program is distributed in the hope that it will be useful,
1.25 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.26 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.27 + * GNU General Public License for more details.
1.28 + *
1.29 + * You should have received a copy of the GNU General Public License
1.30 + * along with this program; if not, write to the Free Software
1.31 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.32 + */
1.33 +
1.34 +#ifndef _PURPLE_CERTIFICATE_H
1.35 +#define _PURPLE_CERTIFICATE_H
1.36 +
1.37 +#include <time.h>
1.38 +
1.39 +#include <glib.h>
1.40 +
1.41 +#ifdef __cplusplus
1.42 +extern "C" {
1.43 +#endif /* __cplusplus */
1.44 +
1.45 +
1.46 +typedef enum
1.47 +{
1.48 + PURPLE_CERTIFICATE_INVALID = 0,
1.49 + PURPLE_CERTIFICATE_VALID = 1
1.50 +} PurpleCertificateVerificationStatus;
1.51 +
1.52 +typedef struct _PurpleCertificate PurpleCertificate;
1.53 +typedef struct _PurpleCertificatePool PurpleCertificatePool;
1.54 +typedef struct _PurpleCertificateScheme PurpleCertificateScheme;
1.55 +typedef struct _PurpleCertificateVerifier PurpleCertificateVerifier;
1.56 +typedef struct _PurpleCertificateVerificationRequest PurpleCertificateVerificationRequest;
1.57 +
1.58 +/**
1.59 + * Callback function for the results of a verification check
1.60 + * @param st Status code
1.61 + * @param userdata User-defined data
1.62 + */
1.63 +typedef void (*PurpleCertificateVerifiedCallback)
1.64 + (PurpleCertificateVerificationStatus st,
1.65 + gpointer userdata);
1.66 +
1.67 +/** A certificate instance
1.68 + *
1.69 + * An opaque data structure representing a single certificate under some
1.70 + * CertificateScheme
1.71 + */
1.72 +struct _PurpleCertificate
1.73 +{
1.74 + /** Scheme this certificate is under */
1.75 + PurpleCertificateScheme * scheme;
1.76 + /** Opaque pointer to internal data */
1.77 + gpointer data;
1.78 +};
1.79 +
1.80 +/**
1.81 + * Database for retrieval or storage of Certificates
1.82 + *
1.83 + * More or less a hash table; all lookups and writes are controlled by a string
1.84 + * key.
1.85 + */
1.86 +struct _PurpleCertificatePool
1.87 +{
1.88 + /** Scheme this Pool operates for */
1.89 + gchar *scheme_name;
1.90 + /** Internal name to refer to the pool by */
1.91 + gchar *name;
1.92 +
1.93 + /** User-friendly name for this type
1.94 + * ex: N_("SSL Servers")
1.95 + * When this is displayed anywhere, it should be i18ned
1.96 + * ex: _(pool->fullname)
1.97 + */
1.98 + gchar *fullname;
1.99 +
1.100 + /** Internal pool data */
1.101 + gpointer data;
1.102 +
1.103 + /**
1.104 + * Set up the Pool's internal state
1.105 + *
1.106 + * Upon calling purple_certificate_register_pool() , this function will
1.107 + * be called. May be NULL.
1.108 + * @return TRUE if the initialization succeeded, otherwise FALSE
1.109 + */
1.110 + gboolean (* init)(void);
1.111 +
1.112 + /**
1.113 + * Uninit the Pool's internal state
1.114 + *
1.115 + * Will be called by purple_certificate_unregister_pool() . May be NULL
1.116 + */
1.117 + void (* uninit)(void);
1.118 +
1.119 + /** Check for presence of a certificate in the pool using unique ID */
1.120 + gboolean (* cert_in_pool)(const gchar *id);
1.121 + /** Retrieve a PurpleCertificate from the pool */
1.122 + PurpleCertificate * (* get_cert)(const gchar *id);
1.123 + /** Add a certificate to the pool. Must overwrite any other
1.124 + * certificates sharing the same ID in the pool.
1.125 + * @return TRUE if the operation succeeded, otherwise FALSE
1.126 + */
1.127 + gboolean (* put_cert)(const gchar *id, PurpleCertificate *crt);
1.128 + /** Delete a certificate from the pool */
1.129 + gboolean (* delete_cert)(const gchar *id);
1.130 +
1.131 + /** Returns a list of IDs stored in the pool */
1.132 + GList * (* get_idlist)(void);
1.133 +
1.134 + void (*_purple_reserved1)(void);
1.135 + void (*_purple_reserved2)(void);
1.136 + void (*_purple_reserved3)(void);
1.137 + void (*_purple_reserved4)(void);
1.138 +};
1.139 +
1.140 +/** A certificate type
1.141 + *
1.142 + * A CertificateScheme must implement all of the fields in the structure,
1.143 + * and register it using purple_certificate_register_scheme()
1.144 + *
1.145 + * There may be only ONE CertificateScheme provided for each certificate
1.146 + * type, as specified by the "name" field.
1.147 + */
1.148 +struct _PurpleCertificateScheme
1.149 +{
1.150 + /** Name of the certificate type
1.151 + * ex: "x509", "pgp", etc.
1.152 + * This must be globally unique - you may not register more than one
1.153 + * CertificateScheme of the same name at a time.
1.154 + */
1.155 + gchar * name;
1.156 +
1.157 + /** User-friendly name for this type
1.158 + * ex: N_("X.509 Certificates")
1.159 + * When this is displayed anywhere, it should be i18ned
1.160 + * ex: _(scheme->fullname)
1.161 + */
1.162 + gchar * fullname;
1.163 +
1.164 + /** Imports a certificate from a file
1.165 + *
1.166 + * @param filename File to import the certificate from
1.167 + * @return Pointer to the newly allocated Certificate struct
1.168 + * or NULL on failure.
1.169 + */
1.170 + PurpleCertificate * (* import_certificate)(const gchar * filename);
1.171 +
1.172 + /**
1.173 + * Exports a certificate to a file
1.174 + *
1.175 + * @param filename File to export the certificate to
1.176 + * @param crt Certificate to export
1.177 + * @return TRUE if the export succeeded, otherwise FALSE
1.178 + * @see purple_certificate_export()
1.179 + */
1.180 + gboolean (* export_certificate)(const gchar *filename, PurpleCertificate *crt);
1.181 +
1.182 + /**
1.183 + * Duplicates a certificate
1.184 + *
1.185 + * Certificates are generally assumed to be read-only, so feel free to
1.186 + * do any sort of reference-counting magic you want here. If this ever
1.187 + * changes, please remember to change the magic accordingly.
1.188 + * @return Reference to the new copy
1.189 + */
1.190 + PurpleCertificate * (* copy_certificate)(PurpleCertificate *crt);
1.191 +
1.192 + /** Destroys and frees a Certificate structure
1.193 + *
1.194 + * Destroys a Certificate's internal data structures and calls
1.195 + * free(crt)
1.196 + *
1.197 + * @param crt Certificate instance to be destroyed. It WILL NOT be
1.198 + * destroyed if it is not of the correct
1.199 + * CertificateScheme. Can be NULL
1.200 + */
1.201 + void (* destroy_certificate)(PurpleCertificate * crt);
1.202 +
1.203 + /** Find whether "crt" has a valid signature from issuer "issuer"
1.204 + * @see purple_certificate_signed_by() */
1.205 + gboolean (*signed_by)(PurpleCertificate *crt, PurpleCertificate *issuer);
1.206 + /**
1.207 + * Retrieves the certificate public key fingerprint using SHA1
1.208 + *
1.209 + * @param crt Certificate instance
1.210 + * @return Binary representation of SHA1 hash - must be freed using
1.211 + * g_byte_array_free()
1.212 + */
1.213 + GByteArray * (* get_fingerprint_sha1)(PurpleCertificate *crt);
1.214 +
1.215 + /**
1.216 + * Retrieves a unique certificate identifier
1.217 + *
1.218 + * @param crt Certificate instance
1.219 + * @return Newly allocated string that can be used to uniquely
1.220 + * identify the certificate.
1.221 + */
1.222 + gchar * (* get_unique_id)(PurpleCertificate *crt);
1.223 +
1.224 + /**
1.225 + * Retrieves a unique identifier for the certificate's issuer
1.226 + *
1.227 + * @param crt Certificate instance
1.228 + * @return Newly allocated string that can be used to uniquely
1.229 + * identify the issuer's certificate.
1.230 + */
1.231 + gchar * (* get_issuer_unique_id)(PurpleCertificate *crt);
1.232 +
1.233 + /**
1.234 + * Gets the certificate subject's name
1.235 + *
1.236 + * For X.509, this is the "Common Name" field, as we're only using it
1.237 + * for hostname verification at the moment
1.238 + *
1.239 + * @see purple_certificate_get_subject_name()
1.240 + *
1.241 + * @param crt Certificate instance
1.242 + * @return Newly allocated string with the certificate subject.
1.243 + */
1.244 + gchar * (* get_subject_name)(PurpleCertificate *crt);
1.245 +
1.246 + /**
1.247 + * Check the subject name against that on the certificate
1.248 + * @see purple_certificate_check_subject_name()
1.249 + * @return TRUE if it is a match, else FALSE
1.250 + */
1.251 + gboolean (* check_subject_name)(PurpleCertificate *crt, const gchar *name);
1.252 +
1.253 + /** Retrieve the certificate activation/expiration times */
1.254 + gboolean (* get_times)(PurpleCertificate *crt, time_t *activation, time_t *expiration);
1.255 +
1.256 + void (*_purple_reserved1)(void);
1.257 + void (*_purple_reserved2)(void);
1.258 + void (*_purple_reserved3)(void);
1.259 + void (*_purple_reserved4)(void);
1.260 +};
1.261 +
1.262 +/** A set of operations used to provide logic for verifying a Certificate's
1.263 + * authenticity.
1.264 + *
1.265 + * A Verifier provider must fill out these fields, then register it using
1.266 + * purple_certificate_register_verifier()
1.267 + *
1.268 + * The (scheme_name, name) value must be unique for each Verifier - you may not
1.269 + * register more than one Verifier of the same name for each Scheme
1.270 + */
1.271 +struct _PurpleCertificateVerifier
1.272 +{
1.273 + /** Name of the scheme this Verifier operates on
1.274 + *
1.275 + * The scheme will be looked up by name when a Request is generated
1.276 + * using this Verifier
1.277 + */
1.278 + gchar *scheme_name;
1.279 +
1.280 + /** Name of the Verifier - case insensitive */
1.281 + gchar *name;
1.282 +
1.283 + /**
1.284 + * Start the verification process
1.285 + *
1.286 + * To be called from purple_certificate_verify once it has
1.287 + * constructed the request. This will use the information in the
1.288 + * given VerificationRequest to check the certificate and callback
1.289 + * the requester with the verification results.
1.290 + *
1.291 + * @param vrq Request to process
1.292 + */
1.293 + void (* start_verification)(PurpleCertificateVerificationRequest *vrq);
1.294 +
1.295 + /**
1.296 + * Destroy a completed Request under this Verifier
1.297 + * The function pointed to here is only responsible for cleaning up
1.298 + * whatever PurpleCertificateVerificationRequest::data points to.
1.299 + * It should not call free(vrq)
1.300 + *
1.301 + * @param vrq Request to destroy
1.302 + */
1.303 + void (* destroy_request)(PurpleCertificateVerificationRequest *vrq);
1.304 +
1.305 + void (*_purple_reserved1)(void);
1.306 + void (*_purple_reserved2)(void);
1.307 + void (*_purple_reserved3)(void);
1.308 + void (*_purple_reserved4)(void);
1.309 +};
1.310 +
1.311 +/** Structure for a single certificate request
1.312 + *
1.313 + * Useful for keeping track of the state of a verification that involves
1.314 + * several steps
1.315 + */
1.316 +struct _PurpleCertificateVerificationRequest
1.317 +{
1.318 + /** Reference to the verification logic used */
1.319 + PurpleCertificateVerifier *verifier;
1.320 + /** Reference to the scheme used.
1.321 + *
1.322 + * This is looked up from the Verifier when the Request is generated
1.323 + */
1.324 + PurpleCertificateScheme *scheme;
1.325 +
1.326 + /**
1.327 + * Name to check that the certificate is issued to
1.328 + *
1.329 + * For X.509 certificates, this is the Common Name
1.330 + */
1.331 + gchar *subject_name;
1.332 +
1.333 + /** List of certificates in the chain to be verified (such as that returned by purple_ssl_get_peer_certificates )
1.334 + *
1.335 + * This is most relevant for X.509 certificates used in SSL sessions.
1.336 + * The list order should be: certificate, issuer, issuer's issuer, etc.
1.337 + */
1.338 + GList *cert_chain;
1.339 +
1.340 + /** Internal data used by the Verifier code */
1.341 + gpointer data;
1.342 +
1.343 + /** Function to call with the verification result */
1.344 + PurpleCertificateVerifiedCallback cb;
1.345 + /** Data to pass to the post-verification callback */
1.346 + gpointer cb_data;
1.347 +};
1.348 +
1.349 +/*****************************************************************************/
1.350 +/** @name Certificate Verification Functions */
1.351 +/*****************************************************************************/
1.352 +/*@{*/
1.353 +
1.354 +/**
1.355 + * Constructs a verification request and passed control to the specified Verifier
1.356 + *
1.357 + * It is possible that the callback will be called immediately upon calling
1.358 + * this function. Plan accordingly.
1.359 + *
1.360 + * @param verifier Verification logic to use.
1.361 + * @see purple_certificate_find_verifier()
1.362 + *
1.363 + * @param subject_name Name that should match the first certificate in the
1.364 + * chain for the certificate to be valid. Will be strdup'd
1.365 + * into the Request struct
1.366 + *
1.367 + * @param cert_chain Certificate chain to check. If there is more than one
1.368 + * certificate in the chain (X.509), the peer's
1.369 + * certificate comes first, then the issuer/signer's
1.370 + * certificate, etc. The whole list is duplicated into the
1.371 + * Request struct.
1.372 + *
1.373 + * @param cb Callback function to be called with whether the
1.374 + * certificate was approved or not.
1.375 + * @param cb_data User-defined data for the above.
1.376 + */
1.377 +void
1.378 +purple_certificate_verify (PurpleCertificateVerifier *verifier,
1.379 + const gchar *subject_name, GList *cert_chain,
1.380 + PurpleCertificateVerifiedCallback cb,
1.381 + gpointer cb_data);
1.382 +
1.383 +/**
1.384 + * Completes and destroys a VerificationRequest
1.385 + *
1.386 + * @param vrq Request to conclude
1.387 + * @param st Success/failure code to pass to the request's
1.388 + * completion callback.
1.389 + */
1.390 +void
1.391 +purple_certificate_verify_complete(PurpleCertificateVerificationRequest *vrq,
1.392 + PurpleCertificateVerificationStatus st);
1.393 +
1.394 +/*@}*/
1.395 +
1.396 +/*****************************************************************************/
1.397 +/** @name Certificate Functions */
1.398 +/*****************************************************************************/
1.399 +/*@{*/
1.400 +
1.401 +/**
1.402 + * Makes a duplicate of a certificate
1.403 + *
1.404 + * @param crt Instance to duplicate
1.405 + * @return Pointer to new instance
1.406 + */
1.407 +PurpleCertificate *
1.408 +purple_certificate_copy(PurpleCertificate *crt);
1.409 +
1.410 +/**
1.411 + * Duplicates an entire list of certificates
1.412 + *
1.413 + * @param crt_list List to duplicate
1.414 + * @return New list copy
1.415 + */
1.416 +GList *
1.417 +purple_certificate_copy_list(GList *crt_list);
1.418 +
1.419 +/**
1.420 + * Destroys and free()'s a Certificate
1.421 + *
1.422 + * @param crt Instance to destroy. May be NULL.
1.423 + */
1.424 +void
1.425 +purple_certificate_destroy (PurpleCertificate *crt);
1.426 +
1.427 +/**
1.428 + * Destroy an entire list of Certificate instances and the containing list
1.429 + *
1.430 + * @param crt_list List of certificates to destroy. May be NULL.
1.431 + */
1.432 +void
1.433 +purple_certificate_destroy_list (GList * crt_list);
1.434 +
1.435 +/**
1.436 + * Check whether 'crt' has a valid signature made by 'issuer'
1.437 + *
1.438 + * @param crt Certificate instance to check signature of
1.439 + * @param issuer Certificate thought to have signed 'crt'
1.440 + *
1.441 + * @return TRUE if 'crt' has a valid signature made by 'issuer',
1.442 + * otherwise FALSE
1.443 + * @todo Find a way to give the reason (bad signature, not the issuer, etc.)
1.444 + */
1.445 +gboolean
1.446 +purple_certificate_signed_by(PurpleCertificate *crt, PurpleCertificate *issuer);
1.447 +
1.448 +/**
1.449 + * Check that a certificate chain is valid and, if not, the failing certificate.
1.450 + *
1.451 + * Uses purple_certificate_signed_by() to verify that each PurpleCertificate
1.452 + * in the chain carries a valid signature from the next. A single-certificate
1.453 + * chain is considered to be valid.
1.454 + *
1.455 + * @param chain List of PurpleCertificate instances comprising the chain,
1.456 + * in the order certificate, issuer, issuer's issuer, etc.
1.457 + * @param failing A pointer to a PurpleCertificate*. If not NULL, if the
1.458 + * chain fails to validate, this will be set to the
1.459 + * certificate whose signature could not be validated.
1.460 + * @return TRUE if the chain is valid. See description.
1.461 + *
1.462 + * @since 2.6.0
1.463 + * @deprecated This function will become
1.464 + * purple_certificate_check_signature_chain in 3.0.0
1.465 + */
1.466 +gboolean
1.467 +purple_certificate_check_signature_chain_with_failing(GList *chain,
1.468 + PurpleCertificate **failing);
1.469 +
1.470 +/**
1.471 + * Check that a certificate chain is valid
1.472 + *
1.473 + * Uses purple_certificate_signed_by() to verify that each PurpleCertificate
1.474 + * in the chain carries a valid signature from the next. A single-certificate
1.475 + * chain is considered to be valid.
1.476 + *
1.477 + * @param chain List of PurpleCertificate instances comprising the chain,
1.478 + * in the order certificate, issuer, issuer's issuer, etc.
1.479 + * @return TRUE if the chain is valid. See description.
1.480 + * @todo Specify which certificate in the chain caused a failure
1.481 + * @deprecated This function will be removed in 3.0.0 and replaced with
1.482 + * purple_certificate_check_signature_chain_with_failing
1.483 + */
1.484 +gboolean
1.485 +purple_certificate_check_signature_chain(GList *chain);
1.486 +
1.487 +/**
1.488 + * Imports a PurpleCertificate from a file
1.489 + *
1.490 + * @param scheme Scheme to import under
1.491 + * @param filename File path to import from
1.492 + * @return Pointer to a new PurpleCertificate, or NULL on failure
1.493 + */
1.494 +PurpleCertificate *
1.495 +purple_certificate_import(PurpleCertificateScheme *scheme, const gchar *filename);
1.496 +
1.497 +/**
1.498 + * Exports a PurpleCertificate to a file
1.499 + *
1.500 + * @param filename File to export the certificate to
1.501 + * @param crt Certificate to export
1.502 + * @return TRUE if the export succeeded, otherwise FALSE
1.503 + */
1.504 +gboolean
1.505 +purple_certificate_export(const gchar *filename, PurpleCertificate *crt);
1.506 +
1.507 +
1.508 +/**
1.509 + * Retrieves the certificate public key fingerprint using SHA1.
1.510 + *
1.511 + * @param crt Certificate instance
1.512 + * @return Binary representation of the hash. You are responsible for free()ing
1.513 + * this.
1.514 + * @see purple_base16_encode_chunked()
1.515 + */
1.516 +GByteArray *
1.517 +purple_certificate_get_fingerprint_sha1(PurpleCertificate *crt);
1.518 +
1.519 +/**
1.520 + * Get a unique identifier for the certificate
1.521 + *
1.522 + * @param crt Certificate instance
1.523 + * @return String representing the certificate uniquely. Must be g_free()'ed
1.524 + */
1.525 +gchar *
1.526 +purple_certificate_get_unique_id(PurpleCertificate *crt);
1.527 +
1.528 +/**
1.529 + * Get a unique identifier for the certificate's issuer
1.530 + *
1.531 + * @param crt Certificate instance
1.532 + * @return String representing the certificate's issuer uniquely. Must be
1.533 + * g_free()'ed
1.534 + */
1.535 +gchar *
1.536 +purple_certificate_get_issuer_unique_id(PurpleCertificate *crt);
1.537 +
1.538 +/**
1.539 + * Gets the certificate subject's name
1.540 + *
1.541 + * For X.509, this is the "Common Name" field, as we're only using it
1.542 + * for hostname verification at the moment
1.543 + *
1.544 + * @param crt Certificate instance
1.545 + * @return Newly allocated string with the certificate subject.
1.546 + */
1.547 +gchar *
1.548 +purple_certificate_get_subject_name(PurpleCertificate *crt);
1.549 +
1.550 +/**
1.551 + * Check the subject name against that on the certificate
1.552 + * @param crt Certificate instance
1.553 + * @param name Name to check.
1.554 + * @return TRUE if it is a match, else FALSE
1.555 + */
1.556 +gboolean
1.557 +purple_certificate_check_subject_name(PurpleCertificate *crt, const gchar *name);
1.558 +
1.559 +/**
1.560 + * Get the expiration/activation times.
1.561 + *
1.562 + * @param crt Certificate instance
1.563 + * @param activation Reference to store the activation time at. May be NULL
1.564 + * if you don't actually want it.
1.565 + * @param expiration Reference to store the expiration time at. May be NULL
1.566 + * if you don't actually want it.
1.567 + * @return TRUE if the requested values were obtained, otherwise FALSE.
1.568 + */
1.569 +gboolean
1.570 +purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration);
1.571 +
1.572 +/*@}*/
1.573 +
1.574 +/*****************************************************************************/
1.575 +/** @name Certificate Pool Functions */
1.576 +/*****************************************************************************/
1.577 +/*@{*/
1.578 +/**
1.579 + * Helper function for generating file paths in ~/.purple/certificates for
1.580 + * CertificatePools that use them.
1.581 + *
1.582 + * All components will be escaped for filesystem friendliness.
1.583 + *
1.584 + * @param pool CertificatePool to build a path for
1.585 + * @param id Key to look up a Certificate by. May be NULL.
1.586 + * @return A newly allocated path of the form
1.587 + * ~/.purple/certificates/scheme_name/pool_name/unique_id
1.588 + */
1.589 +gchar *
1.590 +purple_certificate_pool_mkpath(PurpleCertificatePool *pool, const gchar *id);
1.591 +
1.592 +/**
1.593 + * Determines whether a pool can be used.
1.594 + *
1.595 + * Checks whether the associated CertificateScheme is loaded.
1.596 + *
1.597 + * @param pool Pool to check
1.598 + *
1.599 + * @return TRUE if the pool can be used, otherwise FALSE
1.600 + */
1.601 +gboolean
1.602 +purple_certificate_pool_usable(PurpleCertificatePool *pool);
1.603 +
1.604 +/**
1.605 + * Looks up the scheme the pool operates under
1.606 + *
1.607 + * @param pool Pool to get the scheme of
1.608 + *
1.609 + * @return Pointer to the pool's scheme, or NULL if it isn't loaded.
1.610 + * @see purple_certificate_pool_usable()
1.611 + */
1.612 +PurpleCertificateScheme *
1.613 +purple_certificate_pool_get_scheme(PurpleCertificatePool *pool);
1.614 +
1.615 +/**
1.616 + * Check for presence of an ID in a pool.
1.617 + * @param pool Pool to look in
1.618 + * @param id ID to look for
1.619 + * @return TRUE if the ID is in the pool, else FALSE
1.620 + */
1.621 +gboolean
1.622 +purple_certificate_pool_contains(PurpleCertificatePool *pool, const gchar *id);
1.623 +
1.624 +/**
1.625 + * Retrieve a certificate from a pool.
1.626 + * @param pool Pool to fish in
1.627 + * @param id ID to look up
1.628 + * @return Retrieved certificate, or NULL if it wasn't there
1.629 + */
1.630 +PurpleCertificate *
1.631 +purple_certificate_pool_retrieve(PurpleCertificatePool *pool, const gchar *id);
1.632 +
1.633 +/**
1.634 + * Add a certificate to a pool
1.635 + *
1.636 + * Any pre-existing certificate of the same ID will be overwritten.
1.637 + *
1.638 + * @param pool Pool to add to
1.639 + * @param id ID to store the certificate with
1.640 + * @param crt Certificate to store
1.641 + * @return TRUE if the operation succeeded, otherwise FALSE
1.642 + */
1.643 +gboolean
1.644 +purple_certificate_pool_store(PurpleCertificatePool *pool, const gchar *id, PurpleCertificate *crt);
1.645 +
1.646 +/**
1.647 + * Remove a certificate from a pool
1.648 + *
1.649 + * @param pool Pool to remove from
1.650 + * @param id ID to remove
1.651 + * @return TRUE if the operation succeeded, otherwise FALSE
1.652 + */
1.653 +gboolean
1.654 +purple_certificate_pool_delete(PurpleCertificatePool *pool, const gchar *id);
1.655 +
1.656 +/**
1.657 + * Get the list of IDs currently in the pool.
1.658 + *
1.659 + * @param pool Pool to enumerate
1.660 + * @return GList pointing to newly-allocated id strings. Free using
1.661 + * purple_certificate_pool_destroy_idlist()
1.662 + */
1.663 +GList *
1.664 +purple_certificate_pool_get_idlist(PurpleCertificatePool *pool);
1.665 +
1.666 +/**
1.667 + * Destroys the result given by purple_certificate_pool_get_idlist()
1.668 + *
1.669 + * @param idlist ID List to destroy
1.670 + */
1.671 +void
1.672 +purple_certificate_pool_destroy_idlist(GList *idlist);
1.673 +
1.674 +/*@}*/
1.675 +
1.676 +/*****************************************************************************/
1.677 +/** @name Certificate Subsystem API */
1.678 +/*****************************************************************************/
1.679 +/*@{*/
1.680 +
1.681 +/**
1.682 + * Initialize the certificate system
1.683 + */
1.684 +void
1.685 +purple_certificate_init(void);
1.686 +
1.687 +/**
1.688 + * Un-initialize the certificate system
1.689 + */
1.690 +void
1.691 +purple_certificate_uninit(void);
1.692 +
1.693 +/**
1.694 + * Get the Certificate subsystem handle for signalling purposes
1.695 + */
1.696 +gpointer
1.697 +purple_certificate_get_handle(void);
1.698 +
1.699 +/** Look up a registered CertificateScheme by name
1.700 + * @param name The scheme name. Case insensitive.
1.701 + * @return Pointer to the located Scheme, or NULL if it isn't found.
1.702 + */
1.703 +PurpleCertificateScheme *
1.704 +purple_certificate_find_scheme(const gchar *name);
1.705 +
1.706 +/**
1.707 + * Get all registered CertificateSchemes
1.708 + *
1.709 + * @return GList pointing to all registered CertificateSchemes . This value
1.710 + * is owned by libpurple
1.711 + */
1.712 +GList *
1.713 +purple_certificate_get_schemes(void);
1.714 +
1.715 +/** Register a CertificateScheme with libpurple
1.716 + *
1.717 + * No two schemes can be registered with the same name; this function enforces
1.718 + * that.
1.719 + *
1.720 + * @param scheme Pointer to the scheme to register.
1.721 + * @return TRUE if the scheme was successfully added, otherwise FALSE
1.722 + */
1.723 +gboolean
1.724 +purple_certificate_register_scheme(PurpleCertificateScheme *scheme);
1.725 +
1.726 +/** Unregister a CertificateScheme from libpurple
1.727 + *
1.728 + * @param scheme Scheme to unregister.
1.729 + * If the scheme is not registered, this is a no-op.
1.730 + *
1.731 + * @return TRUE if the unregister completed successfully
1.732 + */
1.733 +gboolean
1.734 +purple_certificate_unregister_scheme(PurpleCertificateScheme *scheme);
1.735 +
1.736 +/** Look up a registered PurpleCertificateVerifier by scheme and name
1.737 + * @param scheme_name Scheme name. Case insensitive.
1.738 + * @param ver_name The verifier name. Case insensitive.
1.739 + * @return Pointer to the located Verifier, or NULL if it isn't found.
1.740 + */
1.741 +PurpleCertificateVerifier *
1.742 +purple_certificate_find_verifier(const gchar *scheme_name, const gchar *ver_name);
1.743 +
1.744 +/**
1.745 + * Get the list of registered CertificateVerifiers
1.746 + *
1.747 + * @return GList of all registered PurpleCertificateVerifier. This value
1.748 + * is owned by libpurple
1.749 + */
1.750 +GList *
1.751 +purple_certificate_get_verifiers(void);
1.752 +
1.753 +/**
1.754 + * Register a CertificateVerifier with libpurple
1.755 + *
1.756 + * @param vr Verifier to register.
1.757 + * @return TRUE if register succeeded, otherwise FALSE
1.758 + */
1.759 +gboolean
1.760 +purple_certificate_register_verifier(PurpleCertificateVerifier *vr);
1.761 +
1.762 +/**
1.763 + * Unregister a CertificateVerifier with libpurple
1.764 + *
1.765 + * @param vr Verifier to unregister.
1.766 + * @return TRUE if unregister succeeded, otherwise FALSE
1.767 + */
1.768 +gboolean
1.769 +purple_certificate_unregister_verifier(PurpleCertificateVerifier *vr);
1.770 +
1.771 +/** Look up a registered PurpleCertificatePool by scheme and name
1.772 + * @param scheme_name Scheme name. Case insensitive.
1.773 + * @param pool_name Pool name. Case insensitive.
1.774 + * @return Pointer to the located Pool, or NULL if it isn't found.
1.775 + */
1.776 +PurpleCertificatePool *
1.777 +purple_certificate_find_pool(const gchar *scheme_name, const gchar *pool_name);
1.778 +
1.779 +/**
1.780 + * Get the list of registered Pools
1.781 + *
1.782 + * @return GList of all registered PurpleCertificatePool s. This value
1.783 + * is owned by libpurple
1.784 + */
1.785 +GList *
1.786 +purple_certificate_get_pools(void);
1.787 +
1.788 +/**
1.789 + * Register a CertificatePool with libpurple and call its init function
1.790 + *
1.791 + * @param pool Pool to register.
1.792 + * @return TRUE if the register succeeded, otherwise FALSE
1.793 + */
1.794 +gboolean
1.795 +purple_certificate_register_pool(PurpleCertificatePool *pool);
1.796 +
1.797 +/**
1.798 + * Unregister a CertificatePool with libpurple and call its uninit function
1.799 + *
1.800 + * @param pool Pool to unregister.
1.801 + * @return TRUE if the unregister succeeded, otherwise FALSE
1.802 + */
1.803 +gboolean
1.804 +purple_certificate_unregister_pool(PurpleCertificatePool *pool);
1.805 +
1.806 +/*@}*/
1.807 +
1.808 +
1.809 +/**
1.810 + * Displays a window showing X.509 certificate information
1.811 + *
1.812 + * @param crt Certificate under an "x509" Scheme
1.813 + * @todo Will break on CA certs, as they have no Common Name
1.814 + */
1.815 +void
1.816 +purple_certificate_display_x509(PurpleCertificate *crt);
1.817 +
1.818 +/**
1.819 + * Add a search path for certificates.
1.820 + *
1.821 + * @param path Path to search for certificates.
1.822 + */
1.823 +void purple_certificate_add_ca_search_path(const char *path);
1.824 +
1.825 +#ifdef __cplusplus
1.826 +}
1.827 +#endif /* __cplusplus */
1.828 +
1.829 +#endif /* _PURPLE_CERTIFICATE_H */