2007-09-27 Marcus Brinkmann <marcus@g10code.de>
[gpgme.git] / gpgme / gpgme.h
index 7ebb61b..c0bc8e3 100644 (file)
@@ -1,22 +1,23 @@
 /* gpgme.h - Public interface to GnuPG Made Easy.
    Copyright (C) 2000 Werner Koch (dd9jn)
-   Copyright (C) 2001, 2002, 2003 g10 Code GmbH
+   Copyright (C) 2001, 2002, 2003, 2004, 2005, 2007 g10 Code GmbH
 
    This file is part of GPGME.
  
    GPGME is free software; you can redistribute it and/or modify it
-   under the terms of the GNU General Public License as published by
-   the Free Software Foundation; either version 2 of the License, or
-   (at your option) any later version.
+   under the terms of the GNU Lesser General Public License as
+   published by the Free Software Foundation; either version 2.1 of
+   the License, or (at your option) any later version.
+   
    GPGME is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-   General Public License for more details.
-   You should have received a copy of the GNU General Public License
-   along with GPGME; if not, write to the Free Software Foundation,
-   Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
+   Lesser General Public License for more details.
+   
+   You should have received a copy of the GNU Lesser General Public
+   License along with this program; if not, write to the Free Software
+   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 
+   MA 02110-1301, USA.  */
 
 #ifndef GPGME_H
 #define GPGME_H
 # include <sys/types.h>
 #endif
 
+#include <gpg-error.h>
+
 #ifdef __cplusplus
 extern "C" {
 #if 0 /* just to make Emacs auto-indent happy */
 }
 #endif
-#endif
+#endif /* __cplusplus */
 
-#include <gpg-error.h>
 
 \f
 /* Check for compiler features.  */
@@ -71,7 +73,8 @@ extern "C" {
    AM_PATH_GPGME macro) check that this header matches the installed
    library.  Warning: Do not edit the next line.  configure will do
    that for you!  */
-#define GPGME_VERSION "0.4.3"
+#define GPGME_VERSION "1.1.6-svn1264"
+
 
 \f
 /* Some opaque data types used by GPGME.  */
@@ -131,11 +134,14 @@ gpgme_err_source (gpgme_error_t err)
    code in the error value ERR.  This function is not thread safe.  */
 const char *gpgme_strerror (gpgme_error_t err);
 
-/* Return a pointer to a string containing a description of the error
-   code in the error value ERR.  The buffer for the string is
-   allocated with malloc(), and has to be released by the user.  On
-   error, NULL is returned.  */
-char *gpgme_strerror_r (gpgme_error_t err);
+/* Return the error string for ERR in the user-supplied buffer BUF of
+   size BUFLEN.  This function is, in contrast to gpg_strerror,
+   thread-safe if a thread-safe strerror_r() function is provided by
+   the system.  If the function succeeds, 0 is returned and BUF
+   contains the string describing the error.  If the buffer was not
+   large enough, ERANGE is returned and BUF contains as much of the
+   beginning of the error string as fits into the buffer.  */
+int gpgme_strerror_r (gpg_error_t err, char *buf, size_t buflen);
 
 
 /* Return a pointer to a string containing a description of the error
@@ -295,10 +301,61 @@ typedef enum
   {
     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
     GPGME_PROTOCOL_CMS     = 1,
+    GPGME_PROTOCOL_UNKNOWN = 255
   }
 gpgme_protocol_t;
 
 \f
+/* The available keylist mode flags.  */
+#define GPGME_KEYLIST_MODE_LOCAL               1
+#define GPGME_KEYLIST_MODE_EXTERN              2
+#define GPGME_KEYLIST_MODE_SIGS                        4
+#define GPGME_KEYLIST_MODE_SIG_NOTATIONS       8
+#define GPGME_KEYLIST_MODE_VALIDATE            256
+
+typedef unsigned int gpgme_keylist_mode_t;
+
+\f
+/* Signature notations.  */
+
+/* The available signature notation flags.  */
+#define GPGME_SIG_NOTATION_HUMAN_READABLE      1
+#define GPGME_SIG_NOTATION_CRITICAL            2
+
+typedef unsigned int gpgme_sig_notation_flags_t;
+
+struct _gpgme_sig_notation
+{
+  struct _gpgme_sig_notation *next;
+
+  /* If NAME is a null pointer, then VALUE contains a policy URL
+     rather than a notation.  */
+  char *name;
+
+  /* The value of the notation data.  */
+  char *value;
+
+  /* The length of the name of the notation data.  */
+  int name_len;
+
+  /* The length of the value of the notation data.  */
+  int value_len;
+
+  /* The accumulated flags.  */
+  gpgme_sig_notation_flags_t flags;
+
+  /* Notation data is human-readable.  */
+  unsigned int human_readable : 1;
+
+  /* Notation data is critical.  */
+  unsigned int critical : 1;
+
+  /* Internal to GPGME, do not use.  */
+  int _unused : 30;
+};
+typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
+
+\f
 /* The possible stati for the edit operation.  */
 typedef enum
   {
@@ -381,7 +438,19 @@ typedef enum
     GPGME_STATUS_EXPSIG,
     GPGME_STATUS_EXPKEYSIG,
     GPGME_STATUS_TRUNCATED,
-    GPGME_STATUS_ERROR
+    GPGME_STATUS_ERROR,
+    GPGME_STATUS_NEWSIG,
+    GPGME_STATUS_REVKEYSIG,
+    GPGME_STATUS_SIG_SUBPACKET,
+    GPGME_STATUS_NEED_PASSPHRASE_PIN,
+    GPGME_STATUS_SC_OP_FAILURE,
+    GPGME_STATUS_SC_OP_SUCCESS,
+    GPGME_STATUS_CARDCTRL,
+    GPGME_STATUS_BACKUP_KEY_CREATED,
+    GPGME_STATUS_PKA_TRUST_BAD,
+    GPGME_STATUS_PKA_TRUST_GOOD,
+
+    GPGME_STATUS_PLAINTEXT
   }
 gpgme_status_code_t;
 
@@ -395,13 +464,16 @@ struct _gpgme_engine_info
   gpgme_protocol_t protocol;
 
   /* The file name of the engine binary.  */
-  const char *file_name;
-
+  char *file_name;
+  
   /* The version string of the installed engine.  */
-  const char *version;
+  char *version;
 
   /* The minimum version required for GPGME.  */
   const char *req_version;
+
+  /* The home directory used, or NULL if default.  */
+  char *home_dir;
 };
 typedef struct _gpgme_engine_info *gpgme_engine_info_t;
 
@@ -438,8 +510,11 @@ struct _gpgme_subkey
   /* True if subkey can be used for authentication.  */
   unsigned int can_authenticate : 1;
 
+  /* True if subkey is qualified for signatures according to German law.  */
+  unsigned int is_qualified : 1;
+
   /* Internal to GPGME, do not use.  */
-  unsigned int _unused : 23;
+  unsigned int _unused : 22;
   
   /* Public key algorithm supported by this subkey.  */
   gpgme_pubkey_algo_t pubkey_algo;
@@ -470,7 +545,7 @@ struct _gpgme_key_sig
 {
   struct _gpgme_key_sig *next;
 
-  /* True if the signature is revoked.  */
+  /* True if the signature is a revocation signature.  */
   unsigned int revoked : 1;
 
   /* True if the signature is expired.  */
@@ -503,8 +578,12 @@ struct _gpgme_key_sig
   /* Same as in gpgme_signature_t.  */
   gpgme_error_t status;
 
-  /* Crypto backend specific signature class.  */
-  unsigned int class;
+#ifdef __cplusplus
+  unsigned int _obsolete_class _GPGME_DEPRECATED;
+#else
+  /* Must be set to SIG_CLASS below.  */
+  unsigned int class _GPGME_DEPRECATED;
+#endif
 
   /* The user ID string.  */
   char *uid;
@@ -517,6 +596,15 @@ struct _gpgme_key_sig
 
   /* The comment part of the user ID.  */
   char *comment;
+
+  /* Crypto backend specific signature class.  */
+  unsigned int sig_class;
+
+  /* Notation data and policy URLs.  */
+  gpgme_sig_notation_t notations;
+
+  /* Internal to GPGME, do not use.  */
+  gpgme_sig_notation_t _last_notation;
 };
 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
 
@@ -592,8 +680,11 @@ struct _gpgme_key
   /* True if key can be used for authentication.  */
   unsigned int can_authenticate : 1;
 
+  /* True if subkey is qualified for signatures according to German law.  */
+  unsigned int is_qualified : 1;
+
   /* Internal to GPGME, do not use.  */
-  unsigned int _unused : 23;
+  unsigned int _unused : 22;
 
   /* This is the protocol supported by this key.  */
   gpgme_protocol_t protocol;
@@ -625,6 +716,9 @@ struct _gpgme_key
 
   /* Internal to GPGME, do not use.  */
   gpgme_user_id_t _last_uid;
+
+  /* The keylist mode that was active when listing the key.  */
+  gpgme_keylist_mode_t keylist_mode;
 };
 typedef struct _gpgme_key *gpgme_key_t;
 
@@ -677,21 +771,15 @@ void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
 /* Return non-zero if text mode is set in CTX.  */
 int gpgme_get_textmode (gpgme_ctx_t ctx);
 
+/* Use whatever the default of the backend crypto engine is.  */
+#define GPGME_INCLUDE_CERTS_DEFAULT    -256
+
 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
 
 /* Return the number of certs to include in an S/MIME message.  */
 int gpgme_get_include_certs (gpgme_ctx_t ctx);
 
-/* The available keylist mode flags.  */
-typedef enum
-  {
-    GPGME_KEYLIST_MODE_LOCAL  = 1,
-    GPGME_KEYLIST_MODE_EXTERN = 2,
-    GPGME_KEYLIST_MODE_SIGS   = 4
-  }
-gpgme_keylist_mode_t;
-
 /* Set keylist mode in CTX to MODE.  */
 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
                                      gpgme_keylist_mode_t mode);
@@ -719,6 +807,23 @@ void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
                            void **hook_value);
 
+/* This function sets the locale for the context CTX, or the default
+   locale if CTX is a null pointer.  */
+gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
+                               const char *value);
+
+/* Get the information about the configured engines.  A pointer to the
+   first engine in the statically allocated linked list is returned.
+   The returned data is valid until the next gpgme_ctx_set_engine_info.  */
+gpgme_engine_info_t gpgme_ctx_get_engine_info (gpgme_ctx_t ctx);
+
+/* Set the engine info for the context CTX, protocol PROTO, to the
+   file name FILE_NAME and the home directory HOME_DIR.  */
+gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t ctx,
+                                        gpgme_protocol_t proto,
+                                        const char *file_name,
+                                        const char *home_dir);
+
 \f
 /* Return a statically allocated string with the name of the public
    key algorithm ALGO, or NULL if that name is not known.  */
@@ -765,6 +870,22 @@ gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
      _GPGME_DEPRECATED;
 
 \f
+/* Clear all notation data from the context.  */
+void gpgme_sig_notation_clear (gpgme_ctx_t ctx);
+
+/* Add the human-readable notation data with name NAME and value VALUE
+   to the context CTX, using the flags FLAGS.  If NAME is NULL, then
+   VALUE should be a policy URL.  The flag
+   GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
+   data, and false for policy URLs.  */
+gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
+                                     const char *value,
+                                     gpgme_sig_notation_flags_t flags);
+
+/* Get the sig notations for this context.  */
+gpgme_sig_notation_t gpgme_sig_notation_get (gpgme_ctx_t ctx);
+
+\f
 /* Run control.  */
 
 /* The type of an I/O callback function.  */
@@ -879,10 +1000,13 @@ gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
                                       int copy);
 
 /* Destroy the data buffer DH and return a pointer to its content.
-   The memory has be to released with free by the user.  It's size is
-   returned in R_LEN.  */
+   The memory has be to released with gpgme_free() by the user.  It's
+   size is returned in R_LEN.  */
 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
 
+/* Release the memory returned by gpgme_data_release_and_get_mem().  */
+void gpgme_free (void *buffer);
+
 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
                                       gpgme_data_cbs_t cbs,
                                       void *handle);
@@ -898,6 +1022,14 @@ gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
                                       gpgme_data_encoding_t enc);
 
+/* Get the file name associated with the data object with handle DH, or
+   NULL if there is none.  */
+char *gpgme_data_get_file_name (gpgme_data_t dh);
+
+/* Set the file name associated with the data object with handle DH to
+   FILE_NAME.  */
+gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh,
+                                       const char *file_name);
 
 
 /* Create a new data buffer which retrieves the data from the callback
@@ -980,6 +1112,10 @@ unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
 \f
 /* Crypto Operations.  */
 
+/* Cancel a pending asynchronous operation.  */
+gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
+
+\f
 struct _gpgme_invalid_key
 {
   struct _gpgme_invalid_key *next;
@@ -1030,9 +1166,40 @@ gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
 
 \f
 /* Decryption.  */
+
+struct _gpgme_recipient
+{
+  struct _gpgme_recipient *next;
+
+  /* The key ID of key for which the text was encrypted.  */
+  char *keyid;
+
+  /* Internal to GPGME, do not use.  */
+  char _keyid[16 + 1];
+
+  /* The public key algorithm of the recipient key.  */
+  gpgme_pubkey_algo_t pubkey_algo;
+
+  /* The status of the recipient.  */
+  gpgme_error_t status;
+};
+typedef struct _gpgme_recipient *gpgme_recipient_t;
+
 struct _gpgme_op_decrypt_result
 {
   char *unsupported_algorithm;
+
+  /* Key should not have been used for encryption.  */
+  unsigned int wrong_key_usage : 1;
+
+  /* Internal to GPGME, do not use.  */
+  int _unused : 31;
+
+  gpgme_recipient_t recipients;
+
+  /* The original file name of the plaintext message, if
+     available.  */
+  char *file_name;
 };
 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
 
@@ -1079,8 +1246,15 @@ struct _gpgme_new_signature
   /* The fingerprint of the signature.  */
   char *fpr;
 
+#ifdef __cplusplus
+  unsigned int _obsolete_class_2;
+#else
+  /* Must be set to SIG_CLASS below.  */
+  unsigned int class _GPGME_DEPRECATED;
+#endif
+
   /* Crypto backend specific signature class.  */
-  unsigned int class;
+  unsigned int sig_class;
 };
 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
 
@@ -1105,16 +1279,6 @@ gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
 
 \f
 /* Verify.  */
-struct _gpgme_sig_notation
-{
-  struct _gpgme_sig_notation *next;
-
-  /* If NAME is a null pointer, then VALUE contains a policy URL
-     rather than a notation.  */
-  char *name;
-  char *value;
-};
-typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
 
 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
 typedef enum
@@ -1155,19 +1319,39 @@ struct _gpgme_signature
   /* Signature exipration time or 0.  */
   unsigned long exp_timestamp;
 
-  int wrong_key_usage : 1;
+  /* Key should not have been used for signing.  */
+  unsigned int wrong_key_usage : 1;
+
+  /* PKA status: 0 = not available, 1 = bad, 2 = okay, 3 = RFU. */
+  unsigned int pka_trust : 2;
+
+  /* Validity has been verified using the chain model. */
+  unsigned int chain_model : 1;
 
   /* Internal to GPGME, do not use.  */
-  int _unused : 31;
+  int _unused : 28;
 
   gpgme_validity_t validity;
   gpgme_error_t validity_reason;
+
+  /* The public key algorithm used to create the signature.  */
+  gpgme_pubkey_algo_t pubkey_algo;
+
+  /* The hash algorithm used to create the signature.  */
+  gpgme_hash_algo_t hash_algo;
+
+  /* The mailbox from the PKA information or NULL. */
+  char *pka_address;
 };
 typedef struct _gpgme_signature *gpgme_signature_t;
 
 struct _gpgme_op_verify_result
 {
   gpgme_signature_t signatures;
+
+  /* The original file name of the plaintext message, if
+     available.  */
+  char *file_name;
 };
 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
 
@@ -1184,23 +1368,22 @@ gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
 
 \f
 /* Import.  */
-enum
-  {
-    /* The key was new.  */
-    GPGME_IMPORT_NEW = 1,
 
-    /* The key contained new user IDs.  */
-    GPGME_IMPORT_UID = 2,
+/* The key was new.  */
+#define GPGME_IMPORT_NEW       1
+
+/* The key contained new user IDs.  */
+#define GPGME_IMPORT_UID       2
 
-    /* The key contained new signatures.  */
-    GPGME_IMPORT_SIG = 4,
+/* The key contained new signatures.  */
+#define GPGME_IMPORT_SIG       4
 
-    /* The key contained new sub keys.  */
-    GPGME_IMPORT_SUBKEY        = 8,
+/* The key contained new sub keys.  */
+#define GPGME_IMPORT_SUBKEY    8
+
+/* The key contained a secret key.  */
+#define GPGME_IMPORT_SECRET    16
 
-    /* The key contained a secret key.  */
-    GPGME_IMPORT_SECRET = 16
-  };
 
 struct _gpgme_import_status
 {
@@ -1342,6 +1525,15 @@ gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
                             gpgme_edit_cb_t fnc, void *fnc_value,
                             gpgme_data_t out);
 
+/* Edit the card for the key KEY.  Send status and command requests to
+   FNC and output of edit commands to OUT.  */
+gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
+                                       gpgme_edit_cb_t fnc, void *fnc_value,
+                                       gpgme_data_t out);
+gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t ctx, gpgme_key_t key,
+                                 gpgme_edit_cb_t fnc, void *fnc_value,
+                                 gpgme_data_t out);
+
 \f
 /* Key management functions.  */
 struct _gpgme_op_keylist_result
@@ -1453,9 +1645,18 @@ int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
 /* Check that the library fulfills the version requirement.  */
 const char *gpgme_check_version (const char *req_version);
 
-/* Retrieve information about the backend engines.  */
+/* Get the information about the configured and installed engines.  A
+   pointer to the first engine in the statically allocated linked list
+   is returned in *INFO.  If an error occurs, it is returned.  The
+   returned data is valid until the next gpgme_set_engine_info.  */
 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
 
+/* Set the default engine info for the protocol PROTO to the file name
+   FILE_NAME and the home directory HOME_DIR.  */
+gpgme_error_t gpgme_set_engine_info (gpgme_protocol_t proto,
+                                    const char *file_name,
+                                    const char *home_dir);
+
 \f
 /* Engine support functions.  */