doc/
[gpgme.git] / gpgme / gpgme.h
1 /* gpgme.h - Public interface to GnuPG Made Easy.
2    Copyright (C) 2000 Werner Koch (dd9jn)
3    Copyright (C) 2001, 2002, 2003, 2004 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 General Public License as published by
9    the Free Software Foundation; either version 2 of the License, or
10    (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    General Public License for more details.
16  
17    You should have received a copy of the GNU General Public License
18    along with GPGME; if not, write to the Free Software Foundation,
19    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
20
21 #ifndef GPGME_H
22 #define GPGME_H
23
24 #ifdef __GNUC__
25 #define _GPGME_INLINE __inline__
26 #elif __STDC_VERSION__ >= 199901L
27 #define _GPGME_INLINE inline
28 #else
29 #define _GPGME_INLINE
30 #endif
31
32 /* Include stdio.h for the FILE type definition.  */
33 #include <stdio.h>
34
35 #ifdef _MSC_VER
36   typedef long off_t;
37   typedef long ssize_t;
38 #else
39 # include <sys/types.h>
40 #ifdef _WIN32
41 typedef long ssize_t;
42 #endif
43 #endif
44
45 #ifdef __cplusplus
46 extern "C" {
47 #if 0 /* just to make Emacs auto-indent happy */
48 }
49 #endif
50 #endif /* __cplusplus */
51
52 #include <gpg-error.h>
53
54 \f
55 /* Check for compiler features.  */
56 #if __GNUC__
57 #define _GPGME_GCC_VERSION (__GNUC__ * 10000 \
58                             + __GNUC_MINOR__ * 100 \
59                             + __GNUC_PATCHLEVEL__)
60
61 #if _GPGME_GCC_VERSION > 30100
62 #define _GPGME_DEPRECATED       __attribute__ ((__deprecated__))
63 #endif
64 #endif
65
66 #ifndef _GPGME_DEPRECATED
67 #define _GPGME_DEPRECATED
68 #endif
69
70 \f
71 /* The version of this header should match the one of the library.  Do
72    not use this symbol in your application, use gpgme_check_version
73    instead.  The purpose of this macro is to let autoconf (using the
74    AM_PATH_GPGME macro) check that this header matches the installed
75    library.  Warning: Do not edit the next line.  configure will do
76    that for you!  */
77 #define GPGME_VERSION "0.4.7"
78
79 \f
80 /* Some opaque data types used by GPGME.  */
81
82 /* The context holds some global state and configration options, as
83    well as the results of a crypto operation.  */
84 struct gpgme_context;
85 typedef struct gpgme_context *gpgme_ctx_t;
86
87 /* The data object is used by GPGME to exchange arbitrary data.  */
88 struct gpgme_data;
89 typedef struct gpgme_data *gpgme_data_t;
90
91 \f
92 /* Wrappers for the libgpg-error library.  */
93
94 typedef gpg_error_t gpgme_error_t;
95 typedef gpg_err_code_t gpgme_err_code_t;
96 typedef gpg_err_source_t gpgme_err_source_t;
97
98
99 static _GPGME_INLINE gpgme_error_t
100 gpgme_err_make (gpgme_err_source_t source, gpgme_err_code_t code)
101 {
102   return gpg_err_make (source, code);
103 }
104
105
106 /* The user can define GPGME_ERR_SOURCE_DEFAULT before including this
107    file to specify a default source for gpgme_error.  */
108 #ifndef GPGME_ERR_SOURCE_DEFAULT
109 #define GPGME_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_1
110 #endif
111
112 static _GPGME_INLINE gpgme_error_t
113 gpgme_error (gpgme_err_code_t code)
114 {
115   return gpgme_err_make (GPGME_ERR_SOURCE_DEFAULT, code);
116 }
117
118
119 static _GPGME_INLINE gpgme_err_code_t
120 gpgme_err_code (gpgme_error_t err)
121 {
122   return gpg_err_code (err);
123 }
124
125
126 static _GPGME_INLINE gpgme_err_source_t
127 gpgme_err_source (gpgme_error_t err)
128 {
129   return gpg_err_source (err);
130 }
131
132
133 /* Return a pointer to a string containing a description of the error
134    code in the error value ERR.  This function is not thread safe.  */
135 const char *gpgme_strerror (gpgme_error_t err);
136
137 /* Return the error string for ERR in the user-supplied buffer BUF of
138    size BUFLEN.  This function is, in contrast to gpg_strerror,
139    thread-safe if a thread-safe strerror_r() function is provided by
140    the system.  If the function succeeds, 0 is returned and BUF
141    contains the string describing the error.  If the buffer was not
142    large enough, ERANGE is returned and BUF contains as much of the
143    beginning of the error string as fits into the buffer.  */
144 int gpgme_strerror_r (gpg_error_t err, char *buf, size_t buflen);
145
146
147 /* Return a pointer to a string containing a description of the error
148    source in the error value ERR.  */
149 const char *gpgme_strsource (gpgme_error_t err);
150
151
152 /* Retrieve the error code for the system error ERR.  This returns
153    GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
154    this).  */
155 gpgme_err_code_t gpgme_err_code_from_errno (int err);
156
157
158 /* Retrieve the system error for the error code CODE.  This returns 0
159    if CODE is not a system error code.  */
160 int gpgme_err_code_to_errno (gpgme_err_code_t code);
161
162   
163 /* Return an error value with the error source SOURCE and the system
164    error ERR.  */
165 gpgme_error_t gpgme_err_make_from_errno (gpgme_err_source_t source, int err);
166
167
168 /* Return an error value with the system error ERR.  */
169 gpgme_err_code_t gpgme_error_from_errno (int err);
170
171 \f
172 /* The possible encoding mode of gpgme_data_t objects.  */
173 typedef enum
174   {
175     GPGME_DATA_ENCODING_NONE   = 0,     /* Not specified.  */
176     GPGME_DATA_ENCODING_BINARY = 1,
177     GPGME_DATA_ENCODING_BASE64 = 2,
178     GPGME_DATA_ENCODING_ARMOR  = 3      /* Either PEM or OpenPGP Armor.  */
179   }
180 gpgme_data_encoding_t;
181
182 \f
183 /* Public key algorithms from libgcrypt.  */
184 typedef enum
185   {
186     GPGME_PK_RSA   = 1,
187     GPGME_PK_RSA_E = 2,
188     GPGME_PK_RSA_S = 3,
189     GPGME_PK_ELG_E = 16,
190     GPGME_PK_DSA   = 17,
191     GPGME_PK_ELG   = 20
192   }
193 gpgme_pubkey_algo_t;
194
195
196 /* Hash algorithms from libgcrypt.  */
197 typedef enum
198   {
199     GPGME_MD_NONE          = 0,  
200     GPGME_MD_MD5           = 1,
201     GPGME_MD_SHA1          = 2,
202     GPGME_MD_RMD160        = 3,
203     GPGME_MD_MD2           = 5,
204     GPGME_MD_TIGER         = 6,   /* TIGER/192. */
205     GPGME_MD_HAVAL         = 7,   /* HAVAL, 5 pass, 160 bit. */
206     GPGME_MD_SHA256        = 8,
207     GPGME_MD_SHA384        = 9,
208     GPGME_MD_SHA512        = 10,
209     GPGME_MD_MD4           = 301,
210     GPGME_MD_CRC32         = 302,
211     GPGME_MD_CRC32_RFC1510 = 303,
212     GPGME_MD_CRC24_RFC2440 = 304
213   }
214 gpgme_hash_algo_t;
215
216 \f
217 /* The possible signature stati.  Deprecated, use error value in sig
218    status.  */
219 typedef enum
220   {
221     GPGME_SIG_STAT_NONE  = 0,
222     GPGME_SIG_STAT_GOOD  = 1,
223     GPGME_SIG_STAT_BAD   = 2,
224     GPGME_SIG_STAT_NOKEY = 3,
225     GPGME_SIG_STAT_NOSIG = 4,
226     GPGME_SIG_STAT_ERROR = 5,
227     GPGME_SIG_STAT_DIFF  = 6,
228     GPGME_SIG_STAT_GOOD_EXP = 7,
229     GPGME_SIG_STAT_GOOD_EXPKEY = 8
230   }
231 _gpgme_sig_stat_t;
232 typedef _gpgme_sig_stat_t gpgme_sig_stat_t _GPGME_DEPRECATED;
233
234
235 /* The available signature modes.  */
236 typedef enum
237   {
238     GPGME_SIG_MODE_NORMAL = 0,
239     GPGME_SIG_MODE_DETACH = 1,
240     GPGME_SIG_MODE_CLEAR  = 2
241   }
242 gpgme_sig_mode_t;
243
244 \f
245 /* The available key and signature attributes.  Deprecated, use the
246    individual result structures instead.  */
247 typedef enum
248   {
249     GPGME_ATTR_KEYID        = 1,
250     GPGME_ATTR_FPR          = 2,
251     GPGME_ATTR_ALGO         = 3,
252     GPGME_ATTR_LEN          = 4,
253     GPGME_ATTR_CREATED      = 5,
254     GPGME_ATTR_EXPIRE       = 6,
255     GPGME_ATTR_OTRUST       = 7,
256     GPGME_ATTR_USERID       = 8,
257     GPGME_ATTR_NAME         = 9,
258     GPGME_ATTR_EMAIL        = 10,
259     GPGME_ATTR_COMMENT      = 11,
260     GPGME_ATTR_VALIDITY     = 12,
261     GPGME_ATTR_LEVEL        = 13,
262     GPGME_ATTR_TYPE         = 14,
263     GPGME_ATTR_IS_SECRET    = 15,
264     GPGME_ATTR_KEY_REVOKED  = 16,
265     GPGME_ATTR_KEY_INVALID  = 17,
266     GPGME_ATTR_UID_REVOKED  = 18,
267     GPGME_ATTR_UID_INVALID  = 19,
268     GPGME_ATTR_KEY_CAPS     = 20,
269     GPGME_ATTR_CAN_ENCRYPT  = 21,
270     GPGME_ATTR_CAN_SIGN     = 22,
271     GPGME_ATTR_CAN_CERTIFY  = 23,
272     GPGME_ATTR_KEY_EXPIRED  = 24,
273     GPGME_ATTR_KEY_DISABLED = 25,
274     GPGME_ATTR_SERIAL       = 26,
275     GPGME_ATTR_ISSUER       = 27,
276     GPGME_ATTR_CHAINID      = 28,
277     GPGME_ATTR_SIG_STATUS   = 29,
278     GPGME_ATTR_ERRTOK       = 30,
279     GPGME_ATTR_SIG_SUMMARY  = 31,
280     GPGME_ATTR_SIG_CLASS    = 32
281   }
282 _gpgme_attr_t;
283 typedef _gpgme_attr_t gpgme_attr_t _GPGME_DEPRECATED;
284
285 \f
286 /* The available validities for a trust item or key.  */
287 typedef enum
288   {
289     GPGME_VALIDITY_UNKNOWN   = 0,
290     GPGME_VALIDITY_UNDEFINED = 1,
291     GPGME_VALIDITY_NEVER     = 2,
292     GPGME_VALIDITY_MARGINAL  = 3,
293     GPGME_VALIDITY_FULL      = 4,
294     GPGME_VALIDITY_ULTIMATE  = 5
295   }
296 gpgme_validity_t;
297
298 \f
299 /* The available protocols.  */
300 typedef enum
301   {
302     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
303     GPGME_PROTOCOL_CMS     = 1
304   }
305 gpgme_protocol_t;
306
307 \f
308 /* The available keylist mode flags.  */
309 typedef enum
310   {
311     GPGME_KEYLIST_MODE_LOCAL  = 1,
312     GPGME_KEYLIST_MODE_EXTERN = 2,
313     GPGME_KEYLIST_MODE_SIGS   = 4,
314     GPGME_KEYLIST_MODE_VALIDATE = 256
315   }
316 gpgme_keylist_mode_t;
317
318 \f
319 /* The possible stati for the edit operation.  */
320 typedef enum
321   {
322     GPGME_STATUS_EOF,
323     /* mkstatus processing starts here */
324     GPGME_STATUS_ENTER,
325     GPGME_STATUS_LEAVE,
326     GPGME_STATUS_ABORT,
327
328     GPGME_STATUS_GOODSIG,
329     GPGME_STATUS_BADSIG,
330     GPGME_STATUS_ERRSIG,
331
332     GPGME_STATUS_BADARMOR,
333
334     GPGME_STATUS_RSA_OR_IDEA,
335     GPGME_STATUS_KEYEXPIRED,
336     GPGME_STATUS_KEYREVOKED,
337
338     GPGME_STATUS_TRUST_UNDEFINED,
339     GPGME_STATUS_TRUST_NEVER,
340     GPGME_STATUS_TRUST_MARGINAL,
341     GPGME_STATUS_TRUST_FULLY,
342     GPGME_STATUS_TRUST_ULTIMATE,
343
344     GPGME_STATUS_SHM_INFO,
345     GPGME_STATUS_SHM_GET,
346     GPGME_STATUS_SHM_GET_BOOL,
347     GPGME_STATUS_SHM_GET_HIDDEN,
348
349     GPGME_STATUS_NEED_PASSPHRASE,
350     GPGME_STATUS_VALIDSIG,
351     GPGME_STATUS_SIG_ID,
352     GPGME_STATUS_ENC_TO,
353     GPGME_STATUS_NODATA,
354     GPGME_STATUS_BAD_PASSPHRASE,
355     GPGME_STATUS_NO_PUBKEY,
356     GPGME_STATUS_NO_SECKEY,
357     GPGME_STATUS_NEED_PASSPHRASE_SYM,
358     GPGME_STATUS_DECRYPTION_FAILED,
359     GPGME_STATUS_DECRYPTION_OKAY,
360     GPGME_STATUS_MISSING_PASSPHRASE,
361     GPGME_STATUS_GOOD_PASSPHRASE,
362     GPGME_STATUS_GOODMDC,
363     GPGME_STATUS_BADMDC,
364     GPGME_STATUS_ERRMDC,
365     GPGME_STATUS_IMPORTED,
366     GPGME_STATUS_IMPORT_OK,
367     GPGME_STATUS_IMPORT_PROBLEM,
368     GPGME_STATUS_IMPORT_RES,
369     GPGME_STATUS_FILE_START,
370     GPGME_STATUS_FILE_DONE,
371     GPGME_STATUS_FILE_ERROR,
372
373     GPGME_STATUS_BEGIN_DECRYPTION,
374     GPGME_STATUS_END_DECRYPTION,
375     GPGME_STATUS_BEGIN_ENCRYPTION,
376     GPGME_STATUS_END_ENCRYPTION,
377
378     GPGME_STATUS_DELETE_PROBLEM,
379     GPGME_STATUS_GET_BOOL,
380     GPGME_STATUS_GET_LINE,
381     GPGME_STATUS_GET_HIDDEN,
382     GPGME_STATUS_GOT_IT,
383     GPGME_STATUS_PROGRESS,
384     GPGME_STATUS_SIG_CREATED,
385     GPGME_STATUS_SESSION_KEY,
386     GPGME_STATUS_NOTATION_NAME,
387     GPGME_STATUS_NOTATION_DATA,
388     GPGME_STATUS_POLICY_URL,
389     GPGME_STATUS_BEGIN_STREAM,
390     GPGME_STATUS_END_STREAM,
391     GPGME_STATUS_KEY_CREATED,
392     GPGME_STATUS_USERID_HINT,
393     GPGME_STATUS_UNEXPECTED,
394     GPGME_STATUS_INV_RECP,
395     GPGME_STATUS_NO_RECP,
396     GPGME_STATUS_ALREADY_SIGNED,
397     GPGME_STATUS_SIGEXPIRED,
398     GPGME_STATUS_EXPSIG,
399     GPGME_STATUS_EXPKEYSIG,
400     GPGME_STATUS_TRUNCATED,
401     GPGME_STATUS_ERROR,
402     GPGME_STATUS_NEWSIG
403   }
404 gpgme_status_code_t;
405
406 \f
407 /* The engine information structure.  */
408 struct _gpgme_engine_info
409 {
410   struct _gpgme_engine_info *next;
411
412   /* The protocol ID.  */
413   gpgme_protocol_t protocol;
414
415   /* The file name of the engine binary.  */
416   const char *file_name;
417
418   /* The version string of the installed engine.  */
419   const char *version;
420
421   /* The minimum version required for GPGME.  */
422   const char *req_version;
423 };
424 typedef struct _gpgme_engine_info *gpgme_engine_info_t;
425
426 \f
427 /* A subkey from a key.  */
428 struct _gpgme_subkey
429 {
430   struct _gpgme_subkey *next;
431
432   /* True if subkey is revoked.  */
433   unsigned int revoked : 1;
434
435   /* True if subkey is expired.  */
436   unsigned int expired : 1;
437
438   /* True if subkey is disabled.  */
439   unsigned int disabled : 1;
440
441   /* True if subkey is invalid.  */
442   unsigned int invalid : 1;
443
444   /* True if subkey can be used for encryption.  */
445   unsigned int can_encrypt : 1;
446
447   /* True if subkey can be used for signing.  */
448   unsigned int can_sign : 1;
449
450   /* True if subkey can be used for certification.  */
451   unsigned int can_certify : 1;
452
453   /* True if subkey is secret.  */
454   unsigned int secret : 1;
455
456   /* True if subkey can be used for authentication.  */
457   unsigned int can_authenticate : 1;
458
459   /* Internal to GPGME, do not use.  */
460   unsigned int _unused : 23;
461   
462   /* Public key algorithm supported by this subkey.  */
463   gpgme_pubkey_algo_t pubkey_algo;
464
465   /* Length of the subkey.  */
466   unsigned int length;
467
468   /* The key ID of the subkey.  */
469   char *keyid;
470
471   /* Internal to GPGME, do not use.  */
472   char _keyid[16 + 1];
473
474   /* The fingerprint of the subkey in hex digit form.  */
475   char *fpr;
476
477   /* The creation timestamp, -1 if invalid, 0 if not available.  */
478   long int timestamp;
479
480   /* The expiration timestamp, 0 if the subkey does not expire.  */
481   long int expires;
482 };
483 typedef struct _gpgme_subkey *gpgme_subkey_t;
484
485
486 /* A signature on a user ID.  */
487 struct _gpgme_key_sig
488 {
489   struct _gpgme_key_sig *next;
490
491   /* True if the signature is a revocation signature.  */
492   unsigned int revoked : 1;
493
494   /* True if the signature is expired.  */
495   unsigned int expired : 1;
496
497   /* True if the signature is invalid.  */
498   unsigned int invalid : 1;
499
500   /* True if the signature should be exported.  */
501   unsigned int exportable : 1;
502
503   /* Internal to GPGME, do not use.  */
504   unsigned int _unused : 28;
505
506   /* The public key algorithm used to create the signature.  */
507   gpgme_pubkey_algo_t pubkey_algo;
508
509   /* The key ID of key used to create the signature.  */
510   char *keyid;
511
512   /* Internal to GPGME, do not use.  */
513   char _keyid[16 + 1];
514
515   /* The creation timestamp, -1 if invalid, 0 if not available.  */
516   long int timestamp;
517
518   /* The expiration timestamp, 0 if the subkey does not expire.  */
519   long int expires;
520
521   /* Same as in gpgme_signature_t.  */
522   gpgme_error_t status;
523
524 #ifdef __cplusplus
525   unsigned int _obsolete_class _GPGME_DEPRECATED;
526 #else
527   /* Must be set to SIG_CLASS below.  */
528   unsigned int class _GPGME_DEPRECATED;
529 #endif
530
531   /* The user ID string.  */
532   char *uid;
533
534   /* The name part of the user ID.  */
535   char *name;
536
537   /* The email part of the user ID.  */
538   char *email;
539
540   /* The comment part of the user ID.  */
541   char *comment;
542
543   /* Crypto backend specific signature class.  */
544   unsigned int sig_class;
545 };
546 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
547
548
549 /* An user ID from a key.  */
550 struct _gpgme_user_id
551 {
552   struct _gpgme_user_id *next;
553
554   /* True if the user ID is revoked.  */
555   unsigned int revoked : 1;
556
557   /* True if the user ID is invalid.  */
558   unsigned int invalid : 1;
559
560   /* Internal to GPGME, do not use.  */
561   unsigned int _unused : 30;
562
563   /* The validity of the user ID.  */
564   gpgme_validity_t validity; 
565
566   /* The user ID string.  */
567   char *uid;
568
569   /* The name part of the user ID.  */
570   char *name;
571
572   /* The email part of the user ID.  */
573   char *email;
574
575   /* The comment part of the user ID.  */
576   char *comment;
577
578   /* The signatures of the user ID.  */
579   gpgme_key_sig_t signatures;
580
581   /* Internal to GPGME, do not use.  */
582   gpgme_key_sig_t _last_keysig;
583 };
584 typedef struct _gpgme_user_id *gpgme_user_id_t;
585
586
587 /* A key from the keyring.  */
588 struct _gpgme_key
589 {
590   /* Internal to GPGME, do not use.  */
591   unsigned int _refs;
592
593   /* True if key is revoked.  */
594   unsigned int revoked : 1;
595
596   /* True if key is expired.  */
597   unsigned int expired : 1;
598
599   /* True if key is disabled.  */
600   unsigned int disabled : 1;
601
602   /* True if key is invalid.  */
603   unsigned int invalid : 1;
604
605   /* True if key can be used for encryption.  */
606   unsigned int can_encrypt : 1;
607
608   /* True if key can be used for signing.  */
609   unsigned int can_sign : 1;
610
611   /* True if key can be used for certification.  */
612   unsigned int can_certify : 1;
613
614   /* True if key is secret.  */
615   unsigned int secret : 1;
616
617   /* True if key can be used for authentication.  */
618   unsigned int can_authenticate : 1;
619
620   /* Internal to GPGME, do not use.  */
621   unsigned int _unused : 23;
622
623   /* This is the protocol supported by this key.  */
624   gpgme_protocol_t protocol;
625
626   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
627      issuer serial.  */
628   char *issuer_serial;
629
630   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
631      issuer name.  */
632   char *issuer_name;
633
634   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
635      ID.  */
636   char *chain_id;
637
638   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
639      owner trust.  */
640   gpgme_validity_t owner_trust;
641
642   /* The subkeys of the key.  */
643   gpgme_subkey_t subkeys;
644
645   /* The user IDs of the key.  */
646   gpgme_user_id_t uids;
647
648   /* Internal to GPGME, do not use.  */
649   gpgme_subkey_t _last_subkey;
650
651   /* Internal to GPGME, do not use.  */
652   gpgme_user_id_t _last_uid;
653
654   /* The keylist mode that was active when listing the key.  */
655   /* Implementation note: We are using unsigned int here, and not
656      gpgme_keylist_mode_t, as the latter is currently an enum of
657      unknown size.  */
658   unsigned int keylist_mode;
659 };
660 typedef struct _gpgme_key *gpgme_key_t;
661
662
663 \f
664 /* Types for callback functions.  */
665
666 /* Request a passphrase from the user.  */
667 typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
668                                                 const char *uid_hint,
669                                                 const char *passphrase_info,
670                                                 int prev_was_bad, int fd);
671
672 /* Inform the user about progress made.  */
673 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
674                                      int type, int current, int total);
675
676 /* Interact with the user about an edit operation.  */
677 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
678                                           gpgme_status_code_t status,
679                                           const char *args, int fd);
680
681 \f
682 /* Context management functions.  */
683
684 /* Create a new context and return it in CTX.  */
685 gpgme_error_t gpgme_new (gpgme_ctx_t *ctx);
686
687 /* Release the context CTX.  */
688 void gpgme_release (gpgme_ctx_t ctx);
689
690 /* Set the protocol to be used by CTX to PROTO.  */
691 gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
692
693 /* Get the protocol used with CTX */
694 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
695
696 /* Get the string describing protocol PROTO, or NULL if invalid.  */
697 const char *gpgme_get_protocol_name (gpgme_protocol_t proto);
698
699 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
700 void gpgme_set_armor (gpgme_ctx_t ctx, int yes);
701
702 /* Return non-zero if armor mode is set in CTX.  */
703 int gpgme_get_armor (gpgme_ctx_t ctx);
704
705 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
706 void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
707
708 /* Return non-zero if text mode is set in CTX.  */
709 int gpgme_get_textmode (gpgme_ctx_t ctx);
710
711 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
712 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
713
714 /* Return the number of certs to include in an S/MIME message.  */
715 int gpgme_get_include_certs (gpgme_ctx_t ctx);
716
717 /* Set keylist mode in CTX to MODE.  */
718 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
719                                       gpgme_keylist_mode_t mode);
720
721 /* Get keylist mode in CTX.  */
722 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
723
724 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
725    passed as first argument to the passphrase callback function.  */
726 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
727                               gpgme_passphrase_cb_t cb, void *hook_value);
728
729 /* Get the current passphrase callback function in *CB and the current
730    hook value in *HOOK_VALUE.  */
731 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
732                               void **hook_value);
733
734 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
735    passed as first argument to the progress callback function.  */
736 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
737                             void *hook_value);
738
739 /* Get the current progress callback function in *CB and the current
740    hook value in *HOOK_VALUE.  */
741 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
742                             void **hook_value);
743
744 /* This function sets the locale for the context CTX, or the default
745    locale if CTX is a null pointer.  */
746 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
747                                 const char *value);
748 \f
749 /* Return a statically allocated string with the name of the public
750    key algorithm ALGO, or NULL if that name is not known.  */
751 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
752
753 /* Return a statically allocated string with the name of the hash
754    algorithm ALGO, or NULL if that name is not known.  */
755 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
756
757 \f
758 /* Delete all signers from CTX.  */
759 void gpgme_signers_clear (gpgme_ctx_t ctx);
760
761 /* Add KEY to list of signers in CTX.  */
762 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
763
764 /* Return the SEQth signer's key in CTX.  */
765 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
766
767 /* Retrieve the signature status of signature IDX in CTX after a
768    successful verify operation in R_STAT (if non-null).  The creation
769    time stamp of the signature is returned in R_CREATED (if non-null).
770    The function returns a string containing the fingerprint.
771    Deprecated, use verify result directly.  */
772 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
773                                   _gpgme_sig_stat_t *r_stat,
774                                   time_t *r_created) _GPGME_DEPRECATED;
775
776 /* Retrieve certain attributes of a signature.  IDX is the index
777    number of the signature after a successful verify operation.  WHAT
778    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
779    one.  WHATIDX is to be passed as 0 for most attributes . */
780 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
781                                         _gpgme_attr_t what, int whatidx)
782      _GPGME_DEPRECATED;
783 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
784                                        _gpgme_attr_t what, int whatidx)
785      _GPGME_DEPRECATED;
786
787
788 /* Get the key used to create signature IDX in CTX and return it in
789    R_KEY.  */
790 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
791      _GPGME_DEPRECATED;
792
793 \f
794 /* Run control.  */
795
796 /* The type of an I/O callback function.  */
797 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
798
799 /* The type of a function that can register FNC as the I/O callback
800    function for the file descriptor FD with direction dir (0: for writing,
801    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
802    function should return a TAG suitable for the corresponding
803    gpgme_remove_io_cb_t, and an error value.  */
804 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
805                                                  gpgme_io_cb_t fnc,
806                                                  void *fnc_data, void **tag);
807
808 /* The type of a function that can remove a previously registered I/O
809    callback function given TAG as returned by the register
810    function.  */
811 typedef void (*gpgme_remove_io_cb_t) (void *tag);
812
813 typedef enum
814   {
815     GPGME_EVENT_START,
816     GPGME_EVENT_DONE,
817     GPGME_EVENT_NEXT_KEY,
818     GPGME_EVENT_NEXT_TRUSTITEM
819   }
820 gpgme_event_io_t;
821
822 /* The type of a function that is called when a context finished an
823    operation.  */
824 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
825                                      void *type_data);
826
827 struct gpgme_io_cbs
828 {
829   gpgme_register_io_cb_t add;
830   void *add_priv;
831   gpgme_remove_io_cb_t remove;
832   gpgme_event_io_cb_t event;
833   void *event_priv;
834 };
835 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
836
837 /* Set the I/O callback functions in CTX to IO_CBS.  */
838 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
839
840 /* Get the current I/O callback functions.  */
841 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
842
843 /* Process the pending operation and, if HANG is non-zero, wait for
844    the pending operation to finish.  */
845 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
846
847 \f
848 /* Functions to handle data objects.  */
849
850 /* Read up to SIZE bytes into buffer BUFFER from the data object with
851    the handle HANDLE.  Return the number of characters read, 0 on EOF
852    and -1 on error.  If an error occurs, errno is set.  */
853 typedef ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer,
854                                          size_t size);
855
856 /* Write up to SIZE bytes from buffer BUFFER to the data object with
857    the handle HANDLE.  Return the number of characters written, or -1
858    on error.  If an error occurs, errno is set.  */
859 typedef ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
860                                           size_t size);
861
862 /* Set the current position from where the next read or write starts
863    in the data object with the handle HANDLE to OFFSET, relativ to
864    WHENCE.  */
865 typedef off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence);
866
867 /* Close the data object with the handle DL.  */
868 typedef void (*gpgme_data_release_cb_t) (void *handle);
869
870 struct gpgme_data_cbs
871 {
872   gpgme_data_read_cb_t read;
873   gpgme_data_write_cb_t write;
874   gpgme_data_seek_cb_t seek;
875   gpgme_data_release_cb_t release;
876 };
877 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
878
879 /* Read up to SIZE bytes into buffer BUFFER from the data object with
880    the handle DH.  Return the number of characters read, 0 on EOF and
881    -1 on error.  If an error occurs, errno is set.  */
882 ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
883
884 /* Write up to SIZE bytes from buffer BUFFER to the data object with
885    the handle DH.  Return the number of characters written, or -1 on
886    error.  If an error occurs, errno is set.  */
887 ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
888
889 /* Set the current position from where the next read or write starts
890    in the data object with the handle DH to OFFSET, relativ to
891    WHENCE.  */
892 off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
893
894 /* Create a new data buffer and return it in R_DH.  */
895 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
896
897 /* Destroy the data buffer DH.  */
898 void gpgme_data_release (gpgme_data_t dh);
899
900 /* Create a new data buffer filled with SIZE bytes starting from
901    BUFFER.  If COPY is zero, copying is delayed until necessary, and
902    the data is taken from the original location when needed.  */
903 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
904                                        const char *buffer, size_t size,
905                                        int copy);
906
907 /* Destroy the data buffer DH and return a pointer to its content.
908    The memory has be to released with free by the user.  It's size is
909    returned in R_LEN.  */
910 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
911
912 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
913                                        gpgme_data_cbs_t cbs,
914                                        void *handle);
915
916 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
917
918 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
919
920 /* Return the encoding attribute of the data buffer DH */
921 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
922
923 /* Set the encoding attribute of data buffer DH to ENC */
924 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
925                                        gpgme_data_encoding_t enc);
926
927
928
929 /* Create a new data buffer which retrieves the data from the callback
930    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
931    instead.  */
932 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
933                                            int (*read_cb) (void*,char *,
934                                                            size_t,size_t*),
935                                            void *read_cb_value)
936      _GPGME_DEPRECATED;
937
938 /* Create a new data buffer filled with the content of file FNAME.
939    COPY must be non-zero.  For delayed read, please use
940    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
941 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
942                                         const char *fname,
943                                         int copy);
944
945 /* Create a new data buffer filled with LENGTH bytes starting from
946    OFFSET within the file FNAME or stream FP (exactly one must be
947    non-zero).  */
948 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
949                                             const char *fname, FILE *fp,
950                                             off_t offset, size_t length);
951
952 /* Reset the read pointer in DH.  Deprecated, please use
953    gpgme_data_seek instead.  */
954 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh) _GPGME_DEPRECATED;
955
956 \f
957 /* Key and trust functions.  */
958
959 /* Get the key with the fingerprint FPR from the crypto backend.  If
960    SECRET is true, get the secret key.  */
961 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
962                              gpgme_key_t *r_key, int secret);
963
964 /* Acquire a reference to KEY.  */
965 void gpgme_key_ref (gpgme_key_t key);
966
967 /* Release a reference to KEY.  If this was the last one the key is
968    destroyed.  */
969 void gpgme_key_unref (gpgme_key_t key);
970 void gpgme_key_release (gpgme_key_t key);
971
972 /* Return the value of the attribute WHAT of KEY, which has to be
973    representable by a string.  IDX specifies the sub key or user ID
974    for attributes related to sub keys or user IDs.  Deprecated, use
975    key structure directly instead. */
976 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
977                                        const void *reserved, int idx)
978      _GPGME_DEPRECATED;
979
980 /* Return the value of the attribute WHAT of KEY, which has to be
981    representable by an unsigned integer.  IDX specifies the sub key or
982    user ID for attributes related to sub keys or user IDs.
983    Deprecated, use key structure directly instead.  */
984 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
985                                         const void *reserved, int idx)
986      _GPGME_DEPRECATED;
987
988 /* Return the value of the attribute WHAT of a signature on user ID
989    UID_IDX in KEY, which has to be representable by a string.  IDX
990    specifies the signature.  Deprecated, use key structure directly
991    instead.  */
992 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
993                                            _gpgme_attr_t what,
994                                            const void *reserved, int idx)
995      _GPGME_DEPRECATED;
996
997 /* Return the value of the attribute WHAT of a signature on user ID
998    UID_IDX in KEY, which has to be representable by an unsigned
999    integer string.  IDX specifies the signature.  Deprecated, use key
1000    structure directly instead.  */
1001 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
1002                                             _gpgme_attr_t what,
1003                                             const void *reserved, int idx)
1004      _GPGME_DEPRECATED;
1005
1006 \f
1007 /* Crypto Operations.  */
1008
1009 /* Cancel a pending asynchronous operation.  */
1010 gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
1011
1012 \f
1013 struct _gpgme_invalid_key
1014 {
1015   struct _gpgme_invalid_key *next;
1016   char *fpr;
1017   gpgme_error_t reason;
1018 };
1019 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
1020
1021 \f
1022 /* Encryption.  */
1023 struct _gpgme_op_encrypt_result
1024 {
1025   /* The list of invalid recipients.  */
1026   gpgme_invalid_key_t invalid_recipients;
1027 };
1028 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
1029
1030 /* Retrieve a pointer to the result of the encrypt operation.  */
1031 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
1032
1033 /* The valid encryption flags.  */
1034 typedef enum
1035   {
1036     GPGME_ENCRYPT_ALWAYS_TRUST = 1
1037   }
1038 gpgme_encrypt_flags_t;
1039
1040 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1041    store the resulting ciphertext in CIPHER.  */
1042 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
1043                                       gpgme_encrypt_flags_t flags,
1044                                       gpgme_data_t plain, gpgme_data_t cipher);
1045 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1046                                 gpgme_encrypt_flags_t flags,
1047                                 gpgme_data_t plain, gpgme_data_t cipher);
1048
1049 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1050    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1051    with the signers in CTX.  */
1052 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1053                                            gpgme_key_t recp[],
1054                                            gpgme_encrypt_flags_t flags,
1055                                            gpgme_data_t plain,
1056                                            gpgme_data_t cipher);
1057 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1058                                      gpgme_encrypt_flags_t flags,
1059                                      gpgme_data_t plain, gpgme_data_t cipher);
1060
1061 \f
1062 /* Decryption.  */
1063 struct _gpgme_op_decrypt_result
1064 {
1065   char *unsupported_algorithm;
1066 };
1067 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1068
1069 /* Retrieve a pointer to the result of the decrypt operation.  */
1070 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1071
1072 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1073    plaintext in PLAIN.  */
1074 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1075                                       gpgme_data_t plain);
1076 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1077                                 gpgme_data_t cipher, gpgme_data_t plain);
1078
1079 /* Decrypt ciphertext CIPHER and make a signature verification within
1080    CTX and store the resulting plaintext in PLAIN.  */
1081 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1082                                              gpgme_data_t cipher,
1083                                              gpgme_data_t plain);
1084 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1085                                        gpgme_data_t plain);
1086
1087 \f
1088 /* Signing.  */
1089 struct _gpgme_new_signature
1090 {
1091   struct _gpgme_new_signature *next;
1092
1093   /* The type of the signature.  */
1094   gpgme_sig_mode_t type;
1095
1096   /* The public key algorithm used to create the signature.  */
1097   gpgme_pubkey_algo_t pubkey_algo;
1098
1099   /* The hash algorithm used to create the signature.  */
1100   gpgme_hash_algo_t hash_algo;
1101
1102   /* Internal to GPGME, do not use.  Must be set to the same value as
1103      CLASS below.  */
1104   unsigned long _obsolete_class;
1105
1106   /* Signature creation time.  */
1107   long int timestamp;
1108
1109   /* The fingerprint of the signature.  */
1110   char *fpr;
1111
1112 #ifdef __cplusplus
1113   unsigned int _obsolete_class_2;
1114 #else
1115   /* Must be set to SIG_CLASS below.  */
1116   unsigned int class _GPGME_DEPRECATED;
1117 #endif
1118
1119   /* Crypto backend specific signature class.  */
1120   unsigned int sig_class;
1121 };
1122 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1123
1124 struct _gpgme_op_sign_result
1125 {
1126   /* The list of invalid signers.  */
1127   gpgme_invalid_key_t invalid_signers;
1128   gpgme_new_signature_t signatures;
1129 };
1130 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1131
1132 /* Retrieve a pointer to the result of the signing operation.  */
1133 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1134
1135 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1136 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1137                                    gpgme_data_t plain, gpgme_data_t sig,
1138                                    gpgme_sig_mode_t mode);
1139 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1140                              gpgme_data_t plain, gpgme_data_t sig,
1141                              gpgme_sig_mode_t mode);
1142
1143 \f
1144 /* Verify.  */
1145 struct _gpgme_sig_notation
1146 {
1147   struct _gpgme_sig_notation *next;
1148
1149   /* If NAME is a null pointer, then VALUE contains a policy URL
1150      rather than a notation.  */
1151   char *name;
1152   char *value;
1153 };
1154 typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
1155
1156 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1157 typedef enum
1158   {
1159     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1160     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1161     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1162     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1163     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1164     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1165     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1166     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1167     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1168     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1169     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1170   }
1171 gpgme_sigsum_t;
1172
1173 struct _gpgme_signature
1174 {
1175   struct _gpgme_signature *next;
1176
1177   /* A summary of the signature status.  */
1178   gpgme_sigsum_t summary;
1179
1180   /* The fingerprint or key ID of the signature.  */
1181   char *fpr;
1182
1183   /* The status of the signature.  */
1184   gpgme_error_t status;
1185
1186   /* Notation data and policy URLs.  */
1187   gpgme_sig_notation_t notations;
1188
1189   /* Signature creation time.  */
1190   unsigned long timestamp;
1191
1192   /* Signature exipration time or 0.  */
1193   unsigned long exp_timestamp;
1194
1195   unsigned int wrong_key_usage : 1;
1196
1197   /* Internal to GPGME, do not use.  */
1198   int _unused : 31;
1199
1200   gpgme_validity_t validity;
1201   gpgme_error_t validity_reason;
1202 };
1203 typedef struct _gpgme_signature *gpgme_signature_t;
1204
1205 struct _gpgme_op_verify_result
1206 {
1207   gpgme_signature_t signatures;
1208 };
1209 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1210
1211 /* Retrieve a pointer to the result of the verify operation.  */
1212 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1213
1214 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1215 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1216                                      gpgme_data_t signed_text,
1217                                      gpgme_data_t plaintext);
1218 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1219                                gpgme_data_t signed_text,
1220                                gpgme_data_t plaintext);
1221
1222 \f
1223 /* Import.  */
1224 enum
1225   {
1226     /* The key was new.  */
1227     GPGME_IMPORT_NEW = 1,
1228
1229     /* The key contained new user IDs.  */
1230     GPGME_IMPORT_UID = 2,
1231
1232     /* The key contained new signatures.  */
1233     GPGME_IMPORT_SIG = 4,
1234
1235     /* The key contained new sub keys.  */
1236     GPGME_IMPORT_SUBKEY = 8,
1237
1238     /* The key contained a secret key.  */
1239     GPGME_IMPORT_SECRET = 16
1240   };
1241
1242 struct _gpgme_import_status
1243 {
1244   struct _gpgme_import_status *next;
1245
1246   /* Fingerprint.  */
1247   char *fpr;
1248
1249   /* If a problem occured, the reason why the key could not be
1250      imported.  Otherwise GPGME_No_Error.  */
1251   gpgme_error_t result;
1252
1253   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1254      ORed.  0 means the key was already known and no new components
1255      have been added.  */
1256   unsigned int status;
1257 };
1258 typedef struct _gpgme_import_status *gpgme_import_status_t;
1259
1260 /* Import.  */
1261 struct _gpgme_op_import_result
1262 {
1263   /* Number of considered keys.  */
1264   int considered;
1265
1266   /* Keys without user ID.  */
1267   int no_user_id;
1268
1269   /* Imported keys.  */
1270   int imported;
1271
1272   /* Imported RSA keys.  */
1273   int imported_rsa;
1274
1275   /* Unchanged keys.  */
1276   int unchanged;
1277
1278   /* Number of new user ids.  */
1279   int new_user_ids;
1280
1281   /* Number of new sub keys.  */
1282   int new_sub_keys;
1283
1284   /* Number of new signatures.  */
1285   int new_signatures;
1286
1287   /* Number of new revocations.  */
1288   int new_revocations;
1289
1290   /* Number of secret keys read.  */
1291   int secret_read;
1292
1293   /* Number of secret keys imported.  */
1294   int secret_imported;
1295
1296   /* Number of secret keys unchanged.  */
1297   int secret_unchanged;
1298
1299   /* Number of new keys skipped.  */
1300   int skipped_new_keys;
1301
1302   /* Number of keys not imported.  */
1303   int not_imported;
1304
1305   /* List of keys for which an import was attempted.  */
1306   gpgme_import_status_t imports;
1307 };
1308 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1309
1310 /* Retrieve a pointer to the result of the import operation.  */
1311 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1312
1313 /* Import the key in KEYDATA into the keyring.  */
1314 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1315 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1316 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
1317                                    int *nr) _GPGME_DEPRECATED;
1318
1319 \f
1320 /* Export the keys found by PATTERN into KEYDATA.  */
1321 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1322                                      unsigned int reserved,
1323                                      gpgme_data_t keydata);
1324 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1325                                unsigned int reserved, gpgme_data_t keydata);
1326
1327 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1328                                          const char *pattern[],
1329                                          unsigned int reserved,
1330                                          gpgme_data_t keydata);
1331 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1332                                    unsigned int reserved,
1333                                    gpgme_data_t keydata);
1334
1335 \f
1336 /* Key generation.  */
1337 struct _gpgme_op_genkey_result
1338 {
1339   /* A primary key was generated.  */
1340   unsigned int primary : 1;
1341
1342   /* A sub key was generated.  */
1343   unsigned int sub : 1;
1344
1345   /* Internal to GPGME, do not use.  */
1346   unsigned int _unused : 30;
1347
1348   /* The fingerprint of the generated key.  */
1349   char *fpr;
1350 };
1351 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1352
1353 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1354    SECKEY should be null for now.  PARMS specifies what keys should be
1355    generated.  */
1356 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1357                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1358 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1359                                gpgme_data_t pubkey, gpgme_data_t seckey);
1360
1361 /* Retrieve a pointer to the result of the genkey operation.  */
1362 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1363
1364 \f
1365 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1366    keys are also deleted.  */
1367 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1368                                      int allow_secret);
1369 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1370                                int allow_secret);
1371
1372 \f
1373 /* Edit the key KEY.  Send status and command requests to FNC and
1374    output of edit commands to OUT.  */
1375 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1376                                    gpgme_edit_cb_t fnc, void *fnc_value,
1377                                    gpgme_data_t out);
1378 gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1379                              gpgme_edit_cb_t fnc, void *fnc_value,
1380                              gpgme_data_t out);
1381
1382 /* Edit the card for the key KEY.  Send status and command requests to
1383    FNC and output of edit commands to OUT.  */
1384 gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1385                                         gpgme_edit_cb_t fnc, void *fnc_value,
1386                                         gpgme_data_t out);
1387 gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1388                                   gpgme_edit_cb_t fnc, void *fnc_value,
1389                                   gpgme_data_t out);
1390
1391 \f
1392 /* Key management functions.  */
1393 struct _gpgme_op_keylist_result
1394 {
1395   unsigned int truncated : 1;
1396
1397   /* Internal to GPGME, do not use.  */
1398   unsigned int _unused : 31;
1399 };
1400 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
1401
1402 /* Retrieve a pointer to the result of the key listing operation.  */
1403 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
1404
1405 /* Start a keylist operation within CTX, searching for keys which
1406    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1407    returned.  */
1408 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
1409                                       int secret_only);
1410 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
1411                                           const char *pattern[],
1412                                           int secret_only, int reserved);
1413
1414 /* Return the next key from the keylist in R_KEY.  */
1415 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
1416
1417 /* Terminate a pending keylist operation within CTX.  */
1418 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
1419
1420 \f
1421 /* Trust items and operations.  */
1422
1423 struct _gpgme_trust_item
1424 {
1425   /* Internal to GPGME, do not use.  */
1426   unsigned int _refs;
1427
1428   /* The key ID to which the trust item belongs.  */
1429   char *keyid;
1430
1431   /* Internal to GPGME, do not use.  */
1432   char _keyid[16 + 1];
1433
1434   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1435   int type;
1436
1437   /* The trust level.  */
1438   int level;
1439
1440   /* The owner trust if TYPE is 1.  */
1441   char *owner_trust;
1442
1443   /* Internal to GPGME, do not use.  */
1444   char _owner_trust[2];
1445
1446   /* The calculated validity.  */
1447   char *validity;
1448  
1449   /* Internal to GPGME, do not use.  */
1450   char _validity[2];
1451
1452   /* The user name if TYPE is 2.  */
1453   char *name;
1454 };
1455 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
1456
1457 /* Start a trustlist operation within CTX, searching for trust items
1458    which match PATTERN.  */
1459 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
1460                                         const char *pattern, int max_level);
1461
1462 /* Return the next trust item from the trustlist in R_ITEM.  */
1463 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
1464                                        gpgme_trust_item_t *r_item);
1465
1466 /* Terminate a pending trustlist operation within CTX.  */
1467 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
1468
1469 /* Acquire a reference to ITEM.  */
1470 void gpgme_trust_item_ref (gpgme_trust_item_t item);
1471
1472 /* Release a reference to ITEM.  If this was the last one the trust
1473    item is destroyed.  */
1474 void gpgme_trust_item_unref (gpgme_trust_item_t item);
1475
1476 /* Release the trust item ITEM.  Deprecated, use
1477    gpgme_trust_item_unref.  */
1478 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED;
1479
1480 /* Return the value of the attribute WHAT of ITEM, which has to be
1481    representable by a string.  Deprecated, use trust item structure
1482    directly.  */
1483 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
1484                                               _gpgme_attr_t what,
1485                                               const void *reserved, int idx)
1486      _GPGME_DEPRECATED;
1487
1488 /* Return the value of the attribute WHAT of KEY, which has to be
1489    representable by an integer.  IDX specifies a running index if the
1490    attribute appears more than once in the key.  Deprecated, use trust
1491    item structure directly.  */
1492 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
1493                                    const void *reserved, int idx)
1494      _GPGME_DEPRECATED;
1495
1496 \f
1497 /* Various functions.  */
1498
1499 /* Check that the library fulfills the version requirement.  */
1500 const char *gpgme_check_version (const char *req_version);
1501
1502 /* Retrieve information about the backend engines.  */
1503 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
1504
1505 \f
1506 /* Engine support functions.  */
1507
1508 /* Verify that the engine implementing PROTO is installed and
1509    available.  */
1510 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
1511
1512 \f
1513 /* Deprecated types.  */
1514 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED;
1515 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED;
1516 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED;
1517 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED;
1518 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED;
1519 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED;
1520 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED;
1521 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED;
1522 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED;
1523 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED;
1524 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED;
1525 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED;
1526 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED;
1527 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED;
1528 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED;
1529 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED;
1530 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED;
1531 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED;
1532 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED;
1533 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED;
1534 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED;
1535 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED;
1536 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED;
1537 #define GpgmeIOCbs gpgme_io_cbs
1538 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED;
1539 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED;
1540 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED;
1541 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED;
1542 #define GpgmeDataCbs gpgme_data_cbs
1543 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED;
1544 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED;
1545 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED;
1546 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED;
1547 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED;
1548 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED;
1549 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED;
1550 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED;
1551 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED;
1552
1553 #ifdef __cplusplus
1554 }
1555 #endif
1556 #endif /* GPGME_H */