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