Removed the gpgme_set_signature_algorithm stuff. We can't add a
[gpgme.git] / 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 /**
34  * gpgme_new:
35  * @r_ctx: Returns the new context
36  *
37  * Create a new context to be used with most of the other GPGME
38  * functions.  Use gpgme_release_context() to release all resources
39  *
40  * Return value: An error code
41  **/
42 GpgmeError
43 gpgme_new (GpgmeCtx *r_ctx)
44 {
45   GpgmeCtx ctx;
46
47   if (!r_ctx)
48     return mk_error (Invalid_Value);
49   *r_ctx = 0;
50   ctx = xtrycalloc (1, sizeof *ctx);
51   if (!ctx)
52     return mk_error (Out_Of_Core);
53   ctx->keylist_mode = GPGME_KEYLIST_MODE_LOCAL;
54   ctx->verbosity = 1;
55   ctx->include_certs = 1;
56   *r_ctx = ctx;
57
58   return 0;
59 }
60
61
62 /**
63  * gpgme_release:
64  * @c: Context to be released.
65  *
66  * Release all resources associated with the given context.
67  **/
68 void
69 gpgme_release (GpgmeCtx ctx)
70 {
71   if (!ctx)
72     return;
73   _gpgme_engine_release (ctx->engine);
74   _gpgme_release_result (ctx);
75   gpgme_key_release (ctx->tmp_key);
76   gpgme_data_release (ctx->help_data_1);
77   gpgme_data_release (ctx->notation);
78   gpgme_signers_clear (ctx);
79   if (ctx->signers)
80     xfree (ctx->signers);
81   /* FIXME: Release the key_queue.  */
82   xfree (ctx);
83 }
84
85 void
86 _gpgme_release_result (GpgmeCtx ctx)
87 {
88   _gpgme_release_verify_result (ctx->result.verify);
89   _gpgme_release_decrypt_result (ctx->result.decrypt);
90   _gpgme_release_sign_result (ctx->result.sign);
91   _gpgme_release_encrypt_result (ctx->result.encrypt);
92   _gpgme_release_passphrase_result (ctx->result.passphrase);
93   _gpgme_release_import_result (ctx->result.import);
94   _gpgme_release_delete_result (ctx->result.delete);
95   _gpgme_release_genkey_result (ctx->result.genkey);
96   memset (&ctx->result, 0, sizeof (ctx->result));
97   _gpgme_set_op_info (ctx, NULL);
98   ctx->error = 0;
99 }
100
101
102 /**
103  * gpgme_cancel:
104  * @c: the context
105  *
106  * Cancel the current operation.  It is not guaranteed that it will work for
107  * all kinds of operations.  It is especially useful in a passphrase callback
108  * to stop the system from asking another time for the passphrase.
109  **/
110 void
111 gpgme_cancel (GpgmeCtx ctx)
112 {
113   return_if_fail (ctx);
114
115   ctx->cancel = 1;
116 }
117
118 /**
119  * gpgme_get_notation:
120  * @c: the context
121  *
122  * If there is notation data available from the last signature check,
123  * this function may be used to return this notation data as a string.
124  * The string is an XML represantaton of that data embedded in a
125  * %&lt;notation&gt; container.
126  *
127  * Return value: An XML string or NULL if no notation data is available.
128  **/
129 char *
130 gpgme_get_notation (GpgmeCtx ctx)
131 {
132   if (!ctx->notation)
133     return NULL;
134   return _gpgme_data_get_as_string (ctx->notation);
135 }
136
137
138 /**
139  * gpgme_get_op_info:
140  * @c: the context
141  * @reserved:
142  *
143  * Return information about the last information.  The caller has to
144  * free the string.  NULL is returned if there is not previous
145  * operation available or the operation has not yet finished.
146  *
147  * Here is a sample information we return:
148  * <literal>
149  * <![CDATA[
150  * <GnupgOperationInfo>
151  *   <signature>
152  *     <detached/> <!-- or cleartext or standard -->
153  *     <algo>17</algo>
154  *     <hashalgo>2</hashalgo>
155  *     <micalg>pgp-sha1</micalg>
156  *     <sigclass>01</sigclass>
157  *     <created>9222222</created>
158  *     <fpr>121212121212121212</fpr>
159  *   </signature>
160  * </GnupgOperationInfo>
161  * ]]>
162  * </literal>
163  * Return value: NULL for no info available or an XML string
164  **/
165 char *
166 gpgme_get_op_info (GpgmeCtx ctx, int reserved)
167 {
168   if (!ctx || reserved)
169     return NULL;  /* Invalid value.  */
170
171   return _gpgme_data_get_as_string (ctx->op_info);
172 }
173
174
175 /*
176  * Store the data object with the operation info in the
177  * context. Caller should not use that object anymore.
178  */
179 void
180 _gpgme_set_op_info (GpgmeCtx ctx, GpgmeData info)
181 {
182   assert (ctx);
183
184   gpgme_data_release (ctx->op_info);
185   ctx->op_info = NULL;
186
187   if (info)
188     ctx->op_info = info;
189 }
190
191
192 GpgmeError
193 gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol protocol)
194 {
195   if (!ctx)
196     return mk_error (Invalid_Value);
197
198   switch (protocol)
199     {
200     case GPGME_PROTOCOL_OpenPGP:
201       ctx->use_cms = 0;
202       break;
203     case GPGME_PROTOCOL_CMS:
204       ctx->use_cms = 1;
205       break;
206     case GPGME_PROTOCOL_AUTO:
207       return mk_error (Not_Implemented);
208     default:
209       return mk_error (Invalid_Value);
210     }
211
212   return 0;
213 }
214
215
216 /**
217  * gpgme_set_armor:
218  * @ctx: the context
219  * @yes: boolean value to set or clear that flag
220  *
221  * Enable or disable the use of an ascii armor for all output.
222  **/
223 void
224 gpgme_set_armor (GpgmeCtx ctx, int yes)
225 {
226   if (!ctx)
227     return;
228   ctx->use_armor = yes;
229 }
230
231
232 /**
233  * gpgme_get_armor:
234  * @ctx: the context
235  *
236  * Return the state of the armor flag which can be changed using
237  * gpgme_set_armor().
238  *
239  * Return value: Boolean whether armor mode is to be used.
240  **/
241 int
242 gpgme_get_armor (GpgmeCtx ctx)
243 {
244   return ctx && ctx->use_armor;
245 }
246
247
248 /**
249  * gpgme_set_textmode:
250  * @ctx: the context
251  * @yes: boolean flag whether textmode should be enabled
252  *
253  * Enable or disable the use of the special textmode.  Textmode is for example
254  * used for the RFC2015 signatures; note that the updated RFC 3156 mandates
255  * that the MUA does some preparations so that textmode is not needed anymore.
256  **/
257 void
258 gpgme_set_textmode (GpgmeCtx ctx, int yes)
259 {
260   if (!ctx)
261     return;
262   ctx->use_textmode = yes;
263 }
264
265 /**
266  * gpgme_get_textmode:
267  * @ctx: the context
268  *
269  * Return the state of the textmode flag which can be changed using
270  * gpgme_set_textmode().
271  *
272  * Return value: Boolean whether textmode is to be used.
273  **/
274 int
275 gpgme_get_textmode (GpgmeCtx ctx)
276 {
277   return ctx && ctx->use_textmode;
278 }
279
280
281 /**
282  * gpgme_set_include_certs:
283  * @ctx: the context
284  *
285  * Set the number of certifications to include in an S/MIME message.
286  * The default is 1 (only the cert of the sender).  -1 means all certs,
287  * and -2 means all certs except the root cert.
288  *
289  * Return value: Boolean whether textmode is to be used.
290  **/
291 void
292 gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs)
293 {
294   if (nr_of_certs < -2)
295     ctx->include_certs = -2;
296   else
297     ctx->include_certs = nr_of_certs;
298 }
299
300
301 /**
302  * gpgme_get_include_certs:
303  * @ctx: the context
304  *
305  * Get the number of certifications to include in an S/MIME message.
306  *
307  * Return value: Boolean whether textmode is to be used.
308  **/
309 int
310 gpgme_get_include_certs (GpgmeCtx ctx)
311 {
312   return ctx->include_certs;
313 }
314
315
316 /**
317  * gpgme_set_keylist_mode:
318  * @ctx: the context
319  * @mode: listing mode
320  *
321  * This function changes the default behaviour of the keylisting
322  * functions.  mode is a bitwise-OR of the GPGME_KEYLIST_* flags.
323  * The default mode is GPGME_KEYLIST_MODE_LOCAL.
324  *
325  * Return value: GPGME_Invalid_Value if ctx is not a context or mode
326  * not a valid mode.
327  **/
328 GpgmeError
329 gpgme_set_keylist_mode (GpgmeCtx ctx, int mode)
330 {
331   if (!ctx)
332     return mk_error (Invalid_Value);
333
334   if (!((mode & GPGME_KEYLIST_MODE_LOCAL)
335         || (mode & GPGME_KEYLIST_MODE_EXTERN)))
336     return mk_error (Invalid_Value);
337
338   ctx->keylist_mode = mode;
339   return 0;
340 }
341
342
343 /**
344  * gpgme_get_keylist_mode:
345  * @ctx: the context
346  *
347  * This function ch the default behaviour of the keylisting functions.
348  * Defines values for @mode are: %0 = normal, %1 = fast listing without
349  * information about key validity.
350  *
351  * Return value: 0 if ctx is not a valid context, or the current mode.
352  * Note that 0 is never a valid mode.
353  **/
354 int
355 gpgme_get_keylist_mode (GpgmeCtx ctx)
356 {
357   if (!ctx)
358     return 0;
359   return ctx->keylist_mode;
360 }
361
362
363 /**
364  * gpgme_set_passphrase_cb:
365  * @ctx: the context
366  * @cb: A callback function
367  * @cb_value: The value passed to the callback function
368  *
369  * This function sets a callback function to be used to pass a passphrase
370  * to gpg. The preferred way to handle this is by using the gpg-agent, but
371  * because that beast is not ready for real use, you can use this passphrase
372  * thing.
373  *
374  * The callback function is defined as:
375  * <literal>
376  * typedef const char *(*GpgmePassphraseCb)(void*cb_value,
377  *                                          const char *desc,
378  *                                          void **r_hd);
379  * </literal>
380  * and called whenever gpgme needs a passphrase. DESC will have a nice
381  * text, to be used to prompt for the passphrase and R_HD is just a parameter
382  * to be used by the callback it self.  Because the callback returns a const
383  * string, the callback might want to know when it can release resources
384  * assocated with that returned string; gpgme helps here by calling this
385  * passphrase callback with an DESC of %NULL as soon as it does not need
386  * the returned string anymore.  The callback function might then choose
387  * to release resources depending on R_HD.
388  *
389  **/
390 void
391 gpgme_set_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb cb, void *cb_value)
392 {
393   if (ctx)
394     {
395       ctx->passphrase_cb = cb;
396       ctx->passphrase_cb_value = cb_value;
397     }
398 }
399
400 /**
401  * gpgme_set_progress_cb:
402  * @ctx: the context
403  * @cb: A callback function
404  * @cb_value: The value passed to the callback function
405  *
406  * This function sets a callback function to be used as a progress indicator.
407  *
408  * The callback function is defined as:
409  * <literal>
410  * typedef void (*GpgmeProgressCb) (void *cb_value,
411  *                                  const char *what, int type,
412  *                                  int curretn, int total);
413  * </literal>
414  * For details on the progress events, see the entry for the PROGRESS
415  * status in the file doc/DETAILS of the GnuPG distribution.
416  **/
417 void
418 gpgme_set_progress_cb (GpgmeCtx ctx, GpgmeProgressCb cb, void *cb_value)
419 {
420   if (ctx)
421     {
422       ctx->progress_cb = cb;
423       ctx->progress_cb_value = cb_value;
424     }
425 }