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