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