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