2002-07-03 Marcus Brinkmann <marcus@g10code.de>
[gpgme.git] / gpgme / gpgme.h
1 /* gpgme.h -  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 #ifndef GPGME_H
23 #define GPGME_H
24
25 #include <stdio.h> /* For FILE *.  */
26 #ifdef _MSC_VER
27   typedef long off_t;
28 #else
29 # include <sys/types.h>
30 #endif
31
32 #ifdef __cplusplus
33 extern "C" {
34 #if 0 /* just to make Emacs auto-indent happy */
35 }
36 #endif
37 #endif
38
39
40 /* The version of this header should match the one of the library.  Do
41    not use this symbol in your application, use gpgme_check_version
42    instead.  The purpose of this macro is to let autoconf (using the
43    AM_PATH_GPGME macro) check that this header matches the installed
44    library.  Warning: Do not edit the next line.  configure will do
45    that for you!  */
46 #define GPGME_VERSION "0.3.9"
47
48
49 /* The opaque data types used by GPGME.  */
50
51 /* The context holds some global state and configration options as
52    well as the results of a crypto operation.  */
53 struct gpgme_context_s;
54 typedef struct gpgme_context_s *GpgmeCtx;
55
56 /* The data object used by GPGME to exchange arbitrary data.  */
57 struct gpgme_data_s;
58 typedef struct gpgme_data_s *GpgmeData;
59
60 /* A list of recipients to be used in an encryption operation.  */
61 struct gpgme_recipients_s;
62 typedef struct gpgme_recipients_s *GpgmeRecipients;
63
64 /* A key from the keyring.  */
65 struct gpgme_key_s;
66 typedef struct gpgme_key_s *GpgmeKey;
67
68 /* A trust item.  */
69 struct gpgme_trust_item_s;
70 typedef struct gpgme_trust_item_s *GpgmeTrustItem;
71
72
73 /* The error numbers used by GPGME.  */
74 typedef enum
75   {
76     GPGME_EOF                = -1,
77     GPGME_No_Error           = 0,
78     GPGME_General_Error      = 1,
79     GPGME_Out_Of_Core        = 2,
80     GPGME_Invalid_Value      = 3,
81     GPGME_Busy               = 4,
82     GPGME_No_Request         = 5,
83     GPGME_Exec_Error         = 6,
84     GPGME_Too_Many_Procs     = 7,
85     GPGME_Pipe_Error         = 8,
86     GPGME_No_Recipients      = 9,
87     GPGME_No_Data            = 10,
88     GPGME_Conflict           = 11,
89     GPGME_Not_Implemented    = 12,
90     GPGME_Read_Error         = 13,
91     GPGME_Write_Error        = 14,
92     GPGME_Invalid_Type       = 15,
93     GPGME_Invalid_Mode       = 16,
94     GPGME_File_Error         = 17,  /* errno is set in this case.  */
95     GPGME_Decryption_Failed  = 18,
96     GPGME_No_Passphrase      = 19,
97     GPGME_Canceled           = 20,
98     GPGME_Invalid_Key        = 21,
99     GPGME_Invalid_Engine     = 22,
100     GPGME_Invalid_Recipients = 23
101   }
102 GpgmeError;
103
104 /* The possible types of GpgmeData objects.  */
105 typedef enum
106   {
107     GPGME_DATA_TYPE_NONE = 0,
108     GPGME_DATA_TYPE_MEM  = 1,
109     GPGME_DATA_TYPE_FD   = 2,
110     GPGME_DATA_TYPE_FILE = 3,
111     GPGME_DATA_TYPE_CB   = 4
112   }
113 GpgmeDataType;
114
115 /* The possible encoding mode of GpgmeData objects.  */
116 typedef enum
117   {
118     GPGME_DATA_ENCODING_NONE   = 0, /* i.e. not specified */
119     GPGME_DATA_ENCODING_BINARY = 1,
120     GPGME_DATA_ENCODING_BASE64 = 2, 
121     GPGME_DATA_ENCODING_ARMOR  = 3 /* Either PEM or OpenPGP Armor */
122   }
123 GpgmeDataEncoding;
124
125 /* The possible signature stati.  */
126 typedef enum
127   {
128     GPGME_SIG_STAT_NONE  = 0,
129     GPGME_SIG_STAT_GOOD  = 1,
130     GPGME_SIG_STAT_BAD   = 2,
131     GPGME_SIG_STAT_NOKEY = 3,
132     GPGME_SIG_STAT_NOSIG = 4,
133     GPGME_SIG_STAT_ERROR = 5,
134     GPGME_SIG_STAT_DIFF  = 6,
135     GPGME_SIG_STAT_GOOD_EXP = 7,
136     GPGME_SIG_STAT_GOOD_EXPKEY = 8
137   }
138 GpgmeSigStat;
139
140 /* Flags used with the GPGME_ATTR_SIG_SUMMARY. */
141 enum 
142   {
143     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid */
144     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good. */
145     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad. */
146     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked. */
147     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired. */
148     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired. */
149     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing. */
150     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available. */
151     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old. */
152     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met. */
153     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured. */
154   };
155
156
157 /* The available signature modes.  */
158 typedef enum
159   {
160     GPGME_SIG_MODE_NORMAL = 0,
161     GPGME_SIG_MODE_DETACH = 1,
162     GPGME_SIG_MODE_CLEAR  = 2
163   }
164 GpgmeSigMode;
165
166 /* The available key and signature attributes.  */
167 typedef enum
168   {
169     GPGME_ATTR_KEYID        = 1,
170     GPGME_ATTR_FPR          = 2,
171     GPGME_ATTR_ALGO         = 3,
172     GPGME_ATTR_LEN          = 4,
173     GPGME_ATTR_CREATED      = 5,
174     GPGME_ATTR_EXPIRE       = 6,
175     GPGME_ATTR_OTRUST       = 7,
176     GPGME_ATTR_USERID       = 8,
177     GPGME_ATTR_NAME         = 9,
178     GPGME_ATTR_EMAIL        = 10,
179     GPGME_ATTR_COMMENT      = 11,
180     GPGME_ATTR_VALIDITY     = 12,
181     GPGME_ATTR_LEVEL        = 13,
182     GPGME_ATTR_TYPE         = 14,
183     GPGME_ATTR_IS_SECRET    = 15,
184     GPGME_ATTR_KEY_REVOKED  = 16,
185     GPGME_ATTR_KEY_INVALID  = 17,
186     GPGME_ATTR_UID_REVOKED  = 18,
187     GPGME_ATTR_UID_INVALID  = 19,
188     GPGME_ATTR_KEY_CAPS     = 20,
189     GPGME_ATTR_CAN_ENCRYPT  = 21,
190     GPGME_ATTR_CAN_SIGN     = 22,
191     GPGME_ATTR_CAN_CERTIFY  = 23,
192     GPGME_ATTR_KEY_EXPIRED  = 24,
193     GPGME_ATTR_KEY_DISABLED = 25,
194     GPGME_ATTR_SERIAL       = 26,
195     GPGME_ATTR_ISSUER       = 27,
196     GPGME_ATTR_CHAINID      = 28,
197     GPGME_ATTR_SIG_STATUS   = 29,
198     GPGME_ATTR_ERRTOK       = 30,
199     GPGME_ATTR_SIG_SUMMARY  = 31
200   }
201 GpgmeAttr;
202
203 /* The available validities for a trust item or key.  */
204 typedef enum
205   {
206     GPGME_VALIDITY_UNKNOWN   = 0,
207     GPGME_VALIDITY_UNDEFINED = 1,
208     GPGME_VALIDITY_NEVER     = 2,
209     GPGME_VALIDITY_MARGINAL  = 3,
210     GPGME_VALIDITY_FULL      = 4,
211     GPGME_VALIDITY_ULTIMATE  = 5
212   }
213 GpgmeValidity;
214
215 /* The available protocols.  */
216 typedef enum
217   {
218     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
219     GPGME_PROTOCOL_CMS     = 1,
220     GPGME_PROTOCOL_AUTO    = 2
221   }
222 GpgmeProtocol;
223
224
225 /* The available keylist mode flags.  */
226 #define GPGME_KEYLIST_MODE_LOCAL 1
227 #define GPGME_KEYLIST_MODE_EXTERN 2
228
229
230 /* Types for callback functions.  */
231
232 /* Request a passphrase from the user.  */
233 typedef const char *(*GpgmePassphraseCb) (void *hook, const char *desc,
234                                           void **r_hd);
235
236 /* Inform the user about progress made.  */
237 typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
238                                  int type, int current, int total);
239
240
241 /* Context management functions.  */
242
243 /* Create a new context and return it in CTX.  */
244 GpgmeError gpgme_new (GpgmeCtx *ctx);
245
246 /* Release the context CTX.  */
247 void gpgme_release (GpgmeCtx ctx);
248
249 /* Retrieve more info about performed signature check.  */
250 char *gpgme_get_notation (GpgmeCtx ctx);
251
252 /* Set the protocol to be used by CTX to PROTO.  */
253 GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
254
255 /* Get the protocol used with CTX */
256 GpgmeProtocol gpgme_get_protocol (GpgmeCtx ctx);
257
258 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
259 void gpgme_set_armor (GpgmeCtx ctx, int yes);
260
261 /* Return non-zero if armor mode is set in CTX.  */
262 int gpgme_get_armor (GpgmeCtx ctx);
263
264 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
265 void gpgme_set_textmode (GpgmeCtx ctx, int yes);
266
267 /* Return non-zero if text mode is set in CTX.  */
268 int gpgme_get_textmode (GpgmeCtx ctx);
269
270 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
271 void gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs);
272
273 /* Return the number of certs to include in an S/MIME message.  */
274 int gpgme_get_include_certs (GpgmeCtx ctx);
275
276 /* Set keylist mode in CTX to MODE.  */
277 GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
278
279 /* Get keylist mode in CTX.  */
280 int gpgme_get_keylist_mode (GpgmeCtx ctx);
281
282 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
283    passed as first argument to the passphrase callback function.  */
284 void gpgme_set_passphrase_cb (GpgmeCtx ctx,
285                               GpgmePassphraseCb cb, void *hook_value);
286
287 /* Get the current passphrase callback function in *CB and the current
288    hook value in *HOOK_VALUE.  */
289 void gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *cb,
290                               void **hook_value);
291
292 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
293    passed as first argument to the progress callback function.  */
294 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
295
296 /* Get the current progress callback function in *CB and the current
297    hook value in *HOOK_VALUE.  */
298 void gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *cb,
299                             void **hook_value);
300
301 /* Delete all signers from CTX.  */
302 void gpgme_signers_clear (GpgmeCtx ctx);
303
304 /* Add KEY to list of signers in CTX.  */
305 GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
306
307 /* Return the SEQth signer's key in CTX.  */
308 GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
309
310 /* Retrieve the signature status of signature IDX in CTX after a
311    successful verify operation in R_STAT (if non-null).  The creation
312    time stamp of the signature is returned in R_CREATED (if non-null).
313    The function returns a string containing the fingerprint.  */
314 const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
315                                   GpgmeSigStat *r_stat, time_t *r_created);
316
317 /* Retrieve certain attributes of a signature.  IDX is the index
318    number of the signature after a successful verify operation.  WHAT
319    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
320    one.  WHATIDX is to be passed as 0 for most attributes . */
321 unsigned long gpgme_get_sig_ulong_attr (GpgmeCtx c, int idx,
322                                         GpgmeAttr what, int whatidx);
323 const char *gpgme_get_sig_string_attr (GpgmeCtx c, int idx,
324                                       GpgmeAttr what, int whatidx);
325
326
327 /* Get the key used to create signature IDX in CTX and return it in
328    R_KEY.  */
329 GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
330
331 /* Return a string with more info about the last crypto operating in CTX.
332    RESERVED should be zero.  The user has to free the string.  */
333 char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
334
335
336 /* Run control.  */
337
338 /* The type of an I/O callback function.  */
339 typedef void (*GpgmeIOCb) (void *data, int fd);
340
341 /* The type of a function that can register FNC as the I/O callback
342    function for the file descriptor FD with direction dir (0: for writing,
343    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
344    function should return a TAG suitable for the corresponding
345    GpgmeRemoveIOCb, and an error value.  */
346 typedef GpgmeError (*GpgmeRegisterIOCb) (void *data, int fd, int dir,
347                                          GpgmeIOCb fnc, void *fnc_data,
348                                          void **tag);
349
350 /* The type of a function that can remove a previously registered I/O
351    callback function given TAG as returned by the register
352    function.  */
353 typedef void (*GpgmeRemoveIOCb) (void *tag);
354
355 typedef enum { GPGME_EVENT_DONE,
356                GPGME_EVENT_NEXT_KEY,
357                GPGME_EVENT_NEXT_TRUSTITEM } GpgmeEventIO;
358
359 /* The type of a function that is called when a context finished an
360    operation.  */
361 typedef void (*GpgmeEventIOCb) (void *data, GpgmeEventIO type,
362                                 void *type_data);
363
364 struct GpgmeIOCbs
365 {
366   GpgmeRegisterIOCb add;
367   void *add_priv;
368   GpgmeRemoveIOCb remove;
369   GpgmeEventIOCb event;
370   void *event_priv;
371 };
372
373 /* Set the I/O callback functions in CTX to IO_CBS.  */
374 void gpgme_set_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
375
376 /* Get the current I/O callback functions.  */
377 void gpgme_get_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
378
379 /* Cancel a pending operation in CTX.  */
380 void gpgme_cancel (GpgmeCtx ctx);
381
382 /* Process the pending operation and, if HANG is non-zero, wait for
383    the pending operation to finish.  */
384 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
385
386
387 /* Functions to handle recipients.  */
388
389 /* Create a new recipients set and return it in R_RSET.  */
390 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
391
392 /* Release the recipients set RSET.  */
393 void gpgme_recipients_release (GpgmeRecipients rset);
394
395 /* Add NAME to the recipients set RSET.  */
396 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
397
398 /* Add NAME with validity AL to the recipients set RSET.  */
399 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
400                                                     const char *name,
401                                                     GpgmeValidity val);
402
403 /* Return the number of recipients in RSET.  */
404 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
405
406 /* Create a new enumeration handle for the recipients set RSET and
407    return it in ITER.  */
408 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
409                                        void **iter);
410
411 /* Return the next recipient from the recipient set RSET in the
412    enumerator ITER.  */
413 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
414                                         void **iter);
415
416 /* Destroy the enumerator ITER for the recipient set RSET.  */
417 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
418                                         void **iter);
419
420
421 /* Functions to handle data objects.  */
422
423 /* Create a new data buffer and return it in R_DH.  */
424 GpgmeError gpgme_data_new (GpgmeData *r_dh);
425
426 /* Create a new data buffer filled with SIZE bytes starting from
427    BUFFER.  If COPY is zero, copying is delayed until necessary, and
428    the data is taken from the original location when needed.  */
429 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
430                                     const char *buffer, size_t size,
431                                     int copy);
432
433 /* Create a new data buffer which retrieves the data from the callback
434    function READ_CB.  */
435 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
436                                         int (*read_cb) (void*,char *,size_t,size_t*),
437                                         void *read_cb_value);
438
439 /* Create a new data buffer filled with the content of file FNAME.
440    COPY must be non-zero (delayed reads are not supported yet).  */
441 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
442                                      const char *fname,
443                                      int copy);
444
445 /* Create a new data buffer filled with LENGTH bytes starting from
446    OFFSET within the file FNAME or stream FP (exactly one must be
447    non-zero).  */
448 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
449                                          const char *fname, FILE *fp,
450                                          off_t offset, size_t length);
451
452 /* Destroy the data buffer DH.  */
453 void gpgme_data_release (GpgmeData dh);
454
455 /* Destroy the data buffer DH and return a pointer to its content.
456    The memory has be to released with free by the user.  It's size is
457    returned in R_LEN.  */
458 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
459
460 /* Return the type of the data buffer DH.  */
461 GpgmeDataType gpgme_data_get_type (GpgmeData dh);
462
463 /* Return the encoding attribute of the data buffer DH */
464 GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh);
465
466 /* Set the encoding attribute of data buffer DH to ENC */
467 GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc);
468
469 /* Reset the read pointer in DH.  */
470 GpgmeError gpgme_data_rewind (GpgmeData dh);
471
472 /* Read LENGTH bytes from the data object DH and store them in the
473    memory starting at BUFFER.  The number of bytes actually read is
474    returned in NREAD.  */
475 GpgmeError gpgme_data_read (GpgmeData dh, void *buffer,
476                             size_t length, size_t *nread);
477
478 /* Write LENGTH bytes starting from BUFFER into the data object DH.  */
479 GpgmeError gpgme_data_write (GpgmeData dh, const void *buffer, size_t length);
480
481
482 /* Key and trust functions.  */
483
484 /* Acquire a reference to KEY.  */
485 void gpgme_key_ref (GpgmeKey key);
486
487 /* Release a reference to KEY.  If this was the last one the key is
488    destroyed.  */
489 void gpgme_key_unref (GpgmeKey key);
490 void gpgme_key_release (GpgmeKey key);
491
492 /* Get the data from key KEY in a XML string, which has to be released
493    with free by the user.  */
494 char *gpgme_key_get_as_xml (GpgmeKey key);
495
496 /* Return the value of the attribute WHAT of KEY, which has to be
497    representable by a string.  IDX specifies the sub key or
498    user ID for attributes related to sub keys or user IDs.  */
499 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
500                                        const void *reserved, int idx);
501
502 /* Return the value of the attribute WHAT of KEY, which has to be
503    representable by an unsigned integer.  IDX specifies the sub key or
504    user ID for attributes related to sub keys or user IDs.  */
505 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
506                                         const void *reserved, int idx);
507
508 /* Release the trust item ITEM.  */
509 void gpgme_trust_item_release (GpgmeTrustItem item);
510
511 /* Return the value of the attribute WHAT of ITEM, which has to be
512    representable by a string.  */
513 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
514                                               GpgmeAttr what,
515                                               const void *reserved, int idx);
516
517 /* Return the value of the attribute WHAT of KEY, which has to be
518    representable by an integer.  IDX specifies a running index if the
519    attribute appears more than once in the key.  */
520 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
521                                    const void *reserved, int idx);
522
523
524 /* Crypto operation function.  */
525
526 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
527    store the resulting ciphertext in CIPHER.  */
528 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
529                                    GpgmeRecipients recp,
530                                    GpgmeData plain, GpgmeData cipher);
531 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
532                              GpgmeRecipients recp,
533                              GpgmeData plain, GpgmeData cipher);
534
535 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
536    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
537    with the signers in CTX.  */
538 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
539                                         GpgmeRecipients recp,
540                                         GpgmeData plain, GpgmeData cipher);
541 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
542                                   GpgmeRecipients recp,
543                                   GpgmeData plain, GpgmeData cipher);
544
545 /* Decrypt ciphertext CIPHER within CTX and store the resulting
546    plaintext in PLAIN.  */
547 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
548                                    GpgmeData cipher, GpgmeData plain);
549 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
550                              GpgmeData cipher, GpgmeData plain);
551
552 /* Decrypt ciphertext CIPHER and make a signature verification within
553    CTX and store the resulting plaintext in PLAIN.  */
554 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
555                                           GpgmeData cipher, GpgmeData plain);
556 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
557                                     GpgmeData cipher, GpgmeData plain,
558                                     GpgmeSigStat *r_status);
559
560 /* Sign the plaintext PLAIN and store the signature in SIG.  Only
561    detached signatures are supported for now.  */
562 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
563                                 GpgmeData plain, GpgmeData sig,
564                                 GpgmeSigMode mode);
565 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
566                           GpgmeData plain, GpgmeData sig,
567                           GpgmeSigMode mode);
568
569 /* Verify within CTX that SIG is a valid signature for TEXT.  */
570 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx,
571                                   GpgmeData sig, GpgmeData text);
572 GpgmeError gpgme_op_verify (GpgmeCtx ctx,
573                             GpgmeData sig, GpgmeData text,
574                             GpgmeSigStat *r_status);
575
576 /* Import the key in KEYDATA into the keyring.  */
577 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
578 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
579
580 /* Export the keys listed in RECP into KEYDATA.  */
581 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
582                                   GpgmeData keydata);
583 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
584                             GpgmeData keydata);
585
586 /* Generate a new keypair and add it to the keyring.  PUBKEY and
587    SECKEY should be null for now.  PARMS specifies what keys should be
588    generated.  */
589 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
590                                   GpgmeData pubkey, GpgmeData seckey);
591 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
592                             GpgmeData pubkey, GpgmeData seckey);
593
594 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
595    keys are also deleted.  */
596 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
597                                   int allow_secret);
598 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
599                             int allow_secret);
600
601
602 /* Key management functions */
603
604 /* Start a keylist operation within CTX, searching for keys which
605    match PATTERN.  If SECRET_ONLY is true, only secret keys are
606    returned.  */
607 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
608                                    const char *pattern, int secret_only);
609 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
610                                        int secret_only, int reserved);
611
612 /* Return the next key from the keylist in R_KEY.  */
613 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
614
615 /* Terminate a pending keylist operation within CTX.  */
616 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
617
618
619 /* Start a trustlist operation within CTX, searching for trust items
620    which match PATTERN.  */
621 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
622                                      const char *pattern, int max_level);
623
624 /* Return the next trust item from the trustlist in R_ITEM.  */
625 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
626
627 /* Terminate a pending trustlist operation within CTX.  */
628 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
629
630
631 /* Various functions.  */
632
633 /* Check that the library fulfills the version requirement.  */
634 const char *gpgme_check_version (const char *req_version);
635
636 /* Check that the backend engine is available.  DEPRECATED.  */
637 GpgmeError  gpgme_check_engine (void);
638
639 /* Retrieve information about the backend engines.  */
640 const char *gpgme_get_engine_info (void);
641
642 /* Return a string describing ERR.  */
643 const char *gpgme_strerror (GpgmeError err);
644
645 /* Register an idle function.  */
646 typedef void (*GpgmeIdleFunc)(void);
647 GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle);
648
649
650 /* Engine support functions.  */
651
652 /* Verify that the engine implementing PROTO is installed and
653    available.  */
654 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
655
656
657 #ifdef __cplusplus
658 }
659 #endif
660 #endif /* GPGME_H */