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