343e77527a5bf3662ce27aec3a264138a8e49729
[gpgme.git] / src / gpgme.c
1 /* gpgme.c - GnuPG Made Easy.
2    Copyright (C) 2000 Werner Koch (dd9jn)
3    Copyright (C) 2001, 2002, 2003, 2004, 2005, 2007, 2012,
4                  2014, 2015 g10 Code GmbH
5
6    This file is part of GPGME.
7
8    GPGME is free software; you can redistribute it and/or modify it
9    under the terms of the GNU Lesser General Public License as
10    published by the Free Software Foundation; either version 2.1 of
11    the License, or (at your option) any later version.
12
13    GPGME is distributed in the hope that it will be useful, but
14    WITHOUT ANY WARRANTY; without even the implied warranty of
15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16    Lesser General Public License for more details.
17
18    You should have received a copy of the GNU Lesser General Public
19    License along with this program; if not, see <http://www.gnu.org/licenses/>.
20  */
21
22 #if HAVE_CONFIG_H
23 #include <config.h>
24 #endif
25 #include <stdio.h>
26 #include <stdlib.h>
27 #include <string.h>
28 #include <assert.h>
29 #include <errno.h>
30 #ifdef HAVE_LOCALE_H
31 #include <locale.h>
32 #endif
33
34 #include "util.h"
35 #include "context.h"
36 #include "ops.h"
37 #include "wait.h"
38 #include "debug.h"
39 #include "priv-io.h"
40 #include "sys-util.h"
41
42 \f
43 /* The default locale.  */
44 DEFINE_STATIC_LOCK (def_lc_lock);
45 static char *def_lc_ctype;
46 static char *def_lc_messages;
47
48 \f
49 gpgme_error_t _gpgme_selftest = GPG_ERR_NOT_OPERATIONAL;
50
51 /* Protects all reference counters in result structures.  All other
52    accesses to a result structure are read only.  */
53 DEFINE_STATIC_LOCK (result_ref_lock);
54
55 \f
56 /* Set the global flag NAME to VALUE.  Return 0 on success.  Note that
57    this function does not use gpgme_error and thus a non-zero return
58    value merely means "error".  Certain flags may be set before
59    gpgme_check_version is called.  See the manual for a description of
60    supported flags.  The caller must assure that this function is
61    called only by one thread at a time.  */
62 int
63 gpgme_set_global_flag (const char *name, const char *value)
64 {
65   if (!name || !value)
66     return -1;
67   else if (!strcmp (name, "debug"))
68     return _gpgme_debug_set_debug_envvar (value);
69   else if (!strcmp (name, "disable-gpgconf"))
70     {
71       _gpgme_dirinfo_disable_gpgconf ();
72       return 0;
73     }
74   else if (!strcmp (name, "gpgconf-name"))
75     return _gpgme_set_default_gpgconf_name (value);
76   else if (!strcmp (name, "gpg-name"))
77     return _gpgme_set_default_gpg_name (value);
78   else
79     return -1;
80 }
81
82
83 \f
84 /* Create a new context as an environment for GPGME crypto
85    operations.  */
86 gpgme_error_t
87 gpgme_new (gpgme_ctx_t *r_ctx)
88 {
89   gpgme_error_t err;
90   gpgme_ctx_t ctx;
91   TRACE_BEG (DEBUG_CTX, "gpgme_new", r_ctx);
92
93   if (_gpgme_selftest)
94     return TRACE_ERR (gpgme_error (_gpgme_selftest));
95
96   if (!r_ctx)
97     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
98
99   ctx = calloc (1, sizeof *ctx);
100   if (!ctx)
101     return TRACE_ERR (gpg_error_from_syserror ());
102
103   INIT_LOCK (ctx->lock);
104
105   err = _gpgme_engine_info_copy (&ctx->engine_info);
106   if (!err && !ctx->engine_info)
107     err = gpg_error (GPG_ERR_NO_ENGINE);
108   if (err)
109     {
110       free (ctx);
111       return TRACE_ERR (err);
112     }
113
114   ctx->keylist_mode = GPGME_KEYLIST_MODE_LOCAL;
115   ctx->include_certs = GPGME_INCLUDE_CERTS_DEFAULT;
116   ctx->protocol = GPGME_PROTOCOL_OpenPGP;
117   ctx->sub_protocol = GPGME_PROTOCOL_DEFAULT;
118   _gpgme_fd_table_init (&ctx->fdt);
119
120   LOCK (def_lc_lock);
121   if (def_lc_ctype)
122     {
123       ctx->lc_ctype = strdup (def_lc_ctype);
124       if (!ctx->lc_ctype)
125         {
126           int saved_err = gpg_error_from_syserror ();
127           UNLOCK (def_lc_lock);
128           _gpgme_engine_info_release (ctx->engine_info);
129           free (ctx);
130           return TRACE_ERR (saved_err);
131         }
132     }
133   else
134     def_lc_ctype = NULL;
135
136   if (def_lc_messages)
137     {
138       ctx->lc_messages = strdup (def_lc_messages);
139       if (!ctx->lc_messages)
140         {
141           int saved_err = gpg_error_from_syserror ();
142           UNLOCK (def_lc_lock);
143           if (ctx->lc_ctype)
144             free (ctx->lc_ctype);
145           _gpgme_engine_info_release (ctx->engine_info);
146           free (ctx);
147           return TRACE_ERR (saved_err);
148         }
149     }
150   else
151     def_lc_messages = NULL;
152   UNLOCK (def_lc_lock);
153
154   *r_ctx = ctx;
155
156   return TRACE_SUC1 ("ctx=%p", ctx);
157 }
158
159
160 gpgme_error_t
161 _gpgme_cancel_with_err (gpgme_ctx_t ctx, gpg_error_t ctx_err,
162                         gpg_error_t op_err)
163 {
164   gpgme_error_t err;
165   struct gpgme_io_event_done_data data;
166
167   TRACE_BEG2 (DEBUG_CTX, "_gpgme_cancel_with_err", ctx, "ctx_err=%i, op_err=%i",
168               ctx_err, op_err);
169
170   if (ctx_err)
171     {
172       err = _gpgme_engine_cancel (ctx->engine);
173       if (err)
174         return TRACE_ERR (err);
175     }
176   else
177     {
178       err = _gpgme_engine_cancel_op (ctx->engine);
179       if (err)
180         return TRACE_ERR (err);
181     }
182
183   data.err = ctx_err;
184   data.op_err = op_err;
185
186   _gpgme_engine_io_event (ctx->engine, GPGME_EVENT_DONE, &data);
187
188   return TRACE_ERR (0);
189 }
190
191
192 /* Cancel a pending asynchronous operation.  */
193 gpgme_error_t
194 gpgme_cancel (gpgme_ctx_t ctx)
195 {
196   gpg_error_t err;
197
198   TRACE_BEG (DEBUG_CTX, "gpgme_cancel", ctx);
199
200   if (!ctx)
201     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
202
203   err = _gpgme_cancel_with_err (ctx, gpg_error (GPG_ERR_CANCELED), 0);
204
205   return TRACE_ERR (err);
206 }
207
208
209 /* Cancel a pending operation asynchronously.  */
210 gpgme_error_t
211 gpgme_cancel_async (gpgme_ctx_t ctx)
212 {
213   TRACE_BEG (DEBUG_CTX, "gpgme_cancel_async", ctx);
214
215   if (!ctx)
216     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
217
218   LOCK (ctx->lock);
219   ctx->canceled = 1;
220   UNLOCK (ctx->lock);
221
222   return TRACE_ERR (0);
223 }
224
225
226 /* Release all resources associated with the given context.  */
227 void
228 gpgme_release (gpgme_ctx_t ctx)
229 {
230   TRACE (DEBUG_CTX, "gpgme_release", ctx);
231
232   if (!ctx)
233     return;
234
235   _gpgme_engine_release (ctx->engine);
236   ctx->engine = NULL;
237   _gpgme_fd_table_deinit (&ctx->fdt);
238   _gpgme_release_result (ctx);
239   _gpgme_signers_clear (ctx);
240   _gpgme_sig_notation_clear (ctx);
241   if (ctx->signers)
242     free (ctx->signers);
243   if (ctx->lc_ctype)
244     free (ctx->lc_ctype);
245   if (ctx->lc_messages)
246     free (ctx->lc_messages);
247   _gpgme_engine_info_release (ctx->engine_info);
248   ctx->engine_info = NULL;
249   DESTROY_LOCK (ctx->lock);
250   free (ctx);
251 }
252
253
254 void
255 gpgme_result_ref (void *result)
256 {
257   struct ctx_op_data *data;
258
259   if (! result)
260     return;
261
262   data = (void*)((char*)result - sizeof (struct ctx_op_data));
263
264   assert (data->magic == CTX_OP_DATA_MAGIC);
265
266   LOCK (result_ref_lock);
267   data->references++;
268   UNLOCK (result_ref_lock);
269 }
270
271
272 void
273 gpgme_result_unref (void *result)
274 {
275   struct ctx_op_data *data;
276
277   if (! result)
278     return;
279
280   data = (void*)((char*)result - sizeof (struct ctx_op_data));
281
282   assert (data->magic == CTX_OP_DATA_MAGIC);
283
284   LOCK (result_ref_lock);
285   if (--data->references)
286     {
287       UNLOCK (result_ref_lock);
288       return;
289     }
290   UNLOCK (result_ref_lock);
291
292   if (data->cleanup)
293     (*data->cleanup) (data->hook);
294   free (data);
295 }
296
297
298 void
299 _gpgme_release_result (gpgme_ctx_t ctx)
300 {
301   struct ctx_op_data *data = ctx->op_data;
302
303   while (data)
304     {
305       struct ctx_op_data *next_data = data->next;
306       data->next = NULL;
307       gpgme_result_unref (data->hook);
308       data = next_data;
309     }
310   ctx->op_data = NULL;
311 }
312
313
314 gpgme_error_t
315 gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t protocol)
316 {
317   TRACE_BEG2 (DEBUG_CTX, "gpgme_set_protocol", ctx, "protocol=%i (%s)",
318               protocol, gpgme_get_protocol_name (protocol)
319               ? gpgme_get_protocol_name (protocol) : "invalid");
320
321   if (protocol != GPGME_PROTOCOL_OpenPGP
322       && protocol != GPGME_PROTOCOL_CMS
323       && protocol != GPGME_PROTOCOL_GPGCONF
324       && protocol != GPGME_PROTOCOL_ASSUAN
325       && protocol != GPGME_PROTOCOL_G13
326       && protocol != GPGME_PROTOCOL_UISERVER
327       && protocol != GPGME_PROTOCOL_SPAWN)
328     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
329
330   if (!ctx)
331     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
332
333   if (ctx->protocol != protocol)
334     {
335       /* Shut down the engine when switching protocols.  */
336       if (ctx->engine)
337         {
338           TRACE_LOG1 ("releasing ctx->engine=%p", ctx->engine);
339           _gpgme_engine_release (ctx->engine);
340           ctx->engine = NULL;
341         }
342
343       ctx->protocol = protocol;
344     }
345   return TRACE_ERR (0);
346 }
347
348
349 gpgme_protocol_t
350 gpgme_get_protocol (gpgme_ctx_t ctx)
351 {
352   TRACE2 (DEBUG_CTX, "gpgme_get_protocol", ctx,
353           "ctx->protocol=%i (%s)", ctx->protocol,
354           gpgme_get_protocol_name (ctx->protocol)
355           ? gpgme_get_protocol_name (ctx->protocol) : "invalid");
356
357   return ctx->protocol;
358 }
359
360
361 gpgme_error_t
362 gpgme_set_sub_protocol (gpgme_ctx_t ctx, gpgme_protocol_t protocol)
363 {
364   TRACE2 (DEBUG_CTX, "gpgme_set_sub_protocol", ctx, "protocol=%i (%s)",
365           protocol, gpgme_get_protocol_name (protocol)
366           ? gpgme_get_protocol_name (protocol) : "invalid");
367
368   if (!ctx)
369     return gpg_error (GPG_ERR_INV_VALUE);
370
371   ctx->sub_protocol = protocol;
372   return 0;
373 }
374
375
376 gpgme_protocol_t
377 gpgme_get_sub_protocol (gpgme_ctx_t ctx)
378 {
379   TRACE2 (DEBUG_CTX, "gpgme_get_sub_protocol", ctx,
380           "ctx->sub_protocol=%i (%s)", ctx->sub_protocol,
381           gpgme_get_protocol_name (ctx->sub_protocol)
382           ? gpgme_get_protocol_name (ctx->sub_protocol) : "invalid");
383
384   return ctx->sub_protocol;
385 }
386
387
388 const char *
389 gpgme_get_protocol_name (gpgme_protocol_t protocol)
390 {
391   switch (protocol)
392     {
393     case GPGME_PROTOCOL_OpenPGP:
394       return "OpenPGP";
395
396     case GPGME_PROTOCOL_CMS:
397       return "CMS";
398
399     case GPGME_PROTOCOL_GPGCONF:
400       return "GPGCONF";
401
402     case GPGME_PROTOCOL_ASSUAN:
403       return "Assuan";
404
405     case GPGME_PROTOCOL_G13:
406       return "G13";
407
408     case GPGME_PROTOCOL_UISERVER:
409       return "UIServer";
410
411     case GPGME_PROTOCOL_SPAWN:
412       return "Spawn";
413
414     case GPGME_PROTOCOL_DEFAULT:
415       return "default";
416
417     case GPGME_PROTOCOL_UNKNOWN:
418       return "unknown";
419
420     default:
421       return NULL;
422     }
423 }
424
425 /* Enable or disable the use of an ascii armor for all output.  */
426 void
427 gpgme_set_armor (gpgme_ctx_t ctx, int use_armor)
428 {
429   TRACE2 (DEBUG_CTX, "gpgme_set_armor", ctx, "use_armor=%i (%s)",
430           use_armor, use_armor ? "yes" : "no");
431
432   if (!ctx)
433     return;
434
435   ctx->use_armor = use_armor;
436 }
437
438
439 /* Return the state of the armor flag.  */
440 int
441 gpgme_get_armor (gpgme_ctx_t ctx)
442 {
443   TRACE2 (DEBUG_CTX, "gpgme_get_armor", ctx, "ctx->use_armor=%i (%s)",
444           ctx->use_armor, ctx->use_armor ? "yes" : "no");
445   return ctx->use_armor;
446 }
447
448
449 /* Enable or disable the use of the special textmode.  Textmode is for
450   example used for the RFC2015 signatures; note that the updated RFC
451   3156 mandates that the MUA does some preparations so that textmode
452   is not needed anymore.  */
453 void
454 gpgme_set_textmode (gpgme_ctx_t ctx, int use_textmode)
455 {
456   TRACE2 (DEBUG_CTX, "gpgme_set_textmode", ctx, "use_textmode=%i (%s)",
457           use_textmode, use_textmode ? "yes" : "no");
458
459   if (!ctx)
460     return;
461
462   ctx->use_textmode = use_textmode;
463 }
464
465 /* Return the state of the textmode flag.  */
466 int
467 gpgme_get_textmode (gpgme_ctx_t ctx)
468 {
469   TRACE2 (DEBUG_CTX, "gpgme_get_textmode", ctx, "ctx->use_textmode=%i (%s)",
470           ctx->use_textmode, ctx->use_textmode ? "yes" : "no");
471   return ctx->use_textmode;
472 }
473
474
475 /* Enable offline mode for this context. In offline mode dirmngr
476   will be disabled. */
477 void
478 gpgme_set_offline (gpgme_ctx_t ctx, int offline)
479 {
480   TRACE2 (DEBUG_CTX, "gpgme_set_offline", ctx, "offline=%i (%s)",
481           offline, offline ? "yes" : "no");
482
483   if (!ctx)
484     return;
485
486   ctx->offline = offline;
487 }
488
489 /* Return the state of the offline flag.  */
490 int
491 gpgme_get_offline (gpgme_ctx_t ctx)
492 {
493   TRACE2 (DEBUG_CTX, "gpgme_get_offline", ctx, "ctx->offline=%i (%s)",
494           ctx->offline, ctx->offline ? "yes" : "no");
495   return ctx->offline;
496 }
497
498
499 /* Set the number of certifications to include in an S/MIME message.
500    The default is GPGME_INCLUDE_CERTS_DEFAULT.  -1 means all certs,
501    and -2 means all certs except the root cert.  */
502 void
503 gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs)
504 {
505   if (!ctx)
506     return;
507
508   if (nr_of_certs == GPGME_INCLUDE_CERTS_DEFAULT)
509     ctx->include_certs = GPGME_INCLUDE_CERTS_DEFAULT;
510   else if (nr_of_certs < -2)
511     ctx->include_certs = -2;
512   else
513     ctx->include_certs = nr_of_certs;
514
515   TRACE2 (DEBUG_CTX, "gpgme_set_include_certs", ctx, "nr_of_certs=%i%s",
516           nr_of_certs, nr_of_certs == ctx->include_certs ? "" : " (-2)");
517 }
518
519
520 /* Get the number of certifications to include in an S/MIME
521    message.  */
522 int
523 gpgme_get_include_certs (gpgme_ctx_t ctx)
524 {
525   TRACE1 (DEBUG_CTX, "gpgme_get_include_certs", ctx, "ctx->include_certs=%i",
526           ctx->include_certs);
527   return ctx->include_certs;
528 }
529
530
531 /* This function changes the default behaviour of the keylisting
532    functions.  MODE is a bitwise-OR of the GPGME_KEYLIST_* flags.  The
533    default mode is GPGME_KEYLIST_MODE_LOCAL.  */
534 gpgme_error_t
535 gpgme_set_keylist_mode (gpgme_ctx_t ctx, gpgme_keylist_mode_t mode)
536 {
537   TRACE1 (DEBUG_CTX, "gpgme_set_keylist_mode", ctx, "keylist_mode=0x%x",
538           mode);
539
540   if (!ctx)
541     return gpg_error (GPG_ERR_INV_VALUE);
542
543   ctx->keylist_mode = mode;
544   return 0;
545 }
546
547 /* This function returns the default behaviour of the keylisting
548    functions.  */
549 gpgme_keylist_mode_t
550 gpgme_get_keylist_mode (gpgme_ctx_t ctx)
551 {
552   TRACE1 (DEBUG_CTX, "gpgme_get_keylist_mode", ctx,
553           "ctx->keylist_mode=0x%x", ctx->keylist_mode);
554   return ctx->keylist_mode;
555 }
556
557
558 /* Set the pinentry mode for CTX to MODE. */
559 gpgme_error_t
560 gpgme_set_pinentry_mode (gpgme_ctx_t ctx, gpgme_pinentry_mode_t mode)
561 {
562   TRACE1 (DEBUG_CTX, "gpgme_set_pinentry_mode", ctx, "pinentry_mode=%u",
563           (unsigned int)mode);
564
565   if (!ctx)
566     return gpg_error (GPG_ERR_INV_VALUE);
567
568   switch (mode)
569     {
570     case GPGME_PINENTRY_MODE_DEFAULT:
571     case GPGME_PINENTRY_MODE_ASK:
572     case GPGME_PINENTRY_MODE_CANCEL:
573     case GPGME_PINENTRY_MODE_ERROR:
574     case GPGME_PINENTRY_MODE_LOOPBACK:
575       break;
576     default:
577       return gpg_error (GPG_ERR_INV_VALUE);
578     }
579
580   ctx->pinentry_mode = mode;
581   return 0;
582 }
583
584
585 /* Get the pinentry mode of CTX.  */
586 gpgme_pinentry_mode_t
587 gpgme_get_pinentry_mode (gpgme_ctx_t ctx)
588 {
589   TRACE1 (DEBUG_CTX, "gpgme_get_pinentry_mode", ctx,
590           "ctx->pinentry_mode=%u", (unsigned int)ctx->pinentry_mode);
591   return ctx->pinentry_mode;
592 }
593
594
595 /* This function sets a callback function to be used to pass a
596    passphrase to gpg.  */
597 void
598 gpgme_set_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t cb,
599                          void *cb_value)
600 {
601   TRACE2 (DEBUG_CTX, "gpgme_set_passphrase_cb", ctx,
602           "passphrase_cb=%p/%p", cb, cb_value);
603
604   if (!ctx)
605     return;
606
607   ctx->passphrase_cb = cb;
608   ctx->passphrase_cb_value = cb_value;
609 }
610
611
612 /* This function returns the callback function to be used to pass a
613    passphrase to the crypto engine.  */
614 void
615 gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *r_cb,
616                          void **r_cb_value)
617 {
618   TRACE2 (DEBUG_CTX, "gpgme_get_passphrase_cb", ctx,
619           "ctx->passphrase_cb=%p/%p",
620           ctx->passphrase_cb, ctx->passphrase_cb_value);
621   if (r_cb)
622     *r_cb = ctx->passphrase_cb;
623   if (r_cb_value)
624     *r_cb_value = ctx->passphrase_cb_value;
625 }
626
627
628 /* This function sets a callback function to be used as a progress
629    indicator.  */
630 void
631 gpgme_set_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t cb, void *cb_value)
632 {
633   TRACE2 (DEBUG_CTX, "gpgme_set_progress_cb", ctx, "progress_cb=%p/%p",
634           cb, cb_value);
635
636   if (!ctx)
637     return;
638
639   ctx->progress_cb = cb;
640   ctx->progress_cb_value = cb_value;
641 }
642
643
644 /* This function returns the callback function to be used as a
645    progress indicator.  */
646 void
647 gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *r_cb,
648                        void **r_cb_value)
649 {
650   TRACE2 (DEBUG_CTX, "gpgme_get_progress_cb", ctx, "ctx->progress_cb=%p/%p",
651           ctx->progress_cb, ctx->progress_cb_value);
652   if (r_cb)
653     *r_cb = ctx->progress_cb;
654   if (r_cb_value)
655     *r_cb_value = ctx->progress_cb_value;
656 }
657
658
659 /* This function sets a callback function to be used as a status
660    message forwarder.  */
661 void
662 gpgme_set_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t cb, void *cb_value)
663 {
664   TRACE2 (DEBUG_CTX, "gpgme_set_status_cb", ctx, "status_cb=%p/%p",
665           cb, cb_value);
666
667   if (!ctx)
668     return;
669
670   ctx->status_cb = cb;
671   ctx->status_cb_value = cb_value;
672 }
673
674
675 /* This function returns the callback function to be used as a
676    status message forwarder.  */
677 void
678 gpgme_get_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t *r_cb,
679                        void **r_cb_value)
680 {
681   TRACE2 (DEBUG_CTX, "gpgme_get_status_cb", ctx, "ctx->status_cb=%p/%p",
682           ctx ? ctx->status_cb : NULL, ctx ? ctx->status_cb_value : NULL);
683
684   if (r_cb)
685     *r_cb = NULL;
686
687   if (r_cb_value)
688     *r_cb_value = NULL;
689
690   if (!ctx || !ctx->status_cb)
691     return;
692
693   if (r_cb)
694     *r_cb = ctx->status_cb;
695   if (r_cb_value)
696     *r_cb_value = ctx->status_cb_value;
697 }
698
699
700 /* Set the I/O callback functions for CTX to IO_CBS.  */
701 void
702 gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs)
703 {
704   if (!ctx)
705     return;
706
707   if (io_cbs)
708     {
709       TRACE6 (DEBUG_CTX, "gpgme_set_io_cbs", ctx,
710               "io_cbs=%p (add=%p/%p, remove=%p, event=%p/%p",
711               io_cbs, io_cbs->add, io_cbs->add_priv, io_cbs->remove,
712               io_cbs->event, io_cbs->event_priv);
713       ctx->io_cbs = *io_cbs;
714     }
715   else
716     {
717       TRACE1 (DEBUG_CTX, "gpgme_set_io_cbs", ctx,
718               "io_cbs=%p (default)", io_cbs);
719       ctx->io_cbs.add = NULL;
720       ctx->io_cbs.add_priv = NULL;
721       ctx->io_cbs.remove = NULL;
722       ctx->io_cbs.event = NULL;
723       ctx->io_cbs.event_priv = NULL;
724     }
725 }
726
727
728 /* This function provides access to the internal read function; it is
729    normally not used.  */
730 gpgme_ssize_t
731 gpgme_io_read (int fd, void *buffer, size_t count)
732 {
733   int ret;
734   TRACE_BEG2 (DEBUG_GLOBAL, "gpgme_io_read", fd,
735               "buffer=%p, count=%u", buffer, count);
736
737   ret = _gpgme_io_read (fd, buffer, count);
738
739   return TRACE_SYSRES (ret);
740 }
741
742
743 /* This function provides access to the internal write function.  It
744    is to be used by user callbacks to return data to gpgme.  See
745    gpgme_passphrase_cb_t and gpgme_edit_cb_t.  */
746 gpgme_ssize_t
747 gpgme_io_write (int fd, const void *buffer, size_t count)
748 {
749   int ret;
750   TRACE_BEG2 (DEBUG_GLOBAL, "gpgme_io_write", fd,
751               "buffer=%p, count=%u", buffer, count);
752
753   ret = _gpgme_io_write (fd, buffer, count);
754
755   return TRACE_SYSRES (ret);
756 }
757
758 /* This function provides access to the internal write function.  It
759    is to be used by user callbacks to return data to gpgme.  See
760    gpgme_passphrase_cb_t and gpgme_edit_cb_t.  Note that this is a
761    variant of gpgme_io_write which guarantees that all COUNT bytes are
762    written or an error is return.  Returns: 0 on success or -1 on
763    error and the sets errno. */
764 int
765 gpgme_io_writen (int fd, const void *buffer_arg, size_t count)
766 {
767   const char *buffer = buffer_arg;
768   int ret = 0;
769   TRACE_BEG2 (DEBUG_GLOBAL, "gpgme_io_writen", fd,
770               "buffer=%p, count=%u", buffer, count);
771   while (count)
772     {
773       ret = _gpgme_io_write (fd, buffer, count);
774       if (ret < 0)
775         break;
776       buffer += ret;
777       count -= ret;
778       ret = 0;
779     }
780   return TRACE_SYSRES (ret);
781 }
782
783
784 /* This function returns the callback function for I/O.  */
785 void
786 gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs)
787 {
788   TRACE6 (DEBUG_CTX, "gpgme_get_io_cbs", ctx,
789           "io_cbs=%p, ctx->io_cbs.add=%p/%p, .remove=%p, .event=%p/%p",
790           io_cbs, io_cbs->add, io_cbs->add_priv, io_cbs->remove,
791           io_cbs->event, io_cbs->event_priv);
792
793   *io_cbs = ctx->io_cbs;
794 }
795
796 \f
797 /* This function sets the locale for the context CTX, or the default
798    locale if CTX is a null pointer.  */
799 gpgme_error_t
800 gpgme_set_locale (gpgme_ctx_t ctx, int category, const char *value)
801 {
802   int failed = 0;
803   char *new_lc_ctype = NULL;
804   char *new_lc_messages = NULL;
805
806   TRACE_BEG2 (DEBUG_CTX, "gpgme_set_locale", ctx,
807                "category=%i, value=%s", category, value ? value : "(null)");
808
809 #define PREPARE_ONE_LOCALE(lcat, ucat)                          \
810   if (!failed && value                                          \
811       && (category == LC_ALL || category == LC_ ## ucat))       \
812     {                                                           \
813       new_lc_ ## lcat = strdup (value);                         \
814       if (!new_lc_ ## lcat)                                     \
815         failed = 1;                                             \
816     }
817
818 #ifdef LC_CTYPE
819   PREPARE_ONE_LOCALE (ctype, CTYPE);
820 #endif
821 #ifdef LC_MESSAGES
822   PREPARE_ONE_LOCALE (messages, MESSAGES);
823 #endif
824
825   if (failed)
826     {
827       int saved_err = gpg_error_from_syserror ();
828
829       if (new_lc_ctype)
830         free (new_lc_ctype);
831       if (new_lc_messages)
832         free (new_lc_messages);
833
834       return TRACE_ERR (saved_err);
835     }
836
837 #define SET_ONE_LOCALE(lcat, ucat)                      \
838   if (category == LC_ALL || category == LC_ ## ucat)    \
839     {                                                   \
840       if (ctx)                                          \
841         {                                               \
842           if (ctx->lc_ ## lcat)                         \
843             free (ctx->lc_ ## lcat);                    \
844           ctx->lc_ ## lcat = new_lc_ ## lcat;           \
845         }                                               \
846       else                                              \
847         {                                               \
848           if (def_lc_ ## lcat)                          \
849             free (def_lc_ ## lcat);                     \
850           def_lc_ ## lcat = new_lc_ ## lcat;            \
851         }                                               \
852     }
853
854   if (!ctx)
855     LOCK (def_lc_lock);
856 #ifdef LC_CTYPE
857   SET_ONE_LOCALE (ctype, CTYPE);
858 #endif
859 #ifdef LC_MESSAGES
860   SET_ONE_LOCALE (messages, MESSAGES);
861 #endif
862   if (!ctx)
863     UNLOCK (def_lc_lock);
864
865   return TRACE_ERR (0);
866 }
867
868 \f
869 /* Get the information about the configured engines.  A pointer to the
870    first engine in the statically allocated linked list is returned.
871    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
872 gpgme_engine_info_t
873 gpgme_ctx_get_engine_info (gpgme_ctx_t ctx)
874 {
875   TRACE1 (DEBUG_CTX, "gpgme_ctx_get_engine_info", ctx,
876           "ctx->engine_info=%p", ctx->engine_info);
877   return ctx->engine_info;
878 }
879
880
881 /* Set the engine info for the context CTX, protocol PROTO, to the
882    file name FILE_NAME and the home directory HOME_DIR.  */
883 gpgme_error_t
884 gpgme_ctx_set_engine_info (gpgme_ctx_t ctx, gpgme_protocol_t proto,
885                            const char *file_name, const char *home_dir)
886 {
887   gpgme_error_t err;
888   TRACE_BEG4 (DEBUG_CTX, "gpgme_ctx_set_engine_info", ctx,
889               "protocol=%i (%s), file_name=%s, home_dir=%s",
890               proto, gpgme_get_protocol_name (proto)
891               ? gpgme_get_protocol_name (proto) : "unknown",
892               file_name ? file_name : "(default)",
893               home_dir ? home_dir : "(default)");
894
895   if (!ctx)
896     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
897
898   /* Shut down the engine when changing engine info.  */
899   if (ctx->engine)
900     {
901       TRACE_LOG1 ("releasing ctx->engine=%p", ctx->engine);
902       _gpgme_engine_release (ctx->engine);
903       ctx->engine = NULL;
904     }
905   err = _gpgme_set_engine_info (ctx->engine_info, proto,
906                                 file_name, home_dir);
907   return TRACE_ERR (err);
908 }
909
910 \f
911 /* Clear all notation data from the context.  */
912 void
913 _gpgme_sig_notation_clear (gpgme_ctx_t ctx)
914 {
915   gpgme_sig_notation_t notation;
916
917   if (!ctx)
918     return;
919
920   notation = ctx->sig_notations;
921   while (notation)
922     {
923       gpgme_sig_notation_t next_notation = notation->next;
924       _gpgme_sig_notation_free (notation);
925       notation = next_notation;
926     }
927   ctx->sig_notations = NULL;
928 }
929
930 void
931 gpgme_sig_notation_clear (gpgme_ctx_t ctx)
932 {
933   TRACE (DEBUG_CTX, "gpgme_sig_notation_clear", ctx);
934
935   if (!ctx)
936     return;
937
938   _gpgme_sig_notation_clear (ctx);
939 }
940
941
942 /* Add the human-readable notation data with name NAME and value VALUE
943    to the context CTX, using the flags FLAGS.  If NAME is NULL, then
944    VALUE should be a policy URL.  The flag
945    GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
946    data, and false for policy URLs.  */
947 gpgme_error_t
948 gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
949                         const char *value, gpgme_sig_notation_flags_t flags)
950 {
951   gpgme_error_t err;
952   gpgme_sig_notation_t notation;
953   gpgme_sig_notation_t *lastp;
954
955   TRACE_BEG3 (DEBUG_CTX, "gpgme_sig_notation_add", ctx,
956               "name=%s, value=%s, flags=0x%x",
957               name ? name : "(null)", value ? value : "(null)",
958               flags);
959
960   if (!ctx)
961     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
962
963   if (name)
964     flags |= GPGME_SIG_NOTATION_HUMAN_READABLE;
965   else
966     flags &= ~GPGME_SIG_NOTATION_HUMAN_READABLE;
967
968   err = _gpgme_sig_notation_create (&notation, name, name ? strlen (name) : 0,
969                                     value, value ? strlen (value) : 0, flags);
970   if (err)
971     return TRACE_ERR (err);
972
973   lastp = &ctx->sig_notations;
974   while (*lastp)
975     lastp = &(*lastp)->next;
976
977   *lastp = notation;
978   return TRACE_ERR (0);
979 }
980
981
982 /* Get the sig notations for this context.  */
983 gpgme_sig_notation_t
984 gpgme_sig_notation_get (gpgme_ctx_t ctx)
985 {
986   if (!ctx)
987     {
988       TRACE (DEBUG_CTX, "gpgme_sig_notation_get", ctx);
989       return NULL;
990     }
991   TRACE1 (DEBUG_CTX, "gpgme_sig_notation_get", ctx,
992           "ctx->sig_notations=%p", ctx->sig_notations);
993
994   return ctx->sig_notations;
995 }
996
997
998 \f
999 /* Return a public key algorithm string made of the algorithm and size
1000    or the curve name.  May return NULL on error.  Caller must free the
1001    result using gpgme_free.  */
1002 char *
1003 gpgme_pubkey_algo_string (gpgme_subkey_t subkey)
1004 {
1005   const char *prefix = NULL;
1006   char *result;
1007
1008   if (!subkey)
1009     {
1010       gpg_err_set_errno (EINVAL);
1011       return NULL;
1012     }
1013
1014   switch (subkey->pubkey_algo)
1015     {
1016     case GPGME_PK_RSA:
1017     case GPGME_PK_RSA_E:
1018     case GPGME_PK_RSA_S: prefix = "rsa"; break;
1019     case GPGME_PK_ELG_E: prefix = "elg"; break;
1020     case GPGME_PK_DSA:   prefix = "dsa"; break;
1021     case GPGME_PK_ELG:   prefix = "xxx"; break;
1022     case GPGME_PK_ECC:
1023     case GPGME_PK_ECDH:
1024     case GPGME_PK_ECDSA:
1025     case GPGME_PK_EDDSA: prefix = "";    break;
1026     }
1027
1028   if (prefix && *prefix)
1029     {
1030       char buffer[40];
1031       snprintf (buffer, sizeof buffer, "%s%u", prefix, subkey->length);
1032       result = strdup (buffer);
1033     }
1034   else if (prefix && subkey->curve && *subkey->curve)
1035     result = strdup (subkey->curve);
1036   else if (prefix)
1037     result =  strdup ("E_error");
1038   else
1039     result = strdup  ("unknown");
1040
1041   return result;
1042 }
1043
1044
1045 const char *
1046 gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo)
1047 {
1048   switch (algo)
1049     {
1050     case GPGME_PK_RSA:   return "RSA";
1051     case GPGME_PK_RSA_E: return "RSA-E";
1052     case GPGME_PK_RSA_S: return "RSA-S";
1053     case GPGME_PK_ELG_E: return "ELG-E";
1054     case GPGME_PK_DSA:   return "DSA";
1055     case GPGME_PK_ECC:   return "ECC";
1056     case GPGME_PK_ELG:   return "ELG";
1057     case GPGME_PK_ECDSA: return "ECDSA";
1058     case GPGME_PK_ECDH:  return "ECDH";
1059     case GPGME_PK_EDDSA: return "EdDSA";
1060     default:             return NULL;
1061     }
1062 }
1063
1064
1065 const char *
1066 gpgme_hash_algo_name (gpgme_hash_algo_t algo)
1067 {
1068   switch (algo)
1069     {
1070     case GPGME_MD_MD5:
1071       return "MD5";
1072
1073     case GPGME_MD_SHA1:
1074       return "SHA1";
1075
1076     case GPGME_MD_RMD160:
1077       return "RIPEMD160";
1078
1079     case GPGME_MD_MD2:
1080       return "MD2";
1081
1082     case GPGME_MD_TIGER:
1083       return "TIGER192";
1084
1085     case GPGME_MD_HAVAL:
1086       return "HAVAL";
1087
1088     case GPGME_MD_SHA256:
1089       return "SHA256";
1090
1091     case GPGME_MD_SHA384:
1092       return "SHA384";
1093
1094     case GPGME_MD_SHA512:
1095       return "SHA512";
1096
1097     case GPGME_MD_SHA224:
1098       return "SHA224";
1099
1100     case GPGME_MD_MD4:
1101       return "MD4";
1102
1103     case GPGME_MD_CRC32:
1104       return "CRC32";
1105
1106     case GPGME_MD_CRC32_RFC1510:
1107       return "CRC32RFC1510";
1108
1109     case GPGME_MD_CRC24_RFC2440:
1110       return "CRC24RFC2440";
1111
1112     default:
1113       return NULL;
1114     }
1115 }