doc/
[gpgme.git] / gpgme / gpgme.h
1 /* gpgme.h - Public interface to 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 #ifndef GPGME_H
22 #define GPGME_H
23
24 /* Include stdio.h for the FILE type definition.  */
25 #include <stdio.h>
26
27 #ifdef _MSC_VER
28   typedef long off_t;
29   typedef long ssize_t;
30 #else
31 # include <sys/types.h>
32 #endif
33
34 #ifdef __cplusplus
35 extern "C" {
36 #if 0 /* just to make Emacs auto-indent happy */
37 }
38 #endif
39 #endif
40
41 \f
42 /* The version of this header should match the one of the library.  Do
43    not use this symbol in your application, use gpgme_check_version
44    instead.  The purpose of this macro is to let autoconf (using the
45    AM_PATH_GPGME macro) check that this header matches the installed
46    library.  Warning: Do not edit the next line.  configure will do
47    that for you!  */
48 #define GPGME_VERSION "0.4.1"
49
50 \f
51 /* The opaque data types used by GPGME.  */
52
53 /* The context holds some global state and configration options, as
54    well as the results of a crypto operation.  */
55 struct gpgme_context_s;
56 typedef struct gpgme_context_s *GpgmeCtx;
57
58 /* The data object is used by GPGME to exchange arbitrary data.  */
59 struct gpgme_data_s;
60 typedef struct gpgme_data_s *GpgmeData;
61
62 /* A list of recipients to be used in an encryption operation.  */
63 struct gpgme_recipients_s;
64 typedef struct gpgme_recipients_s *GpgmeRecipients;
65
66 \f
67 /* Public data types provided by GPGME.  */
68
69 /* The error numbers used by GPGME.  */
70 typedef enum
71   {
72     GPGME_EOF                     = -1,
73     GPGME_No_Error                = 0x0000,
74     GPGME_General_Error           = 0x0001,
75     GPGME_Out_Of_Core             = 0x0002,
76     GPGME_Invalid_Value           = 0x0003,
77     GPGME_Exec_Error              = 0x0004,
78     GPGME_Too_Many_Procs          = 0x0005,
79     GPGME_Pipe_Error              = 0x0006,
80     GPGME_No_Data                 = 0x0007,
81     GPGME_Conflict                = 0x0008,
82     GPGME_Not_Implemented         = 0x0009,
83     GPGME_Read_Error              = 0x000a,
84     GPGME_Write_Error             = 0x000b,
85     GPGME_File_Error              = 0x000c, /* errno is set in this case.  */
86     GPGME_Decryption_Failed       = 0x000d,
87     GPGME_Bad_Passphrase          = 0x000e,
88     GPGME_Canceled                = 0x000f,
89     GPGME_Invalid_Key             = 0x0010,
90     GPGME_Invalid_Engine          = 0x0011,
91     GPGME_No_UserID               = 0x0012,
92     GPGME_Invalid_UserID          = 0x0013,
93
94     /* Reasons for invalid user id.  */
95     GPGME_Unknown_Reason          = 0x0100,
96     GPGME_Not_Found               = 0x0101,
97     GPGME_Ambiguous_Specification = 0x0102,
98     GPGME_Wrong_Key_Usage         = 0x0103,
99     GPGME_Key_Revoked             = 0x0104,
100     GPGME_Key_Expired             = 0x0105,
101     GPGME_No_CRL_Known            = 0x0106,
102     GPGME_CRL_Too_Old             = 0x0107,
103     GPGME_Policy_Mismatch         = 0x0108,
104     GPGME_No_Secret_Key           = 0x0109,
105     GPGME_Key_Not_Trusted         = 0x010a,
106     
107     /* Import problems.  */
108     GPGME_Issuer_Missing          = 0x0200,
109     GPGME_Chain_Too_Long          = 0x0201,
110
111     /* Verification problems.  */
112     GPGME_Unsupported_Algorithm   = 0x0300,
113     GPGME_Sig_Expired             = 0x0301,
114     GPGME_Bad_Signature           = 0x0302,
115     GPGME_No_Public_Key           = 0x0303,
116
117     /* Deprecated.  */
118     GPGME_Busy                    = -2,
119     GPGME_No_Request              = -3
120   }
121 GpgmeError;
122
123 #define GPGME_No_Recipients     GPGME_No_UserID
124 #define GPGME_Invalid_Recipient GPGME_Invalid_UserID
125 #define GPGME_No_Passphrase     GPGME_Bad_Passphrase
126
127
128 /* The possible encoding mode of GpgmeData objects.  */
129 typedef enum
130   {
131     GPGME_DATA_ENCODING_NONE   = 0,     /* Not specified.  */
132     GPGME_DATA_ENCODING_BINARY = 1,
133     GPGME_DATA_ENCODING_BASE64 = 2,
134     GPGME_DATA_ENCODING_ARMOR  = 3      /* Either PEM or OpenPGP Armor.  */
135   }
136 GpgmeDataEncoding;
137
138
139 /* Public key algorithms from libgcrypt.  */
140 typedef enum
141   {
142     GPGME_PK_RSA   = 1,
143     GPGME_PK_RSA_E = 2,
144     GPGME_PK_RSA_S = 3,
145     GPGME_PK_ELG_E = 16,
146     GPGME_PK_DSA   = 17,
147     GPGME_PK_ELG   = 20
148   }
149 GpgmePubKeyAlgo;
150
151
152 /* Hash algorithms from libgcrypt.  */
153 typedef enum
154   {
155     GPGME_MD_NONE          = 0,  
156     GPGME_MD_MD5           = 1,
157     GPGME_MD_SHA1          = 2,
158     GPGME_MD_RMD160        = 3,
159     GPGME_MD_MD2           = 5,
160     GPGME_MD_TIGER         = 6,   /* TIGER/192. */
161     GPGME_MD_HAVAL         = 7,   /* HAVAL, 5 pass, 160 bit. */
162     GPGME_MD_SHA256        = 8,
163     GPGME_MD_SHA384        = 9,
164     GPGME_MD_SHA512        = 10,
165     GPGME_MD_MD4           = 301,
166     GPGME_MD_CRC32         = 302,
167     GPGME_MD_CRC32_RFC1510 = 303,
168     GPGME_MD_CRC24_RFC2440 = 304
169   }
170 GpgmeHashAlgo;
171
172
173 /* The possible signature stati.  */
174 typedef enum
175   {
176     GPGME_SIG_STAT_NONE  = 0,
177     GPGME_SIG_STAT_GOOD  = 1,
178     GPGME_SIG_STAT_BAD   = 2,
179     GPGME_SIG_STAT_NOKEY = 3,
180     GPGME_SIG_STAT_NOSIG = 4,
181     GPGME_SIG_STAT_ERROR = 5,
182     GPGME_SIG_STAT_DIFF  = 6,
183     GPGME_SIG_STAT_GOOD_EXP = 7,
184     GPGME_SIG_STAT_GOOD_EXPKEY = 8
185   }
186 GpgmeSigStat;
187
188 /* The available signature modes.  */
189 typedef enum
190   {
191     GPGME_SIG_MODE_NORMAL = 0,
192     GPGME_SIG_MODE_DETACH = 1,
193     GPGME_SIG_MODE_CLEAR  = 2
194   }
195 GpgmeSigMode;
196
197
198 /* The available key and signature attributes.  */
199 typedef enum
200   {
201     GPGME_ATTR_KEYID        = 1,
202     GPGME_ATTR_FPR          = 2,
203     GPGME_ATTR_ALGO         = 3,
204     GPGME_ATTR_LEN          = 4,
205     GPGME_ATTR_CREATED      = 5,
206     GPGME_ATTR_EXPIRE       = 6,
207     GPGME_ATTR_OTRUST       = 7,
208     GPGME_ATTR_USERID       = 8,
209     GPGME_ATTR_NAME         = 9,
210     GPGME_ATTR_EMAIL        = 10,
211     GPGME_ATTR_COMMENT      = 11,
212     GPGME_ATTR_VALIDITY     = 12,
213     GPGME_ATTR_LEVEL        = 13,
214     GPGME_ATTR_TYPE         = 14,
215     GPGME_ATTR_IS_SECRET    = 15,
216     GPGME_ATTR_KEY_REVOKED  = 16,
217     GPGME_ATTR_KEY_INVALID  = 17,
218     GPGME_ATTR_UID_REVOKED  = 18,
219     GPGME_ATTR_UID_INVALID  = 19,
220     GPGME_ATTR_KEY_CAPS     = 20,
221     GPGME_ATTR_CAN_ENCRYPT  = 21,
222     GPGME_ATTR_CAN_SIGN     = 22,
223     GPGME_ATTR_CAN_CERTIFY  = 23,
224     GPGME_ATTR_KEY_EXPIRED  = 24,
225     GPGME_ATTR_KEY_DISABLED = 25,
226     GPGME_ATTR_SERIAL       = 26,
227     GPGME_ATTR_ISSUER       = 27,
228     GPGME_ATTR_CHAINID      = 28,
229     GPGME_ATTR_SIG_STATUS   = 29,
230     GPGME_ATTR_ERRTOK       = 30,
231     GPGME_ATTR_SIG_SUMMARY  = 31,
232     GPGME_ATTR_SIG_CLASS    = 32
233   }
234 GpgmeAttr;
235
236 /* The available validities for a trust item or key.  */
237 typedef enum
238   {
239     GPGME_VALIDITY_UNKNOWN   = 0,
240     GPGME_VALIDITY_UNDEFINED = 1,
241     GPGME_VALIDITY_NEVER     = 2,
242     GPGME_VALIDITY_MARGINAL  = 3,
243     GPGME_VALIDITY_FULL      = 4,
244     GPGME_VALIDITY_ULTIMATE  = 5
245   }
246 GpgmeValidity;
247
248
249 /* The available protocols.  */
250 typedef enum
251   {
252     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
253     GPGME_PROTOCOL_CMS     = 1,
254   }
255 GpgmeProtocol;
256
257 \f
258 /* The possible stati for the edit operation.  */
259 typedef enum
260   {
261     GPGME_STATUS_EOF,
262     /* mkstatus processing starts here */
263     GPGME_STATUS_ENTER,
264     GPGME_STATUS_LEAVE,
265     GPGME_STATUS_ABORT,
266
267     GPGME_STATUS_GOODSIG,
268     GPGME_STATUS_BADSIG,
269     GPGME_STATUS_ERRSIG,
270
271     GPGME_STATUS_BADARMOR,
272
273     GPGME_STATUS_RSA_OR_IDEA,
274     GPGME_STATUS_KEYEXPIRED,
275     GPGME_STATUS_KEYREVOKED,
276
277     GPGME_STATUS_TRUST_UNDEFINED,
278     GPGME_STATUS_TRUST_NEVER,
279     GPGME_STATUS_TRUST_MARGINAL,
280     GPGME_STATUS_TRUST_FULLY,
281     GPGME_STATUS_TRUST_ULTIMATE,
282
283     GPGME_STATUS_SHM_INFO,
284     GPGME_STATUS_SHM_GET,
285     GPGME_STATUS_SHM_GET_BOOL,
286     GPGME_STATUS_SHM_GET_HIDDEN,
287
288     GPGME_STATUS_NEED_PASSPHRASE,
289     GPGME_STATUS_VALIDSIG,
290     GPGME_STATUS_SIG_ID,
291     GPGME_STATUS_ENC_TO,
292     GPGME_STATUS_NODATA,
293     GPGME_STATUS_BAD_PASSPHRASE,
294     GPGME_STATUS_NO_PUBKEY,
295     GPGME_STATUS_NO_SECKEY,
296     GPGME_STATUS_NEED_PASSPHRASE_SYM,
297     GPGME_STATUS_DECRYPTION_FAILED,
298     GPGME_STATUS_DECRYPTION_OKAY,
299     GPGME_STATUS_MISSING_PASSPHRASE,
300     GPGME_STATUS_GOOD_PASSPHRASE,
301     GPGME_STATUS_GOODMDC,
302     GPGME_STATUS_BADMDC,
303     GPGME_STATUS_ERRMDC,
304     GPGME_STATUS_IMPORTED,
305     GPGME_STATUS_IMPORT_OK,
306     GPGME_STATUS_IMPORT_PROBLEM,
307     GPGME_STATUS_IMPORT_RES,
308     GPGME_STATUS_FILE_START,
309     GPGME_STATUS_FILE_DONE,
310     GPGME_STATUS_FILE_ERROR,
311
312     GPGME_STATUS_BEGIN_DECRYPTION,
313     GPGME_STATUS_END_DECRYPTION,
314     GPGME_STATUS_BEGIN_ENCRYPTION,
315     GPGME_STATUS_END_ENCRYPTION,
316
317     GPGME_STATUS_DELETE_PROBLEM,
318     GPGME_STATUS_GET_BOOL,
319     GPGME_STATUS_GET_LINE,
320     GPGME_STATUS_GET_HIDDEN,
321     GPGME_STATUS_GOT_IT,
322     GPGME_STATUS_PROGRESS,
323     GPGME_STATUS_SIG_CREATED,
324     GPGME_STATUS_SESSION_KEY,
325     GPGME_STATUS_NOTATION_NAME,
326     GPGME_STATUS_NOTATION_DATA,
327     GPGME_STATUS_POLICY_URL,
328     GPGME_STATUS_BEGIN_STREAM,
329     GPGME_STATUS_END_STREAM,
330     GPGME_STATUS_KEY_CREATED,
331     GPGME_STATUS_USERID_HINT,
332     GPGME_STATUS_UNEXPECTED,
333     GPGME_STATUS_INV_RECP,
334     GPGME_STATUS_NO_RECP,
335     GPGME_STATUS_ALREADY_SIGNED,
336     GPGME_STATUS_SIGEXPIRED,
337     GPGME_STATUS_EXPSIG,
338     GPGME_STATUS_EXPKEYSIG,
339     GPGME_STATUS_TRUNCATED,
340     GPGME_STATUS_ERROR
341   }
342 GpgmeStatusCode;
343
344 \f
345 /* The engine information structure.  */
346 struct _gpgme_engine_info
347 {
348   struct _gpgme_engine_info *next;
349
350   /* The protocol ID.  */
351   GpgmeProtocol protocol;
352
353   /* The file name of the engine binary.  */
354   const char *file_name;
355
356   /* The version string of the installed engine.  */
357   const char *version;
358
359   /* The minimum version required for GPGME.  */
360   const char *req_version;
361 };
362 typedef struct _gpgme_engine_info *GpgmeEngineInfo;
363
364 \f
365 /* A subkey from a key.  */
366 struct _gpgme_subkey
367 {
368   struct _gpgme_subkey *next;
369
370   /* True if subkey is revoked.  */
371   unsigned int revoked : 1;
372
373   /* True if subkey is expired.  */
374   unsigned int expired : 1;
375
376   /* True if subkey is disabled.  */
377   unsigned int disabled : 1;
378
379   /* True if subkey is invalid.  */
380   unsigned int invalid : 1;
381
382   /* True if subkey can be used for encryption.  */
383   unsigned int can_encrypt : 1;
384
385   /* True if subkey can be used for signing.  */
386   unsigned int can_sign : 1;
387
388   /* True if subkey can be used for certification.  */
389   unsigned int can_certify : 1;
390
391   /* True if subkey is secret.  */
392   unsigned int secret : 1;
393
394   /* Internal to GPGME, do not use.  */
395   unsigned int _unused : 24;
396   
397   /* Public key algorithm supported by this subkey.  */
398   GpgmePubKeyAlgo pubkey_algo;
399
400   /* Length of the subkey.  */
401   unsigned int length;
402
403   /* The key ID of the subkey.  */
404   char *keyid;
405
406   /* Internal to GPGME, do not use.  */
407   char _keyid[16 + 1];
408
409   /* The fingerprint of the subkey in hex digit form.  */
410   char *fpr;
411
412   /* The creation timestamp, -1 if invalid, 0 if not available.  */
413   long int timestamp;
414
415   /* The expiration timestamp, 0 if the subkey does not expire.  */
416   long int expires;
417 };
418 typedef struct _gpgme_subkey *GpgmeSubkey;
419
420 /* A signature on a user ID.  */
421 struct _gpgme_key_sig
422 {
423   struct _gpgme_key_sig *next;
424
425   /* True if the signature is revoked.  */
426   unsigned int revoked : 1;
427
428   /* True if the signature is expired.  */
429   unsigned int expired : 1;
430
431   /* True if the signature is invalid.  */
432   unsigned int invalid : 1;
433
434   /* True if the signature should be exported.  */
435   unsigned int exportable : 1;
436
437   /* Internal to GPGME, do not use.  */
438   unsigned int _unused : 28;
439
440   /* The public key algorithm used to create the signature.  */
441   GpgmePubKeyAlgo pubkey_algo;
442
443   /* The key ID of key used to create the signature.  */
444   char *keyid;
445
446   /* Internal to GPGME, do not use.  */
447   char _keyid[16 + 1];
448
449   /* The creation timestamp, -1 if invalid, 0 if not available.  */
450   long int timestamp;
451
452   /* The expiration timestamp, 0 if the subkey does not expire.  */
453   long int expires;
454
455   /* Same as in GpgmeSignature.  */
456   GpgmeError status;
457
458   /* Crypto backend specific signature class.  */
459   unsigned int class;
460
461   /* The user ID string.  */
462   char *uid;
463
464   /* The name part of the user ID.  */
465   char *name;
466
467   /* The email part of the user ID.  */
468   char *email;
469
470   /* The comment part of the user ID.  */
471   char *comment;
472 };
473 typedef struct _gpgme_key_sig *GpgmeKeySig;
474
475 /* An user ID from a key.  */
476 struct _gpgme_user_id
477 {
478   struct _gpgme_user_id *next;
479
480   /* True if the user ID is revoked.  */
481   unsigned int revoked : 1;
482
483   /* True if the user ID is invalid.  */
484   unsigned int invalid : 1;
485
486   /* Internal to GPGME, do not use.  */
487   unsigned int _unused : 30;
488
489   /* The validity of the user ID.  */
490   GpgmeValidity validity; 
491
492   /* The user ID string.  */
493   char *uid;
494
495   /* The name part of the user ID.  */
496   char *name;
497
498   /* The email part of the user ID.  */
499   char *email;
500
501   /* The comment part of the user ID.  */
502   char *comment;
503
504   /* The signatures of the user ID.  */
505   GpgmeKeySig signatures;
506
507   /* Internal to GPGME, do not use.  */
508   GpgmeKeySig _last_keysig;
509 };
510 typedef struct _gpgme_user_id *GpgmeUserID;
511
512 /* A key from the keyring.  */
513 struct _gpgme_key
514 {
515   /* Internal to GPGME, do not use.  */
516   unsigned int _refs;
517
518   /* True if key is revoked.  */
519   unsigned int revoked : 1;
520
521   /* True if key is expired.  */
522   unsigned int expired : 1;
523
524   /* True if key is disabled.  */
525   unsigned int disabled : 1;
526
527   /* True if key is invalid.  */
528   unsigned int invalid : 1;
529
530   /* True if key can be used for encryption.  */
531   unsigned int can_encrypt : 1;
532
533   /* True if key can be used for signing.  */
534   unsigned int can_sign : 1;
535
536   /* True if key can be used for certification.  */
537   unsigned int can_certify : 1;
538
539   /* True if key is secret.  */
540   unsigned int secret : 1;
541
542   /* Internal to GPGME, do not use.  */
543   unsigned int _unused : 24;
544
545   /* This is the protocol supported by this key.  */
546   GpgmeProtocol protocol;
547
548   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
549      issuer serial.  */
550   char *issuer_serial;
551
552   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
553      issuer name.  */
554   char *issuer_name;
555
556   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
557      ID.  */
558   char *chain_id;
559
560   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
561      owner trust.  */
562   GpgmeValidity owner_trust;
563
564   /* The subkeys of the key.  */
565   GpgmeSubkey subkeys;
566
567   /* The user IDs of the key.  */
568   GpgmeUserID uids;
569
570   /* Internal to GPGME, do not use.  */
571   GpgmeSubkey _last_subkey;
572
573   /* Internal to GPGME, do not use.  */
574   GpgmeUserID _last_uid;
575 };
576 typedef struct _gpgme_key *GpgmeKey;
577
578 \f
579 /* Types for callback functions.  */
580
581 /* Request a passphrase from the user.  */
582 typedef GpgmeError (*GpgmePassphraseCb) (void *hook, const char *desc,
583                                          void **r_hd, const char **result);
584
585 /* Inform the user about progress made.  */
586 typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
587                                  int type, int current, int total);
588
589 /* Interact with the user about an edit operation.  */
590 typedef GpgmeError (*GpgmeEditCb) (void *opaque, GpgmeStatusCode status,
591                                    const char *args, const char **reply);
592
593 \f
594 /* Context management functions.  */
595
596 /* Create a new context and return it in CTX.  */
597 GpgmeError gpgme_new (GpgmeCtx *ctx);
598
599 /* Release the context CTX.  */
600 void gpgme_release (GpgmeCtx ctx);
601
602 /* Set the protocol to be used by CTX to PROTO.  */
603 GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
604
605 /* Get the protocol used with CTX */
606 GpgmeProtocol gpgme_get_protocol (GpgmeCtx ctx);
607
608 /* Get the string describing protocol PROTO, or NULL if invalid.  */
609 const char *gpgme_get_protocol_name (GpgmeProtocol proto);
610
611 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
612 void gpgme_set_armor (GpgmeCtx ctx, int yes);
613
614 /* Return non-zero if armor mode is set in CTX.  */
615 int gpgme_get_armor (GpgmeCtx ctx);
616
617 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
618 void gpgme_set_textmode (GpgmeCtx ctx, int yes);
619
620 /* Return non-zero if text mode is set in CTX.  */
621 int gpgme_get_textmode (GpgmeCtx ctx);
622
623 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
624 void gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs);
625
626 /* Return the number of certs to include in an S/MIME message.  */
627 int gpgme_get_include_certs (GpgmeCtx ctx);
628
629 /* The available keylist mode flags.  */
630 enum
631   {
632     GPGME_KEYLIST_MODE_LOCAL  = 1,
633     GPGME_KEYLIST_MODE_EXTERN = 2,
634     GPGME_KEYLIST_MODE_SIGS   = 4
635   };
636
637 /* Set keylist mode in CTX to MODE.  */
638 GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
639
640 /* Get keylist mode in CTX.  */
641 int gpgme_get_keylist_mode (GpgmeCtx ctx);
642
643 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
644    passed as first argument to the passphrase callback function.  */
645 void gpgme_set_passphrase_cb (GpgmeCtx ctx,
646                               GpgmePassphraseCb cb, void *hook_value);
647
648 /* Get the current passphrase callback function in *CB and the current
649    hook value in *HOOK_VALUE.  */
650 void gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *cb,
651                               void **hook_value);
652
653 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
654    passed as first argument to the progress callback function.  */
655 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
656
657 /* Get the current progress callback function in *CB and the current
658    hook value in *HOOK_VALUE.  */
659 void gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *cb,
660                             void **hook_value);
661
662 \f
663 /* Return a statically allocated string with the name of the public
664    key algorithm ALGO, or NULL if that name is not known.  */
665 const char *gpgme_pubkey_algo_name (GpgmePubKeyAlgo algo);
666
667 /* Return a statically allocated string with the name of the hash
668    algorithm ALGO, or NULL if that name is not known.  */
669 const char *gpgme_hash_algo_name (GpgmeHashAlgo algo);
670
671 \f
672 /* Delete all signers from CTX.  */
673 void gpgme_signers_clear (GpgmeCtx ctx);
674
675 /* Add KEY to list of signers in CTX.  */
676 GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
677
678 /* Return the SEQth signer's key in CTX.  */
679 GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
680
681 /* Retrieve the signature status of signature IDX in CTX after a
682    successful verify operation in R_STAT (if non-null).  The creation
683    time stamp of the signature is returned in R_CREATED (if non-null).
684    The function returns a string containing the fingerprint.  */
685 const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
686                                   GpgmeSigStat *r_stat, time_t *r_created);
687
688 /* Retrieve certain attributes of a signature.  IDX is the index
689    number of the signature after a successful verify operation.  WHAT
690    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
691    one.  WHATIDX is to be passed as 0 for most attributes . */
692 unsigned long gpgme_get_sig_ulong_attr (GpgmeCtx c, int idx,
693                                         GpgmeAttr what, int whatidx);
694 const char *gpgme_get_sig_string_attr (GpgmeCtx c, int idx,
695                                       GpgmeAttr what, int whatidx);
696
697
698 /* Get the key used to create signature IDX in CTX and return it in
699    R_KEY.  */
700 GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
701
702 \f
703 /* Run control.  */
704
705 /* The type of an I/O callback function.  */
706 typedef GpgmeError (*GpgmeIOCb) (void *data, int fd);
707
708 /* The type of a function that can register FNC as the I/O callback
709    function for the file descriptor FD with direction dir (0: for writing,
710    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
711    function should return a TAG suitable for the corresponding
712    GpgmeRemoveIOCb, and an error value.  */
713 typedef GpgmeError (*GpgmeRegisterIOCb) (void *data, int fd, int dir,
714                                          GpgmeIOCb fnc, void *fnc_data,
715                                          void **tag);
716
717 /* The type of a function that can remove a previously registered I/O
718    callback function given TAG as returned by the register
719    function.  */
720 typedef void (*GpgmeRemoveIOCb) (void *tag);
721
722 typedef enum { GPGME_EVENT_START,
723                GPGME_EVENT_DONE,
724                GPGME_EVENT_NEXT_KEY,
725                GPGME_EVENT_NEXT_TRUSTITEM } GpgmeEventIO;
726
727 /* The type of a function that is called when a context finished an
728    operation.  */
729 typedef void (*GpgmeEventIOCb) (void *data, GpgmeEventIO type,
730                                 void *type_data);
731
732 struct GpgmeIOCbs
733 {
734   GpgmeRegisterIOCb add;
735   void *add_priv;
736   GpgmeRemoveIOCb remove;
737   GpgmeEventIOCb event;
738   void *event_priv;
739 };
740
741 /* Set the I/O callback functions in CTX to IO_CBS.  */
742 void gpgme_set_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
743
744 /* Get the current I/O callback functions.  */
745 void gpgme_get_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
746
747 /* Process the pending operation and, if HANG is non-zero, wait for
748    the pending operation to finish.  */
749 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
750
751 \f
752 /* Functions to handle recipients.  */
753
754 /* Create a new recipients set and return it in R_RSET.  */
755 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
756
757 /* Release the recipients set RSET.  */
758 void gpgme_recipients_release (GpgmeRecipients rset);
759
760 /* Add NAME to the recipients set RSET.  */
761 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
762
763 /* Add NAME with validity AL to the recipients set RSET.  */
764 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
765                                                     const char *name,
766                                                     GpgmeValidity val);
767
768 /* Return the number of recipients in RSET.  */
769 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
770
771 /* Create a new enumeration handle for the recipients set RSET and
772    return it in ITER.  */
773 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
774                                        void **iter);
775
776 /* Return the next recipient from the recipient set RSET in the
777    enumerator ITER.  */
778 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
779                                         void **iter);
780
781 /* Destroy the enumerator ITER for the recipient set RSET.  */
782 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
783                                         void **iter);
784
785 \f
786 /* Functions to handle data objects.  */
787
788 /* Read up to SIZE bytes into buffer BUFFER from the data object with
789    the handle HANDLE.  Return the number of characters read, 0 on EOF
790    and -1 on error.  If an error occurs, errno is set.  */
791 typedef ssize_t (*GpgmeDataReadCb) (void *handle, void *buffer, size_t size);
792
793 /* Write up to SIZE bytes from buffer BUFFER to the data object with
794    the handle HANDLE.  Return the number of characters written, or -1
795    on error.  If an error occurs, errno is set.  */
796 typedef ssize_t (*GpgmeDataWriteCb) (void *handle, const void *buffer,
797                                      size_t size);
798
799 /* Set the current position from where the next read or write starts
800    in the data object with the handle HANDLE to OFFSET, relativ to
801    WHENCE.  */
802 typedef off_t (*GpgmeDataSeekCb) (void *handle, off_t offset, int whence);
803
804 /* Close the data object with the handle DL.  */
805 typedef void (*GpgmeDataReleaseCb) (void *handle);
806
807 struct GpgmeDataCbs
808 {
809   GpgmeDataReadCb read;
810   GpgmeDataWriteCb write;
811   GpgmeDataSeekCb seek;
812   GpgmeDataReleaseCb release;
813 };
814
815 /* Read up to SIZE bytes into buffer BUFFER from the data object with
816    the handle DH.  Return the number of characters read, 0 on EOF and
817    -1 on error.  If an error occurs, errno is set.  */
818 ssize_t gpgme_data_read (GpgmeData dh, void *buffer, size_t size);
819
820 /* Write up to SIZE bytes from buffer BUFFER to the data object with
821    the handle DH.  Return the number of characters written, or -1 on
822    error.  If an error occurs, errno is set.  */
823 ssize_t gpgme_data_write (GpgmeData dh, const void *buffer, size_t size);
824
825 /* Set the current position from where the next read or write starts
826    in the data object with the handle DH to OFFSET, relativ to
827    WHENCE.  */
828 off_t gpgme_data_seek (GpgmeData dh, off_t offset, int whence);
829
830 /* Create a new data buffer and return it in R_DH.  */
831 GpgmeError gpgme_data_new (GpgmeData *r_dh);
832
833 /* Destroy the data buffer DH.  */
834 void gpgme_data_release (GpgmeData dh);
835
836 /* Create a new data buffer filled with SIZE bytes starting from
837    BUFFER.  If COPY is zero, copying is delayed until necessary, and
838    the data is taken from the original location when needed.  */
839 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
840                                     const char *buffer, size_t size,
841                                     int copy);
842
843 /* Destroy the data buffer DH and return a pointer to its content.
844    The memory has be to released with free by the user.  It's size is
845    returned in R_LEN.  */
846 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
847
848 GpgmeError gpgme_data_new_from_cbs (GpgmeData *dh,
849                                     struct GpgmeDataCbs *cbs,
850                                     void *handle);
851
852 GpgmeError gpgme_data_new_from_fd (GpgmeData *dh, int fd);
853
854 GpgmeError gpgme_data_new_from_stream (GpgmeData *dh, FILE *stream);
855
856 /* Return the encoding attribute of the data buffer DH */
857 GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh);
858
859 /* Set the encoding attribute of data buffer DH to ENC */
860 GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc);
861
862
863
864 /* Create a new data buffer which retrieves the data from the callback
865    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
866    instead.  */
867 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
868                                         int (*read_cb) (void*,char *,size_t,size_t*),
869                                         void *read_cb_value);
870
871 /* Create a new data buffer filled with the content of file FNAME.
872    COPY must be non-zero.  For delayed read, please use
873    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
874 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
875                                      const char *fname,
876                                      int copy);
877
878 /* Create a new data buffer filled with LENGTH bytes starting from
879    OFFSET within the file FNAME or stream FP (exactly one must be
880    non-zero).  */
881 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
882                                          const char *fname, FILE *fp,
883                                          off_t offset, size_t length);
884
885 /* Reset the read pointer in DH.  Deprecated, please use
886    gpgme_data_seek instead.  */
887 GpgmeError gpgme_data_rewind (GpgmeData dh);
888
889 \f
890 /* Key and trust functions.  */
891
892 /* Get the key with the fingerprint FPR from the crypto backend.  If
893    SECRET is true, get the secret key.  */
894 GpgmeError gpgme_get_key (GpgmeCtx ctx, const char *fpr, GpgmeKey *r_key,
895                           int secret);
896
897 /* Acquire a reference to KEY.  */
898 void gpgme_key_ref (GpgmeKey key);
899
900 /* Release a reference to KEY.  If this was the last one the key is
901    destroyed.  */
902 void gpgme_key_unref (GpgmeKey key);
903 void gpgme_key_release (GpgmeKey key);
904
905 /* Return the value of the attribute WHAT of KEY, which has to be
906    representable by a string.  IDX specifies the sub key or
907    user ID for attributes related to sub keys or user IDs.  */
908 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
909                                        const void *reserved, int idx);
910
911 /* Return the value of the attribute WHAT of KEY, which has to be
912    representable by an unsigned integer.  IDX specifies the sub key or
913    user ID for attributes related to sub keys or user IDs.  */
914 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
915                                         const void *reserved, int idx);
916
917 /* Return the value of the attribute WHAT of a signature on user ID
918    UID_IDX in KEY, which has to be representable by a string.  IDX
919    specifies the signature.  */
920 const char *gpgme_key_sig_get_string_attr (GpgmeKey key, int uid_idx,
921                                            GpgmeAttr what,
922                                            const void *reserved, int idx);
923
924 /* Return the value of the attribute WHAT of a signature on user ID
925    UID_IDX in KEY, which has to be representable by an unsigned
926    integer string.  IDX specifies the signature.  */
927 unsigned long gpgme_key_sig_get_ulong_attr (GpgmeKey key, int uid_idx,
928                                             GpgmeAttr what,
929                                             const void *reserved, int idx);
930
931 \f
932 /* Crypto Operations.  */
933
934 struct _gpgme_invalid_user_id
935 {
936   struct _gpgme_invalid_user_id *next;
937   char *id;
938   GpgmeError reason;
939 };
940 typedef struct _gpgme_invalid_user_id *GpgmeInvalidUserID;
941
942 \f
943 /* Encryption.  */
944 struct _gpgme_op_encrypt_result
945 {
946   /* The list of invalid recipients.  */
947   GpgmeInvalidUserID invalid_recipients;
948 };
949 typedef struct _gpgme_op_encrypt_result *GpgmeEncryptResult;
950
951 /* Retrieve a pointer to the result of the encrypt operation.  */
952 GpgmeEncryptResult gpgme_op_encrypt_result (GpgmeCtx ctx);
953
954 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
955    store the resulting ciphertext in CIPHER.  */
956 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
957                                    GpgmeRecipients recp,
958                                    GpgmeData plain, GpgmeData cipher);
959 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
960                              GpgmeRecipients recp,
961                              GpgmeData plain, GpgmeData cipher);
962
963 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
964    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
965    with the signers in CTX.  */
966 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
967                                         GpgmeRecipients recp,
968                                         GpgmeData plain, GpgmeData cipher);
969 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
970                                   GpgmeRecipients recp,
971                                   GpgmeData plain, GpgmeData cipher);
972
973 \f
974 /* Decryption.  */
975 struct _gpgme_op_decrypt_result
976 {
977   char *unsupported_algorithm;
978 };
979 typedef struct _gpgme_op_decrypt_result *GpgmeDecryptResult;
980
981 /* Retrieve a pointer to the result of the decrypt operation.  */
982 GpgmeDecryptResult gpgme_op_decrypt_result (GpgmeCtx ctx);
983
984 /* Decrypt ciphertext CIPHER within CTX and store the resulting
985    plaintext in PLAIN.  */
986 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
987                                    GpgmeData cipher, GpgmeData plain);
988 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
989                              GpgmeData cipher, GpgmeData plain);
990
991 /* Decrypt ciphertext CIPHER and make a signature verification within
992    CTX and store the resulting plaintext in PLAIN.  */
993 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
994                                           GpgmeData cipher, GpgmeData plain);
995 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
996                                     GpgmeData cipher, GpgmeData plain);
997
998 \f
999 /* Signing.  */
1000 struct _gpgme_new_signature
1001 {
1002   struct _gpgme_new_signature *next;
1003   GpgmeSigMode type;
1004   GpgmePubKeyAlgo pubkey_algo;
1005   GpgmeHashAlgo hash_algo;
1006   unsigned long class;
1007   long int timestamp;
1008   char *fpr;
1009 };
1010 typedef struct _gpgme_new_signature *GpgmeNewSignature;
1011
1012 struct _gpgme_op_sign_result
1013 {
1014   /* The list of invalid signers.  */
1015   GpgmeInvalidUserID invalid_signers;
1016   GpgmeNewSignature signatures;
1017 };
1018 typedef struct _gpgme_op_sign_result *GpgmeSignResult;
1019
1020 /* Retrieve a pointer to the result of the signing operation.  */
1021 GpgmeSignResult gpgme_op_sign_result (GpgmeCtx ctx);
1022
1023 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1024 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
1025                                 GpgmeData plain, GpgmeData sig,
1026                                 GpgmeSigMode mode);
1027 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
1028                           GpgmeData plain, GpgmeData sig,
1029                           GpgmeSigMode mode);
1030
1031 \f
1032 /* Verify.  */
1033 struct _gpgme_sig_notation
1034 {
1035   struct _gpgme_sig_notation *next;
1036
1037   /* If NAME is a null pointer, then VALUE contains a policy URL
1038      rather than a notation.  */
1039   char *name;
1040   char *value;
1041 };
1042 typedef struct _gpgme_sig_notation *GpgmeSigNotation;
1043
1044 /* Flags used for the SUMMARY field in a GpgmeSignature.  */
1045 enum 
1046   {
1047     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1048     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1049     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1050     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1051     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1052     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1053     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1054     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1055     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1056     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1057     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1058   };
1059
1060 struct _gpgme_signature
1061 {
1062   struct _gpgme_signature *next;
1063
1064   /* A summary of the signature status.  */
1065   unsigned int summary;
1066
1067   /* The fingerprint or key ID of the signature.  */
1068   char *fpr;
1069
1070   /* The status of the signature.  */
1071   GpgmeError status;
1072
1073   /* Notation data and policy URLs.  */
1074   GpgmeSigNotation notations;
1075
1076   /* Signature creation time.  */
1077   unsigned long timestamp;
1078
1079   /* Signature exipration time or 0.  */
1080   unsigned long exp_timestamp;
1081
1082   int wrong_key_usage : 1;
1083
1084   /* Internal to GPGME, do not use.  */
1085   int _unused : 31;
1086
1087   GpgmeValidity validity;
1088   GpgmeError validity_reason;
1089 };
1090 typedef struct _gpgme_signature *GpgmeSignature;
1091
1092 struct _gpgme_op_verify_result
1093 {
1094   GpgmeSignature signatures;
1095 };
1096 typedef struct _gpgme_op_verify_result *GpgmeVerifyResult;
1097
1098 /* Retrieve a pointer to the result of the verify operation.  */
1099 GpgmeVerifyResult gpgme_op_verify_result (GpgmeCtx ctx);
1100
1101 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1102 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig,
1103                                   GpgmeData signed_text, GpgmeData plaintext);
1104 GpgmeError gpgme_op_verify (GpgmeCtx ctx, GpgmeData sig,
1105                             GpgmeData signed_text, GpgmeData plaintext);
1106
1107 \f
1108 /* Import.  */
1109 enum
1110   {
1111     /* The key was new.  */
1112     GPGME_IMPORT_NEW = 1,
1113
1114     /* The key contained new user IDs.  */
1115     GPGME_IMPORT_UID = 2,
1116
1117     /* The key contained new signatures.  */
1118     GPGME_IMPORT_SIG = 4,
1119
1120     /* The key contained new sub keys.  */
1121     GPGME_IMPORT_SUBKEY = 8,
1122
1123     /* The key contained a secret key.  */
1124     GPGME_IMPORT_SECRET = 16
1125   };
1126
1127 struct _gpgme_import_status
1128 {
1129   struct _gpgme_import_status *next;
1130
1131   /* Fingerprint.  */
1132   char *fpr;
1133
1134   /* If a problem occured, the reason why the key could not be
1135      imported.  Otherwise GPGME_No_Error.  */
1136   GpgmeError result;
1137
1138   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1139      ORed.  0 means the key was already known and no new components
1140      have been added.  */
1141   unsigned int status;
1142 };
1143 typedef struct _gpgme_import_status *GpgmeImportStatus;
1144
1145 /* Import.  */
1146 struct _gpgme_op_import_result
1147 {
1148   /* Number of considered keys.  */
1149   int considered;
1150
1151   /* Keys without user ID.  */
1152   int no_user_id;
1153
1154   /* Imported keys.  */
1155   int imported;
1156
1157   /* Imported RSA keys.  */
1158   int imported_rsa;
1159
1160   /* Unchanged keys.  */
1161   int unchanged;
1162
1163   /* Number of new user ids.  */
1164   int new_user_ids;
1165
1166   /* Number of new sub keys.  */
1167   int new_sub_keys;
1168
1169   /* Number of new signatures.  */
1170   int new_signatures;
1171
1172   /* Number of new revocations.  */
1173   int new_revocations;
1174
1175   /* Number of secret keys read.  */
1176   int secret_read;
1177
1178   /* Number of secret keys imported.  */
1179   int secret_imported;
1180
1181   /* Number of secret keys unchanged.  */
1182   int secret_unchanged;
1183
1184   /* Number of keys not imported.  */
1185   int not_imported;
1186
1187   /* List of keys for which an import was attempted.  */
1188   GpgmeImportStatus imports;
1189 };
1190 typedef struct _gpgme_op_import_result *GpgmeImportResult;
1191
1192 /* Retrieve a pointer to the result of the import operation.  */
1193 GpgmeImportResult gpgme_op_import_result (GpgmeCtx ctx);
1194
1195 /* Import the key in KEYDATA into the keyring.  */
1196 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
1197 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
1198 GpgmeError gpgme_op_import_ext (GpgmeCtx ctx, GpgmeData keydata, int *nr);
1199
1200 \f
1201 /* Export the keys listed in RECP into KEYDATA.  */
1202 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
1203                                   GpgmeData keydata);
1204 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
1205                             GpgmeData keydata);
1206
1207 \f
1208 /* Key generation.  */
1209 struct _gpgme_op_genkey_result
1210 {
1211   /* A primary key was generated.  */
1212   unsigned int primary : 1;
1213
1214   /* A sub key was generated.  */
1215   unsigned int sub : 1;
1216
1217   /* Internal to GPGME, do not use.  */
1218   unsigned int _unused : 30;
1219
1220   /* The fingerprint of the generated key.  */
1221   char *fpr;
1222 };
1223 typedef struct _gpgme_op_genkey_result *GpgmeGenKeyResult;
1224
1225 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1226    SECKEY should be null for now.  PARMS specifies what keys should be
1227    generated.  */
1228 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
1229                                   GpgmeData pubkey, GpgmeData seckey);
1230 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
1231                             GpgmeData pubkey, GpgmeData seckey);
1232
1233 /* Retrieve a pointer to the result of the genkey operation.  */
1234 GpgmeGenKeyResult gpgme_op_genkey_result (GpgmeCtx ctx);
1235
1236 \f
1237 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1238    keys are also deleted.  */
1239 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
1240                                   int allow_secret);
1241 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
1242                             int allow_secret);
1243
1244 /* Edit the key KEY.  Send status and command requests to FNC and
1245    output of edit commands to OUT.  */
1246 GpgmeError gpgme_op_edit_start (GpgmeCtx ctx, GpgmeKey key,
1247                           GpgmeEditCb fnc, void *fnc_value,
1248                           GpgmeData out);
1249 GpgmeError gpgme_op_edit (GpgmeCtx ctx, GpgmeKey key,
1250                           GpgmeEditCb fnc, void *fnc_value,
1251                           GpgmeData out);
1252
1253 \f
1254 /* Key management functions */
1255 struct _gpgme_op_keylist_result
1256 {
1257   unsigned int truncated : 1;
1258
1259   /* Internal to GPGME, do not use.  */
1260   unsigned int _unused : 31;
1261 };
1262 typedef struct _gpgme_op_keylist_result *GpgmeKeyListResult;
1263
1264 /* Retrieve a pointer to the result of the key listing operation.  */
1265 GpgmeKeyListResult gpgme_op_keylist_result (GpgmeCtx ctx);
1266
1267 /* Start a keylist operation within CTX, searching for keys which
1268    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1269    returned.  */
1270 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
1271                                    const char *pattern, int secret_only);
1272 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
1273                                        int secret_only, int reserved);
1274
1275 /* Return the next key from the keylist in R_KEY.  */
1276 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
1277
1278 /* Terminate a pending keylist operation within CTX.  */
1279 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
1280
1281 \f
1282 /* Trust items and operations.  */
1283
1284 struct _gpgme_trust_item
1285 {
1286   /* Internal to GPGME, do not use.  */
1287   unsigned int _refs;
1288
1289   /* The key ID to which the trust item belongs.  */
1290   char *keyid;
1291
1292   /* Internal to GPGME, do not use.  */
1293   char _keyid[16 + 1];
1294
1295   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1296   int type;
1297
1298   /* The trust level.  */
1299   int level;
1300
1301   /* The owner trust if TYPE is 1.  */
1302   char *owner_trust;
1303
1304   /* Internal to GPGME, do not use.  */
1305   char _owner_trust[2];
1306
1307   /* The calculated validity.  */
1308   char *validity;
1309  
1310   /* Internal to GPGME, do not use.  */
1311   char _validity[2];
1312
1313   /* The user name if TYPE is 2.  */
1314   char *name;
1315 };
1316 typedef struct _gpgme_trust_item *GpgmeTrustItem;
1317
1318 /* Start a trustlist operation within CTX, searching for trust items
1319    which match PATTERN.  */
1320 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
1321                                      const char *pattern, int max_level);
1322
1323 /* Return the next trust item from the trustlist in R_ITEM.  */
1324 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
1325
1326 /* Terminate a pending trustlist operation within CTX.  */
1327 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
1328
1329 /* Acquire a reference to ITEM.  */
1330 void gpgme_trust_item_ref (GpgmeTrustItem item);
1331
1332 /* Release a reference to ITEM.  If this was the last one the trust
1333    item is destroyed.  */
1334 void gpgme_trust_item_unref (GpgmeTrustItem item);
1335
1336 /* Release the trust item ITEM.  */
1337 void gpgme_trust_item_release (GpgmeTrustItem item);
1338
1339 /* Return the value of the attribute WHAT of ITEM, which has to be
1340    representable by a string.  */
1341 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
1342                                               GpgmeAttr what,
1343                                               const void *reserved, int idx);
1344
1345 /* Return the value of the attribute WHAT of KEY, which has to be
1346    representable by an integer.  IDX specifies a running index if the
1347    attribute appears more than once in the key.  */
1348 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
1349                                    const void *reserved, int idx);
1350
1351 \f
1352 /* Various functions.  */
1353
1354 /* Check that the library fulfills the version requirement.  */
1355 const char *gpgme_check_version (const char *req_version);
1356
1357 /* Retrieve information about the backend engines.  */
1358 GpgmeError gpgme_get_engine_info (GpgmeEngineInfo *engine_info);
1359
1360 /* Return a string describing ERR.  */
1361 const char *gpgme_strerror (GpgmeError err);
1362
1363 \f
1364 /* Engine support functions.  */
1365
1366 /* Verify that the engine implementing PROTO is installed and
1367    available.  */
1368 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
1369
1370
1371 #ifdef __cplusplus
1372 }
1373 #endif
1374 #endif /* GPGME_H */