Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages | Search for 
libpurple

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:

Go to the source code of 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...

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 (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.

Typedefs

typedef _PurpleCertificate PurpleCertificate
typedef _PurpleCertificatePool PurpleCertificatePool
typedef _PurpleCertificateScheme PurpleCertificateScheme
typedef _PurpleCertificateVerifier PurpleCertificateVerifier
typedef _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.

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

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.