doc: Remove cruft from a doc entry.
[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 /* Note that setting the protocol will intentionally not fail if the
324  * engine is not available.  */
325 gpgme_error_t
326 gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t protocol)
327 {
328   TRACE_BEG  (DEBUG_CTX, "gpgme_set_protocol", ctx, "protocol=%i (%s)",
329               protocol, gpgme_get_protocol_name (protocol)
330               ? gpgme_get_protocol_name (protocol) : "invalid");
331
332   if (protocol != GPGME_PROTOCOL_OpenPGP
333       && protocol != GPGME_PROTOCOL_CMS
334       && protocol != GPGME_PROTOCOL_GPGCONF
335       && protocol != GPGME_PROTOCOL_ASSUAN
336       && protocol != GPGME_PROTOCOL_G13
337       && protocol != GPGME_PROTOCOL_UISERVER
338       && protocol != GPGME_PROTOCOL_SPAWN)
339     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
340
341   if (!ctx)
342     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
343
344   if (ctx->protocol != protocol)
345     {
346       /* Shut down the engine when switching protocols.  */
347       if (ctx->engine)
348         {
349           TRACE_LOG  ("releasing ctx->engine=%p", ctx->engine);
350           _gpgme_engine_release (ctx->engine);
351           ctx->engine = NULL;
352         }
353
354       ctx->protocol = protocol;
355     }
356   return TRACE_ERR (0);
357 }
358
359
360 gpgme_protocol_t
361 gpgme_get_protocol (gpgme_ctx_t ctx)
362 {
363   TRACE (DEBUG_CTX, "gpgme_get_protocol", ctx,
364           "ctx->protocol=%i (%s)", ctx->protocol,
365           gpgme_get_protocol_name (ctx->protocol)
366           ? gpgme_get_protocol_name (ctx->protocol) : "invalid");
367
368   return ctx->protocol;
369 }
370
371
372 gpgme_error_t
373 gpgme_set_sub_protocol (gpgme_ctx_t ctx, gpgme_protocol_t protocol)
374 {
375   TRACE (DEBUG_CTX, "gpgme_set_sub_protocol", ctx, "protocol=%i (%s)",
376           protocol, gpgme_get_protocol_name (protocol)
377           ? gpgme_get_protocol_name (protocol) : "invalid");
378
379   if (!ctx)
380     return gpg_error (GPG_ERR_INV_VALUE);
381
382   ctx->sub_protocol = protocol;
383   return 0;
384 }
385
386
387 gpgme_protocol_t
388 gpgme_get_sub_protocol (gpgme_ctx_t ctx)
389 {
390   TRACE (DEBUG_CTX, "gpgme_get_sub_protocol", ctx,
391           "ctx->sub_protocol=%i (%s)", ctx->sub_protocol,
392           gpgme_get_protocol_name (ctx->sub_protocol)
393           ? gpgme_get_protocol_name (ctx->sub_protocol) : "invalid");
394
395   return ctx->sub_protocol;
396 }
397
398
399 const char *
400 gpgme_get_protocol_name (gpgme_protocol_t protocol)
401 {
402   switch (protocol)
403     {
404     case GPGME_PROTOCOL_OpenPGP:
405       return "OpenPGP";
406
407     case GPGME_PROTOCOL_CMS:
408       return "CMS";
409
410     case GPGME_PROTOCOL_GPGCONF:
411       return "GPGCONF";
412
413     case GPGME_PROTOCOL_ASSUAN:
414       return "Assuan";
415
416     case GPGME_PROTOCOL_G13:
417       return "G13";
418
419     case GPGME_PROTOCOL_UISERVER:
420       return "UIServer";
421
422     case GPGME_PROTOCOL_SPAWN:
423       return "Spawn";
424
425     case GPGME_PROTOCOL_DEFAULT:
426       return "default";
427
428     case GPGME_PROTOCOL_UNKNOWN:
429       return "unknown";
430
431     default:
432       return NULL;
433     }
434 }
435
436
437 /* Store the sender's address in the context.  ADDRESS is addr-spec of
438  * mailbox but my also be a complete mailbox, in which case this
439  * function extracts the addr-spec from it.  Returns 0 on success or
440  * an error code if no valid addr-spec could be extracted from
441  * ADDRESS.  */
442 gpgme_error_t
443 gpgme_set_sender (gpgme_ctx_t ctx, const char *address)
444 {
445   char *p = NULL;
446
447   TRACE_BEG  (DEBUG_CTX, "gpgme_set_sender", ctx, "sender='%s'",
448               address?address:"(null)");
449
450   if (!ctx || (address && !(p = _gpgme_mailbox_from_userid (address))))
451     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
452
453   free (ctx->sender);
454   ctx->sender = p;
455   return TRACE_ERR (0);
456 }
457
458
459 /* Return the sender's address (addr-spec part) from the context or
460  * NULL if none was set.  The returned value is valid as long as the
461  * CTX is valid and gpgme_set_sender has not been used.  */
462 const char *
463 gpgme_get_sender (gpgme_ctx_t ctx)
464 {
465   TRACE (DEBUG_CTX, "gpgme_get_sender", ctx, "sender='%s'",
466           ctx?ctx->sender:"");
467
468   return ctx->sender;
469 }
470
471
472 /* Enable or disable the use of an ascii armor for all output.  */
473 void
474 gpgme_set_armor (gpgme_ctx_t ctx, int use_armor)
475 {
476   TRACE (DEBUG_CTX, "gpgme_set_armor", ctx, "use_armor=%i (%s)",
477           use_armor, use_armor ? "yes" : "no");
478
479   if (!ctx)
480     return;
481
482   ctx->use_armor = !!use_armor;
483 }
484
485
486 /* Return the state of the armor flag.  */
487 int
488 gpgme_get_armor (gpgme_ctx_t ctx)
489 {
490   TRACE (DEBUG_CTX, "gpgme_get_armor", ctx, "ctx->use_armor=%i (%s)",
491           ctx->use_armor, ctx->use_armor ? "yes" : "no");
492   return ctx->use_armor;
493 }
494
495
496 /* Set the flag NAME for CTX to VALUE.  Please consult the manual for
497  * a description of the flags.
498  */
499 gpgme_error_t
500 gpgme_set_ctx_flag (gpgme_ctx_t ctx, const char *name, const char *value)
501 {
502   gpgme_error_t err = 0;
503   int abool;
504
505   TRACE (DEBUG_CTX, "gpgme_set_ctx_flag", ctx,
506           "name='%s' value='%s'",
507           name? name:"(null)", value?value:"(null)");
508
509   abool = (value && *value)? !!atoi (value) : 0;
510
511   if (!ctx || !name || !value)
512     err = gpg_error (GPG_ERR_INV_VALUE);
513   else if (!strcmp (name, "redraw"))
514     {
515       ctx->redraw_suggested = abool;
516     }
517   else if (!strcmp (name, "full-status"))
518     {
519       ctx->full_status = abool;
520     }
521   else if (!strcmp (name, "raw-description"))
522     {
523       ctx->raw_description = abool;
524     }
525   else if (!strcmp (name, "export-session-key"))
526     {
527       ctx->export_session_keys = abool;
528     }
529   else if (!strcmp (name, "override-session-key"))
530     {
531       free (ctx->override_session_key);
532       ctx->override_session_key = strdup (value);
533       if (!ctx->override_session_key)
534         err = gpg_error_from_syserror ();
535     }
536   else if (!strcmp (name, "auto-key-retrieve"))
537     {
538       ctx->auto_key_retrieve = abool;
539     }
540   else if (!strcmp (name, "request-origin"))
541     {
542       free (ctx->request_origin);
543       ctx->request_origin = strdup (value);
544       if (!ctx->request_origin)
545         err = gpg_error_from_syserror ();
546     }
547   else if (!strcmp (name, "no-symkey-cache"))
548     {
549       ctx->no_symkey_cache = abool;
550     }
551   else if (!strcmp (name, "ignore-mdc-error"))
552     {
553       ctx->ignore_mdc_error = abool;
554     }
555   else if (!strcmp (name, "auto-key-locate"))
556     {
557       free (ctx->auto_key_locate);
558       ctx->auto_key_locate = strdup (value);
559       if (!ctx->auto_key_locate)
560         err = gpg_error_from_syserror ();
561     }
562   else if (!strcmp (name, "trust-model"))
563     {
564       free (ctx->trust_model);
565       ctx->trust_model = strdup (value);
566       if (!ctx->trust_model)
567         err = gpg_error_from_syserror ();
568     }
569   else
570     err = gpg_error (GPG_ERR_UNKNOWN_NAME);
571
572   return err;
573 }
574
575
576 /* Get the context flag named NAME.  See gpgme_set_ctx_flag for a list
577  * of valid names.  If the NAME is unknown NULL is returned.  For a
578  * boolean flag an empty string is returned for False and the string
579  * "1" for True; thus either atoi or a simple string test can be
580  * used.  */
581 const char *
582 gpgme_get_ctx_flag (gpgme_ctx_t ctx, const char *name)
583 {
584   if (!ctx || !name)
585     return NULL;
586   else if (!strcmp (name, "redraw"))
587     {
588       return ctx->redraw_suggested? "1":"";
589     }
590   else if (!strcmp (name, "full-status"))
591     {
592       return ctx->full_status? "1":"";
593     }
594   else if (!strcmp (name, "raw-description"))
595     {
596       return ctx->raw_description? "1":"";
597     }
598   else if (!strcmp (name, "export-session-key"))
599     {
600       return ctx->export_session_keys? "1":"";
601     }
602   else if (!strcmp (name, "override-session-key"))
603     {
604       return ctx->override_session_key? ctx->override_session_key : "";
605     }
606   else if (!strcmp (name, "auto-key-retrieve"))
607     {
608       return ctx->auto_key_retrieve? "1":"";
609     }
610   else if (!strcmp (name, "request-origin"))
611     {
612       return ctx->request_origin? ctx->request_origin : "";
613     }
614   else if (!strcmp (name, "no-symkey-cache"))
615     {
616       return ctx->no_symkey_cache? "1":"";
617     }
618   else if (!strcmp (name, "ignore-mdc-error"))
619     {
620       return ctx->ignore_mdc_error? "1":"";
621     }
622   else if (!strcmp (name, "auto-key-locate"))
623     {
624       return ctx->auto_key_locate? ctx->auto_key_locate : "";
625     }
626   else
627     return NULL;
628 }
629
630
631 /* Enable or disable the use of the special textmode.  Textmode is for
632   example used for the RFC2015 signatures; note that the updated RFC
633   3156 mandates that the MUA does some preparations so that textmode
634   is not needed anymore.  */
635 void
636 gpgme_set_textmode (gpgme_ctx_t ctx, int use_textmode)
637 {
638   TRACE (DEBUG_CTX, "gpgme_set_textmode", ctx, "use_textmode=%i (%s)",
639           use_textmode, use_textmode ? "yes" : "no");
640
641   if (!ctx)
642     return;
643
644   ctx->use_textmode = !!use_textmode;
645 }
646
647 /* Return the state of the textmode flag.  */
648 int
649 gpgme_get_textmode (gpgme_ctx_t ctx)
650 {
651   TRACE (DEBUG_CTX, "gpgme_get_textmode", ctx, "ctx->use_textmode=%i (%s)",
652           ctx->use_textmode, ctx->use_textmode ? "yes" : "no");
653   return ctx->use_textmode;
654 }
655
656
657 /* Enable offline mode for this context. In offline mode dirmngr
658   will be disabled. */
659 void
660 gpgme_set_offline (gpgme_ctx_t ctx, int offline)
661 {
662   TRACE (DEBUG_CTX, "gpgme_set_offline", ctx, "offline=%i (%s)",
663           offline, offline ? "yes" : "no");
664
665   if (!ctx)
666     return;
667
668   ctx->offline = !!offline;
669 }
670
671 /* Return the state of the offline flag.  */
672 int
673 gpgme_get_offline (gpgme_ctx_t ctx)
674 {
675   TRACE (DEBUG_CTX, "gpgme_get_offline", ctx, "ctx->offline=%i (%s)",
676           ctx->offline, ctx->offline ? "yes" : "no");
677   return ctx->offline;
678 }
679
680
681 /* Set the number of certifications to include in an S/MIME message.
682    The default is GPGME_INCLUDE_CERTS_DEFAULT.  -1 means all certs,
683    and -2 means all certs except the root cert.  */
684 void
685 gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs)
686 {
687   if (!ctx)
688     return;
689
690   if (nr_of_certs == GPGME_INCLUDE_CERTS_DEFAULT)
691     ctx->include_certs = GPGME_INCLUDE_CERTS_DEFAULT;
692   else if (nr_of_certs < -2)
693     ctx->include_certs = -2;
694   else
695     ctx->include_certs = nr_of_certs;
696
697   TRACE (DEBUG_CTX, "gpgme_set_include_certs", ctx, "nr_of_certs=%i%s",
698           nr_of_certs, nr_of_certs == ctx->include_certs ? "" : " (-2)");
699 }
700
701
702 /* Get the number of certifications to include in an S/MIME
703    message.  */
704 int
705 gpgme_get_include_certs (gpgme_ctx_t ctx)
706 {
707   TRACE (DEBUG_CTX, "gpgme_get_include_certs", ctx, "ctx->include_certs=%i",
708           ctx->include_certs);
709   return ctx->include_certs;
710 }
711
712
713 /* This function changes the default behaviour of the keylisting
714    functions.  MODE is a bitwise-OR of the GPGME_KEYLIST_* flags.  The
715    default mode is GPGME_KEYLIST_MODE_LOCAL.  */
716 gpgme_error_t
717 gpgme_set_keylist_mode (gpgme_ctx_t ctx, gpgme_keylist_mode_t mode)
718 {
719   TRACE (DEBUG_CTX, "gpgme_set_keylist_mode", ctx, "keylist_mode=0x%x",
720           mode);
721
722   if (!ctx)
723     return gpg_error (GPG_ERR_INV_VALUE);
724
725   ctx->keylist_mode = mode;
726   return 0;
727 }
728
729 /* This function returns the default behaviour of the keylisting
730    functions.  */
731 gpgme_keylist_mode_t
732 gpgme_get_keylist_mode (gpgme_ctx_t ctx)
733 {
734   TRACE (DEBUG_CTX, "gpgme_get_keylist_mode", ctx,
735           "ctx->keylist_mode=0x%x", ctx->keylist_mode);
736   return ctx->keylist_mode;
737 }
738
739
740 /* Set the pinentry mode for CTX to MODE. */
741 gpgme_error_t
742 gpgme_set_pinentry_mode (gpgme_ctx_t ctx, gpgme_pinentry_mode_t mode)
743 {
744   TRACE (DEBUG_CTX, "gpgme_set_pinentry_mode", ctx, "pinentry_mode=%u",
745           (unsigned int)mode);
746
747   if (!ctx)
748     return gpg_error (GPG_ERR_INV_VALUE);
749
750   switch (mode)
751     {
752     case GPGME_PINENTRY_MODE_DEFAULT:
753     case GPGME_PINENTRY_MODE_ASK:
754     case GPGME_PINENTRY_MODE_CANCEL:
755     case GPGME_PINENTRY_MODE_ERROR:
756     case GPGME_PINENTRY_MODE_LOOPBACK:
757       break;
758     default:
759       return gpg_error (GPG_ERR_INV_VALUE);
760     }
761
762   ctx->pinentry_mode = mode;
763   return 0;
764 }
765
766
767 /* Get the pinentry mode of CTX.  */
768 gpgme_pinentry_mode_t
769 gpgme_get_pinentry_mode (gpgme_ctx_t ctx)
770 {
771   TRACE (DEBUG_CTX, "gpgme_get_pinentry_mode", ctx,
772           "ctx->pinentry_mode=%u", (unsigned int)ctx->pinentry_mode);
773   return ctx->pinentry_mode;
774 }
775
776
777 /* This function sets a callback function to be used to pass a
778    passphrase to gpg.  */
779 void
780 gpgme_set_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t cb,
781                          void *cb_value)
782 {
783   TRACE (DEBUG_CTX, "gpgme_set_passphrase_cb", ctx,
784           "passphrase_cb=%p/%p", cb, cb_value);
785
786   if (!ctx)
787     return;
788
789   ctx->passphrase_cb = cb;
790   ctx->passphrase_cb_value = cb_value;
791 }
792
793
794 /* This function returns the callback function to be used to pass a
795    passphrase to the crypto engine.  */
796 void
797 gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *r_cb,
798                          void **r_cb_value)
799 {
800   TRACE (DEBUG_CTX, "gpgme_get_passphrase_cb", ctx,
801           "ctx->passphrase_cb=%p/%p",
802           ctx->passphrase_cb, ctx->passphrase_cb_value);
803   if (r_cb)
804     *r_cb = ctx->passphrase_cb;
805   if (r_cb_value)
806     *r_cb_value = ctx->passphrase_cb_value;
807 }
808
809
810 /* This function sets a callback function to be used as a progress
811    indicator.  */
812 void
813 gpgme_set_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t cb, void *cb_value)
814 {
815   TRACE (DEBUG_CTX, "gpgme_set_progress_cb", ctx, "progress_cb=%p/%p",
816           cb, cb_value);
817
818   if (!ctx)
819     return;
820
821   ctx->progress_cb = cb;
822   ctx->progress_cb_value = cb_value;
823 }
824
825
826 /* This function returns the callback function to be used as a
827    progress indicator.  */
828 void
829 gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *r_cb,
830                        void **r_cb_value)
831 {
832   TRACE (DEBUG_CTX, "gpgme_get_progress_cb", ctx, "ctx->progress_cb=%p/%p",
833           ctx->progress_cb, ctx->progress_cb_value);
834   if (r_cb)
835     *r_cb = ctx->progress_cb;
836   if (r_cb_value)
837     *r_cb_value = ctx->progress_cb_value;
838 }
839
840
841 /* This function sets a callback function to be used as a status
842    message forwarder.  */
843 void
844 gpgme_set_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t cb, void *cb_value)
845 {
846   TRACE (DEBUG_CTX, "gpgme_set_status_cb", ctx, "status_cb=%p/%p",
847           cb, cb_value);
848
849   if (!ctx)
850     return;
851
852   ctx->status_cb = cb;
853   ctx->status_cb_value = cb_value;
854 }
855
856
857 /* This function returns the callback function to be used as a
858    status message forwarder.  */
859 void
860 gpgme_get_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t *r_cb,
861                        void **r_cb_value)
862 {
863   TRACE (DEBUG_CTX, "gpgme_get_status_cb", ctx, "ctx->status_cb=%p/%p",
864           ctx ? ctx->status_cb : NULL, ctx ? ctx->status_cb_value : NULL);
865
866   if (r_cb)
867     *r_cb = NULL;
868
869   if (r_cb_value)
870     *r_cb_value = NULL;
871
872   if (!ctx || !ctx->status_cb)
873     return;
874
875   if (r_cb)
876     *r_cb = ctx->status_cb;
877   if (r_cb_value)
878     *r_cb_value = ctx->status_cb_value;
879 }
880
881
882 /* Set the I/O callback functions for CTX to IO_CBS.  */
883 void
884 gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs)
885 {
886   if (!ctx)
887     return;
888
889   if (io_cbs)
890     {
891       TRACE (DEBUG_CTX, "gpgme_set_io_cbs", ctx,
892               "io_cbs=%p (add=%p/%p, remove=%p, event=%p/%p",
893               io_cbs, io_cbs->add, io_cbs->add_priv, io_cbs->remove,
894               io_cbs->event, io_cbs->event_priv);
895       ctx->io_cbs = *io_cbs;
896     }
897   else
898     {
899       TRACE (DEBUG_CTX, "gpgme_set_io_cbs", ctx,
900               "io_cbs=%p (default)", io_cbs);
901       ctx->io_cbs.add = NULL;
902       ctx->io_cbs.add_priv = NULL;
903       ctx->io_cbs.remove = NULL;
904       ctx->io_cbs.event = NULL;
905       ctx->io_cbs.event_priv = NULL;
906     }
907 }
908
909
910 /* This function provides access to the internal read function; it is
911    normally not used.  */
912 gpgme_ssize_t
913 gpgme_io_read (int fd, void *buffer, size_t count)
914 {
915   int ret;
916   TRACE_BEG  (DEBUG_GLOBAL, "gpgme_io_read", fd,
917               "buffer=%p, count=%zu", buffer, count);
918
919   ret = _gpgme_io_read (fd, buffer, count);
920
921   return TRACE_SYSRES (ret);
922 }
923
924
925 /* This function provides access to the internal write function.  It
926    is to be used by user callbacks to return data to gpgme.  See
927    gpgme_passphrase_cb_t and gpgme_edit_cb_t.  */
928 gpgme_ssize_t
929 gpgme_io_write (int fd, const void *buffer, size_t count)
930 {
931   int ret;
932   TRACE_BEG  (DEBUG_GLOBAL, "gpgme_io_write", fd,
933               "buffer=%p, count=%zu", buffer, count);
934
935   ret = _gpgme_io_write (fd, buffer, count);
936
937   return TRACE_SYSRES (ret);
938 }
939
940 /* This function provides access to the internal write function.  It
941    is to be used by user callbacks to return data to gpgme.  See
942    gpgme_passphrase_cb_t and gpgme_edit_cb_t.  Note that this is a
943    variant of gpgme_io_write which guarantees that all COUNT bytes are
944    written or an error is return.  Returns: 0 on success or -1 on
945    error and the sets errno. */
946 int
947 gpgme_io_writen (int fd, const void *buffer_arg, size_t count)
948 {
949   const char *buffer = buffer_arg;
950   int ret = 0;
951   TRACE_BEG  (DEBUG_GLOBAL, "gpgme_io_writen", fd,
952               "buffer=%p, count=%zu", buffer, count);
953   while (count)
954     {
955       ret = _gpgme_io_write (fd, buffer, count);
956       if (ret < 0)
957         break;
958       buffer += ret;
959       count -= ret;
960       ret = 0;
961     }
962   return TRACE_SYSRES (ret);
963 }
964
965
966 /* This function returns the callback function for I/O.  */
967 void
968 gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs)
969 {
970   TRACE (DEBUG_CTX, "gpgme_get_io_cbs", ctx,
971           "io_cbs=%p, ctx->io_cbs.add=%p/%p, .remove=%p, .event=%p/%p",
972           io_cbs, io_cbs->add, io_cbs->add_priv, io_cbs->remove,
973           io_cbs->event, io_cbs->event_priv);
974
975   *io_cbs = ctx->io_cbs;
976 }
977
978 \f
979 /* This function sets the locale for the context CTX, or the default
980    locale if CTX is a null pointer.  */
981 gpgme_error_t
982 gpgme_set_locale (gpgme_ctx_t ctx, int category, const char *value)
983 {
984   int failed = 0;
985   char *new_lc_ctype = NULL;
986   char *new_lc_messages = NULL;
987
988   TRACE_BEG  (DEBUG_CTX, "gpgme_set_locale", ctx,
989                "category=%i, value=%s", category, value ? value : "(null)");
990
991 #define PREPARE_ONE_LOCALE(lcat, ucat)                          \
992   if (!failed && value                                          \
993       && (category == LC_ALL || category == LC_ ## ucat))       \
994     {                                                           \
995       new_lc_ ## lcat = strdup (value);                         \
996       if (!new_lc_ ## lcat)                                     \
997         failed = 1;                                             \
998     }
999
1000 #ifdef LC_CTYPE
1001   PREPARE_ONE_LOCALE (ctype, CTYPE);
1002 #endif
1003 #ifdef LC_MESSAGES
1004   PREPARE_ONE_LOCALE (messages, MESSAGES);
1005 #endif
1006
1007   if (failed)
1008     {
1009       int saved_err = gpg_error_from_syserror ();
1010
1011       if (new_lc_ctype)
1012         free (new_lc_ctype);
1013       if (new_lc_messages)
1014         free (new_lc_messages);
1015
1016       return TRACE_ERR (saved_err);
1017     }
1018
1019 #define SET_ONE_LOCALE(lcat, ucat)                      \
1020   if (category == LC_ALL || category == LC_ ## ucat)    \
1021     {                                                   \
1022       if (ctx)                                          \
1023         {                                               \
1024           if (ctx->lc_ ## lcat)                         \
1025             free (ctx->lc_ ## lcat);                    \
1026           ctx->lc_ ## lcat = new_lc_ ## lcat;           \
1027         }                                               \
1028       else                                              \
1029         {                                               \
1030           if (def_lc_ ## lcat)                          \
1031             free (def_lc_ ## lcat);                     \
1032           def_lc_ ## lcat = new_lc_ ## lcat;            \
1033         }                                               \
1034     }
1035
1036   if (!ctx)
1037     LOCK (def_lc_lock);
1038 #ifdef LC_CTYPE
1039   SET_ONE_LOCALE (ctype, CTYPE);
1040 #endif
1041 #ifdef LC_MESSAGES
1042   SET_ONE_LOCALE (messages, MESSAGES);
1043 #endif
1044   if (!ctx)
1045     UNLOCK (def_lc_lock);
1046
1047   return TRACE_ERR (0);
1048 }
1049
1050 \f
1051 /* Get the information about the configured engines.  A pointer to the
1052    first engine in the statically allocated linked list is returned.
1053    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
1054 gpgme_engine_info_t
1055 gpgme_ctx_get_engine_info (gpgme_ctx_t ctx)
1056 {
1057   TRACE (DEBUG_CTX, "gpgme_ctx_get_engine_info", ctx,
1058           "ctx->engine_info=%p", ctx->engine_info);
1059   return ctx->engine_info;
1060 }
1061
1062
1063 /* Set the engine info for the context CTX, protocol PROTO, to the
1064    file name FILE_NAME and the home directory HOME_DIR.  */
1065 gpgme_error_t
1066 gpgme_ctx_set_engine_info (gpgme_ctx_t ctx, gpgme_protocol_t proto,
1067                            const char *file_name, const char *home_dir)
1068 {
1069   gpgme_error_t err;
1070   TRACE_BEG  (DEBUG_CTX, "gpgme_ctx_set_engine_info", ctx,
1071               "protocol=%i (%s), file_name=%s, home_dir=%s",
1072               proto, gpgme_get_protocol_name (proto)
1073               ? gpgme_get_protocol_name (proto) : "unknown",
1074               file_name ? file_name : "(default)",
1075               home_dir ? home_dir : "(default)");
1076
1077   if (!ctx)
1078     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
1079
1080   /* Shut down the engine when changing engine info.  */
1081   if (ctx->engine)
1082     {
1083       TRACE_LOG  ("releasing ctx->engine=%p", ctx->engine);
1084       _gpgme_engine_release (ctx->engine);
1085       ctx->engine = NULL;
1086     }
1087   err = _gpgme_set_engine_info (ctx->engine_info, proto,
1088                                 file_name, home_dir);
1089   return TRACE_ERR (err);
1090 }
1091
1092 \f
1093 /* Clear all notation data from the context.  */
1094 void
1095 _gpgme_sig_notation_clear (gpgme_ctx_t ctx)
1096 {
1097   gpgme_sig_notation_t notation;
1098
1099   if (!ctx)
1100     return;
1101
1102   notation = ctx->sig_notations;
1103   while (notation)
1104     {
1105       gpgme_sig_notation_t next_notation = notation->next;
1106       _gpgme_sig_notation_free (notation);
1107       notation = next_notation;
1108     }
1109   ctx->sig_notations = NULL;
1110 }
1111
1112 void
1113 gpgme_sig_notation_clear (gpgme_ctx_t ctx)
1114 {
1115   TRACE (DEBUG_CTX, "gpgme_sig_notation_clear", ctx, "");
1116
1117   if (!ctx)
1118     return;
1119
1120   _gpgme_sig_notation_clear (ctx);
1121 }
1122
1123
1124 /* Add the human-readable notation data with name NAME and value VALUE
1125    to the context CTX, using the flags FLAGS.  If NAME is NULL, then
1126    VALUE should be a policy URL.  The flag
1127    GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
1128    data, and false for policy URLs.  */
1129 gpgme_error_t
1130 gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
1131                         const char *value, gpgme_sig_notation_flags_t flags)
1132 {
1133   gpgme_error_t err;
1134   gpgme_sig_notation_t notation;
1135   gpgme_sig_notation_t *lastp;
1136
1137   TRACE_BEG  (DEBUG_CTX, "gpgme_sig_notation_add", ctx,
1138               "name=%s, value=%s, flags=0x%x",
1139               name ? name : "(null)", value ? value : "(null)",
1140               flags);
1141
1142   if (!ctx)
1143     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
1144
1145   if (name)
1146     flags |= GPGME_SIG_NOTATION_HUMAN_READABLE;
1147   else
1148     flags &= ~GPGME_SIG_NOTATION_HUMAN_READABLE;
1149
1150   err = _gpgme_sig_notation_create (&notation, name, name ? strlen (name) : 0,
1151                                     value, value ? strlen (value) : 0, flags);
1152   if (err)
1153     return TRACE_ERR (err);
1154
1155   lastp = &ctx->sig_notations;
1156   while (*lastp)
1157     lastp = &(*lastp)->next;
1158
1159   *lastp = notation;
1160   return TRACE_ERR (0);
1161 }
1162
1163
1164 /* Get the sig notations for this context.  */
1165 gpgme_sig_notation_t
1166 gpgme_sig_notation_get (gpgme_ctx_t ctx)
1167 {
1168   if (!ctx)
1169     {
1170       TRACE (DEBUG_CTX, "gpgme_sig_notation_get", ctx, "");
1171       return NULL;
1172     }
1173   TRACE (DEBUG_CTX, "gpgme_sig_notation_get", ctx,
1174           "ctx->sig_notations=%p", ctx->sig_notations);
1175
1176   return ctx->sig_notations;
1177 }
1178
1179
1180 \f
1181 /* Return a public key algorithm string made of the algorithm and size
1182    or the curve name.  May return NULL on error.  Caller must free the
1183    result using gpgme_free.  */
1184 char *
1185 gpgme_pubkey_algo_string (gpgme_subkey_t subkey)
1186 {
1187   const char *prefix = NULL;
1188   char *result;
1189
1190   if (!subkey)
1191     {
1192       gpg_err_set_errno (EINVAL);
1193       return NULL;
1194     }
1195
1196   switch (subkey->pubkey_algo)
1197     {
1198     case GPGME_PK_RSA:
1199     case GPGME_PK_RSA_E:
1200     case GPGME_PK_RSA_S: prefix = "rsa"; break;
1201     case GPGME_PK_ELG_E: prefix = "elg"; break;
1202     case GPGME_PK_DSA:   prefix = "dsa"; break;
1203     case GPGME_PK_ELG:   prefix = "xxx"; break;
1204     case GPGME_PK_ECC:
1205     case GPGME_PK_ECDH:
1206     case GPGME_PK_ECDSA:
1207     case GPGME_PK_EDDSA: prefix = "";    break;
1208     }
1209
1210   if (prefix && *prefix)
1211     {
1212       char buffer[40];
1213       snprintf (buffer, sizeof buffer, "%s%u", prefix, subkey->length);
1214       result = strdup (buffer);
1215     }
1216   else if (prefix && subkey->curve && *subkey->curve)
1217     result = strdup (subkey->curve);
1218   else if (prefix)
1219     result =  strdup ("E_error");
1220   else
1221     result = strdup  ("unknown");
1222
1223   return result;
1224 }
1225
1226
1227 const char *
1228 gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo)
1229 {
1230   switch (algo)
1231     {
1232     case GPGME_PK_RSA:   return "RSA";
1233     case GPGME_PK_RSA_E: return "RSA-E";
1234     case GPGME_PK_RSA_S: return "RSA-S";
1235     case GPGME_PK_ELG_E: return "ELG-E";
1236     case GPGME_PK_DSA:   return "DSA";
1237     case GPGME_PK_ECC:   return "ECC";
1238     case GPGME_PK_ELG:   return "ELG";
1239     case GPGME_PK_ECDSA: return "ECDSA";
1240     case GPGME_PK_ECDH:  return "ECDH";
1241     case GPGME_PK_EDDSA: return "EdDSA";
1242     default:             return NULL;
1243     }
1244 }
1245
1246
1247 const char *
1248 gpgme_hash_algo_name (gpgme_hash_algo_t algo)
1249 {
1250   switch (algo)
1251     {
1252     case GPGME_MD_MD5:
1253       return "MD5";
1254
1255     case GPGME_MD_SHA1:
1256       return "SHA1";
1257
1258     case GPGME_MD_RMD160:
1259       return "RIPEMD160";
1260
1261     case GPGME_MD_MD2:
1262       return "MD2";
1263
1264     case GPGME_MD_TIGER:
1265       return "TIGER192";
1266
1267     case GPGME_MD_HAVAL:
1268       return "HAVAL";
1269
1270     case GPGME_MD_SHA256:
1271       return "SHA256";
1272
1273     case GPGME_MD_SHA384:
1274       return "SHA384";
1275
1276     case GPGME_MD_SHA512:
1277       return "SHA512";
1278
1279     case GPGME_MD_SHA224:
1280       return "SHA224";
1281
1282     case GPGME_MD_MD4:
1283       return "MD4";
1284
1285     case GPGME_MD_CRC32:
1286       return "CRC32";
1287
1288     case GPGME_MD_CRC32_RFC1510:
1289       return "CRC32RFC1510";
1290
1291     case GPGME_MD_CRC24_RFC2440:
1292       return "CRC24RFC2440";
1293
1294     default:
1295       return NULL;
1296     }
1297 }