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