032a205ff866c9bbc1020b42a7feb31c28a6cbe6
[gpgme.git] / src / gpgme.h.in
1 /* gpgme.h - Public interface to GnuPG Made Easy.                   -*- c -*-
2  * Copyright (C) 2000 Werner Koch (dd9jn)
3  * Copyright (C) 2001-2017 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, see <http://www.gnu.org/licenses/>.
19  *
20  * Generated from gpgme.h.in for @GPGME_CONFIG_HOST@.
21  */
22
23 #ifndef GPGME_H
24 #define GPGME_H
25
26 /* Include stdio.h for the FILE type definition.  */
27 #include <stdio.h>
28 #include <time.h>
29 #include <gpg-error.h>
30
31 #ifdef __cplusplus
32 extern "C" {
33 #if 0 /*(Make Emacsen's auto-indent happy.)*/
34 }
35 #endif
36 #endif /* __cplusplus */
37
38
39 /* The version of this header should match the one of the library.  Do
40    not use this symbol in your application, use gpgme_check_version
41    instead.  The purpose of this macro is to let autoconf (using the
42    AM_PATH_GPGME macro) check that this header matches the installed
43    library.  */
44 #define GPGME_VERSION "@PACKAGE_VERSION@"
45
46 /* The version number of this header.  It may be used to handle minor
47    API incompatibilities.  */
48 #define GPGME_VERSION_NUMBER @VERSION_NUMBER@
49
50
51 /* System specific typedefs.  */
52 @INSERT__TYPEDEFS_FOR_GPGME_H@
53
54
55 \f
56 /*
57  * Check for compiler features.
58  */
59 #ifdef GPGRT_INLINE
60 # define _GPGME_INLINE GPGRT_INLINE
61 #elif defined(__GNUC__)
62 # define _GPGME_INLINE __inline__
63 #elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
64 # define _GPGME_INLINE inline
65 #else
66 # define _GPGME_INLINE
67 #endif
68
69
70 /* The deprecated macro takes the version number of GPGME which
71  * introduced the deprecation as parameter for documentation.  */
72 #ifdef GPGRT_ATTR_DEPRECATED
73 # define _GPGME_DEPRECATED(a,b) GPGRT_ATTR_DEPRECATED
74 #elif defined(__GNUC__)
75 # define _GPGME_GCC_VERSION (__GNUC__ * 10000 \
76                              + __GNUC_MINOR__ * 100 \
77                              + __GNUC_PATCHLEVEL__)
78
79 # if _GPGME_GCC_VERSION > 30100
80 #  define _GPGME_DEPRECATED(a,b)  __attribute__ ((__deprecated__))
81 # else
82 #  define _GPGME_DEPRECATED(a,b)
83 # endif
84 #else
85 # define _GPGME_DEPRECATED(a,b)
86 #endif
87
88
89 /* The macro _GPGME_DEPRECATED_OUTSIDE_GPGME suppresses warnings for
90    fields we must access in GPGME for ABI compatibility.  */
91 #ifdef _GPGME_IN_GPGME
92 #define _GPGME_DEPRECATED_OUTSIDE_GPGME(a,b)
93 #else
94 #define _GPGME_DEPRECATED_OUTSIDE_GPGME(a,b) _GPGME_DEPRECATED(a,b)
95 #endif
96
97
98 /* Check for a matching _FILE_OFFSET_BITS definition.  */
99 #if @NEED__FILE_OFFSET_BITS@
100 #ifndef _FILE_OFFSET_BITS
101 #error GPGME was compiled with _FILE_OFFSET_BITS = @NEED__FILE_OFFSET_BITS@, please see the section "Largefile support (LFS)" in the GPGME manual.
102 #else
103 #if (_FILE_OFFSET_BITS) != (@NEED__FILE_OFFSET_BITS@)
104 #error GPGME was compiled with a different value for _FILE_OFFSET_BITS, namely @NEED__FILE_OFFSET_BITS@, please see the section "Largefile support (LFS)" in the GPGME manual.
105 #endif
106 #endif
107 #endif
108
109
110 \f
111 /*
112  * Some opaque data types used by GPGME.
113  */
114
115 /* The context holds some global state and configuration options, as
116    well as the results of a crypto operation.  */
117 struct gpgme_context;
118 typedef struct gpgme_context *gpgme_ctx_t;
119
120 /* The data object is used by GPGME to exchange arbitrary data.  */
121 struct gpgme_data;
122 typedef struct gpgme_data *gpgme_data_t;
123
124
125 \f
126 /*
127  * Wrappers for the libgpg-error library.
128  */
129
130 typedef gpg_error_t gpgme_error_t;
131 typedef gpg_err_code_t gpgme_err_code_t;
132 typedef gpg_err_source_t gpgme_err_source_t;
133
134
135 static _GPGME_INLINE gpgme_error_t
136 gpgme_err_make (gpgme_err_source_t source, gpgme_err_code_t code)
137 {
138   return gpg_err_make (source, code);
139 }
140
141
142 /* The user can define GPGME_ERR_SOURCE_DEFAULT before including this
143    file to specify a default source for gpgme_error.  */
144 #ifndef GPGME_ERR_SOURCE_DEFAULT
145 #define GPGME_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_1
146 #endif
147
148 static _GPGME_INLINE gpgme_error_t
149 gpgme_error (gpgme_err_code_t code)
150 {
151   return gpgme_err_make (GPGME_ERR_SOURCE_DEFAULT, code);
152 }
153
154
155 static _GPGME_INLINE gpgme_err_code_t
156 gpgme_err_code (gpgme_error_t err)
157 {
158   return gpg_err_code (err);
159 }
160
161
162 static _GPGME_INLINE gpgme_err_source_t
163 gpgme_err_source (gpgme_error_t err)
164 {
165   return gpg_err_source (err);
166 }
167
168
169 /* Return a pointer to a string containing a description of the error
170    code in the error value ERR.  This function is not thread safe.  */
171 const char *gpgme_strerror (gpgme_error_t err);
172
173 /* Return the error string for ERR in the user-supplied buffer BUF of
174    size BUFLEN.  This function is, in contrast to gpg_strerror,
175    thread-safe if a thread-safe strerror_r() function is provided by
176    the system.  If the function succeeds, 0 is returned and BUF
177    contains the string describing the error.  If the buffer was not
178    large enough, ERANGE is returned and BUF contains as much of the
179    beginning of the error string as fits into the buffer.  */
180 int gpgme_strerror_r (gpg_error_t err, char *buf, size_t buflen);
181
182 /* Return a pointer to a string containing a description of the error
183    source in the error value ERR.  */
184 const char *gpgme_strsource (gpgme_error_t err);
185
186 /* Retrieve the error code for the system error ERR.  This returns
187    GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
188    this).  */
189 gpgme_err_code_t gpgme_err_code_from_errno (int err);
190
191 /* Retrieve the system error for the error code CODE.  This returns 0
192    if CODE is not a system error code.  */
193 int gpgme_err_code_to_errno (gpgme_err_code_t code);
194
195 /* Retrieve the error code directly from the ERRNO variable.  This
196    returns GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped
197    (report this) and GPG_ERR_MISSING_ERRNO if ERRNO has the value 0. */
198 gpgme_err_code_t gpgme_err_code_from_syserror (void);
199
200 /* Set the ERRNO variable.  This function is the preferred way to set
201    ERRNO due to peculiarities on WindowsCE.  */
202 void gpgme_err_set_errno (int err);
203
204 /* Return an error value with the error source SOURCE and the system
205    error ERR.  FIXME: Should be inline.  */
206 gpgme_error_t gpgme_err_make_from_errno (gpgme_err_source_t source, int err);
207
208 /* Return an error value with the system error ERR.  FIXME: Should be inline.  */
209 gpgme_error_t gpgme_error_from_errno (int err);
210
211
212 static _GPGME_INLINE gpgme_error_t
213 gpgme_error_from_syserror (void)
214 {
215   return gpgme_error (gpgme_err_code_from_syserror ());
216 }
217
218
219 \f
220 /*
221  * Various constants and types
222  */
223
224 /* The possible encoding mode of gpgme_data_t objects.  */
225 typedef enum
226   {
227     GPGME_DATA_ENCODING_NONE   = 0,     /* Not specified.  */
228     GPGME_DATA_ENCODING_BINARY = 1,
229     GPGME_DATA_ENCODING_BASE64 = 2,
230     GPGME_DATA_ENCODING_ARMOR  = 3,     /* Either PEM or OpenPGP Armor.  */
231     GPGME_DATA_ENCODING_URL    = 4,     /* LF delimited URL list.        */
232     GPGME_DATA_ENCODING_URLESC = 5,     /* Ditto, but percent escaped.   */
233     GPGME_DATA_ENCODING_URL0   = 6,     /* Nul delimited URL list.       */
234     GPGME_DATA_ENCODING_MIME   = 7      /* Data is a MIME part.          */
235   }
236 gpgme_data_encoding_t;
237
238
239 /* Known data types.  */
240 typedef enum
241   {
242     GPGME_DATA_TYPE_INVALID      = 0,   /* Not detected.  */
243     GPGME_DATA_TYPE_UNKNOWN      = 1,
244     GPGME_DATA_TYPE_PGP_SIGNED   = 0x10,
245     GPGME_DATA_TYPE_PGP_ENCRYPTED= 0x11,
246     GPGME_DATA_TYPE_PGP_OTHER    = 0x12,
247     GPGME_DATA_TYPE_PGP_KEY      = 0x13,
248     GPGME_DATA_TYPE_PGP_SIGNATURE= 0x18, /* Detached signature */
249     GPGME_DATA_TYPE_CMS_SIGNED   = 0x20,
250     GPGME_DATA_TYPE_CMS_ENCRYPTED= 0x21,
251     GPGME_DATA_TYPE_CMS_OTHER    = 0x22,
252     GPGME_DATA_TYPE_X509_CERT    = 0x23,
253     GPGME_DATA_TYPE_PKCS12       = 0x24,
254   }
255 gpgme_data_type_t;
256
257
258 /* Public key algorithms.  */
259 typedef enum
260   {
261     GPGME_PK_RSA   = 1,
262     GPGME_PK_RSA_E = 2,
263     GPGME_PK_RSA_S = 3,
264     GPGME_PK_ELG_E = 16,
265     GPGME_PK_DSA   = 17,
266     GPGME_PK_ECC   = 18,
267     GPGME_PK_ELG   = 20,
268     GPGME_PK_ECDSA = 301,
269     GPGME_PK_ECDH  = 302,
270     GPGME_PK_EDDSA = 303
271   }
272 gpgme_pubkey_algo_t;
273
274
275 /* Hash algorithms (the values match those from libgcrypt).  */
276 typedef enum
277   {
278     GPGME_MD_NONE          = 0,
279     GPGME_MD_MD5           = 1,
280     GPGME_MD_SHA1          = 2,
281     GPGME_MD_RMD160        = 3,
282     GPGME_MD_MD2           = 5,
283     GPGME_MD_TIGER         = 6,   /* TIGER/192. */
284     GPGME_MD_HAVAL         = 7,   /* HAVAL, 5 pass, 160 bit. */
285     GPGME_MD_SHA256        = 8,
286     GPGME_MD_SHA384        = 9,
287     GPGME_MD_SHA512        = 10,
288     GPGME_MD_SHA224        = 11,
289     GPGME_MD_MD4           = 301,
290     GPGME_MD_CRC32         = 302,
291     GPGME_MD_CRC32_RFC1510 = 303,
292     GPGME_MD_CRC24_RFC2440 = 304
293   }
294 gpgme_hash_algo_t;
295
296
297 /* The available signature modes.  */
298 typedef enum
299   {
300     GPGME_SIG_MODE_NORMAL = 0,
301     GPGME_SIG_MODE_DETACH = 1,
302     GPGME_SIG_MODE_CLEAR  = 2
303   }
304 gpgme_sig_mode_t;
305
306
307 /* The available validities for a trust item or key.  */
308 typedef enum
309   {
310     GPGME_VALIDITY_UNKNOWN   = 0,
311     GPGME_VALIDITY_UNDEFINED = 1,
312     GPGME_VALIDITY_NEVER     = 2,
313     GPGME_VALIDITY_MARGINAL  = 3,
314     GPGME_VALIDITY_FULL      = 4,
315     GPGME_VALIDITY_ULTIMATE  = 5
316   }
317 gpgme_validity_t;
318
319
320 /* The TOFU policies. */
321 typedef enum
322   {
323     GPGME_TOFU_POLICY_NONE    = 0,
324     GPGME_TOFU_POLICY_AUTO    = 1,
325     GPGME_TOFU_POLICY_GOOD    = 2,
326     GPGME_TOFU_POLICY_UNKNOWN = 3,
327     GPGME_TOFU_POLICY_BAD     = 4,
328     GPGME_TOFU_POLICY_ASK     = 5
329   }
330 gpgme_tofu_policy_t;
331
332
333 /* The available protocols.  */
334 typedef enum
335   {
336     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
337     GPGME_PROTOCOL_CMS     = 1,
338     GPGME_PROTOCOL_GPGCONF = 2,  /* Special code for gpgconf.  */
339     GPGME_PROTOCOL_ASSUAN  = 3,  /* Low-level access to an Assuan server.  */
340     GPGME_PROTOCOL_G13     = 4,
341     GPGME_PROTOCOL_UISERVER= 5,
342     GPGME_PROTOCOL_SPAWN   = 6,  /* Direct access to any program.  */
343     GPGME_PROTOCOL_DEFAULT = 254,
344     GPGME_PROTOCOL_UNKNOWN = 255
345   }
346 gpgme_protocol_t;
347 /* Convenience macro for the surprisingly mixed spelling.  */
348 #define GPGME_PROTOCOL_OPENPGP GPGME_PROTOCOL_OpenPGP
349
350
351 /* The available keylist mode flags.  */
352 #define GPGME_KEYLIST_MODE_LOCAL                1
353 #define GPGME_KEYLIST_MODE_EXTERN               2
354 #define GPGME_KEYLIST_MODE_SIGS                 4
355 #define GPGME_KEYLIST_MODE_SIG_NOTATIONS        8
356 #define GPGME_KEYLIST_MODE_WITH_SECRET          16
357 #define GPGME_KEYLIST_MODE_WITH_TOFU            32
358 #define GPGME_KEYLIST_MODE_EPHEMERAL            128
359 #define GPGME_KEYLIST_MODE_VALIDATE             256
360
361 typedef unsigned int gpgme_keylist_mode_t;
362
363
364 /* The pinentry modes. */
365 typedef enum
366   {
367     GPGME_PINENTRY_MODE_DEFAULT  = 0,
368     GPGME_PINENTRY_MODE_ASK      = 1,
369     GPGME_PINENTRY_MODE_CANCEL   = 2,
370     GPGME_PINENTRY_MODE_ERROR    = 3,
371     GPGME_PINENTRY_MODE_LOOPBACK = 4
372   }
373 gpgme_pinentry_mode_t;
374
375
376 /* The available export mode flags.  */
377 #define GPGME_EXPORT_MODE_EXTERN                2
378 #define GPGME_EXPORT_MODE_MINIMAL               4
379 #define GPGME_EXPORT_MODE_SECRET               16
380 #define GPGME_EXPORT_MODE_RAW                  32
381 #define GPGME_EXPORT_MODE_PKCS12               64
382
383 typedef unsigned int gpgme_export_mode_t;
384
385
386 /* Flags for the audit log functions.  */
387 #define GPGME_AUDITLOG_HTML      1
388 #define GPGME_AUDITLOG_WITH_HELP 128
389
390
391 /* The available signature notation flags.  */
392 #define GPGME_SIG_NOTATION_HUMAN_READABLE       1
393 #define GPGME_SIG_NOTATION_CRITICAL             2
394
395 typedef unsigned int gpgme_sig_notation_flags_t;
396
397 /* An object to hold information about notation data.  This structure
398  * shall be considered read-only and an application must not allocate
399  * such a structure on its own.  */
400 struct _gpgme_sig_notation
401 {
402   struct _gpgme_sig_notation *next;
403
404   /* If NAME is a null pointer, then VALUE contains a policy URL
405      rather than a notation.  */
406   char *name;
407
408   /* The value of the notation data.  */
409   char *value;
410
411   /* The length of the name of the notation data.  */
412   int name_len;
413
414   /* The length of the value of the notation data.  */
415   int value_len;
416
417   /* The accumulated flags.  */
418   gpgme_sig_notation_flags_t flags;
419
420   /* Notation data is human-readable.  */
421   unsigned int human_readable : 1;
422
423   /* Notation data is critical.  */
424   unsigned int critical : 1;
425
426   /* Internal to GPGME, do not use.  */
427   int _unused : 30;
428 };
429 typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
430
431
432 \f
433 /*
434  * Public structures.
435  */
436
437 /* The engine information structure.
438  * This structure shall be considered read-only and an application
439  * must not allocate such a structure on its own.  */
440 struct _gpgme_engine_info
441 {
442   struct _gpgme_engine_info *next;
443
444   /* The protocol ID.  */
445   gpgme_protocol_t protocol;
446
447   /* The file name of the engine binary.  */
448   char *file_name;
449
450   /* The version string of the installed engine.  */
451   char *version;
452
453   /* The minimum version required for GPGME.  */
454   const char *req_version;
455
456   /* The home directory used, or NULL if default.  */
457   char *home_dir;
458 };
459 typedef struct _gpgme_engine_info *gpgme_engine_info_t;
460
461
462 /* An object with TOFU information.
463  * This structure shall be considered read-only and an application
464  * must not allocate such a structure on its own.  */
465 struct _gpgme_tofu_info
466 {
467   struct _gpgme_tofu_info *next;
468
469   /* The TOFU validity:
470    *  0 := conflict
471    *  1 := key without history
472    *  2 := key with too little history
473    *  3 := key with enough history for basic trust
474    *  4 := key with a lot of history
475    */
476   unsigned int validity : 3;
477
478   /* The TOFU policy (gpgme_tofu_policy_t).  */
479   unsigned int policy : 4;
480
481   unsigned int _rfu : 25;
482
483   /* Number of signatures seen for this binding.  Capped at USHRT_MAX.  */
484   unsigned short signcount;
485   /* Number of encryptions done with this binding.  Capped at USHRT_MAX.  */
486   unsigned short encrcount;
487
488   /* Number of seconds since Epoch when the first and the most
489    * recently seen message were verified/decrypted.  0 means unknown. */
490   unsigned long signfirst;
491   unsigned long signlast;
492   unsigned long encrfirst;
493   unsigned long encrlast;
494
495   /* If non-NULL a human readable string summarizing the TOFU data. */
496   char *description;
497 };
498 typedef struct _gpgme_tofu_info *gpgme_tofu_info_t;
499
500
501 /* A subkey from a key.
502  * This structure shall be considered read-only and an application
503  * must not allocate such a structure on its own.  */
504 struct _gpgme_subkey
505 {
506   struct _gpgme_subkey *next;
507
508   /* True if subkey is revoked.  */
509   unsigned int revoked : 1;
510
511   /* True if subkey is expired.  */
512   unsigned int expired : 1;
513
514   /* True if subkey is disabled.  */
515   unsigned int disabled : 1;
516
517   /* True if subkey is invalid.  */
518   unsigned int invalid : 1;
519
520   /* True if subkey can be used for encryption.  */
521   unsigned int can_encrypt : 1;
522
523   /* True if subkey can be used for signing.  */
524   unsigned int can_sign : 1;
525
526   /* True if subkey can be used for certification.  */
527   unsigned int can_certify : 1;
528
529   /* True if subkey is secret.  */
530   unsigned int secret : 1;
531
532   /* True if subkey can be used for authentication.  */
533   unsigned int can_authenticate : 1;
534
535   /* True if subkey is qualified for signatures according to German law.  */
536   unsigned int is_qualified : 1;
537
538   /* True if the secret key is stored on a smart card.  */
539   unsigned int is_cardkey : 1;
540
541   /* Internal to GPGME, do not use.  */
542   unsigned int _unused : 21;
543
544   /* Public key algorithm supported by this subkey.  */
545   gpgme_pubkey_algo_t pubkey_algo;
546
547   /* Length of the subkey.  */
548   unsigned int length;
549
550   /* The key ID of the subkey.  */
551   char *keyid;
552
553   /* Internal to GPGME, do not use.  */
554   char _keyid[16 + 1];
555
556   /* The fingerprint of the subkey in hex digit form.  */
557   char *fpr;
558
559   /* The creation timestamp, -1 if invalid, 0 if not available.  */
560   long int timestamp;
561
562   /* The expiration timestamp, 0 if the subkey does not expire.  */
563   long int expires;
564
565   /* The serial number of a smart card holding this key or NULL.  */
566   char *card_number;
567
568   /* The name of the curve for ECC algorithms or NULL.  */
569   char *curve;
570
571   /* The keygrip of the subkey in hex digit form or NULL if not availabale.  */
572   char *keygrip;
573 };
574 typedef struct _gpgme_subkey *gpgme_subkey_t;
575
576
577 /* A signature on a user ID.
578  * This structure shall be considered read-only and an application
579  * must not allocate such a structure on its own.  */
580 struct _gpgme_key_sig
581 {
582   struct _gpgme_key_sig *next;
583
584   /* True if the signature is a revocation signature.  */
585   unsigned int revoked : 1;
586
587   /* True if the signature is expired.  */
588   unsigned int expired : 1;
589
590   /* True if the signature is invalid.  */
591   unsigned int invalid : 1;
592
593   /* True if the signature should be exported.  */
594   unsigned int exportable : 1;
595
596   /* Internal to GPGME, do not use.  */
597   unsigned int _unused : 28;
598
599   /* The public key algorithm used to create the signature.  */
600   gpgme_pubkey_algo_t pubkey_algo;
601
602   /* The key ID of key used to create the signature.  */
603   char *keyid;
604
605   /* Internal to GPGME, do not use.  */
606   char _keyid[16 + 1];
607
608   /* The creation timestamp, -1 if invalid, 0 if not available.  */
609   long int timestamp;
610
611   /* The expiration timestamp, 0 if the subkey does not expire.  */
612   long int expires;
613
614   /* Same as in gpgme_signature_t.  */
615   gpgme_error_t status;
616
617 #ifdef __cplusplus
618   unsigned int _obsolete_class _GPGME_DEPRECATED(0,4);
619 #else
620   /* Must be set to SIG_CLASS below.  */
621   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME(0,4);
622 #endif
623
624   /* The user ID string.  */
625   char *uid;
626
627   /* The name part of the user ID.  */
628   char *name;
629
630   /* The email part of the user ID.  */
631   char *email;
632
633   /* The comment part of the user ID.  */
634   char *comment;
635
636   /* Crypto backend specific signature class.  */
637   unsigned int sig_class;
638
639   /* Notation data and policy URLs.  */
640   gpgme_sig_notation_t notations;
641
642   /* Internal to GPGME, do not use.  */
643   gpgme_sig_notation_t _last_notation;
644 };
645 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
646
647
648 /* An user ID from a key.
649  * This structure shall be considered read-only and an application
650  * must not allocate such a structure on its own.  */
651 struct _gpgme_user_id
652 {
653   struct _gpgme_user_id *next;
654
655   /* True if the user ID is revoked.  */
656   unsigned int revoked : 1;
657
658   /* True if the user ID is invalid.  */
659   unsigned int invalid : 1;
660
661   /* Internal to GPGME, do not use.  */
662   unsigned int _unused : 30;
663
664   /* The validity of the user ID.  */
665   gpgme_validity_t validity;
666
667   /* The user ID string.  */
668   char *uid;
669
670   /* The name part of the user ID.  */
671   char *name;
672
673   /* The email part of the user ID.  */
674   char *email;
675
676   /* The comment part of the user ID.  */
677   char *comment;
678
679   /* The signatures of the user ID.  */
680   gpgme_key_sig_t signatures;
681
682   /* Internal to GPGME, do not use.  */
683   gpgme_key_sig_t _last_keysig;
684
685   /* The mail address (addr-spec from RFC5322) of the UID string.
686    * This is general the same as the EMAIL part of this struct but
687    * might be slightly different.  If no mail address is available
688    * NULL is stored.  */
689   char *address;
690
691   /* The malloced TOFU information or NULL.  */
692   gpgme_tofu_info_t tofu;
693 };
694 typedef struct _gpgme_user_id *gpgme_user_id_t;
695
696
697 /* A key from the keyring.
698  * This structure shall be considered read-only and an application
699  * must not allocate such a structure on its own.  */
700 struct _gpgme_key
701 {
702   /* Internal to GPGME, do not use.  */
703   unsigned int _refs;
704
705   /* True if key is revoked.  */
706   unsigned int revoked : 1;
707
708   /* True if key is expired.  */
709   unsigned int expired : 1;
710
711   /* True if key is disabled.  */
712   unsigned int disabled : 1;
713
714   /* True if key is invalid.  */
715   unsigned int invalid : 1;
716
717   /* True if key can be used for encryption.  */
718   unsigned int can_encrypt : 1;
719
720   /* True if key can be used for signing.  */
721   unsigned int can_sign : 1;
722
723   /* True if key can be used for certification.  */
724   unsigned int can_certify : 1;
725
726   /* True if key is secret.  */
727   unsigned int secret : 1;
728
729   /* True if key can be used for authentication.  */
730   unsigned int can_authenticate : 1;
731
732   /* True if subkey is qualified for signatures according to German law.  */
733   unsigned int is_qualified : 1;
734
735   /* Internal to GPGME, do not use.  */
736   unsigned int _unused : 22;
737
738   /* This is the protocol supported by this key.  */
739   gpgme_protocol_t protocol;
740
741   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
742      issuer serial.  */
743   char *issuer_serial;
744
745   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
746      issuer name.  */
747   char *issuer_name;
748
749   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
750      ID.  */
751   char *chain_id;
752
753   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
754      owner trust.  */
755   gpgme_validity_t owner_trust;
756
757   /* The subkeys of the key.  */
758   gpgme_subkey_t subkeys;
759
760   /* The user IDs of the key.  */
761   gpgme_user_id_t uids;
762
763   /* Internal to GPGME, do not use.  */
764   gpgme_subkey_t _last_subkey;
765
766   /* Internal to GPGME, do not use.  */
767   gpgme_user_id_t _last_uid;
768
769   /* The keylist mode that was active when listing the key.  */
770   gpgme_keylist_mode_t keylist_mode;
771
772   /* This field gives the fingerprint of the primary key.  Note that
773    * this is a copy of the FPR of the first subkey.  We need it here
774    * to allow for an incomplete key object.  */
775   char *fpr;
776 };
777 typedef struct _gpgme_key *gpgme_key_t;
778
779
780 /* An invalid key object.
781  * This structure shall be considered read-only and an application
782  * must not allocate such a structure on its own.  */
783 struct _gpgme_invalid_key
784 {
785   struct _gpgme_invalid_key *next;
786
787   /* The string used to request the key.  Despite the name this may
788    * not be a fingerprint.  */
789   char *fpr;
790
791   /* The error code.  */
792   gpgme_error_t reason;
793 };
794 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
795
796
797 \f
798 /*
799  * Types for callback functions.
800  */
801
802 /* Request a passphrase from the user.  */
803 typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
804                                                 const char *uid_hint,
805                                                 const char *passphrase_info,
806                                                 int prev_was_bad, int fd);
807
808 /* Inform the user about progress made.  */
809 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
810                                      int type, int current, int total);
811
812 /* Status messages from gpg. */
813 typedef gpgme_error_t (*gpgme_status_cb_t) (void *opaque, const char *keyword,
814                                             const char *args);
815
816 /* Interact with the user about an edit operation.  */
817 typedef gpgme_error_t (*gpgme_interact_cb_t) (void *opaque,
818                                               const char *keyword,
819                                               const char *args, int fd);
820
821
822 \f
823 /*
824  * Context management functions.
825  */
826
827 /* Create a new context and return it in CTX.  */
828 gpgme_error_t gpgme_new (gpgme_ctx_t *ctx);
829
830 /* Release the context CTX.  */
831 void gpgme_release (gpgme_ctx_t ctx);
832
833 /* Set the flag NAME for CTX to VALUE.  */
834 gpgme_error_t gpgme_set_ctx_flag (gpgme_ctx_t ctx,
835                                   const char *name, const char *value);
836
837 /* Get the value of the flag NAME from CTX.  */
838 const char *gpgme_get_ctx_flag (gpgme_ctx_t ctx, const char *name);
839
840 /* Set the protocol to be used by CTX to PROTO.  */
841 gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
842
843 /* Get the protocol used with CTX */
844 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
845
846 /* Set the crypto protocol to be used by CTX to PROTO.
847    gpgme_set_protocol actually sets the backend engine.  This sets the
848    crypto protocol used in engines that support more than one crypto
849    prococol (for example, an UISERVER can support OpenPGP and CMS).
850    This is reset to the default with gpgme_set_protocol.  */
851 gpgme_error_t gpgme_set_sub_protocol (gpgme_ctx_t ctx,
852                                       gpgme_protocol_t proto);
853
854 /* Get the sub protocol.  */
855 gpgme_protocol_t gpgme_get_sub_protocol (gpgme_ctx_t ctx);
856
857 /* Get the string describing protocol PROTO, or NULL if invalid.  */
858 const char *gpgme_get_protocol_name (gpgme_protocol_t proto);
859
860 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
861 void gpgme_set_armor (gpgme_ctx_t ctx, int yes);
862
863 /* Return non-zero if armor mode is set in CTX.  */
864 int gpgme_get_armor (gpgme_ctx_t ctx);
865
866 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
867 void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
868
869 /* Return non-zero if text mode is set in CTX.  */
870 int gpgme_get_textmode (gpgme_ctx_t ctx);
871
872 /* If YES is non-zero, enable offline mode in CTX, disable it otherwise.  */
873 void gpgme_set_offline (gpgme_ctx_t ctx, int yes);
874
875 /* Return non-zero if offline mode is set in CTX.  */
876 int gpgme_get_offline (gpgme_ctx_t ctx);
877
878 /* Use whatever the default of the backend crypto engine is.  */
879 #define GPGME_INCLUDE_CERTS_DEFAULT     -256
880
881 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
882 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
883
884 /* Return the number of certs to include in an S/MIME message.  */
885 int gpgme_get_include_certs (gpgme_ctx_t ctx);
886
887 /* Set keylist mode in CTX to MODE.  */
888 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
889                                       gpgme_keylist_mode_t mode);
890
891 /* Get keylist mode in CTX.  */
892 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
893
894 /* Set the pinentry mode for CTX to MODE. */
895 gpgme_error_t gpgme_set_pinentry_mode (gpgme_ctx_t ctx,
896                                        gpgme_pinentry_mode_t mode);
897
898 /* Get the pinentry mode of CTX.  */
899 gpgme_pinentry_mode_t gpgme_get_pinentry_mode (gpgme_ctx_t ctx);
900
901 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
902    passed as first argument to the passphrase callback function.  */
903 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
904                               gpgme_passphrase_cb_t cb, void *hook_value);
905
906 /* Get the current passphrase callback function in *CB and the current
907    hook value in *HOOK_VALUE.  */
908 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
909                               void **hook_value);
910
911 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
912    passed as first argument to the progress callback function.  */
913 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
914                             void *hook_value);
915
916 /* Get the current progress callback function in *CB and the current
917    hook value in *HOOK_VALUE.  */
918 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
919                             void **hook_value);
920
921 /* Set the status callback function in CTX to CB.  HOOK_VALUE is
922    passed as first argument to the status callback function.  */
923 void gpgme_set_status_cb (gpgme_ctx_t c, gpgme_status_cb_t cb,
924                           void *hook_value);
925
926 /* Get the current status callback function in *CB and the current
927    hook value in *HOOK_VALUE.  */
928 void gpgme_get_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t *cb,
929                           void **hook_value);
930
931 /* This function sets the locale for the context CTX, or the default
932    locale if CTX is a null pointer.  */
933 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
934                                 const char *value);
935
936 /* Get the information about the configured engines.  A pointer to the
937    first engine in the statically allocated linked list is returned.
938    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
939 gpgme_engine_info_t gpgme_ctx_get_engine_info (gpgme_ctx_t ctx);
940
941 /* Set the engine info for the context CTX, protocol PROTO, to the
942    file name FILE_NAME and the home directory HOME_DIR.  */
943 gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t ctx,
944                                          gpgme_protocol_t proto,
945                                          const char *file_name,
946                                          const char *home_dir);
947
948 /* Delete all signers from CTX.  */
949 void gpgme_signers_clear (gpgme_ctx_t ctx);
950
951 /* Add KEY to list of signers in CTX.  */
952 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
953
954 /* Return the number of signers in CTX.  */
955 unsigned int gpgme_signers_count (const gpgme_ctx_t ctx);
956
957 /* Return the SEQth signer's key in CTX.  */
958 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
959
960 /* Clear all notation data from the context.  */
961 void gpgme_sig_notation_clear (gpgme_ctx_t ctx);
962
963 /* Add the human-readable notation data with name NAME and value VALUE
964    to the context CTX, using the flags FLAGS.  If NAME is NULL, then
965    VALUE should be a policy URL.  The flag
966    GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
967    data, and false for policy URLs.  */
968 gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
969                                       const char *value,
970                                       gpgme_sig_notation_flags_t flags);
971
972 /* Get the sig notations for this context.  */
973 gpgme_sig_notation_t gpgme_sig_notation_get (gpgme_ctx_t ctx);
974
975 /* Store a sender address in the context.  */
976 gpgme_error_t gpgme_set_sender (gpgme_ctx_t ctx, const char *address);
977
978 /* Get the sender address from the context.  */
979 const char *gpgme_get_sender (gpgme_ctx_t ctx);
980
981
982 \f
983 /*
984  * Run control.
985  */
986
987 /* The type of an I/O callback function.  */
988 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
989
990 /* The type of a function that can register FNC as the I/O callback
991    function for the file descriptor FD with direction dir (0: for writing,
992    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
993    function should return a TAG suitable for the corresponding
994    gpgme_remove_io_cb_t, and an error value.  */
995 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
996                                                  gpgme_io_cb_t fnc,
997                                                  void *fnc_data, void **tag);
998
999 /* The type of a function that can remove a previously registered I/O
1000    callback function given TAG as returned by the register
1001    function.  */
1002 typedef void (*gpgme_remove_io_cb_t) (void *tag);
1003
1004 typedef enum
1005   {
1006     GPGME_EVENT_START,
1007     GPGME_EVENT_DONE,
1008     GPGME_EVENT_NEXT_KEY,
1009     GPGME_EVENT_NEXT_TRUSTITEM
1010   }
1011 gpgme_event_io_t;
1012
1013 struct gpgme_io_event_done_data
1014 {
1015   /* A fatal IPC error or an operational error in state-less
1016      protocols.  */
1017   gpgme_error_t err;
1018
1019   /* An operational errors in session-based protocols.  */
1020   gpgme_error_t op_err;
1021 };
1022 typedef struct gpgme_io_event_done_data *gpgme_io_event_done_data_t;
1023
1024 /* The type of a function that is called when a context finished an
1025    operation.  */
1026 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
1027                                      void *type_data);
1028
1029 struct gpgme_io_cbs
1030 {
1031   gpgme_register_io_cb_t add;
1032   void *add_priv;
1033   gpgme_remove_io_cb_t remove;
1034   gpgme_event_io_cb_t event;
1035   void *event_priv;
1036 };
1037 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
1038
1039 /* Set the I/O callback functions in CTX to IO_CBS.  */
1040 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
1041
1042 /* Get the current I/O callback functions.  */
1043 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
1044
1045 /* Wrappers around the internal I/O functions for use with
1046    gpgme_passphrase_cb_t and gpgme_interact_cb_t.  */
1047 @API__SSIZE_T@ gpgme_io_read (int fd, void *buffer, size_t count);
1048 @API__SSIZE_T@ gpgme_io_write (int fd, const void *buffer, size_t count);
1049 int     gpgme_io_writen (int fd, const void *buffer, size_t count);
1050
1051 /* Process the pending operation and, if HANG is non-zero, wait for
1052    the pending operation to finish.  */
1053 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
1054
1055 gpgme_ctx_t gpgme_wait_ext (gpgme_ctx_t ctx, gpgme_error_t *status,
1056                             gpgme_error_t *op_err, int hang);
1057
1058 /* Cancel a pending asynchronous operation.  */
1059 gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
1060
1061 /* Cancel a pending operation asynchronously.  */
1062 gpgme_error_t gpgme_cancel_async (gpgme_ctx_t ctx);
1063
1064
1065 \f
1066 /*
1067  * Functions to handle data objects.
1068  */
1069
1070 /* Read up to SIZE bytes into buffer BUFFER from the data object with
1071    the handle HANDLE.  Return the number of characters read, 0 on EOF
1072    and -1 on error.  If an error occurs, errno is set.  */
1073 typedef @API__SSIZE_T@ (*gpgme_data_read_cb_t) (void *handle, void *buffer,
1074                                          size_t size);
1075
1076 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1077    the handle HANDLE.  Return the number of characters written, or -1
1078    on error.  If an error occurs, errno is set.  */
1079 typedef @API__SSIZE_T@ (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
1080                                           size_t size);
1081
1082 /* Set the current position from where the next read or write starts
1083    in the data object with the handle HANDLE to OFFSET, relativ to
1084    WHENCE.  Returns the new offset in bytes from the beginning of the
1085    data object.  */
1086 typedef @API__OFF_T@ (*gpgme_data_seek_cb_t) (void *handle,
1087                                        @API__OFF_T@ offset, int whence);
1088
1089 /* Close the data object with the handle HANDLE.  */
1090 typedef void (*gpgme_data_release_cb_t) (void *handle);
1091
1092 struct gpgme_data_cbs
1093 {
1094   gpgme_data_read_cb_t read;
1095   gpgme_data_write_cb_t write;
1096   gpgme_data_seek_cb_t seek;
1097   gpgme_data_release_cb_t release;
1098 };
1099 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
1100
1101 /* Read up to SIZE bytes into buffer BUFFER from the data object with
1102    the handle DH.  Return the number of characters read, 0 on EOF and
1103    -1 on error.  If an error occurs, errno is set.  */
1104 @API__SSIZE_T@ gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
1105
1106 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1107    the handle DH.  Return the number of characters written, or -1 on
1108    error.  If an error occurs, errno is set.  */
1109 @API__SSIZE_T@ gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
1110
1111 /* Set the current position from where the next read or write starts
1112    in the data object with the handle DH to OFFSET, relativ to WHENCE.
1113    Returns the new offset in bytes from the beginning of the data
1114    object.  */
1115 @API__OFF_T@ gpgme_data_seek (gpgme_data_t dh, @API__OFF_T@ offset, int whence);
1116
1117 /* Create a new data buffer and return it in R_DH.  */
1118 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
1119
1120 /* Destroy the data buffer DH.  */
1121 void gpgme_data_release (gpgme_data_t dh);
1122
1123 /* Create a new data buffer filled with SIZE bytes starting from
1124    BUFFER.  If COPY is zero, copying is delayed until necessary, and
1125    the data is taken from the original location when needed.  */
1126 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
1127                                        const char *buffer, size_t size,
1128                                        int copy);
1129
1130 /* Destroy the data buffer DH and return a pointer to its content.
1131    The memory has be to released with gpgme_free() by the user.  It's
1132    size is returned in R_LEN.  */
1133 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
1134
1135 /* Release the memory returned by gpgme_data_release_and_get_mem() and
1136    some other functions.  */
1137 void gpgme_free (void *buffer);
1138
1139 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
1140                                        gpgme_data_cbs_t cbs,
1141                                        void *handle);
1142
1143 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
1144
1145 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
1146
1147 /* Return the encoding attribute of the data buffer DH */
1148 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
1149
1150 /* Set the encoding attribute of data buffer DH to ENC */
1151 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
1152                                        gpgme_data_encoding_t enc);
1153
1154 /* Get the file name associated with the data object with handle DH, or
1155    NULL if there is none.  */
1156 char *gpgme_data_get_file_name (gpgme_data_t dh);
1157
1158 /* Set the file name associated with the data object with handle DH to
1159    FILE_NAME.  */
1160 gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh,
1161                                         const char *file_name);
1162
1163 /* Set a flag for the data object DH.  See the manual for details.  */
1164 gpg_error_t gpgme_data_set_flag (gpgme_data_t dh,
1165                                  const char *name, const char *value);
1166
1167 /* Try to identify the type of the data in DH.  */
1168 gpgme_data_type_t gpgme_data_identify (gpgme_data_t dh, int reserved);
1169
1170
1171 /* Create a new data buffer filled with the content of file FNAME.
1172    COPY must be non-zero.  For delayed read, please use
1173    gpgme_data_new_from_fd or gpgme_data_new_from_stream instead.  */
1174 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
1175                                         const char *fname,
1176                                         int copy);
1177
1178 /* Create a new data buffer filled with LENGTH bytes starting from
1179    OFFSET within the file FNAME or stream FP (exactly one must be
1180    non-zero).  */
1181 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
1182                                             const char *fname, FILE *fp,
1183                                             @API__OFF_T@ offset, size_t length);
1184
1185 /* Convenience function to do a gpgme_data_seek (dh, 0, SEEK_SET).  */
1186 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh);
1187
1188
1189 \f
1190 /*
1191  * Key and trust functions.
1192  */
1193
1194 /* Get the key with the fingerprint FPR from the crypto backend.  If
1195    SECRET is true, get the secret key.  */
1196 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
1197                              gpgme_key_t *r_key, int secret);
1198
1199 /* Create a dummy key to specify an email address.  */
1200 gpgme_error_t gpgme_key_from_uid (gpgme_key_t *key, const char *name);
1201
1202 /* Acquire a reference to KEY.  */
1203 void gpgme_key_ref (gpgme_key_t key);
1204
1205 /* Release a reference to KEY.  If this was the last one the key is
1206    destroyed.  */
1207 void gpgme_key_unref (gpgme_key_t key);
1208 void gpgme_key_release (gpgme_key_t key);
1209
1210
1211 \f
1212 /*
1213  * Encryption.
1214  */
1215
1216 /* An object to return results from an encryption operation.
1217  * This structure shall be considered read-only and an application
1218  * must not allocate such a structure on its own.  */
1219 struct _gpgme_op_encrypt_result
1220 {
1221   /* The list of invalid recipients.  */
1222   gpgme_invalid_key_t invalid_recipients;
1223 };
1224 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
1225
1226 /* Retrieve a pointer to the result of the encrypt operation.  */
1227 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
1228
1229 /* The valid encryption flags.  */
1230 typedef enum
1231   {
1232     GPGME_ENCRYPT_ALWAYS_TRUST = 1,
1233     GPGME_ENCRYPT_NO_ENCRYPT_TO = 2,
1234     GPGME_ENCRYPT_PREPARE = 4,
1235     GPGME_ENCRYPT_EXPECT_SIGN = 8,
1236     GPGME_ENCRYPT_NO_COMPRESS = 16,
1237     GPGME_ENCRYPT_SYMMETRIC = 32
1238   }
1239 gpgme_encrypt_flags_t;
1240
1241 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1242    store the resulting ciphertext in CIPHER.  */
1243 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
1244                                       gpgme_encrypt_flags_t flags,
1245                                       gpgme_data_t plain, gpgme_data_t cipher);
1246 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1247                                 gpgme_encrypt_flags_t flags,
1248                                 gpgme_data_t plain, gpgme_data_t cipher);
1249
1250 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1251    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1252    with the signers in CTX.  */
1253 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1254                                            gpgme_key_t recp[],
1255                                            gpgme_encrypt_flags_t flags,
1256                                            gpgme_data_t plain,
1257                                            gpgme_data_t cipher);
1258 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1259                                      gpgme_encrypt_flags_t flags,
1260                                      gpgme_data_t plain, gpgme_data_t cipher);
1261
1262 \f
1263 /*
1264  * Decryption.
1265  */
1266
1267 /* An object to hold information about a recipient.
1268  * This structure shall be considered read-only and an application
1269  * must not allocate such a structure on its own.  */
1270 struct _gpgme_recipient
1271 {
1272   struct _gpgme_recipient *next;
1273
1274   /* The key ID of key for which the text was encrypted.  */
1275   char *keyid;
1276
1277   /* Internal to GPGME, do not use.  */
1278   char _keyid[16 + 1];
1279
1280   /* The public key algorithm of the recipient key.  */
1281   gpgme_pubkey_algo_t pubkey_algo;
1282
1283   /* The status of the recipient.  */
1284   gpgme_error_t status;
1285 };
1286 typedef struct _gpgme_recipient *gpgme_recipient_t;
1287
1288 /* An object to return results from a decryption operation.
1289  * This structure shall be considered read-only and an application
1290  * must not allocate such a structure on its own.  */
1291 struct _gpgme_op_decrypt_result
1292 {
1293   char *unsupported_algorithm;
1294
1295   /* Key should not have been used for encryption.  */
1296   unsigned int wrong_key_usage : 1;
1297
1298   /* Internal to GPGME, do not use.  */
1299   int _unused : 31;
1300
1301   gpgme_recipient_t recipients;
1302
1303   /* The original file name of the plaintext message, if
1304      available.  */
1305   char *file_name;
1306
1307   /* A textual representation of the session key used to decrypt the
1308    * message, if available */
1309   char *session_key;
1310 };
1311 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1312
1313 /* Retrieve a pointer to the result of the decrypt operation.  */
1314 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1315
1316 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1317    plaintext in PLAIN.  */
1318 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1319                                       gpgme_data_t plain);
1320 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1321                                 gpgme_data_t cipher, gpgme_data_t plain);
1322
1323 /* Decrypt ciphertext CIPHER and make a signature verification within
1324    CTX and store the resulting plaintext in PLAIN.  */
1325 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1326                                              gpgme_data_t cipher,
1327                                              gpgme_data_t plain);
1328 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1329                                        gpgme_data_t plain);
1330
1331 \f
1332 /*
1333  * Signing.
1334  */
1335
1336 /* An object with signatures data.
1337  * This structure shall be considered read-only and an application
1338  * must not allocate such a structure on its own.  */
1339 struct _gpgme_new_signature
1340 {
1341   struct _gpgme_new_signature *next;
1342
1343   /* The type of the signature.  */
1344   gpgme_sig_mode_t type;
1345
1346   /* The public key algorithm used to create the signature.  */
1347   gpgme_pubkey_algo_t pubkey_algo;
1348
1349   /* The hash algorithm used to create the signature.  */
1350   gpgme_hash_algo_t hash_algo;
1351
1352   /* Internal to GPGME, do not use.  Must be set to the same value as
1353      CLASS below.  */
1354   unsigned long _obsolete_class;
1355
1356   /* Signature creation time.  */
1357   long int timestamp;
1358
1359   /* The fingerprint of the signature.  */
1360   char *fpr;
1361
1362 #ifdef __cplusplus
1363   unsigned int _obsolete_class_2;
1364 #else
1365   /* Must be set to SIG_CLASS below.  */
1366   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME(0,4);
1367 #endif
1368
1369   /* Crypto backend specific signature class.  */
1370   unsigned int sig_class;
1371 };
1372 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1373
1374
1375 /* An object to return results from a signing operation.
1376  * This structure shall be considered read-only and an application
1377  * must not allocate such a structure on its own.  */
1378 struct _gpgme_op_sign_result
1379 {
1380   /* The list of invalid signers.  */
1381   gpgme_invalid_key_t invalid_signers;
1382   gpgme_new_signature_t signatures;
1383 };
1384 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1385
1386 /* Retrieve a pointer to the result of the signing operation.  */
1387 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1388
1389 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1390 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1391                                    gpgme_data_t plain, gpgme_data_t sig,
1392                                    gpgme_sig_mode_t mode);
1393 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1394                              gpgme_data_t plain, gpgme_data_t sig,
1395                              gpgme_sig_mode_t mode);
1396
1397 \f
1398 /*
1399  * Verify.
1400  */
1401
1402 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1403 typedef enum
1404   {
1405     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1406     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1407     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1408     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1409     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1410     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1411     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1412     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1413     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1414     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1415     GPGME_SIGSUM_SYS_ERROR   = 0x0800,  /* A system error occurred.  */
1416     GPGME_SIGSUM_TOFU_CONFLICT=0x1000   /* Tofu conflict detected.  */
1417   }
1418 gpgme_sigsum_t;
1419
1420
1421 /* An object to hold the verification status of a signature.
1422  * This structure shall be considered read-only and an application
1423  * must not allocate such a structure on its own.  */
1424 struct _gpgme_signature
1425 {
1426   struct _gpgme_signature *next;
1427
1428   /* A summary of the signature status.  */
1429   gpgme_sigsum_t summary;
1430
1431   /* The fingerprint of the signature.  This can be a subkey.  */
1432   char *fpr;
1433
1434   /* The status of the signature.  */
1435   gpgme_error_t status;
1436
1437   /* Notation data and policy URLs.  */
1438   gpgme_sig_notation_t notations;
1439
1440   /* Signature creation time.  */
1441   unsigned long timestamp;
1442
1443   /* Signature expiration time or 0.  */
1444   unsigned long exp_timestamp;
1445
1446   /* Key should not have been used for signing.  */
1447   unsigned int wrong_key_usage : 1;
1448
1449   /* PKA status: 0 = not available, 1 = bad, 2 = okay, 3 = RFU. */
1450   unsigned int pka_trust : 2;
1451
1452   /* Validity has been verified using the chain model. */
1453   unsigned int chain_model : 1;
1454
1455   /* Internal to GPGME, do not use.  */
1456   int _unused : 28;
1457
1458   gpgme_validity_t validity;
1459   gpgme_error_t validity_reason;
1460
1461   /* The public key algorithm used to create the signature.  */
1462   gpgme_pubkey_algo_t pubkey_algo;
1463
1464   /* The hash algorithm used to create the signature.  */
1465   gpgme_hash_algo_t hash_algo;
1466
1467   /* The mailbox from the PKA information or NULL. */
1468   char *pka_address;
1469
1470   /* If non-NULL, a possible incomplete key object with the data
1471    * available for the signature.  */
1472   gpgme_key_t key;
1473 };
1474 typedef struct _gpgme_signature *gpgme_signature_t;
1475
1476 /* An object to return the results of a verify operation.
1477  * This structure shall be considered read-only and an application
1478  * must not allocate such a structure on its own.  */
1479 struct _gpgme_op_verify_result
1480 {
1481   gpgme_signature_t signatures;
1482
1483   /* The original file name of the plaintext message, if
1484      available.  */
1485   char *file_name;
1486 };
1487 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1488
1489 /* Retrieve a pointer to the result of the verify operation.  */
1490 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1491
1492 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1493 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1494                                      gpgme_data_t signed_text,
1495                                      gpgme_data_t plaintext);
1496 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1497                                gpgme_data_t signed_text,
1498                                gpgme_data_t plaintext);
1499
1500 \f
1501 /*
1502  * Import/Export
1503  */
1504
1505 #define GPGME_IMPORT_NEW        1  /* The key was new.  */
1506 #define GPGME_IMPORT_UID        2  /* The key contained new user IDs.  */
1507 #define GPGME_IMPORT_SIG        4  /* The key contained new signatures.  */
1508 #define GPGME_IMPORT_SUBKEY     8  /* The key contained new sub keys.  */
1509 #define GPGME_IMPORT_SECRET    16  /* The key contained a secret key.  */
1510
1511
1512 /* An object to hold results for one imported key.
1513  * This structure shall be considered read-only and an application
1514  * must not allocate such a structure on its own.  */
1515 struct _gpgme_import_status
1516 {
1517   struct _gpgme_import_status *next;
1518
1519   /* Fingerprint.  */
1520   char *fpr;
1521
1522   /* If a problem occurred, the reason why the key could not be
1523      imported.  Otherwise GPGME_No_Error.  */
1524   gpgme_error_t result;
1525
1526   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1527      ORed.  0 means the key was already known and no new components
1528      have been added.  */
1529   unsigned int status;
1530 };
1531 typedef struct _gpgme_import_status *gpgme_import_status_t;
1532
1533 /* Import result object.
1534  * This structure shall be considered read-only and an application
1535  * must not allocate such a structure on its own.  */
1536 struct _gpgme_op_import_result
1537 {
1538   /* Number of considered keys.  */
1539   int considered;
1540
1541   /* Keys without user ID.  */
1542   int no_user_id;
1543
1544   /* Imported keys.  */
1545   int imported;
1546
1547   /* Imported RSA keys.  */
1548   int imported_rsa;
1549
1550   /* Unchanged keys.  */
1551   int unchanged;
1552
1553   /* Number of new user ids.  */
1554   int new_user_ids;
1555
1556   /* Number of new sub keys.  */
1557   int new_sub_keys;
1558
1559   /* Number of new signatures.  */
1560   int new_signatures;
1561
1562   /* Number of new revocations.  */
1563   int new_revocations;
1564
1565   /* Number of secret keys read.  */
1566   int secret_read;
1567
1568   /* Number of secret keys imported.  */
1569   int secret_imported;
1570
1571   /* Number of secret keys unchanged.  */
1572   int secret_unchanged;
1573
1574   /* Number of new keys skipped.  */
1575   int skipped_new_keys;
1576
1577   /* Number of keys not imported.  */
1578   int not_imported;
1579
1580   /* List of keys for which an import was attempted.  */
1581   gpgme_import_status_t imports;
1582 };
1583 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1584
1585 /* Retrieve a pointer to the result of the import operation.  */
1586 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1587
1588 /* Import the key in KEYDATA into the keyring.  */
1589 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1590 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1591
1592 /* Import the keys from the array KEYS into the keyring.  */
1593 gpgme_error_t gpgme_op_import_keys_start (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1594 gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1595
1596
1597 /* Export the keys found by PATTERN into KEYDATA.  */
1598 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1599                                      gpgme_export_mode_t mode,
1600                                      gpgme_data_t keydata);
1601 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1602                                gpgme_export_mode_t mode,
1603                                gpgme_data_t keydata);
1604
1605 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1606                                          const char *pattern[],
1607                                          gpgme_export_mode_t mode,
1608                                          gpgme_data_t keydata);
1609 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1610                                    gpgme_export_mode_t mode,
1611                                    gpgme_data_t keydata);
1612
1613 /* Export the keys from the array KEYS into KEYDATA.  */
1614 gpgme_error_t gpgme_op_export_keys_start (gpgme_ctx_t ctx,
1615                                           gpgme_key_t keys[],
1616                                           gpgme_export_mode_t mode,
1617                                           gpgme_data_t keydata);
1618 gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t ctx,
1619                                     gpgme_key_t keys[],
1620                                     gpgme_export_mode_t mode,
1621                                     gpgme_data_t keydata);
1622
1623
1624 \f
1625 /*
1626  * Key generation.
1627  */
1628
1629 /* Flags for the key creation functions.  */
1630 #define GPGME_CREATE_SIGN       (1 << 0)  /* Allow usage: signing.     */
1631 #define GPGME_CREATE_ENCR       (1 << 1)  /* Allow usage: encryption.  */
1632 #define GPGME_CREATE_CERT       (1 << 2)  /* Allow usage: certification.  */
1633 #define GPGME_CREATE_AUTH       (1 << 3)  /* Allow usage: authentication.  */
1634 #define GPGME_CREATE_NOPASSWD   (1 << 7)  /* Create w/o passphrase.    */
1635 #define GPGME_CREATE_SELFSIGNED (1 << 8)  /* Create self-signed cert.  */
1636 #define GPGME_CREATE_NOSTORE    (1 << 9)  /* Do not store the key.     */
1637 #define GPGME_CREATE_WANTPUB    (1 << 10) /* Return the public key.    */
1638 #define GPGME_CREATE_WANTSEC    (1 << 11) /* Return the secret key.    */
1639 #define GPGME_CREATE_FORCE      (1 << 12) /* Force creation.           */
1640 #define GPGME_CREATE_NOEXPIRE   (1 << 13) /* Create w/o expiration.    */
1641
1642 /* An object to return result from a key generation.
1643  * This structure shall be considered read-only and an application
1644  * must not allocate such a structure on its own.  */
1645 struct _gpgme_op_genkey_result
1646 {
1647   /* A primary key was generated.  */
1648   unsigned int primary : 1;
1649
1650   /* A sub key was generated.  */
1651   unsigned int sub : 1;
1652
1653   /* A user id was generated.  */
1654   unsigned int uid : 1;
1655
1656   /* Internal to GPGME, do not use.  */
1657   unsigned int _unused : 29;
1658
1659   /* The fingerprint of the generated key.  */
1660   char *fpr;
1661
1662   /* A memory data object with the created public key.  Only set when
1663    * GPGME_CREATE_WANTPUB has been used. */
1664   gpgme_data_t pubkey;
1665
1666   /* A memory data object with the created secret key.  Only set when
1667    * GPGME_CREATE_WANTSEC has been used. */
1668   gpgme_data_t seckey;
1669 };
1670 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1671
1672 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1673    SECKEY should be null for now.  PARMS specifies what keys should be
1674    generated.  */
1675 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1676                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1677 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1678                                gpgme_data_t pubkey, gpgme_data_t seckey);
1679
1680 /* Generate a key pair using the modern interface.  */
1681 gpgme_error_t gpgme_op_createkey_start (gpgme_ctx_t ctx,
1682                                         const char *userid,
1683                                         const char *algo,
1684                                         unsigned long reserved,
1685                                         unsigned long expires,
1686                                         gpgme_key_t certkey,
1687                                         unsigned int flags);
1688 gpgme_error_t gpgme_op_createkey       (gpgme_ctx_t ctx,
1689                                         const char *userid,
1690                                         const char *algo,
1691                                         unsigned long reserved,
1692                                         unsigned long expires,
1693                                         gpgme_key_t certkey,
1694                                         unsigned int flags);
1695 /* Add a new subkey to KEY.  */
1696 gpgme_error_t gpgme_op_createsubkey_start (gpgme_ctx_t ctx,
1697                                            gpgme_key_t key,
1698                                            const char *algo,
1699                                            unsigned long reserved,
1700                                            unsigned long expires,
1701                                            unsigned int flags);
1702 gpgme_error_t gpgme_op_createsubkey       (gpgme_ctx_t ctx,
1703                                            gpgme_key_t key,
1704                                            const char *algo,
1705                                            unsigned long reserved,
1706                                            unsigned long expires,
1707                                            unsigned int flags);
1708
1709 /* Add USERID to an existing KEY.  */
1710 gpgme_error_t gpgme_op_adduid_start (gpgme_ctx_t ctx,
1711                                      gpgme_key_t key, const char *userid,
1712                                      unsigned int reserved);
1713 gpgme_error_t gpgme_op_adduid       (gpgme_ctx_t ctx,
1714                                      gpgme_key_t key, const char *userid,
1715                                      unsigned int reserved);
1716
1717 /* Revoke a USERID from a KEY.  */
1718 gpgme_error_t gpgme_op_revuid_start (gpgme_ctx_t ctx,
1719                                      gpgme_key_t key, const char *userid,
1720                                      unsigned int reserved);
1721 gpgme_error_t gpgme_op_revuid       (gpgme_ctx_t ctx,
1722                                      gpgme_key_t key, const char *userid,
1723                                      unsigned int reserved);
1724
1725
1726
1727 /* Retrieve a pointer to the result of a genkey, createkey, or
1728  * createsubkey operation.  */
1729 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1730
1731
1732 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1733    keys are also deleted.  */
1734 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1735                                      int allow_secret);
1736 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1737                                int allow_secret);
1738
1739 \f
1740 /*
1741  * Key signing interface
1742  */
1743
1744 /* Flags for the key signing functions.  */
1745 #define GPGME_KEYSIGN_LOCAL     (1 << 7)  /* Create a local signature.  */
1746 #define GPGME_KEYSIGN_LFSEP     (1 << 8)  /* Indicate LF separated user ids. */
1747 #define GPGME_KEYSIGN_NOEXPIRE  (1 << 9)  /* Force no expiration.  */
1748
1749
1750 /* Sign the USERID of KEY using the current set of signers.  */
1751 gpgme_error_t gpgme_op_keysign_start (gpgme_ctx_t ctx,
1752                                       gpgme_key_t key, const char *userid,
1753                                       unsigned long expires,
1754                                       unsigned int flags);
1755 gpgme_error_t gpgme_op_keysign       (gpgme_ctx_t ctx,
1756                                       gpgme_key_t key, const char *userid,
1757                                       unsigned long expires,
1758                                       unsigned int flags);
1759
1760
1761
1762 \f
1763 /*
1764  * Key edit interface
1765  */
1766
1767 /* Flags to select the mode of the interact.  */
1768 #define GPGME_INTERACT_CARD   (1 << 0)  /* Use --card-edit mode. */
1769
1770
1771 /* Edit the KEY.  Send status and command requests to FNC and
1772    output of edit commands to OUT.  */
1773 gpgme_error_t gpgme_op_interact_start (gpgme_ctx_t ctx,
1774                                        gpgme_key_t key,
1775                                        unsigned int flags,
1776                                        gpgme_interact_cb_t fnc,
1777                                        void *fnc_value,
1778                                        gpgme_data_t out);
1779 gpgme_error_t gpgme_op_interact (gpgme_ctx_t ctx, gpgme_key_t key,
1780                                  unsigned int flags,
1781                                  gpgme_interact_cb_t fnc,
1782                                  void *fnc_value,
1783                                  gpgme_data_t out);
1784
1785
1786 /* Set the Tofu policy of KEY to POLCIY.  */
1787 gpgme_error_t gpgme_op_tofu_policy_start (gpgme_ctx_t ctx,
1788                                           gpgme_key_t key,
1789                                           gpgme_tofu_policy_t policy);
1790 gpgme_error_t gpgme_op_tofu_policy       (gpgme_ctx_t ctx,
1791                                           gpgme_key_t key,
1792                                           gpgme_tofu_policy_t policy);
1793
1794
1795
1796 \f
1797 /*
1798  * Key listing
1799  */
1800
1801 /* An object to return results from a key listing operation.
1802  * This structure shall be considered read-only and an application
1803  * must not allocate such a structure on its own.  */
1804 struct _gpgme_op_keylist_result
1805 {
1806   unsigned int truncated : 1;
1807
1808   /* Internal to GPGME, do not use.  */
1809   unsigned int _unused : 31;
1810 };
1811 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
1812
1813 /* Retrieve a pointer to the result of the key listing operation.  */
1814 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
1815
1816 /* Start a keylist operation within CTX, searching for keys which
1817    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1818    returned.  */
1819 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
1820                                       int secret_only);
1821 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
1822                                           const char *pattern[],
1823                                           int secret_only, int reserved);
1824
1825 /* Return the next key from the keylist in R_KEY.  */
1826 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
1827
1828 /* Terminate a pending keylist operation within CTX.  */
1829 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
1830
1831 /* Change the passphrase for KEY.  FLAGS is reserved for future use
1832    and must be passed as 0.  */
1833 gpgme_error_t gpgme_op_passwd_start (gpgme_ctx_t ctx, gpgme_key_t key,
1834                                      unsigned int flags);
1835 gpgme_error_t gpgme_op_passwd (gpgme_ctx_t ctx, gpgme_key_t key,
1836                                unsigned int flags);
1837
1838
1839 \f
1840 /*
1841  * Trust items and operations.
1842  */
1843
1844 /* An object to hold data of a trust item.
1845  * This structure shall be considered read-only and an application
1846  * must not allocate such a structure on its own.  */
1847 struct _gpgme_trust_item
1848 {
1849   /* Internal to GPGME, do not use.  */
1850   unsigned int _refs;
1851
1852   /* The key ID to which the trust item belongs.  */
1853   char *keyid;
1854
1855   /* Internal to GPGME, do not use.  */
1856   char _keyid[16 + 1];
1857
1858   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1859   int type;
1860
1861   /* The trust level.  */
1862   int level;
1863
1864   /* The owner trust if TYPE is 1.  */
1865   char *owner_trust;
1866
1867   /* Internal to GPGME, do not use.  */
1868   char _owner_trust[2];
1869
1870   /* The calculated validity.  */
1871   char *validity;
1872
1873   /* Internal to GPGME, do not use.  */
1874   char _validity[2];
1875
1876   /* The user name if TYPE is 2.  */
1877   char *name;
1878 };
1879 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
1880
1881 /* Start a trustlist operation within CTX, searching for trust items
1882    which match PATTERN.  */
1883 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
1884                                         const char *pattern, int max_level);
1885
1886 /* Return the next trust item from the trustlist in R_ITEM.  */
1887 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
1888                                        gpgme_trust_item_t *r_item);
1889
1890 /* Terminate a pending trustlist operation within CTX.  */
1891 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
1892
1893 /* Acquire a reference to ITEM.  */
1894 void gpgme_trust_item_ref (gpgme_trust_item_t item);
1895
1896 /* Release a reference to ITEM.  If this was the last one the trust
1897    item is destroyed.  */
1898 void gpgme_trust_item_unref (gpgme_trust_item_t item);
1899
1900
1901 \f
1902 /*
1903  * Audit log
1904  */
1905
1906 /* Return the auditlog for the current session.  This may be called
1907    after a successful or failed operation.  If no audit log is
1908    available GPG_ERR_NO_DATA is returned.  */
1909 gpgme_error_t gpgme_op_getauditlog_start (gpgme_ctx_t ctx, gpgme_data_t output,
1910                                           unsigned int flags);
1911 gpgme_error_t gpgme_op_getauditlog (gpgme_ctx_t ctx, gpgme_data_t output,
1912                                     unsigned int flags);
1913
1914
1915 \f
1916 /*
1917  * Spawn interface
1918  */
1919
1920 /* Flags for the spawn operations.  */
1921 #define GPGME_SPAWN_DETACHED      1
1922 #define GPGME_SPAWN_ALLOW_SET_FG  2
1923
1924
1925 /* Run the command FILE with the arguments in ARGV.  Connect stdin to
1926    DATAIN, stdout to DATAOUT, and STDERR to DATAERR.  If one the data
1927    streams is NULL, connect to /dev/null instead.  */
1928 gpgme_error_t gpgme_op_spawn_start (gpgme_ctx_t ctx,
1929                                     const char *file, const char *argv[],
1930                                     gpgme_data_t datain,
1931                                     gpgme_data_t dataout, gpgme_data_t dataerr,
1932                                     unsigned int flags);
1933 gpgme_error_t gpgme_op_spawn (gpgme_ctx_t ctx,
1934                               const char *file, const char *argv[],
1935                               gpgme_data_t datain,
1936                               gpgme_data_t dataout, gpgme_data_t dataerr,
1937                               unsigned int flags);
1938
1939 \f
1940 /*
1941  * Low-level Assuan protocol access.
1942  */
1943 typedef gpgme_error_t (*gpgme_assuan_data_cb_t)
1944      (void *opaque, const void *data, size_t datalen);
1945
1946 typedef gpgme_error_t (*gpgme_assuan_inquire_cb_t)
1947      (void *opaque, const char *name, const char *args,
1948       gpgme_data_t *r_data);
1949
1950 typedef gpgme_error_t (*gpgme_assuan_status_cb_t)
1951      (void *opaque, const char *status, const char *args);
1952
1953 /* Send the Assuan COMMAND and return results via the callbacks.
1954    Asynchronous variant. */
1955 gpgme_error_t gpgme_op_assuan_transact_start (gpgme_ctx_t ctx,
1956                                               const char *command,
1957                                               gpgme_assuan_data_cb_t data_cb,
1958                                               void *data_cb_value,
1959                                               gpgme_assuan_inquire_cb_t inq_cb,
1960                                               void *inq_cb_value,
1961                                               gpgme_assuan_status_cb_t stat_cb,
1962                                               void *stat_cb_value);
1963
1964 /* Send the Assuan COMMAND and return results via the callbacks.
1965    Synchronous variant. */
1966 gpgme_error_t gpgme_op_assuan_transact_ext (gpgme_ctx_t ctx,
1967                                             const char *command,
1968                                             gpgme_assuan_data_cb_t data_cb,
1969                                             void *data_cb_value,
1970                                             gpgme_assuan_inquire_cb_t inq_cb,
1971                                             void *inq_cb_value,
1972                                             gpgme_assuan_status_cb_t stat_cb,
1973                                             void *stat_cb_value,
1974                                             gpgme_error_t *op_err);
1975
1976 \f
1977 /*
1978  * Crypto container support.
1979  */
1980
1981 /* An object to return results from a VFS mount operation.
1982  * This structure shall be considered read-only and an application
1983  * must not allocate such a structure on its own.  */
1984 struct _gpgme_op_vfs_mount_result
1985 {
1986   char *mount_dir;
1987 };
1988 typedef struct _gpgme_op_vfs_mount_result *gpgme_vfs_mount_result_t;
1989
1990 gpgme_vfs_mount_result_t gpgme_op_vfs_mount_result (gpgme_ctx_t ctx);
1991
1992 /* The container is automatically unmounted when the context is reset
1993    or destroyed.  Transmission errors are returned directly,
1994    operational errors are returned in OP_ERR.  */
1995 gpgme_error_t gpgme_op_vfs_mount (gpgme_ctx_t ctx, const char *container_file,
1996                                   const char *mount_dir, unsigned int flags,
1997                                   gpgme_error_t *op_err);
1998
1999 gpgme_error_t gpgme_op_vfs_create (gpgme_ctx_t ctx, gpgme_key_t recp[],
2000                                    const char *container_file,
2001                                    unsigned int flags, gpgme_error_t *op_err);
2002
2003 \f
2004 /*
2005  * Interface to gpgconf(1).
2006  */
2007
2008 /* The expert level at which a configuration option or group of
2009    options should be displayed.  See the gpgconf(1) documentation for
2010    more details.  */
2011 typedef enum
2012   {
2013     GPGME_CONF_BASIC = 0,
2014     GPGME_CONF_ADVANCED = 1,
2015     GPGME_CONF_EXPERT = 2,
2016     GPGME_CONF_INVISIBLE = 3,
2017     GPGME_CONF_INTERNAL = 4
2018   }
2019 gpgme_conf_level_t;
2020
2021
2022 /* The data type of a configuration option argument.  See the gpgconf(1)
2023    documentation for more details.  */
2024 typedef enum
2025   {
2026     /* Basic types.  */
2027     GPGME_CONF_NONE = 0,
2028     GPGME_CONF_STRING = 1,
2029     GPGME_CONF_INT32 = 2,
2030     GPGME_CONF_UINT32 = 3,
2031
2032     /* Complex types.  */
2033     GPGME_CONF_FILENAME = 32,
2034     GPGME_CONF_LDAP_SERVER = 33,
2035     GPGME_CONF_KEY_FPR = 34,
2036     GPGME_CONF_PUB_KEY = 35,
2037     GPGME_CONF_SEC_KEY = 36,
2038     GPGME_CONF_ALIAS_LIST = 37
2039   }
2040 gpgme_conf_type_t;
2041
2042 /* For now, compatibility.  */
2043 #define GPGME_CONF_PATHNAME GPGME_CONF_FILENAME
2044
2045
2046 /* This represents a single argument for a configuration option.
2047    Which of the members of value is used depends on the ALT_TYPE.  */
2048 typedef struct gpgme_conf_arg
2049 {
2050   struct gpgme_conf_arg *next;
2051   /* True if the option appears without an (optional) argument.  */
2052   unsigned int no_arg;
2053   union
2054   {
2055     unsigned int count;
2056     unsigned int uint32;
2057     int int32;
2058     char *string;
2059   } value;
2060 } *gpgme_conf_arg_t;
2061
2062
2063 /* The flags of a configuration option.  See the gpgconf
2064    documentation for details.  */
2065 #define GPGME_CONF_GROUP        (1 << 0)
2066 #define GPGME_CONF_OPTIONAL     (1 << 1)
2067 #define GPGME_CONF_LIST         (1 << 2)
2068 #define GPGME_CONF_RUNTIME      (1 << 3)
2069 #define GPGME_CONF_DEFAULT      (1 << 4)
2070 #define GPGME_CONF_DEFAULT_DESC (1 << 5)
2071 #define GPGME_CONF_NO_ARG_DESC  (1 << 6)
2072 #define GPGME_CONF_NO_CHANGE    (1 << 7)
2073
2074
2075 /* The representation of a single configuration option.  See the
2076    gpg-conf documentation for details.  */
2077 typedef struct gpgme_conf_opt
2078 {
2079   struct gpgme_conf_opt *next;
2080
2081   /* The option name.  */
2082   char *name;
2083
2084   /* The flags for this option.  */
2085   unsigned int flags;
2086
2087   /* The level of this option.  */
2088   gpgme_conf_level_t level;
2089
2090   /* The localized description of this option.  */
2091   char *description;
2092
2093   /* The type and alternate type of this option.  */
2094   gpgme_conf_type_t type;
2095   gpgme_conf_type_t alt_type;
2096
2097   /* The localized (short) name of the argument, if any.  */
2098   char *argname;
2099
2100   /* The default value.  */
2101   gpgme_conf_arg_t default_value;
2102   char *default_description;
2103
2104   /* The default value if the option is not set.  */
2105   gpgme_conf_arg_t no_arg_value;
2106   char *no_arg_description;
2107
2108   /* The current value if the option is set.  */
2109   gpgme_conf_arg_t value;
2110
2111   /* The new value, if any.  NULL means reset to default.  */
2112   int change_value;
2113   gpgme_conf_arg_t new_value;
2114
2115   /* Free for application use.  */
2116   void *user_data;
2117 } *gpgme_conf_opt_t;
2118
2119
2120 /* The representation of a component that can be configured.  See the
2121    gpg-conf documentation for details.  */
2122 typedef struct gpgme_conf_comp
2123 {
2124   struct gpgme_conf_comp *next;
2125
2126   /* Internal to GPGME, do not use!  */
2127   gpgme_conf_opt_t *_last_opt_p;
2128
2129   /* The component name.  */
2130   char *name;
2131
2132   /* A human-readable description for the component.  */
2133   char *description;
2134
2135   /* The program name (an absolute path to the program).  */
2136   char *program_name;
2137
2138   /* A linked list of options for this component.  */
2139   struct gpgme_conf_opt *options;
2140 } *gpgme_conf_comp_t;
2141
2142
2143 /* Allocate a new gpgme_conf_arg_t.  If VALUE is NULL, a "no arg
2144    default" is prepared.  If type is a string type, VALUE should point
2145    to the string.  Else, it should point to an unsigned or signed
2146    integer respectively.  */
2147 gpgme_error_t gpgme_conf_arg_new (gpgme_conf_arg_t *arg_p,
2148                                   gpgme_conf_type_t type, const void *value);
2149
2150 /* This also releases all chained argument structures!  */
2151 void gpgme_conf_arg_release (gpgme_conf_arg_t arg, gpgme_conf_type_t type);
2152
2153 /* Register a change for the value of OPT to ARG.  If RESET is 1 (do
2154    not use any values but 0 or 1), ARG is ignored and the option is
2155    not changed (reverting a previous change).  Otherwise, if ARG is
2156    NULL, the option is cleared or reset to its default. The change
2157    is done with gpgconf's --runtime option to immediately take effect. */
2158 gpgme_error_t gpgme_conf_opt_change (gpgme_conf_opt_t opt, int reset,
2159                                      gpgme_conf_arg_t arg);
2160
2161 /* Release a set of configurations.  */
2162 void gpgme_conf_release (gpgme_conf_comp_t conf);
2163
2164 /* Retrieve the current configurations.  */
2165 gpgme_error_t gpgme_op_conf_load (gpgme_ctx_t ctx, gpgme_conf_comp_t *conf_p);
2166
2167 /* Save the configuration of component comp.  This function does not
2168    follow chained components!  */
2169 gpgme_error_t gpgme_op_conf_save (gpgme_ctx_t ctx, gpgme_conf_comp_t comp);
2170
2171
2172 /* Information about software versions.
2173  * This structure shall be considered read-only and an application
2174  * must not allocate such a structure on its own.  */
2175 typedef struct _gpgme_op_query_swdb_result
2176 {
2177   /* RFU */
2178   struct _gpgme_op_query_swdb_result *next;
2179
2180   /* The name of the package (e.g. "gpgme", "gnupg") */
2181   char *name;
2182
2183   /* The version number of the installed version.  */
2184   char *iversion;
2185
2186   /* The time the online info was created.  */
2187   unsigned long created;
2188
2189   /* The time the online info was retrieved.  */
2190   unsigned long retrieved;
2191
2192   /* This bit is set if an error occured or some of the information
2193    * in this structure may not be set.  */
2194   unsigned int warning : 1;
2195
2196   /* An update is available.  */
2197   unsigned int update : 1;
2198
2199   /* The update is important.  */
2200   unsigned int urgent : 1;
2201
2202   /* No information at all available.  */
2203   unsigned int noinfo : 1;
2204
2205   /* The package name is not known. */
2206   unsigned int unknown : 1;
2207
2208   /* The information here is too old.  */
2209   unsigned int tooold : 1;
2210
2211   /* Other error.  */
2212   unsigned int error : 1;
2213
2214   unsigned int _reserved : 25;
2215
2216   /* The version number of the latest released version.  */
2217   char *version;
2218
2219   /* The release date of that version.  */
2220   unsigned long reldate;
2221
2222 } *gpgme_query_swdb_result_t;
2223
2224
2225 /* Run the gpgconf --query-swdb command.  */
2226 gpgme_error_t gpgme_op_query_swdb (gpgme_ctx_t ctx,
2227                                    const char *name, const char *iversion,
2228                                    unsigned int reserved);
2229
2230 /* Return the result from the last query_swdb operation.  */
2231 gpgme_query_swdb_result_t gpgme_op_query_swdb_result (gpgme_ctx_t ctx);
2232
2233
2234
2235 \f
2236 /*
2237  * Various functions.
2238  */
2239
2240 /* Set special global flags; consult the manual before use.  */
2241 int gpgme_set_global_flag (const char *name, const char *value);
2242
2243 /* Check that the library fulfills the version requirement.  Note:
2244    This is here only for the case where a user takes a pointer from
2245    the old version of this function.  The new version and macro for
2246    run-time checks are below.  */
2247 const char *gpgme_check_version (const char *req_version);
2248
2249 /* Check that the library fulfills the version requirement and check
2250    for struct layout mismatch involving bitfields.  */
2251 const char *gpgme_check_version_internal (const char *req_version,
2252                                           size_t offset_sig_validity);
2253
2254 #define gpgme_check_version(req_version)                                \
2255   gpgme_check_version_internal (req_version,                            \
2256                                 offsetof (struct _gpgme_signature, validity))
2257
2258 /* Return the default values for various directories.  */
2259 const char *gpgme_get_dirinfo (const char *what);
2260
2261 /* Get the information about the configured and installed engines.  A
2262    pointer to the first engine in the statically allocated linked list
2263    is returned in *INFO.  If an error occurs, it is returned.  The
2264    returned data is valid until the next gpgme_set_engine_info.  */
2265 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
2266
2267 /* Set the default engine info for the protocol PROTO to the file name
2268    FILE_NAME and the home directory HOME_DIR.  */
2269 gpgme_error_t gpgme_set_engine_info (gpgme_protocol_t proto,
2270                                      const char *file_name,
2271                                      const char *home_dir);
2272
2273 /* Verify that the engine implementing PROTO is installed and
2274    available.  */
2275 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
2276
2277
2278 /* Reference counting for result objects.  */
2279 void gpgme_result_ref (void *result);
2280 void gpgme_result_unref (void *result);
2281
2282 /* Return a public key algorithm string (e.g. "rsa2048").  Caller must
2283    free using gpgme_free.  */
2284 char *gpgme_pubkey_algo_string (gpgme_subkey_t subkey);
2285
2286 /* Return a statically allocated string with the name of the public
2287    key algorithm ALGO, or NULL if that name is not known.  */
2288 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
2289
2290 /* Return a statically allocated string with the name of the hash
2291    algorithm ALGO, or NULL if that name is not known.  */
2292 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
2293
2294 /* Return the addr-spec from a user id.  Caller must free the result
2295  * with gpgme_free. */
2296 char *gpgme_addrspec_from_uid (const char *uid);
2297
2298
2299 \f
2300 /*
2301  * Deprecated types, constants and functions.
2302  */
2303
2304 /* The possible stati for gpgme_op_edit.  The use of that function and
2305  * these status codes are deprecated in favor of gpgme_op_interact. */
2306 typedef enum
2307   {
2308     GPGME_STATUS_EOF = 0,
2309     /* mkstatus processing starts here */
2310     GPGME_STATUS_ENTER = 1,
2311     GPGME_STATUS_LEAVE = 2,
2312     GPGME_STATUS_ABORT = 3,
2313
2314     GPGME_STATUS_GOODSIG = 4,
2315     GPGME_STATUS_BADSIG = 5,
2316     GPGME_STATUS_ERRSIG = 6,
2317
2318     GPGME_STATUS_BADARMOR = 7,
2319
2320     GPGME_STATUS_RSA_OR_IDEA = 8,      /* (legacy) */
2321     GPGME_STATUS_KEYEXPIRED = 9,
2322     GPGME_STATUS_KEYREVOKED = 10,
2323
2324     GPGME_STATUS_TRUST_UNDEFINED = 11,
2325     GPGME_STATUS_TRUST_NEVER = 12,
2326     GPGME_STATUS_TRUST_MARGINAL = 13,
2327     GPGME_STATUS_TRUST_FULLY = 14,
2328     GPGME_STATUS_TRUST_ULTIMATE = 15,
2329
2330     GPGME_STATUS_SHM_INFO = 16,        /* (legacy) */
2331     GPGME_STATUS_SHM_GET = 17,         /* (legacy) */
2332     GPGME_STATUS_SHM_GET_BOOL = 18,    /* (legacy) */
2333     GPGME_STATUS_SHM_GET_HIDDEN = 19,  /* (legacy) */
2334
2335     GPGME_STATUS_NEED_PASSPHRASE = 20,
2336     GPGME_STATUS_VALIDSIG = 21,
2337     GPGME_STATUS_SIG_ID = 22,
2338     GPGME_STATUS_ENC_TO = 23,
2339     GPGME_STATUS_NODATA = 24,
2340     GPGME_STATUS_BAD_PASSPHRASE = 25,
2341     GPGME_STATUS_NO_PUBKEY = 26,
2342     GPGME_STATUS_NO_SECKEY = 27,
2343     GPGME_STATUS_NEED_PASSPHRASE_SYM = 28,
2344     GPGME_STATUS_DECRYPTION_FAILED = 29,
2345     GPGME_STATUS_DECRYPTION_OKAY = 30,
2346     GPGME_STATUS_MISSING_PASSPHRASE = 31,
2347     GPGME_STATUS_GOOD_PASSPHRASE = 32,
2348     GPGME_STATUS_GOODMDC = 33,
2349     GPGME_STATUS_BADMDC = 34,
2350     GPGME_STATUS_ERRMDC = 35,
2351     GPGME_STATUS_IMPORTED = 36,
2352     GPGME_STATUS_IMPORT_OK = 37,
2353     GPGME_STATUS_IMPORT_PROBLEM = 38,
2354     GPGME_STATUS_IMPORT_RES = 39,
2355     GPGME_STATUS_FILE_START = 40,
2356     GPGME_STATUS_FILE_DONE = 41,
2357     GPGME_STATUS_FILE_ERROR = 42,
2358
2359     GPGME_STATUS_BEGIN_DECRYPTION = 43,
2360     GPGME_STATUS_END_DECRYPTION = 44,
2361     GPGME_STATUS_BEGIN_ENCRYPTION = 45,
2362     GPGME_STATUS_END_ENCRYPTION = 46,
2363
2364     GPGME_STATUS_DELETE_PROBLEM = 47,
2365     GPGME_STATUS_GET_BOOL = 48,
2366     GPGME_STATUS_GET_LINE = 49,
2367     GPGME_STATUS_GET_HIDDEN = 50,
2368     GPGME_STATUS_GOT_IT = 51,
2369     GPGME_STATUS_PROGRESS = 52,
2370     GPGME_STATUS_SIG_CREATED = 53,
2371     GPGME_STATUS_SESSION_KEY = 54,
2372     GPGME_STATUS_NOTATION_NAME = 55,
2373     GPGME_STATUS_NOTATION_DATA = 56,
2374     GPGME_STATUS_POLICY_URL = 57,
2375     GPGME_STATUS_BEGIN_STREAM = 58,    /* (legacy) */
2376     GPGME_STATUS_END_STREAM = 59,      /* (legacy) */
2377     GPGME_STATUS_KEY_CREATED = 60,
2378     GPGME_STATUS_USERID_HINT = 61,
2379     GPGME_STATUS_UNEXPECTED = 62,
2380     GPGME_STATUS_INV_RECP = 63,
2381     GPGME_STATUS_NO_RECP = 64,
2382     GPGME_STATUS_ALREADY_SIGNED = 65,
2383     GPGME_STATUS_SIGEXPIRED = 66,      /* (legacy) */
2384     GPGME_STATUS_EXPSIG = 67,
2385     GPGME_STATUS_EXPKEYSIG = 68,
2386     GPGME_STATUS_TRUNCATED = 69,
2387     GPGME_STATUS_ERROR = 70,
2388     GPGME_STATUS_NEWSIG = 71,
2389     GPGME_STATUS_REVKEYSIG = 72,
2390     GPGME_STATUS_SIG_SUBPACKET = 73,
2391     GPGME_STATUS_NEED_PASSPHRASE_PIN = 74,
2392     GPGME_STATUS_SC_OP_FAILURE = 75,
2393     GPGME_STATUS_SC_OP_SUCCESS = 76,
2394     GPGME_STATUS_CARDCTRL = 77,
2395     GPGME_STATUS_BACKUP_KEY_CREATED = 78,
2396     GPGME_STATUS_PKA_TRUST_BAD = 79,
2397     GPGME_STATUS_PKA_TRUST_GOOD = 80,
2398     GPGME_STATUS_PLAINTEXT = 81,
2399     GPGME_STATUS_INV_SGNR = 82,
2400     GPGME_STATUS_NO_SGNR = 83,
2401     GPGME_STATUS_SUCCESS = 84,
2402     GPGME_STATUS_DECRYPTION_INFO = 85,
2403     GPGME_STATUS_PLAINTEXT_LENGTH = 86,
2404     GPGME_STATUS_MOUNTPOINT = 87,
2405     GPGME_STATUS_PINENTRY_LAUNCHED = 88,
2406     GPGME_STATUS_ATTRIBUTE = 89,
2407     GPGME_STATUS_BEGIN_SIGNING = 90,
2408     GPGME_STATUS_KEY_NOT_CREATED = 91,
2409     GPGME_STATUS_INQUIRE_MAXLEN = 92,
2410     GPGME_STATUS_FAILURE = 93,
2411     GPGME_STATUS_KEY_CONSIDERED = 94,
2412     GPGME_STATUS_TOFU_USER = 95,
2413     GPGME_STATUS_TOFU_STATS = 96,
2414     GPGME_STATUS_TOFU_STATS_LONG = 97,
2415     GPGME_STATUS_NOTATION_FLAGS = 98
2416   }
2417 gpgme_status_code_t;
2418
2419 /* The callback type used by the deprecated functions gpgme_op_edit
2420  * and gpgme_op_card_edit.  */
2421 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
2422                                           gpgme_status_code_t status,
2423                                           const char *args, int fd);
2424
2425 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
2426                                    gpgme_edit_cb_t fnc, void *fnc_value,
2427                                    gpgme_data_t out) _GPGME_DEPRECATED(1,7);
2428 gpgme_error_t gpgme_op_edit       (gpgme_ctx_t ctx, gpgme_key_t key,
2429                                    gpgme_edit_cb_t fnc, void *fnc_value,
2430                                    gpgme_data_t out) _GPGME_DEPRECATED(1,7);
2431 gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
2432                                         gpgme_edit_cb_t fnc, void *fnc_value,
2433                                         gpgme_data_t out)
2434                                         _GPGME_DEPRECATED(1,7);
2435 gpgme_error_t gpgme_op_card_edit       (gpgme_ctx_t ctx, gpgme_key_t key,
2436                                         gpgme_edit_cb_t fnc, void *fnc_value,
2437                                         gpgme_data_t out)
2438                                         _GPGME_DEPRECATED(1,7);
2439
2440 /* The possible signature stati.  Deprecated, use error value in sig
2441    status.  */
2442 typedef enum
2443   {
2444     GPGME_SIG_STAT_NONE  = 0,
2445     GPGME_SIG_STAT_GOOD  = 1,
2446     GPGME_SIG_STAT_BAD   = 2,
2447     GPGME_SIG_STAT_NOKEY = 3,
2448     GPGME_SIG_STAT_NOSIG = 4,
2449     GPGME_SIG_STAT_ERROR = 5,
2450     GPGME_SIG_STAT_DIFF  = 6,
2451     GPGME_SIG_STAT_GOOD_EXP = 7,
2452     GPGME_SIG_STAT_GOOD_EXPKEY = 8
2453   }
2454 _gpgme_sig_stat_t;
2455 typedef _gpgme_sig_stat_t gpgme_sig_stat_t _GPGME_DEPRECATED(0,4);
2456
2457 /* The available key and signature attributes.  Deprecated, use the
2458    individual result structures instead.  */
2459 typedef enum
2460   {
2461     GPGME_ATTR_KEYID        = 1,
2462     GPGME_ATTR_FPR          = 2,
2463     GPGME_ATTR_ALGO         = 3,
2464     GPGME_ATTR_LEN          = 4,
2465     GPGME_ATTR_CREATED      = 5,
2466     GPGME_ATTR_EXPIRE       = 6,
2467     GPGME_ATTR_OTRUST       = 7,
2468     GPGME_ATTR_USERID       = 8,
2469     GPGME_ATTR_NAME         = 9,
2470     GPGME_ATTR_EMAIL        = 10,
2471     GPGME_ATTR_COMMENT      = 11,
2472     GPGME_ATTR_VALIDITY     = 12,
2473     GPGME_ATTR_LEVEL        = 13,
2474     GPGME_ATTR_TYPE         = 14,
2475     GPGME_ATTR_IS_SECRET    = 15,
2476     GPGME_ATTR_KEY_REVOKED  = 16,
2477     GPGME_ATTR_KEY_INVALID  = 17,
2478     GPGME_ATTR_UID_REVOKED  = 18,
2479     GPGME_ATTR_UID_INVALID  = 19,
2480     GPGME_ATTR_KEY_CAPS     = 20,
2481     GPGME_ATTR_CAN_ENCRYPT  = 21,
2482     GPGME_ATTR_CAN_SIGN     = 22,
2483     GPGME_ATTR_CAN_CERTIFY  = 23,
2484     GPGME_ATTR_KEY_EXPIRED  = 24,
2485     GPGME_ATTR_KEY_DISABLED = 25,
2486     GPGME_ATTR_SERIAL       = 26,
2487     GPGME_ATTR_ISSUER       = 27,
2488     GPGME_ATTR_CHAINID      = 28,
2489     GPGME_ATTR_SIG_STATUS   = 29,
2490     GPGME_ATTR_ERRTOK       = 30,
2491     GPGME_ATTR_SIG_SUMMARY  = 31,
2492     GPGME_ATTR_SIG_CLASS    = 32
2493   }
2494 _gpgme_attr_t;
2495 typedef _gpgme_attr_t gpgme_attr_t _GPGME_DEPRECATED(0,4);
2496
2497 /* Retrieve the signature status of signature IDX in CTX after a
2498    successful verify operation in R_STAT (if non-null).  The creation
2499    time stamp of the signature is returned in R_CREATED (if non-null).
2500    The function returns a string containing the fingerprint.
2501    Deprecated, use verify result directly.  */
2502 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
2503                                   _gpgme_sig_stat_t *r_stat,
2504                                   time_t *r_created) _GPGME_DEPRECATED(0,4);
2505
2506 /* Retrieve certain attributes of a signature.  IDX is the index
2507    number of the signature after a successful verify operation.  WHAT
2508    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
2509    one.  WHATIDX is to be passed as 0 for most attributes . */
2510 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
2511                                         _gpgme_attr_t what, int whatidx)
2512      _GPGME_DEPRECATED(0,4);
2513 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
2514                                        _gpgme_attr_t what, int whatidx)
2515      _GPGME_DEPRECATED(0,4);
2516
2517
2518 /* Get the key used to create signature IDX in CTX and return it in
2519    R_KEY.  */
2520 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
2521      _GPGME_DEPRECATED(0,4);
2522
2523 /* Create a new data buffer which retrieves the data from the callback
2524    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
2525    instead.  */
2526 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
2527                                            int (*read_cb) (void*,char *,
2528                                                            size_t,size_t*),
2529                                            void *read_cb_value)
2530      _GPGME_DEPRECATED(0,4);
2531
2532 /* Return the value of the attribute WHAT of KEY, which has to be
2533    representable by a string.  IDX specifies the sub key or user ID
2534    for attributes related to sub keys or user IDs.  Deprecated, use
2535    key structure directly instead. */
2536 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
2537                                        const void *reserved, int idx)
2538      _GPGME_DEPRECATED(0,4);
2539
2540 /* Return the value of the attribute WHAT of KEY, which has to be
2541    representable by an unsigned integer.  IDX specifies the sub key or
2542    user ID for attributes related to sub keys or user IDs.
2543    Deprecated, use key structure directly instead.  */
2544 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
2545                                         const void *reserved, int idx)
2546      _GPGME_DEPRECATED(0,4);
2547
2548 /* Return the value of the attribute WHAT of a signature on user ID
2549    UID_IDX in KEY, which has to be representable by a string.  IDX
2550    specifies the signature.  Deprecated, use key structure directly
2551    instead.  */
2552 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
2553                                            _gpgme_attr_t what,
2554                                            const void *reserved, int idx)
2555      _GPGME_DEPRECATED(0,4);
2556
2557 /* Return the value of the attribute WHAT of a signature on user ID
2558    UID_IDX in KEY, which has to be representable by an unsigned
2559    integer string.  IDX specifies the signature.  Deprecated, use key
2560    structure directly instead.  */
2561 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
2562                                             _gpgme_attr_t what,
2563                                             const void *reserved, int idx)
2564      _GPGME_DEPRECATED(0,4);
2565
2566
2567 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
2568                                    int *nr) _GPGME_DEPRECATED(0,4);
2569
2570 /* Release the trust item ITEM.  Deprecated, use
2571    gpgme_trust_item_unref.  */
2572 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED(0,4);
2573
2574 /* Return the value of the attribute WHAT of ITEM, which has to be
2575    representable by a string.  Deprecated, use trust item structure
2576    directly.  */
2577 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
2578                                               _gpgme_attr_t what,
2579                                               const void *reserved, int idx)
2580      _GPGME_DEPRECATED(0,4);
2581
2582 /* Return the value of the attribute WHAT of KEY, which has to be
2583    representable by an integer.  IDX specifies a running index if the
2584    attribute appears more than once in the key.  Deprecated, use trust
2585    item structure directly.  */
2586 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
2587                                    const void *reserved, int idx)
2588      _GPGME_DEPRECATED(0,4);
2589
2590 /* Compat.
2591  * This structure shall be considered read-only and an application
2592  * must not allocate such a structure on its own.  */
2593 struct _gpgme_op_assuan_result
2594 {
2595   /* Deprecated.  Use the second value in a DONE event or the
2596      synchronous variant gpgme_op_assuan_transact_ext.  */
2597   gpgme_error_t err _GPGME_DEPRECATED_OUTSIDE_GPGME(1,2);
2598 };
2599 typedef struct _gpgme_op_assuan_result *gpgme_assuan_result_t;
2600
2601
2602 /* Return the result of the last Assuan command. */
2603 gpgme_assuan_result_t gpgme_op_assuan_result (gpgme_ctx_t ctx)
2604   _GPGME_DEPRECATED(1,2);
2605
2606 gpgme_error_t
2607 gpgme_op_assuan_transact (gpgme_ctx_t ctx,
2608                               const char *command,
2609                               gpgme_assuan_data_cb_t data_cb,
2610                               void *data_cb_value,
2611                               gpgme_assuan_inquire_cb_t inq_cb,
2612                               void *inq_cb_value,
2613                               gpgme_assuan_status_cb_t status_cb,
2614                           void *status_cb_value) _GPGME_DEPRECATED(1,2);
2615
2616
2617
2618 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED(0,4);
2619 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED(0,4);
2620 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED(0,4);
2621 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED(0,4);
2622 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED(0,4);
2623 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED(0,4);
2624 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED(0,4);
2625 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED(0,4);
2626 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED(0,4);
2627 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED(0,4);
2628 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED(0,4);
2629 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED(0,4);
2630 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED(0,4);
2631 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED(0,4);
2632 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED(0,4);
2633 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED(0,4);
2634 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED(0,4);
2635 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED(0,4);
2636 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED(0,4);
2637 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED(0,4);
2638 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED(0,4);
2639 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED(0,4);
2640 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED(0,4);
2641 #define GpgmeIOCbs gpgme_io_cbs
2642 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED(0,4);
2643 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED(0,4);
2644 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED(0,4);
2645 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED(0,4);
2646 #define GpgmeDataCbs gpgme_data_cbs
2647 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED(0,4);
2648 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED(0,4);
2649 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED(0,4);
2650 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED(0,4);
2651 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED(0,4);
2652 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED(0,4);
2653 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED(0,4);
2654 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED(0,4);
2655 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED(0,4);
2656
2657 #ifdef __cplusplus
2658 }
2659 #endif
2660 #endif /* GPGME_H */
2661 /*
2662 @emacs_local_vars_begin@
2663 @emacs_local_vars_read_only@
2664 @emacs_local_vars_end@
2665 */