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