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