1 /* gpgmetools.h - additional gpgme support functions for GPA. 2 Copyright (C) 2002, Miguel Coca. 3 Copyright (C) 2005, 2008 g10 Code GmbH. 4 Copyright (C) 2015 g10 Code GmbH. 5 6 This file is part of GPA 7 8 GPA is free software; you can redistribute it and/or modify it 9 under the terms of the GNU General Public License as published by 10 the Free Software Foundation; either version 3 of the License, or 11 (at your option) any later version. 12 13 GPA is distributed in the hope that it will be useful, but WITHOUT 14 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 15 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public 16 License for more details. 17 18 You should have received a copy of the GNU General Public License 19 along with this program; if not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 /* A set of auxiliary functions for common tasks related to GPGME. */ 23 24 #ifndef GPGMETOOLS_H 25 #define GPGMETOOLS_H 26 27 #include <gtk/gtk.h> 28 #include <gpgme.h> 29 30 #include "gpacontext.h" 31 32 /* Internal algorithm identifiers, describing which keys to 33 create. */ 34 typedef enum 35 { 36 GPA_KEYGEN_ALGO_RSA_RSA, 37 GPA_KEYGEN_ALGO_RSA_ELGAMAL, 38 GPA_KEYGEN_ALGO_RSA, 39 GPA_KEYGEN_ALGO_DSA_ELGAMAL, 40 GPA_KEYGEN_ALGO_DSA, 41 GPA_KEYGEN_ALGO_VIA_CARD 42 } gpa_keygen_algo_t; 43 44 45 46 typedef struct 47 { 48 /* User ID. */ 49 gchar *name; 50 gchar *email; 51 gchar *comment; 52 53 /* Algorithm. */ 54 gpa_keygen_algo_t algo; 55 56 /* Key size. */ 57 gint keysize; 58 59 /* The password to use. */ 60 gchar *password; 61 62 /* Epiration date. It is only used if it is valid. */ 63 GDate expire; 64 65 /* True if the encryption key is created with an backup file. */ 66 gboolean backup; 67 68 /* Used to return an error description. */ 69 char *r_error_desc; 70 71 } gpa_keygen_para_t; 72 73 74 /* An object to collect information about key imports. */ 75 struct gpa_import_result_s 76 { 77 unsigned int files; /* # of files imported. */ 78 unsigned int bad_files; /* # of files with errors. */ 79 80 /* To avoid breaking translated strings the variables below are int 81 and not unsigned int as they should be for counters. */ 82 int considered; 83 int imported; 84 int unchanged; 85 int secret_read; 86 int secret_imported; 87 int secret_unchanged; 88 }; 89 typedef struct gpa_import_result_s *gpa_import_result_t; 90 91 92 93 /* Report an unexpected error in GPGME and quit the application. 94 Better to use the macro instead of the function. */ 95 #define gpa_gpgme_error(err) \ 96 do { _gpa_gpgme_error (err, __FILE__, __LINE__); } while (0) 97 void _gpa_gpgme_error (gpg_error_t err, 98 const char *file, int line) G_GNUC_NORETURN; 99 100 /* The same as gpa_gpgme_error, without quitting. */ 101 #define gpa_gpgme_warn(err,desc,ctx) \ 102 do { _gpa_gpgme_warn (err, desc, ctx, __FILE__, __LINE__); } while (0) 103 #define gpa_gpgme_warning_ext(err,desc) \ 104 do { _gpa_gpgme_warn (err, desc, NULL, __FILE__, __LINE__); } while (0) 105 #define gpa_gpgme_warning(err) \ 106 do { _gpa_gpgme_warn (err, NULL, NULL, __FILE__, __LINE__); } while (0) 107 void _gpa_gpgme_warn (gpg_error_t err, const char *desc, GpaContext *ctx, 108 const char *file, int line); 109 110 /* Initialize a gpgme_ctx_t for use with GPA. */ 111 gpgme_ctx_t gpa_gpgme_new (void); 112 113 /* Write the contents of the gpgme_data_t object to the file. Receives 114 a filehandle instead of the filename, so that the caller can make 115 sure the file is accesible before putting anything into data. */ 116 void dump_data_to_file (gpgme_data_t data, FILE *file); 117 118 /* Not really a gpgme function, but needed in most places 119 dump_data_to_file is used. Opens a file for writing, asking the 120 user to overwrite if it exists and reporting any errors. Returns 121 NULL on failure, but you can assume the user has been informed of 122 the error (or maybe he just didn't want to overwrite!). The 123 filename of the file that is actually open (if FILENAME already 124 exists, then the user can choose a different file) is saved in 125 *FILENAME_USED. It must be xfreed. This is set even if this 126 function returns NULL! */ 127 FILE *gpa_fopen (const char *filename, GtkWidget *parent, 128 char **filename_used); 129 130 /* Do a gpgme_data_new_from_file and report any GPG_ERR_File_Error to 131 the user. */ 132 gpg_error_t gpa_gpgme_data_new_from_file (gpgme_data_t *data, 133 const char *filename, 134 GtkWidget *parent); 135 136 /* Create a new gpgme_data_t from a file for writing, and return the 137 file descriptor for the file. Always reports all errors to the 138 user. The _direct variant does not check for overwriting. The 139 filename of the file that is actually open (if FILENAME already 140 exists, then the user can choose a different file) is saved in 141 *FILENAME_USED. It must be xfreed. This is set even if this 142 function returns NULL! */ 143 int gpa_open_output_direct (const char *filename, gpgme_data_t *data, 144 GtkWidget *parent); 145 int gpa_open_output (const char *filename, gpgme_data_t *data, 146 GtkWidget *parent, char **filename_used); 147 148 /* Create a new gpgme_data_t from a file for reading, and return the 149 file descriptor for the file. Always reports all errors to the user. */ 150 int gpa_open_input (const char *filename, gpgme_data_t *data, 151 GtkWidget *parent); 152 153 /* Write the contents of the gpgme_data_t into the clipboard. */ 154 int dump_data_to_clipboard (gpgme_data_t data, GtkClipboard *clipboard); 155 156 /* Begin generation of a key with the given parameters. It prepares 157 the parameters required by Gpgme and returns whatever 158 gpgme_op_genkey_start returns. */ 159 gpg_error_t gpa_generate_key_start (gpgme_ctx_t ctx, 160 gpa_keygen_para_t *params); 161 162 /* Backup a key. It exports both the public and secret keys to a 163 file. IS_X509 tells the function that the fingerprint is from an 164 X.509 key. Returns TRUE on success and FALSE on error. It 165 displays errors to the user. */ 166 gboolean gpa_backup_key (const gchar *fpr, const char *filename, int is_x509); 167 168 gpa_keygen_para_t *gpa_keygen_para_new (void); 169 170 void gpa_keygen_para_free (gpa_keygen_para_t *params); 171 172 /* Ownertrust strings. */ 173 const gchar *gpa_key_ownertrust_string (gpgme_key_t key); 174 175 /* Key validity strings. */ 176 const gchar *gpa_key_validity_string (gpgme_key_t key); 177 178 /* UID validity strings. */ 179 const gchar *gpa_uid_validity_string (gpgme_user_id_t uid); 180 181 /* Function to manage import results. */ 182 void gpa_gpgme_update_import_results (gpa_import_result_t result, 183 unsigned int files, 184 unsigned int bad_files, 185 gpgme_import_result_t info); 186 void gpa_gpgme_show_import_results (GtkWidget *parent, 187 gpa_import_result_t result); 188 189 190 191 /* This is the function called by GPGME when it wants a 192 passphrase. */ 193 gpg_error_t gpa_passphrase_cb (void *hook, const char *uid_hint, 194 const char *passphrase_info, 195 int prev_was_bad, int fd); 196 197 198 /* Convenience functions to access key attributes, which need to be 199 filtered before being displayed to the user. */ 200 201 /* Return the user ID string, making sure it is properly UTF-8 202 encoded. Allocates a new string, which must be freed with 203 g_free(). */ 204 gchar *gpa_gpgme_key_get_userid (gpgme_user_id_t key); 205 206 /* Return the key fingerprint, properly formatted according to the key 207 version. Allocates a new string, which must be freed with 208 g_free(). This is based on code from GPAPA's extract_fingerprint. */ 209 gchar *gpa_gpgme_key_format_fingerprint (const char *fpraw); 210 211 /* Return the short key ID of the indicated key. The returned string 212 is valid as long as the key is valid. */ 213 const gchar *gpa_gpgme_key_get_short_keyid (gpgme_key_t key); 214 215 /* Convenience function to access key signature attibutes, much like 216 the previous ones. */ 217 218 /* Return the user ID, making sure it is properly UTF-8 encoded. 219 Allocates a new string, which must be freed with g_free(). */ 220 gchar *gpa_gpgme_key_sig_get_userid (gpgme_key_sig_t sig); 221 222 /* Return the short key ID of the indicated key. The returned string 223 is valid as long as the key is valid. */ 224 const gchar *gpa_gpgme_key_sig_get_short_keyid (gpgme_key_sig_t sig); 225 226 /* Return a string with the status of the key signature. */ 227 const gchar *gpa_gpgme_key_sig_get_sig_status (gpgme_key_sig_t sig, 228 GHashTable *revoked); 229 230 /* Return a string with the level of the key signature. */ 231 const gchar *gpa_gpgme_key_sig_get_level (gpgme_key_sig_t sig); 232 233 /* Return a human readable string with the status of the signature 234 SIG. */ 235 char *gpa_gpgme_get_signature_desc (gpgme_ctx_t ctx, gpgme_signature_t sig, 236 char **r_keydesc, gpgme_key_t *r_key); 237 238 239 /* Return a string listing the capabilities of a key. */ 240 const gchar *gpa_get_key_capabilities_text (gpgme_key_t key); 241 242 /* Return a copy of the key array. */ 243 gpgme_key_t *gpa_gpgme_copy_keyarray (gpgme_key_t *keys); 244 245 /* Release all keys in the array KEYS as weel as ARRY itself. */ 246 void gpa_gpgme_release_keyarray (gpgme_key_t *keys); 247 248 /* Try switching to the gpg2 backend. */ 249 void gpa_switch_to_gpg2 (const char *gpg_binary, const char *gpgsm_binary); 250 251 /* Return true if the gpg engine has at least version NEED_VERSION. */ 252 int is_gpg_version_at_least (const char *need_version); 253 254 /* Run a simple gpg command. */ 255 gpg_error_t gpa_start_simple_gpg_command (gboolean (*cb) 256 (void *opaque, char *line), 257 void *cb_arg, 258 gpgme_protocol_t protocol, 259 int use_stderr, 260 const char *first_arg, ... 261 ) G_GNUC_NULL_TERMINATED; 262 263 void gpa_start_agent (void); 264 265 /* Funtions to check user inputs in the same way gpg does. */ 266 const char *gpa_validate_gpg_name (const char *name); 267 const char *gpa_validate_gpg_email (const char *email); 268 const char *gpa_validate_gpg_comment (const char *comment); 269 270 271 #endif /*GPGMETOOLS_H*/ 272