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