doc/
[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.3"
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 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
232 void gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs);
233
234 /* Return the number of certs to include in an S/MIME message.  */
235 int gpgme_get_include_certs (GpgmeCtx ctx);
236
237 /* Set keylist mode in CTX to MODE.  */
238 GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
239
240 /* Get keylist mode in CTX.  */
241 int gpgme_get_keylist_mode (GpgmeCtx ctx);
242
243 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
244    passed as first argument to the passphrase callback function.  */
245 void gpgme_set_passphrase_cb (GpgmeCtx ctx,
246                               GpgmePassphraseCb cb, void *hook_value);
247
248 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
249    passed as first argument to the progress callback function.  */
250 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
251
252 /* Delete all signers from CTX.  */
253 void gpgme_signers_clear (GpgmeCtx ctx);
254
255 /* Add KEY to list of signers in CTX.  */
256 GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
257
258 /* Return the SEQth signer's key in CTX.  */
259 GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
260
261 /* Retrieve the signature status of signature IDX in CTX after a
262    successful verify operation in R_STAT (if non-null).  The creation
263    time stamp of the signature is returned in R_CREATED (if non-null).
264    The function returns a string containing the fingerprint.  */
265 const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
266                                   GpgmeSigStat *r_stat, time_t *r_created);
267
268 /* Get the key used to create signature IDX in CTX and return it in
269    R_KEY.  */
270 GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
271
272 /* Return a string with more info about the last crypto operating in CTX.
273    RESERVED should be zero.  The user has to free the string.  */
274 char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
275
276
277 /* Run control.  */
278
279 /* Cancel a pending operation in CTX.  */
280 void       gpgme_cancel (GpgmeCtx ctx);
281
282 /* Process the pending operation and, if HANG is non-zero, wait for
283    the pending operation to finish.  */
284 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
285
286
287 /* Functions to handle recipients.  */
288
289 /* Create a new recipients set and return it in R_RSET.  */
290 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
291
292 /* Release the recipients set RSET.  */
293 void gpgme_recipients_release (GpgmeRecipients rset);
294
295 /* Add NAME to the recipients set RSET.  */
296 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
297
298 /* Add NAME with validity AL to the recipients set RSET.  */
299 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
300                                                     const char *name,
301                                                     GpgmeValidity val);
302
303 /* Return the number of recipients in RSET.  */
304 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
305
306 /* Create a new enumeration handle for the recipients set RSET and
307    return it in ITER.  */
308 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
309                                        void **iter);
310
311 /* Return the next recipient from the recipient set RSET in the
312    enumerator ITER.  */
313 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
314                                         void **iter);
315
316 /* Destroy the enumerator ITER for the recipient set RSET.  */
317 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
318                                         void **iter);
319
320
321 /* Functions to handle data objects.  */
322
323 /* Create a new data buffer and return it in R_DH.  */
324 GpgmeError gpgme_data_new (GpgmeData *r_dh);
325
326 /* Create a new data buffer filled with SIZE bytes starting from
327    BUFFER.  If COPY is zero, copying is delayed until necessary, and
328    the data is taken from the original location when needed.  */
329 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
330                                     const char *buffer, size_t size,
331                                     int copy);
332
333 /* Create a new data buffer which retrieves the data from the callback
334    function READ_CB.  */
335 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
336                                         int (*read_cb) (void*,char *,size_t,size_t*),
337                                         void *read_cb_value);
338
339 /* Create a new data buffer filled with the content of file FNAME.
340    COPY must be non-zero (delayed reads are not supported yet).  */
341 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
342                                      const char *fname,
343                                      int copy);
344
345 /* Create a new data buffer filled with LENGTH bytes starting from
346    OFFSET within the file FNAME or stream FP (exactly one must be
347    non-zero).  */
348 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
349                                          const char *fname, FILE *fp,
350                                          off_t offset, size_t length);
351
352 /* Destroy the data buffer DH.  */
353 void gpgme_data_release (GpgmeData dh);
354
355 /* Destroy the data buffer DH and return a pointer to its content.
356    The memory has be to released with free by the user.  It's size is
357    returned in R_LEN.  */
358 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
359
360 /* Return the type of the data buffer DH.  */
361 GpgmeDataType gpgme_data_get_type (GpgmeData dh);
362
363 /* Reset the read pointer in DH.  */
364 GpgmeError gpgme_data_rewind (GpgmeData dh);
365
366 /* Read LENGTH bytes from the data object DH and store them in the
367    memory starting at BUFFER.  The number of bytes actually read is
368    returned in NREAD.  */
369 GpgmeError gpgme_data_read (GpgmeData dh, char *buffer,
370                             size_t length, size_t *nread);
371
372 /* Write LENGTH bytes starting from BUFFER into the data object DH.  */
373 GpgmeError gpgme_data_write (GpgmeData dh, const char *buffer, size_t length);
374
375
376 /* Key and trust functions.  */
377
378 /* Acquire a reference to KEY.  */
379 void gpgme_key_ref (GpgmeKey key);
380
381 /* Release a reference to KEY.  If this was the last one the key is
382    destroyed.  */
383 void gpgme_key_unref (GpgmeKey key);
384 void gpgme_key_release (GpgmeKey key);
385
386 /* Get the data from key KEY in a XML string, which has to be released
387    with free by the user.  */
388 char *gpgme_key_get_as_xml (GpgmeKey key);
389
390 /* Return the value of the attribute WHAT of KEY, which has to be
391    representable by a string.  IDX specifies a running index if the
392    attribute appears more than once in the key.  */
393 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
394                                        const void *reserved, int idx);
395
396 /* Return the value of the attribute WHAT of KEY, which has to be
397    representable by an unsigned integer.  IDX specifies a running
398    index if the attribute appears more than once in the key.  */
399 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
400                                         const void *reserved, int idx);
401
402 /* Release the trust item ITEM.  */
403 void gpgme_trust_item_release (GpgmeTrustItem item);
404
405 /* Return the value of the attribute WHAT of ITEM, which has to be
406    representable by a string.  IDX specifies a running index if the
407    attribute appears more than once in the key.  */
408 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
409                                               GpgmeAttr what,
410                                               const void *reserved, int idx);
411
412 /* Return the value of the attribute WHAT of KEY, which has to be
413    representable by an integer.  IDX specifies a running index if the
414    attribute appears more than once in the key.  */
415 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
416                                    const void *reserved, int idx);
417
418
419 /* Crypto operation function.  */
420
421 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
422    store the resulting ciphertext in CIPHER.  */
423 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
424                                    GpgmeRecipients recp,
425                                    GpgmeData plain, GpgmeData cipher);
426 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
427                              GpgmeRecipients recp,
428                              GpgmeData plain, GpgmeData cipher);
429
430 /* Decrypt ciphertext CIPHER within CTX and store the resulting
431    plaintext in PLAIN.  */
432 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
433                                    GpgmeData cipher, GpgmeData plain);
434 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
435                              GpgmeData cipher, GpgmeData plain);
436
437 /* Decrypt ciphertext CIPHER and make a signature verification within
438    CTX and store the resulting plaintext in PLAIN.  */
439 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
440                                           GpgmeData cipher, GpgmeData plain);
441 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
442                                     GpgmeData cipher, GpgmeData plain,
443                                     GpgmeSigStat *r_status);
444
445 /* Sign the plaintext PLAIN and store the signature in SIG.  Only
446    detached signatures are supported for now.  */
447 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
448                                 GpgmeData plain, GpgmeData sig,
449                                 GpgmeSigMode mode);
450 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
451                           GpgmeData plain, GpgmeData sig,
452                           GpgmeSigMode mode);
453
454 /* Verify within CTX that SIG is a valid signature for TEXT.  */
455 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx,
456                                   GpgmeData sig, GpgmeData text);
457 GpgmeError gpgme_op_verify (GpgmeCtx ctx,
458                             GpgmeData sig, GpgmeData text,
459                             GpgmeSigStat *r_status);
460
461 /* Import the key in KEYDATA into the keyring.  */
462 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
463 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
464
465 /* Export the keys listed in RECP into KEYDATA.  */
466 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
467                                   GpgmeData keydata);
468 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
469                             GpgmeData keydata);
470
471 /* Generate a new keypair and add it to the keyring.  PUBKEY and
472    SECKEY should be null for now.  PARMS specifies what keys should be
473    generated.  */
474 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
475                                   GpgmeData pubkey, GpgmeData seckey);
476 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
477                             GpgmeData pubkey, GpgmeData seckey);
478
479 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
480    keys are also deleted.  */
481 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
482                                   int allow_secret);
483 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
484                             int allow_secret);
485
486
487 /* Key management functions */
488
489 /* Start a keylist operation within CTX, searching for keys which
490    match PATTERN.  If SECRET_ONLY is true, only secret keys are
491    returned.  */
492 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
493                                    const char *pattern, int secret_only);
494
495 /* Return the next key from the keylist in R_KEY.  */
496 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
497
498 /* Terminate a pending keylist operation within CTX.  */
499 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
500
501
502 /* Start a trustlist operation within CTX, searching for trust items
503    which match PATTERN.  */
504 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
505                                      const char *pattern, int max_level);
506
507 /* Return the next trust item from the trustlist in R_ITEM.  */
508 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
509
510 /* Terminate a pending trustlist operation within CTX.  */
511 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
512
513
514 /* Various functions.  */
515
516 /* Check that the library fulfills the version requirement.  */
517 const char *gpgme_check_version (const char *req_version);
518
519 /* Check that the backend engine is available.  DEPRECATED.  */
520 GpgmeError  gpgme_check_engine (void);
521
522 /* Retrieve information about the backend engines.  */
523 const char *gpgme_get_engine_info (void);
524
525 /* Return a string describing ERR.  */
526 const char *gpgme_strerror (GpgmeError err);
527
528 /* Register an idle function.  */
529 typedef void (*GpgmeIdleFunc)(void);
530 GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle);
531
532
533 /* Engine support functions.  */
534
535 /* Verify that the engine implementing PROTO is installed and
536    available.  */
537 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
538
539
540 #ifdef __cplusplus
541 }
542 #endif
543 #endif /* GPGME_H */