pinentry.h (9541B)
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 <http://www.gnu.org/licenses/>. 18 */ 19 20 #ifndef PINENTRY_H 21 #define PINENTRY_H 22 23 #ifdef __cplusplus 24 extern "C" { 25 #if 0 26 } 27 #endif 28 #endif 29 30 typedef enum { 31 PINENTRY_COLOR_NONE, PINENTRY_COLOR_DEFAULT, 32 PINENTRY_COLOR_BLACK, PINENTRY_COLOR_RED, 33 PINENTRY_COLOR_GREEN, PINENTRY_COLOR_YELLOW, 34 PINENTRY_COLOR_BLUE, PINENTRY_COLOR_MAGENTA, 35 PINENTRY_COLOR_CYAN, PINENTRY_COLOR_WHITE 36 } pinentry_color_t; 37 38 struct pinentry 39 { 40 /* The window title, or NULL. (Assuan: "SETTITLE TITLE".) */ 41 char *title; 42 /* The description to display, or NULL. (Assuan: "SETDESC 43 DESC".) */ 44 char *description; 45 /* The error message to display, or NULL. (Assuan: "SETERROR 46 MESSAGE".) */ 47 char *error; 48 /* The prompt to display, or NULL. (Assuan: "SETPROMPT 49 prompt".) */ 50 char *prompt; 51 /* The OK button text to display, or NULL. (Assuan: "SETOK 52 OK".) */ 53 char *ok; 54 /* The Not-OK button text to display, or NULL. This is the text for 55 the alternative option shown by the third button. (Assuan: 56 "SETNOTOK NOTOK".) */ 57 char *notok; 58 /* The Cancel button text to display, or NULL. (Assuan: "SETCANCEL 59 CANCEL".) */ 60 char *cancel; 61 62 /* The buffer to store the secret into. */ 63 char *pin; 64 /* The length of the buffer. */ 65 int pin_len; 66 /* Whether the pin was read from an external cache (1) or entered by 67 the user (0). */ 68 int pin_from_cache; 69 70 /* The name of the X display to use if X is available and supported. 71 (Assuan: "OPTION display DISPLAY".) */ 72 char *display; 73 /* The name of the terminal node to open if X not available or 74 supported. (Assuan: "OPTION ttyname TTYNAME".) */ 75 char *ttyname; 76 /* The type of the terminal. (Assuan: "OPTION ttytype TTYTYPE".) */ 77 char *ttytype; 78 /* The LC_CTYPE value for the terminal. (Assuan: "OPTION lc-ctype 79 LC_CTYPE".) */ 80 char *lc_ctype; 81 /* The LC_MESSAGES value for the terminal. (Assuan: "OPTION 82 lc-messages LC_MESSAGES".) */ 83 char *lc_messages; 84 85 /* True if debug mode is requested. */ 86 int debug; 87 88 /* The number of seconds before giving up while waiting for user input. */ 89 int timeout; 90 91 /* True if caller should grab the keyboard. (Assuan: "OPTION grab" 92 or "OPTION no-grab".) */ 93 int grab; 94 /* The window ID of the parent window over which the pinentry window 95 should be displayed. (Assuan: "OPTION parent-wid WID".) */ 96 int parent_wid; 97 98 /* The name of an optional file which will be touched after a curses 99 entry has been displayed. (Assuan: "OPTION touch-file 100 FILENAME".) */ 101 char *touch_file; 102 103 /* The frontend should set this to -1 if the user canceled the 104 request, and to the length of the PIN stored in pin 105 otherwise. */ 106 int result; 107 108 /* The frontend should set this if the NOTOK button was pressed. */ 109 int canceled; 110 111 /* The frontend should set this to true if an error with the local 112 conversion occured. */ 113 int locale_err; 114 115 /* The frontend should set this to a gpg-error so that commands are 116 able to return specific error codes. This is an ugly hack due to 117 the fact that pinentry_cmd_handler_t returns the length of the 118 passphrase or a negative error code. */ 119 int specific_err; 120 121 /* The frontend should set this to true if the window close button 122 has been used. This flag is used in addition to a regular return 123 value. */ 124 int close_button; 125 126 /* The caller should set this to true if only one button is 127 required. This is useful for notification dialogs where only a 128 dismiss button is required. */ 129 int one_button; 130 131 /* If true a second prompt for the passphrase is shown and the user 132 is expected to enter the same passphrase again. Pinentry checks 133 that both match. (Assuan: "SETREPEAT".) */ 134 char *repeat_passphrase; 135 136 /* The string to show if a repeated passphrase does not match. 137 (Assuan: "SETREPEATERROR ERROR".) */ 138 char *repeat_error_string; 139 140 /* Set to true if the passphrase has been entered a second time and 141 matches the first passphrase. */ 142 int repeat_okay; 143 144 /* If this is not NULL, a passphrase quality indicator is shown. 145 There will also be an inquiry back to the caller to get an 146 indication of the quality for the passphrase entered so far. The 147 string is used as a label for the quality bar. (Assuan: 148 "SETQUALITYBAR LABEL".) */ 149 char *quality_bar; 150 151 /* The tooltip to be show for the qualitybar. Malloced or NULL. 152 (Assuan: "SETQUALITYBAR_TT TOOLTIP".) */ 153 char *quality_bar_tt; 154 155 /* For the curses pinentry, the color of error messages. */ 156 pinentry_color_t color_fg; 157 int color_fg_bright; 158 pinentry_color_t color_bg; 159 pinentry_color_t color_so; 160 int color_so_bright; 161 162 /* Malloced and i18ned default strings or NULL. These strings may 163 include an underscore character to indicate an accelerator key. 164 A double underscore represents a plain one. */ 165 /* (Assuan: "OPTION default-ok OK"). */ 166 char *default_ok; 167 /* (Assuan: "OPTION default-cancel CANCEL"). */ 168 char *default_cancel; 169 /* (Assuan: "OPTION default-prompt PROMPT"). */ 170 char *default_prompt; 171 /* (Assuan: "OPTION default-pwmngr 172 SAVE_PASSWORD_WITH_PASSWORD_MANAGER?"). */ 173 char *default_pwmngr; 174 175 /* Whether we are allowed to read the password from an external 176 cache. (Assuan: "OPTION allow-external-password-cache") */ 177 int allow_external_password_cache; 178 179 /* We only try the cache once. */ 180 int tried_password_cache; 181 182 /* A stable identifier for the key. (Assuan: "SETKEYINFO 183 KEYINFO".) */ 184 char *keyinfo; 185 186 /* Whether we may cache the password (according to the user). */ 187 int may_cache_password; 188 189 /* NOTE: If you add any additional fields to this structure, be sure 190 to update the initializer in pinentry/pinentry.c!!! */ 191 192 /* For the quality indicator we need to do an inquiry. Thus we need 193 to save the assuan ctx. */ 194 void *ctx_assuan; 195 196 }; 197 typedef struct pinentry *pinentry_t; 198 199 200 /* The pinentry command handler type processes the pinentry request 201 PIN. If PIN->pin is zero, request a confirmation, otherwise a PIN 202 entry. On confirmation, the function should return TRUE if 203 confirmed, and FALSE otherwise. On PIN entry, the function should 204 return -1 if an error occured or the user cancelled the operation 205 and 1 otherwise. */ 206 typedef int (*pinentry_cmd_handler_t) (pinentry_t pin); 207 208 /* Start the pinentry event loop. The program will start to process 209 Assuan commands until it is finished or an error occurs. If an 210 error occurs, -1 is returned and errno indicates the type of an 211 error. Otherwise, 0 is returned. */ 212 int pinentry_loop (void); 213 214 /* The same as above but allows to specify the i/o descriptors. 215 * infd and outfd will be duplicated in this function so the caller 216 * still has to close them if necessary. 217 */ 218 int pinentry_loop2 (int infd, int outfd); 219 220 221 /* Convert the UTF-8 encoded string TEXT to the encoding given in 222 LC_CTYPE. Return NULL on error. */ 223 char *pinentry_utf8_to_local (const char *lc_ctype, const char *text); 224 225 /* Convert TEXT which is encoded according to LC_CTYPE to UTF-8. With 226 SECURE set to true, use secure memory for the returned buffer. 227 Return NULL on error. */ 228 char *pinentry_local_to_utf8 (char *lc_ctype, char *text, int secure); 229 230 231 /* Run a quality inquiry for PASSPHRASE of LENGTH. */ 232 int pinentry_inq_quality (pinentry_t pin, 233 const char *passphrase, size_t length); 234 235 /* Try to make room for at least LEN bytes for the pin in the pinentry 236 PIN. Returns new buffer on success and 0 on failure. */ 237 char *pinentry_setbufferlen (pinentry_t pin, int len); 238 239 /* Use the buffer at BUFFER for PIN->PIN. BUFFER must be NULL or 240 allocated using secmem_alloc. LEN is the size of the buffer. If 241 it is unknown, but BUFFER is a NUL terminated string, you pass 0 to 242 just use strlen(buffer)+1. */ 243 void pinentry_setbuffer_use (pinentry_t pin, char *buffer, int len); 244 245 /* Initialize the secure memory subsystem, drop privileges and 246 return. Must be called early. */ 247 void pinentry_init (const char *pgmname); 248 249 /* Return true if either DISPLAY is set or ARGV contains the string 250 "--display". */ 251 int pinentry_have_display (int argc, char **argv); 252 253 /* Parse the command line options. May exit the program if only help 254 or version output is requested. */ 255 void pinentry_parse_opts (int argc, char *argv[]); 256 257 258 /* The caller must define this variable to process assuan commands. */ 259 extern pinentry_cmd_handler_t pinentry_cmd_handler; 260 261 262 263 264 265 #ifdef HAVE_W32_SYSTEM 266 /* Windows declares sleep as obsolete, but provides a definition for 267 _sleep but non for the still existing sleep. */ 268 #define sleep(a) _sleep ((a)) 269 #endif /*HAVE_W32_SYSTEM*/ 270 271 272 273 #if 0 274 { 275 #endif 276 #ifdef __cplusplus 277 } 278 #endif 279 280 #endif /* PINENTRY_H */