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