libpurple/cipher.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_CIPHER_H
  23 #define PURPLE_CIPHER_H
  24 /**
  25  * SECTION:cipher
  26  * @section_id: libpurple-cipher
  27  * @short_description: <filename>cipher.h</filename>
  28  * @title: Cipher and Hash API
  29  */
  30
  31 #include <glib.h>
  32 #include <glib-object.h>
  33 #include <string.h>
  34
  35 #define PURPLE_TYPE_CIPHER                              (purple_cipher_get_type())
  36 #define PURPLE_CIPHER(obj)                              (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_CIPHER, PurpleCipher))
  37 #define PURPLE_CIPHER_CLASS(klass)              (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_CIPHER, PurpleCipherClass))
  38 #define PURPLE_IS_CIPHER(obj)                   (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_CIPHER))
  39 #define PURPLE_IS_CIPHER_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_CIPHER))
  40 #define PURPLE_CIPHER_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_CIPHER, PurpleCipherClass))
  41
  42 typedef struct _PurpleCipher       PurpleCipher;
  43 typedef struct _PurpleCipherClass  PurpleCipherClass;
  44
  45 #define PURPLE_TYPE_HASH                                (purple_hash_get_type())
  46 #define PURPLE_HASH(obj)                                (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_HASH, PurpleHash))
  47 #define PURPLE_HASH_CLASS(klass)                (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_HASH, PurpleHashClass))
  48 #define PURPLE_IS_HASH(obj)                             (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_HASH))
  49 #define PURPLE_IS_HASH_CLASS(klass)             (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_HASH))
  50 #define PURPLE_HASH_GET_CLASS(obj)              (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_HASH, PurpleHashClass))
  51
  52 typedef struct _PurpleHash       PurpleHash;
  53 typedef struct _PurpleHashClass  PurpleHashClass;
  54
  55 /**
  56  * PurpleCipherBatchMode:
  57  * @PURPLE_CIPHER_BATCH_MODE_ECB: Electronic Codebook Mode
  58  * @PURPLE_CIPHER_BATCH_MODE_CBC: Cipher Block Chaining Mode
  59  *
  60  * Modes for batch encrypters
  61  */
  62 typedef enum {
  63         PURPLE_CIPHER_BATCH_MODE_ECB,
  64         PURPLE_CIPHER_BATCH_MODE_CBC
  65 } PurpleCipherBatchMode;
  66
  67 /**
  68  * PurpleCipher:
  69  *
  70  * Purple Cipher is an opaque data structure and should not be used directly.
  71  */
  72 struct _PurpleCipher {
  73         GObject gparent;
  74 };
  75
  76 struct _PurpleCipherClass {
  77         GObjectClass parent_class;
  78
  79         /** The reset function */
  80         void (*reset)(PurpleCipher *cipher);
  81
  82         /** The reset state function */
  83         void (*reset_state)(PurpleCipher *cipher);
  84
  85         /** The set initialization vector function */
  86         void (*set_iv)(PurpleCipher *cipher, guchar *iv, size_t len);
  87
  88         /** The append data function */
  89         void (*append)(PurpleCipher *cipher, const guchar *data, size_t len);
  90
  91         /** The digest function */
  92         gboolean (*digest)(PurpleCipher *cipher, guchar digest[], size_t len);
  93
  94         /** The get digest size function */
  95         size_t (*get_digest_size)(PurpleCipher *cipher);
  96
  97         /** The encrypt function */
  98         ssize_t (*encrypt)(PurpleCipher *cipher, const guchar input[], size_t in_len, guchar output[], size_t out_size);
  99
 100         /** The decrypt function */
 101         ssize_t (*decrypt)(PurpleCipher *cipher, const guchar input[], size_t in_len, guchar output[], size_t out_size);
 102
 103         /** The set salt function */
 104         void (*set_salt)(PurpleCipher *cipher, const guchar *salt, size_t len);
 105
 106         /** The set key function */
 107         void (*set_key)(PurpleCipher *cipher, const guchar *key, size_t len);
 108
 109         /** The get key size function */
 110         size_t (*get_key_size)(PurpleCipher *cipher);
 111
 112         /** The set batch mode function */
 113         void (*set_batch_mode)(PurpleCipher *cipher, PurpleCipherBatchMode mode);
 114
 115         /** The get batch mode function */
 116         PurpleCipherBatchMode (*get_batch_mode)(PurpleCipher *cipher);
 117
 118         /** The get block size function */
 119         size_t (*get_block_size)(PurpleCipher *cipher);
 120
 121         /*< private >*/
 122         void (*_purple_reserved1)(void);
 123         void (*_purple_reserved2)(void);
 124         void (*_purple_reserved3)(void);
 125         void (*_purple_reserved4)(void);
 126 };
 127
 128 /**
 129  * PurpleHash:
 130  *
 131  * Purple Hash is an opaque data structure and should not be used directly.
 132  */
 133 struct _PurpleHash {
 134         GObject gparent;
 135 };
 136
 137 struct _PurpleHashClass {
 138         GObjectClass parent_class;
 139
 140         /** The reset function */
 141         void (*reset)(PurpleHash *hash);
 142
 143         /** The reset state function */
 144         void (*reset_state)(PurpleHash *hash);
 145
 146         /** The append data function */
 147         void (*append)(PurpleHash *hash, const guchar *data, size_t len);
 148
 149         /** The digest function */
 150         gboolean (*digest)(PurpleHash *hash, guchar digest[], size_t len);
 151
 152         /** The get digest size function */
 153         size_t (*get_digest_size)(PurpleHash *hash);
 154
 155         /** The get block size function */
 156         size_t (*get_block_size)(PurpleHash *hash);
 157
 158         /*< private >*/
 159         void (*_purple_reserved1)(void);
 160         void (*_purple_reserved2)(void);
 161         void (*_purple_reserved3)(void);
 162         void (*_purple_reserved4)(void);
 163 };
 164
 165 G_BEGIN_DECLS
 166
 167 /*****************************************************************************/
 168 /* PurpleCipher API                                                          */
 169 /*****************************************************************************/
 170
 171 /**
 172  * purple_cipher_get_type:
 173  *
 174  * Returns: The #GType for the Cipher object.
 175  */
 176 GType purple_cipher_get_type(void);
 177
 178 /**
 179  * purple_cipher_reset:
 180  * @cipher:  The cipher
 181  *
 182  * Resets a cipher to it's default value
 183  * Note: If you have set an IV you will have to set it after resetting
 184  */
 185 void purple_cipher_reset(PurpleCipher *cipher);
 186
 187 /**
 188  * purple_cipher_reset_state:
 189  * @cipher:  The cipher
 190  *
 191  * Resets a cipher state to it's default value, but doesn't touch stateless
 192  * configuration.
 193  *
 194  * That means, IV and digest will be wiped out, but keys, ops or salt
 195  * will remain untouched.
 196  */
 197 void purple_cipher_reset_state(PurpleCipher *cipher);
 198
 199 /**
 200  * purple_cipher_set_iv:
 201  * @cipher:  The cipher
 202  * @iv:      The initialization vector to set
 203  * @len:     The len of the IV
 204  *
 205  * Sets the initialization vector for a cipher
 206  * Note: This should only be called right after a cipher is created or reset
 207  */
 208 void purple_cipher_set_iv(PurpleCipher *cipher, guchar *iv, size_t len);
 209
 210 /**
 211  * purple_cipher_append:
 212  * @cipher:  The cipher
 213  * @data:    The data to append
 214  * @len:     The length of the data
 215  *
 216  * Appends data to the cipher context
 217  */
 218 void purple_cipher_append(PurpleCipher *cipher, const guchar *data, size_t len);
 219
 220 /**
 221  * purple_cipher_digest:
 222  * @cipher:  The cipher
 223  * @digest:  The return buffer for the digest
 224  * @len:     The length of the buffer
 225  *
 226  * Digests a cipher context
 227  */
 228 gboolean purple_cipher_digest(PurpleCipher *cipher, guchar digest[], size_t len);
 229
 230 /**
 231  * purple_cipher_digest_to_str:
 232  * @cipher:   The cipher
 233  * @digest_s: The return buffer for the string digest
 234  * @len:      The length of the buffer
 235  *
 236  * Converts a guchar digest into a hex string
 237  */
 238 gboolean purple_cipher_digest_to_str(PurpleCipher *cipher, gchar digest_s[], size_t len);
 239
 240 /**
 241  * purple_cipher_get_digest_size:
 242  * @cipher: The cipher whose digest size to get
 243  *
 244  * Gets the digest size of a cipher
 245  *
 246  * Returns: The digest size of the cipher
 247  */
 248 size_t purple_cipher_get_digest_size(PurpleCipher *cipher);
 249
 250 /**
 251  * purple_cipher_encrypt:
 252  * @cipher:   The cipher
 253  * @input:    The data to encrypt
 254  * @in_len:   The length of the data
 255  * @output:   The output buffer
 256  * @out_size: The size of the output buffer
 257  *
 258  * Encrypts data using the cipher
 259  *
 260  * Returns: A length of data that was outputed or -1, if failed
 261  */
 262 ssize_t purple_cipher_encrypt(PurpleCipher *cipher, const guchar input[], size_t in_len, guchar output[], size_t out_size);
 263
 264 /**
 265  * purple_cipher_decrypt:
 266  * @cipher:   The cipher
 267  * @input:    The data to encrypt
 268  * @in_len:   The length of the returned value
 269  * @output:   The output buffer
 270  * @out_size: The size of the output buffer
 271  *
 272  * Decrypts data using the cipher
 273  *
 274  * Returns: A length of data that was outputed or -1, if failed
 275  */
 276 ssize_t purple_cipher_decrypt(PurpleCipher *cipher, const guchar input[], size_t in_len, guchar output[], size_t out_size);
 277
 278 /**
 279  * purple_cipher_set_salt:
 280  * @cipher:  The cipher whose salt to set
 281  * @salt:    The salt
 282  * @len:     The length of the salt
 283  *
 284  * Sets the salt on a cipher
 285  */
 286 void purple_cipher_set_salt(PurpleCipher *cipher, const guchar *salt, size_t len);
 287
 288 /**
 289  * purple_cipher_set_key:
 290  * @cipher:  The cipher whose key to set
 291  * @key:     The key
 292  * @len:     The size of the key
 293  *
 294  * Sets the key on a cipher
 295  */
 296 void purple_cipher_set_key(PurpleCipher *cipher, const guchar *key, size_t len);
 297
 298 /**
 299  * purple_cipher_get_key_size:
 300  * @cipher: The cipher whose key size to get
 301  *
 302  * Gets the size of the key if the cipher supports it
 303  *
 304  * Returns: The size of the key
 305  */
 306 size_t purple_cipher_get_key_size(PurpleCipher *cipher);
 307
 308 /**
 309  * purple_cipher_set_batch_mode:
 310  * @cipher:  The cipher whose batch mode to set
 311  * @mode:    The batch mode under which the cipher should operate
 312  *
 313  * Sets the batch mode of a cipher
 314  */
 315 void purple_cipher_set_batch_mode(PurpleCipher *cipher, PurpleCipherBatchMode mode);
 316
 317 /**
 318  * purple_cipher_get_batch_mode:
 319  * @cipher: The cipher whose batch mode to get
 320  *
 321  * Gets the batch mode of a cipher
 322  *
 323  * Returns: The batch mode under which the cipher is operating
 324  */
 325 PurpleCipherBatchMode purple_cipher_get_batch_mode(PurpleCipher *cipher);
 326
 327 /**
 328  * purple_cipher_get_block_size:
 329  * @cipher: The cipher whose block size to get
 330  *
 331  * Gets the block size of a cipher
 332  *
 333  * Returns: The block size of the cipher
 334  */
 335 size_t purple_cipher_get_block_size(PurpleCipher *cipher);
 336
 337 /*****************************************************************************/
 338 /* PurpleHash API                                                            */
 339 /*****************************************************************************/
 340
 341 /**
 342  * purple_hash_get_type:
 343  *
 344  * Returns: The #GType for the Hash object.
 345  */
 346 GType purple_hash_get_type(void);
 347
 348 /**
 349  * purple_hash_reset:
 350  * @hash:  The hash
 351  *
 352  * Resets a hash to it's default value
 353  * Note: If you have set an IV you will have to set it after resetting
 354  */
 355 void purple_hash_reset(PurpleHash *hash);
 356
 357 /**
 358  * purple_hash_reset_state:
 359  * @hash:  The hash
 360  *
 361  * Resets a hash state to it's default value, but doesn't touch stateless
 362  * configuration.
 363  *
 364  * That means, IV and digest will be wiped out, but keys, ops or salt
 365  * will remain untouched.
 366  */
 367 void purple_hash_reset_state(PurpleHash *hash);
 368
 369 /**
 370  * purple_hash_append:
 371  * @hash:    The hash
 372  * @data:    The data to append
 373  * @len:     The length of the data
 374  *
 375  * Appends data to the hash context
 376  */
 377 void purple_hash_append(PurpleHash *hash, const guchar *data, size_t len);
 378
 379 /**
 380  * purple_hash_digest:
 381  * @hash:    The hash
 382  * @digest:  The return buffer for the digest
 383  * @len:     The length of the buffer
 384  *
 385  * Digests a hash context
 386  */
 387 gboolean purple_hash_digest(PurpleHash *hash, guchar digest[], size_t len);
 388
 389 /**
 390  * purple_hash_digest_to_str:
 391  * @hash:     The hash
 392  * @digest_s: The return buffer for the string digest
 393  * @len:      The length of the buffer
 394  *
 395  * Converts a guchar digest into a hex string
 396  */
 397 gboolean purple_hash_digest_to_str(PurpleHash *hash, gchar digest_s[], size_t len);
 398
 399 /**
 400  * purple_hash_get_digest_size:
 401  * @hash: The hash whose digest size to get
 402  *
 403  * Gets the digest size of a hash
 404  *
 405  * Returns: The digest size of the hash
 406  */
 407 size_t purple_hash_get_digest_size(PurpleHash *hash);
 408
 409 /**
 410  * purple_hash_get_block_size:
 411  * @hash: The hash whose block size to get
 412  *
 413  * Gets the block size of a hash
 414  *
 415  * Returns: The block size of the hash
 416  */
 417 size_t purple_hash_get_block_size(PurpleHash *hash);
 418
 419 G_END_DECLS
 420
 421 #endif /* PURPLE_CIPHER_H */