Mercurial > pidgin
annotate src/cipher.h @ 10827:53e7884c549a
[gaim-migrate @ 12492]
this should fix some problems with contact aware conversations, while
possibly introducing new problems, and breaking some plugins.
Someone needs to just remove GaimConvWindows all together.
committer: Tailor Script <tailor@pidgin.im>
author | Tim Ringenbach <marv@pidgin.im> |
---|---|
date | Fri, 15 Apr 2005 22:32:00 +0000 |
parents | b256ce6b85b8 |
children | 8dca96cbcd64 |
rev | line source |
---|---|
10684 | 1 /** |
2 * @file cipher.h Gaim Cipher API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
7 * Gaim is the legal property of its developers, whose names are too numerous | |
8 * to list here. Please refer to the COPYRIGHT file distributed with this | |
9 * source distribution. | |
10 * | |
11 * This program is free software; you can redistribute it and/or modify | |
12 * it under the terms of the GNU General Public License as published by | |
13 * the Free Software Foundation; either version 2 of the License, or | |
14 * (at your option) any later version. | |
15 * | |
16 * This program is distributed in the hope that it will be useful, | |
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 * GNU General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU General Public License | |
22 * along with this program; if not, write to the Free Software | |
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
24 */ | |
25 #ifndef GAIM_CIPHER_H | |
26 #define GAIM_CIPHER_H | |
27 | |
28 #include <glib.h> | |
29 | |
30 #define GAIM_CIPHER(obj) ((GaimCipher *)(obj)) /**< GaimCipher typecast helper */ | |
31 #define GAIM_CIPHER_OPS(obj) ((GaimCipherOps *)(obj)) /**< GaimCipherInfo typecase helper */ | |
32 #define GAIM_CIPHER_CONTEXT(obj) ((GaimCipherContext *)(obj)) /**< GaimCipherContext typecast helper */ | |
33 | |
34 typedef struct _GaimCipher GaimCipher; /**< A handle to a GaimCipher */ | |
35 typedef struct _GaimCipherOps GaimCipherOps; /**< Ops for a GaimCipher */ | |
36 typedef struct _GaimCipherContext GaimCipherContext; /**< A context for a GaimCipher */ | |
37 | |
38 | |
39 /** | |
40 * The operation flags for a cipher | |
41 */ | |
42 typedef enum _GaimCipherCaps { | |
43 GAIM_CIPHER_CAPS_SET_OPT = 1 << 1, /**< Set option flag */ | |
44 GAIM_CIPHER_CAPS_GET_OPT = 1 << 2, /**< Get option flag */ | |
45 GAIM_CIPHER_CAPS_INIT = 1 << 3, /**< Init flag */ | |
46 GAIM_CIPHER_CAPS_RESET = 1 << 4, /**< Reset flag */ | |
47 GAIM_CIPHER_CAPS_UNINIT = 1 << 5, /**< Uninit flag */ | |
48 GAIM_CIPHER_CAPS_SET_IV = 1 << 6, /**< Set IV flag */ | |
49 GAIM_CIPHER_CAPS_APPEND = 1 << 7, /**< Append flag */ | |
50 GAIM_CIPHER_CAPS_DIGEST = 1 << 8, /**< Digest flag */ | |
51 GAIM_CIPHER_CAPS_ENCRYPT = 1 << 9, /**< Encrypt flag */ | |
52 GAIM_CIPHER_CAPS_DECRYPT = 1 << 10, /**< Decrypt flag */ | |
53 GAIM_CIPHER_CAPS_SET_SALT = 1 << 11, /**< Set salt flag */ | |
54 GAIM_CIPHER_CAPS_GET_SALT_SIZE = 1 << 12, /**< Get salt size flag */ | |
55 GAIM_CIPHER_CAPS_SET_KEY = 1 << 13, /**< Set key flag */ | |
56 GAIM_CIPHER_CAPS_GET_KEY_SIZE = 1 << 14, /**< Get key size flag */ | |
57 GAIM_CIPHER_CAPS_UNKNOWN = 1 << 16 /**< Unknown */ | |
58 } GaimCipherCaps; | |
59 | |
60 /** | |
61 * The operations of a cipher. Every cipher must implement one of these. | |
62 */ | |
63 struct _GaimCipherOps { | |
64 /** The set option function */ | |
65 void (*set_option)(GaimCipherContext *context, const gchar *name, void *value); | |
66 | |
67 /** The get option function */ | |
68 void *(*get_option)(GaimCipherContext *context, const gchar *name); | |
69 | |
70 /** The init function */ | |
71 void (*init)(GaimCipherContext *context, void *extra); | |
72 | |
73 /** The reset function */ | |
74 void (*reset)(GaimCipherContext *context, void *extra); | |
75 | |
76 /** The uninit function */ | |
77 void (*uninit)(GaimCipherContext *context); | |
78 | |
79 /** The set initialization vector function */ | |
80 void (*set_iv)(GaimCipherContext *context, guint8 *iv, size_t len); | |
81 | |
82 /** The append data function */ | |
83 void (*append)(GaimCipherContext *context, const guint8 *data, size_t len); | |
84 | |
85 /** The digest function */ | |
10687
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
86 gboolean (*digest)(GaimCipherContext *context, size_t in_len, guint8 digest[], size_t *out_len); |
10684 | 87 |
88 /** The encrypt function */ | |
89 int (*encrypt)(GaimCipherContext *context, const guint8 data[], size_t len, guint8 output[], size_t *outlen); | |
90 | |
91 /** The decrypt function */ | |
92 int (*decrypt)(GaimCipherContext *context, const guint8 data[], size_t len, guint8 output[], size_t *outlen); | |
93 | |
94 /** The set salt function */ | |
95 void (*set_salt)(GaimCipherContext *context, guint8 *salt); | |
96 | |
97 /** The get salt size function */ | |
98 size_t (*get_salt_size)(GaimCipherContext *context); | |
99 | |
100 /** The set key function */ | |
101 void (*set_key)(GaimCipherContext *context, guint8 *key); | |
102 | |
103 /** The get key size function */ | |
104 size_t (*get_key_size)(GaimCipherContext *context); | |
105 }; | |
106 | |
107 #ifdef __cplusplus | |
108 extern "C" { | |
109 #endif /* __cplusplus */ | |
110 | |
111 /*****************************************************************************/ | |
112 /** @name GaimCipher API */ | |
113 /*****************************************************************************/ | |
114 /*@{*/ | |
115 | |
116 /** | |
117 * Gets a cipher's name | |
118 * | |
119 * @param cipher The cipher handle | |
120 * | |
121 * @return The cipher's name | |
122 */ | |
123 const gchar *gaim_cipher_get_name(GaimCipher *cipher); | |
124 | |
125 /** | |
126 * Gets a cipher's capabilities | |
127 * | |
128 * @param cipher The cipher handle | |
129 * | |
130 * @return The cipher's info | |
131 */ | |
132 guint gaim_cipher_get_capabilities(GaimCipher *cipher); | |
133 | |
134 /** | |
135 * Gets a digest from a cipher | |
136 * | |
10687
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
137 * @param name The cipher's name |
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
138 * @param data The data to hash |
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
139 * @param data_len The length of the data |
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
140 * @param in_len The length of the buffer |
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
141 * @param digest The returned digest |
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
142 * @param out_len The length written |
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
143 * |
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
144 * @return @c TRUE if successful, @c FALSE otherwise |
10684 | 145 */ |
10687
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
146 gboolean gaim_cipher_digest_region(const gchar *name, const guint8 *data, size_t data_len, size_t in_len, guint8 digest[], size_t *out_len); |
10684 | 147 |
148 /*@}*/ | |
149 /******************************************************************************/ | |
150 /** @name GaimCiphers API */ | |
151 /******************************************************************************/ | |
152 /*@{*/ | |
153 | |
154 /** | |
155 * Finds a cipher by it's name | |
156 * | |
157 * @param name The name of the cipher to find | |
158 * | |
159 * @return The cipher handle or @c NULL | |
160 */ | |
161 GaimCipher *gaim_ciphers_find_cipher(const gchar *name); | |
162 | |
163 /** | |
164 * Registers a cipher as a usable cipher | |
165 * | |
166 * @param name The name of the new cipher | |
167 * @param ops The cipher ops to register | |
168 * | |
169 * @return The handle to the new cipher or @c NULL if it failed | |
170 */ | |
171 GaimCipher *gaim_ciphers_register_cipher(const gchar *name, GaimCipherOps *ops); | |
172 | |
173 /** | |
174 * Unregisters a cipher | |
175 * | |
176 * @param cipher The cipher handle to unregister | |
177 * | |
178 * @return Whether or not the cipher was successfully unloaded | |
179 */ | |
180 gboolean gaim_ciphers_unregister_cipher(GaimCipher *cipher); | |
181 | |
182 /** | |
183 * Gets the list of ciphers | |
184 * | |
185 * @return The list of available ciphers | |
186 * @note This list should not be modified, it is owned by the cipher core | |
187 */ | |
188 GList *gaim_ciphers_get_ciphers(); | |
189 | |
190 /*@}*/ | |
191 /******************************************************************************/ | |
192 /** @name GaimCipher Subsystem API */ | |
193 /******************************************************************************/ | |
194 /*@{*/ | |
195 | |
196 /** | |
197 * Gets the handle to the cipher subsystem | |
198 * | |
199 * @return The handle to the cipher subsystem | |
200 */ | |
201 gpointer gaim_ciphers_get_handle(); | |
202 | |
203 /** | |
204 * Initializes the cipher core | |
205 */ | |
206 void gaim_ciphers_init(); | |
207 | |
208 /** | |
209 * Uninitializes the cipher core | |
210 */ | |
211 void gaim_ciphers_uninit(); | |
212 | |
213 /*@}*/ | |
214 /******************************************************************************/ | |
215 /** @name GaimCipherContext API */ | |
216 /******************************************************************************/ | |
217 /*@{*/ | |
218 | |
219 /** | |
220 * Sets the value an option on a cipher context | |
221 * | |
222 * @param context The cipher context | |
223 * @param name The name of the option | |
224 * @param value The value to set | |
225 */ | |
226 void gaim_cipher_context_set_option(GaimCipherContext *context, const gchar *name, gpointer value); | |
227 | |
228 /** | |
229 * Gets the vale of an option on a cipher context | |
230 * | |
231 * @param context The cipher context | |
232 * @param name The name of the option | |
233 * @return The value of the option | |
234 */ | |
235 gpointer gaim_cipher_context_get_option(GaimCipherContext *context, const gchar *name); | |
236 | |
237 /** | |
238 * Creates a new cipher context and initializes it | |
239 * | |
240 * @param cipher The cipher to use | |
241 * @param extra Extra data for the specific cipher | |
242 * | |
243 * @return The new cipher context | |
244 */ | |
245 GaimCipherContext *gaim_cipher_context_new(GaimCipher *cipher, void *extra); | |
246 | |
247 /** | |
248 * Creates a new cipher context by the cipher name and initializes it | |
249 * | |
250 * @param name The cipher's name | |
251 * @param extra Extra data for the specific cipher | |
252 * | |
253 * @return The new cipher context | |
254 */ | |
255 GaimCipherContext *gaim_cipher_context_new_by_name(const gchar *name, void *extra); | |
256 | |
257 /** | |
258 * Resets a cipher context to it's default value | |
259 * @note If you have set an IV you will have to set it after resetting | |
260 * | |
261 * @param context The context to reset | |
262 * @param extra Extra data for the specific cipher | |
263 */ | |
264 void gaim_cipher_context_reset(GaimCipherContext *context, gpointer extra); | |
265 | |
266 /** | |
267 * Destorys a cipher context and deinitializes it | |
268 * | |
269 * @param context The cipher context to destory | |
270 */ | |
271 void gaim_cipher_context_destroy(GaimCipherContext *context); | |
272 | |
273 /** | |
274 * Sets the initialization vector for a context | |
275 * @note This should only be called right after a cipher context is created or reset | |
276 * | |
277 * @param context The context to set the IV to | |
278 * @param iv The initialization vector to set | |
279 * @param len The len of the IV | |
280 */ | |
281 void gaim_cipher_context_set_iv(GaimCipherContext *context, guint8 *iv, size_t len); | |
282 | |
283 /** | |
284 * Appends data to the context | |
285 * | |
286 * @param context The context to append data to | |
287 * @param data The data to append | |
288 * @param len The length of the data | |
289 */ | |
290 void gaim_cipher_context_append(GaimCipherContext *context, const guint8 *data, size_t len); | |
291 | |
292 /** | |
293 * Digests a context | |
294 * | |
295 * @param context The context to digest | |
10687
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
296 * @param in_len The length of the buffer |
10684 | 297 * @param digest The return buffer for the digest |
10687
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
298 * @param out_len The length of the returned value |
10684 | 299 */ |
10687
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
300 gboolean gaim_cipher_context_digest(GaimCipherContext *context, size_t in_len, guint8 digest[], size_t *out_len); |
10684 | 301 |
302 /** | |
303 * Converts a guint8 digest into a hex string | |
304 * | |
305 * @param context The context to get a digest from | |
10687
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
306 * @param in_len The length of the buffer |
10684 | 307 * @param digest_s The return buffer for the string digest |
10687
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
308 * @param out_len The length of the returned value |
10684 | 309 */ |
10687
b256ce6b85b8
[gaim-migrate @ 12235]
Etan Reisner <pidgin@unreliablesource.net>
parents:
10684
diff
changeset
|
310 gboolean gaim_cipher_context_digest_to_str(GaimCipherContext *context, size_t in_len, gchar digest_s[], size_t *out_len); |
10684 | 311 |
312 /** | |
313 * Encrypts data using the context | |
314 * | |
315 * @param context The context | |
316 * @param data The data to encrypt | |
317 * @param len The length of the data | |
318 * @param output The output buffer | |
319 * @param outlen The len of data that was outputed | |
320 * | |
321 * @return A cipher specific status code | |
322 */ | |
323 gint gaim_cipher_context_encrypt(GaimCipherContext *context, const guint8 data[], size_t len, guint8 output[], size_t *outlen); | |
324 | |
325 /** | |
326 * Decrypts data using the context | |
327 * | |
328 * @param context The context | |
329 * @param data The data to encrypt | |
330 * @param len The length of the returned value | |
331 * @param output The output buffer | |
332 * @param outlen The len of data that was outputed | |
333 * | |
334 * @return A cipher specific status code | |
335 */ | |
336 gint gaim_cipher_context_decrypt(GaimCipherContext *context, const guint8 data[], size_t len, guint8 output[], size_t *outlen); | |
337 | |
338 /** | |
339 * Sets the salt on a context | |
340 * | |
341 * @param context The context who's salt to set | |
342 * @param salt The salt | |
343 */ | |
344 void gaim_cipher_context_set_salt(GaimCipherContext *context, guint8 *salt); | |
345 | |
346 /** | |
347 * Gets the size of the salt if the cipher supports it | |
348 * | |
349 * @param context The context who's salt size to get | |
350 * | |
351 * @return The size of the salt | |
352 */ | |
353 size_t gaim_cipher_context_get_salt_size(GaimCipherContext *context); | |
354 | |
355 /** | |
356 * Sets the key on a context | |
357 * | |
358 * @param context The context who's key to set | |
359 * @param key The key | |
360 */ | |
361 void gaim_cipher_context_set_key(GaimCipherContext *context, guint8 *key); | |
362 | |
363 /** | |
364 * Gets the key size for a context | |
365 * | |
366 * @param context The context who's key size to get | |
367 * | |
368 * @return The size of the key | |
369 */ | |
370 size_t gaim_cipher_context_get_key_size(GaimCipherContext *context); | |
371 | |
372 /** | |
373 * Sets the cipher data for a context | |
374 * | |
375 * @param context The context who's cipher data to set | |
376 * @param data The cipher data to set | |
377 */ | |
378 void gaim_cipher_context_set_data(GaimCipherContext *context, gpointer data); | |
379 | |
380 /** | |
381 * Gets the cipher data for a context | |
382 * | |
383 * @param context The context who's cipher data to get | |
384 * | |
385 * @return The cipher data | |
386 */ | |
387 gpointer gaim_cipher_context_get_data(GaimCipherContext *context); | |
388 | |
389 /*@}*/ | |
390 | |
391 #ifdef __cplusplus | |
392 } | |
393 #endif /* __cplusplus */ | |
394 | |
395 #endif /* GAIM_CIPHER_H */ |