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