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