1 /* vim:tw=78:ts=8:sw=4:set ft=c: */
3 Copyright (C) 2006-2008 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 02110-1301 USA
22 #define LIBPWMD_VERSION 0x506
24 #include <gpg-error.h>
31 * A handle is a pointer to a pwm_t that is returned with pwmd_connect().
34 typedef struct pwm_s pwm_t
;
37 * Used with pwmd_open_nb() and pwmd_save_nb(). Both are non-blocking
38 * functions for pin retrieval with pinentry. The pwmd_open_nb_finalize() and
39 * pwmd_save_nb_finalize() functions use this type after a successful read()
40 * from the returned file descriptor of those functions.
42 * Although version 1.4 and later of pwmd has it's own support for pinentry,
43 * commands that uses pinentry will block and as a result block the client. So
44 * these non-blocking functions may be used to retrieve the key before sending
45 * the command that requires a key.
47 * Update: Use pwmd_open_async() and pwmd_save_async() instead. pwmd_open_nb()
48 * and pwmd_save_nb() and the associated finalization functions will be
49 * removed in a later version.
52 char filename
[FILENAME_MAX
];
53 int fd
; /* Closed after the finalize function. */
54 gpg_error_t error
; /* Returned from the NB function. */
58 * For use with pwmd_process(). pwmd_open_async() and pwmd_save_async() use
68 * A custom callback password retrieval function which is set with
69 * pwmd_setopt(). This has priority over other retrieval methods if set.
71 typedef char *(*pwmd_password_fn
)(pwm_t
*pwm
, void *data
);
74 * A callback to be set with pwmd_setopt() that processes Assuan protocol
75 * status messages. The 'line' is the status message which is prefixed with
78 typedef int (*pwmd_status_fn
)(void *data
, const char *line
);
81 * A callback function that is passed to pwmd_inquire(). 'data' is the user
82 * data that was passed to pwmd_inquire(). 'keyword' is the same as the 'cmd'
83 * argument to pwmd_inquire().
85 * 'rc' is the return code from assuan_send_data() and is initially 0 on the
86 * first call to the set callback. This gives the client a chance to cleanup
87 * if assuan_send_data() fails for some reason and should probably return the
88 * same error code, if set, after doing so.
90 * 'result' should be set to the data to be sent which is of 'len' bytes. The
91 * data is not modified.
93 * The function should return GPG_ERR_EOF when no more data needs to be sent
94 * or to finish sending the set 'result' and end the INQUIRE, 0 if there is
95 * more data pending or an error code which will terminate the INQUIRE.
97 typedef gpg_error_t (*pwmd_inquire_fn
)(void *data
, const char *keyword
,
98 gpg_error_t rc
, char **result
, size_t *len
);
101 * Library options which are set with pwmd_setopt().
105 * PWMD_OPTION_PASSWORD_FUNC
107 * Function to retrieve a password. This function should return an
108 * string which is the password or NULL on error.
110 PWMD_OPTION_PASSWORD_FUNC
,
113 * PWMD_OPTION_PASSWORD_DATA
115 * Data passed to the password function.
117 PWMD_OPTION_PASSWORD_DATA
,
120 * PWMD_OPTION_PINENTRY
122 * The following argument should be of type int and set to 1 to enable the
123 * use of pinentry(1) to retrieve passwords. Setting to 0 will disable
124 * using pinentry and the password must be set with PWMD_OPTION_PASSWORD
125 * or gotten from PWMD_OPTION_PASSWORD_FUNC. The pwmd command "OPTION
126 * PINENTRY=0" is sent when this option is set (1) to prevent pinentry
127 * from being called on the pwmd server and enabled when unset.
129 PWMD_OPTION_PINENTRY
,
132 * PWMD_OPTION_PINENTRY_TRIES
134 * The number of password tries before giving up. If the pinentry "Cancel"
135 * button is selected, pinentry will abort. Must be > 0. The default is 3.
137 PWMD_OPTION_PINENTRY_TRIES
,
140 * PWMD_OPTION_PINENTRY_PATH
142 * The full pathname to the pinentry program. If not specified,
143 * /usr/bin/pinentry will be used.
145 PWMD_OPTION_PINENTRY_PATH
,
148 * PWMD_OPTION_PINENTRY_TTY
150 * pinentry --ttyname.
152 PWMD_OPTION_PINENTRY_TTY
,
155 * PWMD_OPTION_PINENTRY_DISPLAY
159 PWMD_OPTION_PINENTRY_DISPLAY
,
162 * PWMD_OPTION_PINENTRY_TERM
166 PWMD_OPTION_PINENTRY_TERM
,
169 * PWMD_OPTION_PASSWORD
171 * The following argument should be of type char* which specifies the
172 * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
173 * PWMD_OPTION_PINENTRY is 0. The password will be kept in memory until
174 * pwmd_close() is called so setting this option isn't needed each time
175 * pwmd_open() or pwmd_save() is called regardless of pwmd cache settings.
177 PWMD_OPTION_PASSWORD
,
180 * PWMD_OPTION_PINENTRY_TITLE
181 * PWMD_OPTION_PINENTRY_PROMPT
182 * PWMD_OPTION_PINENTRY_DESC
184 * The following argument is of type char* which specifies either the
185 * title, prompt or description in the pinentry program when
186 * PWMD_OPTION_PINENTRY is set. Note that any CR, LF or % must be percent
187 * escape (the hexidecimal value of the character).
189 PWMD_OPTION_PINENTRY_TITLE
,
190 PWMD_OPTION_PINENTRY_PROMPT
,
191 PWMD_OPTION_PINENTRY_DESC
,
194 * PWMD_OPTION_STATUS_FUNC
196 * A function to be called when a status line is sent from pwmd. This
197 * function should return 0 on success or a gpg-error error code. This
198 * function won't be used when getting a password with pinentry.
200 PWMD_OPTION_STATUS_FUNC
,
203 * PWMD_OPTION_STATUS_DATA
205 * Data passed to the status function.
207 PWMD_OPTION_STATUS_DATA
,
211 * Initialize the library. This sets up various things and must be called
212 * before the other functions.
214 gpg_error_t
pwmd_init(void);
217 * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
218 * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
219 * with the other functions or NULL if there was an error in which case
220 * 'error' is set to an error code which may be described by pwmd_strerror().
222 pwm_t
*pwmd_connect(const char *socket_path
, gpg_error_t
*error
) __attribute__ ((warn_unused_result
));
225 * Sets 'ctx' to the assuan context associated with the handle 'pwm' and 'fd'
226 * to the socket file descriptor. Returns 0 on success or an error code.
228 struct assuan_context_s
;
229 typedef struct assuan_context_s
*assuan_context_t
;
230 gpg_error_t
pwmd_assuan_ctx(pwm_t
*pwm
, assuan_context_t
*ctx
, int *fd
) __attribute__ ((warn_unused_result
));
233 * A wrapper around assuan_pending_line() and assuan_read_line(). Returns 0 if
234 * there was a pending line and sets 'line' to the content and 'len' to the
235 * length. Returns GPG_ERR_NO_DATA if there was no pending line or any error
236 * from assuan_read_line().
238 gpg_error_t
pwmd_pending_line(pwm_t
*pwm
, char **line
, size_t *len
) __attribute__ ((warn_unused_result
));
241 * Sets a libpwmd option 'opt'. The next argument should be of the data type
242 * required for the option. Returns 0 on success or an error code.
244 gpg_error_t
pwmd_setopt(pwm_t
*pwm
, pwmd_option_t opt
, ...) __attribute__ ((warn_unused_result
));
247 * Opens a file 'filename' (the OPEN command). The filename is not a full path
248 * but only filename which is looked for in the pwmd configured data
249 * directory. How the password is gotten depends on options set with
250 * pwmd_setopt() and whether the file is cached on the server. Returns 0 on
251 * success or an error code.
253 gpg_error_t
pwmd_open(pwm_t
*pwm
, const char *filename
) __attribute__ ((warn_unused_result
));
256 * This is like pwmd_open() but won't block the process when pinentry is used
257 * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
258 * on the server or if the file doesn't exist on the file system (a new file).
259 * Otherwise it returns a file descriptor that select() can use. When ready
260 * for a read, read() should read a pwmd_nb_status_t. If there is a system
261 * error (pipe() or fork()), then -1 is returned and 'error' is set to an
262 * error code that pwmd_strerror() can describe. See pwmd_open_nb_finalize().
264 * The 'timeout' parameter specifies the number of seconds until the pinentry
265 * terminates. Setting to 0 (the default) will disable timeouts. Note that the
266 * child process will reset the SIGALRM handler (if any) to it's own handler
267 * and that the actual OPEN command isn't calculated as part of the elapsed
270 * Be sure to set PWMD_OPTION_PINENTRY.
272 int pwmd_open_nb(pwm_t
*pwm
, gpg_error_t
*error
, const char *filename
,
273 int timeout
) __attribute__ ((warn_unused_result
,deprecated
));
276 * When a file descriptor has been returned from pwmd_open_nb() and after a
277 * successful read(), you should call pwmd_open_nb_finalize() to update the
278 * 'pwm' handle. If there was a pinentry or protocol error
279 * pwmd_open_nb_finalize() will return an error code or 0 on success. Note
280 * that pwmd_open_nb_finalize() will close the file descriptor returned from
283 gpg_error_t
pwmd_open_nb_finalize(pwm_t
*pwm
, pwmd_nb_status_t
*status
) __attribute__ ((warn_unused_result
,deprecated
));
286 * This is the preferred way to do a non-blocking open. The difference from
287 * pwmd_open_nb() is that libpwmd wont fork() to get the pin. Instead, it will
288 * let pwmd use it's pinentry retrieval method. When successful this function
289 * returns 0 and pwmd_process() should be called until the command completes.
291 gpg_error_t
pwmd_open_async(pwm_t
*pwm
, const char *filename
) __attribute__ ((warn_unused_result
));
295 * After pwmd_open_async() or pwmd_save_async() returns 0, this function
296 * should be called until ASYNC_DONE is returned. It will return ASYNC_PROCESS
297 * when the command is still running. After ASYNC_DONE is returned, any error
298 * that may have occurred is stored in 'rc'. If an error occurred or not,
299 * pwmd_finalize() must be called to reset a control variable so the next
300 * async command may be performed.
302 pwmd_async_t
pwmd_process(pwm_t
*pwm
, gpg_error_t
*rc
) __attribute__ ((warn_unused_result
));
306 * Resets the control variable for the associated handle. Call this function
307 * after ASYNC_DONE is returned from pwmd_process().
309 gpg_error_t
pwmd_finalize(pwm_t
*pwm
) __attribute__ ((warn_unused_result
));
313 * Sends the SAVE command to the associated handle 'pwm'. If a password is
314 * required, how it is gotten depends on options set with pwmd_setopt().
315 * Returns 0 on success or an error code.
317 gpg_error_t
pwmd_save(pwm_t
*pwm
) __attribute__ ((warn_unused_result
));
320 * This is like pwmd_save() but won't block the process when pinentry is used
321 * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
322 * on the server or if the file doesn't exist on the file system (a new file).
323 * Otherwise it returns a file descriptor that select() can use. When ready
324 * for a read, read() should read a pwmd_nb_status_t. If there is a system
325 * error (pipe() or fork()), then -1 is returned and 'error' is set to an
326 * error code that pwmd_strerror() can describe. See pwmd_save_nb_finalize().
328 * Note that there is no timeout setting. If a password is required, pinentry
331 * Be sure to set PWMD_OPTION_PINENTRY.
333 int pwmd_save_nb(pwm_t
*pwm
, gpg_error_t
*error
) __attribute__ ((warn_unused_result
,deprecated
));
336 * When a file descriptor has been returned from pwmd_save_nb() and after a
337 * successful read(), you should call pwmd_save_nb_finalize() to update the
338 * 'pwm' handle. If there was a pinentry or protocol error
339 * pwmd_save_nb_finalize() will return an error code or 0 on success. Note
340 * that pwmd_save_nb_finalize() will close the file descriptor returned from
343 gpg_error_t
pwmd_save_nb_finalize(pwm_t
*pwm
, pwmd_nb_status_t
*status
) __attribute__ ((warn_unused_result
,deprecated
));
346 * Like pwmd_save_nb() but uses pwmd to launch pinentry rather than having
347 * libpwmd fork(). This function returns 0 on success and pwmd_process()
348 * should be called until the command completes.
350 gpg_error_t
pwmd_save_async(pwm_t
*pwm
) __attribute__ ((warn_unused_result
));
354 * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
355 * timeout the associated pinentry process, then call this function after your
356 * timer has expired. Returns 0 on success or an error code.
358 gpg_error_t
pwmd_terminate_pinentry(pwm_t
*pwm
) __attribute__ ((warn_unused_result
));
361 * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
362 * command fails an error code is returned which may be described by passing
363 * the error to pwmd_strerror(). If successful the function returns 0 and the
364 * 'result' is the character data of the command or NULL if there was none.
366 * For commands which use an INQUIRE (i.e., STORE), use pwmd_inquire() and not
369 * A note about the BYE command: Client's should not send this command
370 * directly with pwmd_command(). They should use pwmd_close() instead because
371 * libassuan will close the file descriptors with the associated context.
373 gpg_error_t
pwmd_command(pwm_t
*pwm
, char **result
, const char *cmd
, ...) __attribute__ ((warn_unused_result
));
376 * Commands which use an INQUIRE to send data (i.e., STORE) should use this
377 * function and not pwmd_command(). 'cmd' is the command to send and is also
378 * the 'keyword' argument passed to the callback function 'func'. 'data' is
379 * user data passed to the callback function. Returnes 0 on success or an
380 * error code which may have been returned from the callback function.
382 gpg_error_t
pwmd_inquire(pwm_t
*pwm
, const char *cmd
, pwmd_inquire_fn func
,
383 void *data
) __attribute__ ((warn_unused_result
));
386 * Free the memory used by the result of pwmd_command() if any. It is
387 * important to use this function because libpwmd keeps track of all memory
390 void pwmd_free_result(void *);
393 * Closes the connection to the socket and frees the resources of the handle.
396 void pwmd_close(pwm_t
*pwm
);
399 * Protocol error codes.
401 #define EPWMD_BADKEY GPG_ERR_INV_PASSPHRASE
402 #define EPWMD_COMMAND_SYNTAX GPG_ERR_SYNTAX
403 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_ELEMENT_NOT_FOUND
404 #define EPWMD_ACCOUNT_EXISTS GPG_ERR_AMBIGUOUS_NAME
405 #define EPWMD_CACHE_NOT_FOUND GPG_ERR_NOT_FOUND
406 #define EPWMD_ATTR_SYNTAX GPG_ERR_SYNTAX
407 #define EPWMD_ATTR_NOT_FOUND GPG_ERR_NOT_FOUND
408 #define EPWMD_INVALID_FILENAME GPG_ERR_INV_VALUE
409 #define EPWMD_EMPTY_ELEMENT GPG_ERR_NO_VALUE
410 #define EPWMD_INVALID_ELEMENT GPG_ERR_INV_VALUE
411 #define EPWMD_ERROR GPG_ERR_USER_1
412 #define EPWMD_MAX_SLOTS GPG_ERR_USER_2
413 #define EPWMD_LOOP GPG_ERR_USER_3
414 #define EPWMD_NO_FILE GPG_ERR_USER_4
415 #define EPWMD_LIBXML_ERROR GPG_ERR_USER_5
416 #define EPWMD_FILE_MODIFIED GPG_ERR_USER_6
417 #define EPWMD_MAX GPG_ERR_USER_7
420 * Return a string describing a pwmd protocol error code.
422 const char *pwmd_strerror(gpg_error_t error
);