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