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