1 /* pinentry.h - The interface for the PIN entry support library. 2 * Copyright (C) 2002, 2003, 2010, 2015 g10 Code GmbH 3 * 4 * This file is part of PINENTRY. 5 * 6 * PINENTRY is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * 11 * PINENTRY is distributed in the hope that it will be useful, but 12 * WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, see <https://www.gnu.org/licenses/>. 18 * SPDX-License-Identifier: GPL-2.0+ 19 */ 20 21 #ifndef PINENTRY_H 22 #define PINENTRY_H 23 24 #ifdef __cplusplus 25 extern "C" { 26 #if 0 27 } 28 #endif 29 #endif 30 31 typedef enum { 32 PINENTRY_COLOR_NONE, PINENTRY_COLOR_DEFAULT, 33 PINENTRY_COLOR_BLACK, PINENTRY_COLOR_RED, 34 PINENTRY_COLOR_GREEN, PINENTRY_COLOR_YELLOW, 35 PINENTRY_COLOR_BLUE, PINENTRY_COLOR_MAGENTA, 36 PINENTRY_COLOR_CYAN, PINENTRY_COLOR_WHITE 37 } pinentry_color_t; 38 39 struct pinentry 40 { 41 /* The window title, or NULL. (Assuan: "SETTITLE TITLE".) */ 42 char *title; 43 /* The description to display, or NULL. (Assuan: "SETDESC 44 DESC".) */ 45 char *description; 46 /* The error message to display, or NULL. (Assuan: "SETERROR 47 MESSAGE".) */ 48 char *error; 49 /* The prompt to display, or NULL. (Assuan: "SETPROMPT 50 prompt".) */ 51 char *prompt; 52 /* The OK button text to display, or NULL. (Assuan: "SETOK 53 OK".) */ 54 char *ok; 55 /* The Not-OK button text to display, or NULL. This is the text for 56 the alternative option shown by the third button. (Assuan: 57 "SETNOTOK NOTOK".) */ 58 char *notok; 59 /* The Cancel button text to display, or NULL. (Assuan: "SETCANCEL 60 CANCEL".) */ 61 char *cancel; 62 63 /* The buffer to store the secret into. */ 64 char *pin; 65 /* The length of the buffer. */ 66 int pin_len; 67 /* Whether the pin was read from an external cache (1) or entered by 68 the user (0). */ 69 int pin_from_cache; 70 71 /* The name of the X display to use if X is available and supported. 72 (Assuan: "OPTION display DISPLAY".) */ 73 char *display; 74 /* The name of the terminal node to open if X not available or 75 supported. (Assuan: "OPTION ttyname TTYNAME".) */ 76 char *ttyname; 77 /* The type of the terminal. (Assuan: "OPTION ttytype TTYTYPE".) */ 78 char *ttytype_l; 79 /* Set the alert mode (none, beep or flash). */ 80 char *ttyalert; 81 /* The LC_CTYPE value for the terminal. (Assuan: "OPTION lc-ctype 82 LC_CTYPE".) */ 83 char *lc_ctype; 84 /* The LC_MESSAGES value for the terminal. (Assuan: "OPTION 85 lc-messages LC_MESSAGES".) */ 86 char *lc_messages; 87 88 /* True if debug mode is requested. */ 89 int debug; 90 91 /* The number of seconds before giving up while waiting for user input. */ 92 int timeout; 93 94 /* True if caller should grab the keyboard. (Assuan: "OPTION grab" 95 or "OPTION no-grab".) */ 96 int grab; 97 98 /* The PID of the owner or 0 if not known. The owner is the process 99 * which actually triggered the the pinentry. For example gpg. */ 100 unsigned long owner_pid; 101 102 /* The numeric uid (user ID) of the owner process or -1 if not 103 * known. */ 104 int owner_uid; 105 106 /* The malloced hostname of the owner or NULL. */ 107 char *owner_host; 108 109 /* The window ID of the parent window over which the pinentry window 110 should be displayed. (Assuan: "OPTION parent-wid WID".) */ 111 int parent_wid; 112 113 /* The name of an optional file which will be touched after a curses 114 entry has been displayed. (Assuan: "OPTION touch-file 115 FILENAME".) */ 116 char *touch_file; 117 118 /* The frontend should set this to -1 if the user canceled the 119 request, and to the length of the PIN stored in pin 120 otherwise. */ 121 int result; 122 123 /* The frontend should set this if the NOTOK button was pressed. */ 124 int canceled; 125 126 /* The frontend should set this to true if an error with the local 127 conversion occurred. */ 128 int locale_err; 129 130 /* The frontend should set this to a gpg-error so that commands are 131 able to return specific error codes. This is an ugly hack due to 132 the fact that pinentry_cmd_handler_t returns the length of the 133 passphrase or a negative error code. */ 134 int specific_err; 135 136 /* The frontend may store a string with the error location here. */ 137 const char *specific_err_loc; 138 139 /* The frontend may store a malloced string here to emit an ERROR 140 * status code with this extra info along with SPECIFIC_ERR. */ 141 char *specific_err_info; 142 143 /* The frontend should set this to true if the window close button 144 has been used. This flag is used in addition to a regular return 145 value. */ 146 int close_button; 147 148 /* The caller should set this to true if only one button is 149 required. This is useful for notification dialogs where only a 150 dismiss button is required. */ 151 int one_button; 152 153 /* If true a second prompt for the passphrase is shown and the user 154 is expected to enter the same passphrase again. Pinentry checks 155 that both match. (Assuan: "SETREPEAT".) */ 156 char *repeat_passphrase; 157 158 /* The string to show if a repeated passphrase does not match. 159 (Assuan: "SETREPEATERROR ERROR".) */ 160 char *repeat_error_string; 161 162 /* Set to true if the passphrase has been entered a second time and 163 matches the first passphrase. */ 164 int repeat_okay; 165 166 /* If this is not NULL, a passphrase quality indicator is shown. 167 There will also be an inquiry back to the caller to get an 168 indication of the quality for the passphrase entered so far. The 169 string is used as a label for the quality bar. (Assuan: 170 "SETQUALITYBAR LABEL".) */ 171 char *quality_bar; 172 173 /* The tooltip to be show for the qualitybar. Malloced or NULL. 174 (Assuan: "SETQUALITYBAR_TT TOOLTIP".) */ 175 char *quality_bar_tt; 176 177 /* If this is not NULL, a generate action should be shown. 178 There will be an inquiry back to the caller to get such a 179 PIN. generate action. Malloced or NULL. 180 (Assuan: "GENPIN LABEL .) */ 181 char *genpin_label; 182 183 /* The tooltip to be show for the generate action. Malloced or NULL. 184 (Assuan: "GENPIN TOOLTIP".) */ 185 char *genpin_tt; 186 187 /* For the curses pinentry, the color of error messages. */ 188 pinentry_color_t color_fg; 189 int color_fg_bright; 190 pinentry_color_t color_bg; 191 pinentry_color_t color_so; 192 int color_so_bright; 193 194 /* Malloced and i18ned default strings or NULL. These strings may 195 include an underscore character to indicate an accelerator key. 196 A double underscore represents a plain one. */ 197 /* (Assuan: "OPTION default-ok OK"). */ 198 char *default_ok; 199 /* (Assuan: "OPTION default-cancel CANCEL"). */ 200 char *default_cancel; 201 /* (Assuan: "OPTION default-prompt PROMPT"). */ 202 char *default_prompt; 203 /* (Assuan: "OPTION default-pwmngr 204 SAVE_PASSWORD_WITH_PASSWORD_MANAGER?"). */ 205 char *default_pwmngr; 206 /* (Assuan: "OPTION default-cf-visi 207 Do you really want to make your passphrase visible?"). */ 208 char *default_cf_visi; 209 /* (Assuan: "OPTION default-tt-visi 210 Make passphrase visible?"). */ 211 char *default_tt_visi; 212 /* (Assuan: "OPTION default-tt-hide 213 Hide passphrase"). */ 214 char *default_tt_hide; 215 216 /* Whether we are allowed to read the password from an external 217 cache. (Assuan: "OPTION allow-external-password-cache") */ 218 int allow_external_password_cache; 219 220 /* We only try the cache once. */ 221 int tried_password_cache; 222 223 /* A stable identifier for the key. (Assuan: "SETKEYINFO 224 KEYINFO".) */ 225 char *keyinfo; 226 227 /* Whether we may cache the password (according to the user). */ 228 int may_cache_password; 229 230 /* NOTE: If you add any additional fields to this structure, be sure 231 to update the initializer in pinentry/pinentry.c!!! */ 232 233 /* For the quality indicator and genpin we need to do an inquiry. 234 Thus we need to save the assuan ctx. */ 235 void *ctx_assuan; 236 237 /* An UTF-8 string with an invisible character used to override the 238 default in some pinentries. Only the first character is 239 used. */ 240 char *invisible_char; 241 242 }; 243 typedef struct pinentry *pinentry_t; 244 245 246 /* The pinentry command handler type processes the pinentry request 247 PIN. If PIN->pin is zero, request a confirmation, otherwise a PIN 248 entry. On confirmation, the function should return TRUE if 249 confirmed, and FALSE otherwise. On PIN entry, the function should 250 return -1 if an error occurred or the user cancelled the operation 251 and 1 otherwise. */ 252 typedef int (*pinentry_cmd_handler_t) (pinentry_t pin); 253 254 /* Start the pinentry event loop. The program will start to process 255 Assuan commands until it is finished or an error occurs. If an 256 error occurs, -1 is returned and errno indicates the type of an 257 error. Otherwise, 0 is returned. */ 258 int pinentry_loop (void); 259 260 /* The same as above but allows to specify the i/o descriptors. 261 * infd and outfd will be duplicated in this function so the caller 262 * still has to close them if necessary. 263 */ 264 int pinentry_loop2 (int infd, int outfd); 265 266 267 /* Convert the UTF-8 encoded string TEXT to the encoding given in 268 LC_CTYPE. Return NULL on error. */ 269 char *pinentry_utf8_to_local (const char *lc_ctype, const char *text); 270 271 /* Convert TEXT which is encoded according to LC_CTYPE to UTF-8. With 272 SECURE set to true, use secure memory for the returned buffer. 273 Return NULL on error. */ 274 char *pinentry_local_to_utf8 (char *lc_ctype, char *text, int secure); 275 276 char *pinentry_get_title (pinentry_t pe); 277 278 /* Run a quality inquiry for PASSPHRASE of LENGTH. */ 279 int pinentry_inq_quality (pinentry_t pin, 280 const char *passphrase, size_t length); 281 282 /* Run a genpin iquriry. Returns a malloced string or NULL */ 283 char *pinentry_inq_genpin (pinentry_t pin); 284 285 /* Try to make room for at least LEN bytes for the pin in the pinentry 286 PIN. Returns new buffer on success and 0 on failure. */ 287 char *pinentry_setbufferlen (pinentry_t pin, int len); 288 289 /* Use the buffer at BUFFER for PIN->PIN. BUFFER must be NULL or 290 allocated using secmem_alloc. LEN is the size of the buffer. If 291 it is unknown, but BUFFER is a NUL terminated string, you pass 0 to 292 just use strlen(buffer)+1. */ 293 void pinentry_setbuffer_use (pinentry_t pin, char *buffer, int len); 294 295 /* Initialize the secure memory subsystem, drop privileges and 296 return. Must be called early. */ 297 void pinentry_init (const char *pgmname); 298 299 /* Return true if either DISPLAY is set or ARGV contains the string 300 "--display". */ 301 int pinentry_have_display (int argc, char **argv); 302 303 /* Parse the command line options. May exit the program if only help 304 or version output is requested. */ 305 void pinentry_parse_opts (int argc, char *argv[]); 306 307 /* Set the optional flag used with getinfo. */ 308 void pinentry_set_flavor_flag (const char *string); 309 310 311 312 /* The caller must define this variable to process assuan commands. */ 313 extern pinentry_cmd_handler_t pinentry_cmd_handler; 314 315 316 317 318 319 #ifdef HAVE_W32_SYSTEM 320 /* Windows declares sleep as obsolete, but provides a definition for 321 _sleep but non for the still existing sleep. */ 322 #define sleep(a) _sleep ((a)) 323 #endif /*HAVE_W32_SYSTEM*/ 324 325 326 327 #if 0 328 { 329 #endif 330 #ifdef __cplusplus 331 } 332 #endif 333 334 #endif /* PINENTRY_H */ 335