1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/cipher.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,505 @@
1.4 +/**
1.5 + * @file cipher.h Purple Cipher API
1.6 + * @ingroup core
1.7 + * @see @ref cipher-signals
1.8 + */
1.9 +
1.10 +/* purple
1.11 + *
1.12 + * Purple is the legal property of its developers, whose names are too numerous
1.13 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.14 + * source distribution.
1.15 + *
1.16 + * This program is free software; you can redistribute it and/or modify
1.17 + * it under the terms of the GNU General Public License as published by
1.18 + * the Free Software Foundation; either version 2 of the License, or
1.19 + * (at your option) any later version.
1.20 + *
1.21 + * This program is distributed in the hope that it will be useful,
1.22 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.23 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.24 + * GNU General Public License for more details.
1.25 + *
1.26 + * You should have received a copy of the GNU General Public License
1.27 + * along with this program; if not, write to the Free Software
1.28 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.29 + */
1.30 +#ifndef PURPLE_CIPHER_H
1.31 +#define PURPLE_CIPHER_H
1.32 +
1.33 +#include <glib.h>
1.34 +
1.35 +#define PURPLE_CIPHER(obj) ((PurpleCipher *)(obj)) /**< PurpleCipher typecast helper */
1.36 +#define PURPLE_CIPHER_OPS(obj) ((PurpleCipherOps *)(obj)) /**< PurpleCipherInfo typecase helper */
1.37 +#define PURPLE_CIPHER_CONTEXT(obj) ((PurpleCipherContext *)(obj)) /**< PurpleCipherContext typecast helper */
1.38 +
1.39 +typedef struct _PurpleCipher PurpleCipher; /**< A handle to a PurpleCipher */
1.40 +typedef struct _PurpleCipherOps PurpleCipherOps; /**< Ops for a PurpleCipher */
1.41 +typedef struct _PurpleCipherContext PurpleCipherContext; /**< A context for a PurpleCipher */
1.42 +
1.43 +/**
1.44 + * Modes for batch encrypters
1.45 + */
1.46 +typedef enum _PurpleCipherBatchMode {
1.47 + PURPLE_CIPHER_BATCH_MODE_ECB,
1.48 + PURPLE_CIPHER_BATCH_MODE_CBC
1.49 +} PurpleCipherBatchMode;
1.50 +
1.51 +/**
1.52 + * The operation flags for a cipher
1.53 + */
1.54 +typedef enum _PurpleCipherCaps {
1.55 + PURPLE_CIPHER_CAPS_SET_OPT = 1 << 1, /**< Set option flag */
1.56 + PURPLE_CIPHER_CAPS_GET_OPT = 1 << 2, /**< Get option flag */
1.57 + PURPLE_CIPHER_CAPS_INIT = 1 << 3, /**< Init flag */
1.58 + PURPLE_CIPHER_CAPS_RESET = 1 << 4, /**< Reset flag */
1.59 + PURPLE_CIPHER_CAPS_UNINIT = 1 << 5, /**< Uninit flag */
1.60 + PURPLE_CIPHER_CAPS_SET_IV = 1 << 6, /**< Set IV flag */
1.61 + PURPLE_CIPHER_CAPS_APPEND = 1 << 7, /**< Append flag */
1.62 + PURPLE_CIPHER_CAPS_DIGEST = 1 << 8, /**< Digest flag */
1.63 + PURPLE_CIPHER_CAPS_ENCRYPT = 1 << 9, /**< Encrypt flag */
1.64 + PURPLE_CIPHER_CAPS_DECRYPT = 1 << 10, /**< Decrypt flag */
1.65 + PURPLE_CIPHER_CAPS_SET_SALT = 1 << 11, /**< Set salt flag */
1.66 + PURPLE_CIPHER_CAPS_GET_SALT_SIZE = 1 << 12, /**< Get salt size flag */
1.67 + PURPLE_CIPHER_CAPS_SET_KEY = 1 << 13, /**< Set key flag */
1.68 + PURPLE_CIPHER_CAPS_GET_KEY_SIZE = 1 << 14, /**< Get key size flag */
1.69 + PURPLE_CIPHER_CAPS_SET_BATCH_MODE = 1 << 15, /**< Set batch mode flag */
1.70 + PURPLE_CIPHER_CAPS_GET_BATCH_MODE = 1 << 16, /**< Get batch mode flag */
1.71 + PURPLE_CIPHER_CAPS_GET_BLOCK_SIZE = 1 << 17, /**< The get block size flag */
1.72 + PURPLE_CIPHER_CAPS_SET_KEY_WITH_LEN = 1 << 18, /**< The set key with length flag */
1.73 + PURPLE_CIPHER_CAPS_UNKNOWN = 1 << 19 /**< Unknown */
1.74 +} PurpleCipherCaps;
1.75 +
1.76 +/**
1.77 + * The operations of a cipher. Every cipher must implement one of these.
1.78 + */
1.79 +struct _PurpleCipherOps {
1.80 + /** The set option function */
1.81 + void (*set_option)(PurpleCipherContext *context, const gchar *name, void *value);
1.82 +
1.83 + /** The get option function */
1.84 + void *(*get_option)(PurpleCipherContext *context, const gchar *name);
1.85 +
1.86 + /** The init function */
1.87 + void (*init)(PurpleCipherContext *context, void *extra);
1.88 +
1.89 + /** The reset function */
1.90 + void (*reset)(PurpleCipherContext *context, void *extra);
1.91 +
1.92 + /** The uninit function */
1.93 + void (*uninit)(PurpleCipherContext *context);
1.94 +
1.95 + /** The set initialization vector function */
1.96 + void (*set_iv)(PurpleCipherContext *context, guchar *iv, size_t len);
1.97 +
1.98 + /** The append data function */
1.99 + void (*append)(PurpleCipherContext *context, const guchar *data, size_t len);
1.100 +
1.101 + /** The digest function */
1.102 + gboolean (*digest)(PurpleCipherContext *context, size_t in_len, guchar digest[], size_t *out_len);
1.103 +
1.104 + /** The encrypt function */
1.105 + int (*encrypt)(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
1.106 +
1.107 + /** The decrypt function */
1.108 + int (*decrypt)(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
1.109 +
1.110 + /** The set salt function */
1.111 + void (*set_salt)(PurpleCipherContext *context, guchar *salt);
1.112 +
1.113 + /** The get salt size function */
1.114 + size_t (*get_salt_size)(PurpleCipherContext *context);
1.115 +
1.116 + /** The set key function */
1.117 + void (*set_key)(PurpleCipherContext *context, const guchar *key);
1.118 +
1.119 + /** The get key size function */
1.120 + size_t (*get_key_size)(PurpleCipherContext *context);
1.121 +
1.122 + /** The set batch mode function */
1.123 + void (*set_batch_mode)(PurpleCipherContext *context, PurpleCipherBatchMode mode);
1.124 +
1.125 + /** The get batch mode function */
1.126 + PurpleCipherBatchMode (*get_batch_mode)(PurpleCipherContext *context);
1.127 +
1.128 + /** The get block size function */
1.129 + size_t (*get_block_size)(PurpleCipherContext *context);
1.130 +
1.131 + /** The set key with length function */
1.132 + void (*set_key_with_len)(PurpleCipherContext *context, const guchar *key, size_t len);
1.133 +};
1.134 +
1.135 +#ifdef __cplusplus
1.136 +extern "C" {
1.137 +#endif /* __cplusplus */
1.138 +
1.139 +/*****************************************************************************/
1.140 +/** @name PurpleCipher API */
1.141 +/*****************************************************************************/
1.142 +/*@{*/
1.143 +
1.144 +/**
1.145 + * Gets a cipher's name
1.146 + *
1.147 + * @param cipher The cipher handle
1.148 + *
1.149 + * @return The cipher's name
1.150 + */
1.151 +const gchar *purple_cipher_get_name(PurpleCipher *cipher);
1.152 +
1.153 +/**
1.154 + * Gets a cipher's capabilities
1.155 + *
1.156 + * @param cipher The cipher handle
1.157 + *
1.158 + * @return The cipher's info
1.159 + */
1.160 +guint purple_cipher_get_capabilities(PurpleCipher *cipher);
1.161 +
1.162 +/**
1.163 + * Gets a digest from a cipher
1.164 + *
1.165 + * @param name The cipher's name
1.166 + * @param data The data to hash
1.167 + * @param data_len The length of the data
1.168 + * @param in_len The length of the buffer
1.169 + * @param digest The returned digest
1.170 + * @param out_len The length written
1.171 + *
1.172 + * @return @c TRUE if successful, @c FALSE otherwise
1.173 + */
1.174 +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);
1.175 +
1.176 +/*@}*/
1.177 +/******************************************************************************/
1.178 +/** @name PurpleCiphers API */
1.179 +/******************************************************************************/
1.180 +/*@{*/
1.181 +
1.182 +/**
1.183 + * Finds a cipher by it's name
1.184 + *
1.185 + * @param name The name of the cipher to find
1.186 + *
1.187 + * @return The cipher handle or @c NULL
1.188 + */
1.189 +PurpleCipher *purple_ciphers_find_cipher(const gchar *name);
1.190 +
1.191 +/**
1.192 + * Registers a cipher as a usable cipher
1.193 + *
1.194 + * @param name The name of the new cipher
1.195 + * @param ops The cipher ops to register
1.196 + *
1.197 + * @return The handle to the new cipher or @c NULL if it failed
1.198 + */
1.199 +PurpleCipher *purple_ciphers_register_cipher(const gchar *name, PurpleCipherOps *ops);
1.200 +
1.201 +/**
1.202 + * Unregisters a cipher
1.203 + *
1.204 + * @param cipher The cipher handle to unregister
1.205 + *
1.206 + * @return Whether or not the cipher was successfully unloaded
1.207 + */
1.208 +gboolean purple_ciphers_unregister_cipher(PurpleCipher *cipher);
1.209 +
1.210 +/**
1.211 + * Gets the list of ciphers
1.212 + *
1.213 + * @return The list of available ciphers
1.214 + * @note This list should not be modified, it is owned by the cipher core
1.215 + */
1.216 +GList *purple_ciphers_get_ciphers(void);
1.217 +
1.218 +/*@}*/
1.219 +/******************************************************************************/
1.220 +/** @name PurpleCipher Subsystem API */
1.221 +/******************************************************************************/
1.222 +/*@{*/
1.223 +
1.224 +/**
1.225 + * Gets the handle to the cipher subsystem
1.226 + *
1.227 + * @return The handle to the cipher subsystem
1.228 + */
1.229 +gpointer purple_ciphers_get_handle(void);
1.230 +
1.231 +/**
1.232 + * Initializes the cipher core
1.233 + */
1.234 +void purple_ciphers_init(void);
1.235 +
1.236 +/**
1.237 + * Uninitializes the cipher core
1.238 + */
1.239 +void purple_ciphers_uninit(void);
1.240 +
1.241 +/*@}*/
1.242 +/******************************************************************************/
1.243 +/** @name PurpleCipherContext API */
1.244 +/******************************************************************************/
1.245 +/*@{*/
1.246 +
1.247 +/**
1.248 + * Sets the value an option on a cipher context
1.249 + *
1.250 + * @param context The cipher context
1.251 + * @param name The name of the option
1.252 + * @param value The value to set
1.253 + */
1.254 +void purple_cipher_context_set_option(PurpleCipherContext *context, const gchar *name, gpointer value);
1.255 +
1.256 +/**
1.257 + * Gets the vale of an option on a cipher context
1.258 + *
1.259 + * @param context The cipher context
1.260 + * @param name The name of the option
1.261 + * @return The value of the option
1.262 + */
1.263 +gpointer purple_cipher_context_get_option(PurpleCipherContext *context, const gchar *name);
1.264 +
1.265 +/**
1.266 + * Creates a new cipher context and initializes it
1.267 + *
1.268 + * @param cipher The cipher to use
1.269 + * @param extra Extra data for the specific cipher
1.270 + *
1.271 + * @return The new cipher context
1.272 + */
1.273 +PurpleCipherContext *purple_cipher_context_new(PurpleCipher *cipher, void *extra);
1.274 +
1.275 +/**
1.276 + * Creates a new cipher context by the cipher name and initializes it
1.277 + *
1.278 + * @param name The cipher's name
1.279 + * @param extra Extra data for the specific cipher
1.280 + *
1.281 + * @return The new cipher context
1.282 + */
1.283 +PurpleCipherContext *purple_cipher_context_new_by_name(const gchar *name, void *extra);
1.284 +
1.285 +/**
1.286 + * Resets a cipher context to it's default value
1.287 + * @note If you have set an IV you will have to set it after resetting
1.288 + *
1.289 + * @param context The context to reset
1.290 + * @param extra Extra data for the specific cipher
1.291 + */
1.292 +void purple_cipher_context_reset(PurpleCipherContext *context, gpointer extra);
1.293 +
1.294 +/**
1.295 + * Destorys a cipher context and deinitializes it
1.296 + *
1.297 + * @param context The cipher context to destory
1.298 + */
1.299 +void purple_cipher_context_destroy(PurpleCipherContext *context);
1.300 +
1.301 +/**
1.302 + * Sets the initialization vector for a context
1.303 + * @note This should only be called right after a cipher context is created or reset
1.304 + *
1.305 + * @param context The context to set the IV to
1.306 + * @param iv The initialization vector to set
1.307 + * @param len The len of the IV
1.308 + */
1.309 +void purple_cipher_context_set_iv(PurpleCipherContext *context, guchar *iv, size_t len);
1.310 +
1.311 +/**
1.312 + * Appends data to the context
1.313 + *
1.314 + * @param context The context to append data to
1.315 + * @param data The data to append
1.316 + * @param len The length of the data
1.317 + */
1.318 +void purple_cipher_context_append(PurpleCipherContext *context, const guchar *data, size_t len);
1.319 +
1.320 +/**
1.321 + * Digests a context
1.322 + *
1.323 + * @param context The context to digest
1.324 + * @param in_len The length of the buffer
1.325 + * @param digest The return buffer for the digest
1.326 + * @param out_len The length of the returned value
1.327 + */
1.328 +gboolean purple_cipher_context_digest(PurpleCipherContext *context, size_t in_len, guchar digest[], size_t *out_len);
1.329 +
1.330 +/**
1.331 + * Converts a guchar digest into a hex string
1.332 + *
1.333 + * @param context The context to get a digest from
1.334 + * @param in_len The length of the buffer
1.335 + * @param digest_s The return buffer for the string digest
1.336 + * @param out_len The length of the returned value
1.337 + */
1.338 +gboolean purple_cipher_context_digest_to_str(PurpleCipherContext *context, size_t in_len, gchar digest_s[], size_t *out_len);
1.339 +
1.340 +/**
1.341 + * Encrypts data using the context
1.342 + *
1.343 + * @param context The context
1.344 + * @param data The data to encrypt
1.345 + * @param len The length of the data
1.346 + * @param output The output buffer
1.347 + * @param outlen The len of data that was outputed
1.348 + *
1.349 + * @return A cipher specific status code
1.350 + */
1.351 +gint purple_cipher_context_encrypt(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
1.352 +
1.353 +/**
1.354 + * Decrypts data using the context
1.355 + *
1.356 + * @param context The context
1.357 + * @param data The data to encrypt
1.358 + * @param len The length of the returned value
1.359 + * @param output The output buffer
1.360 + * @param outlen The len of data that was outputed
1.361 + *
1.362 + * @return A cipher specific status code
1.363 + */
1.364 +gint purple_cipher_context_decrypt(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
1.365 +
1.366 +/**
1.367 + * Sets the salt on a context
1.368 + *
1.369 + * @param context The context whose salt to set
1.370 + * @param salt The salt
1.371 + */
1.372 +void purple_cipher_context_set_salt(PurpleCipherContext *context, guchar *salt);
1.373 +
1.374 +/**
1.375 + * Gets the size of the salt if the cipher supports it
1.376 + *
1.377 + * @param context The context whose salt size to get
1.378 + *
1.379 + * @return The size of the salt
1.380 + */
1.381 +size_t purple_cipher_context_get_salt_size(PurpleCipherContext *context);
1.382 +
1.383 +/**
1.384 + * Sets the key on a context
1.385 + *
1.386 + * @param context The context whose key to set
1.387 + * @param key The key
1.388 + */
1.389 +void purple_cipher_context_set_key(PurpleCipherContext *context, const guchar *key);
1.390 +
1.391 +/**
1.392 + * Gets the key size for a context
1.393 + *
1.394 + * @param context The context whose key size to get
1.395 + *
1.396 + * @return The size of the key
1.397 + */
1.398 +size_t purple_cipher_context_get_key_size(PurpleCipherContext *context);
1.399 +
1.400 +/**
1.401 + * Sets the batch mode of a context
1.402 + *
1.403 + * @param context The context whose batch mode to set
1.404 + * @param mode The batch mode under which the cipher should operate
1.405 + *
1.406 + */
1.407 +void purple_cipher_context_set_batch_mode(PurpleCipherContext *context, PurpleCipherBatchMode mode);
1.408 +
1.409 +/**
1.410 + * Gets the batch mode of a context
1.411 + *
1.412 + * @param context The context whose batch mode to get
1.413 + *
1.414 + * @return The batch mode under which the cipher is operating
1.415 + */
1.416 +PurpleCipherBatchMode purple_cipher_context_get_batch_mode(PurpleCipherContext *context);
1.417 +
1.418 +/**
1.419 + * Gets the block size of a context
1.420 + *
1.421 + * @param context The context whose block size to get
1.422 + *
1.423 + * @return The block size of the context
1.424 + */
1.425 +size_t purple_cipher_context_get_block_size(PurpleCipherContext *context);
1.426 +
1.427 +/**
1.428 + * Sets the key with a given length on a context
1.429 + *
1.430 + * @param context The context whose key to set
1.431 + * @param key The key
1.432 + * @param len The length of the key
1.433 + *
1.434 + */
1.435 +void purple_cipher_context_set_key_with_len(PurpleCipherContext *context, const guchar *key, size_t len);
1.436 +
1.437 +/**
1.438 + * Sets the cipher data for a context
1.439 + *
1.440 + * @param context The context whose cipher data to set
1.441 + * @param data The cipher data to set
1.442 + */
1.443 +void purple_cipher_context_set_data(PurpleCipherContext *context, gpointer data);
1.444 +
1.445 +/**
1.446 + * Gets the cipher data for a context
1.447 + *
1.448 + * @param context The context whose cipher data to get
1.449 + *
1.450 + * @return The cipher data
1.451 + */
1.452 +gpointer purple_cipher_context_get_data(PurpleCipherContext *context);
1.453 +
1.454 +/*@}*/
1.455 +/*****************************************************************************/
1.456 +/** @name Purple Cipher HTTP Digest Helper Functions */
1.457 +/*****************************************************************************/
1.458 +/*@{*/
1.459 +
1.460 +/**
1.461 + * Calculates a session key for HTTP Digest authentation
1.462 + *
1.463 + * See RFC 2617 for more information.
1.464 + *
1.465 + * @param algorithm The hash algorithm to use
1.466 + * @param username The username provided by the user
1.467 + * @param realm The authentication realm provided by the server
1.468 + * @param password The password provided by the user
1.469 + * @param nonce The nonce provided by the server
1.470 + * @param client_nonce The nonce provided by the client
1.471 + *
1.472 + * @return The session key, or @c NULL if an error occurred.
1.473 + */
1.474 +gchar *purple_cipher_http_digest_calculate_session_key(
1.475 + const gchar *algorithm, const gchar *username,
1.476 + const gchar *realm, const gchar *password,
1.477 + const gchar *nonce, const gchar *client_nonce);
1.478 +
1.479 +/** Calculate a response for HTTP Digest authentication
1.480 + *
1.481 + * See RFC 2617 for more information.
1.482 + *
1.483 + * @param algorithm The hash algorithm to use
1.484 + * @param method The HTTP method in use
1.485 + * @param digest_uri The URI from the initial request
1.486 + * @param qop The "quality of protection"
1.487 + * @param entity The entity body
1.488 + * @param nonce The nonce provided by the server
1.489 + * @param nonce_count The nonce count
1.490 + * @param client_nonce The nonce provided by the client
1.491 + * @param session_key The session key from purple_cipher_http_digest_calculate_session_key()
1.492 + *
1.493 + * @return The hashed response, or @c NULL if an error occurred.
1.494 + */
1.495 +gchar *purple_cipher_http_digest_calculate_response(
1.496 + const gchar *algorithm, const gchar *method,
1.497 + const gchar *digest_uri, const gchar *qop,
1.498 + const gchar *entity, const gchar *nonce,
1.499 + const gchar *nonce_count, const gchar *client_nonce,
1.500 + const gchar *session_key);
1.501 +
1.502 +/*@}*/
1.503 +
1.504 +#ifdef __cplusplus
1.505 +}
1.506 +#endif /* __cplusplus */
1.507 +
1.508 +#endif /* PURPLE_CIPHER_H */