2003-04-24 Marcus Brinkmann <marcus@g10code.de>
[gpgme.git] / gpgme / gpgme.h
1 /* gpgme.h - Public interface to GnuPG Made Easy.
2    Copyright (C) 2000 Werner Koch (dd9jn)
3    Copyright (C) 2001, 2002, 2003 g10 Code GmbH
4
5    This file is part of GPGME.
6  
7    GPGME is free software; you can redistribute it and/or modify it
8    under the terms of the GNU General Public License as published by
9    the Free Software Foundation; either version 2 of the License, or
10    (at your option) any later version.
11  
12    GPGME is distributed in the hope that it will be useful, but
13    WITHOUT ANY WARRANTY; without even the implied warranty of
14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15    General Public License for more details.
16  
17    You should have received a copy of the GNU General Public License
18    along with GPGME; if not, write to the Free Software Foundation,
19    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
20
21 #ifndef GPGME_H
22 #define GPGME_H
23
24 #include <stdio.h> /* For FILE *.  */
25 #ifdef _MSC_VER
26   typedef long off_t;
27   typedef long ssize_t;
28 #else
29 # include <sys/types.h>
30 #endif
31
32 #ifdef __cplusplus
33 extern "C" {
34 #if 0 /* just to make Emacs auto-indent happy */
35 }
36 #endif
37 #endif
38
39
40 /* The version of this header should match the one of the library.  Do
41    not use this symbol in your application, use gpgme_check_version
42    instead.  The purpose of this macro is to let autoconf (using the
43    AM_PATH_GPGME macro) check that this header matches the installed
44    library.  Warning: Do not edit the next line.  configure will do
45    that for you!  */
46 #define GPGME_VERSION "0.4.1"
47
48
49 /* The opaque data types used by GPGME.  */
50
51 /* The context holds some global state and configration options as
52    well as the results of a crypto operation.  */
53 struct gpgme_context_s;
54 typedef struct gpgme_context_s *GpgmeCtx;
55
56 /* The data object used by GPGME to exchange arbitrary data.  */
57 struct gpgme_data_s;
58 typedef struct gpgme_data_s *GpgmeData;
59
60 /* A list of recipients to be used in an encryption operation.  */
61 struct gpgme_recipients_s;
62 typedef struct gpgme_recipients_s *GpgmeRecipients;
63
64 /* A key from the keyring.  */
65 struct gpgme_key_s;
66 typedef struct gpgme_key_s *GpgmeKey;
67
68 /* A trust item.  */
69 struct gpgme_trust_item_s;
70 typedef struct gpgme_trust_item_s *GpgmeTrustItem;
71
72
73 /* The error numbers used by GPGME.  */
74 typedef enum
75   {
76     GPGME_EOF                     = -1,
77     GPGME_No_Error                = 0x0000,
78     GPGME_General_Error           = 0x0001,
79     GPGME_Out_Of_Core             = 0x0002,
80     GPGME_Invalid_Value           = 0x0003,
81     GPGME_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 \f
224 /* The possible stati for the edit operation.  */
225 typedef enum
226   {
227     GPGME_STATUS_EOF,
228     /* mkstatus processing 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_OK,
272     GPGME_STATUS_IMPORT_PROBLEM,
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   }
308 GpgmeStatusCode;
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 /* The engine information structure.  */
316 struct _gpgme_engine_info
317 {
318   struct _gpgme_engine_info *next;
319
320   /* The protocol ID.  */
321   GpgmeProtocol protocol;
322
323   /* The file name of the engine binary.  */
324   const char *file_name;
325
326   /* The version string of the installed engine.  */
327   const char *version;
328
329   /* The minimum version required for GPGME.  */
330   const char *req_version;
331 };
332 typedef struct _gpgme_engine_info *GpgmeEngineInfo;
333
334
335 /* Types for callback functions.  */
336
337 /* Request a passphrase from the user.  */
338 typedef GpgmeError (*GpgmePassphraseCb) (void *hook, const char *desc,
339                                          void **r_hd, const char **result);
340
341 /* Inform the user about progress made.  */
342 typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
343                                  int type, int current, int total);
344
345 /* Interact with the user about an edit operation.  */
346 typedef GpgmeError (*GpgmeEditCb) (void *opaque, GpgmeStatusCode status,
347                                    const char *args, const char **reply);
348
349 /* Context management functions.  */
350
351 /* Create a new context and return it in CTX.  */
352 GpgmeError gpgme_new (GpgmeCtx *ctx);
353
354 /* Release the context CTX.  */
355 void gpgme_release (GpgmeCtx ctx);
356
357 /* Retrieve more info about performed signature check.  */
358 char *gpgme_get_notation (GpgmeCtx ctx);
359
360 /* Set the protocol to be used by CTX to PROTO.  */
361 GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
362
363 /* Get the protocol used with CTX */
364 GpgmeProtocol gpgme_get_protocol (GpgmeCtx ctx);
365
366 /* Get the string describing protocol PROTO, or NULL if invalid.  */
367 const char *gpgme_get_protocol_name (GpgmeProtocol proto);
368
369 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
370 void gpgme_set_armor (GpgmeCtx ctx, int yes);
371
372 /* Return non-zero if armor mode is set in CTX.  */
373 int gpgme_get_armor (GpgmeCtx ctx);
374
375 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
376 void gpgme_set_textmode (GpgmeCtx ctx, int yes);
377
378 /* Return non-zero if text mode is set in CTX.  */
379 int gpgme_get_textmode (GpgmeCtx ctx);
380
381 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
382 void gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs);
383
384 /* Return the number of certs to include in an S/MIME message.  */
385 int gpgme_get_include_certs (GpgmeCtx ctx);
386
387 /* Set keylist mode in CTX to MODE.  */
388 GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
389
390 /* Get keylist mode in CTX.  */
391 int gpgme_get_keylist_mode (GpgmeCtx ctx);
392
393 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
394    passed as first argument to the passphrase callback function.  */
395 void gpgme_set_passphrase_cb (GpgmeCtx ctx,
396                               GpgmePassphraseCb cb, void *hook_value);
397
398 /* Get the current passphrase callback function in *CB and the current
399    hook value in *HOOK_VALUE.  */
400 void gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *cb,
401                               void **hook_value);
402
403 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
404    passed as first argument to the progress callback function.  */
405 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
406
407 /* Get the current progress callback function in *CB and the current
408    hook value in *HOOK_VALUE.  */
409 void gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *cb,
410                             void **hook_value);
411
412 /* Delete all signers from CTX.  */
413 void gpgme_signers_clear (GpgmeCtx ctx);
414
415 /* Add KEY to list of signers in CTX.  */
416 GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
417
418 /* Return the SEQth signer's key in CTX.  */
419 GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
420
421 /* Retrieve the signature status of signature IDX in CTX after a
422    successful verify operation in R_STAT (if non-null).  The creation
423    time stamp of the signature is returned in R_CREATED (if non-null).
424    The function returns a string containing the fingerprint.  */
425 const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
426                                   GpgmeSigStat *r_stat, time_t *r_created);
427
428 /* Retrieve certain attributes of a signature.  IDX is the index
429    number of the signature after a successful verify operation.  WHAT
430    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
431    one.  WHATIDX is to be passed as 0 for most attributes . */
432 unsigned long gpgme_get_sig_ulong_attr (GpgmeCtx c, int idx,
433                                         GpgmeAttr what, int whatidx);
434 const char *gpgme_get_sig_string_attr (GpgmeCtx c, int idx,
435                                       GpgmeAttr what, int whatidx);
436
437
438 /* Get the key used to create signature IDX in CTX and return it in
439    R_KEY.  */
440 GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
441
442 /* Return a string with more info about the last crypto operating in CTX.
443    RESERVED should be zero.  The user has to free the string.  */
444 char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
445
446
447 /* Run control.  */
448
449 /* The type of an I/O callback function.  */
450 typedef GpgmeError (*GpgmeIOCb) (void *data, int fd);
451
452 /* The type of a function that can register FNC as the I/O callback
453    function for the file descriptor FD with direction dir (0: for writing,
454    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
455    function should return a TAG suitable for the corresponding
456    GpgmeRemoveIOCb, and an error value.  */
457 typedef GpgmeError (*GpgmeRegisterIOCb) (void *data, int fd, int dir,
458                                          GpgmeIOCb fnc, void *fnc_data,
459                                          void **tag);
460
461 /* The type of a function that can remove a previously registered I/O
462    callback function given TAG as returned by the register
463    function.  */
464 typedef void (*GpgmeRemoveIOCb) (void *tag);
465
466 typedef enum { GPGME_EVENT_START,
467                GPGME_EVENT_DONE,
468                GPGME_EVENT_NEXT_KEY,
469                GPGME_EVENT_NEXT_TRUSTITEM } GpgmeEventIO;
470
471 /* The type of a function that is called when a context finished an
472    operation.  */
473 typedef void (*GpgmeEventIOCb) (void *data, GpgmeEventIO type,
474                                 void *type_data);
475
476 struct GpgmeIOCbs
477 {
478   GpgmeRegisterIOCb add;
479   void *add_priv;
480   GpgmeRemoveIOCb remove;
481   GpgmeEventIOCb event;
482   void *event_priv;
483 };
484
485 /* Set the I/O callback functions in CTX to IO_CBS.  */
486 void gpgme_set_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
487
488 /* Get the current I/O callback functions.  */
489 void gpgme_get_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
490
491 /* Process the pending operation and, if HANG is non-zero, wait for
492    the pending operation to finish.  */
493 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
494
495
496 /* Functions to handle recipients.  */
497
498 /* Create a new recipients set and return it in R_RSET.  */
499 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
500
501 /* Release the recipients set RSET.  */
502 void gpgme_recipients_release (GpgmeRecipients rset);
503
504 /* Add NAME to the recipients set RSET.  */
505 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
506
507 /* Add NAME with validity AL to the recipients set RSET.  */
508 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
509                                                     const char *name,
510                                                     GpgmeValidity val);
511
512 /* Return the number of recipients in RSET.  */
513 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
514
515 /* Create a new enumeration handle for the recipients set RSET and
516    return it in ITER.  */
517 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
518                                        void **iter);
519
520 /* Return the next recipient from the recipient set RSET in the
521    enumerator ITER.  */
522 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
523                                         void **iter);
524
525 /* Destroy the enumerator ITER for the recipient set RSET.  */
526 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
527                                         void **iter);
528
529
530 /* Functions to handle data objects.  */
531
532 /* Read up to SIZE bytes into buffer BUFFER from the data object with
533    the handle HANDLE.  Return the number of characters read, 0 on EOF
534    and -1 on error.  If an error occurs, errno is set.  */
535 typedef ssize_t (*GpgmeDataReadCb) (void *handle, void *buffer, size_t size);
536
537 /* Write up to SIZE bytes from buffer BUFFER to the data object with
538    the handle HANDLE.  Return the number of characters written, or -1
539    on error.  If an error occurs, errno is set.  */
540 typedef ssize_t (*GpgmeDataWriteCb) (void *handle, const void *buffer,
541                                      size_t size);
542
543 /* Set the current position from where the next read or write starts
544    in the data object with the handle HANDLE to OFFSET, relativ to
545    WHENCE.  */
546 typedef off_t (*GpgmeDataSeekCb) (void *handle, off_t offset, int whence);
547
548 /* Close the data object with the handle DL.  */
549 typedef void (*GpgmeDataReleaseCb) (void *handle);
550
551 struct GpgmeDataCbs
552 {
553   GpgmeDataReadCb read;
554   GpgmeDataWriteCb write;
555   GpgmeDataSeekCb seek;
556   GpgmeDataReleaseCb release;
557 };
558
559 /* Read up to SIZE bytes into buffer BUFFER from the data object with
560    the handle DH.  Return the number of characters read, 0 on EOF and
561    -1 on error.  If an error occurs, errno is set.  */
562 ssize_t gpgme_data_read (GpgmeData dh, void *buffer, size_t size);
563
564 /* Write up to SIZE bytes from buffer BUFFER to the data object with
565    the handle DH.  Return the number of characters written, or -1 on
566    error.  If an error occurs, errno is set.  */
567 ssize_t gpgme_data_write (GpgmeData dh, const void *buffer, size_t size);
568
569 /* Set the current position from where the next read or write starts
570    in the data object with the handle DH to OFFSET, relativ to
571    WHENCE.  */
572 off_t gpgme_data_seek (GpgmeData dh, off_t offset, int whence);
573
574 /* Create a new data buffer and return it in R_DH.  */
575 GpgmeError gpgme_data_new (GpgmeData *r_dh);
576
577 /* Destroy the data buffer DH.  */
578 void gpgme_data_release (GpgmeData dh);
579
580 /* Create a new data buffer filled with SIZE bytes starting from
581    BUFFER.  If COPY is zero, copying is delayed until necessary, and
582    the data is taken from the original location when needed.  */
583 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
584                                     const char *buffer, size_t size,
585                                     int copy);
586
587 /* Destroy the data buffer DH and return a pointer to its content.
588    The memory has be to released with free by the user.  It's size is
589    returned in R_LEN.  */
590 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
591
592 GpgmeError gpgme_data_new_from_cbs (GpgmeData *dh,
593                                     struct GpgmeDataCbs *cbs,
594                                     void *handle);
595
596 GpgmeError gpgme_data_new_from_fd (GpgmeData *dh, int fd);
597
598 GpgmeError gpgme_data_new_from_stream (GpgmeData *dh, FILE *stream);
599
600 /* Return the encoding attribute of the data buffer DH */
601 GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh);
602
603 /* Set the encoding attribute of data buffer DH to ENC */
604 GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc);
605
606
607
608 /* Create a new data buffer which retrieves the data from the callback
609    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
610    instead.  */
611 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
612                                         int (*read_cb) (void*,char *,size_t,size_t*),
613                                         void *read_cb_value);
614
615 /* Create a new data buffer filled with the content of file FNAME.
616    COPY must be non-zero.  For delayed read, please use
617    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
618 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
619                                      const char *fname,
620                                      int copy);
621
622 /* Create a new data buffer filled with LENGTH bytes starting from
623    OFFSET within the file FNAME or stream FP (exactly one must be
624    non-zero).  */
625 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
626                                          const char *fname, FILE *fp,
627                                          off_t offset, size_t length);
628
629 /* Reset the read pointer in DH.  Deprecated, please use
630    gpgme_data_seek instead.  */
631 GpgmeError gpgme_data_rewind (GpgmeData dh);
632
633
634 /* Key and trust functions.  */
635
636 /* Get the key with the fingerprint FPR from the key cache or from the
637    crypto backend.  If FORCE_UPDATE is true, force a refresh of the
638    key from the crypto backend and replace the key in the cache, if
639    any.  If SECRET is true, get the secret key.  */
640 GpgmeError gpgme_get_key (GpgmeCtx ctx, const char *fpr, GpgmeKey *r_key,
641                           int secret, int force_update);
642
643 /* Acquire a reference to KEY.  */
644 void gpgme_key_ref (GpgmeKey key);
645
646 /* Release a reference to KEY.  If this was the last one the key is
647    destroyed.  */
648 void gpgme_key_unref (GpgmeKey key);
649 void gpgme_key_release (GpgmeKey key);
650
651 /* Get the data from key KEY in a XML string, which has to be released
652    with free by the user.  */
653 char *gpgme_key_get_as_xml (GpgmeKey key);
654
655 /* Return the value of the attribute WHAT of KEY, which has to be
656    representable by a string.  IDX specifies the sub key or
657    user ID for attributes related to sub keys or user IDs.  */
658 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
659                                        const void *reserved, int idx);
660
661 /* Return the value of the attribute WHAT of KEY, which has to be
662    representable by an unsigned integer.  IDX specifies the sub key or
663    user ID for attributes related to sub keys or user IDs.  */
664 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
665                                         const void *reserved, int idx);
666
667 /* Return the value of the attribute WHAT of a signature on user ID
668    UID_IDX in KEY, which has to be representable by a string.  IDX
669    specifies the signature.  */
670 const char *gpgme_key_sig_get_string_attr (GpgmeKey key, int uid_idx,
671                                            GpgmeAttr what,
672                                            const void *reserved, int idx);
673
674 /* Return the value of the attribute WHAT of a signature on user ID
675    UID_IDX in KEY, which has to be representable by an unsigned
676    integer string.  IDX specifies the signature.  */
677 unsigned long gpgme_key_sig_get_ulong_attr (GpgmeKey key, int uid_idx,
678                                             GpgmeAttr what,
679                                             const void *reserved, int idx);
680
681
682 /* Release the trust item ITEM.  */
683 void gpgme_trust_item_release (GpgmeTrustItem item);
684
685 /* Return the value of the attribute WHAT of ITEM, which has to be
686    representable by a string.  */
687 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
688                                               GpgmeAttr what,
689                                               const void *reserved, int idx);
690
691 /* Return the value of the attribute WHAT of KEY, which has to be
692    representable by an integer.  IDX specifies a running index if the
693    attribute appears more than once in the key.  */
694 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
695                                    const void *reserved, int idx);
696
697
698 /* Crypto operation function.  */
699
700 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
701    store the resulting ciphertext in CIPHER.  */
702 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
703                                    GpgmeRecipients recp,
704                                    GpgmeData plain, GpgmeData cipher);
705 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
706                              GpgmeRecipients recp,
707                              GpgmeData plain, GpgmeData cipher);
708
709 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
710    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
711    with the signers in CTX.  */
712 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
713                                         GpgmeRecipients recp,
714                                         GpgmeData plain, GpgmeData cipher);
715 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
716                                   GpgmeRecipients recp,
717                                   GpgmeData plain, GpgmeData cipher);
718
719 /* Decrypt ciphertext CIPHER within CTX and store the resulting
720    plaintext in PLAIN.  */
721 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
722                                    GpgmeData cipher, GpgmeData plain);
723 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
724                              GpgmeData cipher, GpgmeData plain);
725
726 /* Decrypt ciphertext CIPHER and make a signature verification within
727    CTX and store the resulting plaintext in PLAIN.  */
728 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
729                                           GpgmeData cipher, GpgmeData plain);
730 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
731                                     GpgmeData cipher, GpgmeData plain);
732
733 /* Sign the plaintext PLAIN and store the signature in SIG.  Only
734    detached signatures are supported for now.  */
735 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
736                                 GpgmeData plain, GpgmeData sig,
737                                 GpgmeSigMode mode);
738 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
739                           GpgmeData plain, GpgmeData sig,
740                           GpgmeSigMode mode);
741
742 /* Verify within CTX that SIG is a valid signature for TEXT.  */
743 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig,
744                                   GpgmeData signed_text, GpgmeData plaintext);
745 GpgmeError gpgme_op_verify (GpgmeCtx ctx, GpgmeData sig,
746                             GpgmeData signed_text, GpgmeData plaintext);
747
748 /* Import the key in KEYDATA into the keyring.  */
749 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
750 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
751 GpgmeError gpgme_op_import_ext (GpgmeCtx ctx, GpgmeData keydata, int *nr);
752
753 /* Export the keys listed in RECP into KEYDATA.  */
754 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
755                                   GpgmeData keydata);
756 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
757                             GpgmeData keydata);
758
759 /* Generate a new keypair and add it to the keyring.  PUBKEY and
760    SECKEY should be null for now.  PARMS specifies what keys should be
761    generated.  On success, if *FPR is non-null, it contains a
762    malloc()'ed string with the fingerprint of the generated key on
763    success.  */
764 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
765                                   GpgmeData pubkey, GpgmeData seckey);
766 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
767                             GpgmeData pubkey, GpgmeData seckey,
768                             char **fpr);
769
770 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
771    keys are also deleted.  */
772 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
773                                   int allow_secret);
774 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
775                             int allow_secret);
776
777 /* Edit the key KEY.  Send status and command requests to FNC and
778    output of edit commands to OUT.  */
779 GpgmeError gpgme_op_edit_start (GpgmeCtx ctx, GpgmeKey key,
780                           GpgmeEditCb fnc, void *fnc_value,
781                           GpgmeData out);
782 GpgmeError gpgme_op_edit (GpgmeCtx ctx, GpgmeKey key,
783                           GpgmeEditCb fnc, void *fnc_value,
784                           GpgmeData out);
785
786 /* Key management functions */
787
788 /* Start a keylist operation within CTX, searching for keys which
789    match PATTERN.  If SECRET_ONLY is true, only secret keys are
790    returned.  */
791 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
792                                    const char *pattern, int secret_only);
793 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
794                                        int secret_only, int reserved);
795
796 /* Return the next key from the keylist in R_KEY.  */
797 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
798
799 /* Terminate a pending keylist operation within CTX.  */
800 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
801
802
803 /* Start a trustlist operation within CTX, searching for trust items
804    which match PATTERN.  */
805 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
806                                      const char *pattern, int max_level);
807
808 /* Return the next trust item from the trustlist in R_ITEM.  */
809 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
810
811 /* Terminate a pending trustlist operation within CTX.  */
812 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
813
814
815 /* Various functions.  */
816
817 /* Check that the library fulfills the version requirement.  */
818 const char *gpgme_check_version (const char *req_version);
819
820 /* Retrieve information about the backend engines.  */
821 GpgmeError gpgme_get_engine_info (GpgmeEngineInfo *engine_info);
822
823 /* Return a string describing ERR.  */
824 const char *gpgme_strerror (GpgmeError err);
825
826
827 /* Engine support functions.  */
828
829 /* Verify that the engine implementing PROTO is installed and
830    available.  */
831 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
832
833
834 #ifdef __cplusplus
835 }
836 #endif
837 #endif /* GPGME_H */