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