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