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