pidgin/pidgin
Clone
Summary
Browse
Changes
Graph
Update network.c for the dns code removal
use-gresolver
2015-12-15, Gary Kramlich
703722d83214
Update network.c for the dns code removal
/*
*
* purple
*
* Purple is the legal property of its developers, whose names are too numerous
* to list here. Please refer to the COPYRIGHT file distributed with this
* source distribution.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*/
#ifndef _PURPLE_CERTIFICATE_H
#define _PURPLE_CERTIFICATE_H
/**
* SECTION:certificate
* @section_id: libpurple-certificate
* @short_description: <filename>certificate.h</filename>
* @title: Public-Key Certificate API
* @see_also: <link linkend="chapter-signals-certificate">Certificate signals</link>
*/
#include
<time.h>
#include
<glib.h>
/**
* PurpleCertificateVerificationStatus:
* @PURPLE_CERTIFICATE_UNKNOWN_ERROR: Unknown error.
* @PURPLE_CERTIFICATE_VALID: Not an error.
* @PURPLE_CERTIFICATE_NON_FATALS_MASK: Non-fatal.
* @PURPLE_CERTIFICATE_SELF_SIGNED: The certificate is self-signed.
* @PURPLE_CERTIFICATE_CA_UNKNOWN: The CA is not in libpurple's pool of
* certificates.
* @PURPLE_CERTIFICATE_NOT_ACTIVATED: The current time is before the
* certificate's specified activation time.
* @PURPLE_CERTIFICATE_EXPIRED: The current time is after the certificate's
* specified expiration time.
* @PURPLE_CERTIFICATE_NAME_MISMATCH: The certificate's subject name doesn't
* match the expected.
* @PURPLE_CERTIFICATE_NO_CA_POOL: No CA pool was found. This shouldn't happen.
* @PURPLE_CERTIFICATE_FATALS_MASK: Fatal
* @PURPLE_CERTIFICATE_INVALID_CHAIN: The signature chain could not be
* validated. Due to limitations in the the current API,
* this also indicates one of the CA certificates in the
* chain is expired (or not yet activated).
* @PURPLE_CERTIFICATE_REVOKED: The signature has been revoked.
* @PURPLE_CERTIFICATE_REJECTED: The certificate was rejected by the user.
*/
/* FIXME 3.0.0 PURPLE_CERTIFICATE_INVALID_CHAIN -- see description */
typedef
enum
{
PURPLE_CERTIFICATE_UNKNOWN_ERROR
=
-1
,
PURPLE_CERTIFICATE_VALID
=
0
,
/* Non-fatal */
PURPLE_CERTIFICATE_NON_FATALS_MASK
=
0x0000FFFF
,
/* The certificate is self-signed. */
PURPLE_CERTIFICATE_SELF_SIGNED
=
0x01
,
/* The CA is not in libpurple's pool of certificates. */
PURPLE_CERTIFICATE_CA_UNKNOWN
=
0x02
,
/* The current time is before the certificate's specified
* activation time.
*/
PURPLE_CERTIFICATE_NOT_ACTIVATED
=
0x04
,
/* The current time is after the certificate's specified expiration time */
PURPLE_CERTIFICATE_EXPIRED
=
0x08
,
/* The certificate's subject name doesn't match the expected */
PURPLE_CERTIFICATE_NAME_MISMATCH
=
0x10
,
/* No CA pool was found. This shouldn't happen... */
PURPLE_CERTIFICATE_NO_CA_POOL
=
0x20
,
/* Fatal */
PURPLE_CERTIFICATE_FATALS_MASK
=
0xFFFF0000
,
/* The signature chain could not be validated. Due to limitations in the
* the current API, this also indicates one of the CA certificates in the
* chain is expired (or not yet activated). FIXME 3.0.0 */
PURPLE_CERTIFICATE_INVALID_CHAIN
=
0x10000
,
/* The signature has been revoked. */
PURPLE_CERTIFICATE_REVOKED
=
0x20000
,
PURPLE_CERTIFICATE_REJECTED
=
0x40000
,
/*< private >*/
PURPLE_CERTIFICATE_LAST
=
0x80000
,
}
PurpleCertificateVerificationStatus
;
#define PURPLE_TYPE_CERTIFICATE (purple_certificate_get_type())
typedef
struct
_PurpleCertificate
PurpleCertificate
;
#define PURPLE_TYPE_CERTIFICATE_POOL (purple_certificate_pool_get_type())
typedef
struct
_PurpleCertificatePool
PurpleCertificatePool
;
typedef
struct
_PurpleCertificateScheme
PurpleCertificateScheme
;
typedef
struct
_PurpleCertificateVerifier
PurpleCertificateVerifier
;
typedef
struct
_PurpleCertificateVerificationRequest
PurpleCertificateVerificationRequest
;
/**
* PurpleCertificateVerifiedCallback:
* @st: Status code
* @userdata: User-defined data
*
* Callback function for the results of a verification check
*/
typedef
void
(
*
PurpleCertificateVerifiedCallback
)(
PurpleCertificateVerificationStatus
st
,
gpointer
userdata
);
/**
* PurpleCertificate:
* @scheme: Scheme this certificate is under
* @data: Opaque pointer to internal data
*
* A certificate instance
*
* An opaque data structure representing a single certificate under some
* CertificateScheme
*/
struct
_PurpleCertificate
{
PurpleCertificateScheme
*
scheme
;
gpointer
data
;
};
/**
* PurpleCertificatePool:
* @scheme_name: Scheme this Pool operates for
* @name: Internal name to refer to the pool by
* @fullname: User-friendly name for this type. ex: N_("SSL Servers"). When
* this is displayed anywhere, it should be i18ned.
* ex: _(pool->fullname)
* @data: Internal pool data
* @init: Set up the Pool's internal state
* <sbr/>Upon calling purple_certificate_register_pool() , this
* function will be called. May be %NULL.
* <sbr/>Returns: %TRUE if the initialization succeeded,
* otherwise %FALSE.
* @uninit: Uninit the Pool's internal state. Will be called by
* purple_certificate_unregister_pool(). May be %NULL.
* @cert_in_pool: Check for presence of a certificate in the pool using unique
* ID
* @get_cert: Retrieve a PurpleCertificate from the pool
* @put_cert: Add a certificate to the pool. Must overwrite any other
* certificates sharing the same ID in the pool.
* <sbr/>Returns: %TRUE if the operation succeeded, otherwise
* %FALSE.
* @delete_cert: Delete a certificate from the pool
* @get_idlist: Returns a list of IDs stored in the pool
*
* Database for retrieval or storage of Certificates
*
* More or less a hash table; all lookups and writes are controlled by a string
* key.
*/
struct
_PurpleCertificatePool
{
gchar
*
scheme_name
;
gchar
*
name
;
gchar
*
fullname
;
gpointer
data
;
gboolean
(
*
init
)(
void
);
void
(
*
uninit
)(
void
);
gboolean
(
*
cert_in_pool
)(
const
gchar
*
id
);
PurpleCertificate
*
(
*
get_cert
)(
const
gchar
*
id
);
gboolean
(
*
put_cert
)(
const
gchar
*
id
,
PurpleCertificate
*
crt
);
gboolean
(
*
delete_cert
)(
const
gchar
*
id
);
GList
*
(
*
get_idlist
)(
void
);
/*< private >*/
void
(
*
_purple_reserved1
)(
void
);
void
(
*
_purple_reserved2
)(
void
);
void
(
*
_purple_reserved3
)(
void
);
void
(
*
_purple_reserved4
)(
void
);
};
/**
* PurpleCertificateScheme:
* @name: Name of the certificate type. ex: "x509", "pgp", etc.
* <sbr/> This must be globally unique - you may not register more than
* one CertificateScheme of the same name at a time.
* @fullname: User-friendly name for this type. ex: N_("X.509 Certificates")
* <sbr/> When this is displayed anywhere, it should be i18ned. ex:
* _(scheme->fullname)
* @import_certificate: Imports a certificate from a file
* <sbr/> @filename: File to import the certificate from
* <sbr/> Returns: Pointer to the newly allocated
* Certificate struct or NULL on failure.
* @export_certificate: Exports a certificate to a file.
* <sbr/>See purple_certificate_export().
* <sbr/>@filename: File to export the certificate to
* <sbr/>@crt: Certificate to export
* <sbr/>Returns: %TRUE if the export succeeded,
* otherwise %FALSE
* @copy_certificate: Duplicates a certificate
* <sbr/>Certificates are generally assumed to be read-only,
* so feel free to do any sort of reference-counting magic
* you want here. If this ever changes, please remember to
* change the magic accordingly.
* <sbr/>Returns: Reference to the new copy
* @destroy_certificate: Destroys and frees a Certificate structure
* <sbr/> Destroys a Certificate's internal data
* structures and calls free(@crt)
* <sbr/> @crt: Certificate instance to be destroyed.
* It <emphasis>WILL NOT</emphasis> be destroyed if it is
* not of the correct CertificateScheme. Can be %NULL.
* @signed_by: Find whether "crt" has a valid signature from issuer "issuer".
* <sbr/>See purple_certificate_signed_by().
* @get_fingerprint_sha1: Retrieves the certificate public key fingerprint using
* SHA1
* <sbr/>@crt: Certificate instance
* <sbr/>Returns: Binary representation of SHA1 hash -
* must be freed using g_byte_array_free().
* @get_unique_id: Retrieves a unique certificate identifier
* <sbr/>@crt: Certificate instance
* <sbr/>Returns: Newly allocated string that can be used to
* uniquely identify the certificate.
* @get_issuer_unique_id: Retrieves a unique identifier for the certificate's
* issuer
* <sbr/>@crt: Certificate instance
* <sbr/>Returns: Newly allocated string that can be used
* to uniquely identify the issuer's
* certificate.
* @get_subject_name: Gets the certificate subject's name
* <sbr/>For X.509, this is the "Common Name" field, as we're
* only using it for hostname verification at the moment.
* <sbr/>See purple_certificate_get_subject_name().
* <sbr/>@crt: Certificate instance
* <sbr/>Returns: Newly allocated string with the certificate
* subject.
* @check_subject_name: Check the subject name against that on the certificate
* <sbr/>See purple_certificate_check_subject_name().
* <sbr/>Returns: %TRUE if it is a match, else %FALSE
* @get_times: Retrieve the certificate activation/expiration times
* @import_certificates: Imports certificates from a file
* <sbr/> @filename: File to import the certificates from
* <sbr/> Returns: #GSList of pointers to the newly
* allocated Certificate structs or
* %NULL on failure.
* @get_der_data: Retrieves the certificate data in DER form
* <sbr/>@crt: Certificate instance
* <sbr/>Returns: Binary DER representation of certificate - must
* be freed using g_byte_array_free().
*
* A certificate type.
*
* A CertificateScheme must implement all of the fields in the structure,
* and register it using purple_certificate_register_scheme().
*
* There may be only <emphasis>ONE</emphasis> CertificateScheme provided for
* each certificate type, as specified by the "name" field.
*/
struct
_PurpleCertificateScheme
{
gchar
*
name
;
gchar
*
fullname
;
PurpleCertificate
*
(
*
import_certificate
)(
const
gchar
*
filename
);
gboolean
(
*
export_certificate
)(
const
gchar
*
filename
,
PurpleCertificate
*
crt
);
PurpleCertificate
*
(
*
copy_certificate
)(
PurpleCertificate
*
crt
);
void
(
*
destroy_certificate
)(
PurpleCertificate
*
crt
);
/** Find whether "crt" has a valid signature from "issuer," including
* appropriate values for the CA flag in the basic constraints extension.
* @see purple_certificate_signed_by() */
gboolean
(
*
signed_by
)(
PurpleCertificate
*
crt
,
PurpleCertificate
*
issuer
);
GByteArray
*
(
*
get_fingerprint_sha1
)(
PurpleCertificate
*
crt
);
gchar
*
(
*
get_unique_id
)(
PurpleCertificate
*
crt
);
gchar
*
(
*
get_issuer_unique_id
)(
PurpleCertificate
*
crt
);
gchar
*
(
*
get_subject_name
)(
PurpleCertificate
*
crt
);
gboolean
(
*
check_subject_name
)(
PurpleCertificate
*
crt
,
const
gchar
*
name
);
gboolean
(
*
get_times
)(
PurpleCertificate
*
crt
,
gint64
*
activation
,
gint64
*
expiration
);
GSList
*
(
*
import_certificates
)(
const
gchar
*
filename
);
GByteArray
*
(
*
get_der_data
)(
PurpleCertificate
*
crt
);
/**
* Register a certificate as "trusted."
*/
gboolean
(
*
register_trusted_tls_cert
)(
PurpleCertificate
*
crt
,
gboolean
ca
);
/**
* Verify that a certificate is valid, performing all necessary checks
* including date range, valid cert chain, recognized and valid CAs, etc.
*/
void
(
*
verify_cert
)(
PurpleCertificateVerificationRequest
*
vrq
,
PurpleCertificateVerificationStatus
*
flags
);
/*< private >*/
void
(
*
_purple_reserved1
)(
void
);
void
(
*
_purple_reserved2
)(
void
);
void
(
*
_purple_reserved3
)(
void
);
};
/**
* PurpleCertificateVerifier:
* @scheme_name: Name of the scheme this Verifier operates on. The scheme
* will be looked up by name when a Request is generated
* using this Verifier.
* @name: Name of the Verifier - case insensitive.
* @start_verification: Start the verification process. To be called from
* purple_certificate_verify() once it has constructed the
* request. This will use the information in the given
* VerificationRequest to check the certificate and
* callback the requester with the verification results.
* <sbr/>@vrq: The request to process.
* @destroy_request: Destroy a completed Request under this Verifier. The
* function pointed to here is only responsible for
* cleaning up whatever
* #PurpleCertificateVerificationRequest.data points to.
* It should not call free(@vrq).
* <sbr/>@vrq: The request to destroy.
*
* A set of operations used to provide logic for verifying a Certificate's
* authenticity.
*
* A Verifier provider must fill out these fields, then register it using
* purple_certificate_register_verifier().
*
* The (scheme_name, name) value must be unique for each Verifier - you may not
* register more than one Verifier of the same name for each Scheme.
*/
struct
_PurpleCertificateVerifier
{
gchar
*
scheme_name
;
gchar
*
name
;
void
(
*
start_verification
)(
PurpleCertificateVerificationRequest
*
vrq
);
void
(
*
destroy_request
)(
PurpleCertificateVerificationRequest
*
vrq
);
/*< private >*/
void
(
*
_purple_reserved1
)(
void
);
void
(
*
_purple_reserved2
)(
void
);
void
(
*
_purple_reserved3
)(
void
);
void
(
*
_purple_reserved4
)(
void
);
};
/**
* PurpleCertificateVerificationRequest:
* @verifier: Reference to the verification logic used.
* @scheme: Reference to the scheme used. This is looked up from the
* Verifier when the Request is generated.
* @subject_name: Name to check that the certificate is issued to. For X.509
* certificates, this is the Common Name.
* @cert_chain: List of certificates in the chain to be verified (such as that
* returned by purple_ssl_get_peer_certificates()). This is most
* relevant for X.509 certificates used in SSL sessions. The list
* order should be: certificate, issuer, issuer's issuer, etc.
* @data: Internal data used by the Verifier code.
* @cb: Function to call with the verification result.
* @cb_data: Data to pass to the post-verification callback.
*
* Structure for a single certificate request
*
* Useful for keeping track of the state of a verification that involves
* several steps
*/
struct
_PurpleCertificateVerificationRequest
{
PurpleCertificateVerifier
*
verifier
;
PurpleCertificateScheme
*
scheme
;
gchar
*
subject_name
;
GList
*
cert_chain
;
gpointer
data
;
PurpleCertificateVerifiedCallback
cb
;
gpointer
cb_data
;
};
G_BEGIN_DECLS
/*****************************************************************************/
/* Certificate Verification Functions */
/*****************************************************************************/
/**
* purple_certificate_verify:
* @verifier: Verification logic to use.
* See purple_certificate_find_verifier().
* @subject_name: Name that should match the first certificate in the
* chain for the certificate to be valid. Will be strdup'd
* into the Request struct
* @cert_chain: Certificate chain to check. If there is more than one
* certificate in the chain (X.509), the peer's
* certificate comes first, then the issuer/signer's
* certificate, etc. The whole list is duplicated into the
* Request struct.
* @cb: (scope call): Callback function to be called with whether the
* certificate was approved or not.
* @cb_data: User-defined data for the above.
*
* Constructs a verification request and passed control to the specified Verifier
*
* It is possible that the callback will be called immediately upon calling
* this function. Plan accordingly.
*/
void
purple_certificate_verify
(
PurpleCertificateVerifier
*
verifier
,
const
gchar
*
subject_name
,
GList
*
cert_chain
,
PurpleCertificateVerifiedCallback
cb
,
gpointer
cb_data
);
/**
* purple_certificate_verify_complete:
* @vrq: Request to conclude
* @st: Success/failure code to pass to the request's
* completion callback.
*
* Completes and destroys a VerificationRequest
*/
void
purple_certificate_verify_complete
(
PurpleCertificateVerificationRequest
*
vrq
,
PurpleCertificateVerificationStatus
st
);
/*****************************************************************************/
/* Certificate Functions */
/*****************************************************************************/
/**
* purple_certificate_get_type:
*
* Returns: The #GType for the #PurpleCertificate boxed structure.
*/
GType
purple_certificate_get_type
(
void
);
/**
* purple_certificate_copy:
* @crt: Instance to duplicate
*
* Makes a duplicate of a certificate
*
* Returns: Pointer to new instance
*/
PurpleCertificate
*
purple_certificate_copy
(
PurpleCertificate
*
crt
);
/**
* purple_certificate_copy_list:
* @crt_list: List to duplicate
*
* Duplicates an entire list of certificates
*
* Returns: New list copy
*/
GList
*
purple_certificate_copy_list
(
GList
*
crt_list
);
/**
* purple_certificate_destroy:
* @crt: Instance to destroy. May be NULL.
*
* Destroys and free()'s a Certificate
*/
void
purple_certificate_destroy
(
PurpleCertificate
*
crt
);
/**
* purple_certificate_destroy_list:
* @crt_list: List of certificates to destroy. May be NULL.
*
* Destroy an entire list of Certificate instances and the containing list
*/
void
purple_certificate_destroy_list
(
GList
*
crt_list
);
/**
* purple_certificate_signed_by:
* @crt: Certificate instance to check signature of
* @issuer: Certificate thought to have signed 'crt'
*
* Check whether 'crt' has a valid signature made by 'issuer'
*
* Returns: TRUE if 'crt' has a valid signature made by 'issuer',
* otherwise FALSE
*/
/* TODO Find a way to give the reason (bad signature, not the issuer, etc.) */
gboolean
purple_certificate_signed_by
(
PurpleCertificate
*
crt
,
PurpleCertificate
*
issuer
);
/**
* purple_certificate_check_signature_chain:
* @chain: List of PurpleCertificate instances comprising the chain,
* in the order certificate, issuer, issuer's issuer, etc.
* @failing: A pointer to a PurpleCertificate*. If not NULL, if the
* chain fails to validate, this will be set to the
* certificate whose signature could not be validated.
*
* Check that a certificate chain is valid and, if not, the failing certificate.
*
* Uses purple_certificate_signed_by() to verify that each PurpleCertificate
* in the chain carries a valid signature from the next. A single-certificate
* chain is considered to be valid.
*
* Returns: TRUE if the chain is valid. See description.
*/
gboolean
purple_certificate_check_signature_chain
(
GList
*
chain
,
PurpleCertificate
**
failing
);
/**
* purple_certificate_import:
* @scheme: Scheme to import under
* @filename: File path to import from
*
* Imports a PurpleCertificate from a file
*
* Returns: Pointer to a new PurpleCertificate, or NULL on failure
*/
PurpleCertificate
*
purple_certificate_import
(
PurpleCertificateScheme
*
scheme
,
const
gchar
*
filename
);
/**
* purple_certificates_import:
* @scheme: Scheme to import under
* @filename: File path to import from
*
* Imports a list of PurpleCertificates from a file
*
* Returns: Pointer to a GSList of new PurpleCertificates, or NULL on failure
*/
GSList
*
purple_certificates_import
(
PurpleCertificateScheme
*
scheme
,
const
gchar
*
filename
);
/**
* purple_certificate_export:
* @filename: File to export the certificate to
* @crt: Certificate to export
*
* Exports a PurpleCertificate to a file
*
* Returns: TRUE if the export succeeded, otherwise FALSE
*/
gboolean
purple_certificate_export
(
const
gchar
*
filename
,
PurpleCertificate
*
crt
);
/**
* purple_certificate_get_fingerprint_sha1:
* @crt: Certificate instance
*
* Retrieves the certificate public key fingerprint using SHA1.
* See purple_base16_encode_chunked().
*
* Returns: Binary representation of the hash. You are responsible for free()ing
* this.
*/
GByteArray
*
purple_certificate_get_fingerprint_sha1
(
PurpleCertificate
*
crt
);
/**
* purple_certificate_get_unique_id:
* @crt: Certificate instance
*
* Get a unique identifier for the certificate
*
* Returns: String representing the certificate uniquely. Must be g_free()'ed
*/
gchar
*
purple_certificate_get_unique_id
(
PurpleCertificate
*
crt
);
/**
* purple_certificate_get_issuer_unique_id:
* @crt: Certificate instance
*
* Get a unique identifier for the certificate's issuer
*
* Returns: String representing the certificate's issuer uniquely. Must be
* g_free()'ed
*/
gchar
*
purple_certificate_get_issuer_unique_id
(
PurpleCertificate
*
crt
);
/**
* purple_certificate_get_subject_name:
* @crt: Certificate instance
*
* Gets the certificate subject's name
*
* For X.509, this is the "Common Name" field, as we're only using it
* for hostname verification at the moment
*
* Returns: Newly allocated string with the certificate subject.
*/
gchar
*
purple_certificate_get_subject_name
(
PurpleCertificate
*
crt
);
/**
* purple_certificate_check_subject_name:
* @crt: Certificate instance
* @name: Name to check.
*
* Check the subject name against that on the certificate
*
* Returns: TRUE if it is a match, else FALSE
*/
gboolean
purple_certificate_check_subject_name
(
PurpleCertificate
*
crt
,
const
gchar
*
name
);
/**
* purple_certificate_get_times:
* @crt: Certificate instance
* @activation: Reference to store the activation time at. May be NULL
* if you don't actually want it.
* @expiration: Reference to store the expiration time at. May be NULL
* if you don't actually want it.
*
* Get the expiration/activation times.
*
* Returns: TRUE if the requested values were obtained, otherwise FALSE.
*/
gboolean
purple_certificate_get_times
(
PurpleCertificate
*
crt
,
gint64
*
activation
,
gint64
*
expiration
);
/**
* purple_certificate_get_der_data:
* @crt: Certificate instance
*
* Retrieves the certificate data in DER form.
*
* Returns: Binary DER representation of the certificate - must be freed using
* g_byte_array_free().
*/
GByteArray
*
purple_certificate_get_der_data
(
PurpleCertificate
*
crt
);
/**
* purple_certificate_get_display_string:
* @crt: Certificate instance
*
* Retrieves a string suitable for displaying a certificate to the user.
*
* Returns: String representing the certificate that may be displayed to the user
* - must be freed using g_free().
*/
char
*
purple_certificate_get_display_string
(
PurpleCertificate
*
crt
);
/*****************************************************************************/
/* Certificate Pool Functions */
/*****************************************************************************/
/**
* purple_certificate_pool_get_type:
*
* Returns: The #GType for the #PurpleCertificatePool boxed structure.
*/
/* TODO: Boxing of PurpleCertificatePool is a temporary solution to having a
* GType for certificate pools. This should rather be a GObject instead of
* a GBoxed. */
GType
purple_certificate_pool_get_type
(
void
);
/**
* purple_certificate_pool_mkpath:
* @pool: CertificatePool to build a path for
* @id: Key to look up a Certificate by. May be NULL.
*
* Helper function for generating file paths in ~/.purple/certificates for
* CertificatePools that use them.
*
* All components will be escaped for filesystem friendliness.
*
* Returns: A newly allocated path of the form
* ~/.purple/certificates/scheme_name/pool_name/unique_id
*/
gchar
*
purple_certificate_pool_mkpath
(
PurpleCertificatePool
*
pool
,
const
gchar
*
id
);
/**
* purple_certificate_pool_usable:
* @pool: Pool to check
*
* Determines whether a pool can be used.
*
* Checks whether the associated CertificateScheme is loaded.
*
* Returns: TRUE if the pool can be used, otherwise FALSE
*/
gboolean
purple_certificate_pool_usable
(
PurpleCertificatePool
*
pool
);
/**
* purple_certificate_pool_get_scheme:
* @pool: Pool to get the scheme of
*
* Looks up the scheme the pool operates under.
* See purple_certificate_pool_usable()
*
* Returns: Pointer to the pool's scheme, or NULL if it isn't loaded.
*/
PurpleCertificateScheme
*
purple_certificate_pool_get_scheme
(
PurpleCertificatePool
*
pool
);
/**
* purple_certificate_pool_contains:
* @pool: Pool to look in
* @id: ID to look for
*
* Check for presence of an ID in a pool.
*
* Returns: TRUE if the ID is in the pool, else FALSE
*/
gboolean
purple_certificate_pool_contains
(
PurpleCertificatePool
*
pool
,
const
gchar
*
id
);
/**
* purple_certificate_pool_retrieve:
* @pool: Pool to fish in
* @id: ID to look up
*
* Retrieve a certificate from a pool.
*
* Returns: Retrieved certificate (to be freed with
* purple_certificate_destroy), or NULL if it wasn't there
*/
PurpleCertificate
*
purple_certificate_pool_retrieve
(
PurpleCertificatePool
*
pool
,
const
gchar
*
id
);
/**
* purple_certificate_pool_store:
* @pool: Pool to add to
* @id: ID to store the certificate with
* @crt: Certificate to store
*
* Add a certificate to a pool
*
* Any pre-existing certificate of the same ID will be overwritten.
*
* Returns: TRUE if the operation succeeded, otherwise FALSE
*/
gboolean
purple_certificate_pool_store
(
PurpleCertificatePool
*
pool
,
const
gchar
*
id
,
PurpleCertificate
*
crt
);
/**
* purple_certificate_pool_delete:
* @pool: Pool to remove from
* @id: ID to remove
*
* Remove a certificate from a pool
*
* Returns: TRUE if the operation succeeded, otherwise FALSE
*/
gboolean
purple_certificate_pool_delete
(
PurpleCertificatePool
*
pool
,
const
gchar
*
id
);
/**
* purple_certificate_pool_get_idlist:
* @pool: Pool to enumerate
*
* Get the list of IDs currently in the pool.
*
* Returns: GList pointing to newly-allocated id strings. Free using
* purple_certificate_pool_destroy_idlist()
*/
GList
*
purple_certificate_pool_get_idlist
(
PurpleCertificatePool
*
pool
);
/**
* purple_certificate_pool_destroy_idlist:
* @idlist: ID List to destroy
*
* Destroys the result given by purple_certificate_pool_get_idlist()
*/
void
purple_certificate_pool_destroy_idlist
(
GList
*
idlist
);
/*****************************************************************************/
/* Certificate Subsystem API */
/*****************************************************************************/
/**
* purple_certificate_init:
*
* Initialize the certificate system
*/
void
purple_certificate_init
(
void
);
/**
* purple_certificate_uninit:
*
* Un-initialize the certificate system
*/
void
purple_certificate_uninit
(
void
);
/**
* purple_certificate_get_handle:
*
* Get the Certificate subsystem handle for signalling purposes
*/
gpointer
purple_certificate_get_handle
(
void
);
/**
* purple_certificate_find_scheme:
* @name: The scheme name. Case insensitive.
*
* Look up a registered CertificateScheme by name
*
* Returns: Pointer to the located Scheme, or NULL if it isn't found.
*/
PurpleCertificateScheme
*
purple_certificate_find_scheme
(
const
gchar
*
name
);
/**
* purple_certificate_get_schemes:
*
* Get all registered CertificateSchemes
*
* Returns: GList pointing to all registered CertificateSchemes . This value
* is owned by libpurple
*/
GList
*
purple_certificate_get_schemes
(
void
);
/**
* purple_certificate_register_scheme:
* @scheme: Pointer to the scheme to register.
*
* Register a CertificateScheme with libpurple
*
* No two schemes can be registered with the same name; this function enforces
* that.
*
* Returns: TRUE if the scheme was successfully added, otherwise FALSE
*/
gboolean
purple_certificate_register_scheme
(
PurpleCertificateScheme
*
scheme
);
/**
* purple_certificate_unregister_scheme:
* @scheme: Scheme to unregister.
* If the scheme is not registered, this is a no-op.
*
* Unregister a CertificateScheme from libpurple
*
* Returns: TRUE if the unregister completed successfully
*/
gboolean
purple_certificate_unregister_scheme
(
PurpleCertificateScheme
*
scheme
);
/**
* purple_certificate_find_verifier:
* @scheme_name: Scheme name. Case insensitive.
* @ver_name: The verifier name. Case insensitive.
*
* Look up a registered PurpleCertificateVerifier by scheme and name
*
* Returns: Pointer to the located Verifier, or NULL if it isn't found.
*/
PurpleCertificateVerifier
*
purple_certificate_find_verifier
(
const
gchar
*
scheme_name
,
const
gchar
*
ver_name
);
/**
* purple_certificate_get_verifiers:
*
* Get the list of registered CertificateVerifiers
*
* Returns: GList of all registered PurpleCertificateVerifier. This value
* is owned by libpurple
*/
GList
*
purple_certificate_get_verifiers
(
void
);
/**
* purple_certificate_register_verifier:
* @vr: Verifier to register.
*
* Register a CertificateVerifier with libpurple
*
* Returns: TRUE if register succeeded, otherwise FALSE
*/
gboolean
purple_certificate_register_verifier
(
PurpleCertificateVerifier
*
vr
);
/**
* purple_certificate_unregister_verifier:
* @vr: Verifier to unregister.
*
* Unregister a CertificateVerifier with libpurple
*
* Returns: TRUE if unregister succeeded, otherwise FALSE
*/
gboolean
purple_certificate_unregister_verifier
(
PurpleCertificateVerifier
*
vr
);
/**
* purple_certificate_find_pool:
* @scheme_name: Scheme name. Case insensitive.
* @pool_name: Pool name. Case insensitive.
*
* Look up a registered PurpleCertificatePool by scheme and name
*
* Returns: Pointer to the located Pool, or NULL if it isn't found.
*/
PurpleCertificatePool
*
purple_certificate_find_pool
(
const
gchar
*
scheme_name
,
const
gchar
*
pool_name
);
/**
* purple_certificate_get_pools:
*
* Get the list of registered Pools
*
* Returns: GList of all registered PurpleCertificatePool s. This value
* is owned by libpurple
*/
GList
*
purple_certificate_get_pools
(
void
);
/**
* purple_certificate_register_pool:
* @pool: Pool to register.
*
* Register a CertificatePool with libpurple and call its init function
*
* Returns: TRUE if the register succeeded, otherwise FALSE
*/
gboolean
purple_certificate_register_pool
(
PurpleCertificatePool
*
pool
);
/**
* purple_certificate_unregister_pool:
* @pool: Pool to unregister.
*
* Unregister a CertificatePool with libpurple and call its uninit function
*
* Returns: TRUE if the unregister succeeded, otherwise FALSE
*/
gboolean
purple_certificate_unregister_pool
(
PurpleCertificatePool
*
pool
);
/**
* purple_certificate_add_ca_search_path:
* @path: Path to search for certificates.
*
* Add a search path for certificates.
*/
void
purple_certificate_add_ca_search_path
(
const
char
*
path
);
G_END_DECLS
#endif
/* _PURPLE_CERTIFICATE_H */
