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