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