a729e407f38f2a4f7a2a2bc11060f8174f5c437c
[gpgme.git] / gpgme / gpgme.c
1 /* gpgme.c - GnuPG Made Easy.
2    Copyright (C) 2000 Werner Koch (dd9jn)
3    Copyright (C) 2001, 2002, 2003 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 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, but
13    WITHOUT ANY WARRANTY; without even the implied warranty of
14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15    General Public License for more details.
16  
17    You should have received a copy of the GNU General Public License
18    along with GPGME; if not, write to the Free Software Foundation,
19    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
20
21 #if HAVE_CONFIG_H
22 #include <config.h>
23 #endif
24 #include <stdio.h>
25 #include <stdlib.h>
26 #include <string.h>
27 #include <assert.h>
28
29 #include "util.h"
30 #include "context.h"
31 #include "ops.h"
32 #include "wait.h"
33
34 /* Create a new context as an environment for GPGME crypto
35    operations.  */
36 GpgmeError
37 gpgme_new (GpgmeCtx *r_ctx)
38 {
39   GpgmeCtx ctx;
40
41   if (!r_ctx)
42     return GPGME_Invalid_Value;
43   *r_ctx = 0;
44   ctx = calloc (1, sizeof *ctx);
45   if (!ctx)
46     return GPGME_Out_Of_Core;
47   ctx->keylist_mode = GPGME_KEYLIST_MODE_LOCAL;
48   ctx->include_certs = 1;
49   ctx->protocol = GPGME_PROTOCOL_OpenPGP;
50   _gpgme_fd_table_init (&ctx->fdt);
51   *r_ctx = ctx;
52   return 0;
53 }
54
55
56 /**
57  * gpgme_release:
58  * @c: Context to be released.
59  *
60  * Release all resources associated with the given context.
61  **/
62 void
63 gpgme_release (GpgmeCtx ctx)
64 {
65   if (!ctx)
66     return;
67   _gpgme_engine_release (ctx->engine);
68   _gpgme_fd_table_deinit (&ctx->fdt);
69   _gpgme_release_result (ctx);
70   gpgme_signers_clear (ctx);
71   if (ctx->signers)
72     free (ctx->signers);
73   free (ctx);
74 }
75
76 void
77 _gpgme_release_result (GpgmeCtx ctx)
78 {
79   struct ctx_op_data *data = ctx->op_data;
80
81   while (data)
82     {
83       struct ctx_op_data *next_data = data->next;
84       if (data->cleanup)
85         (*data->cleanup) (data->hook);
86       free (data);
87       data = next_data;
88     }
89   ctx->op_data = NULL;
90 }
91
92
93 GpgmeError
94 gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol protocol)
95 {
96   if (protocol != GPGME_PROTOCOL_OpenPGP && protocol != GPGME_PROTOCOL_CMS)
97     return GPGME_Invalid_Value;
98
99   ctx->protocol = protocol;
100   return 0;
101 }
102
103
104 GpgmeProtocol
105 gpgme_get_protocol (GpgmeCtx ctx)
106 {
107   return ctx->protocol;
108 }
109
110
111 const char *
112 gpgme_get_protocol_name (GpgmeProtocol protocol)
113 {
114   switch (protocol)
115     {
116     case GPGME_PROTOCOL_OpenPGP:
117       return "OpenPGP";
118
119     case GPGME_PROTOCOL_CMS:
120       return "CMS";
121
122     default:
123       return NULL;
124     }
125 }
126
127 /**
128  * gpgme_set_armor:
129  * @ctx: the context
130  * @yes: boolean value to set or clear that flag
131  *
132  * Enable or disable the use of an ascii armor for all output.
133  **/
134 void
135 gpgme_set_armor (GpgmeCtx ctx, int yes)
136 {
137   if (!ctx)
138     return;
139   ctx->use_armor = yes;
140 }
141
142
143 /**
144  * gpgme_get_armor:
145  * @ctx: the context
146  *
147  * Return the state of the armor flag which can be changed using
148  * gpgme_set_armor().
149  *
150  * Return value: Boolean whether armor mode is to be used.
151  **/
152 int
153 gpgme_get_armor (GpgmeCtx ctx)
154 {
155   return ctx && ctx->use_armor;
156 }
157
158
159 /**
160  * gpgme_set_textmode:
161  * @ctx: the context
162  * @yes: boolean flag whether textmode should be enabled
163  *
164  * Enable or disable the use of the special textmode.  Textmode is for example
165  * used for the RFC2015 signatures; note that the updated RFC 3156 mandates
166  * that the MUA does some preparations so that textmode is not needed anymore.
167  **/
168 void
169 gpgme_set_textmode (GpgmeCtx ctx, int yes)
170 {
171   if (!ctx)
172     return;
173   ctx->use_textmode = yes;
174 }
175
176 /**
177  * gpgme_get_textmode:
178  * @ctx: the context
179  *
180  * Return the state of the textmode flag which can be changed using
181  * gpgme_set_textmode().
182  *
183  * Return value: Boolean whether textmode is to be used.
184  **/
185 int
186 gpgme_get_textmode (GpgmeCtx ctx)
187 {
188   return ctx && ctx->use_textmode;
189 }
190
191
192 /**
193  * gpgme_set_include_certs:
194  * @ctx: the context
195  *
196  * Set the number of certifications to include in an S/MIME message.
197  * The default is 1 (only the cert of the sender).  -1 means all certs,
198  * and -2 means all certs except the root cert.
199  *
200  * Return value: Boolean whether textmode is to be used.
201  **/
202 void
203 gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs)
204 {
205   if (nr_of_certs < -2)
206     ctx->include_certs = -2;
207   else
208     ctx->include_certs = nr_of_certs;
209 }
210
211
212 /**
213  * gpgme_get_include_certs:
214  * @ctx: the context
215  *
216  * Get the number of certifications to include in an S/MIME message.
217  *
218  * Return value: Boolean whether textmode is to be used.
219  **/
220 int
221 gpgme_get_include_certs (GpgmeCtx ctx)
222 {
223   return ctx->include_certs;
224 }
225
226
227 /**
228  * gpgme_set_keylist_mode:
229  * @ctx: the context
230  * @mode: listing mode
231  *
232  * This function changes the default behaviour of the keylisting
233  * functions.  mode is a bitwise-OR of the GPGME_KEYLIST_* flags.
234  * The default mode is GPGME_KEYLIST_MODE_LOCAL.
235  *
236  * Return value: GPGME_Invalid_Value if ctx is not a context or mode
237  * not a valid mode.
238  **/
239 GpgmeError
240 gpgme_set_keylist_mode (GpgmeCtx ctx, int mode)
241 {
242   if (!ctx)
243     return GPGME_Invalid_Value;
244
245   if (!((mode & GPGME_KEYLIST_MODE_LOCAL)
246         || (mode & GPGME_KEYLIST_MODE_EXTERN)
247         || (mode & GPGME_KEYLIST_MODE_SIGS)))
248      return GPGME_Invalid_Value;
249
250   ctx->keylist_mode = mode;
251   return 0;
252 }
253
254
255 /**
256  * gpgme_get_keylist_mode:
257  * @ctx: the context
258  *
259  * This function ch the default behaviour of the keylisting functions.
260  * Defines values for @mode are: %0 = normal, %1 = fast listing without
261  * information about key validity.
262  *
263  * Return value: 0 if ctx is not a valid context, or the current mode.
264  * Note that 0 is never a valid mode.
265  **/
266 int
267 gpgme_get_keylist_mode (GpgmeCtx ctx)
268 {
269   if (!ctx)
270     return 0;
271   return ctx->keylist_mode;
272 }
273
274
275 /**
276  * gpgme_set_passphrase_cb:
277  * @ctx: the context
278  * @cb: A callback function
279  * @cb_value: The value passed to the callback function
280  *
281  * This function sets a callback function to be used to pass a passphrase
282  * to gpg. The preferred way to handle this is by using the gpg-agent, but
283  * because that beast is not ready for real use, you can use this passphrase
284  * thing.
285  *
286  * The callback function is defined as:
287  * <literal>
288  * typedef const char *(*GpgmePassphraseCb)(void*cb_value,
289  *                                          const char *desc,
290  *                                          void **r_hd);
291  * </literal>
292  * and called whenever gpgme needs a passphrase. DESC will have a nice
293  * text, to be used to prompt for the passphrase and R_HD is just a parameter
294  * to be used by the callback it self.  Because the callback returns a const
295  * string, the callback might want to know when it can release resources
296  * assocated with that returned string; gpgme helps here by calling this
297  * passphrase callback with an DESC of %NULL as soon as it does not need
298  * the returned string anymore.  The callback function might then choose
299  * to release resources depending on R_HD.
300  *
301  **/
302 void
303 gpgme_set_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb cb, void *cb_value)
304 {
305   if (ctx)
306     {
307       ctx->passphrase_cb = cb;
308       ctx->passphrase_cb_value = cb_value;
309     }
310 }
311
312
313 /**
314  * gpgme_get_passphrase_cb:
315  * @ctx: the context
316  * @r_cb: The current callback function
317  * @r_cb_value: The current value passed to the callback function
318  *
319  * This function returns the callback function to be used to pass a passphrase
320  * to the crypto engine.
321  **/
322 void
323 gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *r_cb, void **r_cb_value)
324 {
325   if (ctx)
326     {
327       if (r_cb)
328         *r_cb = ctx->passphrase_cb;
329       if (r_cb_value)
330         *r_cb_value = ctx->passphrase_cb_value;
331     }
332   else
333     {
334       if (r_cb)
335         *r_cb = NULL;
336       if (r_cb_value)
337         *r_cb_value = NULL;
338     }
339 }
340
341
342 /**
343  * gpgme_set_progress_cb:
344  * @ctx: the context
345  * @cb: A callback function
346  * @cb_value: The value passed to the callback function
347  *
348  * This function sets a callback function to be used as a progress indicator.
349  *
350  * The callback function is defined as:
351  * <literal>
352  * typedef void (*GpgmeProgressCb) (void *cb_value,
353  *                                  const char *what, int type,
354  *                                  int curretn, int total);
355  * </literal>
356  * For details on the progress events, see the entry for the PROGRESS
357  * status in the file doc/DETAILS of the GnuPG distribution.
358  **/
359 void
360 gpgme_set_progress_cb (GpgmeCtx ctx, GpgmeProgressCb cb, void *cb_value)
361 {
362   if (ctx)
363     {
364       ctx->progress_cb = cb;
365       ctx->progress_cb_value = cb_value;
366     }
367 }
368
369
370 /**
371  * gpgme_get_progress_cb:
372  * @ctx: the context
373  * @r_cb: The current callback function
374  * @r_cb_value: The current value passed to the callback function
375  *
376  * This function returns the callback function to be used as a
377  * progress indicator.
378  **/
379 void
380 gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *r_cb, void **r_cb_value)
381 {
382   if (ctx)
383     {
384       if (r_cb)
385         *r_cb = ctx->progress_cb;
386       if (r_cb_value)
387         *r_cb_value = ctx->progress_cb_value;
388     }
389   else
390     {
391       if (r_cb)
392         *r_cb = NULL;
393       if (r_cb_value)
394         *r_cb_value = NULL;
395     }
396 }
397
398
399 /**
400  * gpgme_set_io_cbs:
401  * @ctx: the context
402  * @register_io_cb: A callback function
403  * @register_hook_value: The value passed to the callback function
404  * @remove_io_cb: Another callback function
405  *
406  **/
407 void
408 gpgme_set_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs)
409 {
410   if (!ctx)
411     return;
412
413   if (io_cbs)
414     ctx->io_cbs = *io_cbs;
415   else
416     {
417       ctx->io_cbs.add = NULL;
418       ctx->io_cbs.add_priv = NULL;
419       ctx->io_cbs.remove = NULL;
420       ctx->io_cbs.event = NULL;
421       ctx->io_cbs.event_priv = NULL;
422     }
423 }
424
425
426 /**
427  * gpgme_get_io_cbs:
428  * @ctx: the context
429  * @r_register_cb: The current register callback function
430  * @r_register_cb_value: The current value passed to the
431  * register callback function
432  * @r_remove_cb: The current remove callback function
433  *
434  * This function returns the callback function to be used to pass a passphrase
435  * to the crypto engine.
436  **/
437 void
438 gpgme_get_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs)
439 {
440   if (ctx && io_cbs)
441     *io_cbs = ctx->io_cbs;
442 }
443
444
445 const char *
446 gpgme_pubkey_algo_name (GpgmePubKeyAlgo algo)
447 {
448   switch (algo)
449     {
450     case GPGME_PK_RSA:
451       return "RSA";
452
453     case GPGME_PK_RSA_E:
454       return "RSA-E";
455
456     case GPGME_PK_RSA_S:
457       return "RSA-S";
458
459     case GPGME_PK_ELG_E:
460       return "ELG-E";
461
462     case GPGME_PK_DSA:
463       return "DSA";
464
465     case GPGME_PK_ELG:
466       return "ELG";
467
468     default:
469       return NULL;
470     }
471 }
472
473
474 const char *
475 gpgme_hash_algo_name (GpgmeHashAlgo algo)
476 {
477   switch (algo)
478     {
479     case GPGME_MD_MD5:
480       return "MD5";
481
482     case GPGME_MD_SHA1:
483       return "SHA1";
484
485     case GPGME_MD_RMD160:
486       return "RMD160";
487
488     case GPGME_MD_MD2:
489       return "MD2";
490
491     case GPGME_MD_TIGER:
492       return "TIGER";
493
494     case GPGME_MD_HAVAL:
495       return "HAVAL";
496
497     case GPGME_MD_SHA256:
498       return "SHA256";
499
500     case GPGME_MD_SHA384:
501       return "SHA384";
502
503     case GPGME_MD_SHA512:
504       return "SHA512";
505
506     case GPGME_MD_MD4:
507       return "MD4";
508
509     case GPGME_MD_CRC32:
510       return "CRC32";
511
512     case GPGME_MD_CRC32_RFC1510:
513       return "CRC32-RFC1510";
514
515     case GPGME_MD_CRC24_RFC2440:
516       return "CRC24-RFC2440";
517
518     default:
519       return NULL;
520     }
521 }