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