Get rid of getopt_long and improve --help output.
[pinentry.git] / pinentry / pinentry.h
1 /* pinentry.h - The interface for the PIN entry support library.
2    Copyright (C) 2002, 2003, 2010 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 #undef ENABLE_ENHANCED
31
32 typedef enum {
33   PINENTRY_COLOR_NONE, PINENTRY_COLOR_DEFAULT,
34   PINENTRY_COLOR_BLACK, PINENTRY_COLOR_RED,
35   PINENTRY_COLOR_GREEN, PINENTRY_COLOR_YELLOW,
36   PINENTRY_COLOR_BLUE, PINENTRY_COLOR_MAGENTA,
37   PINENTRY_COLOR_CYAN, PINENTRY_COLOR_WHITE
38 } pinentry_color_t;
39
40 struct pinentry
41 {
42   /* The window title, or NULL.  */
43   char *title;
44   /* The description to display, or NULL.  */
45   char *description;
46   /* The error message to display, or NULL.  */
47   char *error;
48   /* The prompt to display, or NULL.  */
49   char *prompt;
50   /* The OK button text to display, or NULL.  */
51   char *ok;
52   /* The Not-OK button text to display, or NULL.  */
53   char *notok;
54   /* The Cancel button text to display, or NULL.  */
55   char *cancel;
56   /* The buffer to store the secret into.  */
57   char *pin;
58   /* The length of the buffer.  */
59   int pin_len;
60
61   /* The name of the X display to use if X is available and supported.  */
62   char *display;
63   /* The name of the terminal node to open if X not available or supported.  */
64   char *ttyname;
65   /* The type of the terminal.  */
66   char *ttytype;
67   /* The LC_CTYPE value for the terminal.  */
68   char *lc_ctype;
69   /* The LC_MESSAGES value for the terminal.  */
70   char *lc_messages;
71
72   /* True if debug mode is requested.  */
73   int debug;
74
75   /* The number of seconds before giving up while waiting for user input. */
76   int timeout;
77
78 #ifdef ENABLE_ENHANCED
79   /* True if enhanced mode is requested.  */
80   int enhanced;
81 #endif
82
83   /* True if caller should grab the keyboard.  */
84   int grab;
85   /* The window ID of the parent window over which the pinentry window
86      should be displayed.  */
87   int parent_wid;
88
89   /* The name of an optional file which will be touched after a curses
90      entry has been displayed.  */
91   char *touch_file;
92
93   /* The user should set this to -1 if the user canceled the request,
94      and to the length of the PIN stored in pin otherwise.  */
95   int result;
96
97   /* The user should set this if the NOTOK button was pressed.  */
98   int canceled;
99
100   /* The user should set this to true if an error with the local
101      conversion occured. */
102   int locale_err;
103
104   /* The user should set this to true if the window close button has
105      been used.  This flag is used in addition to a regular return
106      value.  */
107   int close_button;
108
109   /* The caller should set this to true if only one button is
110      required.  This is useful for notification dialogs where only a
111      dismiss button is required. */
112   int one_button;
113
114   /* If true a second prompt for the passphrase is show and the user
115      is expected to enter the same passphrase again.  Pinentry checks
116      that both match.  */
117   char *repeat_passphrase;
118
119   /* The string to show if a repeated passphrase does not match.  */
120   char *repeat_error_string;
121
122   /* Set to true if the passphrase has been entered a second time and
123      matches the first passphrase.  */
124   int repeat_okay;
125
126   /* If this is not NULL, a passphrase quality indicator is shown.
127      There will also be an inquiry back to the caller to get an
128      indication of the quality for the passphrase entered so far.  The
129      string is used as a label for the quality bar.  */
130   char *quality_bar;
131
132   /* The tooltip to be show for the qualitybar.  Malloced or NULL.  */
133   char *quality_bar_tt;
134
135   /* For the curses pinentry, the color of error messages.  */
136   pinentry_color_t color_fg;
137   int color_fg_bright;
138   pinentry_color_t color_bg;
139   pinentry_color_t color_so;
140   int color_so_bright;
141
142   /* Malloced and i18ned default strings or NULL.  These strings may
143      include an underscore character to indicate an accelerator key.
144      A double underscore represents a plain one.  */
145   char *default_ok;
146   char *default_cancel;
147   char *default_prompt;
148
149   /* For the quality indicator we need to do an inquiry.  Thus we need
150      to save the assuan ctx.  */
151   void *ctx_assuan;
152
153 };
154 typedef struct pinentry *pinentry_t;
155
156 \f
157 /* The pinentry command handler type processes the pinentry request
158    PIN.  If PIN->pin is zero, request a confirmation, otherwise a PIN
159    entry.  On confirmation, the function should return TRUE if
160    confirmed, and FALSE otherwise.  On PIN entry, the function should
161    return -1 if cancelled and the length of the secret otherwise.  */
162 typedef int (*pinentry_cmd_handler_t) (pinentry_t pin);
163
164 /* Start the pinentry event loop.  The program will start to process
165    Assuan commands until it is finished or an error occurs.  If an
166    error occurs, -1 is returned and errno indicates the type of an
167    error.  Otherwise, 0 is returned.  */
168 int pinentry_loop (void);
169
170 /* The same as above but allows to specify the i/o descriptors. */
171 int pinentry_loop2 (int infd, int outfd);
172
173
174 /* Convert the UTF-8 encoded string TEXT to the encoding given in
175    LC_CTYPE.  Return NULL on error. */
176 char *pinentry_utf8_to_local (const char *lc_ctype, const char *text);
177
178 /* Convert TEXT which is encoded according to LC_CTYPE to UTF-8.  With
179    SECURE set to true, use secure memory for the returned buffer.
180    Return NULL on error. */
181 char *pinentry_local_to_utf8 (char *lc_ctype, char *text, int secure);
182
183
184 /* Run a quality inquiry for PASSPHRASE of LENGTH. */
185 int pinentry_inq_quality (pinentry_t pin,
186                           const char *passphrase, size_t length);
187
188 /* Try to make room for at least LEN bytes for the pin in the pinentry
189    PIN.  Returns new buffer on success and 0 on failure.  */
190 char *pinentry_setbufferlen (pinentry_t pin, int len);
191
192 /* Initialize the secure memory subsystem, drop privileges and
193    return.  Must be called early.  */
194 void pinentry_init (const char *pgmname);
195
196 /* Return true if either DISPLAY is set or ARGV contains the string
197    "--display". */
198 int pinentry_have_display (int argc, char **argv);
199
200 /* Parse the command line options.  May exit the program if only help
201    or version output is requested.  */
202 void pinentry_parse_opts (int argc, char *argv[]);
203
204 \f
205 /* The caller must define this variable to process assuan commands.  */
206 extern pinentry_cmd_handler_t pinentry_cmd_handler;
207
208
209
210
211 \f
212 #ifdef HAVE_W32_SYSTEM
213 /* Windows declares sleep as obsolete, but provides a definition for
214    _sleep but non for the still existing sleep.  */
215 #define sleep(a) _sleep ((a))
216 #endif /*HAVE_W32_SYSTEM*/
217
218
219
220 #if 0
221 {
222 #endif
223 #ifdef __cplusplus
224 }
225 #endif
226
227 #endif  /* PINENTRY_H */