libpurple/cipher.h

   1 /**
   2  * @file cipher.h Purple Cipher API
   3  * @ingroup core
   4  * @see @ref cipher-signals
   5  */
   6
   7 /* purple
   8  *
   9  * Purple is the legal property of its developers, whose names are too numerous
  10  * to list here.  Please refer to the COPYRIGHT file distributed with this
  11  * source distribution.
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with this program; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  26  */
  27 #ifndef PURPLE_CIPHER_H
  28 #define PURPLE_CIPHER_H
  29
  30 #include <glib.h>
  31 #include <string.h>
  32
  33 #define PURPLE_CIPHER(obj)                      ((PurpleCipher *)(obj))                 /**< PurpleCipher typecast helper                       */
  34 #define PURPLE_CIPHER_OPS(obj)          ((PurpleCipherOps *)(obj))              /**< PurpleCipherInfo typecase helper           */
  35 #define PURPLE_CIPHER_CONTEXT(obj)      ((PurpleCipherContext *)(obj))  /**< PurpleCipherContext typecast helper        */
  36
  37 typedef struct _PurpleCipher                    PurpleCipher;                   /**< A handle to a PurpleCipher */
  38 typedef struct _PurpleCipherOps         PurpleCipherOps;                /**< Ops for a PurpleCipher             */
  39 typedef struct _PurpleCipherContext     PurpleCipherContext;    /**< A context for a PurpleCipher       */
  40
  41 /**
  42  * Modes for batch encrypters
  43  */
  44 typedef enum _PurpleCipherBatchMode {
  45         PURPLE_CIPHER_BATCH_MODE_ECB,
  46         PURPLE_CIPHER_BATCH_MODE_CBC
  47 } PurpleCipherBatchMode;
  48
  49 /**
  50  * The operation flags for a cipher
  51  */
  52 typedef enum _PurpleCipherCaps {
  53         PURPLE_CIPHER_CAPS_SET_OPT          = 1 << 1,   /**< Set option flag    */
  54         PURPLE_CIPHER_CAPS_GET_OPT          = 1 << 2,   /**< Get option flag    */
  55         PURPLE_CIPHER_CAPS_INIT             = 1 << 3,   /**< Init flag                  */
  56         PURPLE_CIPHER_CAPS_RESET            = 1 << 4,   /**< Reset flag                 */
  57         PURPLE_CIPHER_CAPS_UNINIT           = 1 << 5,   /**< Uninit flag                */
  58         PURPLE_CIPHER_CAPS_SET_IV           = 1 << 6,   /**< Set IV flag                */
  59         PURPLE_CIPHER_CAPS_APPEND           = 1 << 7,   /**< Append flag                */
  60         PURPLE_CIPHER_CAPS_DIGEST           = 1 << 8,   /**< Digest flag                */
  61         PURPLE_CIPHER_CAPS_ENCRYPT          = 1 << 9,   /**< Encrypt flag               */
  62         PURPLE_CIPHER_CAPS_DECRYPT          = 1 << 10,  /**< Decrypt flag               */
  63         PURPLE_CIPHER_CAPS_SET_SALT         = 1 << 11,  /**< Set salt flag              */
  64         PURPLE_CIPHER_CAPS_GET_SALT_SIZE    = 1 << 12,  /**< Get salt size flag */
  65         PURPLE_CIPHER_CAPS_SET_KEY          = 1 << 13,  /**< Set key flag               */
  66         PURPLE_CIPHER_CAPS_GET_KEY_SIZE     = 1 << 14,  /**< Get key size flag  */
  67         PURPLE_CIPHER_CAPS_SET_BATCH_MODE   = 1 << 15,  /**< Set batch mode flag */
  68         PURPLE_CIPHER_CAPS_GET_BATCH_MODE   = 1 << 16,  /**< Get batch mode flag */
  69         PURPLE_CIPHER_CAPS_GET_BLOCK_SIZE   = 1 << 17,  /**< The get block size flag */
  70         PURPLE_CIPHER_CAPS_SET_KEY_WITH_LEN = 1 << 18,  /**< The set key with length flag */
  71         PURPLE_CIPHER_CAPS_UNKNOWN          = 1 << 19   /**< Unknown                    */
  72 } PurpleCipherCaps;
  73
  74 /**
  75  * The operations of a cipher.  Every cipher must implement one of these.
  76  */
  77 struct _PurpleCipherOps {
  78         /** The set option function     */
  79         void (*set_option)(PurpleCipherContext *context, const gchar *name, void *value);
  80
  81         /** The get option function */
  82         void *(*get_option)(PurpleCipherContext *context, const gchar *name);
  83
  84         /** The init function */
  85         void (*init)(PurpleCipherContext *context, void *extra);
  86
  87         /** The reset function */
  88         void (*reset)(PurpleCipherContext *context, void *extra);
  89
  90         /** The uninit function */
  91         void (*uninit)(PurpleCipherContext *context);
  92
  93         /** The set initialization vector function */
  94         void (*set_iv)(PurpleCipherContext *context, guchar *iv, size_t len);
  95
  96         /** The append data function */
  97         void (*append)(PurpleCipherContext *context, const guchar *data, size_t len);
  98
  99         /** The digest function */
 100         gboolean (*digest)(PurpleCipherContext *context, size_t in_len, guchar digest[], size_t *out_len);
 101
 102         /** The encrypt function */
 103         int (*encrypt)(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
 104
 105         /** The decrypt function */
 106         int (*decrypt)(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
 107
 108         /** The set salt function */
 109         void (*set_salt)(PurpleCipherContext *context, guchar *salt);
 110
 111         /** The get salt size function */
 112         size_t (*get_salt_size)(PurpleCipherContext *context);
 113
 114         /** The set key function */
 115         void (*set_key)(PurpleCipherContext *context, const guchar *key);
 116
 117         /** The get key size function */
 118         size_t (*get_key_size)(PurpleCipherContext *context);
 119
 120         /** The set batch mode function */
 121         void (*set_batch_mode)(PurpleCipherContext *context, PurpleCipherBatchMode mode);
 122
 123         /** The get batch mode function */
 124         PurpleCipherBatchMode (*get_batch_mode)(PurpleCipherContext *context);
 125
 126         /** The get block size function */
 127         size_t (*get_block_size)(PurpleCipherContext *context);
 128
 129         /** The set key with length function */
 130         void (*set_key_with_len)(PurpleCipherContext *context, const guchar *key, size_t len);
 131 };
 132
 133 G_BEGIN_DECLS
 134
 135 /*****************************************************************************/
 136 /** @name PurpleCipher API                                                                                                       */
 137 /*****************************************************************************/
 138 /*@{*/
 139
 140 /**
 141  * Gets a cipher's name
 142  *
 143  * @param cipher The cipher handle
 144  *
 145  * @return The cipher's name
 146  */
 147 const gchar *purple_cipher_get_name(PurpleCipher *cipher);
 148
 149 /**
 150  * Gets a cipher's capabilities
 151  *
 152  * @param cipher The cipher handle
 153  *
 154  * @return The cipher's info
 155  */
 156 guint purple_cipher_get_capabilities(PurpleCipher *cipher);
 157
 158 /**
 159  * Gets a digest from a cipher
 160  *
 161  * @param name     The cipher's name
 162  * @param data     The data to hash
 163  * @param data_len The length of the data
 164  * @param in_len   The length of the buffer
 165  * @param digest   The returned digest
 166  * @param out_len  The length written
 167  *
 168  * @return @c TRUE if successful, @c FALSE otherwise
 169  */
 170 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);
 171
 172 /*@}*/
 173 /******************************************************************************/
 174 /** @name PurpleCiphers API                                                                                                       */
 175 /******************************************************************************/
 176 /*@{*/
 177
 178 /**
 179  * Finds a cipher by it's name
 180  *
 181  * @param name The name of the cipher to find
 182  *
 183  * @return The cipher handle or @c NULL
 184  */
 185 PurpleCipher *purple_ciphers_find_cipher(const gchar *name);
 186
 187 /**
 188  * Registers a cipher as a usable cipher
 189  *
 190  * @param name The name of the new cipher
 191  * @param ops  The cipher ops to register
 192  *
 193  * @return The handle to the new cipher or @c NULL if it failed
 194  */
 195 PurpleCipher *purple_ciphers_register_cipher(const gchar *name, PurpleCipherOps *ops);
 196
 197 /**
 198  * Unregisters a cipher
 199  *
 200  * @param cipher The cipher handle to unregister
 201  *
 202  * @return Whether or not the cipher was successfully unloaded
 203  */
 204 gboolean purple_ciphers_unregister_cipher(PurpleCipher *cipher);
 205
 206 /**
 207  * Gets the list of ciphers
 208  *
 209  * @return The list of available ciphers
 210  * @note This list should not be modified, it is owned by the cipher core
 211  */
 212 GList *purple_ciphers_get_ciphers(void);
 213
 214 /*@}*/
 215 /******************************************************************************/
 216 /** @name PurpleCipher Subsystem API                                                                                      */
 217 /******************************************************************************/
 218 /*@{*/
 219
 220 /**
 221  * Gets the handle to the cipher subsystem
 222  *
 223  * @return The handle to the cipher subsystem
 224  */
 225 gpointer purple_ciphers_get_handle(void);
 226
 227 /**
 228  * Initializes the cipher core
 229  */
 230 void purple_ciphers_init(void);
 231
 232 /**
 233  * Uninitializes the cipher core
 234  */
 235 void purple_ciphers_uninit(void);
 236
 237 /*@}*/
 238 /******************************************************************************/
 239 /** @name PurpleCipherContext API                                                                                                 */
 240 /******************************************************************************/
 241 /*@{*/
 242
 243 /**
 244  * Sets the value an option on a cipher context
 245  *
 246  * @param context The cipher context
 247  * @param name    The name of the option
 248  * @param value   The value to set
 249  */
 250 void purple_cipher_context_set_option(PurpleCipherContext *context, const gchar *name, gpointer value);
 251
 252 /**
 253  * Gets the vale of an option on a cipher context
 254  *
 255  * @param context The cipher context
 256  * @param name    The name of the option
 257  * @return The value of the option
 258  */
 259 gpointer purple_cipher_context_get_option(PurpleCipherContext *context, const gchar *name);
 260
 261 /**
 262  * Creates a new cipher context and initializes it
 263  *
 264  * @param cipher The cipher to use
 265  * @param extra  Extra data for the specific cipher
 266  *
 267  * @return The new cipher context
 268  */
 269 PurpleCipherContext *purple_cipher_context_new(PurpleCipher *cipher, void *extra);
 270
 271 /**
 272  * Creates a new cipher context by the cipher name and initializes it
 273  *
 274  * @param name  The cipher's name
 275  * @param extra Extra data for the specific cipher
 276  *
 277  * @return The new cipher context
 278  */
 279 PurpleCipherContext *purple_cipher_context_new_by_name(const gchar *name, void *extra);
 280
 281 /**
 282  * Resets a cipher context to it's default value
 283  * @note If you have set an IV you will have to set it after resetting
 284  *
 285  * @param context The context to reset
 286  * @param extra   Extra data for the specific cipher
 287  */
 288 void purple_cipher_context_reset(PurpleCipherContext *context, gpointer extra);
 289
 290 /**
 291  * Destorys a cipher context and deinitializes it
 292  *
 293  * @param context The cipher context to destory
 294  */
 295 void purple_cipher_context_destroy(PurpleCipherContext *context);
 296
 297 /**
 298  * Sets the initialization vector for a context
 299  * @note This should only be called right after a cipher context is created or reset
 300  *
 301  * @param context The context to set the IV to
 302  * @param iv      The initialization vector to set
 303  * @param len     The len of the IV
 304  */
 305 void purple_cipher_context_set_iv(PurpleCipherContext *context, guchar *iv, size_t len);
 306
 307 /**
 308  * Appends data to the context
 309  *
 310  * @param context The context to append data to
 311  * @param data    The data to append
 312  * @param len     The length of the data
 313  */
 314 void purple_cipher_context_append(PurpleCipherContext *context, const guchar *data, size_t len);
 315
 316 /**
 317  * Digests a context
 318  *
 319  * @param context The context to digest
 320  * @param in_len  The length of the buffer
 321  * @param digest  The return buffer for the digest
 322  * @param out_len The length of the returned value
 323  */
 324 gboolean purple_cipher_context_digest(PurpleCipherContext *context, size_t in_len, guchar digest[], size_t *out_len);
 325
 326 /**
 327  * Converts a guchar digest into a hex string
 328  *
 329  * @param context  The context to get a digest from
 330  * @param in_len   The length of the buffer
 331  * @param digest_s The return buffer for the string digest
 332  * @param out_len  The length of the returned value
 333  */
 334 gboolean purple_cipher_context_digest_to_str(PurpleCipherContext *context, size_t in_len, gchar digest_s[], size_t *out_len);
 335
 336 /**
 337  * Encrypts data using the context
 338  *
 339  * @param context The context
 340  * @param data    The data to encrypt
 341  * @param len     The length of the data
 342  * @param output  The output buffer
 343  * @param outlen  The len of data that was outputed
 344  *
 345  * @return A cipher specific status code
 346  */
 347 gint purple_cipher_context_encrypt(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
 348
 349 /**
 350  * Decrypts data using the context
 351  *
 352  * @param context The context
 353  * @param data    The data to encrypt
 354  * @param len     The length of the returned value
 355  * @param output  The output buffer
 356  * @param outlen  The len of data that was outputed
 357  *
 358  * @return A cipher specific status code
 359  */
 360 gint purple_cipher_context_decrypt(PurpleCipherContext *context, const guchar data[], size_t len, guchar output[], size_t *outlen);
 361
 362 /**
 363  * Sets the salt on a context
 364  *
 365  * @param context The context whose salt to set
 366  * @param salt    The salt
 367  */
 368 void purple_cipher_context_set_salt(PurpleCipherContext *context, guchar *salt);
 369
 370 /**
 371  * Gets the size of the salt if the cipher supports it
 372  *
 373  * @param context The context whose salt size to get
 374  *
 375  * @return The size of the salt
 376  */
 377 size_t purple_cipher_context_get_salt_size(PurpleCipherContext *context);
 378
 379 /**
 380  * Sets the key on a context
 381  *
 382  * @param context The context whose key to set
 383  * @param key     The key
 384  */
 385 void purple_cipher_context_set_key(PurpleCipherContext *context, const guchar *key);
 386
 387 /**
 388  * Gets the key size for a context
 389  *
 390  * @param context The context whose key size to get
 391  *
 392  * @return The size of the key
 393  */
 394 size_t purple_cipher_context_get_key_size(PurpleCipherContext *context);
 395
 396 /**
 397  * Sets the batch mode of a context
 398  *
 399  * @param context The context whose batch mode to set
 400  * @param mode    The batch mode under which the cipher should operate
 401  *
 402  */
 403 void purple_cipher_context_set_batch_mode(PurpleCipherContext *context, PurpleCipherBatchMode mode);
 404
 405 /**
 406  * Gets the batch mode of a context
 407  *
 408  * @param context The context whose batch mode to get
 409  *
 410  * @return The batch mode under which the cipher is operating
 411  */
 412 PurpleCipherBatchMode purple_cipher_context_get_batch_mode(PurpleCipherContext *context);
 413
 414 /**
 415  * Gets the block size of a context
 416  *
 417  * @param context The context whose block size to get
 418  *
 419  * @return The block size of the context
 420  */
 421 size_t purple_cipher_context_get_block_size(PurpleCipherContext *context);
 422
 423 /**
 424  * Sets the key with a given length on a context
 425  *
 426  * @param context The context whose key to set
 427  * @param key     The key
 428  * @param len     The length of the key
 429  *
 430  */
 431 void purple_cipher_context_set_key_with_len(PurpleCipherContext *context, const guchar *key, size_t len);
 432
 433 /**
 434  * Sets the cipher data for a context
 435  *
 436  * @param context The context whose cipher data to set
 437  * @param data    The cipher data to set
 438  */
 439 void purple_cipher_context_set_data(PurpleCipherContext *context, gpointer data);
 440
 441 /**
 442  * Gets the cipher data for a context
 443  *
 444  * @param context The context whose cipher data to get
 445  *
 446  * @return The cipher data
 447  */
 448 gpointer purple_cipher_context_get_data(PurpleCipherContext *context);
 449
 450 /*@}*/
 451 /*****************************************************************************/
 452 /** @name Purple Cipher HTTP Digest Helper Functions                                                     */
 453 /*****************************************************************************/
 454 /*@{*/
 455
 456 /**
 457  * Calculates a session key for HTTP Digest authentation
 458  *
 459  * See RFC 2617 for more information.
 460  *
 461  * @param algorithm    The hash algorithm to use
 462  * @param username     The username provided by the user
 463  * @param realm        The authentication realm provided by the server
 464  * @param password     The password provided by the user
 465  * @param nonce        The nonce provided by the server
 466  * @param client_nonce The nonce provided by the client
 467  *
 468  * @return The session key, or @c NULL if an error occurred.
 469  */
 470 gchar *purple_cipher_http_digest_calculate_session_key(
 471                 const gchar *algorithm, const gchar *username,
 472                 const gchar *realm, const gchar *password,
 473                 const gchar *nonce, const gchar *client_nonce);
 474
 475 /** Calculate a response for HTTP Digest authentication
 476  *
 477  * See RFC 2617 for more information.
 478  *
 479  * @param algorithm         The hash algorithm to use
 480  * @param method            The HTTP method in use
 481  * @param digest_uri        The URI from the initial request
 482  * @param qop               The "quality of protection"
 483  * @param entity            The entity body
 484  * @param nonce             The nonce provided by the server
 485  * @param nonce_count       The nonce count
 486  * @param client_nonce      The nonce provided by the client
 487  * @param session_key       The session key from purple_cipher_http_digest_calculate_session_key()
 488  *
 489  * @return The hashed response, or @c NULL if an error occurred.
 490  */
 491 gchar *purple_cipher_http_digest_calculate_response(
 492                 const gchar *algorithm, const gchar *method,
 493                 const gchar *digest_uri, const gchar *qop,
 494                 const gchar *entity, const gchar *nonce,
 495                 const gchar *nonce_count, const gchar *client_nonce,
 496                 const gchar *session_key);
 497
 498 /*@}*/
 499
 500 G_END_DECLS
 501
 502 #endif /* PURPLE_CIPHER_H */