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 0x@VER_MAJOR@@VER_MINOR@@VER_PATCH@
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: You can use pwmd_open_async() and pwmd_save_async() for
48 * non-blocking pin retrieval. These will have pwmd use it's pinentry method
49 * rather than have libpwmd fork(). pwmd_open_nb() and pwmd_save_nb() will be
50 * kept (both were previously flagged as deprecated) in case pin retrieval
51 * isn't possible with pwmd.
54 char filename
[FILENAME_MAX
];
55 int fd
; /* Closed after the finalize function. */
56 gpg_error_t error
; /* Returned from the NB function. */
60 * For use with pwmd_process(). pwmd_open_async() and pwmd_save_async() use
70 * A custom callback password retrieval function which is set with
71 * pwmd_setopt(). This has priority over other retrieval methods if set.
73 typedef char *(*pwmd_password_fn
)(pwm_t
*pwm
, void *data
);
76 * A callback to be set with pwmd_setopt() that processes Assuan protocol
77 * status messages. The 'line' is the status message which is prefixed with
80 typedef int (*pwmd_status_fn
)(void *data
, const char *line
);
83 * A callback function that is passed to pwmd_inquire(). 'data' is the user
84 * data that was passed to pwmd_inquire(). 'keyword' is the same as the 'cmd'
85 * argument to pwmd_inquire().
87 * 'rc' is the return code from assuan_send_data() and is initially 0 on the
88 * first call to the set callback. This gives the client a chance to cleanup
89 * if assuan_send_data() fails for some reason and should probably return the
90 * same error code, if set, after doing so.
92 * 'result' should be set to the data to be sent which is of 'len' bytes. The
93 * data is not modified.
95 * The function should return GPG_ERR_EOF when no more data needs to be sent
96 * or to finish sending the set 'result' and end the INQUIRE, 0 if there is
97 * more data pending or an error code which will terminate the INQUIRE.
99 typedef gpg_error_t (*pwmd_inquire_fn
)(void *data
, const char *keyword
,
100 gpg_error_t rc
, char **result
, size_t *len
);
103 * Library options which are set with pwmd_setopt().
107 * PWMD_OPTION_PASSWORD_FUNC
109 * Function to retrieve a password. This function should return an
110 * string which is the password or NULL on error.
112 PWMD_OPTION_PASSWORD_FUNC
,
115 * PWMD_OPTION_PASSWORD_DATA
117 * Data passed to the password function.
119 PWMD_OPTION_PASSWORD_DATA
,
122 * PWMD_OPTION_PINENTRY
124 * The following argument should be of type int and set to 1 to enable the
125 * use of pinentry(1) to retrieve passwords. Setting to 0 will disable
126 * using pinentry and the password must be set with PWMD_OPTION_PASSWORD
127 * or gotten from PWMD_OPTION_PASSWORD_FUNC. The pwmd command "OPTION
128 * PINENTRY=0" is sent when this option is set (1) to prevent pinentry
129 * from being called on the pwmd server and enabled when unset.
131 PWMD_OPTION_PINENTRY
,
134 * PWMD_OPTION_PINENTRY_TRIES
136 * The number of password tries before giving up. If the pinentry "Cancel"
137 * button is selected, pinentry will abort. Must be > 0. The default is 3.
139 PWMD_OPTION_PINENTRY_TRIES
,
142 * PWMD_OPTION_PINENTRY_PATH
144 * The full pathname to the pinentry program. If not specified,
145 * /usr/bin/pinentry will be used.
147 PWMD_OPTION_PINENTRY_PATH
,
150 * PWMD_OPTION_PINENTRY_TTY
152 * pinentry --ttyname.
154 PWMD_OPTION_PINENTRY_TTY
,
157 * PWMD_OPTION_PINENTRY_DISPLAY
161 PWMD_OPTION_PINENTRY_DISPLAY
,
164 * PWMD_OPTION_PINENTRY_TERM
168 PWMD_OPTION_PINENTRY_TERM
,
171 * PWMD_OPTION_PASSWORD
173 * The following argument should be of type char* which specifies the
174 * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
175 * PWMD_OPTION_PINENTRY is 0. The password will be kept in memory until
176 * pwmd_close() is called so setting this option isn't needed each time
177 * pwmd_open() or pwmd_save() is called regardless of pwmd cache settings.
179 PWMD_OPTION_PASSWORD
,
182 * PWMD_OPTION_PINENTRY_TITLE
183 * PWMD_OPTION_PINENTRY_PROMPT
184 * PWMD_OPTION_PINENTRY_DESC
186 * The following argument is of type char* which specifies either the
187 * title, prompt or description in the pinentry program when
188 * PWMD_OPTION_PINENTRY is set. Note that any CR, LF or % must be percent
189 * escape (the hexidecimal value of the character).
191 PWMD_OPTION_PINENTRY_TITLE
,
192 PWMD_OPTION_PINENTRY_PROMPT
,
193 PWMD_OPTION_PINENTRY_DESC
,
196 * PWMD_OPTION_STATUS_FUNC
198 * A function to be called when a status line is sent from pwmd. This
199 * function should return 0 on success or a gpg-error error code. This
200 * function won't be used when getting a password with pinentry.
202 PWMD_OPTION_STATUS_FUNC
,
205 * PWMD_OPTION_STATUS_DATA
207 * Data passed to the status function.
209 PWMD_OPTION_STATUS_DATA
,
212 * PWMD_OPTION_VERIFY_HOSTNAME
214 * When verifying the server certificate and this option is set to 1,
215 * also verify the hostname defined in the server certificate. The
218 PWMD_OPTION_VERIFY_HOSTNAME
,
222 * Initialize the library. This sets up various things and must be called
223 * before the other functions.
225 gpg_error_t
pwmd_init(void);
228 * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
229 * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
230 * with the other functions or NULL if there was an error in which case
231 * 'error' is set to an error code which may be described by pwmd_strerror().
233 pwm_t
*pwmd_connect(const char *socket_path
, gpg_error_t
*error
) __attribute__ ((warn_unused_result
));
236 * Connects to the remote host "host". Both Ipv4 and IPv6 addresses are
237 * supported. The "port" parameter may be -1 which uses the default pwmd
240 * The "cert" and "key" parameters should be the location of the client
241 * certificate and client certificate key files to use during authentication.
242 * If NULL, then the defaults ~/.pwmd/client-cert.pem and
243 * ~/.pwmd/client-key.pem will be used. The "ca" parameter is the certificate
244 * authority that the server certificate was signed with. If NULL, the default
245 * ~/.pwmd/ca-cert.pem will be used.
247 * Returns a new handle for use with the other functions or NULL if there was
248 * an error in which case 'error' is set to an error code which may be
249 * described by pwmd_strerror().
251 pwm_t
*pwmd_tcp_connect(char *hostname
, int port
, gpg_error_t
*error
,
252 const char *cert
, const char *key
, const char *ca
) __attribute__ ((warn_unused_result
));
254 /* Like pwmd_tcp_connect() but this function wont block while doing DNS
255 * lookups and connecting. You should call pwmd_process() only when this
256 * function succeeds (see pwmd_process() for more information).
258 pwm_t
*pwmd_tcp_connect_async(char *hostname
, int port
, gpg_error_t
*error
,
259 const char *cert
, const char *key
, const char *ca
) __attribute__ ((warn_unused_result
));
262 * Sets 'ctx' to the assuan context associated with the handle 'pwm' and 'fd'
263 * to the socket file descriptor. Returns 0 on success or an error code.
265 struct assuan_context_s
;
266 typedef struct assuan_context_s
*assuan_context_t
;
267 gpg_error_t
pwmd_assuan_ctx(pwm_t
*pwm
, assuan_context_t
*ctx
, int *fd
) __attribute__ ((warn_unused_result
));
270 * A wrapper around assuan_pending_line() and assuan_read_line(). Returns 0 if
271 * there was a pending line and sets 'line' to the content and 'len' to the
272 * length. Returns GPG_ERR_NO_DATA if there was no pending line. Otherwise the
273 * error returned from assuan_read_line() is returned.
275 gpg_error_t
pwmd_pending_line(pwm_t
*pwm
, char **line
, size_t *len
) __attribute__ ((warn_unused_result
));
278 * Sets a libpwmd option 'opt'. The next argument should be of the data type
279 * required for the option. Returns 0 on success or an error code.
281 gpg_error_t
pwmd_setopt(pwm_t
*pwm
, pwmd_option_t opt
, ...) __attribute__ ((warn_unused_result
));
284 * Opens a file 'filename' (the OPEN command). The filename is not a full path
285 * but only filename which is looked for in the pwmd configured data
286 * directory. How the password is gotten depends on the options set with
287 * pwmd_setopt() and whether the file is cached on the server. Returns 0 on
288 * success or an error code.
290 gpg_error_t
pwmd_open(pwm_t
*pwm
, const char *filename
) __attribute__ ((warn_unused_result
));
293 * This is like pwmd_open() but won't block the process when pinentry is used
294 * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
295 * on the server or if the file doesn't exist on the file system (a new file).
296 * Otherwise it returns a file descriptor that select() can use. When ready
297 * for a read, read() should read a pwmd_nb_status_t. If there is a system
298 * error (pipe() or fork()), then -1 is returned and 'error' is set to an
299 * error code that pwmd_strerror() can describe. See pwmd_open_nb_finalize().
301 * The 'timeout' parameter specifies the number of seconds until the pinentry
302 * terminates. Setting to 0 (the default) will disable timeouts. Note that the
303 * child process will reset the SIGALRM handler (if any) to it's own handler
304 * and that the actual OPEN command isn't calculated as part of the elapsed
307 * Be sure to set PWMD_OPTION_PINENTRY.
309 int pwmd_open_nb(pwm_t
*pwm
, gpg_error_t
*error
, const char *filename
,
310 int timeout
) __attribute__ ((warn_unused_result
));
313 * When a file descriptor has been returned from pwmd_open_nb() and after a
314 * successful read(), you should call pwmd_open_nb_finalize() to update the
315 * 'pwm' handle. If there was a pinentry or protocol error
316 * pwmd_open_nb_finalize() will return an error code or 0 on success. Note
317 * that pwmd_open_nb_finalize() will close the file descriptor returned from
320 gpg_error_t
pwmd_open_nb_finalize(pwm_t
*pwm
, pwmd_nb_status_t
*status
) __attribute__ ((warn_unused_result
));
323 * This is the preferred way to do a non-blocking open. The difference from
324 * pwmd_open_nb() is that libpwmd wont fork() to get the pin. Instead, it will
325 * let pwmd use it's pinentry retrieval method. When successful this function
326 * returns 0 and pwmd_process() should be called until the command completes.
328 * If pwmd is unable to use pinentry, and non-blocking is needed, then
329 * pwmd_open_nb() can be used instead.
331 gpg_error_t
pwmd_open_async(pwm_t
*pwm
, const char *filename
) __attribute__ ((warn_unused_result
));
335 * When the asynchronous commands pwmd_tcp_connect_async(), pwmd_open_async()
336 * or pwmd_save_async() succeed (return 0 or non-NULL), this function
337 * should be called until ASYNC_DONE is returned. It will return ASYNC_PROCESS
338 * when the command is still running. After ASYNC_DONE is returned, any error
339 * that may have occurred is stored in 'rc'. If an error occurred or not,
340 * pwmd_finalize() must be called to reset a control variable so the next
341 * asynchronous command may be performed.
343 pwmd_async_t
pwmd_process(pwm_t
*pwm
, gpg_error_t
*rc
) __attribute__ ((warn_unused_result
));
347 * Resets the control variable for the associated handle. Call this function
348 * after ASYNC_DONE is returned from pwmd_process(). The return value is not
349 * associated with the command that was being processed with pwmd_process().
350 * This function returns 0 on success or an error if "pwm" is not a valid
351 * handle or in an inconsistant state.
353 * NOTE: In the case that pwmd_tcp_connect_async() was used for the
354 * asynchronous command and an error occurred while connecting, this function
355 * will deallocate the resources used by the handle. You may then retry the
358 gpg_error_t
pwmd_finalize(pwm_t
*pwm
) __attribute__ ((warn_unused_result
));
362 * Sends the SAVE command to the associated handle 'pwm'. If a password is
363 * required, how it is gotten depends on options set with pwmd_setopt().
364 * Returns 0 on success or an error code.
366 gpg_error_t
pwmd_save(pwm_t
*pwm
) __attribute__ ((warn_unused_result
));
369 * This is like pwmd_save() but won't block the process when pinentry is used
370 * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
371 * on the server or if the file doesn't exist on the file system (a new file).
372 * Otherwise it returns a file descriptor that select() can use. When ready
373 * for a read, read() should read a pwmd_nb_status_t. If there is a system
374 * error (pipe() or fork()), then -1 is returned and 'error' is set to an
375 * error code that pwmd_strerror() can describe. See pwmd_save_nb_finalize().
377 * Note that there is no timeout setting. If a password is required, pinentry
378 * won't timeout but will wait until either it is canceled or a successful
379 * passphrase is entered.
381 * Be sure to set PWMD_OPTION_PINENTRY.
383 int pwmd_save_nb(pwm_t
*pwm
, gpg_error_t
*error
) __attribute__ ((warn_unused_result
));
386 * When a file descriptor has been returned from pwmd_save_nb() and after a
387 * successful read(), you should call pwmd_save_nb_finalize() to update the
388 * 'pwm' handle. If there was a pinentry or protocol error
389 * pwmd_save_nb_finalize() will return an error code or 0 on success. Note
390 * that pwmd_save_nb_finalize() will close the file descriptor returned from
393 gpg_error_t
pwmd_save_nb_finalize(pwm_t
*pwm
, pwmd_nb_status_t
*status
) __attribute__ ((warn_unused_result
));
396 * Like pwmd_save_nb() but uses pwmd to launch pinentry rather than having
397 * libpwmd fork(). This function returns 0 on success and pwmd_process()
398 * should be called until the command completes.
400 gpg_error_t
pwmd_save_async(pwm_t
*pwm
) __attribute__ ((warn_unused_result
));
404 * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
405 * timeout the associated pinentry process, then call this function after your
406 * timer has expired. Returns 0 on success or an error code.
408 gpg_error_t
pwmd_terminate_pinentry(pwm_t
*pwm
) __attribute__ ((warn_unused_result
));
411 * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
412 * command fails an error code is returned which may be described by passing
413 * the error to pwmd_strerror(). If successful the function returns 0 and the
414 * 'result' is the character data of the command or NULL if there was none.
416 * For commands which use an INQUIRE (i.e., STORE), use pwmd_inquire() and not
419 * A note about the BYE command: Client's should not send this command
420 * directly with pwmd_command(). They should use pwmd_close() instead because
421 * libassuan will close the file descriptors with the associated context.
423 gpg_error_t
pwmd_command(pwm_t
*pwm
, char **result
, const char *cmd
, ...) __attribute__ ((warn_unused_result
));
426 * Commands which use an INQUIRE to send data (i.e., STORE) should use this
427 * function and not pwmd_command(). 'cmd' is the command to send and is also
428 * the 'keyword' argument passed to the callback function 'func'. 'data' is
429 * user data passed to the callback function. Returns 0 on success or an
430 * error code which may have been returned from the callback function.
432 gpg_error_t
pwmd_inquire(pwm_t
*pwm
, const char *cmd
, pwmd_inquire_fn func
,
433 void *data
) __attribute__ ((warn_unused_result
));
436 * Free the memory used by the result of pwmd_command() if any. It is
437 * important to use this function because libpwmd keeps track of all memory
440 void pwmd_free_result(void *);
443 * Closes the connection to the socket and frees the resources of the handle.
446 void pwmd_close(pwm_t
*pwm
);
449 * Protocol error codes.
451 #define EPWMD_BADKEY GPG_ERR_INV_PASSPHRASE
452 #define EPWMD_COMMAND_SYNTAX GPG_ERR_SYNTAX
453 #define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_ELEMENT_NOT_FOUND
454 #define EPWMD_ACCOUNT_EXISTS GPG_ERR_AMBIGUOUS_NAME
455 #define EPWMD_CACHE_NOT_FOUND GPG_ERR_NOT_FOUND
456 #define EPWMD_ATTR_SYNTAX GPG_ERR_SYNTAX
457 #define EPWMD_ATTR_NOT_FOUND GPG_ERR_NOT_FOUND
458 #define EPWMD_INVALID_FILENAME GPG_ERR_INV_VALUE
459 #define EPWMD_EMPTY_ELEMENT GPG_ERR_NO_VALUE
460 #define EPWMD_INVALID_ELEMENT GPG_ERR_INV_VALUE
461 #define EPWMD_ERROR GPG_ERR_USER_1
462 #define EPWMD_MAX_SLOTS GPG_ERR_USER_2
463 #define EPWMD_LOOP GPG_ERR_USER_3
464 #define EPWMD_NO_FILE GPG_ERR_USER_4
465 #define EPWMD_LIBXML_ERROR GPG_ERR_USER_5
466 #define EPWMD_FILE_MODIFIED GPG_ERR_USER_6
467 #define EPWMD_FILE_ACCESS GPG_ERR_USER_7
468 #define EPWMD_MAX GPG_ERR_USER_8
471 * Return a string describing a pwmd protocol error code.
473 const char *pwmd_strerror(gpg_error_t error
);