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