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