Mercurial > pidgin
view libpurple/cipher.h @ 27598:e5fdfff98aa9
When GNU Libidn is available, use it for XMPP stringprep operations.
I made configure fail if libidn is unavailable and force_deps is set
because glib's UTF-8 strdown and casefold operations fail one of the
tests I've updated (based on running the tests with libidn).
Running without libidn will still work in almost every case because people
use all-ASCII JabberIDs and I had to search a fair amount to find
characters for which GLib failed. This shouldn't have a performance impact
on top of Mark's optimizations for all-ASCII JIDs.
author | Paul Aurich <paul@darkrain42.org> |
---|---|
date | Fri, 17 Jul 2009 21:11:25 +0000 |
parents | 584063555949 |
children | 64587c6084e3 |
line wrap: on
line source
/** * @file cipher.h Purple Cipher API * @ingroup core * @see @ref cipher-signals */ /* purple * * Purple is the legal property of its developers, whose names are too numerous * to list here. Please refer to the COPYRIGHT file distributed with this * source distribution. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA */ #ifndef PURPLE_CIPHER_H #define PURPLE_CIPHER_H #include <glib.h> #define PURPLE_CIPHER(obj) ((PurpleCipher *)(obj)) /**< PurpleCipher typecast helper */ #define PURPLE_CIPHER_OPS(obj) ((PurpleCipherOps *)(obj)) /**< PurpleCipherInfo typecase helper */ #define PURPLE_CIPHER_CONTEXT(obj) ((PurpleCipherContext *)(obj)) /**< PurpleCipherContext typecast helper */ typedef struct _PurpleCipher PurpleCipher; /**< A handle to a PurpleCipher */ typedef struct _PurpleCipherOps PurpleCipherOps; /**< Ops for a PurpleCipher */ typedef struct _PurpleCipherContext PurpleCipherContext; /**< A context for a PurpleCipher */ /** * Modes for batch encrypters */ typedef enum _PurpleCipherBatchMode { PURPLE_CIPHER_BATCH_MODE_ECB, PURPLE_CIPHER_BATCH_MODE_CBC } PurpleCipherBatchMode; /** * The operation flags for a cipher */ typedef enum _PurpleCipherCaps { PURPLE_CIPHER_CAPS_SET_OPT = 1 << 1, /**< Set option flag */ PURPLE_CIPHER_CAPS_GET_OPT = 1 << 2, /**< Get option flag */ PURPLE_CIPHER_CAPS_INIT = 1 << 3, /**< Init flag */ PURPLE_CIPHER_CAPS_RESET = 1 << 4, /**< Reset flag */ PURPLE_CIPHER_CAPS_UNINIT = 1 << 5, /**< Uninit flag */ PURPLE_CIPHER_CAPS_SET_IV = 1 << 6, /**< Set IV flag */ PURPLE_CIPHER_CAPS_APPEND = 1 << 7, /**< Append flag */ PURPLE_CIPHER_CAPS_DIGEST = 1 << 8, /**< Digest flag */ PURPLE_CIPHER_CAPS_ENCRYPT = 1 << 9, /**< Encrypt flag */ PURPLE_CIPHER_CAPS_DECRYPT = 1 << 10, /**< Decrypt flag */ PURPLE_CIPHER_CAPS_SET_SALT = 1 << 11, /**< Set salt flag */ PURPLE_CIPHER_CAPS_GET_SALT_SIZE = 1 << 12, /**< Get salt size flag */ PURPLE_CIPHER_CAPS_SET_KEY = 1 << 13, /**< Set key flag */ PURPLE_CIPHER_CAPS_GET_KEY_SIZE = 1 << 14, /**< Get key size flag */ PURPLE_CIPHER_CAPS_SET_BATCH_MODE = 1 << 15, /**< Set batch mode flag */ PURPLE_CIPHER_CAPS_GET_BATCH_MODE = 1 << 16, /**< Get batch mode flag */ PURPLE_CIPHER_CAPS_GET_BLOCK_SIZE = 1 << 17, /**< The get block size flag */ PURPLE_CIPHER_CAPS_SET_KEY_WITH_LEN = 1 << 18, /**< The set key with length flag */ PURPLE_CIPHER_CAPS_UNKNOWN = 1 << 19 /**< Unknown */ } PurpleCipherCaps; /** * The operations of a cipher. Every cipher must implement one of these. */ struct _PurpleCipherOps { /** The set option function */ void (*set_option)(PurpleCipherContext *context, const gchar *name, void *value); /** The get option function */ void *(*get_option)(PurpleCipherContext *context, const gchar *name); /** The init function */ void (*init)(PurpleCipherContext *context, void *extra); /** The reset function */ void (*reset)(PurpleCipherContext *context, void *extra); /** The uninit function */ void (*uninit)(PurpleCipherContext *context); /** The set initialization vector function */ void (*set_iv)(PurpleCipherContext *context, guchar *iv, size_t len); /** The append data function */ void (*append)(PurpleCipherContext *context, const guchar *data, size_t len); /** The digest function */ gboolean (*digest)(PurpleCipherContext *context, size_t in_len, guchar digest[], size_t *out_len); /** The encrypt function */ int (*encrypt)(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen); /** The decrypt function */ int (*decrypt)(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen); /** The set salt function */ void (*set_salt)(PurpleCipherContext *context, guchar *salt); /** The get salt size function */ size_t (*get_salt_size)(PurpleCipherContext *context); /** The set key function */ void (*set_key)(PurpleCipherContext *context, const guchar *key); /** The get key size function */ size_t (*get_key_size)(PurpleCipherContext *context); /** The set batch mode function */ void (*set_batch_mode)(PurpleCipherContext *context, PurpleCipherBatchMode mode); /** The get batch mode function */ PurpleCipherBatchMode (*get_batch_mode)(PurpleCipherContext *context); /** The get block size function */ size_t (*get_block_size)(PurpleCipherContext *context); /** The set key with length function */ void (*set_key_with_len)(PurpleCipherContext *context, const guchar *key, size_t len); }; #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /*****************************************************************************/ /** @name PurpleCipher API */ /*****************************************************************************/ /*@{*/ /** * Gets a cipher's name * * @param cipher The cipher handle * * @return The cipher's name */ const gchar *purple_cipher_get_name(PurpleCipher *cipher); /** * Gets a cipher's capabilities * * @param cipher The cipher handle * * @return The cipher's info */ guint purple_cipher_get_capabilities(PurpleCipher *cipher); /** * Gets a digest from a cipher * * @param name The cipher's name * @param data The data to hash * @param data_len The length of the data * @param in_len The length of the buffer * @param digest The returned digest * @param out_len The length written * * @return @c TRUE if successful, @c FALSE otherwise */ gboolean purple_cipher_digest_region(const gchar *name, const guchar *data, size_t data_len, size_t in_len, guchar digest[], size_t *out_len); /*@}*/ /******************************************************************************/ /** @name PurpleCiphers API */ /******************************************************************************/ /*@{*/ /** * Finds a cipher by it's name * * @param name The name of the cipher to find * * @return The cipher handle or @c NULL */ PurpleCipher *purple_ciphers_find_cipher(const gchar *name); /** * Registers a cipher as a usable cipher * * @param name The name of the new cipher * @param ops The cipher ops to register * * @return The handle to the new cipher or @c NULL if it failed */ PurpleCipher *purple_ciphers_register_cipher(const gchar *name, PurpleCipherOps *ops); /** * Unregisters a cipher * * @param cipher The cipher handle to unregister * * @return Whether or not the cipher was successfully unloaded */ gboolean purple_ciphers_unregister_cipher(PurpleCipher *cipher); /** * Gets the list of ciphers * * @return The list of available ciphers * @note This list should not be modified, it is owned by the cipher core */ GList *purple_ciphers_get_ciphers(void); /*@}*/ /******************************************************************************/ /** @name PurpleCipher Subsystem API */ /******************************************************************************/ /*@{*/ /** * Gets the handle to the cipher subsystem * * @return The handle to the cipher subsystem */ gpointer purple_ciphers_get_handle(void); /** * Initializes the cipher core */ void purple_ciphers_init(void); /** * Uninitializes the cipher core */ void purple_ciphers_uninit(void); /*@}*/ /******************************************************************************/ /** @name PurpleCipherContext API */ /******************************************************************************/ /*@{*/ /** * Sets the value an option on a cipher context * * @param context The cipher context * @param name The name of the option * @param value The value to set */ void purple_cipher_context_set_option(PurpleCipherContext *context, const gchar *name, gpointer value); /** * Gets the vale of an option on a cipher context * * @param context The cipher context * @param name The name of the option * @return The value of the option */ gpointer purple_cipher_context_get_option(PurpleCipherContext *context, const gchar *name); /** * Creates a new cipher context and initializes it * * @param cipher The cipher to use * @param extra Extra data for the specific cipher * * @return The new cipher context */ PurpleCipherContext *purple_cipher_context_new(PurpleCipher *cipher, void *extra); /** * Creates a new cipher context by the cipher name and initializes it * * @param name The cipher's name * @param extra Extra data for the specific cipher * * @return The new cipher context */ PurpleCipherContext *purple_cipher_context_new_by_name(const gchar *name, void *extra); /** * Resets a cipher context to it's default value * @note If you have set an IV you will have to set it after resetting * * @param context The context to reset * @param extra Extra data for the specific cipher */ void purple_cipher_context_reset(PurpleCipherContext *context, gpointer extra); /** * Destorys a cipher context and deinitializes it * * @param context The cipher context to destory */ void purple_cipher_context_destroy(PurpleCipherContext *context); /** * Sets the initialization vector for a context * @note This should only be called right after a cipher context is created or reset * * @param context The context to set the IV to * @param iv The initialization vector to set * @param len The len of the IV */ void purple_cipher_context_set_iv(PurpleCipherContext *context, guchar *iv, size_t len); /** * Appends data to the context * * @param context The context to append data to * @param data The data to append * @param len The length of the data */ void purple_cipher_context_append(PurpleCipherContext *context, const guchar *data, size_t len); /** * Digests a context * * @param context The context to digest * @param in_len The length of the buffer * @param digest The return buffer for the digest * @param out_len The length of the returned value */ gboolean purple_cipher_context_digest(PurpleCipherContext *context, size_t in_len, guchar digest[], size_t *out_len); /** * Converts a guchar digest into a hex string * * @param context The context to get a digest from * @param in_len The length of the buffer * @param digest_s The return buffer for the string digest * @param out_len The length of the returned value */ gboolean purple_cipher_context_digest_to_str(PurpleCipherContext *context, size_t in_len, gchar digest_s[], size_t *out_len); /** * Encrypts data using the context * * @param context The context * @param data The data to encrypt * @param len The length of the data * @param output The output buffer * @param outlen The len of data that was outputed * * @return A cipher specific status code */ gint purple_cipher_context_encrypt(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen); /** * Decrypts data using the context * * @param context The context * @param data The data to encrypt * @param len The length of the returned value * @param output The output buffer * @param outlen The len of data that was outputed * * @return A cipher specific status code */ gint purple_cipher_context_decrypt(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen); /** * Sets the salt on a context * * @param context The context whose salt to set * @param salt The salt */ void purple_cipher_context_set_salt(PurpleCipherContext *context, guchar *salt); /** * Gets the size of the salt if the cipher supports it * * @param context The context whose salt size to get * * @return The size of the salt */ size_t purple_cipher_context_get_salt_size(PurpleCipherContext *context); /** * Sets the key on a context * * @param context The context whose key to set * @param key The key */ void purple_cipher_context_set_key(PurpleCipherContext *context, const guchar *key); /** * Gets the key size for a context * * @param context The context whose key size to get * * @return The size of the key */ size_t purple_cipher_context_get_key_size(PurpleCipherContext *context); /** * Sets the batch mode of a context * * @param context The context whose batch mode to set * @param mode The batch mode under which the cipher should operate * */ void purple_cipher_context_set_batch_mode(PurpleCipherContext *context, PurpleCipherBatchMode mode); /** * Gets the batch mode of a context * * @param context The context whose batch mode to get * * @return The batch mode under which the cipher is operating */ PurpleCipherBatchMode purple_cipher_context_get_batch_mode(PurpleCipherContext *context); /** * Gets the block size of a context * * @param context The context whose block size to get * * @return The block size of the context */ size_t purple_cipher_context_get_block_size(PurpleCipherContext *context); /** * Sets the key with a given length on a context * * @param context The context whose key to set * @param key The key * @param len The length of the key * */ void purple_cipher_context_set_key_with_len(PurpleCipherContext *context, const guchar *key, size_t len); /** * Sets the cipher data for a context * * @param context The context whose cipher data to set * @param data The cipher data to set */ void purple_cipher_context_set_data(PurpleCipherContext *context, gpointer data); /** * Gets the cipher data for a context * * @param context The context whose cipher data to get * * @return The cipher data */ gpointer purple_cipher_context_get_data(PurpleCipherContext *context); /*@}*/ /*****************************************************************************/ /** @name Purple Cipher HTTP Digest Helper Functions */ /*****************************************************************************/ /*@{*/ /** * Calculates a session key for HTTP Digest authentation * * See RFC 2617 for more information. * * @param algorithm The hash algorithm to use * @param username The username provided by the user * @param realm The authentication realm provided by the server * @param password The password provided by the user * @param nonce The nonce provided by the server * @param client_nonce The nonce provided by the client * * @return The session key, or @c NULL if an error occurred. */ gchar *purple_cipher_http_digest_calculate_session_key( const gchar *algorithm, const gchar *username, const gchar *realm, const gchar *password, const gchar *nonce, const gchar *client_nonce); /** Calculate a response for HTTP Digest authentication * * See RFC 2617 for more information. * * @param algorithm The hash algorithm to use * @param method The HTTP method in use * @param digest_uri The URI from the initial request * @param qop The "quality of protection" * @param entity The entity body * @param nonce The nonce provided by the server * @param nonce_count The nonce count * @param client_nonce The nonce provided by the client * @param session_key The session key from purple_cipher_http_digest_calculate_session_key() * * @return The hashed response, or @c NULL if an error occurred. */ gchar *purple_cipher_http_digest_calculate_response( const gchar *algorithm, const gchar *method, const gchar *digest_uri, const gchar *qop, const gchar *entity, const gchar *nonce, const gchar *nonce_count, const gchar *client_nonce, const gchar *session_key); /*@}*/ #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* PURPLE_CIPHER_H */