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