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