comparison libpurple/certificate.h @ 32819:2c6510167895 default tip

propagate from branch 'im.pidgin.pidgin.2.x.y' (head 3315c5dfbd0ad16511bdcf865e5b07c02d07df24) to branch 'im.pidgin.pidgin' (head cbd1eda6bcbf0565ae7766396bb8f6f419cb6a9a)

32818:01ff09d4a463

/**
 * @file certificate.h Public-Key Certificate API
 * @ingroup core
 * @see @ref certificate-signals
 * @since 2.2.0
 */

/*
 *
 * purple

#define _PURPLE_CERTIFICATE_H

#include <time.h>

#include <glib.h>

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */


typedef enum
{
	PURPLE_CERTIFICATE_INVALID = 0,
	PURPLE_CERTIFICATE_VALID = 1

	 *  @return           GSList of pointers to the newly allocated Certificate structs
	 *                    or NULL on failure.
	 */
	GSList * (* import_certificates)(const gchar * filename);

	void (*_purple_reserved1)(void);
	void (*_purple_reserved2)(void);
	void (*_purple_reserved3)(void);
};

/** A set of operations used to provide logic for verifying a Certificate's
 *  authenticity.
 *

	/** Function to call with the verification result */
	PurpleCertificateVerifiedCallback cb;
	/** Data to pass to the post-verification callback */
	gpointer cb_data;
};

/*****************************************************************************/
/** @name Certificate Verification Functions                                 */
/*****************************************************************************/
/*@{*/

 *                   in the order certificate, issuer, issuer's issuer, etc.
 * @param 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.
 * @return 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_signature_chain_with_failing(GList *chain,
		PurpleCertificate **failing);

/**
 * 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.
 *
 * @param chain      List of PurpleCertificate instances comprising the chain,
 *                   in the order certificate, issuer, issuer's issuer, etc.
 * @return 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(GList *chain);

/**
 * Imports a PurpleCertificate from a file
 *
 * @param scheme      Scheme to import under

 * @return TRUE if the requested values were obtained, otherwise FALSE.
 */
gboolean
purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration);

/*@}*/

/*****************************************************************************/
/** @name Certificate Pool Functions                                         */
/*****************************************************************************/

/*@}*/


/**
 * Displays a window showing X.509 certificate information
 *
 * @param crt    Certificate under an "x509" Scheme
 * @todo Will break on CA certs, as they have no Common Name
 */
void
purple_certificate_display_x509(PurpleCertificate *crt);

/**
 * Add a search path for certificates.
 *
 * @param path   Path to search for certificates.
 */
void purple_certificate_add_ca_search_path(const char *path);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* _PURPLE_CERTIFICATE_H */

32819:2c6510167895

/**
 * @file certificate.h Public-Key Certificate API
 * @ingroup core
 * @see @ref certificate-signals
 */

/*
 *
 * purple

#define _PURPLE_CERTIFICATE_H

#include <time.h>

#include <glib.h>

typedef enum
{
	PURPLE_CERTIFICATE_INVALID = 0,
	PURPLE_CERTIFICATE_VALID = 1

	 *  @return           GSList of pointers to the newly allocated Certificate structs
	 *                    or NULL on failure.
	 */
	GSList * (* import_certificates)(const gchar * filename);

	/**
	 * Retrieves the certificate data in DER form
	 *
	 * @param crt   Certificate instance
	 * @return Binary DER representation of certificate - must be freed using
	 *         g_byte_array_free()
	 */
	GByteArray * (* get_der_data)(PurpleCertificate *crt);

	/**
	 * Retrieves a string representation of the certificate suitable for display
	 *
	 * @param crt   Certificate instance
	 * @return User-displayable string representation of certificate - must be
	 *         freed using g_free().
	 */
	gchar * (* get_display_string)(PurpleCertificate *crt);

	void (*_purple_reserved1)(void);
};

/** A set of operations used to provide logic for verifying a Certificate's
 *  authenticity.
 *

	/** Function to call with the verification result */
	PurpleCertificateVerifiedCallback cb;
	/** Data to pass to the post-verification callback */
	gpointer cb_data;
};

G_BEGIN_DECLS

/*****************************************************************************/
/** @name Certificate Verification Functions                                 */
/*****************************************************************************/
/*@{*/

 *                   in the order certificate, issuer, issuer's issuer, etc.
 * @param 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.
 * @return TRUE if the chain is valid. See description.
 */
gboolean
purple_certificate_check_signature_chain(GList *chain,
		PurpleCertificate **failing);

/**
 * Imports a PurpleCertificate from a file
 *
 * @param scheme      Scheme to import under

 * @return TRUE if the requested values were obtained, otherwise FALSE.
 */
gboolean
purple_certificate_get_times(PurpleCertificate *crt, time_t *activation, time_t *expiration);

/**
 * Retrieves the certificate data in DER form.
 *
 * @param crt Certificate instance
 *
 * @return Binary DER representation of the certificate - must be freed using
 *         g_byte_array_free().
 */
GByteArray *
purple_certificate_get_der_data(PurpleCertificate *crt);

/**
 * Retrieves a string suitable for displaying a certificate to the user.
 *
 * @param crt Certificate instance
 *
 * @return 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);

/*@}*/

/*****************************************************************************/
/** @name Certificate Pool Functions                                         */
/*****************************************************************************/

/*@}*/


/**
 * Add a search path for certificates.
 *
 * @param path   Path to search for certificates.
 */
void purple_certificate_add_ca_search_path(const char *path);

G_END_DECLS

#endif /* _PURPLE_CERTIFICATE_H */