Send "OPTION PINENTRY=N" when PWMD_OPTION_PINENTRY changes to enable
[libpwmd.git] / libpwmd.h
blob73e1c4f9bbfa7c1590bc8b6a7211c440960825f7
1 /* vim:tw=78:ts=8:sw=4:set ft=c: */
2 /*
3 Copyright (C) 2006-2007 Ben Kibbey <bjk@luxsci.net>
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation; either version 2 of the License, or
8 (at your option) any later version.
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with this program; if not, write to the Free Software
17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 #ifndef LIBPWMD_H
20 #define LIBPWMD_H
22 #define LIBPWMD_VERSION 0x500
24 #include <assuan.h>
25 #include <gpg-error.h>
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
32 * A handle is a pointer to a pwm_t that is returned with pwmd_connect().
34 struct pwm_s;
35 typedef struct pwm_s pwm_t;
38 * Used with pwmd_open_nb() and pwmd_save_nb(). Both are non-blocking
39 * functions for pin retrieval with pinentry. The pwmd_open_nb_finalize() and
40 * pwmd_save_nb_finalize() functions use this type after a successful read()
41 * from the returned file descriptor of those functions.
43 * Although version 1.4 and later of pwmd has it's own support for pinentry,
44 * commands that uses pinentry will block and as a result block the client. So
45 * these non-blocking functions may be used to retrieve the key before sending
46 * the command that requires a key.
48 typedef struct {
49 char filename[FILENAME_MAX];
50 int fd; /* Closed after the finalize function. */
51 gpg_error_t error; /* Returned from the NB function. */
52 } pwmd_nb_status_t;
55 * A custom callback password retrieval function which is set with
56 * pwmd_setopt().
58 typedef char *(*pwmd_password_fn)(pwm_t *pwm, void *data);
61 * A callback to be set with pwmd_setopt() that processes Assuan protocol
62 * status messages. The 'line' is the status message which is prefixed with
63 * the keyword.
65 typedef int (*pwmd_status_fn)(void *data, const char *line);
68 * A callback function that is passed to pwmd_inquire(). 'data' is the user
69 * data that was passed to pwmd_inquire(). 'keyword' is the same as the 'cmd'
70 * argument to pwmd_inquire().
72 * 'rc' is the return code from assuan_send_data() and is initially 0 on the
73 * first call to the set callback. This gives the client a chance to cleanup
74 * if assuan_send_data() fails for some reason and should probably return the
75 * same error code, if set, after doing so.
77 * 'result' should be set to the data to be sent which is of 'len' bytes. The
78 * data is not modified.
80 * The function should return GPG_ERR_EOF when no more data needs to be sent,
81 * 0 if there is more data pending or an error code which will terminate the
82 * INQUIRE.
84 typedef gpg_error_t (*pwmd_inquire_fn)(void *data, const char *keyword,
85 gpg_error_t rc, char **result, size_t *len);
87 typedef enum {
89 * PWMD_OPTION_PASSWORD_FUNC
91 * Function to retrieve a password. This function should return an
92 * string which is the password or NULL on error.
94 PWMD_OPTION_PASSWORD_FUNC,
97 * PWMD_OPTION_PASSWORD_DATA
99 * Data passed to the password function.
101 PWMD_OPTION_PASSWORD_DATA,
104 * PWMD_OPTION_PINENTRY
106 * The following argument should be of type int and set to 1 to enable the
107 * use of pinentry(1) to retrieve passwords. Setting to 0 will disable
108 * using pinentry and the password must be set with PWMD_OPTION_PASSWORD
109 * or gotten from PWMD_OPTION_PASSWORD_FUNC. The pwmd command "OPTION
110 * PINENTRY=0" is sent when this option is set (1) to prevent pinentry
111 * from being called on the pwmd server and enabled when unset.
113 PWMD_OPTION_PINENTRY,
116 * PWMD_OPTION_PINENTRY_TRIES
118 * The number of password tries before giving up. If the pinentry "Cancel"
119 * button is selected, pinentry will abort. Must be > 0. The default is 3.
121 PWMD_OPTION_PINENTRY_TRIES,
124 * PWMD_OPTION_PINENTRY_PATH
126 * The full pathname to the pinentry program. If not specified,
127 * /usr/bin/pinentry will be used.
129 PWMD_OPTION_PINENTRY_PATH,
132 * PWMD_OPTION_PINENTRY_TTY
134 * pinentry --ttyname.
136 PWMD_OPTION_PINENTRY_TTY,
139 * PWMD_OPTION_PINENTRY_DISPLAY
141 * pinentry --display
143 PWMD_OPTION_PINENTRY_DISPLAY,
146 * PWMD_OPTION_PINENTRY_TERM
148 * pinentry --ttytype
150 PWMD_OPTION_PINENTRY_TERM,
153 * PWMD_OPTION_PASSWORD
155 * The following argument should be of type char* which specifies the
156 * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
157 * PWMD_OPTION_PINENTRY is 0. The password will be kept in memory until
158 * pwmd_close() is called so setting this option isn't needed each time
159 * pwmd_open() or pwmd_save() is called regardless of pwmd cache settings.
161 PWMD_OPTION_PASSWORD,
164 * PWMD_OPTION_PINENTRY_TITLE
165 * PWMD_OPTION_PINENTRY_PROMPT
166 * PWMD_OPTION_PINENTRY_DESC
168 * The following argument is of type char* which specifies either the
169 * title, prompt or description in the pinentry program when
170 * PWMD_OPTION_PINENTRY is set. Note that any CR, LF or % must be percent
171 * escape (the hexidecimal value of the character).
173 PWMD_OPTION_PINENTRY_TITLE,
174 PWMD_OPTION_PINENTRY_PROMPT,
175 PWMD_OPTION_PINENTRY_DESC,
178 * PWMD_OPTION_STATUS_FUNC
180 * A function to be called when a status line is sent from pwmd. This
181 * function should return 0 on success or a gpg-error error code. This
182 * function won't be used when getting a password with pinentry.
184 PWMD_OPTION_STATUS_FUNC,
187 * PWMD_OPTION_STATUS_DATA
189 * Data passed to the status function.
191 PWMD_OPTION_STATUS_DATA,
192 } pwmd_option_t;
195 * Initialize the library. This sets up various things and must be called
196 * before the other functions.
198 gpg_error_t pwmd_init(void);
201 * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
202 * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
203 * with the other functions or NULL if there was an error in which case
204 * 'error' is set to an error code which may be described by pwmd_strerror().
206 pwm_t *pwmd_connect(const char *socket_path, gpg_error_t *error) __attribute__ ((warn_unused_result));
209 * Sets a libpwmd option 'opt'. The next argument should be of the data type
210 * required for the option. Returns 0 on success or an error code.
212 gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...) __attribute__ ((warn_unused_result));
215 * Opens a file 'filename' (the OPEN command). The filename is not a full path
216 * but only filename which is looked for in the pwmd configured data
217 * directory. How the password is gotten depends on options set with
218 * pwmd_setopt() and whether the file is cached on the server. Returns 0 on
219 * success or an error code.
221 gpg_error_t pwmd_open(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result));
224 * This is like pwmd_open() but won't block the process when pinentry is used
225 * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
226 * on the server or if the file doesn't exist on the file system (a new file).
227 * Otherwise it returns a file descriptor that select() can use. When ready
228 * for a read, read() should read a pwmd_nb_status_t. If there is a system
229 * error (pipe() or fork()), then -1 is returned and 'error' is set to an
230 * error code that pwmd_strerror() can describe. See pwmd_open_nb_finalize().
232 * The 'timeout' parameter specifies the number of seconds until the pinentry
233 * terminates. Setting to 0 (the default) will disable timeouts. Note that the
234 * child process will reset the SIGALRM handler (if any) to it's own handler
235 * and that the actual OPEN command isn't calculated as part of the elapsed
236 * time.
238 * Be sure to set PWMD_OPTION_PINENTRY.
240 int pwmd_open_nb(pwm_t *pwm, gpg_error_t *error, const char *filename, int timeout) __attribute__ ((warn_unused_result));
243 * When a file descriptor has been returned from pwmd_open_nb() and after a
244 * successful read(), you should call pwmd_open_nb_finalize() to update the
245 * 'pwm' handle. If there was a pinentry or protocol error
246 * pwmd_open_nb_finalize() will return an error code or 0 on success. Note
247 * that pwmd_open_nb_finalize() will close the file descriptor returned from
248 * pwmd_open_nb().
250 gpg_error_t pwmd_open_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
253 * Sends the SAVE command to the associated handle 'pwm'. If a password is
254 * required, how it is gotten depends on options set with pwmd_setopt().
255 * Returns 0 on success or an error code.
257 gpg_error_t pwmd_save(pwm_t *pwm) __attribute__ ((warn_unused_result));
260 * This is like pwmd_save() but won't block the process when pinentry is used
261 * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
262 * on the server or if the file doesn't exist on the file system (a new file).
263 * Otherwise it returns a file descriptor that select() can use. When ready
264 * for a read, read() should read a pwmd_nb_status_t. If there is a system
265 * error (pipe() or fork()), then -1 is returned and 'error' is set to an
266 * error code that pwmd_strerror() can describe. See pwmd_save_nb_finalize().
268 * Note that there is no timeout setting. If a password is required, pinentry
269 * won't timeout.
271 * Be sure to set PWMD_OPTION_PINENTRY.
273 int pwmd_save_nb(pwm_t *pwm, gpg_error_t *error) __attribute__ ((warn_unused_result));
276 * When a file descriptor has been returned from pwmd_save_nb() and after a
277 * successful read(), you should call pwmd_save_nb_finalize() to update the
278 * 'pwm' handle. If there was a pinentry or protocol error
279 * pwmd_save_nb_finalize() will return an error code or 0 on success. Note
280 * that pwmd_save_nb_finalize() will close the file descriptor returned from
281 * pwmd_save_nb().
283 gpg_error_t pwmd_save_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result));
286 * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
287 * timeout the associated pinentry process, then call this function after your
288 * timer has expired. Returns 0 on success or an error code.
290 gpg_error_t pwmd_terminate_pinentry(pwm_t *pwm) __attribute__ ((warn_unused_result));
293 * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
294 * command fails an error code is returned which may be described by passing
295 * the error to pwmd_strerror(). If successful the function returns 0 and the
296 * 'result' is the character data of the command or NULL if there was none.
298 * For commands which use an INQUIRE (i.e., STORE), use pwmd_inquire() and not
299 * pwmd_command().
301 * A note about the BYE command: Client's should not send this command
302 * directly with pwmd_command(). They should use pwmd_close() instead because
303 * libassuan will close the file descriptors with the associated context. This
304 * is fine except when pwmd_close() is called. pwmd_close() calls
305 * assuan_disconnect() which then sends the BYE command to the closed file
306 * descriptor resulting in a segfault.
308 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) __attribute__ ((warn_unused_result));
311 * Commands which use an INQUIRE to send data (i.e., STORE) should use this
312 * function and not pwmd_command(). 'cmd' is the command to send and is also
313 * the 'keyword' argument to the callback function 'func'. 'data' is user data
314 * passed to the callback function. Returnes 0 on success or and error code
315 * which may have been returned from the callback function.
317 gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_fn func,
318 void *data) __attribute__ ((warn_unused_result));
321 * Free the memory used by the result of pwmd_command() if any. It is
322 * important to use this function because libpwmd keeps track of all memory
323 * de/allocations.
325 void pwmd_free_result(void *);
328 * Closes the connection to the socket and frees the resources of the handle.
329 * Returns no value.
331 void pwmd_close(pwm_t *pwm);
334 * Protocol error codes.
336 #define EPWMD_BADKEY GPG_ERR_INV_PASSPHRASE
337 #define EPWMD_COMMAND_SYNTAX GPG_ERR_SYNTAX
338 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_NOT_FOUND
339 #define EPWMD_ACCOUNT_EXISTS GPG_ERR_AMBIGUOUS_NAME
340 #define EPWMD_CACHE_NOT_FOUND GPG_ERR_NOT_FOUND
341 #define EPWMD_ATTR_SYNTAX GPG_ERR_SYNTAX
342 #define EPWMD_ATTR_NOT_FOUND GPG_ERR_NOT_FOUND
343 #define EPWMD_INVALID_FILENAME GPG_ERR_INV_NAME
344 #define EPWMD_EMPTY_ELEMENT GPG_ERR_NO_VALUE
345 #define EPWMD_INVALID_ELEMENT GPG_ERR_INV_VALUE
346 #define EPWMD_ERROR GPG_ERR_USER_1
347 #define EPWMD_MAX_SLOTS GPG_ERR_USER_2
348 #define EPWMD_LOOP GPG_ERR_USER_3
349 #define EPWMD_NO_FILE GPG_ERR_USER_4
350 #define EPWMD_LIBXML_ERROR GPG_ERR_USER_5
351 #define EPWMD_FILE_MODIFIED GPG_ERR_USER_6
352 #define EPWMD_MAX GPG_ERR_USER_7
355 * Return a string describing a pwmd protocol error code.
357 const char *pwmd_strerror(gpg_error_t error);
359 #ifdef __cplusplus
361 #endif
363 #endif