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