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