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