d17e790445d4fb7dac8a06e92827482a32331183
[pinentry.git] / pinentry / pinentry.h
1 /* pinentry.h - The interface for the PIN entry support library.
2    Copyright (C) 2002, 2003 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, write to the Free Software
18    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
19    02111-1307, USA  */
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.  */
42   char *title;
43   /* The description to display, or NULL.  */
44   char *description;
45   /* The error message to display, or NULL.  */
46   char *error;
47   /* The prompt to display, or NULL.  */
48   char *prompt;
49   /* The OK button text to display, or NULL.  */
50   char *ok;
51   /* The Cancel button text to display, or NULL.  */
52   char *cancel;
53   /* The buffer to store the secret into.  */
54   char *pin;
55   /* The length of the buffer.  */
56   int pin_len;
57
58   /* The name of the X display to use if X is available and supported.  */
59   char *display;
60   /* The name of the terminal node to open if X not available or supported.  */
61   char *ttyname;
62   /* The type of the terminal.  */
63   char *ttytype;
64   /* The LC_CTYPE value for the terminal.  */
65   char *lc_ctype;
66   /* The LC_MESSAGES value for the terminal.  */
67   char *lc_messages;
68
69   /* True if debug mode is requested.  */
70   int debug;
71   /* True if enhanced mode is requested.  */
72   int enhanced;
73   /* True if caller should grab the keyboard.  */
74   int grab;
75   /* The window ID of the parent window over which the pinentry window
76      should be displayed.  */
77   int parent_wid;
78
79   /* The name of an optional file which will be touched after a curses
80      entry has been displayed.  */
81   char *touch_file;
82
83   /* The user should set this to -1 if the user canceled the request,
84      and to the length of the PIN stored in pin otherwise.  */
85   int result;
86
87   /* The user should set this to true if an error with the local
88      conversion occured. */
89   int locale_err;
90
91   /* The caller should set this to true if only one button is
92      required.  This is useful for notification dialogs where only a
93      dismiss button is required. */
94   int one_button;
95
96   /* If this is not NULL, a passphrase quality indicator is shown.
97      There will also be an inquiry back to the caller to get an
98      indication of the quality for the passphrase entered so far.  The
99      string is used as a labe for the auality bar.  */
100   char *quality_bar;
101
102   /* The tooltip to be show for the qualitybar.  Malloced or NULL.  */
103   char *quality_bar_tt;
104
105   /* For the curses pinentry, the color of error messages.  */
106   pinentry_color_t color_fg;
107   int color_fg_bright;
108   pinentry_color_t color_bg;
109   pinentry_color_t color_so;
110   int color_so_bright;
111
112   /* Fo the quality indicator we need to do an inquiry.  Thus we need
113      to save the assuan ctx.  */
114   void *ctx_assuan;
115 };
116 typedef struct pinentry *pinentry_t;
117
118 \f
119 /* The pinentry command handler type processes the pinentry request
120    PIN.  If PIN->pin is zero, request a confirmation, otherwise a PIN
121    entry.  On confirmation, the function should return TRUE if
122    confirmed, and FALSE otherwise.  On PIN entry, the function should
123    return -1 if cancelled and the length of the secret otherwise.  */
124 typedef int (*pinentry_cmd_handler_t) (pinentry_t pin);
125
126 /* Start the pinentry event loop.  The program will start to process
127    Assuan commands until it is finished or an error occurs.  If an
128    error occurs, -1 is returned and errno indicates the type of an
129    error.  Otherwise, 0 is returned.  */
130 int pinentry_loop (void);
131
132
133 /* Convert the UTF-8 encoded string TEXT to the encoding given in
134    LC_CTYPE.  Return NULL on error. */
135 char *pinentry_utf8_to_local (char *lc_ctype, char *text);
136
137 /* Convert TEXT which is encoded according to LC_CTYPE to UTF-8.  With
138    SECURE set to true, use secure memory for the returned buffer.
139    Return NULL on error. */
140 char *pinentry_local_to_utf8 (char *lc_ctype, char *text, int secure);
141
142
143 /* Run a quality inquiry for PASSPHRASE of LENGTH. */
144 int pinentry_inq_quality (pinentry_t pin, 
145                           const char *passphrase, size_t length);
146
147 /* Try to make room for at least LEN bytes for the pin in the pinentry
148    PIN.  Returns new buffer on success and 0 on failure.  */
149 char *pinentry_setbufferlen (pinentry_t pin, int len);
150
151 /* Initialize the secure memory subsystem, drop privileges and
152    return.  Must be called early.  */
153 void pinentry_init (const char *pgmname);
154
155 /* Return true if either DISPLAY is set or ARGV contains the string
156    "--display". */
157 int pinentry_have_display (int argc, char **argv);
158
159 /* Parse the command line options.  Returns 1 if user should print
160    version and exit.  Can exit the program if only help output is
161    requested.  */
162 int pinentry_parse_opts (int argc, char *argv[]);
163
164 \f
165 /* The caller must define this variable to process assuan commands.  */
166 extern pinentry_cmd_handler_t pinentry_cmd_handler;
167
168
169
170
171 \f
172 #ifdef HAVE_W32_SYSTEM
173 /* Windows declares sleep as obsolete, but provides a definition for
174    _sleep but non for the still existing sleep.  */
175 #define sleep(a) _sleep ((a))
176 #endif /*HAVE_W32_SYSTEM*/
177
178
179
180 #if 0 
181 {
182 #endif
183 #ifdef __cplusplus
184 }
185 #endif
186
187 #endif  /* PINENTRY_H */