certificate.h File Reference

Public-Key Certificate API. More...

#include <time.h>
#include <glib.h>

Include dependency graph for certificate.h:

This graph shows which files directly or indirectly include this file:


Data Structures
struct	_PurpleCertificate
	A certificate instance. More...
struct	_PurpleCertificatePool
	Database for retrieval or storage of Certificates. More...
struct	_PurpleCertificateScheme
	A certificate type. More...
struct	_PurpleCertificateVerifier
	A set of operations used to provide logic for verifying a Certificate's authenticity. More...
struct	_PurpleCertificateVerificationRequest
	Structure for a single certificate request. More...
Typedefs
typedef struct _PurpleCertificate	PurpleCertificate
typedef struct _PurpleCertificatePool	PurpleCertificatePool
typedef struct _PurpleCertificateScheme	PurpleCertificateScheme
typedef struct _PurpleCertificateVerifier	PurpleCertificateVerifier
typedef struct _PurpleCertificateVerificationRequest	PurpleCertificateVerificationRequest
typedef void(*	PurpleCertificateVerifiedCallback )(PurpleCertificateVerificationStatus st, gpointer userdata)
	Callback function for the results of a verification check.
Enumerations
enum	PurpleCertificateVerificationStatus { PURPLE_CERTIFICATE_INVALID = 0, PURPLE_CERTIFICATE_VALID = 1 }
Functions
void	purple_certificate_display_x509 (PurpleCertificate *crt)
	Displays a window showing X.509 certificate information.
void	purple_certificate_add_ca_search_path (const char *path)
	Add a search path for certificates.
Certificate Verification Functions
void	purple_certificate_verify (PurpleCertificateVerifier verifier, const gchar subject_name, GList *cert_chain, PurpleCertificateVerifiedCallback cb, gpointer cb_data)
	Constructs a verification request and passed control to the specified Verifier.
void	purple_certificate_verify_complete (PurpleCertificateVerificationRequest *vrq, PurpleCertificateVerificationStatus st)
	Completes and destroys a VerificationRequest.
Certificate Functions
PurpleCertificate *	purple_certificate_copy (PurpleCertificate *crt)
	Makes a duplicate of a certificate.
GList *	purple_certificate_copy_list (GList *crt_list)
	Duplicates an entire list of certificates.
void	purple_certificate_destroy (PurpleCertificate *crt)
	Destroys and free()'s a Certificate.
void	purple_certificate_destroy_list (GList *crt_list)
	Destroy an entire list of Certificate instances and the containing list.
gboolean	purple_certificate_signed_by (PurpleCertificate crt, PurpleCertificate issuer)
	Check whether 'crt' has a valid signature made by 'issuer'.
gboolean	purple_certificate_check_signature_chain_with_failing (GList chain, PurpleCertificate *failing)
	Check that a certificate chain is valid and, if not, the failing certificate.
gboolean	purple_certificate_check_signature_chain (GList *chain)
	Check that a certificate chain is valid.
PurpleCertificate *	purple_certificate_import (PurpleCertificateScheme scheme, const gchar filename)
	Imports a PurpleCertificate from a file.
gboolean	purple_certificate_export (const gchar filename, PurpleCertificate crt)
	Exports a PurpleCertificate to a file.
GByteArray *	purple_certificate_get_fingerprint_sha1 (PurpleCertificate *crt)
	Retrieves the certificate public key fingerprint using SHA1.
gchar *	purple_certificate_get_unique_id (PurpleCertificate *crt)
	Get a unique identifier for the certificate.
gchar *	purple_certificate_get_issuer_unique_id (PurpleCertificate *crt)
	Get a unique identifier for the certificate's issuer.
gchar *	purple_certificate_get_subject_name (PurpleCertificate *crt)
	Gets the certificate subject's name.
gboolean	purple_certificate_check_subject_name (PurpleCertificate crt, const gchar name)
	Check the subject name against that on the certificate.
gboolean	purple_certificate_get_times (PurpleCertificate crt, time_t activation, time_t *expiration)
	Get the expiration/activation times.
Certificate Pool Functions
gchar *	purple_certificate_pool_mkpath (PurpleCertificatePool pool, const gchar id)
	Helper function for generating file paths in ~/.purple/certificates for CertificatePools that use them.
gboolean	purple_certificate_pool_usable (PurpleCertificatePool *pool)
	Determines whether a pool can be used.
PurpleCertificateScheme *	purple_certificate_pool_get_scheme (PurpleCertificatePool *pool)
	Looks up the scheme the pool operates under.
gboolean	purple_certificate_pool_contains (PurpleCertificatePool pool, const gchar id)
	Check for presence of an ID in a pool.
PurpleCertificate *	purple_certificate_pool_retrieve (PurpleCertificatePool pool, const gchar id)
	Retrieve a certificate from a pool.
gboolean	purple_certificate_pool_store (PurpleCertificatePool pool, const gchar id, PurpleCertificate *crt)
	Add a certificate to a pool.
gboolean	purple_certificate_pool_delete (PurpleCertificatePool pool, const gchar id)
	Remove a certificate from a pool.
GList *	purple_certificate_pool_get_idlist (PurpleCertificatePool *pool)
	Get the list of IDs currently in the pool.
void	purple_certificate_pool_destroy_idlist (GList *idlist)
	Destroys the result given by purple_certificate_pool_get_idlist().
Certificate Subsystem API
void	purple_certificate_init (void)
	Initialize the certificate system.
void	purple_certificate_uninit (void)
	Un-initialize the certificate system.
gpointer	purple_certificate_get_handle (void)
	Get the Certificate subsystem handle for signalling purposes.
PurpleCertificateScheme *	purple_certificate_find_scheme (const gchar *name)
	Look up a registered CertificateScheme by name.
GList *	purple_certificate_get_schemes (void)
	Get all registered CertificateSchemes.
gboolean	purple_certificate_register_scheme (PurpleCertificateScheme *scheme)
	Register a CertificateScheme with libpurple.
gboolean	purple_certificate_unregister_scheme (PurpleCertificateScheme *scheme)
	Unregister a CertificateScheme from libpurple.
PurpleCertificateVerifier *	purple_certificate_find_verifier (const gchar scheme_name, const gchar ver_name)
	Look up a registered PurpleCertificateVerifier by scheme and name.
GList *	purple_certificate_get_verifiers (void)
	Get the list of registered CertificateVerifiers.
gboolean	purple_certificate_register_verifier (PurpleCertificateVerifier *vr)
	Register a CertificateVerifier with libpurple.
gboolean	purple_certificate_unregister_verifier (PurpleCertificateVerifier *vr)
	Unregister a CertificateVerifier with libpurple.
PurpleCertificatePool *	purple_certificate_find_pool (const gchar scheme_name, const gchar pool_name)
	Look up a registered PurpleCertificatePool by scheme and name.
GList *	purple_certificate_get_pools (void)
	Get the list of registered Pools.
gboolean	purple_certificate_register_pool (PurpleCertificatePool *pool)
	Register a CertificatePool with libpurple and call its init function.
gboolean	purple_certificate_unregister_pool (PurpleCertificatePool *pool)
	Unregister a CertificatePool with libpurple and call its uninit function.

Detailed Description

Public-Key Certificate API.

See also:: Certificate Signals

Since:: 2.2.0

Definition in file certificate.h.

Typedef Documentation

typedef void(* PurpleCertificateVerifiedCallback)(PurpleCertificateVerificationStatus st, gpointer userdata)

Callback function for the results of a verification check.

Parameters:

	st	Status code
	userdata	User-defined data

Definition at line 61 of file certificate.h.

Function Documentation

void purple_certificate_add_ca_search_path ( const char * path )

Add a search path for certificates.

Parameters:

path

Path to search for certificates.

gboolean purple_certificate_check_signature_chain ( GList * chain )

Check that a certificate chain is valid.

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.

Parameters:

chain

List of PurpleCertificate instances comprising the chain, in the order certificate, issuer, issuer's issuer, etc.

Returns:: TRUE if the chain is valid. See description.

Todo:: Specify which certificate in the chain caused a failure

Deprecated:: This function will be removed in 3.0.0 and replaced with purple_certificate_check_signature_chain_with_failing

gboolean purple_certificate_check_signature_chain_with_failing	(	GList *	chain,
		PurpleCertificate **	failing
	)

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.

Parameters:

	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.

Returns:: TRUE if the chain is valid. See description.

Since:: 2.6.0

Deprecated:: This function will become purple_certificate_check_signature_chain in 3.0.0

gboolean purple_certificate_check_subject_name	(	PurpleCertificate *	crt,
		const gchar *	name
	)

Check the subject name against that on the certificate.

Parameters:

	crt	Certificate instance
	name	Name to check.

Returns:: TRUE if it is a match, else FALSE

PurpleCertificate* purple_certificate_copy ( PurpleCertificate * crt )

Makes a duplicate of a certificate.

Parameters:

crt

Instance to duplicate

Returns:: Pointer to new instance

GList* purple_certificate_copy_list ( GList * crt_list )

Duplicates an entire list of certificates.

Parameters:

crt_list

List to duplicate

Returns:: New list copy

void purple_certificate_destroy ( PurpleCertificate * crt )

Destroys and free()'s a Certificate.

Parameters:

crt

Instance to destroy. May be NULL.

void purple_certificate_destroy_list ( GList * crt_list )

Destroy an entire list of Certificate instances and the containing list.

Parameters:

crt_list

List of certificates to destroy. May be NULL.

void purple_certificate_display_x509 ( PurpleCertificate * crt )

Displays a window showing X.509 certificate information.

Parameters:

crt

Certificate under an "x509" Scheme

Todo:: Will break on CA certs, as they have no Common Name

gboolean purple_certificate_export	(	const gchar *	filename,
		PurpleCertificate *	crt
	)

Exports a PurpleCertificate to a file.

Parameters:

	filename	File to export the certificate to
	crt	Certificate to export

Returns:: TRUE if the export succeeded, otherwise FALSE

PurpleCertificatePool* purple_certificate_find_pool	(	const gchar *	scheme_name,
		const gchar *	pool_name
	)

Look up a registered PurpleCertificatePool by scheme and name.

Parameters:

	scheme_name	Scheme name. Case insensitive.
	pool_name	Pool name. Case insensitive.

Returns:: Pointer to the located Pool, or NULL if it isn't found.

PurpleCertificateScheme* purple_certificate_find_scheme ( const gchar * name )

Look up a registered CertificateScheme by name.

Parameters:

name

The scheme name. Case insensitive.

Returns:: Pointer to the located Scheme, or NULL if it isn't found.

PurpleCertificateVerifier* purple_certificate_find_verifier	(	const gchar *	scheme_name,
		const gchar *	ver_name
	)

Look up a registered PurpleCertificateVerifier by scheme and name.

Parameters:

	scheme_name	Scheme name. Case insensitive.
	ver_name	The verifier name. Case insensitive.

Returns:: Pointer to the located Verifier, or NULL if it isn't found.

GByteArray* purple_certificate_get_fingerprint_sha1 ( PurpleCertificate * crt )

Retrieves the certificate public key fingerprint using SHA1.

Parameters:

crt

Certificate instance

Returns:: Binary representation of the hash. You are responsible for free()ing this.

See also:: purple_base16_encode_chunked()

gchar* purple_certificate_get_issuer_unique_id ( PurpleCertificate * crt )

Get a unique identifier for the certificate's issuer.

Parameters:

crt

Certificate instance

Returns:: String representing the certificate's issuer uniquely. Must be g_free()'ed

GList* purple_certificate_get_pools ( void )

Get the list of registered Pools.

Returns:: GList of all registered PurpleCertificatePool s. This value is owned by libpurple

GList* purple_certificate_get_schemes ( void )

Get all registered CertificateSchemes.

Returns:: GList pointing to all registered CertificateSchemes . This value is owned by libpurple

gchar* purple_certificate_get_subject_name ( PurpleCertificate * crt )

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

Parameters:

crt

Certificate instance

Returns:: Newly allocated string with the certificate subject.

gboolean purple_certificate_get_times	(	PurpleCertificate *	crt,
		time_t *	activation,
		time_t *	expiration
	)

Get the expiration/activation times.

Parameters:

	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.

Returns:: TRUE if the requested values were obtained, otherwise FALSE.

gchar* purple_certificate_get_unique_id ( PurpleCertificate * crt )

Get a unique identifier for the certificate.

Parameters:

crt

Certificate instance

Returns:: String representing the certificate uniquely. Must be g_free()'ed

GList* purple_certificate_get_verifiers ( void )

Get the list of registered CertificateVerifiers.

Returns:: GList of all registered PurpleCertificateVerifier. This value is owned by libpurple

PurpleCertificate* purple_certificate_import	(	PurpleCertificateScheme *	scheme,
		const gchar *	filename
	)

Imports a PurpleCertificate from a file.

Parameters:

	scheme	Scheme to import under
	filename	File path to import from

Returns:: Pointer to a new PurpleCertificate, or NULL on failure

gboolean purple_certificate_pool_contains	(	PurpleCertificatePool *	pool,
		const gchar *	id
	)

Check for presence of an ID in a pool.

Parameters:

	pool	Pool to look in
	id	ID to look for

Returns:: TRUE if the ID is in the pool, else FALSE

gboolean purple_certificate_pool_delete	(	PurpleCertificatePool *	pool,
		const gchar *	id
	)

Remove a certificate from a pool.

Parameters:

	pool	Pool to remove from
	id	ID to remove

Returns:: TRUE if the operation succeeded, otherwise FALSE

void purple_certificate_pool_destroy_idlist ( GList * idlist )

Destroys the result given by purple_certificate_pool_get_idlist().

Parameters:

idlist

ID List to destroy

GList* purple_certificate_pool_get_idlist ( PurpleCertificatePool * pool )

Get the list of IDs currently in the pool.

Parameters:

pool

Pool to enumerate

Returns:: GList pointing to newly-allocated id strings. Free using purple_certificate_pool_destroy_idlist()

PurpleCertificateScheme* purple_certificate_pool_get_scheme ( PurpleCertificatePool * pool )

Looks up the scheme the pool operates under.

Parameters:

pool

Pool to get the scheme of

Returns:: Pointer to the pool's scheme, or NULL if it isn't loaded.

See also:: purple_certificate_pool_usable()

gchar* purple_certificate_pool_mkpath	(	PurpleCertificatePool *	pool,
		const gchar *	id
	)

Helper function for generating file paths in ~/.purple/certificates for CertificatePools that use them.

All components will be escaped for filesystem friendliness.

Parameters:

	pool	CertificatePool to build a path for
	id	Key to look up a Certificate by. May be NULL.

Returns:: A newly allocated path of the form ~/.purple/certificates/scheme_name/pool_name/unique_id

PurpleCertificate* purple_certificate_pool_retrieve	(	PurpleCertificatePool *	pool,
		const gchar *	id
	)

Retrieve a certificate from a pool.

Parameters:

	pool	Pool to fish in
	id	ID to look up

Returns:: Retrieved certificate, or NULL if it wasn't there

gboolean purple_certificate_pool_store	(	PurpleCertificatePool *	pool,
		const gchar *	id,
		PurpleCertificate *	crt
	)

Add a certificate to a pool.

Any pre-existing certificate of the same ID will be overwritten.

Parameters:

	pool	Pool to add to
	id	ID to store the certificate with
	crt	Certificate to store

Returns:: TRUE if the operation succeeded, otherwise FALSE

gboolean purple_certificate_pool_usable ( PurpleCertificatePool * pool )

Determines whether a pool can be used.

Checks whether the associated CertificateScheme is loaded.

Parameters:

pool

Pool to check

Returns:: TRUE if the pool can be used, otherwise FALSE

gboolean purple_certificate_register_pool ( PurpleCertificatePool * pool )

Register a CertificatePool with libpurple and call its init function.

Parameters:

pool

Pool to register.

Returns:: TRUE if the register succeeded, otherwise FALSE

gboolean purple_certificate_register_scheme ( PurpleCertificateScheme * scheme )

Register a CertificateScheme with libpurple.

No two schemes can be registered with the same name; this function enforces that.

Parameters:

scheme

Pointer to the scheme to register.

Returns:: TRUE if the scheme was successfully added, otherwise FALSE

gboolean purple_certificate_register_verifier ( PurpleCertificateVerifier * vr )

Register a CertificateVerifier with libpurple.

Parameters:

vr

Verifier to register.

Returns:: TRUE if register succeeded, otherwise FALSE

gboolean purple_certificate_signed_by	(	PurpleCertificate *	crt,
		PurpleCertificate *	issuer
	)

Check whether 'crt' has a valid signature made by 'issuer'.

Parameters:

	crt	Certificate instance to check signature of
	issuer	Certificate thought to have signed 'crt'

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_unregister_pool ( PurpleCertificatePool * pool )

Unregister a CertificatePool with libpurple and call its uninit function.

Parameters:

pool

Pool to unregister.

Returns:: TRUE if the unregister succeeded, otherwise FALSE

gboolean purple_certificate_unregister_scheme ( PurpleCertificateScheme * scheme )

Unregister a CertificateScheme from libpurple.

Parameters:

scheme

Scheme to unregister. If the scheme is not registered, this is a no-op.

Returns:: TRUE if the unregister completed successfully

gboolean purple_certificate_unregister_verifier ( PurpleCertificateVerifier * vr )

Unregister a CertificateVerifier with libpurple.

Parameters:

vr

Verifier to unregister.

Returns:: TRUE if unregister succeeded, otherwise FALSE

void purple_certificate_verify	(	PurpleCertificateVerifier *	verifier,
		const gchar *	subject_name,
		GList *	cert_chain,
		PurpleCertificateVerifiedCallback	cb,
		gpointer	cb_data
	)

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.

Parameters:

verifier

Verification logic to use.

See also:: purple_certificate_find_verifier()

Parameters:

	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	Callback function to be called with whether the certificate was approved or not.
	cb_data	User-defined data for the above.

void purple_certificate_verify_complete	(	PurpleCertificateVerificationRequest *	vrq,
		PurpleCertificateVerificationStatus	st
	)

Completes and destroys a VerificationRequest.

Parameters:

	vrq	Request to conclude
	st	Success/failure code to pass to the request's completion callback.

Context Navigation

certificate.h File Reference

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Function Documentation