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

Macros

#define PURPLE_CERTIFICATE_SCHEME_HAS_FUNC(obj, member)

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 }
enum  PurpleCertificateInvalidityFlags {
  PURPLE_CERTIFICATE_UNKNOWN_ERROR = -1, PURPLE_CERTIFICATE_NO_PROBLEMS = 0, PURPLE_CERTIFICATE_NON_FATALS_MASK = 0x0000FFFF, PURPLE_CERTIFICATE_SELF_SIGNED = 0x01,
  PURPLE_CERTIFICATE_CA_UNKNOWN = 0x02, PURPLE_CERTIFICATE_NOT_ACTIVATED = 0x04, PURPLE_CERTIFICATE_EXPIRED = 0x08, PURPLE_CERTIFICATE_NAME_MISMATCH = 0x10,
  PURPLE_CERTIFICATE_NO_CA_POOL = 0x20, PURPLE_CERTIFICATE_FATALS_MASK = 0xFFFF0000, PURPLE_CERTIFICATE_INVALID_CHAIN = 0x10000, PURPLE_CERTIFICATE_REVOKED = 0x20000,
  PURPLE_CERTIFICATE_LAST = 0x40000
}

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
PurpleCertificatepurple_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.
PurpleCertificatepurple_certificate_import (PurpleCertificateScheme *scheme, const gchar *filename)
 Imports a PurpleCertificate from a file.
GSList * purple_certificates_import (PurpleCertificateScheme *scheme, const gchar *filename)
 Imports a list of PurpleCertificates 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.
GByteArray * purple_certificate_get_fingerprint_sha256 (PurpleCertificate *crt, gboolean sha1_fallback)
 Retrieves the certificate public key fingerprint using SHA256.
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.
gboolean purple_certificate_compare_pubkeys (PurpleCertificate *crt1, PurpleCertificate *crt2)
 Compares the public keys of two certificates.
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.
PurpleCertificateSchemepurple_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.
PurpleCertificatepurple_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.
PurpleCertificateSchemepurple_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.
PurpleCertificateVerifierpurple_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.
PurpleCertificatePoolpurple_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.

Macro Definition Documentation

#define PURPLE_CERTIFICATE_SCHEME_HAS_FUNC (   obj,
  member 
)
Value:
(((G_STRUCT_OFFSET(PurpleCertificateScheme, member) < G_STRUCT_OFFSET(PurpleCertificateScheme, struct_size)) \
|| (G_STRUCT_OFFSET(PurpleCertificateScheme, member) < obj->struct_size)) && \
obj->member != NULL)

Definition at line 347 of file certificate.h.

Typedef Documentation

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

Callback function for the results of a verification check.

Parameters
stStatus code
userdataUser-defined data

Definition at line 106 of file certificate.h.

Function Documentation

void purple_certificate_add_ca_search_path ( const char *  path)

Add a search path for certificates.

Parameters
pathPath 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
chainList 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
chainList of PurpleCertificate instances comprising the chain, in the order certificate, issuer, issuer's issuer, etc.
failingA 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
crtCertificate instance
nameName to check.
Returns
TRUE if it is a match, else FALSE
gboolean purple_certificate_compare_pubkeys ( PurpleCertificate crt1,
PurpleCertificate crt2 
)

Compares the public keys of two certificates.

If the SSL backend does not implement this function, it may return FALSE every time. This is the case with the NSS plugin, which doesn't need it.

Parameters
crt1A certificate instance
crt2Another certificate instance
Returns
TRUE if both certificates have the same key, otherwise FALSE
Since
2.12.0
PurpleCertificate* purple_certificate_copy ( PurpleCertificate crt)

Makes a duplicate of a certificate.

Parameters
crtInstance to duplicate
Returns
Pointer to new instance
GList* purple_certificate_copy_list ( GList *  crt_list)

Duplicates an entire list of certificates.

Parameters
crt_listList to duplicate
Returns
New list copy
void purple_certificate_destroy ( PurpleCertificate crt)

Destroys and free()'s a Certificate.

Parameters
crtInstance 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_listList of certificates to destroy. May be NULL.
void purple_certificate_display_x509 ( PurpleCertificate crt)

Displays a window showing X.509 certificate information.

Parameters
crtCertificate 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
filenameFile to export the certificate to
crtCertificate 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_nameScheme name. Case insensitive.
pool_namePool 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
nameThe 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_nameScheme name. Case insensitive.
ver_nameThe 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
crtCertificate instance
Returns
Binary representation of the hash. You are responsible for freeing this with g_byte_array_free().
See Also
purple_base16_encode_chunked()
purple_certificate_get_fingerprint_sha256()
GByteArray* purple_certificate_get_fingerprint_sha256 ( PurpleCertificate crt,
gboolean  sha1_fallback 
)

Retrieves the certificate public key fingerprint using SHA256.

Parameters
crtCertificate instance
sha1_fallbackIf true, return SHA1 if the SSL module doesn't implement SHA256. Otherwise, return NULL.
Returns
Binary representation of the hash. You are responsible for freeing this with g_byte_array_free().
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
crtCertificate 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
crtCertificate 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
crtCertificate instance
activationReference to store the activation time at. May be NULL if you don't actually want it.
expirationReference 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
crtCertificate 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
schemeScheme to import under
filenameFile 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
poolPool to look in
idID 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
poolPool to remove from
idID 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
idlistID List to destroy
GList* purple_certificate_pool_get_idlist ( PurpleCertificatePool pool)

Get the list of IDs currently in the pool.

Parameters
poolPool 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
poolPool 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
poolCertificatePool to build a path for
idKey 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
poolPool to fish in
idID to look up
Returns
Retrieved certificate (to be freed with purple_certificate_destroy), 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
poolPool to add to
idID to store the certificate with
crtCertificate 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
poolPool 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
poolPool 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
schemePointer 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
vrVerifier 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
crtCertificate instance to check signature of
issuerCertificate 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
poolPool to unregister.
Returns
TRUE if the unregister succeeded, otherwise FALSE
gboolean purple_certificate_unregister_scheme ( PurpleCertificateScheme scheme)

Unregister a CertificateScheme from libpurple.

Parameters
schemeScheme 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
vrVerifier 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
verifierVerification logic to use.
See Also
purple_certificate_find_verifier()
Parameters
subject_nameName that should match the first certificate in the chain for the certificate to be valid. Will be strdup'd into the Request struct
cert_chainCertificate 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.
cbCallback function to be called with whether the certificate was approved or not.
cb_dataUser-defined data for the above.
void purple_certificate_verify_complete ( PurpleCertificateVerificationRequest vrq,
PurpleCertificateVerificationStatus  st 
)

Completes and destroys a VerificationRequest.

Parameters
vrqRequest to conclude
stSuccess/failure code to pass to the request's completion callback.
GSList* purple_certificates_import ( PurpleCertificateScheme scheme,
const gchar *  filename 
)

Imports a list of PurpleCertificates from a file.

Parameters
schemeScheme to import under
filenameFile path to import from
Returns
Pointer to a GSList of new PurpleCertificates, or NULL on failure
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!