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 /* Return a string with more info about the last crypto operating in CTX.
703    RESERVED should be zero.  The user has to free the string.  */
704 char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
705
706
707 /* Run control.  */
708
709 /* The type of an I/O callback function.  */
710 typedef GpgmeError (*GpgmeIOCb) (void *data, int fd);
711
712 /* The type of a function that can register FNC as the I/O callback
713    function for the file descriptor FD with direction dir (0: for writing,
714    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
715    function should return a TAG suitable for the corresponding
716    GpgmeRemoveIOCb, and an error value.  */
717 typedef GpgmeError (*GpgmeRegisterIOCb) (void *data, int fd, int dir,
718                                          GpgmeIOCb fnc, void *fnc_data,
719                                          void **tag);
720
721 /* The type of a function that can remove a previously registered I/O
722    callback function given TAG as returned by the register
723    function.  */
724 typedef void (*GpgmeRemoveIOCb) (void *tag);
725
726 typedef enum { GPGME_EVENT_START,
727                GPGME_EVENT_DONE,
728                GPGME_EVENT_NEXT_KEY,
729                GPGME_EVENT_NEXT_TRUSTITEM } GpgmeEventIO;
730
731 /* The type of a function that is called when a context finished an
732    operation.  */
733 typedef void (*GpgmeEventIOCb) (void *data, GpgmeEventIO type,
734                                 void *type_data);
735
736 struct GpgmeIOCbs
737 {
738   GpgmeRegisterIOCb add;
739   void *add_priv;
740   GpgmeRemoveIOCb remove;
741   GpgmeEventIOCb event;
742   void *event_priv;
743 };
744
745 /* Set the I/O callback functions in CTX to IO_CBS.  */
746 void gpgme_set_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
747
748 /* Get the current I/O callback functions.  */
749 void gpgme_get_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
750
751 /* Process the pending operation and, if HANG is non-zero, wait for
752    the pending operation to finish.  */
753 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
754
755 \f
756 /* Functions to handle recipients.  */
757
758 /* Create a new recipients set and return it in R_RSET.  */
759 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
760
761 /* Release the recipients set RSET.  */
762 void gpgme_recipients_release (GpgmeRecipients rset);
763
764 /* Add NAME to the recipients set RSET.  */
765 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
766
767 /* Add NAME with validity AL to the recipients set RSET.  */
768 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
769                                                     const char *name,
770                                                     GpgmeValidity val);
771
772 /* Return the number of recipients in RSET.  */
773 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
774
775 /* Create a new enumeration handle for the recipients set RSET and
776    return it in ITER.  */
777 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
778                                        void **iter);
779
780 /* Return the next recipient from the recipient set RSET in the
781    enumerator ITER.  */
782 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
783                                         void **iter);
784
785 /* Destroy the enumerator ITER for the recipient set RSET.  */
786 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
787                                         void **iter);
788
789 \f
790 /* Functions to handle data objects.  */
791
792 /* Read up to SIZE bytes into buffer BUFFER from the data object with
793    the handle HANDLE.  Return the number of characters read, 0 on EOF
794    and -1 on error.  If an error occurs, errno is set.  */
795 typedef ssize_t (*GpgmeDataReadCb) (void *handle, void *buffer, size_t size);
796
797 /* Write up to SIZE bytes from buffer BUFFER to the data object with
798    the handle HANDLE.  Return the number of characters written, or -1
799    on error.  If an error occurs, errno is set.  */
800 typedef ssize_t (*GpgmeDataWriteCb) (void *handle, const void *buffer,
801                                      size_t size);
802
803 /* Set the current position from where the next read or write starts
804    in the data object with the handle HANDLE to OFFSET, relativ to
805    WHENCE.  */
806 typedef off_t (*GpgmeDataSeekCb) (void *handle, off_t offset, int whence);
807
808 /* Close the data object with the handle DL.  */
809 typedef void (*GpgmeDataReleaseCb) (void *handle);
810
811 struct GpgmeDataCbs
812 {
813   GpgmeDataReadCb read;
814   GpgmeDataWriteCb write;
815   GpgmeDataSeekCb seek;
816   GpgmeDataReleaseCb release;
817 };
818
819 /* Read up to SIZE bytes into buffer BUFFER from the data object with
820    the handle DH.  Return the number of characters read, 0 on EOF and
821    -1 on error.  If an error occurs, errno is set.  */
822 ssize_t gpgme_data_read (GpgmeData dh, void *buffer, size_t size);
823
824 /* Write up to SIZE bytes from buffer BUFFER to the data object with
825    the handle DH.  Return the number of characters written, or -1 on
826    error.  If an error occurs, errno is set.  */
827 ssize_t gpgme_data_write (GpgmeData dh, const void *buffer, size_t size);
828
829 /* Set the current position from where the next read or write starts
830    in the data object with the handle DH to OFFSET, relativ to
831    WHENCE.  */
832 off_t gpgme_data_seek (GpgmeData dh, off_t offset, int whence);
833
834 /* Create a new data buffer and return it in R_DH.  */
835 GpgmeError gpgme_data_new (GpgmeData *r_dh);
836
837 /* Destroy the data buffer DH.  */
838 void gpgme_data_release (GpgmeData dh);
839
840 /* Create a new data buffer filled with SIZE bytes starting from
841    BUFFER.  If COPY is zero, copying is delayed until necessary, and
842    the data is taken from the original location when needed.  */
843 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
844                                     const char *buffer, size_t size,
845                                     int copy);
846
847 /* Destroy the data buffer DH and return a pointer to its content.
848    The memory has be to released with free by the user.  It's size is
849    returned in R_LEN.  */
850 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
851
852 GpgmeError gpgme_data_new_from_cbs (GpgmeData *dh,
853                                     struct GpgmeDataCbs *cbs,
854                                     void *handle);
855
856 GpgmeError gpgme_data_new_from_fd (GpgmeData *dh, int fd);
857
858 GpgmeError gpgme_data_new_from_stream (GpgmeData *dh, FILE *stream);
859
860 /* Return the encoding attribute of the data buffer DH */
861 GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh);
862
863 /* Set the encoding attribute of data buffer DH to ENC */
864 GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc);
865
866
867
868 /* Create a new data buffer which retrieves the data from the callback
869    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
870    instead.  */
871 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
872                                         int (*read_cb) (void*,char *,size_t,size_t*),
873                                         void *read_cb_value);
874
875 /* Create a new data buffer filled with the content of file FNAME.
876    COPY must be non-zero.  For delayed read, please use
877    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
878 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
879                                      const char *fname,
880                                      int copy);
881
882 /* Create a new data buffer filled with LENGTH bytes starting from
883    OFFSET within the file FNAME or stream FP (exactly one must be
884    non-zero).  */
885 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
886                                          const char *fname, FILE *fp,
887                                          off_t offset, size_t length);
888
889 /* Reset the read pointer in DH.  Deprecated, please use
890    gpgme_data_seek instead.  */
891 GpgmeError gpgme_data_rewind (GpgmeData dh);
892
893 \f
894 /* Key and trust functions.  */
895
896 /* Get the key with the fingerprint FPR from the crypto backend.  If
897    SECRET is true, get the secret key.  */
898 GpgmeError gpgme_get_key (GpgmeCtx ctx, const char *fpr, GpgmeKey *r_key,
899                           int secret);
900
901 /* Acquire a reference to KEY.  */
902 void gpgme_key_ref (GpgmeKey key);
903
904 /* Release a reference to KEY.  If this was the last one the key is
905    destroyed.  */
906 void gpgme_key_unref (GpgmeKey key);
907 void gpgme_key_release (GpgmeKey key);
908
909 /* Return the value of the attribute WHAT of KEY, which has to be
910    representable by a string.  IDX specifies the sub key or
911    user ID for attributes related to sub keys or user IDs.  */
912 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
913                                        const void *reserved, int idx);
914
915 /* Return the value of the attribute WHAT of KEY, which has to be
916    representable by an unsigned integer.  IDX specifies the sub key or
917    user ID for attributes related to sub keys or user IDs.  */
918 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
919                                         const void *reserved, int idx);
920
921 /* Return the value of the attribute WHAT of a signature on user ID
922    UID_IDX in KEY, which has to be representable by a string.  IDX
923    specifies the signature.  */
924 const char *gpgme_key_sig_get_string_attr (GpgmeKey key, int uid_idx,
925                                            GpgmeAttr what,
926                                            const void *reserved, int idx);
927
928 /* Return the value of the attribute WHAT of a signature on user ID
929    UID_IDX in KEY, which has to be representable by an unsigned
930    integer string.  IDX specifies the signature.  */
931 unsigned long gpgme_key_sig_get_ulong_attr (GpgmeKey key, int uid_idx,
932                                             GpgmeAttr what,
933                                             const void *reserved, int idx);
934
935 \f
936 /* Crypto Operations.  */
937
938 struct _gpgme_invalid_user_id
939 {
940   struct _gpgme_invalid_user_id *next;
941   char *id;
942   GpgmeError reason;
943 };
944 typedef struct _gpgme_invalid_user_id *GpgmeInvalidUserID;
945
946 \f
947 /* Encryption.  */
948 struct _gpgme_op_encrypt_result
949 {
950   /* The list of invalid recipients.  */
951   GpgmeInvalidUserID invalid_recipients;
952 };
953 typedef struct _gpgme_op_encrypt_result *GpgmeEncryptResult;
954
955 /* Retrieve a pointer to the result of the encrypt operation.  */
956 GpgmeEncryptResult gpgme_op_encrypt_result (GpgmeCtx ctx);
957
958 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
959    store the resulting ciphertext in CIPHER.  */
960 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
961                                    GpgmeRecipients recp,
962                                    GpgmeData plain, GpgmeData cipher);
963 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
964                              GpgmeRecipients recp,
965                              GpgmeData plain, GpgmeData cipher);
966
967 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
968    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
969    with the signers in CTX.  */
970 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
971                                         GpgmeRecipients recp,
972                                         GpgmeData plain, GpgmeData cipher);
973 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
974                                   GpgmeRecipients recp,
975                                   GpgmeData plain, GpgmeData cipher);
976
977 \f
978 /* Decryption.  */
979 struct _gpgme_op_decrypt_result
980 {
981   char *unsupported_algorithm;
982 };
983 typedef struct _gpgme_op_decrypt_result *GpgmeDecryptResult;
984
985 /* Retrieve a pointer to the result of the decrypt operation.  */
986 GpgmeDecryptResult gpgme_op_decrypt_result (GpgmeCtx ctx);
987
988 /* Decrypt ciphertext CIPHER within CTX and store the resulting
989    plaintext in PLAIN.  */
990 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
991                                    GpgmeData cipher, GpgmeData plain);
992 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
993                              GpgmeData cipher, GpgmeData plain);
994
995 /* Decrypt ciphertext CIPHER and make a signature verification within
996    CTX and store the resulting plaintext in PLAIN.  */
997 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
998                                           GpgmeData cipher, GpgmeData plain);
999 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
1000                                     GpgmeData cipher, GpgmeData plain);
1001
1002 \f
1003 /* Signing.  */
1004 struct _gpgme_new_signature
1005 {
1006   struct _gpgme_new_signature *next;
1007   GpgmeSigMode type;
1008   GpgmePubKeyAlgo pubkey_algo;
1009   GpgmeHashAlgo hash_algo;
1010   unsigned long class;
1011   long int timestamp;
1012   char *fpr;
1013 };
1014 typedef struct _gpgme_new_signature *GpgmeNewSignature;
1015
1016 struct _gpgme_op_sign_result
1017 {
1018   /* The list of invalid signers.  */
1019   GpgmeInvalidUserID invalid_signers;
1020   GpgmeNewSignature signatures;
1021 };
1022 typedef struct _gpgme_op_sign_result *GpgmeSignResult;
1023
1024 /* Retrieve a pointer to the result of the signing operation.  */
1025 GpgmeSignResult gpgme_op_sign_result (GpgmeCtx ctx);
1026
1027 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1028 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
1029                                 GpgmeData plain, GpgmeData sig,
1030                                 GpgmeSigMode mode);
1031 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
1032                           GpgmeData plain, GpgmeData sig,
1033                           GpgmeSigMode mode);
1034
1035 \f
1036 /* Verify.  */
1037 struct _gpgme_sig_notation
1038 {
1039   struct _gpgme_sig_notation *next;
1040
1041   /* If NAME is a null pointer, then VALUE contains a policy URL
1042      rather than a notation.  */
1043   char *name;
1044   char *value;
1045 };
1046 typedef struct _gpgme_sig_notation *GpgmeSigNotation;
1047
1048 /* Flags used for the SUMMARY field in a GpgmeSignature.  */
1049 enum 
1050   {
1051     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1052     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1053     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1054     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1055     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1056     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1057     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1058     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1059     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1060     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1061     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1062   };
1063
1064 struct _gpgme_signature
1065 {
1066   struct _gpgme_signature *next;
1067
1068   /* A summary of the signature status.  */
1069   unsigned int summary;
1070
1071   /* The fingerprint or key ID of the signature.  */
1072   char *fpr;
1073
1074   /* The status of the signature.  */
1075   GpgmeError status;
1076
1077   /* Notation data and policy URLs.  */
1078   GpgmeSigNotation notations;
1079
1080   /* Signature creation time.  */
1081   unsigned long timestamp;
1082
1083   /* Signature exipration time or 0.  */
1084   unsigned long exp_timestamp;
1085
1086   int wrong_key_usage : 1;
1087
1088   /* Internal to GPGME, do not use.  */
1089   int _unused : 31;
1090
1091   GpgmeValidity validity;
1092   GpgmeError validity_reason;
1093 };
1094 typedef struct _gpgme_signature *GpgmeSignature;
1095
1096 struct _gpgme_op_verify_result
1097 {
1098   GpgmeSignature signatures;
1099 };
1100 typedef struct _gpgme_op_verify_result *GpgmeVerifyResult;
1101
1102 /* Retrieve a pointer to the result of the verify operation.  */
1103 GpgmeVerifyResult gpgme_op_verify_result (GpgmeCtx ctx);
1104
1105 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1106 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig,
1107                                   GpgmeData signed_text, GpgmeData plaintext);
1108 GpgmeError gpgme_op_verify (GpgmeCtx ctx, GpgmeData sig,
1109                             GpgmeData signed_text, GpgmeData plaintext);
1110
1111 \f
1112 /* Import.  */
1113 enum
1114   {
1115     /* The key was new.  */
1116     GPGME_IMPORT_NEW = 1,
1117
1118     /* The key contained new user IDs.  */
1119     GPGME_IMPORT_UID = 2,
1120
1121     /* The key contained new signatures.  */
1122     GPGME_IMPORT_SIG = 4,
1123
1124     /* The key contained new sub keys.  */
1125     GPGME_IMPORT_SUBKEY = 8,
1126
1127     /* The key contained a secret key.  */
1128     GPGME_IMPORT_SECRET = 16
1129   };
1130
1131 struct _gpgme_import_status
1132 {
1133   struct _gpgme_import_status *next;
1134
1135   /* Fingerprint.  */
1136   char *fpr;
1137
1138   /* If a problem occured, the reason why the key could not be
1139      imported.  Otherwise GPGME_No_Error.  */
1140   GpgmeError result;
1141
1142   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1143      ORed.  0 means the key was already known and no new components
1144      have been added.  */
1145   unsigned int status;
1146 };
1147 typedef struct _gpgme_import_status *GpgmeImportStatus;
1148
1149 /* Import.  */
1150 struct _gpgme_op_import_result
1151 {
1152   /* Number of considered keys.  */
1153   int considered;
1154
1155   /* Keys without user ID.  */
1156   int no_user_id;
1157
1158   /* Imported keys.  */
1159   int imported;
1160
1161   /* Imported RSA keys.  */
1162   int imported_rsa;
1163
1164   /* Unchanged keys.  */
1165   int unchanged;
1166
1167   /* Number of new user ids.  */
1168   int new_user_ids;
1169
1170   /* Number of new sub keys.  */
1171   int new_sub_keys;
1172
1173   /* Number of new signatures.  */
1174   int new_signatures;
1175
1176   /* Number of new revocations.  */
1177   int new_revocations;
1178
1179   /* Number of secret keys read.  */
1180   int secret_read;
1181
1182   /* Number of secret keys imported.  */
1183   int secret_imported;
1184
1185   /* Number of secret keys unchanged.  */
1186   int secret_unchanged;
1187
1188   /* Number of keys not imported.  */
1189   int not_imported;
1190
1191   /* List of keys for which an import was attempted.  */
1192   GpgmeImportStatus imports;
1193 };
1194 typedef struct _gpgme_op_import_result *GpgmeImportResult;
1195
1196 /* Retrieve a pointer to the result of the import operation.  */
1197 GpgmeImportResult gpgme_op_import_result (GpgmeCtx ctx);
1198
1199 /* Import the key in KEYDATA into the keyring.  */
1200 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
1201 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
1202 GpgmeError gpgme_op_import_ext (GpgmeCtx ctx, GpgmeData keydata, int *nr);
1203
1204 \f
1205 /* Export the keys listed in RECP into KEYDATA.  */
1206 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
1207                                   GpgmeData keydata);
1208 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
1209                             GpgmeData keydata);
1210
1211 \f
1212 /* Key generation.  */
1213 struct _gpgme_op_genkey_result
1214 {
1215   /* A primary key was generated.  */
1216   unsigned int primary : 1;
1217
1218   /* A sub key was generated.  */
1219   unsigned int sub : 1;
1220
1221   /* Internal to GPGME, do not use.  */
1222   unsigned int _unused : 30;
1223
1224   /* The fingerprint of the generated key.  */
1225   char *fpr;
1226 };
1227 typedef struct _gpgme_op_genkey_result *GpgmeGenKeyResult;
1228
1229 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1230    SECKEY should be null for now.  PARMS specifies what keys should be
1231    generated.  */
1232 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
1233                                   GpgmeData pubkey, GpgmeData seckey);
1234 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
1235                             GpgmeData pubkey, GpgmeData seckey);
1236
1237 /* Retrieve a pointer to the result of the genkey operation.  */
1238 GpgmeGenKeyResult gpgme_op_genkey_result (GpgmeCtx ctx);
1239
1240 \f
1241 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1242    keys are also deleted.  */
1243 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
1244                                   int allow_secret);
1245 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
1246                             int allow_secret);
1247
1248 /* Edit the key KEY.  Send status and command requests to FNC and
1249    output of edit commands to OUT.  */
1250 GpgmeError gpgme_op_edit_start (GpgmeCtx ctx, GpgmeKey key,
1251                           GpgmeEditCb fnc, void *fnc_value,
1252                           GpgmeData out);
1253 GpgmeError gpgme_op_edit (GpgmeCtx ctx, GpgmeKey key,
1254                           GpgmeEditCb fnc, void *fnc_value,
1255                           GpgmeData out);
1256
1257 \f
1258 /* Key management functions */
1259 struct _gpgme_op_keylist_result
1260 {
1261   unsigned int truncated : 1;
1262
1263   /* Internal to GPGME, do not use.  */
1264   unsigned int _unused : 31;
1265 };
1266 typedef struct _gpgme_op_keylist_result *GpgmeKeyListResult;
1267
1268 /* Retrieve a pointer to the result of the key listing operation.  */
1269 GpgmeKeyListResult gpgme_op_keylist_result (GpgmeCtx ctx);
1270
1271 /* Start a keylist operation within CTX, searching for keys which
1272    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1273    returned.  */
1274 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
1275                                    const char *pattern, int secret_only);
1276 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
1277                                        int secret_only, int reserved);
1278
1279 /* Return the next key from the keylist in R_KEY.  */
1280 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
1281
1282 /* Terminate a pending keylist operation within CTX.  */
1283 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
1284
1285 \f
1286 /* Trust items and operations.  */
1287
1288 struct _gpgme_trust_item
1289 {
1290   /* Internal to GPGME, do not use.  */
1291   unsigned int _refs;
1292
1293   /* The key ID to which the trust item belongs.  */
1294   char *keyid;
1295
1296   /* Internal to GPGME, do not use.  */
1297   char _keyid[16 + 1];
1298
1299   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1300   int type;
1301
1302   /* The trust level.  */
1303   int level;
1304
1305   /* The owner trust if TYPE is 1.  */
1306   char *owner_trust;
1307
1308   /* Internal to GPGME, do not use.  */
1309   char _owner_trust[2];
1310
1311   /* The calculated validity.  */
1312   char *validity;
1313  
1314   /* Internal to GPGME, do not use.  */
1315   char _validity[2];
1316
1317   /* The user name if TYPE is 2.  */
1318   char *name;
1319 };
1320 typedef struct _gpgme_trust_item *GpgmeTrustItem;
1321
1322 /* Start a trustlist operation within CTX, searching for trust items
1323    which match PATTERN.  */
1324 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
1325                                      const char *pattern, int max_level);
1326
1327 /* Return the next trust item from the trustlist in R_ITEM.  */
1328 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
1329
1330 /* Terminate a pending trustlist operation within CTX.  */
1331 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
1332
1333 /* Acquire a reference to ITEM.  */
1334 void gpgme_trust_item_ref (GpgmeTrustItem item);
1335
1336 /* Release a reference to ITEM.  If this was the last one the trust
1337    item is destroyed.  */
1338 void gpgme_trust_item_unref (GpgmeTrustItem item);
1339
1340 /* Release the trust item ITEM.  */
1341 void gpgme_trust_item_release (GpgmeTrustItem item);
1342
1343 /* Return the value of the attribute WHAT of ITEM, which has to be
1344    representable by a string.  */
1345 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
1346                                               GpgmeAttr what,
1347                                               const void *reserved, int idx);
1348
1349 /* Return the value of the attribute WHAT of KEY, which has to be
1350    representable by an integer.  IDX specifies a running index if the
1351    attribute appears more than once in the key.  */
1352 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
1353                                    const void *reserved, int idx);
1354
1355 \f
1356 /* Various functions.  */
1357
1358 /* Check that the library fulfills the version requirement.  */
1359 const char *gpgme_check_version (const char *req_version);
1360
1361 /* Retrieve information about the backend engines.  */
1362 GpgmeError gpgme_get_engine_info (GpgmeEngineInfo *engine_info);
1363
1364 /* Return a string describing ERR.  */
1365 const char *gpgme_strerror (GpgmeError err);
1366
1367 \f
1368 /* Engine support functions.  */
1369
1370 /* Verify that the engine implementing PROTO is installed and
1371    available.  */
1372 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
1373
1374
1375 #ifdef __cplusplus
1376 }
1377 #endif
1378 #endif /* GPGME_H */