doc/
[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 #include <errno.h>
29
30 #include "util.h"
31 #include "context.h"
32 #include "ops.h"
33 #include "wait.h"
34
35 /* Create a new context as an environment for GPGME crypto
36    operations.  */
37 gpgme_error_t
38 gpgme_new (gpgme_ctx_t *r_ctx)
39 {
40   gpgme_ctx_t ctx;
41
42   ctx = calloc (1, sizeof *ctx);
43   if (!ctx)
44     return gpg_error_from_errno (errno);
45   ctx->keylist_mode = GPGME_KEYLIST_MODE_LOCAL;
46   ctx->include_certs = 1;
47   ctx->protocol = GPGME_PROTOCOL_OpenPGP;
48   _gpgme_fd_table_init (&ctx->fdt);
49   *r_ctx = ctx;
50   return 0;
51 }
52
53
54 /* Release all resources associated with the given context.  */
55 void
56 gpgme_release (gpgme_ctx_t ctx)
57 {
58   _gpgme_engine_release (ctx->engine);
59   _gpgme_fd_table_deinit (&ctx->fdt);
60   _gpgme_release_result (ctx);
61   gpgme_signers_clear (ctx);
62   if (ctx->signers)
63     free (ctx->signers);
64   free (ctx);
65 }
66
67
68 void
69 _gpgme_release_result (gpgme_ctx_t ctx)
70 {
71   struct ctx_op_data *data = ctx->op_data;
72
73   while (data)
74     {
75       struct ctx_op_data *next_data = data->next;
76       if (data->cleanup)
77         (*data->cleanup) (data->hook);
78       free (data);
79       data = next_data;
80     }
81   ctx->op_data = NULL;
82 }
83
84
85 gpgme_error_t
86 gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t protocol)
87 {
88   if (protocol != GPGME_PROTOCOL_OpenPGP && protocol != GPGME_PROTOCOL_CMS)
89     return gpg_error (GPG_ERR_INV_VALUE);
90
91   ctx->protocol = protocol;
92   return 0;
93 }
94
95
96 gpgme_protocol_t
97 gpgme_get_protocol (gpgme_ctx_t ctx)
98 {
99   return ctx->protocol;
100 }
101
102
103 const char *
104 gpgme_get_protocol_name (gpgme_protocol_t protocol)
105 {
106   switch (protocol)
107     {
108     case GPGME_PROTOCOL_OpenPGP:
109       return "OpenPGP";
110
111     case GPGME_PROTOCOL_CMS:
112       return "CMS";
113
114     default:
115       return NULL;
116     }
117 }
118
119 /* Enable or disable the use of an ascii armor for all output.  */
120 void
121 gpgme_set_armor (gpgme_ctx_t ctx, int yes)
122 {
123   ctx->use_armor = yes;
124 }
125
126
127 /* Return the state of the armor flag.  */
128 int
129 gpgme_get_armor (gpgme_ctx_t ctx)
130 {
131   return ctx->use_armor;
132 }
133
134
135 /* Enable or disable the use of the special textmode.  Textmode is for
136   example used for the RFC2015 signatures; note that the updated RFC
137   3156 mandates that the MUA does some preparations so that textmode
138   is not needed anymore.  */
139 void
140 gpgme_set_textmode (gpgme_ctx_t ctx, int yes)
141 {
142   ctx->use_textmode = yes;
143 }
144
145 /* Return the state of the textmode flag.  */
146 int
147 gpgme_get_textmode (gpgme_ctx_t ctx)
148 {
149   return ctx->use_textmode;
150 }
151
152
153 /* Set the number of certifications to include in an S/MIME message.
154    The default is 1 (only the cert of the sender).  -1 means all
155    certs, and -2 means all certs except the root cert.  */
156 void
157 gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs)
158 {
159   if (nr_of_certs < -2)
160     ctx->include_certs = -2;
161   else
162     ctx->include_certs = nr_of_certs;
163 }
164
165
166 /* Get the number of certifications to include in an S/MIME
167    message.  */
168 int
169 gpgme_get_include_certs (gpgme_ctx_t ctx)
170 {
171   return ctx->include_certs;
172 }
173
174
175 /* This function changes the default behaviour of the keylisting
176    functions.  MODE is a bitwise-OR of the GPGME_KEYLIST_* flags.  The
177    default mode is GPGME_KEYLIST_MODE_LOCAL.  */
178 gpgme_error_t
179 gpgme_set_keylist_mode (gpgme_ctx_t ctx, gpgme_keylist_mode_t mode)
180 {
181   if (!((mode & GPGME_KEYLIST_MODE_LOCAL)
182         || (mode & GPGME_KEYLIST_MODE_EXTERN)
183         || (mode & GPGME_KEYLIST_MODE_SIGS)))
184     return gpg_error (GPG_ERR_INV_VALUE);
185
186   ctx->keylist_mode = mode;
187   return 0;
188 }
189
190 /* This function returns the default behaviour of the keylisting
191    functions.  */
192 gpgme_keylist_mode_t
193 gpgme_get_keylist_mode (gpgme_ctx_t ctx)
194 {
195   return ctx->keylist_mode;
196 }
197
198
199 /* This function sets a callback function to be used to pass a
200    passphrase to gpg.  */
201 void
202 gpgme_set_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t cb,
203                          void *cb_value)
204 {
205   ctx->passphrase_cb = cb;
206   ctx->passphrase_cb_value = cb_value;
207 }
208
209
210 /* This function returns the callback function to be used to pass a
211    passphrase to the crypto engine.  */
212 void
213 gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *r_cb,
214                          void **r_cb_value)
215 {
216   if (r_cb)
217     *r_cb = ctx->passphrase_cb;
218   if (r_cb_value)
219     *r_cb_value = ctx->passphrase_cb_value;
220 }
221
222
223 /* This function sets a callback function to be used as a progress
224    indicator.  */
225 void
226 gpgme_set_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t cb, void *cb_value)
227 {
228   ctx->progress_cb = cb;
229   ctx->progress_cb_value = cb_value;
230 }
231
232
233 /* This function returns the callback function to be used as a
234    progress indicator.  */
235 void
236 gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *r_cb,
237                        void **r_cb_value)
238 {
239   if (r_cb)
240     *r_cb = ctx->progress_cb;
241   if (r_cb_value)
242     *r_cb_value = ctx->progress_cb_value;
243 }
244
245
246 /* Set the I/O callback functions for CTX to IO_CBS.  */
247 void
248 gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs)
249 {
250   if (io_cbs)
251     ctx->io_cbs = *io_cbs;
252   else
253     {
254       ctx->io_cbs.add = NULL;
255       ctx->io_cbs.add_priv = NULL;
256       ctx->io_cbs.remove = NULL;
257       ctx->io_cbs.event = NULL;
258       ctx->io_cbs.event_priv = NULL;
259     }
260 }
261
262
263 /* This function returns the callback function for I/O.  */
264 void
265 gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs)
266 {
267   *io_cbs = ctx->io_cbs;
268 }
269
270
271 const char *
272 gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo)
273 {
274   switch (algo)
275     {
276     case GPGME_PK_RSA:
277       return "RSA";
278
279     case GPGME_PK_RSA_E:
280       return "RSA-E";
281
282     case GPGME_PK_RSA_S:
283       return "RSA-S";
284
285     case GPGME_PK_ELG_E:
286       return "ELG-E";
287
288     case GPGME_PK_DSA:
289       return "DSA";
290
291     case GPGME_PK_ELG:
292       return "ELG";
293
294     default:
295       return NULL;
296     }
297 }
298
299
300 const char *
301 gpgme_hash_algo_name (gpgme_hash_algo_t algo)
302 {
303   switch (algo)
304     {
305     case GPGME_MD_MD5:
306       return "MD5";
307
308     case GPGME_MD_SHA1:
309       return "SHA1";
310
311     case GPGME_MD_RMD160:
312       return "RMD160";
313
314     case GPGME_MD_MD2:
315       return "MD2";
316
317     case GPGME_MD_TIGER:
318       return "TIGER";
319
320     case GPGME_MD_HAVAL:
321       return "HAVAL";
322
323     case GPGME_MD_SHA256:
324       return "SHA256";
325
326     case GPGME_MD_SHA384:
327       return "SHA384";
328
329     case GPGME_MD_SHA512:
330       return "SHA512";
331
332     case GPGME_MD_MD4:
333       return "MD4";
334
335     case GPGME_MD_CRC32:
336       return "CRC32";
337
338     case GPGME_MD_CRC32_RFC1510:
339       return "CRC32-RFC1510";
340
341     case GPGME_MD_CRC24_RFC2440:
342       return "CRC24-RFC2440";
343
344     default:
345       return NULL;
346     }
347 }