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