2005-09-29 Marcus Brinkmann <marcus@g10code.de>
[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_PLAINTEXT
409   }
410 gpgme_status_code_t;
411
412 \f
413 /* The engine information structure.  */
414 struct _gpgme_engine_info
415 {
416   struct _gpgme_engine_info *next;
417
418   /* The protocol ID.  */
419   gpgme_protocol_t protocol;
420
421   /* The file name of the engine binary.  */
422   char *file_name;
423   
424   /* The version string of the installed engine.  */
425   char *version;
426
427   /* The minimum version required for GPGME.  */
428   const char *req_version;
429
430   /* The home directory used, or NULL if default.  */
431   char *home_dir;
432 };
433 typedef struct _gpgme_engine_info *gpgme_engine_info_t;
434
435 \f
436 /* A subkey from a key.  */
437 struct _gpgme_subkey
438 {
439   struct _gpgme_subkey *next;
440
441   /* True if subkey is revoked.  */
442   unsigned int revoked : 1;
443
444   /* True if subkey is expired.  */
445   unsigned int expired : 1;
446
447   /* True if subkey is disabled.  */
448   unsigned int disabled : 1;
449
450   /* True if subkey is invalid.  */
451   unsigned int invalid : 1;
452
453   /* True if subkey can be used for encryption.  */
454   unsigned int can_encrypt : 1;
455
456   /* True if subkey can be used for signing.  */
457   unsigned int can_sign : 1;
458
459   /* True if subkey can be used for certification.  */
460   unsigned int can_certify : 1;
461
462   /* True if subkey is secret.  */
463   unsigned int secret : 1;
464
465   /* True if subkey can be used for authentication.  */
466   unsigned int can_authenticate : 1;
467
468   /* True if subkey is qualified for signatures according to German law.  */
469   unsigned int is_qualified : 1;
470
471   /* Internal to GPGME, do not use.  */
472   unsigned int _unused : 22;
473   
474   /* Public key algorithm supported by this subkey.  */
475   gpgme_pubkey_algo_t pubkey_algo;
476
477   /* Length of the subkey.  */
478   unsigned int length;
479
480   /* The key ID of the subkey.  */
481   char *keyid;
482
483   /* Internal to GPGME, do not use.  */
484   char _keyid[16 + 1];
485
486   /* The fingerprint of the subkey in hex digit form.  */
487   char *fpr;
488
489   /* The creation timestamp, -1 if invalid, 0 if not available.  */
490   long int timestamp;
491
492   /* The expiration timestamp, 0 if the subkey does not expire.  */
493   long int expires;
494 };
495 typedef struct _gpgme_subkey *gpgme_subkey_t;
496
497
498 /* A signature on a user ID.  */
499 struct _gpgme_key_sig
500 {
501   struct _gpgme_key_sig *next;
502
503   /* True if the signature is a revocation signature.  */
504   unsigned int revoked : 1;
505
506   /* True if the signature is expired.  */
507   unsigned int expired : 1;
508
509   /* True if the signature is invalid.  */
510   unsigned int invalid : 1;
511
512   /* True if the signature should be exported.  */
513   unsigned int exportable : 1;
514
515   /* Internal to GPGME, do not use.  */
516   unsigned int _unused : 28;
517
518   /* The public key algorithm used to create the signature.  */
519   gpgme_pubkey_algo_t pubkey_algo;
520
521   /* The key ID of key used to create the signature.  */
522   char *keyid;
523
524   /* Internal to GPGME, do not use.  */
525   char _keyid[16 + 1];
526
527   /* The creation timestamp, -1 if invalid, 0 if not available.  */
528   long int timestamp;
529
530   /* The expiration timestamp, 0 if the subkey does not expire.  */
531   long int expires;
532
533   /* Same as in gpgme_signature_t.  */
534   gpgme_error_t status;
535
536 #ifdef __cplusplus
537   unsigned int _obsolete_class _GPGME_DEPRECATED;
538 #else
539   /* Must be set to SIG_CLASS below.  */
540   unsigned int class _GPGME_DEPRECATED;
541 #endif
542
543   /* The user ID string.  */
544   char *uid;
545
546   /* The name part of the user ID.  */
547   char *name;
548
549   /* The email part of the user ID.  */
550   char *email;
551
552   /* The comment part of the user ID.  */
553   char *comment;
554
555   /* Crypto backend specific signature class.  */
556   unsigned int sig_class;
557 };
558 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
559
560
561 /* An user ID from a key.  */
562 struct _gpgme_user_id
563 {
564   struct _gpgme_user_id *next;
565
566   /* True if the user ID is revoked.  */
567   unsigned int revoked : 1;
568
569   /* True if the user ID is invalid.  */
570   unsigned int invalid : 1;
571
572   /* Internal to GPGME, do not use.  */
573   unsigned int _unused : 30;
574
575   /* The validity of the user ID.  */
576   gpgme_validity_t validity; 
577
578   /* The user ID string.  */
579   char *uid;
580
581   /* The name part of the user ID.  */
582   char *name;
583
584   /* The email part of the user ID.  */
585   char *email;
586
587   /* The comment part of the user ID.  */
588   char *comment;
589
590   /* The signatures of the user ID.  */
591   gpgme_key_sig_t signatures;
592
593   /* Internal to GPGME, do not use.  */
594   gpgme_key_sig_t _last_keysig;
595 };
596 typedef struct _gpgme_user_id *gpgme_user_id_t;
597
598
599 /* A key from the keyring.  */
600 struct _gpgme_key
601 {
602   /* Internal to GPGME, do not use.  */
603   unsigned int _refs;
604
605   /* True if key is revoked.  */
606   unsigned int revoked : 1;
607
608   /* True if key is expired.  */
609   unsigned int expired : 1;
610
611   /* True if key is disabled.  */
612   unsigned int disabled : 1;
613
614   /* True if key is invalid.  */
615   unsigned int invalid : 1;
616
617   /* True if key can be used for encryption.  */
618   unsigned int can_encrypt : 1;
619
620   /* True if key can be used for signing.  */
621   unsigned int can_sign : 1;
622
623   /* True if key can be used for certification.  */
624   unsigned int can_certify : 1;
625
626   /* True if key is secret.  */
627   unsigned int secret : 1;
628
629   /* True if key can be used for authentication.  */
630   unsigned int can_authenticate : 1;
631
632   /* True if subkey is qualified for signatures according to German law.  */
633   unsigned int is_qualified : 1;
634
635   /* Internal to GPGME, do not use.  */
636   unsigned int _unused : 22;
637
638   /* This is the protocol supported by this key.  */
639   gpgme_protocol_t protocol;
640
641   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
642      issuer serial.  */
643   char *issuer_serial;
644
645   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
646      issuer name.  */
647   char *issuer_name;
648
649   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
650      ID.  */
651   char *chain_id;
652
653   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
654      owner trust.  */
655   gpgme_validity_t owner_trust;
656
657   /* The subkeys of the key.  */
658   gpgme_subkey_t subkeys;
659
660   /* The user IDs of the key.  */
661   gpgme_user_id_t uids;
662
663   /* Internal to GPGME, do not use.  */
664   gpgme_subkey_t _last_subkey;
665
666   /* Internal to GPGME, do not use.  */
667   gpgme_user_id_t _last_uid;
668
669   /* The keylist mode that was active when listing the key.  */
670   gpgme_keylist_mode_t keylist_mode;
671 };
672 typedef struct _gpgme_key *gpgme_key_t;
673
674
675 \f
676 /* Types for callback functions.  */
677
678 /* Request a passphrase from the user.  */
679 typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
680                                                 const char *uid_hint,
681                                                 const char *passphrase_info,
682                                                 int prev_was_bad, int fd);
683
684 /* Inform the user about progress made.  */
685 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
686                                      int type, int current, int total);
687
688 /* Interact with the user about an edit operation.  */
689 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
690                                           gpgme_status_code_t status,
691                                           const char *args, int fd);
692
693 \f
694 /* Context management functions.  */
695
696 /* Create a new context and return it in CTX.  */
697 gpgme_error_t gpgme_new (gpgme_ctx_t *ctx);
698
699 /* Release the context CTX.  */
700 void gpgme_release (gpgme_ctx_t ctx);
701
702 /* Set the protocol to be used by CTX to PROTO.  */
703 gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
704
705 /* Get the protocol used with CTX */
706 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
707
708 /* Get the string describing protocol PROTO, or NULL if invalid.  */
709 const char *gpgme_get_protocol_name (gpgme_protocol_t proto);
710
711 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
712 void gpgme_set_armor (gpgme_ctx_t ctx, int yes);
713
714 /* Return non-zero if armor mode is set in CTX.  */
715 int gpgme_get_armor (gpgme_ctx_t ctx);
716
717 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
718 void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
719
720 /* Return non-zero if text mode is set in CTX.  */
721 int gpgme_get_textmode (gpgme_ctx_t ctx);
722
723 /* Use whatever the default of the backend crypto engine is.  */
724 #define GPGME_INCLUDE_CERTS_DEFAULT     -256
725
726 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
727 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
728
729 /* Return the number of certs to include in an S/MIME message.  */
730 int gpgme_get_include_certs (gpgme_ctx_t ctx);
731
732 /* Set keylist mode in CTX to MODE.  */
733 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
734                                       gpgme_keylist_mode_t mode);
735
736 /* Get keylist mode in CTX.  */
737 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
738
739 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
740    passed as first argument to the passphrase callback function.  */
741 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
742                               gpgme_passphrase_cb_t cb, void *hook_value);
743
744 /* Get the current passphrase callback function in *CB and the current
745    hook value in *HOOK_VALUE.  */
746 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
747                               void **hook_value);
748
749 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
750    passed as first argument to the progress callback function.  */
751 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
752                             void *hook_value);
753
754 /* Get the current progress callback function in *CB and the current
755    hook value in *HOOK_VALUE.  */
756 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
757                             void **hook_value);
758
759 /* This function sets the locale for the context CTX, or the default
760    locale if CTX is a null pointer.  */
761 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
762                                 const char *value);
763
764 /* Get the information about the configured engines.  A pointer to the
765    first engine in the statically allocated linked list is returned.
766    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
767 gpgme_engine_info_t gpgme_ctx_get_engine_info (gpgme_ctx_t ctx);
768
769 /* Set the engine info for the context CTX, protocol PROTO, to the
770    file name FILE_NAME and the home directory HOME_DIR.  */
771 gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t ctx,
772                                          gpgme_protocol_t proto,
773                                          const char *file_name,
774                                          const char *home_dir);
775
776 \f
777 /* Return a statically allocated string with the name of the public
778    key algorithm ALGO, or NULL if that name is not known.  */
779 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
780
781 /* Return a statically allocated string with the name of the hash
782    algorithm ALGO, or NULL if that name is not known.  */
783 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
784
785 \f
786 /* Delete all signers from CTX.  */
787 void gpgme_signers_clear (gpgme_ctx_t ctx);
788
789 /* Add KEY to list of signers in CTX.  */
790 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
791
792 /* Return the SEQth signer's key in CTX.  */
793 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
794
795 /* Retrieve the signature status of signature IDX in CTX after a
796    successful verify operation in R_STAT (if non-null).  The creation
797    time stamp of the signature is returned in R_CREATED (if non-null).
798    The function returns a string containing the fingerprint.
799    Deprecated, use verify result directly.  */
800 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
801                                   _gpgme_sig_stat_t *r_stat,
802                                   time_t *r_created) _GPGME_DEPRECATED;
803
804 /* Retrieve certain attributes of a signature.  IDX is the index
805    number of the signature after a successful verify operation.  WHAT
806    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
807    one.  WHATIDX is to be passed as 0 for most attributes . */
808 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
809                                         _gpgme_attr_t what, int whatidx)
810      _GPGME_DEPRECATED;
811 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
812                                        _gpgme_attr_t what, int whatidx)
813      _GPGME_DEPRECATED;
814
815
816 /* Get the key used to create signature IDX in CTX and return it in
817    R_KEY.  */
818 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
819      _GPGME_DEPRECATED;
820
821 \f
822 /* Run control.  */
823
824 /* The type of an I/O callback function.  */
825 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
826
827 /* The type of a function that can register FNC as the I/O callback
828    function for the file descriptor FD with direction dir (0: for writing,
829    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
830    function should return a TAG suitable for the corresponding
831    gpgme_remove_io_cb_t, and an error value.  */
832 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
833                                                  gpgme_io_cb_t fnc,
834                                                  void *fnc_data, void **tag);
835
836 /* The type of a function that can remove a previously registered I/O
837    callback function given TAG as returned by the register
838    function.  */
839 typedef void (*gpgme_remove_io_cb_t) (void *tag);
840
841 typedef enum
842   {
843     GPGME_EVENT_START,
844     GPGME_EVENT_DONE,
845     GPGME_EVENT_NEXT_KEY,
846     GPGME_EVENT_NEXT_TRUSTITEM
847   }
848 gpgme_event_io_t;
849
850 /* The type of a function that is called when a context finished an
851    operation.  */
852 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
853                                      void *type_data);
854
855 struct gpgme_io_cbs
856 {
857   gpgme_register_io_cb_t add;
858   void *add_priv;
859   gpgme_remove_io_cb_t remove;
860   gpgme_event_io_cb_t event;
861   void *event_priv;
862 };
863 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
864
865 /* Set the I/O callback functions in CTX to IO_CBS.  */
866 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
867
868 /* Get the current I/O callback functions.  */
869 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
870
871 /* Process the pending operation and, if HANG is non-zero, wait for
872    the pending operation to finish.  */
873 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
874
875 \f
876 /* Functions to handle data objects.  */
877
878 /* Read up to SIZE bytes into buffer BUFFER from the data object with
879    the handle HANDLE.  Return the number of characters read, 0 on EOF
880    and -1 on error.  If an error occurs, errno is set.  */
881 typedef ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer,
882                                          size_t size);
883
884 /* Write up to SIZE bytes from buffer BUFFER to the data object with
885    the handle HANDLE.  Return the number of characters written, or -1
886    on error.  If an error occurs, errno is set.  */
887 typedef ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
888                                           size_t size);
889
890 /* Set the current position from where the next read or write starts
891    in the data object with the handle HANDLE to OFFSET, relativ to
892    WHENCE.  */
893 typedef off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence);
894
895 /* Close the data object with the handle DL.  */
896 typedef void (*gpgme_data_release_cb_t) (void *handle);
897
898 struct gpgme_data_cbs
899 {
900   gpgme_data_read_cb_t read;
901   gpgme_data_write_cb_t write;
902   gpgme_data_seek_cb_t seek;
903   gpgme_data_release_cb_t release;
904 };
905 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
906
907 /* Read up to SIZE bytes into buffer BUFFER from the data object with
908    the handle DH.  Return the number of characters read, 0 on EOF and
909    -1 on error.  If an error occurs, errno is set.  */
910 ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
911
912 /* Write up to SIZE bytes from buffer BUFFER to the data object with
913    the handle DH.  Return the number of characters written, or -1 on
914    error.  If an error occurs, errno is set.  */
915 ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
916
917 /* Set the current position from where the next read or write starts
918    in the data object with the handle DH to OFFSET, relativ to
919    WHENCE.  */
920 off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
921
922 /* Create a new data buffer and return it in R_DH.  */
923 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
924
925 /* Destroy the data buffer DH.  */
926 void gpgme_data_release (gpgme_data_t dh);
927
928 /* Create a new data buffer filled with SIZE bytes starting from
929    BUFFER.  If COPY is zero, copying is delayed until necessary, and
930    the data is taken from the original location when needed.  */
931 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
932                                        const char *buffer, size_t size,
933                                        int copy);
934
935 /* Destroy the data buffer DH and return a pointer to its content.
936    The memory has be to released with free by the user.  It's size is
937    returned in R_LEN.  */
938 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
939
940 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
941                                        gpgme_data_cbs_t cbs,
942                                        void *handle);
943
944 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
945
946 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
947
948 /* Return the encoding attribute of the data buffer DH */
949 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
950
951 /* Set the encoding attribute of data buffer DH to ENC */
952 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
953                                        gpgme_data_encoding_t enc);
954
955
956
957 /* Create a new data buffer which retrieves the data from the callback
958    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
959    instead.  */
960 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
961                                            int (*read_cb) (void*,char *,
962                                                            size_t,size_t*),
963                                            void *read_cb_value)
964      _GPGME_DEPRECATED;
965
966 /* Create a new data buffer filled with the content of file FNAME.
967    COPY must be non-zero.  For delayed read, please use
968    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
969 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
970                                         const char *fname,
971                                         int copy);
972
973 /* Create a new data buffer filled with LENGTH bytes starting from
974    OFFSET within the file FNAME or stream FP (exactly one must be
975    non-zero).  */
976 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
977                                             const char *fname, FILE *fp,
978                                             off_t offset, size_t length);
979
980 /* Reset the read pointer in DH.  Deprecated, please use
981    gpgme_data_seek instead.  */
982 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh) _GPGME_DEPRECATED;
983
984 \f
985 /* Key and trust functions.  */
986
987 /* Get the key with the fingerprint FPR from the crypto backend.  If
988    SECRET is true, get the secret key.  */
989 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
990                              gpgme_key_t *r_key, int secret);
991
992 /* Acquire a reference to KEY.  */
993 void gpgme_key_ref (gpgme_key_t key);
994
995 /* Release a reference to KEY.  If this was the last one the key is
996    destroyed.  */
997 void gpgme_key_unref (gpgme_key_t key);
998 void gpgme_key_release (gpgme_key_t key);
999
1000 /* Return the value of the attribute WHAT of KEY, which has to be
1001    representable by a string.  IDX specifies the sub key or user ID
1002    for attributes related to sub keys or user IDs.  Deprecated, use
1003    key structure directly instead. */
1004 const char *gpgme_key_get_string_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 KEY, which has to be
1009    representable by an unsigned integer.  IDX specifies the sub key or
1010    user ID for attributes related to sub keys or user IDs.
1011    Deprecated, use key structure directly instead.  */
1012 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
1013                                         const void *reserved, int idx)
1014      _GPGME_DEPRECATED;
1015
1016 /* Return the value of the attribute WHAT of a signature on user ID
1017    UID_IDX in KEY, which has to be representable by a string.  IDX
1018    specifies the signature.  Deprecated, use key structure directly
1019    instead.  */
1020 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
1021                                            _gpgme_attr_t what,
1022                                            const void *reserved, int idx)
1023      _GPGME_DEPRECATED;
1024
1025 /* Return the value of the attribute WHAT of a signature on user ID
1026    UID_IDX in KEY, which has to be representable by an unsigned
1027    integer string.  IDX specifies the signature.  Deprecated, use key
1028    structure directly instead.  */
1029 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
1030                                             _gpgme_attr_t what,
1031                                             const void *reserved, int idx)
1032      _GPGME_DEPRECATED;
1033
1034 \f
1035 /* Crypto Operations.  */
1036
1037 /* Cancel a pending asynchronous operation.  */
1038 gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
1039
1040 \f
1041 struct _gpgme_invalid_key
1042 {
1043   struct _gpgme_invalid_key *next;
1044   char *fpr;
1045   gpgme_error_t reason;
1046 };
1047 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
1048
1049 \f
1050 /* Encryption.  */
1051 struct _gpgme_op_encrypt_result
1052 {
1053   /* The list of invalid recipients.  */
1054   gpgme_invalid_key_t invalid_recipients;
1055 };
1056 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
1057
1058 /* Retrieve a pointer to the result of the encrypt operation.  */
1059 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
1060
1061 /* The valid encryption flags.  */
1062 typedef enum
1063   {
1064     GPGME_ENCRYPT_ALWAYS_TRUST = 1
1065   }
1066 gpgme_encrypt_flags_t;
1067
1068 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1069    store the resulting ciphertext in CIPHER.  */
1070 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
1071                                       gpgme_encrypt_flags_t flags,
1072                                       gpgme_data_t plain, gpgme_data_t cipher);
1073 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1074                                 gpgme_encrypt_flags_t flags,
1075                                 gpgme_data_t plain, gpgme_data_t cipher);
1076
1077 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1078    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1079    with the signers in CTX.  */
1080 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1081                                            gpgme_key_t recp[],
1082                                            gpgme_encrypt_flags_t flags,
1083                                            gpgme_data_t plain,
1084                                            gpgme_data_t cipher);
1085 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1086                                      gpgme_encrypt_flags_t flags,
1087                                      gpgme_data_t plain, gpgme_data_t cipher);
1088
1089 \f
1090 /* Decryption.  */
1091
1092 struct _gpgme_recipient
1093 {
1094   struct _gpgme_recipient *next;
1095
1096   /* The key ID of key for which the text was encrypted.  */
1097   char *keyid;
1098
1099   /* Internal to GPGME, do not use.  */
1100   char _keyid[16 + 1];
1101
1102   /* The public key algorithm of the recipient key.  */
1103   gpgme_pubkey_algo_t pubkey_algo;
1104
1105   /* The status of the recipient.  */
1106   gpgme_error_t status;
1107 };
1108 typedef struct _gpgme_recipient *gpgme_recipient_t;
1109
1110 struct _gpgme_op_decrypt_result
1111 {
1112   char *unsupported_algorithm;
1113
1114   /* Key should not have been used for encryption.  */
1115   unsigned int wrong_key_usage : 1;
1116
1117   /* Internal to GPGME, do not use.  */
1118   int _unused : 31;
1119
1120   gpgme_recipient_t recipients;
1121
1122   /* The original filename of the plaintext message, if available.  */
1123   char *plaintext_filename;
1124 };
1125 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1126
1127 /* Retrieve a pointer to the result of the decrypt operation.  */
1128 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1129
1130 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1131    plaintext in PLAIN.  */
1132 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1133                                       gpgme_data_t plain);
1134 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1135                                 gpgme_data_t cipher, gpgme_data_t plain);
1136
1137 /* Decrypt ciphertext CIPHER and make a signature verification within
1138    CTX and store the resulting plaintext in PLAIN.  */
1139 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1140                                              gpgme_data_t cipher,
1141                                              gpgme_data_t plain);
1142 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1143                                        gpgme_data_t plain);
1144
1145 \f
1146 /* Signing.  */
1147 struct _gpgme_new_signature
1148 {
1149   struct _gpgme_new_signature *next;
1150
1151   /* The type of the signature.  */
1152   gpgme_sig_mode_t type;
1153
1154   /* The public key algorithm used to create the signature.  */
1155   gpgme_pubkey_algo_t pubkey_algo;
1156
1157   /* The hash algorithm used to create the signature.  */
1158   gpgme_hash_algo_t hash_algo;
1159
1160   /* Internal to GPGME, do not use.  Must be set to the same value as
1161      CLASS below.  */
1162   unsigned long _obsolete_class;
1163
1164   /* Signature creation time.  */
1165   long int timestamp;
1166
1167   /* The fingerprint of the signature.  */
1168   char *fpr;
1169
1170 #ifdef __cplusplus
1171   unsigned int _obsolete_class_2;
1172 #else
1173   /* Must be set to SIG_CLASS below.  */
1174   unsigned int class _GPGME_DEPRECATED;
1175 #endif
1176
1177   /* Crypto backend specific signature class.  */
1178   unsigned int sig_class;
1179 };
1180 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1181
1182 struct _gpgme_op_sign_result
1183 {
1184   /* The list of invalid signers.  */
1185   gpgme_invalid_key_t invalid_signers;
1186   gpgme_new_signature_t signatures;
1187 };
1188 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1189
1190 /* Retrieve a pointer to the result of the signing operation.  */
1191 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1192
1193 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1194 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1195                                    gpgme_data_t plain, gpgme_data_t sig,
1196                                    gpgme_sig_mode_t mode);
1197 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1198                              gpgme_data_t plain, gpgme_data_t sig,
1199                              gpgme_sig_mode_t mode);
1200
1201 \f
1202 /* Verify.  */
1203 struct _gpgme_sig_notation
1204 {
1205   struct _gpgme_sig_notation *next;
1206
1207   /* If NAME is a null pointer, then VALUE contains a policy URL
1208      rather than a notation.  */
1209   char *name;
1210   char *value;
1211 };
1212 typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
1213
1214 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1215 typedef enum
1216   {
1217     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1218     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1219     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1220     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1221     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1222     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1223     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1224     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1225     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1226     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1227     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1228   }
1229 gpgme_sigsum_t;
1230
1231 struct _gpgme_signature
1232 {
1233   struct _gpgme_signature *next;
1234
1235   /* A summary of the signature status.  */
1236   gpgme_sigsum_t summary;
1237
1238   /* The fingerprint or key ID of the signature.  */
1239   char *fpr;
1240
1241   /* The status of the signature.  */
1242   gpgme_error_t status;
1243
1244   /* Notation data and policy URLs.  */
1245   gpgme_sig_notation_t notations;
1246
1247   /* Signature creation time.  */
1248   unsigned long timestamp;
1249
1250   /* Signature exipration time or 0.  */
1251   unsigned long exp_timestamp;
1252
1253   /* Key should not have been used for signing.  */
1254   unsigned int wrong_key_usage : 1;
1255
1256   /* Internal to GPGME, do not use.  */
1257   int _unused : 31;
1258
1259   gpgme_validity_t validity;
1260   gpgme_error_t validity_reason;
1261
1262   /* The public key algorithm used to create the signature.  */
1263   gpgme_pubkey_algo_t pubkey_algo;
1264
1265   /* The hash algorithm used to create the signature.  */
1266   gpgme_hash_algo_t hash_algo;
1267 };
1268 typedef struct _gpgme_signature *gpgme_signature_t;
1269
1270 struct _gpgme_op_verify_result
1271 {
1272   gpgme_signature_t signatures;
1273
1274   /* The original filename of the plaintext message, if available.  */
1275   char *plaintext_filename;
1276 };
1277 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1278
1279 /* Retrieve a pointer to the result of the verify operation.  */
1280 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1281
1282 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1283 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1284                                      gpgme_data_t signed_text,
1285                                      gpgme_data_t plaintext);
1286 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1287                                gpgme_data_t signed_text,
1288                                gpgme_data_t plaintext);
1289
1290 \f
1291 /* Import.  */
1292
1293 /* The key was new.  */
1294 #define GPGME_IMPORT_NEW        1
1295
1296 /* The key contained new user IDs.  */
1297 #define GPGME_IMPORT_UID        2
1298
1299 /* The key contained new signatures.  */
1300 #define GPGME_IMPORT_SIG        4
1301
1302 /* The key contained new sub keys.  */
1303 #define GPGME_IMPORT_SUBKEY     8
1304
1305 /* The key contained a secret key.  */
1306 #define GPGME_IMPORT_SECRET     16
1307
1308
1309 struct _gpgme_import_status
1310 {
1311   struct _gpgme_import_status *next;
1312
1313   /* Fingerprint.  */
1314   char *fpr;
1315
1316   /* If a problem occured, the reason why the key could not be
1317      imported.  Otherwise GPGME_No_Error.  */
1318   gpgme_error_t result;
1319
1320   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1321      ORed.  0 means the key was already known and no new components
1322      have been added.  */
1323   unsigned int status;
1324 };
1325 typedef struct _gpgme_import_status *gpgme_import_status_t;
1326
1327 /* Import.  */
1328 struct _gpgme_op_import_result
1329 {
1330   /* Number of considered keys.  */
1331   int considered;
1332
1333   /* Keys without user ID.  */
1334   int no_user_id;
1335
1336   /* Imported keys.  */
1337   int imported;
1338
1339   /* Imported RSA keys.  */
1340   int imported_rsa;
1341
1342   /* Unchanged keys.  */
1343   int unchanged;
1344
1345   /* Number of new user ids.  */
1346   int new_user_ids;
1347
1348   /* Number of new sub keys.  */
1349   int new_sub_keys;
1350
1351   /* Number of new signatures.  */
1352   int new_signatures;
1353
1354   /* Number of new revocations.  */
1355   int new_revocations;
1356
1357   /* Number of secret keys read.  */
1358   int secret_read;
1359
1360   /* Number of secret keys imported.  */
1361   int secret_imported;
1362
1363   /* Number of secret keys unchanged.  */
1364   int secret_unchanged;
1365
1366   /* Number of new keys skipped.  */
1367   int skipped_new_keys;
1368
1369   /* Number of keys not imported.  */
1370   int not_imported;
1371
1372   /* List of keys for which an import was attempted.  */
1373   gpgme_import_status_t imports;
1374 };
1375 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1376
1377 /* Retrieve a pointer to the result of the import operation.  */
1378 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1379
1380 /* Import the key in KEYDATA into the keyring.  */
1381 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1382 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1383 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
1384                                    int *nr) _GPGME_DEPRECATED;
1385
1386 \f
1387 /* Export the keys found by PATTERN into KEYDATA.  */
1388 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1389                                      unsigned int reserved,
1390                                      gpgme_data_t keydata);
1391 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1392                                unsigned int reserved, gpgme_data_t keydata);
1393
1394 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1395                                          const char *pattern[],
1396                                          unsigned int reserved,
1397                                          gpgme_data_t keydata);
1398 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1399                                    unsigned int reserved,
1400                                    gpgme_data_t keydata);
1401
1402 \f
1403 /* Key generation.  */
1404 struct _gpgme_op_genkey_result
1405 {
1406   /* A primary key was generated.  */
1407   unsigned int primary : 1;
1408
1409   /* A sub key was generated.  */
1410   unsigned int sub : 1;
1411
1412   /* Internal to GPGME, do not use.  */
1413   unsigned int _unused : 30;
1414
1415   /* The fingerprint of the generated key.  */
1416   char *fpr;
1417 };
1418 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1419
1420 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1421    SECKEY should be null for now.  PARMS specifies what keys should be
1422    generated.  */
1423 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1424                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1425 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1426                                gpgme_data_t pubkey, gpgme_data_t seckey);
1427
1428 /* Retrieve a pointer to the result of the genkey operation.  */
1429 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1430
1431 \f
1432 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1433    keys are also deleted.  */
1434 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1435                                      int allow_secret);
1436 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1437                                int allow_secret);
1438
1439 \f
1440 /* Edit the key KEY.  Send status and command requests to FNC and
1441    output of edit commands to OUT.  */
1442 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1443                                    gpgme_edit_cb_t fnc, void *fnc_value,
1444                                    gpgme_data_t out);
1445 gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1446                              gpgme_edit_cb_t fnc, void *fnc_value,
1447                              gpgme_data_t out);
1448
1449 /* Edit the card for the key KEY.  Send status and command requests to
1450    FNC and output of edit commands to OUT.  */
1451 gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1452                                         gpgme_edit_cb_t fnc, void *fnc_value,
1453                                         gpgme_data_t out);
1454 gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1455                                   gpgme_edit_cb_t fnc, void *fnc_value,
1456                                   gpgme_data_t out);
1457
1458 \f
1459 /* Key management functions.  */
1460 struct _gpgme_op_keylist_result
1461 {
1462   unsigned int truncated : 1;
1463
1464   /* Internal to GPGME, do not use.  */
1465   unsigned int _unused : 31;
1466 };
1467 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
1468
1469 /* Retrieve a pointer to the result of the key listing operation.  */
1470 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
1471
1472 /* Start a keylist operation within CTX, searching for keys which
1473    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1474    returned.  */
1475 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
1476                                       int secret_only);
1477 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
1478                                           const char *pattern[],
1479                                           int secret_only, int reserved);
1480
1481 /* Return the next key from the keylist in R_KEY.  */
1482 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
1483
1484 /* Terminate a pending keylist operation within CTX.  */
1485 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
1486
1487 \f
1488 /* Trust items and operations.  */
1489
1490 struct _gpgme_trust_item
1491 {
1492   /* Internal to GPGME, do not use.  */
1493   unsigned int _refs;
1494
1495   /* The key ID to which the trust item belongs.  */
1496   char *keyid;
1497
1498   /* Internal to GPGME, do not use.  */
1499   char _keyid[16 + 1];
1500
1501   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1502   int type;
1503
1504   /* The trust level.  */
1505   int level;
1506
1507   /* The owner trust if TYPE is 1.  */
1508   char *owner_trust;
1509
1510   /* Internal to GPGME, do not use.  */
1511   char _owner_trust[2];
1512
1513   /* The calculated validity.  */
1514   char *validity;
1515  
1516   /* Internal to GPGME, do not use.  */
1517   char _validity[2];
1518
1519   /* The user name if TYPE is 2.  */
1520   char *name;
1521 };
1522 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
1523
1524 /* Start a trustlist operation within CTX, searching for trust items
1525    which match PATTERN.  */
1526 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
1527                                         const char *pattern, int max_level);
1528
1529 /* Return the next trust item from the trustlist in R_ITEM.  */
1530 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
1531                                        gpgme_trust_item_t *r_item);
1532
1533 /* Terminate a pending trustlist operation within CTX.  */
1534 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
1535
1536 /* Acquire a reference to ITEM.  */
1537 void gpgme_trust_item_ref (gpgme_trust_item_t item);
1538
1539 /* Release a reference to ITEM.  If this was the last one the trust
1540    item is destroyed.  */
1541 void gpgme_trust_item_unref (gpgme_trust_item_t item);
1542
1543 /* Release the trust item ITEM.  Deprecated, use
1544    gpgme_trust_item_unref.  */
1545 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED;
1546
1547 /* Return the value of the attribute WHAT of ITEM, which has to be
1548    representable by a string.  Deprecated, use trust item structure
1549    directly.  */
1550 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
1551                                               _gpgme_attr_t what,
1552                                               const void *reserved, int idx)
1553      _GPGME_DEPRECATED;
1554
1555 /* Return the value of the attribute WHAT of KEY, which has to be
1556    representable by an integer.  IDX specifies a running index if the
1557    attribute appears more than once in the key.  Deprecated, use trust
1558    item structure directly.  */
1559 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
1560                                    const void *reserved, int idx)
1561      _GPGME_DEPRECATED;
1562
1563 \f
1564 /* Various functions.  */
1565
1566 /* Check that the library fulfills the version requirement.  */
1567 const char *gpgme_check_version (const char *req_version);
1568
1569 /* Get the information about the configured and installed engines.  A
1570    pointer to the first engine in the statically allocated linked list
1571    is returned in *INFO.  If an error occurs, it is returned.  The
1572    returned data is valid until the next gpgme_set_engine_info.  */
1573 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
1574
1575 /* Set the default engine info for the protocol PROTO to the file name
1576    FILE_NAME and the home directory HOME_DIR.  */
1577 gpgme_error_t gpgme_set_engine_info (gpgme_protocol_t proto,
1578                                      const char *file_name,
1579                                      const char *home_dir);
1580
1581 \f
1582 /* Engine support functions.  */
1583
1584 /* Verify that the engine implementing PROTO is installed and
1585    available.  */
1586 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
1587
1588 \f
1589 /* Deprecated types.  */
1590 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED;
1591 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED;
1592 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED;
1593 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED;
1594 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED;
1595 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED;
1596 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED;
1597 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED;
1598 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED;
1599 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED;
1600 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED;
1601 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED;
1602 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED;
1603 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED;
1604 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED;
1605 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED;
1606 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED;
1607 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED;
1608 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED;
1609 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED;
1610 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED;
1611 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED;
1612 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED;
1613 #define GpgmeIOCbs gpgme_io_cbs
1614 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED;
1615 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED;
1616 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED;
1617 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED;
1618 #define GpgmeDataCbs gpgme_data_cbs
1619 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED;
1620 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED;
1621 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED;
1622 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED;
1623 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED;
1624 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED;
1625 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED;
1626 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED;
1627 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED;
1628
1629 #ifdef __cplusplus
1630 }
1631 #endif
1632 #endif /* GPGME_H */