gpgme/gpgme.c

   1 /* gpgme.c -  GnuPG Made Easy
   2  *      Copyright (C) 2000 Werner Koch (dd9jn)
   3  *      Copyright (C) 2001, 2002 g10 Code GmbH
   4  *
   5  * This file is part of GPGME.
   6  *
   7  * GPGME is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * GPGME is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
  20  */
  21
  22 #include <config.h>
  23 #include <stdio.h>
  24 #include <stdlib.h>
  25 #include <string.h>
  26 #include <assert.h>
  27
  28 #include "util.h"
  29 #include "context.h"
  30 #include "ops.h"
  31
  32 /**
  33  * gpgme_new:
  34  * @r_ctx: Returns the new context
  35  *
  36  * Create a new context to be used with most of the other GPGME
  37  * functions.  Use gpgme_release_contect() to release all resources
  38  *
  39  * Return value: An error code
  40  **/
  41 GpgmeError
  42 gpgme_new (GpgmeCtx *r_ctx)
  43 {
  44   GpgmeCtx ctx;
  45
  46   if (!r_ctx)
  47     return mk_error (Invalid_Value);
  48   *r_ctx = 0;
  49   ctx = xtrycalloc (1, sizeof *ctx);
  50   if (!ctx)
  51     return mk_error (Out_Of_Core);
  52   ctx->verbosity = 1;
  53   *r_ctx = ctx;
  54
  55   return 0;
  56 }
  57
  58 /**
  59  * gpgme_release:
  60  * @c: Context to be released.
  61  *
  62  * Release all resources associated with the given context.
  63  **/
  64 void
  65 gpgme_release (GpgmeCtx ctx)
  66 {
  67   if (!ctx)
  68     return;
  69   _gpgme_engine_release (ctx->engine);
  70   _gpgme_release_result (ctx);
  71   gpgme_key_release (ctx->tmp_key);
  72   gpgme_data_release (ctx->help_data_1);
  73   gpgme_data_release (ctx->notation);
  74   gpgme_signers_clear (ctx);
  75   if (ctx->signers)
  76     xfree (ctx->signers);
  77   /* FIXME: Release the key_queue.  */
  78   xfree (ctx);
  79 }
  80
  81 void
  82 _gpgme_release_result (GpgmeCtx ctx)
  83 {
  84   _gpgme_release_verify_result (ctx->result.verify);
  85   _gpgme_release_decrypt_result (ctx->result.decrypt);
  86   _gpgme_release_sign_result (ctx->result.sign);
  87   _gpgme_release_encrypt_result (ctx->result.encrypt);
  88   _gpgme_release_passphrase_result (ctx->result.passphrase);
  89   memset (&ctx->result, 0, sizeof (ctx->result));
  90   _gpgme_set_op_info (ctx, NULL);
  91 }
  92
  93
  94 /**
  95  * gpgme_cancel:
  96  * @c: the context
  97  *
  98  * Cancel the current operation.  It is not guaranteed that it will work for
  99  * all kinds of operations.  It is especially useful in a passphrase callback
 100  * to stop the system from asking another time for the passphrase.
 101  **/
 102 void
 103 gpgme_cancel (GpgmeCtx ctx)
 104 {
 105   return_if_fail (ctx);
 106
 107   ctx->cancel = 1;
 108 }
 109
 110 /**
 111  * gpgme_get_notation:
 112  * @c: the context
 113  *
 114  * If there is notation data available from the last signature check,
 115  * this function may be used to return this notation data as a string.
 116  * The string is an XML represantaton of that data embedded in a
 117  * %&lt;notation&gt; container.
 118  *
 119  * Return value: An XML string or NULL if no notation data is available.
 120  **/
 121 char *
 122 gpgme_get_notation (GpgmeCtx ctx)
 123 {
 124   if (!ctx->notation)
 125     return NULL;
 126   return _gpgme_data_get_as_string (ctx->notation);
 127 }
 128
 129
 130 /**
 131  * gpgme_get_op_info:
 132  * @c: the context
 133  * @reserved:
 134  *
 135  * Return information about the last information.  The caller has to
 136  * free the string.  NULL is returned if there is not previous
 137  * operation available or the operation has not yet finished.
 138  *
 139  * Here is a sample information we return:
 140  * <literal>
 141  * <![CDATA[
 142  * <GnupgOperationInfo>
 143  *   <signature>
 144  *     <detached/> <!-- or cleartext or standard -->
 145  *     <algo>17</algo>
 146  *     <hashalgo>2</hashalgo>
 147  *     <micalg>pgp-sha1</micalg>
 148  *     <sigclass>01</sigclass>
 149  *     <created>9222222</created>
 150  *     <fpr>121212121212121212</fpr>
 151  *   </signature>
 152  * </GnupgOperationInfo>
 153  * ]]>
 154  * </literal>
 155  * Return value: NULL for no info available or an XML string
 156  **/
 157 char *
 158 gpgme_get_op_info (GpgmeCtx ctx, int reserved)
 159 {
 160   if (!ctx || reserved)
 161     return NULL;  /* Invalid value.  */
 162
 163   return _gpgme_data_get_as_string (ctx->op_info);
 164 }
 165
 166
 167 /*
 168  * Store the data object with the operation info in the
 169  * context. Caller should not use that object anymore.
 170  */
 171 void
 172 _gpgme_set_op_info (GpgmeCtx ctx, GpgmeData info)
 173 {
 174   assert (ctx);
 175
 176   gpgme_data_release (ctx->op_info);
 177   ctx->op_info = NULL;
 178
 179   if (info)
 180     ctx->op_info = info;
 181 }
 182
 183
 184 GpgmeError
 185 gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol protocol)
 186 {
 187   if (!ctx)
 188     return mk_error (Invalid_Value);
 189
 190   switch (protocol)
 191     {
 192     case GPGME_PROTOCOL_OpenPGP:
 193       ctx->use_cms = 0;
 194       break;
 195     case GPGME_PROTOCOL_CMS:
 196       ctx->use_cms = 1;
 197       break;
 198     case GPGME_PROTOCOL_AUTO:
 199       return mk_error (Not_Implemented);
 200     default:
 201       return mk_error (Invalid_Value);
 202     }
 203
 204   return 0;
 205 }
 206
 207
 208 /**
 209  * gpgme_set_armor:
 210  * @ctx: the context
 211  * @yes: boolean value to set or clear that flag
 212  *
 213  * Enable or disable the use of an ascii armor for all output.
 214  **/
 215 void
 216 gpgme_set_armor (GpgmeCtx ctx, int yes)
 217 {
 218   if (!ctx)
 219     return;
 220   ctx->use_armor = yes;
 221 }
 222
 223
 224 /**
 225  * gpgme_get_armor:
 226  * @ctx: the context
 227  *
 228  * Return the state of the armor flag which can be changed using
 229  * gpgme_set_armor().
 230  *
 231  * Return value: Boolean whether armor mode is to be used.
 232  **/
 233 int
 234 gpgme_get_armor (GpgmeCtx ctx)
 235 {
 236   return ctx && ctx->use_armor;
 237 }
 238
 239
 240 /**
 241  * gpgme_set_textmode:
 242  * @ctx: the context
 243  * @yes: boolean flag whether textmode should be enabled
 244  *
 245  * Enable or disable the use of the special textmode.  Textmode is for example
 246  * used for the RFC2015 signatures; note that the updated RFC 3156 mandates
 247  * that the MUA does some preparations so that textmode is not needed anymore.
 248  **/
 249 void
 250 gpgme_set_textmode (GpgmeCtx ctx, int yes)
 251 {
 252   if (!ctx)
 253     return;
 254   ctx->use_textmode = yes;
 255 }
 256
 257 /**
 258  * gpgme_get_textmode:
 259  * @ctx: the context
 260  *
 261  * Return the state of the textmode flag which can be changed using
 262  * gpgme_set_textmode().
 263  *
 264  * Return value: Boolean whether textmode is to be used.
 265  **/
 266 int
 267 gpgme_get_textmode (GpgmeCtx ctx)
 268 {
 269   return ctx && ctx->use_textmode;
 270 }
 271
 272
 273 /**
 274  * gpgme_set_keylist_mode:
 275  * @ctx: the context
 276  * @mode: listing mode
 277  *
 278  * This function changes the default behaviour of the keylisting functions.
 279  * Defines values for @mode are: %0 = normal, %1 = fast listing without
 280  * information about key validity.
 281  **/
 282 void
 283 gpgme_set_keylist_mode (GpgmeCtx ctx, int mode)
 284 {
 285   if (!ctx)
 286     return;
 287   ctx->keylist_mode = mode;
 288 }
 289
 290
 291 /**
 292  * gpgme_set_passphrase_cb:
 293  * @ctx: the context
 294  * @cb: A callback function
 295  * @cb_value: The value passed to the callback function
 296  *
 297  * This function sets a callback function to be used to pass a passphrase
 298  * to gpg. The preferred way to handle this is by using the gpg-agent, but
 299  * because that beast is not ready for real use, you can use this passphrase
 300  * thing.
 301  *
 302  * The callback function is defined as:
 303  * <literal>
 304  * typedef const char *(*GpgmePassphraseCb)(void*cb_value,
 305  *                                          const char *desc,
 306  *                                          void *r_hd);
 307  * </literal>
 308  * and called whenever gpgme needs a passphrase. DESC will have a nice
 309  * text, to be used to prompt for the passphrase and R_HD is just a parameter
 310  * to be used by the callback it self.  Because the callback returns a const
 311  * string, the callback might want to know when it can release resources
 312  * assocated with that returned string; gpgme helps here by calling this
 313  * passphrase callback with an DESC of %NULL as soon as it does not need
 314  * the returned string anymore.  The callback function might then choose
 315  * to release resources depending on R_HD.
 316  *
 317  **/
 318 void
 319 gpgme_set_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb cb, void *cb_value)
 320 {
 321   if (ctx)
 322     {
 323       ctx->passphrase_cb = cb;
 324       ctx->passphrase_cb_value = cb_value;
 325     }
 326 }
 327
 328 /**
 329  * gpgme_set_progress_cb:
 330  * @ctx: the context
 331  * @cb: A callback function
 332  * @cb_value: The value passed to the callback function
 333  *
 334  * This function sets a callback function to be used as a progress indicator.
 335  *
 336  * The callback function is defined as:
 337  * <literal>
 338  * typedef void (*GpgmeProgressCb) (void *cb_value,
 339  *                                  const char *what, int type,
 340  *                                  int curretn, int total);
 341  * </literal>
 342  * For details on the progress events, see the entry for the PROGRESS
 343  * status in the file doc/DETAILS of the GnuPG distribution.
 344  **/
 345 void
 346 gpgme_set_progress_cb (GpgmeCtx ctx, GpgmeProgressCb cb, void *cb_value)
 347 {
 348   if (ctx)
 349     {
 350       ctx->progress_cb = cb;
 351       ctx->progress_cb_value = cb_value;
 352     }
 353 }