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