doc/
[gpgme.git] / gpgme / gpgme.h
1 /* gpgme.h - Public interface to GnuPG Made Easy.
2    Copyright (C) 2000 Werner Koch (dd9jn)
3    Copyright (C) 2001, 2002, 2003 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 FILE *.  */
25 #ifdef _MSC_VER
26   typedef long off_t;
27   typedef long ssize_t;
28 #else
29 # include <sys/types.h>
30 #endif
31
32 #ifdef __cplusplus
33 extern "C" {
34 #if 0 /* just to make Emacs auto-indent happy */
35 }
36 #endif
37 #endif
38
39
40 /* The version of this header should match the one of the library.  Do
41    not use this symbol in your application, use gpgme_check_version
42    instead.  The purpose of this macro is to let autoconf (using the
43    AM_PATH_GPGME macro) check that this header matches the installed
44    library.  Warning: Do not edit the next line.  configure will do
45    that for you!  */
46 #define GPGME_VERSION "0.4.1"
47
48
49 /* The opaque data types used by GPGME.  */
50
51 /* The context holds some global state and configration options as
52    well as the results of a crypto operation.  */
53 struct gpgme_context_s;
54 typedef struct gpgme_context_s *GpgmeCtx;
55
56 /* The data object used by GPGME to exchange arbitrary data.  */
57 struct gpgme_data_s;
58 typedef struct gpgme_data_s *GpgmeData;
59
60 /* A list of recipients to be used in an encryption operation.  */
61 struct gpgme_recipients_s;
62 typedef struct gpgme_recipients_s *GpgmeRecipients;
63
64 /* A key from the keyring.  */
65 struct gpgme_key_s;
66 typedef struct gpgme_key_s *GpgmeKey;
67
68 /* A trust item.  */
69 struct gpgme_trust_item_s;
70 typedef struct gpgme_trust_item_s *GpgmeTrustItem;
71
72
73 /* The error numbers used by GPGME.  */
74 typedef enum
75   {
76     GPGME_EOF                     = -1,
77     GPGME_No_Error                = 0x0000,
78     GPGME_General_Error           = 0x0001,
79     GPGME_Out_Of_Core             = 0x0002,
80     GPGME_Invalid_Value           = 0x0003,
81     GPGME_Exec_Error              = 0x0004,
82     GPGME_Too_Many_Procs          = 0x0005,
83     GPGME_Pipe_Error              = 0x0006,
84     GPGME_No_Data                 = 0x0007,
85     GPGME_Conflict                = 0x0008,
86     GPGME_Not_Implemented         = 0x0009,
87     GPGME_Read_Error              = 0x000a,
88     GPGME_Write_Error             = 0x000b,
89     GPGME_Invalid_Type            = 0x000c,
90     GPGME_Invalid_Mode            = 0x000d,
91     GPGME_File_Error              = 0x000e, /* errno is set in this case.  */
92     GPGME_Decryption_Failed       = 0x000f,
93     GPGME_Bad_Passphrase          = 0x0010,
94     GPGME_Canceled                = 0x0011,
95     GPGME_Invalid_Key             = 0x0012,
96     GPGME_Invalid_Engine          = 0x0013,
97     GPGME_No_UserID               = 0x0014,
98     GPGME_Invalid_UserID          = 0x0015,
99
100     /* Reasons for invalid user id.  */
101     GPGME_Unknown_Reason          = 0x0100,
102     GPGME_Not_Found               = 0x0101,
103     GPGME_Ambiguous_Specification = 0x0102,
104     GPGME_Wrong_Key_Usage         = 0x0103,
105     GPGME_Key_Revoked             = 0x0104,
106     GPGME_Key_Expired             = 0x0105,
107     GPGME_No_CRL_Known            = 0x0106,
108     GPGME_CRL_Too_Old             = 0x0107,
109     GPGME_Policy_Mismatch         = 0x0108,
110     GPGME_No_Secret_Key           = 0x0109,
111     GPGME_Key_Not_Trusted         = 0x010a,
112     
113     /* Import problems.  */
114     GPGME_Issuer_Missing          = 0x0200,
115     GPGME_Chain_Too_Long          = 0x0201,
116
117     /* Verification problems.  */
118     GPGME_Unsupported_Algorithm   = 0x0300,
119     GPGME_Sig_Expired             = 0x0301,
120     GPGME_Bad_Signature           = 0x0302,
121     GPGME_No_Public_Key           = 0x0303,
122
123     /* Deprecated.  */
124     GPGME_Busy                    = -2,
125     GPGME_No_Request              = -3
126   }
127 GpgmeError;
128
129 #define GPGME_No_Recipients     GPGME_No_UserID
130 #define GPGME_Invalid_Recipient GPGME_Invalid_UserID
131 #define GPGME_No_Passphrase     GPGME_Bad_Passphrase
132
133 /* The possible types of GpgmeData objects.  */
134 typedef enum
135   {
136     GPGME_DATA_TYPE_NONE = 0,
137     GPGME_DATA_TYPE_MEM  = 1,
138     GPGME_DATA_TYPE_FD   = 2,
139     GPGME_DATA_TYPE_FILE = 3,
140     GPGME_DATA_TYPE_CB   = 4
141   }
142 GpgmeDataType;
143
144 /* The possible encoding mode of GpgmeData objects.  */
145 typedef enum
146   {
147     GPGME_DATA_ENCODING_NONE   = 0,     /* I.e. not specified.  */
148     GPGME_DATA_ENCODING_BINARY = 1,
149     GPGME_DATA_ENCODING_BASE64 = 2,
150     GPGME_DATA_ENCODING_ARMOR  = 3      /* Either PEM or OpenPGP Armor.  */
151   }
152 GpgmeDataEncoding;
153
154 /* The possible signature stati.  */
155 typedef enum
156   {
157     GPGME_SIG_STAT_NONE  = 0,
158     GPGME_SIG_STAT_GOOD  = 1,
159     GPGME_SIG_STAT_BAD   = 2,
160     GPGME_SIG_STAT_NOKEY = 3,
161     GPGME_SIG_STAT_NOSIG = 4,
162     GPGME_SIG_STAT_ERROR = 5,
163     GPGME_SIG_STAT_DIFF  = 6,
164     GPGME_SIG_STAT_GOOD_EXP = 7,
165     GPGME_SIG_STAT_GOOD_EXPKEY = 8
166   }
167 GpgmeSigStat;
168
169 /* Flags used with the GPGME_ATTR_SIG_SUMMARY.  */
170 enum 
171   {
172     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
173     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
174     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
175     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
176     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
177     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
178     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
179     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
180     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
181     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
182     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
183   };
184
185
186 /* The available signature modes.  */
187 typedef enum
188   {
189     GPGME_SIG_MODE_NORMAL = 0,
190     GPGME_SIG_MODE_DETACH = 1,
191     GPGME_SIG_MODE_CLEAR  = 2
192   }
193 GpgmeSigMode;
194
195 /* The available key and signature attributes.  */
196 typedef enum
197   {
198     GPGME_ATTR_KEYID        = 1,
199     GPGME_ATTR_FPR          = 2,
200     GPGME_ATTR_ALGO         = 3,
201     GPGME_ATTR_LEN          = 4,
202     GPGME_ATTR_CREATED      = 5,
203     GPGME_ATTR_EXPIRE       = 6,
204     GPGME_ATTR_OTRUST       = 7,
205     GPGME_ATTR_USERID       = 8,
206     GPGME_ATTR_NAME         = 9,
207     GPGME_ATTR_EMAIL        = 10,
208     GPGME_ATTR_COMMENT      = 11,
209     GPGME_ATTR_VALIDITY     = 12,
210     GPGME_ATTR_LEVEL        = 13,
211     GPGME_ATTR_TYPE         = 14,
212     GPGME_ATTR_IS_SECRET    = 15,
213     GPGME_ATTR_KEY_REVOKED  = 16,
214     GPGME_ATTR_KEY_INVALID  = 17,
215     GPGME_ATTR_UID_REVOKED  = 18,
216     GPGME_ATTR_UID_INVALID  = 19,
217     GPGME_ATTR_KEY_CAPS     = 20,
218     GPGME_ATTR_CAN_ENCRYPT  = 21,
219     GPGME_ATTR_CAN_SIGN     = 22,
220     GPGME_ATTR_CAN_CERTIFY  = 23,
221     GPGME_ATTR_KEY_EXPIRED  = 24,
222     GPGME_ATTR_KEY_DISABLED = 25,
223     GPGME_ATTR_SERIAL       = 26,
224     GPGME_ATTR_ISSUER       = 27,
225     GPGME_ATTR_CHAINID      = 28,
226     GPGME_ATTR_SIG_STATUS   = 29,
227     GPGME_ATTR_ERRTOK       = 30,
228     GPGME_ATTR_SIG_SUMMARY  = 31,
229     GPGME_ATTR_SIG_CLASS    = 32
230   }
231 GpgmeAttr;
232
233 /* The available validities for a trust item or key.  */
234 typedef enum
235   {
236     GPGME_VALIDITY_UNKNOWN   = 0,
237     GPGME_VALIDITY_UNDEFINED = 1,
238     GPGME_VALIDITY_NEVER     = 2,
239     GPGME_VALIDITY_MARGINAL  = 3,
240     GPGME_VALIDITY_FULL      = 4,
241     GPGME_VALIDITY_ULTIMATE  = 5
242   }
243 GpgmeValidity;
244
245 /* The available protocols.  */
246 typedef enum
247   {
248     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
249     GPGME_PROTOCOL_CMS     = 1,
250   }
251 GpgmeProtocol;
252
253 \f
254 /* The possible stati for the edit operation.  */
255 typedef enum
256   {
257     GPGME_STATUS_EOF,
258     /* mkstatus processing starts here */
259     GPGME_STATUS_ENTER,
260     GPGME_STATUS_LEAVE,
261     GPGME_STATUS_ABORT,
262
263     GPGME_STATUS_GOODSIG,
264     GPGME_STATUS_BADSIG,
265     GPGME_STATUS_ERRSIG,
266
267     GPGME_STATUS_BADARMOR,
268
269     GPGME_STATUS_RSA_OR_IDEA,
270     GPGME_STATUS_KEYEXPIRED,
271     GPGME_STATUS_KEYREVOKED,
272
273     GPGME_STATUS_TRUST_UNDEFINED,
274     GPGME_STATUS_TRUST_NEVER,
275     GPGME_STATUS_TRUST_MARGINAL,
276     GPGME_STATUS_TRUST_FULLY,
277     GPGME_STATUS_TRUST_ULTIMATE,
278
279     GPGME_STATUS_SHM_INFO,
280     GPGME_STATUS_SHM_GET,
281     GPGME_STATUS_SHM_GET_BOOL,
282     GPGME_STATUS_SHM_GET_HIDDEN,
283
284     GPGME_STATUS_NEED_PASSPHRASE,
285     GPGME_STATUS_VALIDSIG,
286     GPGME_STATUS_SIG_ID,
287     GPGME_STATUS_ENC_TO,
288     GPGME_STATUS_NODATA,
289     GPGME_STATUS_BAD_PASSPHRASE,
290     GPGME_STATUS_NO_PUBKEY,
291     GPGME_STATUS_NO_SECKEY,
292     GPGME_STATUS_NEED_PASSPHRASE_SYM,
293     GPGME_STATUS_DECRYPTION_FAILED,
294     GPGME_STATUS_DECRYPTION_OKAY,
295     GPGME_STATUS_MISSING_PASSPHRASE,
296     GPGME_STATUS_GOOD_PASSPHRASE,
297     GPGME_STATUS_GOODMDC,
298     GPGME_STATUS_BADMDC,
299     GPGME_STATUS_ERRMDC,
300     GPGME_STATUS_IMPORTED,
301     GPGME_STATUS_IMPORT_OK,
302     GPGME_STATUS_IMPORT_PROBLEM,
303     GPGME_STATUS_IMPORT_RES,
304     GPGME_STATUS_FILE_START,
305     GPGME_STATUS_FILE_DONE,
306     GPGME_STATUS_FILE_ERROR,
307
308     GPGME_STATUS_BEGIN_DECRYPTION,
309     GPGME_STATUS_END_DECRYPTION,
310     GPGME_STATUS_BEGIN_ENCRYPTION,
311     GPGME_STATUS_END_ENCRYPTION,
312
313     GPGME_STATUS_DELETE_PROBLEM,
314     GPGME_STATUS_GET_BOOL,
315     GPGME_STATUS_GET_LINE,
316     GPGME_STATUS_GET_HIDDEN,
317     GPGME_STATUS_GOT_IT,
318     GPGME_STATUS_PROGRESS,
319     GPGME_STATUS_SIG_CREATED,
320     GPGME_STATUS_SESSION_KEY,
321     GPGME_STATUS_NOTATION_NAME,
322     GPGME_STATUS_NOTATION_DATA,
323     GPGME_STATUS_POLICY_URL,
324     GPGME_STATUS_BEGIN_STREAM,
325     GPGME_STATUS_END_STREAM,
326     GPGME_STATUS_KEY_CREATED,
327     GPGME_STATUS_USERID_HINT,
328     GPGME_STATUS_UNEXPECTED,
329     GPGME_STATUS_INV_RECP,
330     GPGME_STATUS_NO_RECP,
331     GPGME_STATUS_ALREADY_SIGNED,
332     GPGME_STATUS_SIGEXPIRED,
333     GPGME_STATUS_EXPSIG,
334     GPGME_STATUS_EXPKEYSIG,
335     GPGME_STATUS_TRUNCATED,
336     GPGME_STATUS_ERROR
337   }
338 GpgmeStatusCode;
339
340 /* The available keylist mode flags.  */
341 #define GPGME_KEYLIST_MODE_LOCAL  1
342 #define GPGME_KEYLIST_MODE_EXTERN 2
343 #define GPGME_KEYLIST_MODE_SIGS   4
344
345 /* The engine information structure.  */
346 struct _gpgme_engine_info
347 {
348   struct _gpgme_engine_info *next;
349
350   /* The protocol ID.  */
351   GpgmeProtocol protocol;
352
353   /* The file name of the engine binary.  */
354   const char *file_name;
355
356   /* The version string of the installed engine.  */
357   const char *version;
358
359   /* The minimum version required for GPGME.  */
360   const char *req_version;
361 };
362 typedef struct _gpgme_engine_info *GpgmeEngineInfo;
363
364
365 /* Types for callback functions.  */
366
367 /* Request a passphrase from the user.  */
368 typedef GpgmeError (*GpgmePassphraseCb) (void *hook, const char *desc,
369                                          void **r_hd, const char **result);
370
371 /* Inform the user about progress made.  */
372 typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
373                                  int type, int current, int total);
374
375 /* Interact with the user about an edit operation.  */
376 typedef GpgmeError (*GpgmeEditCb) (void *opaque, GpgmeStatusCode status,
377                                    const char *args, const char **reply);
378
379 /* Context management functions.  */
380
381 /* Create a new context and return it in CTX.  */
382 GpgmeError gpgme_new (GpgmeCtx *ctx);
383
384 /* Release the context CTX.  */
385 void gpgme_release (GpgmeCtx ctx);
386
387 /* Retrieve more info about performed signature check.  */
388 char *gpgme_get_notation (GpgmeCtx ctx);
389
390 /* Set the protocol to be used by CTX to PROTO.  */
391 GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
392
393 /* Get the protocol used with CTX */
394 GpgmeProtocol gpgme_get_protocol (GpgmeCtx ctx);
395
396 /* Get the string describing protocol PROTO, or NULL if invalid.  */
397 const char *gpgme_get_protocol_name (GpgmeProtocol proto);
398
399 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
400 void gpgme_set_armor (GpgmeCtx ctx, int yes);
401
402 /* Return non-zero if armor mode is set in CTX.  */
403 int gpgme_get_armor (GpgmeCtx ctx);
404
405 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
406 void gpgme_set_textmode (GpgmeCtx ctx, int yes);
407
408 /* Return non-zero if text mode is set in CTX.  */
409 int gpgme_get_textmode (GpgmeCtx ctx);
410
411 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
412 void gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs);
413
414 /* Return the number of certs to include in an S/MIME message.  */
415 int gpgme_get_include_certs (GpgmeCtx ctx);
416
417 /* Set keylist mode in CTX to MODE.  */
418 GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
419
420 /* Get keylist mode in CTX.  */
421 int gpgme_get_keylist_mode (GpgmeCtx ctx);
422
423 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
424    passed as first argument to the passphrase callback function.  */
425 void gpgme_set_passphrase_cb (GpgmeCtx ctx,
426                               GpgmePassphraseCb cb, void *hook_value);
427
428 /* Get the current passphrase callback function in *CB and the current
429    hook value in *HOOK_VALUE.  */
430 void gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *cb,
431                               void **hook_value);
432
433 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
434    passed as first argument to the progress callback function.  */
435 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
436
437 /* Get the current progress callback function in *CB and the current
438    hook value in *HOOK_VALUE.  */
439 void gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *cb,
440                             void **hook_value);
441
442 /* Delete all signers from CTX.  */
443 void gpgme_signers_clear (GpgmeCtx ctx);
444
445 /* Add KEY to list of signers in CTX.  */
446 GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
447
448 /* Return the SEQth signer's key in CTX.  */
449 GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
450
451 /* Retrieve the signature status of signature IDX in CTX after a
452    successful verify operation in R_STAT (if non-null).  The creation
453    time stamp of the signature is returned in R_CREATED (if non-null).
454    The function returns a string containing the fingerprint.  */
455 const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
456                                   GpgmeSigStat *r_stat, time_t *r_created);
457
458 /* Retrieve certain attributes of a signature.  IDX is the index
459    number of the signature after a successful verify operation.  WHAT
460    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
461    one.  WHATIDX is to be passed as 0 for most attributes . */
462 unsigned long gpgme_get_sig_ulong_attr (GpgmeCtx c, int idx,
463                                         GpgmeAttr what, int whatidx);
464 const char *gpgme_get_sig_string_attr (GpgmeCtx c, int idx,
465                                       GpgmeAttr what, int whatidx);
466
467
468 /* Get the key used to create signature IDX in CTX and return it in
469    R_KEY.  */
470 GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
471
472 /* Return a string with more info about the last crypto operating in CTX.
473    RESERVED should be zero.  The user has to free the string.  */
474 char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
475
476
477 /* Run control.  */
478
479 /* The type of an I/O callback function.  */
480 typedef GpgmeError (*GpgmeIOCb) (void *data, int fd);
481
482 /* The type of a function that can register FNC as the I/O callback
483    function for the file descriptor FD with direction dir (0: for writing,
484    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
485    function should return a TAG suitable for the corresponding
486    GpgmeRemoveIOCb, and an error value.  */
487 typedef GpgmeError (*GpgmeRegisterIOCb) (void *data, int fd, int dir,
488                                          GpgmeIOCb fnc, void *fnc_data,
489                                          void **tag);
490
491 /* The type of a function that can remove a previously registered I/O
492    callback function given TAG as returned by the register
493    function.  */
494 typedef void (*GpgmeRemoveIOCb) (void *tag);
495
496 typedef enum { GPGME_EVENT_START,
497                GPGME_EVENT_DONE,
498                GPGME_EVENT_NEXT_KEY,
499                GPGME_EVENT_NEXT_TRUSTITEM } GpgmeEventIO;
500
501 /* The type of a function that is called when a context finished an
502    operation.  */
503 typedef void (*GpgmeEventIOCb) (void *data, GpgmeEventIO type,
504                                 void *type_data);
505
506 struct GpgmeIOCbs
507 {
508   GpgmeRegisterIOCb add;
509   void *add_priv;
510   GpgmeRemoveIOCb remove;
511   GpgmeEventIOCb event;
512   void *event_priv;
513 };
514
515 /* Set the I/O callback functions in CTX to IO_CBS.  */
516 void gpgme_set_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
517
518 /* Get the current I/O callback functions.  */
519 void gpgme_get_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
520
521 /* Process the pending operation and, if HANG is non-zero, wait for
522    the pending operation to finish.  */
523 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
524
525
526 /* Functions to handle recipients.  */
527
528 /* Create a new recipients set and return it in R_RSET.  */
529 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
530
531 /* Release the recipients set RSET.  */
532 void gpgme_recipients_release (GpgmeRecipients rset);
533
534 /* Add NAME to the recipients set RSET.  */
535 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
536
537 /* Add NAME with validity AL to the recipients set RSET.  */
538 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
539                                                     const char *name,
540                                                     GpgmeValidity val);
541
542 /* Return the number of recipients in RSET.  */
543 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
544
545 /* Create a new enumeration handle for the recipients set RSET and
546    return it in ITER.  */
547 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
548                                        void **iter);
549
550 /* Return the next recipient from the recipient set RSET in the
551    enumerator ITER.  */
552 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
553                                         void **iter);
554
555 /* Destroy the enumerator ITER for the recipient set RSET.  */
556 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
557                                         void **iter);
558
559
560 /* Functions to handle data objects.  */
561
562 /* Read up to SIZE bytes into buffer BUFFER from the data object with
563    the handle HANDLE.  Return the number of characters read, 0 on EOF
564    and -1 on error.  If an error occurs, errno is set.  */
565 typedef ssize_t (*GpgmeDataReadCb) (void *handle, void *buffer, size_t size);
566
567 /* Write up to SIZE bytes from buffer BUFFER to the data object with
568    the handle HANDLE.  Return the number of characters written, or -1
569    on error.  If an error occurs, errno is set.  */
570 typedef ssize_t (*GpgmeDataWriteCb) (void *handle, const void *buffer,
571                                      size_t size);
572
573 /* Set the current position from where the next read or write starts
574    in the data object with the handle HANDLE to OFFSET, relativ to
575    WHENCE.  */
576 typedef off_t (*GpgmeDataSeekCb) (void *handle, off_t offset, int whence);
577
578 /* Close the data object with the handle DL.  */
579 typedef void (*GpgmeDataReleaseCb) (void *handle);
580
581 struct GpgmeDataCbs
582 {
583   GpgmeDataReadCb read;
584   GpgmeDataWriteCb write;
585   GpgmeDataSeekCb seek;
586   GpgmeDataReleaseCb release;
587 };
588
589 /* Read up to SIZE bytes into buffer BUFFER from the data object with
590    the handle DH.  Return the number of characters read, 0 on EOF and
591    -1 on error.  If an error occurs, errno is set.  */
592 ssize_t gpgme_data_read (GpgmeData dh, void *buffer, size_t size);
593
594 /* Write up to SIZE bytes from buffer BUFFER to the data object with
595    the handle DH.  Return the number of characters written, or -1 on
596    error.  If an error occurs, errno is set.  */
597 ssize_t gpgme_data_write (GpgmeData dh, const void *buffer, size_t size);
598
599 /* Set the current position from where the next read or write starts
600    in the data object with the handle DH to OFFSET, relativ to
601    WHENCE.  */
602 off_t gpgme_data_seek (GpgmeData dh, off_t offset, int whence);
603
604 /* Create a new data buffer and return it in R_DH.  */
605 GpgmeError gpgme_data_new (GpgmeData *r_dh);
606
607 /* Destroy the data buffer DH.  */
608 void gpgme_data_release (GpgmeData dh);
609
610 /* Create a new data buffer filled with SIZE bytes starting from
611    BUFFER.  If COPY is zero, copying is delayed until necessary, and
612    the data is taken from the original location when needed.  */
613 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
614                                     const char *buffer, size_t size,
615                                     int copy);
616
617 /* Destroy the data buffer DH and return a pointer to its content.
618    The memory has be to released with free by the user.  It's size is
619    returned in R_LEN.  */
620 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
621
622 GpgmeError gpgme_data_new_from_cbs (GpgmeData *dh,
623                                     struct GpgmeDataCbs *cbs,
624                                     void *handle);
625
626 GpgmeError gpgme_data_new_from_fd (GpgmeData *dh, int fd);
627
628 GpgmeError gpgme_data_new_from_stream (GpgmeData *dh, FILE *stream);
629
630 /* Return the encoding attribute of the data buffer DH */
631 GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh);
632
633 /* Set the encoding attribute of data buffer DH to ENC */
634 GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc);
635
636
637
638 /* Create a new data buffer which retrieves the data from the callback
639    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
640    instead.  */
641 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
642                                         int (*read_cb) (void*,char *,size_t,size_t*),
643                                         void *read_cb_value);
644
645 /* Create a new data buffer filled with the content of file FNAME.
646    COPY must be non-zero.  For delayed read, please use
647    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
648 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
649                                      const char *fname,
650                                      int copy);
651
652 /* Create a new data buffer filled with LENGTH bytes starting from
653    OFFSET within the file FNAME or stream FP (exactly one must be
654    non-zero).  */
655 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
656                                          const char *fname, FILE *fp,
657                                          off_t offset, size_t length);
658
659 /* Reset the read pointer in DH.  Deprecated, please use
660    gpgme_data_seek instead.  */
661 GpgmeError gpgme_data_rewind (GpgmeData dh);
662
663
664 /* Key and trust functions.  */
665
666 /* Get the key with the fingerprint FPR from the key cache or from the
667    crypto backend.  If FORCE_UPDATE is true, force a refresh of the
668    key from the crypto backend and replace the key in the cache, if
669    any.  If SECRET is true, get the secret key.  */
670 GpgmeError gpgme_get_key (GpgmeCtx ctx, const char *fpr, GpgmeKey *r_key,
671                           int secret, int force_update);
672
673 /* Acquire a reference to KEY.  */
674 void gpgme_key_ref (GpgmeKey key);
675
676 /* Release a reference to KEY.  If this was the last one the key is
677    destroyed.  */
678 void gpgme_key_unref (GpgmeKey key);
679 void gpgme_key_release (GpgmeKey key);
680
681 /* Get the data from key KEY in a XML string, which has to be released
682    with free by the user.  */
683 char *gpgme_key_get_as_xml (GpgmeKey key);
684
685 /* Return the value of the attribute WHAT of KEY, which has to be
686    representable by a string.  IDX specifies the sub key or
687    user ID for attributes related to sub keys or user IDs.  */
688 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
689                                        const void *reserved, int idx);
690
691 /* Return the value of the attribute WHAT of KEY, which has to be
692    representable by an unsigned integer.  IDX specifies the sub key or
693    user ID for attributes related to sub keys or user IDs.  */
694 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
695                                         const void *reserved, int idx);
696
697 /* Return the value of the attribute WHAT of a signature on user ID
698    UID_IDX in KEY, which has to be representable by a string.  IDX
699    specifies the signature.  */
700 const char *gpgme_key_sig_get_string_attr (GpgmeKey key, int uid_idx,
701                                            GpgmeAttr what,
702                                            const void *reserved, int idx);
703
704 /* Return the value of the attribute WHAT of a signature on user ID
705    UID_IDX in KEY, which has to be representable by an unsigned
706    integer string.  IDX specifies the signature.  */
707 unsigned long gpgme_key_sig_get_ulong_attr (GpgmeKey key, int uid_idx,
708                                             GpgmeAttr what,
709                                             const void *reserved, int idx);
710
711
712 /* Release the trust item ITEM.  */
713 void gpgme_trust_item_release (GpgmeTrustItem item);
714
715 /* Return the value of the attribute WHAT of ITEM, which has to be
716    representable by a string.  */
717 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
718                                               GpgmeAttr what,
719                                               const void *reserved, int idx);
720
721 /* Return the value of the attribute WHAT of KEY, which has to be
722    representable by an integer.  IDX specifies a running index if the
723    attribute appears more than once in the key.  */
724 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
725                                    const void *reserved, int idx);
726
727
728 /* Crypto operation function.  */
729
730 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
731    store the resulting ciphertext in CIPHER.  */
732 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
733                                    GpgmeRecipients recp,
734                                    GpgmeData plain, GpgmeData cipher);
735 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
736                              GpgmeRecipients recp,
737                              GpgmeData plain, GpgmeData cipher);
738
739 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
740    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
741    with the signers in CTX.  */
742 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
743                                         GpgmeRecipients recp,
744                                         GpgmeData plain, GpgmeData cipher);
745 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
746                                   GpgmeRecipients recp,
747                                   GpgmeData plain, GpgmeData cipher);
748
749 /* Decrypt ciphertext CIPHER within CTX and store the resulting
750    plaintext in PLAIN.  */
751 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
752                                    GpgmeData cipher, GpgmeData plain);
753 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
754                              GpgmeData cipher, GpgmeData plain);
755
756 /* Decrypt ciphertext CIPHER and make a signature verification within
757    CTX and store the resulting plaintext in PLAIN.  */
758 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
759                                           GpgmeData cipher, GpgmeData plain);
760 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
761                                     GpgmeData cipher, GpgmeData plain);
762
763 /* Sign the plaintext PLAIN and store the signature in SIG.  Only
764    detached signatures are supported for now.  */
765 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
766                                 GpgmeData plain, GpgmeData sig,
767                                 GpgmeSigMode mode);
768 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
769                           GpgmeData plain, GpgmeData sig,
770                           GpgmeSigMode mode);
771
772 /* Verify within CTX that SIG is a valid signature for TEXT.  */
773 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig,
774                                   GpgmeData signed_text, GpgmeData plaintext);
775 GpgmeError gpgme_op_verify (GpgmeCtx ctx, GpgmeData sig,
776                             GpgmeData signed_text, GpgmeData plaintext);
777
778 \f
779 enum
780   {
781     /* The key was new.  */
782     GPGME_IMPORT_NEW = 1,
783
784     /* The key contained new user IDs.  */
785     GPGME_IMPORT_UID = 2,
786
787     /* The key contained new signatures.  */
788     GPGME_IMPORT_SIG = 4,
789
790     /* The key contained new sub keys.  */
791     GPGME_IMPORT_SUBKEY = 8,
792
793     /* The key contained a private key.  */
794     GPGME_IMPORT_PRIVATE = 16
795   };
796
797 struct _gpgme_import_status
798 {
799   struct _gpgme_import_status *next;
800
801   /* Fingerprint.  */
802   char *fpr;
803
804   /* If a problem occured, the reason why the key could not be
805      imported.  Otherwise GPGME_No_Error.  */
806   GpgmeError result;
807
808   /* The result of the import, the GPGME_IMPORT_* values bit-wise
809      ORed.  0 means the key was already known and no new components
810      have been added.  */
811   unsigned int status;
812 };
813 typedef struct _gpgme_import_status *GpgmeImportStatus;
814
815 /* Import.  */
816 struct _gpgme_op_import_result
817 {
818   /* Number of considered keys.  */
819   int considered;
820
821   /* Keys without user ID.  */
822   int no_user_id;
823
824   /* Imported keys.  */
825   int imported;
826
827   /* Imported RSA keys.  */
828   int imported_rsa;
829
830   /* Unchanged keys.  */
831   int unchanged;
832
833   /* Number of new user ids.  */
834   int new_user_ids;
835
836   /* Number of new sub keys.  */
837   int new_sub_keys;
838
839   /* Number of new signatures.  */
840   int new_signatures;
841
842   /* Number of new revocations.  */
843   int new_revocations;
844
845   /* Number of secret keys read.  */
846   int secret_read;
847
848   /* Number of secret keys imported.  */
849   int secret_imported;
850
851   /* Number of secret keys unchanged.  */
852   int secret_unchanged;
853
854   /* Number of keys not imported.  */
855   int not_imported;
856
857   /* List of keys for which an import was attempted.  */
858   GpgmeImportStatus imports;
859 };
860 typedef struct _gpgme_op_import_result *GpgmeImportResult;
861
862 /* Retrieve a pointer to the result of the import operation.  */
863 GpgmeImportResult gpgme_op_import_result (GpgmeCtx ctx);
864
865 /* Import the key in KEYDATA into the keyring.  */
866 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
867 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
868 GpgmeError gpgme_op_import_ext (GpgmeCtx ctx, GpgmeData keydata, int *nr);
869
870 \f
871 /* Export the keys listed in RECP into KEYDATA.  */
872 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
873                                   GpgmeData keydata);
874 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
875                             GpgmeData keydata);
876
877 \f
878 /* Key generation.  */
879 struct _gpgme_op_genkey_result
880 {
881   /* A primary key was generated.  */
882   unsigned int primary : 1;
883
884   /* A sub key was generated.  */
885   unsigned int sub : 1;
886
887   /* Internal to GPGME, do not use.  */
888   unsigned int _unused : 30;
889
890   /* The fingerprint of the generated key.  */
891   char *fpr;
892 };
893 typedef struct _gpgme_op_genkey_result *GpgmeGenKeyResult;
894
895 /* Generate a new keypair and add it to the keyring.  PUBKEY and
896    SECKEY should be null for now.  PARMS specifies what keys should be
897    generated.  */
898 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
899                                   GpgmeData pubkey, GpgmeData seckey);
900 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
901                             GpgmeData pubkey, GpgmeData seckey);
902
903 /* Retrieve a pointer to the result of the genkey operation.  */
904 GpgmeGenKeyResult gpgme_op_genkey_result (GpgmeCtx ctx);
905
906 \f
907 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
908    keys are also deleted.  */
909 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
910                                   int allow_secret);
911 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
912                             int allow_secret);
913
914 /* Edit the key KEY.  Send status and command requests to FNC and
915    output of edit commands to OUT.  */
916 GpgmeError gpgme_op_edit_start (GpgmeCtx ctx, GpgmeKey key,
917                           GpgmeEditCb fnc, void *fnc_value,
918                           GpgmeData out);
919 GpgmeError gpgme_op_edit (GpgmeCtx ctx, GpgmeKey key,
920                           GpgmeEditCb fnc, void *fnc_value,
921                           GpgmeData out);
922
923 /* Key management functions */
924
925 /* Start a keylist operation within CTX, searching for keys which
926    match PATTERN.  If SECRET_ONLY is true, only secret keys are
927    returned.  */
928 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
929                                    const char *pattern, int secret_only);
930 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
931                                        int secret_only, int reserved);
932
933 /* Return the next key from the keylist in R_KEY.  */
934 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
935
936 /* Terminate a pending keylist operation within CTX.  */
937 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
938
939
940 /* Start a trustlist operation within CTX, searching for trust items
941    which match PATTERN.  */
942 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
943                                      const char *pattern, int max_level);
944
945 /* Return the next trust item from the trustlist in R_ITEM.  */
946 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
947
948 /* Terminate a pending trustlist operation within CTX.  */
949 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
950
951
952 /* Various functions.  */
953
954 /* Check that the library fulfills the version requirement.  */
955 const char *gpgme_check_version (const char *req_version);
956
957 /* Retrieve information about the backend engines.  */
958 GpgmeError gpgme_get_engine_info (GpgmeEngineInfo *engine_info);
959
960 /* Return a string describing ERR.  */
961 const char *gpgme_strerror (GpgmeError err);
962
963
964 /* Engine support functions.  */
965
966 /* Verify that the engine implementing PROTO is installed and
967    available.  */
968 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
969
970
971 #ifdef __cplusplus
972 }
973 #endif
974 #endif /* GPGME_H */