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 crypto backend.  If
684    SECRET is true, get the secret key.  */
685 GpgmeError gpgme_get_key (GpgmeCtx ctx, const char *fpr, GpgmeKey *r_key,
686                           int secret);
687
688 /* Acquire a reference to KEY.  */
689 void gpgme_key_ref (GpgmeKey key);
690
691 /* Release a reference to KEY.  If this was the last one the key is
692    destroyed.  */
693 void gpgme_key_unref (GpgmeKey key);
694 void gpgme_key_release (GpgmeKey key);
695
696 /* Get the data from key KEY in a XML string, which has to be released
697    with free by the user.  */
698 char *gpgme_key_get_as_xml (GpgmeKey key);
699
700 /* Return the value of the attribute WHAT of KEY, which has to be
701    representable by a string.  IDX specifies the sub key or
702    user ID for attributes related to sub keys or user IDs.  */
703 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
704                                        const void *reserved, int idx);
705
706 /* Return the value of the attribute WHAT of KEY, which has to be
707    representable by an unsigned integer.  IDX specifies the sub key or
708    user ID for attributes related to sub keys or user IDs.  */
709 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
710                                         const void *reserved, int idx);
711
712 /* Return the value of the attribute WHAT of a signature on user ID
713    UID_IDX in KEY, which has to be representable by a string.  IDX
714    specifies the signature.  */
715 const char *gpgme_key_sig_get_string_attr (GpgmeKey key, int uid_idx,
716                                            GpgmeAttr what,
717                                            const void *reserved, int idx);
718
719 /* Return the value of the attribute WHAT of a signature on user ID
720    UID_IDX in KEY, which has to be representable by an unsigned
721    integer string.  IDX specifies the signature.  */
722 unsigned long gpgme_key_sig_get_ulong_attr (GpgmeKey key, int uid_idx,
723                                             GpgmeAttr what,
724                                             const void *reserved, int idx);
725
726 \f
727 /* Crypto Operations.  */
728
729 struct _gpgme_invalid_user_id
730 {
731   struct _gpgme_invalid_user_id *next;
732   char *id;
733   GpgmeError reason;
734 };
735 typedef struct _gpgme_invalid_user_id *GpgmeInvalidUserID;
736
737 \f
738 /* Encryption.  */
739 struct _gpgme_op_encrypt_result
740 {
741   /* The list of invalid recipients.  */
742   GpgmeInvalidUserID invalid_recipients;
743 };
744 typedef struct _gpgme_op_encrypt_result *GpgmeEncryptResult;
745
746 /* Retrieve a pointer to the result of the encrypt operation.  */
747 GpgmeEncryptResult gpgme_op_encrypt_result (GpgmeCtx ctx);
748
749 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
750    store the resulting ciphertext in CIPHER.  */
751 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
752                                    GpgmeRecipients recp,
753                                    GpgmeData plain, GpgmeData cipher);
754 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
755                              GpgmeRecipients recp,
756                              GpgmeData plain, GpgmeData cipher);
757
758 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
759    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
760    with the signers in CTX.  */
761 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
762                                         GpgmeRecipients recp,
763                                         GpgmeData plain, GpgmeData cipher);
764 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
765                                   GpgmeRecipients recp,
766                                   GpgmeData plain, GpgmeData cipher);
767
768 \f
769 /* Decryption.  */
770 struct _gpgme_op_decrypt_result
771 {
772   char *unsupported_algorithm;
773 };
774 typedef struct _gpgme_op_decrypt_result *GpgmeDecryptResult;
775
776 /* Retrieve a pointer to the result of the decrypt operation.  */
777 GpgmeDecryptResult gpgme_op_decrypt_result (GpgmeCtx ctx);
778
779 /* Decrypt ciphertext CIPHER within CTX and store the resulting
780    plaintext in PLAIN.  */
781 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
782                                    GpgmeData cipher, GpgmeData plain);
783 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
784                              GpgmeData cipher, GpgmeData plain);
785
786 /* Decrypt ciphertext CIPHER and make a signature verification within
787    CTX and store the resulting plaintext in PLAIN.  */
788 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
789                                           GpgmeData cipher, GpgmeData plain);
790 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
791                                     GpgmeData cipher, GpgmeData plain);
792
793 \f
794 /* Signing.  */
795 struct _gpgme_new_signature
796 {
797   struct _gpgme_new_signature *next;
798   GpgmeSigMode type;
799   GpgmePubKeyAlgo pubkey_algo;
800   GpgmeHashAlgo hash_algo;
801   unsigned long class;
802   long int timestamp;
803   char *fpr;
804 };
805 typedef struct _gpgme_new_signature *GpgmeNewSignature;
806
807 struct _gpgme_op_sign_result
808 {
809   /* The list of invalid signers.  */
810   GpgmeInvalidUserID invalid_signers;
811   GpgmeNewSignature signatures;
812 };
813 typedef struct _gpgme_op_sign_result *GpgmeSignResult;
814
815 /* Retrieve a pointer to the result of the signing operation.  */
816 GpgmeSignResult gpgme_op_sign_result (GpgmeCtx ctx);
817
818 /* Sign the plaintext PLAIN and store the signature in SIG.  */
819 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
820                                 GpgmeData plain, GpgmeData sig,
821                                 GpgmeSigMode mode);
822 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
823                           GpgmeData plain, GpgmeData sig,
824                           GpgmeSigMode mode);
825
826 \f
827 /* Verify.  */
828 struct _gpgme_sig_notation
829 {
830   struct _gpgme_sig_notation *next;
831
832   /* If NAME is a null pointer, then VALUE contains a policy URL
833      rather than a notation.  */
834   char *name;
835   char *value;
836 };
837 typedef struct _gpgme_sig_notation *GpgmeSigNotation;
838
839 /* Flags used for the SUMMARY field in a GpgmeSignature.  */
840 enum 
841   {
842     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
843     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
844     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
845     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
846     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
847     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
848     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
849     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
850     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
851     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
852     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
853   };
854
855 struct _gpgme_signature
856 {
857   struct _gpgme_signature *next;
858
859   /* A summary of the signature status.  */
860   unsigned int summary;
861
862   /* The fingerprint or key ID of the signature.  */
863   char *fpr;
864
865   /* The status of the signature.  */
866   GpgmeError status;
867
868   /* Notation data and policy URLs.  */
869   GpgmeSigNotation notations;
870
871   /* Signature creation time.  */
872   unsigned long timestamp;
873
874   /* Signature exipration time or 0.  */
875   unsigned long exp_timestamp;
876
877   int wrong_key_usage : 1;
878
879   /* Internal to GPGME, do not use.  */
880   int _unused : 31;
881
882   GpgmeValidity validity;
883   GpgmeError validity_reason;
884 };
885 typedef struct _gpgme_signature *GpgmeSignature;
886
887 struct _gpgme_op_verify_result
888 {
889   GpgmeSignature signatures;
890 };
891 typedef struct _gpgme_op_verify_result *GpgmeVerifyResult;
892
893 /* Retrieve a pointer to the result of the verify operation.  */
894 GpgmeVerifyResult gpgme_op_verify_result (GpgmeCtx ctx);
895
896 /* Verify within CTX that SIG is a valid signature for TEXT.  */
897 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig,
898                                   GpgmeData signed_text, GpgmeData plaintext);
899 GpgmeError gpgme_op_verify (GpgmeCtx ctx, GpgmeData sig,
900                             GpgmeData signed_text, GpgmeData plaintext);
901
902 \f
903 /* Import.  */
904 enum
905   {
906     /* The key was new.  */
907     GPGME_IMPORT_NEW = 1,
908
909     /* The key contained new user IDs.  */
910     GPGME_IMPORT_UID = 2,
911
912     /* The key contained new signatures.  */
913     GPGME_IMPORT_SIG = 4,
914
915     /* The key contained new sub keys.  */
916     GPGME_IMPORT_SUBKEY = 8,
917
918     /* The key contained a secret key.  */
919     GPGME_IMPORT_SECRET = 16
920   };
921
922 struct _gpgme_import_status
923 {
924   struct _gpgme_import_status *next;
925
926   /* Fingerprint.  */
927   char *fpr;
928
929   /* If a problem occured, the reason why the key could not be
930      imported.  Otherwise GPGME_No_Error.  */
931   GpgmeError result;
932
933   /* The result of the import, the GPGME_IMPORT_* values bit-wise
934      ORed.  0 means the key was already known and no new components
935      have been added.  */
936   unsigned int status;
937 };
938 typedef struct _gpgme_import_status *GpgmeImportStatus;
939
940 /* Import.  */
941 struct _gpgme_op_import_result
942 {
943   /* Number of considered keys.  */
944   int considered;
945
946   /* Keys without user ID.  */
947   int no_user_id;
948
949   /* Imported keys.  */
950   int imported;
951
952   /* Imported RSA keys.  */
953   int imported_rsa;
954
955   /* Unchanged keys.  */
956   int unchanged;
957
958   /* Number of new user ids.  */
959   int new_user_ids;
960
961   /* Number of new sub keys.  */
962   int new_sub_keys;
963
964   /* Number of new signatures.  */
965   int new_signatures;
966
967   /* Number of new revocations.  */
968   int new_revocations;
969
970   /* Number of secret keys read.  */
971   int secret_read;
972
973   /* Number of secret keys imported.  */
974   int secret_imported;
975
976   /* Number of secret keys unchanged.  */
977   int secret_unchanged;
978
979   /* Number of keys not imported.  */
980   int not_imported;
981
982   /* List of keys for which an import was attempted.  */
983   GpgmeImportStatus imports;
984 };
985 typedef struct _gpgme_op_import_result *GpgmeImportResult;
986
987 /* Retrieve a pointer to the result of the import operation.  */
988 GpgmeImportResult gpgme_op_import_result (GpgmeCtx ctx);
989
990 /* Import the key in KEYDATA into the keyring.  */
991 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
992 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
993 GpgmeError gpgme_op_import_ext (GpgmeCtx ctx, GpgmeData keydata, int *nr);
994
995 \f
996 /* Export the keys listed in RECP into KEYDATA.  */
997 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
998                                   GpgmeData keydata);
999 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
1000                             GpgmeData keydata);
1001
1002 \f
1003 /* Key generation.  */
1004 struct _gpgme_op_genkey_result
1005 {
1006   /* A primary key was generated.  */
1007   unsigned int primary : 1;
1008
1009   /* A sub key was generated.  */
1010   unsigned int sub : 1;
1011
1012   /* Internal to GPGME, do not use.  */
1013   unsigned int _unused : 30;
1014
1015   /* The fingerprint of the generated key.  */
1016   char *fpr;
1017 };
1018 typedef struct _gpgme_op_genkey_result *GpgmeGenKeyResult;
1019
1020 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1021    SECKEY should be null for now.  PARMS specifies what keys should be
1022    generated.  */
1023 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
1024                                   GpgmeData pubkey, GpgmeData seckey);
1025 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
1026                             GpgmeData pubkey, GpgmeData seckey);
1027
1028 /* Retrieve a pointer to the result of the genkey operation.  */
1029 GpgmeGenKeyResult gpgme_op_genkey_result (GpgmeCtx ctx);
1030
1031 \f
1032 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1033    keys are also deleted.  */
1034 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
1035                                   int allow_secret);
1036 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
1037                             int allow_secret);
1038
1039 /* Edit the key KEY.  Send status and command requests to FNC and
1040    output of edit commands to OUT.  */
1041 GpgmeError gpgme_op_edit_start (GpgmeCtx ctx, GpgmeKey key,
1042                           GpgmeEditCb fnc, void *fnc_value,
1043                           GpgmeData out);
1044 GpgmeError gpgme_op_edit (GpgmeCtx ctx, GpgmeKey key,
1045                           GpgmeEditCb fnc, void *fnc_value,
1046                           GpgmeData out);
1047
1048 /* Key management functions */
1049
1050 /* Start a keylist operation within CTX, searching for keys which
1051    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1052    returned.  */
1053 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
1054                                    const char *pattern, int secret_only);
1055 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
1056                                        int secret_only, int reserved);
1057
1058 /* Return the next key from the keylist in R_KEY.  */
1059 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
1060
1061 /* Terminate a pending keylist operation within CTX.  */
1062 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
1063
1064 \f
1065 /* Trust items and operations.  */
1066
1067 struct _gpgme_trust_item
1068 {
1069   /* Internal to GPGME, do not use.  */
1070   unsigned int _refs;
1071
1072   /* The key ID to which the trust item belongs.  */
1073   char *keyid;
1074
1075   /* Internal to GPGME, do not use.  */
1076   char _keyid[16 + 1];
1077
1078   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1079   int type;
1080
1081   /* The trust level.  */
1082   int level;
1083
1084   /* The owner trust if TYPE is 1.  */
1085   char *otrust;
1086
1087   /* Internal to GPGME, do not use.  */
1088   char _otrust[2];
1089
1090   /* The calculated validity.  */
1091   char *val;
1092  
1093   /* Internal to GPGME, do not use.  */
1094   char _val[2];
1095
1096   /* The user name if TYPE is 2.  */
1097   char *name;
1098 };
1099 typedef struct _gpgme_trust_item *GpgmeTrustItem;
1100
1101 /* Start a trustlist operation within CTX, searching for trust items
1102    which match PATTERN.  */
1103 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
1104                                      const char *pattern, int max_level);
1105
1106 /* Return the next trust item from the trustlist in R_ITEM.  */
1107 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
1108
1109 /* Terminate a pending trustlist operation within CTX.  */
1110 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
1111
1112 /* Acquire a reference to ITEM.  */
1113 void gpgme_trust_item_ref (GpgmeTrustItem item);
1114
1115 /* Release a reference to ITEM.  If this was the last one the trust
1116    item is destroyed.  */
1117 void gpgme_trust_item_unref (GpgmeTrustItem item);
1118
1119 /* Release the trust item ITEM.  */
1120 void gpgme_trust_item_release (GpgmeTrustItem item);
1121
1122 /* Return the value of the attribute WHAT of ITEM, which has to be
1123    representable by a string.  */
1124 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
1125                                               GpgmeAttr what,
1126                                               const void *reserved, int idx);
1127
1128 /* Return the value of the attribute WHAT of KEY, which has to be
1129    representable by an integer.  IDX specifies a running index if the
1130    attribute appears more than once in the key.  */
1131 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
1132                                    const void *reserved, int idx);
1133
1134 \f
1135 /* Various functions.  */
1136
1137 /* Check that the library fulfills the version requirement.  */
1138 const char *gpgme_check_version (const char *req_version);
1139
1140 /* Retrieve information about the backend engines.  */
1141 GpgmeError gpgme_get_engine_info (GpgmeEngineInfo *engine_info);
1142
1143 /* Return a string describing ERR.  */
1144 const char *gpgme_strerror (GpgmeError err);
1145
1146 \f
1147 /* Engine support functions.  */
1148
1149 /* Verify that the engine implementing PROTO is installed and
1150    available.  */
1151 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
1152
1153
1154 #ifdef __cplusplus
1155 }
1156 #endif
1157 #endif /* GPGME_H */