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