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