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