Fix comment indentation.
[gpgme.git] / gpgme / gpgme.c
1 /* gpgme.c - GnuPG Made Easy.
2    Copyright (C) 2000 Werner Koch (dd9jn)
3    Copyright (C) 2001, 2002, 2003 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 GPGME_Invalid_Value;
50   *r_ctx = 0;
51   ctx = calloc (1, sizeof *ctx);
52   if (!ctx)
53     return GPGME_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 }
103
104
105 /* Cancel the current operation.  It is not guaranteed that it will
106    work for all kinds of operations.  It is especially useful in a
107    passphrase callback to stop the system from asking another time for
108    the passphrase.  */
109 void
110 gpgme_cancel (GpgmeCtx ctx)
111 {
112   if (!ctx)
113     return;
114
115   ctx->cancel = 1;
116 }
117
118
119 /**
120  * gpgme_get_notation:
121  * @c: the context
122  *
123  * If there is notation data available from the last signature check,
124  * this function may be used to return this notation data as a string.
125  * The string is an XML represantaton of that data embedded in a
126  * %&lt;notation&gt; container.
127  *
128  * Return value: An XML string or NULL if no notation data is available.
129  **/
130 char *
131 gpgme_get_notation (GpgmeCtx ctx)
132 {
133   if (!ctx->notation)
134     return NULL;
135   return _gpgme_data_get_as_string (ctx->notation);
136 }
137
138
139 /**
140  * gpgme_get_op_info:
141  * @c: the context
142  * @reserved:
143  *
144  * Return information about the last operation.  The caller has to
145  * free the string.  NULL is returned if there is not previous
146  * operation available or the operation has not yet finished.
147  *
148  * Here is a sample information we return:
149  * <literal>
150  * <![CDATA[
151  * <GnupgOperationInfo>
152  *   <signature>
153  *     <detached/> <!-- or cleartext or standard -->
154  *     <algo>17</algo>
155  *     <hashalgo>2</hashalgo>
156  *     <micalg>pgp-sha1</micalg>
157  *     <sigclass>01</sigclass>
158  *     <created>9222222</created>
159  *     <fpr>121212121212121212</fpr>
160  *   </signature>
161  * </GnupgOperationInfo>
162  * ]]>
163  * </literal>
164  * Return value: NULL for no info available or an XML string
165  **/
166 char *
167 gpgme_get_op_info (GpgmeCtx ctx, int reserved)
168 {
169   if (!ctx || reserved || !ctx->op_info)
170     return NULL;  /* Invalid value.  */
171
172   return _gpgme_data_get_as_string (ctx->op_info);
173 }
174
175
176 /* Store the data object INFO with the operation info in the context
177    CTX.  INFO is consumed.  Subsequent calls append the data.  */
178 void
179 _gpgme_set_op_info (GpgmeCtx ctx, GpgmeData info)
180 {
181   assert (ctx);
182
183   if (!ctx->op_info)
184     ctx->op_info = info;
185   else
186     {
187       char *info_mem = 0;
188       size_t info_len;
189
190       info_mem = gpgme_data_release_and_get_mem (info, &info_len);
191       _gpgme_data_append (ctx->op_info, info_mem, info_len);
192     }
193 }
194
195
196 GpgmeError
197 gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol protocol)
198 {
199   if (!ctx)
200     return GPGME_Invalid_Value;
201
202   switch (protocol)
203     {
204     case GPGME_PROTOCOL_OpenPGP:
205       ctx->use_cms = 0;
206       break;
207     case GPGME_PROTOCOL_CMS:
208       ctx->use_cms = 1;
209       break;
210     default:
211       return GPGME_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 const char *
229 gpgme_get_protocol_name (GpgmeProtocol protocol)
230 {
231   switch (protocol)
232     {
233     case GPGME_PROTOCOL_OpenPGP:
234       return "OpenPGP";
235
236     case GPGME_PROTOCOL_CMS:
237       return "CMS";
238
239     default:
240       return NULL;
241     }
242 }
243
244 /**
245  * gpgme_set_armor:
246  * @ctx: the context
247  * @yes: boolean value to set or clear that flag
248  *
249  * Enable or disable the use of an ascii armor for all output.
250  **/
251 void
252 gpgme_set_armor (GpgmeCtx ctx, int yes)
253 {
254   if (!ctx)
255     return;
256   ctx->use_armor = yes;
257 }
258
259
260 /**
261  * gpgme_get_armor:
262  * @ctx: the context
263  *
264  * Return the state of the armor flag which can be changed using
265  * gpgme_set_armor().
266  *
267  * Return value: Boolean whether armor mode is to be used.
268  **/
269 int
270 gpgme_get_armor (GpgmeCtx ctx)
271 {
272   return ctx && ctx->use_armor;
273 }
274
275
276 /**
277  * gpgme_set_textmode:
278  * @ctx: the context
279  * @yes: boolean flag whether textmode should be enabled
280  *
281  * Enable or disable the use of the special textmode.  Textmode is for example
282  * used for the RFC2015 signatures; note that the updated RFC 3156 mandates
283  * that the MUA does some preparations so that textmode is not needed anymore.
284  **/
285 void
286 gpgme_set_textmode (GpgmeCtx ctx, int yes)
287 {
288   if (!ctx)
289     return;
290   ctx->use_textmode = yes;
291 }
292
293 /**
294  * gpgme_get_textmode:
295  * @ctx: the context
296  *
297  * Return the state of the textmode flag which can be changed using
298  * gpgme_set_textmode().
299  *
300  * Return value: Boolean whether textmode is to be used.
301  **/
302 int
303 gpgme_get_textmode (GpgmeCtx ctx)
304 {
305   return ctx && ctx->use_textmode;
306 }
307
308
309 /**
310  * gpgme_set_include_certs:
311  * @ctx: the context
312  *
313  * Set the number of certifications to include in an S/MIME message.
314  * The default is 1 (only the cert of the sender).  -1 means all certs,
315  * and -2 means all certs except the root cert.
316  *
317  * Return value: Boolean whether textmode is to be used.
318  **/
319 void
320 gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs)
321 {
322   if (nr_of_certs < -2)
323     ctx->include_certs = -2;
324   else
325     ctx->include_certs = nr_of_certs;
326 }
327
328
329 /**
330  * gpgme_get_include_certs:
331  * @ctx: the context
332  *
333  * Get the number of certifications to include in an S/MIME message.
334  *
335  * Return value: Boolean whether textmode is to be used.
336  **/
337 int
338 gpgme_get_include_certs (GpgmeCtx ctx)
339 {
340   return ctx->include_certs;
341 }
342
343
344 /**
345  * gpgme_set_keylist_mode:
346  * @ctx: the context
347  * @mode: listing mode
348  *
349  * This function changes the default behaviour of the keylisting
350  * functions.  mode is a bitwise-OR of the GPGME_KEYLIST_* flags.
351  * The default mode is GPGME_KEYLIST_MODE_LOCAL.
352  *
353  * Return value: GPGME_Invalid_Value if ctx is not a context or mode
354  * not a valid mode.
355  **/
356 GpgmeError
357 gpgme_set_keylist_mode (GpgmeCtx ctx, int mode)
358 {
359   if (!ctx)
360     return GPGME_Invalid_Value;
361
362   if (!((mode & GPGME_KEYLIST_MODE_LOCAL)
363         || (mode & GPGME_KEYLIST_MODE_EXTERN)
364         || (mode & GPGME_KEYLIST_MODE_SIGS)))
365      return GPGME_Invalid_Value;
366
367   ctx->keylist_mode = mode;
368   return 0;
369 }
370
371
372 /**
373  * gpgme_get_keylist_mode:
374  * @ctx: the context
375  *
376  * This function ch the default behaviour of the keylisting functions.
377  * Defines values for @mode are: %0 = normal, %1 = fast listing without
378  * information about key validity.
379  *
380  * Return value: 0 if ctx is not a valid context, or the current mode.
381  * Note that 0 is never a valid mode.
382  **/
383 int
384 gpgme_get_keylist_mode (GpgmeCtx ctx)
385 {
386   if (!ctx)
387     return 0;
388   return ctx->keylist_mode;
389 }
390
391
392 /**
393  * gpgme_set_passphrase_cb:
394  * @ctx: the context
395  * @cb: A callback function
396  * @cb_value: The value passed to the callback function
397  *
398  * This function sets a callback function to be used to pass a passphrase
399  * to gpg. The preferred way to handle this is by using the gpg-agent, but
400  * because that beast is not ready for real use, you can use this passphrase
401  * thing.
402  *
403  * The callback function is defined as:
404  * <literal>
405  * typedef const char *(*GpgmePassphraseCb)(void*cb_value,
406  *                                          const char *desc,
407  *                                          void **r_hd);
408  * </literal>
409  * and called whenever gpgme needs a passphrase. DESC will have a nice
410  * text, to be used to prompt for the passphrase and R_HD is just a parameter
411  * to be used by the callback it self.  Because the callback returns a const
412  * string, the callback might want to know when it can release resources
413  * assocated with that returned string; gpgme helps here by calling this
414  * passphrase callback with an DESC of %NULL as soon as it does not need
415  * the returned string anymore.  The callback function might then choose
416  * to release resources depending on R_HD.
417  *
418  **/
419 void
420 gpgme_set_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb cb, void *cb_value)
421 {
422   if (ctx)
423     {
424       ctx->passphrase_cb = cb;
425       ctx->passphrase_cb_value = cb_value;
426     }
427 }
428
429
430 /**
431  * gpgme_get_passphrase_cb:
432  * @ctx: the context
433  * @r_cb: The current callback function
434  * @r_cb_value: The current value passed to the callback function
435  *
436  * This function returns the callback function to be used to pass a passphrase
437  * to the crypto engine.
438  **/
439 void
440 gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *r_cb, void **r_cb_value)
441 {
442   if (ctx)
443     {
444       if (r_cb)
445         *r_cb = ctx->passphrase_cb;
446       if (r_cb_value)
447         *r_cb_value = ctx->passphrase_cb_value;
448     }
449   else
450     {
451       if (r_cb)
452         *r_cb = NULL;
453       if (r_cb_value)
454         *r_cb_value = NULL;
455     }
456 }
457
458
459 /**
460  * gpgme_set_progress_cb:
461  * @ctx: the context
462  * @cb: A callback function
463  * @cb_value: The value passed to the callback function
464  *
465  * This function sets a callback function to be used as a progress indicator.
466  *
467  * The callback function is defined as:
468  * <literal>
469  * typedef void (*GpgmeProgressCb) (void *cb_value,
470  *                                  const char *what, int type,
471  *                                  int curretn, int total);
472  * </literal>
473  * For details on the progress events, see the entry for the PROGRESS
474  * status in the file doc/DETAILS of the GnuPG distribution.
475  **/
476 void
477 gpgme_set_progress_cb (GpgmeCtx ctx, GpgmeProgressCb cb, void *cb_value)
478 {
479   if (ctx)
480     {
481       ctx->progress_cb = cb;
482       ctx->progress_cb_value = cb_value;
483     }
484 }
485
486
487 /**
488  * gpgme_get_progress_cb:
489  * @ctx: the context
490  * @r_cb: The current callback function
491  * @r_cb_value: The current value passed to the callback function
492  *
493  * This function returns the callback function to be used as a
494  * progress indicator.
495  **/
496 void
497 gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *r_cb, void **r_cb_value)
498 {
499   if (ctx)
500     {
501       if (r_cb)
502         *r_cb = ctx->progress_cb;
503       if (r_cb_value)
504         *r_cb_value = ctx->progress_cb_value;
505     }
506   else
507     {
508       if (r_cb)
509         *r_cb = NULL;
510       if (r_cb_value)
511         *r_cb_value = NULL;
512     }
513 }
514
515
516 /**
517  * gpgme_set_io_cbs:
518  * @ctx: the context
519  * @register_io_cb: A callback function
520  * @register_hook_value: The value passed to the callback function
521  * @remove_io_cb: Another callback function
522  *
523  **/
524 void
525 gpgme_set_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs)
526 {
527   if (!ctx)
528     return;
529
530   if (io_cbs)
531     ctx->io_cbs = *io_cbs;
532   else
533     {
534       ctx->io_cbs.add = NULL;
535       ctx->io_cbs.add_priv = NULL;
536       ctx->io_cbs.remove = NULL;
537       ctx->io_cbs.event = NULL;
538       ctx->io_cbs.event_priv = NULL;
539     }
540 }
541
542
543 /**
544  * gpgme_get_io_cbs:
545  * @ctx: the context
546  * @r_register_cb: The current register callback function
547  * @r_register_cb_value: The current value passed to the
548  * register callback function
549  * @r_remove_cb: The current remove callback function
550  *
551  * This function returns the callback function to be used to pass a passphrase
552  * to the crypto engine.
553  **/
554 void
555 gpgme_get_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs)
556 {
557   if (ctx && io_cbs)
558     *io_cbs = ctx->io_cbs;
559 }