2002-02-10 Marcus Brinkmann <marcus@g10code.de>
[gpgme.git] / gpgme / gpgme.h
1 /* gpgme.h -  GnuPG Made Easy
2  *      Copyright (C) 2000 Werner Koch (dd9jn)
3  *      Copyright (C) 2001, 2002 g10 Code GmbH
4  *
5  * This file is part of GPGME.
6  *
7  * GPGME is free software; you can redistribute it and/or modify
8  * it 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,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, write to the Free Software
19  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
20  */
21
22 #ifndef GPGME_H
23 #define GPGME_H
24
25 #include <stdio.h> /* For FILE *.  */
26 #ifdef _MSC_VER
27   typedef long off_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.3.2"
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          = 0,
78     GPGME_General_Error     = 1,
79     GPGME_Out_Of_Core       = 2,
80     GPGME_Invalid_Value     = 3,
81     GPGME_Busy              = 4,
82     GPGME_No_Request        = 5,
83     GPGME_Exec_Error        = 6,
84     GPGME_Too_Many_Procs    = 7,
85     GPGME_Pipe_Error        = 8,
86     GPGME_No_Recipients     = 9,
87     GPGME_No_Data           = 10,
88     GPGME_Conflict          = 11,
89     GPGME_Not_Implemented   = 12,
90     GPGME_Read_Error        = 13,
91     GPGME_Write_Error       = 14,
92     GPGME_Invalid_Type      = 15,
93     GPGME_Invalid_Mode      = 16,
94     GPGME_File_Error        = 17,  /* errno is set in this case.  */
95     GPGME_Decryption_Failed = 18,
96     GPGME_No_Passphrase     = 19,
97     GPGME_Canceled          = 20,
98     GPGME_Invalid_Key       = 21,
99     GPGME_Invalid_Engine    = 22
100   }
101 GpgmeError;
102
103 /* The possible types of GpgmeData objects.  */
104 typedef enum
105   {
106     GPGME_DATA_TYPE_NONE = 0,
107     GPGME_DATA_TYPE_MEM  = 1,
108     GPGME_DATA_TYPE_FD   = 2,
109     GPGME_DATA_TYPE_FILE = 3,
110     GPGME_DATA_TYPE_CB   = 4
111   }
112 GpgmeDataType;
113
114 /* The possible signature stati.  */
115 typedef enum
116   {
117     GPGME_SIG_STAT_NONE  = 0,
118     GPGME_SIG_STAT_GOOD  = 1,
119     GPGME_SIG_STAT_BAD   = 2,
120     GPGME_SIG_STAT_NOKEY = 3,
121     GPGME_SIG_STAT_NOSIG = 4,
122     GPGME_SIG_STAT_ERROR = 5,
123     GPGME_SIG_STAT_DIFF  = 6
124   }
125 GpgmeSigStat;
126
127 /* The available signature modes.  */
128 typedef enum
129   {
130     GPGME_SIG_MODE_NORMAL = 0,
131     GPGME_SIG_MODE_DETACH = 1,
132     GPGME_SIG_MODE_CLEAR  = 2
133   }
134 GpgmeSigMode;
135
136 /* The available key attributes.  */
137 typedef enum
138   {
139     GPGME_ATTR_KEYID        = 1,
140     GPGME_ATTR_FPR          = 2,
141     GPGME_ATTR_ALGO         = 3,
142     GPGME_ATTR_LEN          = 4,
143     GPGME_ATTR_CREATED      = 5,
144     GPGME_ATTR_EXPIRE       = 6,
145     GPGME_ATTR_OTRUST       = 7,
146     GPGME_ATTR_USERID       = 8,
147     GPGME_ATTR_NAME         = 9,
148     GPGME_ATTR_EMAIL        = 10,
149     GPGME_ATTR_COMMENT      = 11,
150     GPGME_ATTR_VALIDITY     = 12,
151     GPGME_ATTR_LEVEL        = 13,
152     GPGME_ATTR_TYPE         = 14,
153     GPGME_ATTR_IS_SECRET    = 15,
154     GPGME_ATTR_KEY_REVOKED  = 16,
155     GPGME_ATTR_KEY_INVALID  = 17,
156     GPGME_ATTR_UID_REVOKED  = 18,
157     GPGME_ATTR_UID_INVALID  = 19,
158     GPGME_ATTR_KEY_CAPS     = 20,
159     GPGME_ATTR_CAN_ENCRYPT  = 21,
160     GPGME_ATTR_CAN_SIGN     = 22,
161     GPGME_ATTR_CAN_CERTIFY  = 23,
162     GPGME_ATTR_KEY_EXPIRED  = 24,
163     GPGME_ATTR_KEY_DISABLED = 25
164   }
165 GpgmeAttr;
166
167 /* The available validities for a trust item or key.  */
168 typedef enum
169   {
170     GPGME_VALIDITY_UNKNOWN   = 0,
171     GPGME_VALIDITY_UNDEFINED = 1,
172     GPGME_VALIDITY_NEVER     = 2,
173     GPGME_VALIDITY_MARGINAL  = 3,
174     GPGME_VALIDITY_FULL      = 4,
175     GPGME_VALIDITY_ULTIMATE  = 5
176   }
177 GpgmeValidity;
178
179 /* The available protocols.  */
180 typedef enum
181   {
182     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
183     GPGME_PROTOCOL_CMS     = 1,
184     GPGME_PROTOCOL_AUTO    = 2
185   }
186 GpgmeProtocol;
187
188
189 /* The available keylist mode flags.  */
190 #define GPGME_KEYLIST_MODE_LOCAL 1
191 #define GPGME_KEYLIST_MODE_EXTERN 2
192
193
194 /* Types for callback functions.  */
195
196 /* Request a passphrase from the user.  */
197 typedef const char *(*GpgmePassphraseCb) (void *hook, const char *desc,
198                                           void **r_hd);
199
200 /* Inform the user about progress made.  */
201 typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
202                                  int type, int current, int total);
203
204
205 /* Context management functions.  */
206
207 /* Create a new context and return it in CTX.  */
208 GpgmeError gpgme_new (GpgmeCtx *ctx);
209
210 /* Release the context CTX.  */
211 void gpgme_release (GpgmeCtx ctx);
212
213 /* Retrieve more info about performed signature check.  */
214 char *gpgme_get_notation (GpgmeCtx ctx);
215
216 /* Set the protocol to be used by CTX to PROTO.  */
217 GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
218
219 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
220 void gpgme_set_armor (GpgmeCtx ctx, int yes);
221
222 /* Return non-zero if armor mode is set in CTX.  */
223 int gpgme_get_armor (GpgmeCtx ctx);
224
225 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
226 void gpgme_set_textmode (GpgmeCtx ctx, int yes);
227
228 /* Return non-zero if text mode is set in CTX.  */
229 int gpgme_get_textmode (GpgmeCtx ctx);
230
231 /* Set keylist mode in CTX to MODE.  */
232 GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
233
234 /* Get keylist mode in CTX.  */
235 int gpgme_get_keylist_mode (GpgmeCtx ctx);
236
237 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
238    passed as first argument to the passphrase callback function.  */
239 void gpgme_set_passphrase_cb (GpgmeCtx ctx,
240                               GpgmePassphraseCb cb, void *hook_value);
241
242 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
243    passed as first argument to the progress callback function.  */
244 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
245
246 /* Delete all signers from CTX.  */
247 void gpgme_signers_clear (GpgmeCtx ctx);
248
249 /* Add KEY to list of signers in CTX.  */
250 GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
251
252 /* Return the SEQth signer's key in CTX.  */
253 GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
254
255 /* Retrieve the signature status of signature IDX in CTX after a
256    successful verify operation in R_STAT (if non-null).  The creation
257    time stamp of the signature is returned in R_CREATED (if non-null).
258    The function returns a string containing the fingerprint.  */
259 const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
260                                   GpgmeSigStat *r_stat, time_t *r_created);
261
262 /* Get the key used to create signature IDX in CTX and return it in
263    R_KEY.  */
264 GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
265
266 /* Return a string with more info about the last crypto operating in CTX.
267    RESERVED should be zero.  The user has to free the string.  */
268 char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
269
270
271 /* Run control.  */
272
273 /* Cancel a pending operation in CTX.  */
274 void       gpgme_cancel (GpgmeCtx ctx);
275
276 /* Process the pending operation and, if HANG is non-zero, wait for
277    the pending operation to finish.  */
278 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
279
280
281 /* Functions to handle recipients.  */
282
283 /* Create a new recipients set and return it in R_RSET.  */
284 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
285
286 /* Release the recipients set RSET.  */
287 void gpgme_recipients_release (GpgmeRecipients rset);
288
289 /* Add NAME to the recipients set RSET.  */
290 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
291
292 /* Add NAME with validity AL to the recipients set RSET.  */
293 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
294                                                     const char *name,
295                                                     GpgmeValidity val);
296
297 /* Return the number of recipients in RSET.  */
298 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
299
300 /* Create a new enumeration handle for the recipients set RSET and
301    return it in ITER.  */
302 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
303                                        void **iter);
304
305 /* Return the next recipient from the recipient set RSET in the
306    enumerator ITER.  */
307 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
308                                         void **iter);
309
310 /* Destroy the enumerator ITER for the recipient set RSET.  */
311 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
312                                         void **iter);
313
314
315 /* Functions to handle data objects.  */
316
317 /* Create a new data buffer and return it in R_DH.  */
318 GpgmeError gpgme_data_new (GpgmeData *r_dh);
319
320 /* Create a new data buffer filled with SIZE bytes starting from
321    BUFFER.  If COPY is zero, copying is delayed until necessary, and
322    the data is taken from the original location when needed.  */
323 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
324                                     const char *buffer, size_t size,
325                                     int copy);
326
327 /* Create a new data buffer which retrieves the data from the callback
328    function READ_CB.  */
329 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
330                                         int (*read_cb) (void*,char *,size_t,size_t*),
331                                         void *read_cb_value);
332
333 /* Create a new data buffer filled with the content of file FNAME.
334    COPY must be non-zero (delayed reads are not supported yet).  */
335 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
336                                      const char *fname,
337                                      int copy);
338
339 /* Create a new data buffer filled with LENGTH bytes starting from
340    OFFSET within the file FNAME or stream FP (exactly one must be
341    non-zero).  */
342 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
343                                          const char *fname, FILE *fp,
344                                          off_t offset, size_t length);
345
346 /* Destroy the data buffer DH.  */
347 void gpgme_data_release (GpgmeData dh);
348
349 /* Destroy the data buffer DH and return a pointer to its content.
350    The memory has be to released with free by the user.  It's size is
351    returned in R_LEN.  */
352 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
353
354 /* Return the type of the data buffer DH.  */
355 GpgmeDataType gpgme_data_get_type (GpgmeData dh);
356
357 /* Reset the read pointer in DH.  */
358 GpgmeError gpgme_data_rewind (GpgmeData dh);
359
360 /* Read LENGTH bytes from the data object DH and store them in the
361    memory starting at BUFFER.  The number of bytes actually read is
362    returned in NREAD.  */
363 GpgmeError gpgme_data_read (GpgmeData dh, char *buffer,
364                             size_t length, size_t *nread);
365
366 /* Write LENGTH bytes starting from BUFFER into the data object DH.  */
367 GpgmeError gpgme_data_write (GpgmeData dh, const char *buffer, size_t length);
368
369
370 /* Key and trust functions.  */
371
372 /* Acquire a reference to KEY.  */
373 void gpgme_key_ref (GpgmeKey key);
374
375 /* Release a reference to KEY.  If this was the last one the key is
376    destroyed.  */
377 void gpgme_key_unref (GpgmeKey key);
378 void gpgme_key_release (GpgmeKey key);
379
380 /* Get the data from key KEY in a XML string, which has to be released
381    with free by the user.  */
382 char *gpgme_key_get_as_xml (GpgmeKey key);
383
384 /* Return the value of the attribute WHAT of KEY, which has to be
385    representable by a string.  IDX specifies a running index if the
386    attribute appears more than once in the key.  */
387 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
388                                        const void *reserved, int idx);
389
390 /* Return the value of the attribute WHAT of KEY, which has to be
391    representable by an unsigned integer.  IDX specifies a running
392    index if the attribute appears more than once in the key.  */
393 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
394                                         const void *reserved, int idx);
395
396 /* Release the trust item ITEM.  */
397 void gpgme_trust_item_release (GpgmeTrustItem item);
398
399 /* Return the value of the attribute WHAT of ITEM, which has to be
400    representable by a string.  IDX specifies a running index if the
401    attribute appears more than once in the key.  */
402 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
403                                               GpgmeAttr what,
404                                               const void *reserved, int idx);
405
406 /* Return the value of the attribute WHAT of KEY, which has to be
407    representable by an integer.  IDX specifies a running index if the
408    attribute appears more than once in the key.  */
409 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
410                                    const void *reserved, int idx);
411
412
413 /* Crypto operation function.  */
414
415 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
416    store the resulting ciphertext in CIPHER.  */
417 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
418                                    GpgmeRecipients recp,
419                                    GpgmeData plain, GpgmeData cipher);
420 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
421                              GpgmeRecipients recp,
422                              GpgmeData plain, GpgmeData cipher);
423
424 /* Decrypt ciphertext CIPHER within CTX and store the resulting
425    plaintext in PLAIN.  */
426 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
427                                    GpgmeData cipher, GpgmeData plain);
428 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
429                              GpgmeData cipher, GpgmeData plain);
430
431 /* Decrypt ciphertext CIPHER and make a signature verification within
432    CTX and store the resulting plaintext in PLAIN.  */
433 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
434                                           GpgmeData cipher, GpgmeData plain);
435 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
436                                     GpgmeData cipher, GpgmeData plain,
437                                     GpgmeSigStat *r_status);
438
439 /* Sign the plaintext PLAIN and store the signature in SIG.  Only
440    detached signatures are supported for now.  */
441 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
442                                 GpgmeData plain, GpgmeData sig,
443                                 GpgmeSigMode mode);
444 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
445                           GpgmeData plain, GpgmeData sig,
446                           GpgmeSigMode mode);
447
448 /* Verify within CTX that SIG is a valid signature for TEXT.  */
449 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx,
450                                   GpgmeData sig, GpgmeData text);
451 GpgmeError gpgme_op_verify (GpgmeCtx ctx,
452                             GpgmeData sig, GpgmeData text,
453                             GpgmeSigStat *r_status);
454
455 /* Import the key in KEYDATA into the keyring.  */
456 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
457 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
458
459 /* Export the keys listed in RECP into KEYDATA.  */
460 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
461                                   GpgmeData keydata);
462 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
463                             GpgmeData keydata);
464
465 /* Generate a new keypair and add it to the keyring.  PUBKEY and
466    SECKEY should be null for now.  PARMS specifies what keys should be
467    generated.  */
468 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
469                                   GpgmeData pubkey, GpgmeData seckey);
470 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
471                             GpgmeData pubkey, GpgmeData seckey);
472
473 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
474    keys are also deleted.  */
475 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
476                                   int allow_secret);
477 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
478                             int allow_secret);
479
480
481 /* Key management functions */
482
483 /* Start a keylist operation within CTX, searching for keys which
484    match PATTERN.  If SECRET_ONLY is true, only secret keys are
485    returned.  */
486 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
487                                    const char *pattern, int secret_only);
488
489 /* Return the next key from the keylist in R_KEY.  */
490 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
491
492 /* Terminate a pending keylist operation within CTX.  */
493 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
494
495
496 /* Start a trustlist operation within CTX, searching for trust items
497    which match PATTERN.  */
498 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
499                                      const char *pattern, int max_level);
500
501 /* Return the next trust item from the trustlist in R_ITEM.  */
502 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
503
504 /* Terminate a pending trustlist operation within CTX.  */
505 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
506
507
508 /* Various functions.  */
509
510 /* Check that the library fulfills the version requirement.  */
511 const char *gpgme_check_version (const char *req_version);
512
513 /* Check that the backend engine is available.  DEPRECATED.  */
514 GpgmeError  gpgme_check_engine (void);
515
516 /* Retrieve information about the backend engines.  */
517 const char *gpgme_get_engine_info (void);
518
519 /* Return a string describing ERR.  */
520 const char *gpgme_strerror (GpgmeError err);
521
522 /* Register an idle function.  */
523 typedef void (*GpgmeIdleFunc)(void);
524 GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle);
525
526
527 /* Engine support functions.  */
528
529 /* Verify that the engine implementing PROTO is installed and
530    available.  */
531 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
532
533
534 #ifdef __cplusplus
535 }
536 #endif
537 #endif /* GPGME_H */