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