pidgin 2.14.14dev
|
Public-Key Certificate API. More...
#include <time.h>
#include <glib.h>
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. | |
Functions | |
Certificate Verification Functions <br> | |
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 <br> | |
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. | |
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 <br> | |
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 <br> | |
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. | |
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. | |
Public-Key Certificate API.
Definition in file certificate.h.
#define PURPLE_CERTIFICATE_SCHEME_HAS_FUNC | ( | obj, | |
member | |||
) |
Definition at line 347 of file certificate.h.
typedef struct _PurpleCertificate PurpleCertificate |
Definition at line 94 of file certificate.h.
typedef struct _PurpleCertificatePool PurpleCertificatePool |
Definition at line 95 of file certificate.h.
typedef struct _PurpleCertificateScheme PurpleCertificateScheme |
Definition at line 96 of file certificate.h.
Definition at line 98 of file certificate.h.
typedef void(* PurpleCertificateVerifiedCallback) (PurpleCertificateVerificationStatus st, gpointer userdata) |
Callback function for the results of a verification check.
st | Status code |
userdata | User-defined data |
Definition at line 105 of file certificate.h.
typedef struct _PurpleCertificateVerifier PurpleCertificateVerifier |
Definition at line 97 of file certificate.h.
enum PurpleCertificateInvalidityFlags |
Definition at line 51 of file certificate.h.
enum PurpleCertificateVerificationStatus |
Definition at line 43 of file certificate.h.
void purple_certificate_add_ca_search_path | ( | const char * | path | ) |
Add a search path for certificates.
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.
chain | List of PurpleCertificate instances comprising the chain, in the order certificate, issuer, issuer's issuer, etc. |
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.
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. |
gboolean purple_certificate_check_subject_name | ( | PurpleCertificate * | crt, |
const gchar * | name | ||
) |
Check the subject name against that on the certificate.
crt | Certificate instance |
name | Name to check. |
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.
crt1 | A certificate instance |
crt2 | Another certificate instance |
PurpleCertificate * purple_certificate_copy | ( | PurpleCertificate * | crt | ) |
Makes a duplicate of a certificate.
crt | Instance to duplicate |
GList * purple_certificate_copy_list | ( | GList * | crt_list | ) |
Duplicates an entire list of certificates.
crt_list | List to duplicate |
void purple_certificate_destroy | ( | PurpleCertificate * | crt | ) |
Destroys and free()'s a Certificate.
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.
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.
crt | Certificate under an "x509" Scheme |
gboolean purple_certificate_export | ( | const gchar * | filename, |
PurpleCertificate * | crt | ||
) |
Exports a PurpleCertificate to a file.
filename | File to export the certificate to |
crt | Certificate to export |
PurpleCertificatePool * purple_certificate_find_pool | ( | const gchar * | scheme_name, |
const gchar * | pool_name | ||
) |
Look up a registered PurpleCertificatePool by scheme and name.
scheme_name | Scheme name. Case insensitive. |
pool_name | Pool name. Case insensitive. |
PurpleCertificateScheme * purple_certificate_find_scheme | ( | const gchar * | name | ) |
Look up a registered CertificateScheme by name.
name | The scheme name. Case insensitive. |
PurpleCertificateVerifier * purple_certificate_find_verifier | ( | const gchar * | scheme_name, |
const gchar * | ver_name | ||
) |
Look up a registered PurpleCertificateVerifier by scheme and name.
scheme_name | Scheme name. Case insensitive. |
ver_name | The verifier name. Case insensitive. |
GByteArray * purple_certificate_get_fingerprint_sha1 | ( | PurpleCertificate * | crt | ) |
Retrieves the certificate public key fingerprint using SHA1.
crt | Certificate instance |
GByteArray * purple_certificate_get_fingerprint_sha256 | ( | PurpleCertificate * | crt, |
gboolean | sha1_fallback | ||
) |
Retrieves the certificate public key fingerprint using SHA256.
crt | Certificate instance |
sha1_fallback | If true, return SHA1 if the SSL module doesn't implement SHA256. Otherwise, return NULL. |
gchar * purple_certificate_get_issuer_unique_id | ( | PurpleCertificate * | crt | ) |
Get a unique identifier for the certificate's issuer.
crt | Certificate instance |
GList * purple_certificate_get_pools | ( | void | ) |
Get the list of registered Pools.
GList * purple_certificate_get_schemes | ( | void | ) |
Get all registered CertificateSchemes.
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
crt | Certificate instance |
gboolean purple_certificate_get_times | ( | PurpleCertificate * | crt, |
time_t * | activation, | ||
time_t * | expiration | ||
) |
Get the expiration/activation 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. |
gchar * purple_certificate_get_unique_id | ( | PurpleCertificate * | crt | ) |
Get a unique identifier for the certificate.
crt | Certificate instance |
GList * purple_certificate_get_verifiers | ( | void | ) |
Get the list of registered CertificateVerifiers.
PurpleCertificate * purple_certificate_import | ( | PurpleCertificateScheme * | scheme, |
const gchar * | filename | ||
) |
Imports a PurpleCertificate from a file.
scheme | Scheme to import under |
filename | File path to import from |
gboolean purple_certificate_pool_contains | ( | PurpleCertificatePool * | pool, |
const gchar * | id | ||
) |
Check for presence of an ID in a pool.
pool | Pool to look in |
id | ID to look for |
gboolean purple_certificate_pool_delete | ( | PurpleCertificatePool * | pool, |
const gchar * | id | ||
) |
Remove a certificate from a pool.
pool | Pool to remove from |
id | ID to remove |
void purple_certificate_pool_destroy_idlist | ( | GList * | idlist | ) |
Destroys the result given by purple_certificate_pool_get_idlist()
idlist | ID List to destroy |
GList * purple_certificate_pool_get_idlist | ( | PurpleCertificatePool * | pool | ) |
Get the list of IDs currently in the pool.
pool | Pool to enumerate |
PurpleCertificateScheme * purple_certificate_pool_get_scheme | ( | PurpleCertificatePool * | pool | ) |
Looks up the scheme the pool operates under.
pool | Pool to get the scheme of |
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.
pool | CertificatePool to build a path for |
id | Key to look up a Certificate by. May be NULL. |
PurpleCertificate * purple_certificate_pool_retrieve | ( | PurpleCertificatePool * | pool, |
const gchar * | id | ||
) |
Retrieve a certificate from a pool.
pool | Pool to fish in |
id | ID to look up |
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.
pool | Pool to add to |
id | ID to store the certificate with |
crt | Certificate to store |
gboolean purple_certificate_pool_usable | ( | PurpleCertificatePool * | pool | ) |
Determines whether a pool can be used.
Checks whether the associated CertificateScheme is loaded.
pool | Pool to check |
gboolean purple_certificate_register_pool | ( | PurpleCertificatePool * | pool | ) |
Register a CertificatePool with libpurple and call its init function.
pool | Pool to register. |
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.
scheme | Pointer to the scheme to register. |
gboolean purple_certificate_register_verifier | ( | PurpleCertificateVerifier * | vr | ) |
Register a CertificateVerifier with libpurple.
vr | Verifier to register. |
gboolean purple_certificate_signed_by | ( | PurpleCertificate * | crt, |
PurpleCertificate * | issuer | ||
) |
Check whether 'crt' has a valid signature made by 'issuer'.
crt | Certificate instance to check signature of |
issuer | Certificate thought to have signed 'crt' |
gboolean purple_certificate_unregister_pool | ( | PurpleCertificatePool * | pool | ) |
Unregister a CertificatePool with libpurple and call its uninit function.
pool | Pool to unregister. |
gboolean purple_certificate_unregister_scheme | ( | PurpleCertificateScheme * | scheme | ) |
Unregister a CertificateScheme from libpurple.
scheme | Scheme to unregister. If the scheme is not registered, this is a no-op. |
gboolean purple_certificate_unregister_verifier | ( | PurpleCertificateVerifier * | vr | ) |
Unregister a CertificateVerifier with libpurple.
vr | Verifier to unregister. |
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.
verifier | Verification logic to use. |
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.
vrq | Request to conclude |
st | Success/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.
scheme | Scheme to import under |
filename | File path to import from |