1.1 --- a/Frameworks/libpurple.framework/Versions/0.6.0/Headers/cipher.h Fri Aug 21 13:24:36 2009 -0700
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,505 +0,0 @@
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 */