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