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