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