ed1499675ebb7b03c6deb678107d17b473eed3da
[gpgme.git] / gpgme / gpgme.c
1 /* gpgme.c -  GnuPG Made Easy
2  *      Copyright (C) 2000 Werner Koch (dd9jn)
3  *      Copyright (C) 2001, 2002 g10 Code GmbH
4  *
5  * This file is part of GPGME.
6  *
7  * GPGME 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  * GPGME 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
20  */
21
22 #include <config.h>
23 #include <stdio.h>
24 #include <stdlib.h>
25 #include <string.h>
26 #include <assert.h>
27
28 #include "util.h"
29 #include "context.h"
30 #include "ops.h"
31 #include "wait.h"
32
33 /**
34  * gpgme_new:
35  * @r_ctx: Returns the new context
36  *
37  * Create a new context to be used with most of the other GPGME
38  * functions.  Use gpgme_release_context() to release all resources
39  *
40  * Return value: An error code
41  **/
42 GpgmeError
43 gpgme_new (GpgmeCtx *r_ctx)
44 {
45   GpgmeCtx ctx;
46
47   if (!r_ctx)
48     return mk_error (Invalid_Value);
49   *r_ctx = 0;
50   ctx = xtrycalloc (1, sizeof *ctx);
51   if (!ctx)
52     return mk_error (Out_Of_Core);
53   ctx->keylist_mode = GPGME_KEYLIST_MODE_LOCAL;
54   ctx->verbosity = 1;
55   ctx->include_certs = 1;
56   _gpgme_fd_table_init (&ctx->fdt);
57   *r_ctx = ctx;
58   return 0;
59 }
60
61
62 /**
63  * gpgme_release:
64  * @c: Context to be released.
65  *
66  * Release all resources associated with the given context.
67  **/
68 void
69 gpgme_release (GpgmeCtx ctx)
70 {
71   if (!ctx)
72     return;
73   _gpgme_engine_release (ctx->engine);
74   _gpgme_fd_table_deinit (&ctx->fdt);
75   _gpgme_release_result (ctx);
76   gpgme_key_release (ctx->tmp_key);
77   gpgme_data_release (ctx->help_data_1);
78   gpgme_data_release (ctx->notation);
79   gpgme_signers_clear (ctx);
80   if (ctx->signers)
81     xfree (ctx->signers);
82   /* FIXME: Release the key_queue.  */
83   xfree (ctx);
84 }
85
86 void
87 _gpgme_release_result (GpgmeCtx ctx)
88 {
89   _gpgme_release_verify_result (ctx->result.verify);
90   _gpgme_release_decrypt_result (ctx->result.decrypt);
91   _gpgme_release_sign_result (ctx->result.sign);
92   _gpgme_release_encrypt_result (ctx->result.encrypt);
93   _gpgme_release_passphrase_result (ctx->result.passphrase);
94   _gpgme_release_import_result (ctx->result.import);
95   _gpgme_release_delete_result (ctx->result.delete);
96   _gpgme_release_genkey_result (ctx->result.genkey);
97   _gpgme_release_keylist_result (ctx->result.keylist);
98   memset (&ctx->result, 0, sizeof (ctx->result));
99   _gpgme_set_op_info (ctx, NULL);
100   ctx->error = 0;
101 }
102
103
104 /**
105  * gpgme_cancel:
106  * @c: the context
107  *
108  * Cancel the current operation.  It is not guaranteed that it will work for
109  * all kinds of operations.  It is especially useful in a passphrase callback
110  * to stop the system from asking another time for the passphrase.
111  **/
112 void
113 gpgme_cancel (GpgmeCtx ctx)
114 {
115   return_if_fail (ctx);
116
117   ctx->cancel = 1;
118 }
119
120 /**
121  * gpgme_get_notation:
122  * @c: the context
123  *
124  * If there is notation data available from the last signature check,
125  * this function may be used to return this notation data as a string.
126  * The string is an XML represantaton of that data embedded in a
127  * %&lt;notation&gt; container.
128  *
129  * Return value: An XML string or NULL if no notation data is available.
130  **/
131 char *
132 gpgme_get_notation (GpgmeCtx ctx)
133 {
134   if (!ctx->notation)
135     return NULL;
136   return _gpgme_data_get_as_string (ctx->notation);
137 }
138
139
140 /**
141  * gpgme_get_op_info:
142  * @c: the context
143  * @reserved:
144  *
145  * Return information about the last operation.  The caller has to
146  * free the string.  NULL is returned if there is not previous
147  * operation available or the operation has not yet finished.
148  *
149  * Here is a sample information we return:
150  * <literal>
151  * <![CDATA[
152  * <GnupgOperationInfo>
153  *   <signature>
154  *     <detached/> <!-- or cleartext or standard -->
155  *     <algo>17</algo>
156  *     <hashalgo>2</hashalgo>
157  *     <micalg>pgp-sha1</micalg>
158  *     <sigclass>01</sigclass>
159  *     <created>9222222</created>
160  *     <fpr>121212121212121212</fpr>
161  *   </signature>
162  * </GnupgOperationInfo>
163  * ]]>
164  * </literal>
165  * Return value: NULL for no info available or an XML string
166  **/
167 char *
168 gpgme_get_op_info (GpgmeCtx ctx, int reserved)
169 {
170   if (!ctx || reserved)
171     return NULL;  /* Invalid value.  */
172
173   return _gpgme_data_get_as_string (ctx->op_info);
174 }
175
176
177 /*
178  * Store the data object with the operation info in the
179  * context. Caller should not use that object anymore.
180  */
181 void
182 _gpgme_set_op_info (GpgmeCtx ctx, GpgmeData info)
183 {
184   assert (ctx);
185
186   gpgme_data_release (ctx->op_info);
187   ctx->op_info = NULL;
188
189   if (info)
190     ctx->op_info = info;
191 }
192
193
194 GpgmeError
195 gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol protocol)
196 {
197   if (!ctx)
198     return mk_error (Invalid_Value);
199
200   switch (protocol)
201     {
202     case GPGME_PROTOCOL_OpenPGP:
203       ctx->use_cms = 0;
204       break;
205     case GPGME_PROTOCOL_CMS:
206       ctx->use_cms = 1;
207       break;
208     case GPGME_PROTOCOL_AUTO:
209       return mk_error (Not_Implemented);
210     default:
211       return mk_error (Invalid_Value);
212     }
213
214   return 0;
215 }
216
217 GpgmeProtocol
218 gpgme_get_protocol (GpgmeCtx ctx)
219 {
220   if (!ctx)
221     return 0; /* well, this is OpenPGP */
222   if (ctx->use_cms)
223     return GPGME_PROTOCOL_CMS;
224   return GPGME_PROTOCOL_OpenPGP;
225 }
226
227
228 /**
229  * gpgme_set_armor:
230  * @ctx: the context
231  * @yes: boolean value to set or clear that flag
232  *
233  * Enable or disable the use of an ascii armor for all output.
234  **/
235 void
236 gpgme_set_armor (GpgmeCtx ctx, int yes)
237 {
238   if (!ctx)
239     return;
240   ctx->use_armor = yes;
241 }
242
243
244 /**
245  * gpgme_get_armor:
246  * @ctx: the context
247  *
248  * Return the state of the armor flag which can be changed using
249  * gpgme_set_armor().
250  *
251  * Return value: Boolean whether armor mode is to be used.
252  **/
253 int
254 gpgme_get_armor (GpgmeCtx ctx)
255 {
256   return ctx && ctx->use_armor;
257 }
258
259
260 /**
261  * gpgme_set_textmode:
262  * @ctx: the context
263  * @yes: boolean flag whether textmode should be enabled
264  *
265  * Enable or disable the use of the special textmode.  Textmode is for example
266  * used for the RFC2015 signatures; note that the updated RFC 3156 mandates
267  * that the MUA does some preparations so that textmode is not needed anymore.
268  **/
269 void
270 gpgme_set_textmode (GpgmeCtx ctx, int yes)
271 {
272   if (!ctx)
273     return;
274   ctx->use_textmode = yes;
275 }
276
277 /**
278  * gpgme_get_textmode:
279  * @ctx: the context
280  *
281  * Return the state of the textmode flag which can be changed using
282  * gpgme_set_textmode().
283  *
284  * Return value: Boolean whether textmode is to be used.
285  **/
286 int
287 gpgme_get_textmode (GpgmeCtx ctx)
288 {
289   return ctx && ctx->use_textmode;
290 }
291
292
293 /**
294  * gpgme_set_include_certs:
295  * @ctx: the context
296  *
297  * Set the number of certifications to include in an S/MIME message.
298  * The default is 1 (only the cert of the sender).  -1 means all certs,
299  * and -2 means all certs except the root cert.
300  *
301  * Return value: Boolean whether textmode is to be used.
302  **/
303 void
304 gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs)
305 {
306   if (nr_of_certs < -2)
307     ctx->include_certs = -2;
308   else
309     ctx->include_certs = nr_of_certs;
310 }
311
312
313 /**
314  * gpgme_get_include_certs:
315  * @ctx: the context
316  *
317  * Get the number of certifications to include in an S/MIME message.
318  *
319  * Return value: Boolean whether textmode is to be used.
320  **/
321 int
322 gpgme_get_include_certs (GpgmeCtx ctx)
323 {
324   return ctx->include_certs;
325 }
326
327
328 /**
329  * gpgme_set_keylist_mode:
330  * @ctx: the context
331  * @mode: listing mode
332  *
333  * This function changes the default behaviour of the keylisting
334  * functions.  mode is a bitwise-OR of the GPGME_KEYLIST_* flags.
335  * The default mode is GPGME_KEYLIST_MODE_LOCAL.
336  *
337  * Return value: GPGME_Invalid_Value if ctx is not a context or mode
338  * not a valid mode.
339  **/
340 GpgmeError
341 gpgme_set_keylist_mode (GpgmeCtx ctx, int mode)
342 {
343   if (!ctx)
344     return mk_error (Invalid_Value);
345
346   if (!((mode & GPGME_KEYLIST_MODE_LOCAL)
347         || (mode & GPGME_KEYLIST_MODE_EXTERN)))
348     return mk_error (Invalid_Value);
349
350   ctx->keylist_mode = mode;
351   return 0;
352 }
353
354
355 /**
356  * gpgme_get_keylist_mode:
357  * @ctx: the context
358  *
359  * This function ch the default behaviour of the keylisting functions.
360  * Defines values for @mode are: %0 = normal, %1 = fast listing without
361  * information about key validity.
362  *
363  * Return value: 0 if ctx is not a valid context, or the current mode.
364  * Note that 0 is never a valid mode.
365  **/
366 int
367 gpgme_get_keylist_mode (GpgmeCtx ctx)
368 {
369   if (!ctx)
370     return 0;
371   return ctx->keylist_mode;
372 }
373
374
375 /**
376  * gpgme_set_passphrase_cb:
377  * @ctx: the context
378  * @cb: A callback function
379  * @cb_value: The value passed to the callback function
380  *
381  * This function sets a callback function to be used to pass a passphrase
382  * to gpg. The preferred way to handle this is by using the gpg-agent, but
383  * because that beast is not ready for real use, you can use this passphrase
384  * thing.
385  *
386  * The callback function is defined as:
387  * <literal>
388  * typedef const char *(*GpgmePassphraseCb)(void*cb_value,
389  *                                          const char *desc,
390  *                                          void **r_hd);
391  * </literal>
392  * and called whenever gpgme needs a passphrase. DESC will have a nice
393  * text, to be used to prompt for the passphrase and R_HD is just a parameter
394  * to be used by the callback it self.  Because the callback returns a const
395  * string, the callback might want to know when it can release resources
396  * assocated with that returned string; gpgme helps here by calling this
397  * passphrase callback with an DESC of %NULL as soon as it does not need
398  * the returned string anymore.  The callback function might then choose
399  * to release resources depending on R_HD.
400  *
401  **/
402 void
403 gpgme_set_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb cb, void *cb_value)
404 {
405   if (ctx)
406     {
407       ctx->passphrase_cb = cb;
408       ctx->passphrase_cb_value = cb_value;
409     }
410 }
411
412
413 /**
414  * gpgme_get_passphrase_cb:
415  * @ctx: the context
416  * @r_cb: The current callback function
417  * @r_cb_value: The current value passed to the callback function
418  *
419  * This function returns the callback function to be used to pass a passphrase
420  * to the crypto engine.
421  **/
422 void
423 gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *r_cb, void **r_cb_value)
424 {
425   if (ctx)
426     {
427       if (r_cb)
428         *r_cb = ctx->passphrase_cb;
429       if (r_cb_value)
430         *r_cb_value = ctx->passphrase_cb_value;
431     }
432   else
433     {
434       if (r_cb)
435         *r_cb = NULL;
436       if (r_cb_value)
437         *r_cb_value = NULL;
438     }
439 }
440
441
442 /**
443  * gpgme_set_progress_cb:
444  * @ctx: the context
445  * @cb: A callback function
446  * @cb_value: The value passed to the callback function
447  *
448  * This function sets a callback function to be used as a progress indicator.
449  *
450  * The callback function is defined as:
451  * <literal>
452  * typedef void (*GpgmeProgressCb) (void *cb_value,
453  *                                  const char *what, int type,
454  *                                  int curretn, int total);
455  * </literal>
456  * For details on the progress events, see the entry for the PROGRESS
457  * status in the file doc/DETAILS of the GnuPG distribution.
458  **/
459 void
460 gpgme_set_progress_cb (GpgmeCtx ctx, GpgmeProgressCb cb, void *cb_value)
461 {
462   if (ctx)
463     {
464       ctx->progress_cb = cb;
465       ctx->progress_cb_value = cb_value;
466     }
467 }
468
469
470 /**
471  * gpgme_get_progress_cb:
472  * @ctx: the context
473  * @r_cb: The current callback function
474  * @r_cb_value: The current value passed to the callback function
475  *
476  * This function returns the callback function to be used as a
477  * progress indicator.
478  **/
479 void
480 gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *r_cb, void **r_cb_value)
481 {
482   if (ctx)
483     {
484       if (r_cb)
485         *r_cb = ctx->progress_cb;
486       if (r_cb_value)
487         *r_cb_value = ctx->progress_cb_value;
488     }
489   else
490     {
491       if (r_cb)
492         *r_cb = NULL;
493       if (r_cb_value)
494         *r_cb_value = NULL;
495     }
496 }
497
498
499 /**
500  * gpgme_set_io_cbs:
501  * @ctx: the context
502  * @register_io_cb: A callback function
503  * @register_hook_value: The value passed to the callback function
504  * @remove_io_cb: Another callback function
505  *
506  **/
507 void
508 gpgme_set_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs)
509 {
510   if (ctx && io_cbs)
511     ctx->io_cbs = *io_cbs;
512   else
513     {
514       ctx->io_cbs.add = NULL;
515       ctx->io_cbs.add_priv = NULL;
516       ctx->io_cbs.remove = NULL;
517       ctx->io_cbs.event = NULL;
518       ctx->io_cbs.event_priv = NULL;
519     }
520 }
521
522
523 /**
524  * gpgme_get_io_cbs:
525  * @ctx: the context
526  * @r_register_cb: The current register callback function
527  * @r_register_cb_value: The current value passed to the
528  * register callback function
529  * @r_remove_cb: The current remove callback function
530  *
531  * This function returns the callback function to be used to pass a passphrase
532  * to the crypto engine.
533  **/
534 void
535 gpgme_get_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs)
536 {
537   if (ctx && io_cbs)
538     *io_cbs = ctx->io_cbs;
539 }
540
541
542 void
543 _gpgme_op_event_cb (void *data, GpgmeEventIO type, void *type_data)
544 {
545   GpgmeCtx ctx = data;
546
547   if (type == GPGME_EVENT_DONE)
548     ctx->pending = 0;
549
550   if (ctx->io_cbs.add && ctx->io_cbs.event)
551     (*ctx->io_cbs.event) (ctx->io_cbs.event_priv, type, type_data);
552 }