1 /* vim:tw=78:ts=8:sw=4:set ft=c: */
3 Copyright (C) 2006-2009 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
19 /*! \headerfile libpwmd.h
21 * libpwmd is a library making it easy for applications to use the pwmd
22 * server. Pwmd version 2.0 or later is required; either locally or remotely.
25 /*! \section threads Multiple Threads
27 * \ref libpwmd should be thread-safe on a per handle bases. Meaning that only
28 * one thread should access a \ref pwm_t handle at a time.
30 * There is a limitation that when compiled with \ref pth(3) support SSH
31 * connections cannot make use of the \ref pth(3) IO functions and therefore
32 * will block while waiting on IO operations in other threads (as of libssh2
36 /*! \section ssh SSH Details
38 * A remote connection to a pwmd server is possible by using an SSH channel
39 * which spawns a shell and executes a proxy server that connects to the pwmd
40 * local Unix Domain Socket. Authentication is done by using SSH public key
41 * (see \ref ssh-keygen(1)) authentication and verifying the host key against
42 * a local OpenSSH known hosts formatted file.
44 * The servers public key can be had by using \ref pwmd_get_hostkey() and
45 * storing the result in a file or done automatially by using a callback
46 * function \ref pwmd_knownhost_cb_t while connecting to the unknown host.
48 * On the server side you'll need a proxy server to connect to the real pwmd
49 * server. Here's an example \ref authorized_keys(5) entry that will do this.
50 * The \a public_key portion should be the same as the contents of the
51 * generated \ref ssh-keygen(1) \a identity.pub file which is passed as a
52 * parameter to the SSH connection functions:
55 * command="socat UNIX-CONNECT:$HOME/.pwmd/socket -" <public_key> ...
58 * \note Only an SSH identity without a passphrase is supported. For now
59 * anyway. This is a limitation of libssh2 (version 1.1 as of this writing).
62 * The first version to use the OpenSSH known hosts file format exclusively.
63 * Earlier versions used only an SHA1 hash of the host key.
68 /*! \section pinentry Pinentry Details
70 * \ref pinentry(1) is a program that prompts the user for input which is
71 * normally a passphrase or a confirmation. libpwmd can use this program
72 * either locally (X11 forwarding is not yet supported) or have the pwmd
73 * server use it's pinentry to retrieve a passphrase when needed. How this is
74 * done depends what function gets called and whether the pwmd connection is
75 * over an SSH channel.
77 * There are a few options that tell pinentry how and where to prompt for a
78 * needed passphrase. See the \ref pwmd_option_t section for details. These
79 * options are not sent (when using pwmd's pinentry, not the local one) until
80 * the pinentry is needed.
82 * If using a local pinentry by calling \ref pwmd_open2(), \ref pwmd_save2(),
83 * \ref pwmd_open_async2() or pwmd_save_async2(), libpwmd will send the
84 * command "SET ENABLE_PINENTRY=0" to the pwmd server. This is needed so pwmd
85 * wont try to launch it's own pinentry on passphrase or confirmation failure.
86 * So you may need to reset this option manually depending on your needs;
87 * especially when changing pinentry methods when doing a save (the passphrase
88 * may be set as empty since the remote pinentry is disabled!).
90 * Some pinentry options can also be specified in a local configuration file
91 * \a "~/.pwmd/pinentry.conf". These options are initial values for each
92 * pinentry invokation (not retries) and may be changed by setting the
93 * appropriate \ref pwmd_option_t. Each option and value is separated with a
94 * '=' on a single line. Unrecognized options are ignored. Here are the
97 * \param PATH The full path to the location of the pinentry binary.
98 * \param DISPLAY The X11 display to use.
99 * \param TTYNAME The full path to the tty that pinentry should prompt on.
100 * \param TTYTYPE The terminal type of the tty which is required if DISPLAY is
105 * \note The initial values for the pinentry TTY, TERM and DISPLAY are set
106 * during \ref pwmd_new() depending on the current environment. They may need
107 * to be reset as needed.
109 * \note After establishing an SSH connection, the pwmd pinentry is disabled
110 * by sending the command "SET ENABLE_PINENTRY=0". This is needed because
111 * there currently isn't a way to have the remote pinentry use the local
112 * display. You must be careful to use either a local pinentry or set a
113 * passphrase manually with \ref pwmd_setopt() when a passphrase is required
123 * libpwmd uses libgpg-error for all error codes. Some are user defined
124 * GPG_ERR_USER_N codes, but most are reused from the existing ones. Error
125 * codes can be described by using \ref pwmd_strerror(), or the thread-safe
126 * \ref pwmd_strerror_r().
128 * \note libgpg-error normally returns an error code as a bitmask of an error
129 * source and the actual error code. In order to simplify the result codes,
130 * libpwmd strips any error source from the error code before returning it.
141 #include <gpg-error.h>
148 /*! \def LIBPWMD_VERSION
149 * \brief Version information.
151 * The version of this library.
153 #define LIBPWMD_VERSION 0x@VER_MAJOR@@VER_MINOR@@VER_PATCH@
156 /*! \def LIBPWMD_VERSION_MAJOR
157 * \brief Version information.
159 * The major release number of this library.
161 #define LIBPWMD_VERSION_MAJOR @VER_MAJOR@
164 /*! \def LIBPWMD_VERSION_MINOR
165 * \brief Version information.
167 * The minor release number of this library.
169 #define LIBPWMD_VERSION_MINOR @VER_MINOR@
172 /*! \def LIBPWMD_VERSION_PATCH
173 * \brief Version information.
175 * The patch level of this library.
177 #define LIBPWMD_VERSION_PATCH @VER_PATCH@
180 /*! \def LIBPWMD_VERSION_STR
181 * \brief Version information.
183 * A string representation of the version of this library.
185 #define LIBPWMD_VERSION_STR @VER_STRING@
188 /*! \brief Returns this version of libpwmd.
193 LIBPWMD_API
const char *pwmd_version();
198 * \brief libpwmd handle.
200 * When a handle is mentioned in this documentation it is a pointer of this
201 * type. A new handle is created with \ref pwmd_new().
203 typedef struct pwm_s pwm_t
;
206 /*! \typedef pwmd_async_t
207 * \brief Asynchronous return value.
209 * The return code of \ref pwmd_process() which is used for all asynchronous
216 /*! \ref pwmd_process() should be called again. */
219 /*! The command has completed. The result code should be checked for an
225 /*! \typedef pwmd_ip_version_t
226 * \brief IP protocol version for remote SSH connections.
228 * The value of the option \ref PWMD_OPTION_IP_VERSION which is set with \ref
232 /*! Try both IPv4 and IPv6 addresses. Note that IPv6 is tried first and
233 * that \ref PWMD_IP_ANY only affects a hostname and not an IP address in
234 * the address specification. */
237 /*! Only try IPv4. */
240 /*! Only try IPv6. */
245 /*! \def PWMD_FD_READABLE
246 * \brief For use with \ref pwmd_get_fds().
248 * Set when the file descriptor is readable.
250 #define PWMD_FD_READABLE 0x01
253 /*! \def PWMD_FD_WRITABLE
254 * \brief For use with \ref pwmd_get_fds().
256 * Set when the file descriptor is writable.
258 #define PWMD_FD_WRITABLE 0x02
261 /*! For use with \ref pwmd_get_fds(). */
263 /*! The file descriptor. */
266 /*! A bitmask of \ref PWMD_FD_READABLE and \ref PWMD_FD_WRITABLE. */
271 /*! \typedef pwmd_socket_t
272 * \brief The type of socket a handle is connected to.
274 * For use with \ref pwmd_socket_type().
277 /*! A local domain socket. */
280 /*! An SSH connection over a TCP socket. */
285 /*! \typedef pwmd_pinentry_t
286 * \brief Local pinentry commands and not pwmd pinentry.
288 * For use with \ref pwmd_getpin().
291 /*! When opening a file. */
294 /*! When opening a file failed. */
295 PWMD_PINENTRY_OPEN_FAILED
,
297 /*! When saving a file. */
300 /*! For passphrase confirmation. */
301 PWMD_PINENTRY_SAVE_CONFIRM
,
303 /*! For confirmation of a user-defined prompt. */
304 PWMD_PINENTRY_CONFIRM
,
306 /*! For the default or user defined string set with \ref
307 * PWMD_OPTION_PINENTRY_DESC. */
308 PWMD_PINENTRY_DEFAULT
,
310 /*! To terminate the pinentry process created with \ref pwmd_getpin(). */
315 /*! \typedef pwmd_passphrase_cb_t
316 * \brief Custom passphrase retrieval function.
318 * The value of the option \ref PWMD_OPTION_PASSPHRASE_CB which is set with
319 * \ref pwmd_setopt().
321 * \param user A user data pointer which is set with \ref
322 * PWMD_OPTION_PASSPHRASE_DATA.
323 * \param[out] passphrase The passphrase which may be an empty string or NULL.
324 * It is not modified by libpwmd but must remain allocated for as long as it
326 * \return 0 on success or an error code which will cause a command to fail.
328 typedef gpg_error_t (*pwmd_passphrase_cb_t
)(void *user
, char **passphrase
);
331 /*! \typedef pwmd_status_cb_t
332 * \brief Process status messages.
334 * The value of the option \ref PWMD_OPTION_STATUS_CB which is set with \ref
337 * \param user A user data pointer which is set with \ref
338 * PWMD_OPTION_STATUS_DATA.
339 * \param line The status message line received from the server.
340 * \return 0 on success or an error code which will cause a command to fail.
342 typedef int (*pwmd_status_cb_t
)(void *user
, const char *line
);
345 /*! \typedef pwmd_inquire_cb_t
346 * \brief Send data to the pwmd server.
348 * This is a callback function that gets passed to \ref pwmd_inquire(). It is
349 * used for sending data to the server for commands that need to reply to an
350 * INQUIRE server response (STORE and IMPORT). The reason for this callback is
351 * to let the client send as many bytes as it wants rather than the entire
352 * chunk at once. It gets called during an internal \ref assuan_transact()
353 * from an internal inquire callback function which in turn calls this
354 * function by looping over its return value.
356 * \param user The user data pointer passed to \ref pwmd_inquire().
357 * \param cmd The same as the \a cmd argument to \ref pwmd_inquire().
358 * \param rc The result of the last internal call to \ref assuan_send_data()
359 * which did the sending of the data to the pwmd server. On the first call to
360 * this callback it's value will always be 0 since no data has been sent yet.
361 * \param[out] data The next chunk of data to send or NULL.
362 * \param[out] len The length of \a data or 0.
364 * \retval 0 There is more data to be sent.
365 * \retval GPG_ERR_CANCELED Cancel the current inquire.
366 * \retval GPG_ERR_EOF No need to call this function again, the current
367 * \a line is the last to send.
368 * \retval code Any other error code which will terminate the INQUIRE.
370 * \note The sent data is processed line-per-line. The line is either newline
371 * terminated or is buffered until ASSUAN_LINELENGTH bytes have been
372 * allocated. Any remaining bytes are sent after the INQUIRE has finished.
374 typedef gpg_error_t (*pwmd_inquire_cb_t
)(void *user
, const char *cmd
,
375 gpg_error_t rc
, char **data
, size_t *len
);
378 /*! \typedef pwmd_knownhost_cb_t
379 * \brief Verify a remote SSH connection.
381 * When \ref PWMD_OPTION_KNOWNHOST_CB is set and a the current connections
382 * host key was not found in the known hosts file, then this callback function
383 * can be used to confirm the addition of the new host key to the known_hosts
386 * \param user User data which was set with \ref PWMD_OPTION_KNOWNHOST_DATA.
387 * \param host The hostname as passed to the connecting function.
388 * \param key The raw host key. Note that this differs from the format
389 * returned from \ref pwmd_get_hostkey().
390 * \param len The host key length.
391 * \retval 0 Add the host key to the known hosts file.
392 * \retval GPG_ERR_NOT_CONFIRMED Do not add the host key and abort the
395 * \note If the known hosts file cannot be modified do to filesystem
396 * restrictions when trying to add the new host key, no error is returned.
397 * Instead the host key is added to the current connections host key cache and
398 * the connection is considered verified.
402 typedef gpg_error_t (*pwmd_knownhost_cb_t
)(void *user
, const char *host
,
403 const char *key
, size_t len
);
406 /*! \enum pwmd_option_t
407 * \brief libpwmd options.
409 * Options are set with \ref pwmd_setopt().
414 /*! A custom passphrase retrieval function which, when set, will be used
415 * instead of \ref pinentry(1). This function will not be used if opening
416 * a file and the passphrase is cached on the server or the file is a new
417 * one. The value of this option should be a \ref pwmd_passphrase_cb_t.
419 * \note An empty string as the passphrase is allowed.
421 PWMD_OPTION_PASSPHRASE_CB
,
423 /*! User supplied data which is passed to the custom passphrase function.
425 PWMD_OPTION_PASSPHRASE_DATA
,
427 /*! A string to use as the passphrase when doing an open or save. When not
428 * NULL, this option has precedence over \ref PWMD_OPTION_PASSPHRASE_CB.
430 * \note An empty string as the passphrase is allowed.
432 PWMD_OPTION_PASSPHRASE
,
434 /*! An integer value that specifies the number of tries before \ref
435 * pinentry(1) will give up when opening a file with the wrong supplied
436 * passphrase. The default is 3.
438 * \note This option has no effect when trying to save a file. The user
439 * must either cancel the pinentry causing the save to fail or enter the
440 * correct passphrase during passphrase confirmation.
442 PWMD_OPTION_PINENTRY_TRIES
,
444 /*! A character string value which specifies the full path of the \ref
445 * pinentry(1) binary. For the local \ref pinentry(1) method, the default
446 * is specified at compile time.
450 PWMD_OPTION_PINENTRY_PATH
,
452 /*! A value which specifies the full path to the TTY that \ref pinentry(1)
453 * will use to prompt on. When set and no DISPLAY is available, \ref
454 * PWMD_OPTION_PINENTRY_TERM must also be set.
458 PWMD_OPTION_PINENTRY_TTY
,
460 /*! A value which specifies the terminal type (e.g., vt100) that \ref
461 * pinentry(1) will use when no X11 display is available.
465 PWMD_OPTION_PINENTRY_TERM
,
467 /*! A value which specifies the X11 display that \ref pinentry(1) will
474 PWMD_OPTION_PINENTRY_DISPLAY
,
476 /*! A character string that \ref pinentry(1) will use in it's dialog
479 PWMD_OPTION_PINENTRY_TITLE
,
481 /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
482 PWMD_OPTION_PINENTRY_PROMPT
,
484 /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
485 PWMD_OPTION_PINENTRY_DESC
,
487 /*! For \ref pinentry(1) localization. */
488 PWMD_OPTION_PINENTRY_LC_CTYPE
,
490 /*! \copydoc PWMD_OPTION_PINENTRY_LC_CTYPE */
491 PWMD_OPTION_PINENTRY_LC_MESSAGES
,
493 /*! An integer value that specifies the number of seconds \ref pinentry(1)
494 * will wait for input before timing out and aborting the current command.
495 * If 0, then no timeout will be used. The default is 30.
497 PWMD_OPTION_PINENTRY_TIMEOUT
,
499 /*! A function of type \ref pwmd_status_cb_t that will process status
500 * messages received from the pwmd server.
502 PWMD_OPTION_STATUS_CB
,
504 /*! A user data pointer which is passed to the status message function. */
505 PWMD_OPTION_STATUS_DATA
,
507 /*! The IP version of type \ref pwmd_ip_version_t that \ref
508 * pwmd_ssh_connect() and \ref pwmd_ssh_connect_async() will use when
509 * connecting to the remote pwmd server. The default is \ref PWMD_IP_ANY.
513 PWMD_OPTION_IP_VERSION
,
515 /*! A function to confirm an unknown host hash which wasn't found in the
520 PWMD_OPTION_KNOWNHOST_CB
,
522 /*! User supplied data which is passed to the known host function.
526 PWMD_OPTION_KNOWNHOST_DATA
,
528 /*! When the total number of bytes to be sent via an INQUIRE is known,
529 * this should be set so XFER status messages can be parsed correctly.
530 * When not known or unset, 0 is used as the total argument to the XFER
531 * status message. This option should be set before each call to
532 * \ref pwmd_inquire().
534 * \note During the INQUIRE, PWMD_OPTION_STATUS_CB is called after every
535 * ASSUAN_LINELENGTH bytes have been successfully transferred.
537 * \note This is a libpwmd feature. pwmd itself does not send XFER status
538 * messages during an INQUIRE. Status messages can be parsed only when
539 * PWMD_OPTION_STATUS_CB is set.
541 PWMD_OPTION_INQUIRE_TOTAL
,
543 /*! When set to 1, lock the file mutex after opening a file as if the LOCK
544 * command had been sent.
546 PWMD_OPTION_LOCK_ON_OPEN
,
548 /*! A long integer specifying the number of iterations to encrypt with.
549 * When -1 then the next save operation will use the current iteration
550 * setting and no command will be sent to alter it.
552 PWMD_OPTION_ITERATIONS
,
554 /*! A string specifying the cipher to use to encrypt with. See the pwmd(1)
555 * manual page for available ciphers.
559 /*! When 1, tell pwmd that the passphrase is Base64 encoded. pwmd will
560 * decode the passphrase before encryption and decryption. */
563 /*! Use ssh-agent to retrieve private key to authenticate. */
564 PWMD_OPTION_SSH_AGENT
,
568 /*! \brief Initialize the library.
570 * This function must be the first function called in the library before any
571 * others. It sets up the memory allocators and internationalization among
574 * \return 0 on success or an error code.
576 LIBPWMD_API gpg_error_t
pwmd_init(void);
579 /*! \brief Creates a new handle.
581 * Creates a new handle for use with the other functions.
583 * \param name If not NULL, the name of the application. The application name
584 * is sent to the pwmd server after successfully connecting.
586 * \return a new handle or NULL if there was not enough memory.
588 LIBPWMD_API pwm_t
*pwmd_new(const char *name
);
591 /*! \brief Connect to a local pwmd server.
593 * Connects to a local unix domain socket.
595 * \param pwm A handle.
596 * \param path The socket path to connect to. If NULL, then a default of
597 * \a "~/.pwmd/socket" will be used.
598 * \return 0 on success or an error code.
600 * \see pwmd_ssh_connect(), pwmd_ssh_connect_async(), pwmd_disconnect()
602 LIBPWMD_API gpg_error_t
pwmd_connect(pwm_t
*pwm
, const char *path
);
605 /*! \brief Establish a remote connection to a pwmd server.
607 * Connects to a pwmd server over an SSH channel.
609 * \param pwm A handle.
610 * \param host The hostname to connect to or NULL to resume a connection
611 * previously started with \ref pwmd_get_hostkey().
612 * \param port The port or -1 for the default of 22.
613 * \param identity The SSH identity file to use for authentication. This
614 * should specify the private key. The public key is assumed to be \a
615 * identity.pub. This parameter is not used if \ref PWMD_OPTION_SSH_AGENT is
617 * \param user The username on the SSH server to login as. If NULL then
618 * invoking username will be used.
619 * \param known_hosts An OpenSSH known hosts formatted file containing public
620 * SSH server hashes which may be obtained with \ref pwmd_get_hostkey() or via
621 * \ref pwmd_knownhost_cb_t during a connection. If NULL, the default of
622 * \a "~/.ssh/known_hosts" will be used.
623 * \return 0 on success or an error code.
625 * \see pwmd_ssh_connect_async(), \ref PWMD_OPTION_IP_VERSION,
626 * pwmd_disconnect(), \ref ssh
628 LIBPWMD_API gpg_error_t
pwmd_ssh_connect(pwm_t
*pwm
, const char *host
,
629 int port
, const char *identity
, const char *user
, const char
633 /*! \brief Establish a remote connection to a pwmd server (asynchronously).
635 * This is a variant of \ref pwmd_ssh_connect() that will not block while doing
636 * DNS lookups or while connecting.
640 * \param pwm A handle.
641 * \param host The hostname to connect to or NULL to resume a connection
642 * previously started with \ref pwmd_get_hostkey().
643 * \param port The port or -1 for the default of 22.
644 * \param identity The SSH identity file to use for authentication. This
645 * should specify the private key. The public key is assumed to be \a
646 * identity.pub. This parameter is not used if \ref PWMD_OPTION_SSH_AGENT is
648 * \param user The username on the SSH server to login as. If NULL, the
649 * invoking username will be used.
650 * \param known_hosts An OpenSSH known hosts formatted file containing public
651 * SSH server hashes which may be obtained with \ref pwmd_get_hostkey() or via
652 * \ref pwmd_knownhost_cb_t during a connection. If NULL, the default of
653 * \a "~/.ssh/known_hosts" will be used.
654 * \return 0 on success or an error code.
656 * \see pwmd_process(), \ref PWMD_OPTION_IP_VERSION, pwmd_disconnect(),
659 LIBPWMD_API gpg_error_t
pwmd_ssh_connect_async(pwm_t
*pwm
, const char *host
,
660 int port
, const char *identity
, const char *user
, const char
664 /*! \brief Establish a connection by parsing a URL.
666 * This allows for connecting to a pwmd server by parsing the given URL
667 * string. Whether the connection is to a remote or local server depends on
670 * file://[path/to/local/socket]
674 * ssh[46]://[username@]hostname[:port][,identity,known_hosts]
677 * The parameters in square brackets are optional and if not specified then
678 * defaults will be used. If neither socket specification is matched, the
679 * \a url is assumed to be a file://.
681 * \param pwm A handle.
682 * \param url The string to parse.
684 * \return 0 on success or an error code.
685 * \see \ref pwmd_socket_type(), pwmd_disconnect()
687 LIBPWMD_API gpg_error_t
pwmd_connect_url(pwm_t
*pwm
, const char *url
);
690 /*! \brief Establish a connection by parsing a URL (asynchronously).
692 * This allows for connecting to a pwmd server by parsing the given URL
693 * string. Whether the connection is to a remote or local server depends on
696 * file://[path/to/local/socket]
700 * ssh[46]://[username@]hostname[:port][,identity,known_hosts]
703 * The parameters in square brackets are optional and if not specified then
704 * defaults will be used. If neither socket specification is matched, the
705 * \a url is assumed to be a file://.
709 * \param pwm A handle.
710 * \param url The string to parse.
712 * \return 0 on success or an error code.
713 * \see \ref pwmd_socket_type(), pwmd_disconnect()
715 LIBPWMD_API gpg_error_t
pwmd_connect_url_async(pwm_t
*pwm
, const char *url
);
718 /*! \brief Retrieve a remote SSH public host key.
720 * This key is needed for host verification of the remote pwmd server. You
721 * should be sure that the remote host is really the host that your wanting to
722 * connect to and not subject to a man-in-the-middle attack.
724 * \param pwm A handle.
725 * \param host The hostname or IP to connect to.
726 * \param port The port or -1 for the default of 22.
727 * \param[out] result An OpenSSH known hosts formatted string containing the
728 * servers public key which should be freed with \ref pwmd_free(). If the
729 * \a host was a hostname then two newline separated known host entries will
730 * be returned; one for the hostname and one for the resolved IP address. The
731 * IP known host entry will always be the second in the string.
732 * \return 0 on success or an error code.
735 * The connection is kept open but not verified after returning. It can be
736 * resumed from one of the SSH connection functions.
738 * \see pwmd_get_hostkey_async(), pwmd_ssh_connect(), \ref ssh
740 LIBPWMD_API gpg_error_t
pwmd_get_hostkey(pwm_t
*pwm
, const char *host
, int port
,
744 /*! \brief Retrieve a remote SSH host key (asynchronously).
746 * This key is needed for host verification of the remote pwmd server. You
747 * should be sure that the remote host is really the host that your wanting to
748 * connect to and not subject to a man-in-the-middle attack.
752 * \param pwm A handle.
753 * \param host The hostname or IP to connect to.
754 * \param port The port or -1 for the default of 22.
755 * \return 0 on success or an error code. The result is obtained from \ref
756 * pwmd_process() should be freed with \ref pwmd_free(). It has the same
757 * format as the result from \ref pwmd_get_hostkey().
760 * The connection is kept open but not verified after returning. It can be
761 * resumed from one of the SSH connection functions.
763 * \see pwmd_get_hostkey(), pwmd_ssh_connect_async(), \ref pwmd_process(),
766 LIBPWMD_API gpg_error_t
pwmd_get_hostkey_async(pwm_t
*pwm
, const char *host
,
770 /*! \brief Get the associated file descriptor(s) for a handle.
772 * This function lets the application manually poll the available file
773 * descriptors for the specified handle. It should be called after each
774 * asynchronous function call and after each call to \ref pwmd_process() since
775 * the polled file descriptors may have been closed since the previous call.
777 * After returning, \a n_fds is set to the number of available file
778 * descriptors which are stored in \a fds. The .flags member of \ref pwmd_fd_t
779 * specifies what can be monitored and is a bitmask of \ref PWMD_FD_READABLE
780 * and \ref PWMD_FD_WRITABLE. When ready, \ref pwmd_process() should be
783 * \param pwm A handle.
784 * \param[out] fds Set to the file descriptor(s) of the associated handle.
785 * \param[out] n_fds Initially the size of \a fds then updated to the number
786 * of available file descriptors which are stored in \a fds.
787 * \retval 0 on success or an error code.
788 * \retval GPG_ERR_ERANGE There are more file descriptors than the amount
789 * specified in \a n_fds. \a fds and \a n_fds are still usable though.
790 * \see pwmd_process()
792 LIBPWMD_API gpg_error_t
pwmd_get_fds(pwm_t
*pwm
, pwmd_fd_t
*fds
, int *n_fds
);
795 /*! \brief Check for a unparsed buffered line.
797 * A buffered line is a line that was read from the server but has not yet
798 * been processed. This function determines if there is such a line.
800 * \param pwm A handle.
801 * \retval 0 if there is a pending line.
802 * \retval GPG_ERR_NO_DATA if there is no pending line.
803 * \see pwmd_process()
805 LIBPWMD_API gpg_error_t
pwmd_pending_line(pwm_t
*pwm
);
808 /*! \brief Set handle options.
810 * See \ref pwmd_option_t for option specific details.
812 * \param pwm A handle.
813 * \param opt The option and following value.
814 * \return 0 on success or an error code.
816 LIBPWMD_API gpg_error_t
pwmd_setopt(pwm_t
*pwm
, pwmd_option_t opt
, ...);
819 /*! \brief Launch a local pinentry.
821 * Does not send any command to the server. Maybe useful if a passphrase is
822 * needed before opening a file over a remote connection. This passphrase can
823 * then be set with \ref pwmd_setopt().
825 * This function may also be used to display a user confirmation dialog with
826 * pinentry when \a which is \ref PWMD_PINENTRY_CONFIRM. The text to prompt
827 * with is set with \ref PWMD_OPTION_PINENTRY_TITLE.
829 * \param pwm A handle.
830 * \param filename The filename to use in the pinentry dialog strings.
831 * \param[out] result The entered value in the pinentry dialog which should be
832 * freed with \ref pwmd_free().
833 * \param which Determines the default strings shown in the pinentry
834 * dialog. \ref pwmd_setopt() may also be used to override the defaults. In
835 * this case \ref PWMD_PINENTRY_DEFAULT should be used. \ref
836 * PWMD_PINENTRY_CLOSE should be used to terminate the pinentry process when
837 * the pinentry is no longer needed.
839 * \return 0 on success or an error.
841 LIBPWMD_API gpg_error_t
pwmd_getpin(pwm_t
*pwm
, const char *filename
,
842 char **result
, pwmd_pinentry_t which
);
845 /*! \brief Open a file on the pwmd server.
847 * This will send the OPEN command to the server.
849 * \param pwm A handle.
850 * \param filename The filename to open. The \a filename is not a full path
851 * but the data file only.
852 * \return 0 on success or an error code.
855 LIBPWMD_API gpg_error_t
pwmd_open(pwm_t
*pwm
, const char *filename
);
858 /*! \brief Open a file on the pwmd server by using a server inquire.
860 * This is a convenience function to the OPEN command using \ref
861 * pwmd_inquire() in that it passes the OPEN options that were set with \ref
862 * pwmd_setopt() for you. It uses the specified callback function to retreive
865 * \note Only the passphrase should be sent when using this function and not
866 * any filename argument. That argument will be sent automatically when using
869 * \note Pinentry is disabled when using this function.
871 * \param pwm A handle.
872 * \param filename The filename to open. The \a filename is not a full path
873 * but the data file only.
874 * \param func A callback function of type \ref pwmd_inquire_cb_t which sets
875 * the passphrase to be sent. This acts as a normal \ref pwmd_inquire() would.
876 * \param user A user data pointer passed to the callback function \a func.
877 * \return 0 on success or an error code.
878 * \see \ref PWMD_OPTION_BASE64
880 LIBPWMD_API gpg_error_t
pwmd_open_inquire(pwm_t
*pwm
, const char *filename
,
881 pwmd_inquire_cb_t func
, void *user
);
884 /*! \brief Open a file on the pwmd server using a local pinentry.
886 * This will send the OPEN command to the server like \ref pwmd_open() but
887 * will use the local pinentry and not pwmd's pinentry.
891 * \note This pinentry method is not thread safe. It needs to set a couple of
892 * global variables for the pinentry timeout to work properly.
894 * \param pwm A handle.
895 * \param filename The filename to open. The \a filename is not a full path
896 * but the data file only.
897 * \return 0 on success or an error code.
898 * \retval GPG_ERR_PIN_BLOCKED Another handle is using the local pinentry.
901 LIBPWMD_API gpg_error_t
pwmd_open2(pwm_t
*pwm
, const char *filename
);
904 /*! \brief Open a file on the pwmd server asynchronously (fork method).
906 * This is kind of a hybrid of \ref pwmd_open2() and \ref pwmd_open_async().
907 * It will use the local pinentry asynchronously and also do the OPEN command
914 * \param pwm A handle.
915 * \param filename The filename to open. The \a filename is not a full path
916 * but the data file only.
917 * \return 0 on success or an error code.
918 * \see pwmd_process(), \ref pinentry
920 LIBPWMD_API gpg_error_t
pwmd_open_async2(pwm_t
*pwm
, const char *filename
);
923 /*! \brief Open a file on the pwmd server (asynchronously).
925 * This will send the OPEN command to the pwmd server. The difference from
926 * \ref pwmd_open() is that it will not block if a pinentry is needed for
931 * \param pwm A handle.
932 * \param filename The filename to open. The \a filename is not a full path
933 * but the data file only.
934 * \return 0 on success or an error code.
935 * \see pwmd_process(), \ref pinentry
937 LIBPWMD_API gpg_error_t
pwmd_open_async(pwm_t
*pwm
, const char *filename
);
940 /*! \brief Process an asynchronous function.
942 * After an asynchronous function has been called and has returned
943 * successfully, this function must be called to process the command and
944 * retrieve the result and return value.
946 * This function may also be called when not in a command to check for pending
947 * status messages sent from the server or to process a pending line.
949 * \param pwm A handle.
950 * \param[out] rc Set to the return code of the original command after
951 * ASYNC_DONE has been returned. This value must be checked to determine if
952 * the command succeeded.
953 * \param[out] result Set to the result of the command when \a rc is 0. Note
954 * that not all commands return a result.
955 * \retval ASYNC_DONE The command has completed. \a rc should be checked to
956 * determine if the command was successful or not.
957 * \retval ASYNC_PROCESS The command is still running and this function should
959 * \see pwmd_get_fds(), pwmd_pending_line()
961 LIBPWMD_API pwmd_async_t
pwmd_process(pwm_t
*pwm
, gpg_error_t
*rc
,
965 /*! \brief Save a file on the pwmd server.
967 * This will send the SAVE command.
969 * \param pwm A handle.
970 * \return 0 on success or an error code.
973 LIBPWMD_API gpg_error_t
pwmd_save(pwm_t
*pwm
);
976 /*! \brief Save a file on the pwmd server by using a server inquire.
978 * This is a convenience function to the SAVE command using \ref
979 * pwmd_inquire() in that it passes the SAVE options that were set with \ref
980 * pwmd_setopt() for you. It uses the specified callback function to retreive
983 * \note Pinentry is disabled when using this function.
985 * \param pwm A handle.
986 * \param func A callback function of type \ref pwmd_inquire_cb_t which sets
987 * the passphrase to be sent. This acts as a normal \ref pwmd_inquire() would.
988 * \param user A user data pointer passed to the callback function \a func.
989 * \return 0 on success or an error code.
990 * \see \ref PWMD_OPTION_BASE64
992 LIBPWMD_API gpg_error_t
pwmd_save_inquire(pwm_t
*pwm
, pwmd_inquire_cb_t func
,
996 /*! \brief Save a file on the pwmd server using the local pinentry.
998 * This will send the SAVE command like \ref pwmd_save() but will use a local
999 * pinentry and not pwmd's pinentry.
1001 * \param pwm A handle.
1002 * \return 0 on success or an error code.
1003 * \see \ref pinentry
1005 LIBPWMD_API gpg_error_t
pwmd_save2(pwm_t
*pwm
);
1008 /*! \brief Save a file on the pwmd server asynchronously (fork method).
1010 * This is kind of a hybrid of \ref pwmd_save2() and \ref pwmd_save_async().
1011 * It will use the local pinentry asynchronously and also do the SAVE command
1016 * \param pwm A handle.
1017 * \return 0 on success or an error code.
1018 * \see pwmd_process(), \ref pinentry
1020 LIBPWMD_API gpg_error_t
pwmd_save_async2(pwm_t
*pwm
);
1023 /*! \brief Save changes to a file on the pwmd server (asynchronously).
1025 * This will send the SAVE command to the pwmd server. The difference from
1026 * \ref pwmd_save() is that it will not block if a pinentry is needed for
1031 * \param pwm A handle.
1032 * \return 0 on success or an error code.
1033 * \see pwmd_process(), \ref pinentry
1035 LIBPWMD_API gpg_error_t
pwmd_save_async(pwm_t
*pwm
);
1038 /*! \brief Send a command to the pwmd server.
1040 * Sends a command to the pwmd server. You should avoid sending the BYE
1041 * command here because the assuan context will be freed and bad things will
1042 * happen. Use \ref pwmd_close() instead. For commands that use an INQUIRE to
1043 * send data to the server (STORE and IMPORT), \ref pwmd_inquire() must be
1044 * used and not this function.
1046 * \param pwm A handle.
1047 * \param[out] result The result of the command when successful which must be
1048 * freed with \ref pwmd_free().
1049 * \param cmd The command to send and any following arguments.
1050 * \return 0 on success or an error code.
1052 * \note Not all commands return a result.
1054 LIBPWMD_API gpg_error_t
pwmd_command(pwm_t
*pwm
, char **result
,
1055 const char *cmd
, ...);
1058 /*! \brief Send a command to the pwmd server.
1060 * Like \ref pwmd_command() but uses an argument pointer instead.
1062 * \param pwm A handle.
1063 * \param[out] result The result of the command when successful which must be
1064 * freed with \ref pwmd_free().
1065 * \param cmd The command to send.
1066 * \param ap The arguments to \a cmd.
1067 * \return 0 on success or an error code.
1069 * \note Not all commands return a result.
1071 LIBPWMD_API gpg_error_t
pwmd_command_ap(pwm_t
*pwm
, char **result
,
1072 const char *cmd
, va_list ap
);
1075 /*! \brief Send data to a pwmd server.
1077 * This lets commands that use an INQUIRE (STORE and IMPORT) send the data
1078 * to the server. Use this function rather than \ref pwmd_command() for these
1081 * \param pwm A handle.
1082 * \param cmd The \ref pwmd(1) command to send including any options.
1083 * \param func A callback function of type \ref pwmd_inquire_cb_t which sets
1084 * the data to be sent.
1085 * \param user A user data pointer passed to the callback function \a func.
1086 * \return 0 on success or an error code.
1088 * \see pwmd_inquire_cb_t
1090 LIBPWMD_API gpg_error_t
pwmd_inquire(pwm_t
*pwm
, const char *cmd
,
1091 pwmd_inquire_cb_t func
, void *user
);
1094 /*! \brief Close a connection to the pwmd server.
1096 * This will close the connection but keep any previously set options for the
1099 * \param pwm A handle.
1100 * \return 0 on success or an error code.
1101 * \see \ref pwmd_close()
1103 LIBPWMD_API gpg_error_t
pwmd_disconnect(pwm_t
*pwm
);
1106 /*! \brief Close a handle.
1108 * This will close the connection to a pwmd server and free any resources
1109 * associated with it.
1111 * \param pwm A handle.
1113 * \see \ref pwmd_disconnect(), \ref pwmd_new()
1115 LIBPWMD_API
void pwmd_close(pwm_t
*pwm
);
1118 /*! \brief The type of connection a handle has.
1120 * Useful when you want to know what kind of connection a handle has.
1122 * \param pwm A handle.
1123 * \param[out] type The type of socket.
1124 * \return 0 on success or an error code.
1125 * \see pwmd_connect_url()
1127 LIBPWMD_API gpg_error_t
pwmd_socket_type(pwm_t
*pwm
, pwmd_socket_t
*type
);
1130 /*! \brief Free a previously allocated pointer.
1132 * Use this function to free resources allocated by the other libpwmd memory
1133 * functions. Do not use it to free allocations made by other allocators.
1135 * The difference between the standard free() and this function is that
1136 * this one will zero out the contents of the pointer before freeing it.
1138 * \param ptr The pointer to deallocate.
1140 * \see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(),
1141 * pwmd_process(), pwmd_command()
1143 LIBPWMD_API
void pwmd_free(void *ptr
);
1146 /*! \brief A wrapper around malloc.
1148 * Like malloc(), but lets libpwmd keep track of the pointer.
1150 * \param size The number of bytes to allocate.
1151 * \return A newly allocated pointer or NULL if there wasn't enough memory.
1152 * \see malloc(3), pwmd_free()
1154 LIBPWMD_API
void *pwmd_malloc(size_t size
);
1157 /*! \brief A wrapper around calloc().
1159 * Like calloc(), but lets libpwmd keep track of the pointer.
1161 * \param nmemb The number of elements to allocate.
1162 * \param size The number of bytes to allocate.
1163 * \return A newly allocated pointer or NULL if there wasn't enough memory.
1164 * \see calloc(3), pwmd_free()
1166 LIBPWMD_API
void *pwmd_calloc(size_t nmemb
, size_t size
);
1169 /*! \brief A wrapper around realloc().
1171 * Like realloc(), but lets libpwmd keep track of the pointer.
1173 * \note This function will try and allocate the entire \a size before freeing
1174 * the original pointer and returning the new one.
1176 * \param ptr The pointer to reallocate.
1177 * \param size The new number of bytes to allocate.
1178 * \return A newly allocated pointer or NULL if there wasn't enough memory.
1179 * \see realloc(3), pwmd_free()
1181 LIBPWMD_API
void *pwmd_realloc(void *ptr
, size_t size
);
1184 /*! \brief A wrapper around strdup().
1186 * Like strdup(), but lets libpwmd keep track of the pointer.
1188 * \param str The string to duplicate.
1189 * \return A newly allocated character pointer or NULL if there wasn't
1191 * \see strdup(3), pwmd_free()
1193 LIBPWMD_API
char *pwmd_strdup(const char *str
);
1196 /*! \brief Duplicate a formatted string.
1198 * Like \ref sprintf(3) but returns an allocated string.
1200 * \param fmt The formatted string and any following arguments.
1201 * \return A newly allocated character pointer or NULL if there wasn't
1205 LIBPWMD_API
char *pwmd_strdup_printf(const char *fmt
, ...);
1208 /*! \def EPWMD_NO_FILE
1210 * \brief No data file has been opened.
1212 * Some commands don't require an open data file but most do.
1214 #define EPWMD_NO_FILE GPG_ERR_USER_1
1217 /*! \def EPWMD_LIBXML_ERROR
1219 * \brief libxml2 error.
1221 * This can be a memory allocation error or a parse error. The details of the
1222 * error cannot be obtained with libpwmd. You'd have to connect to the pwmd
1223 * socket and do the command directly to get the actual error.
1225 #define EPWMD_LIBXML_ERROR GPG_ERR_USER_2
1228 /*! \def EPWMD_FILE_MODIFIED
1230 * \brief The data file has been modified.
1232 * Rather than process the next command this error is returned to prevent
1233 * overwriting new data which may have been saved by another client.
1235 #define EPWMD_FILE_MODIFIED GPG_ERR_USER_3
1243 * \brief libgpg-error error code offset.
1245 * If you use your own libgpg-error codes then this should be the base of
1248 #define EPWMD_MAX GPG_ERR_USER_4
1251 /*! \brief Return a description of an error code.
1253 * \param code The error code to describe.
1254 * \return A character description of the error code.
1255 * \see pwmd_strerror_r()
1257 LIBPWMD_API
const char *pwmd_strerror(gpg_error_t code
);
1260 /*! \brief Return a description of an error code (thread-safe).
1262 * This is a thread-safe version of \ref pwmd_strerror().
1264 * \param code The error code to describe.
1265 * \param[out] buf An allocated buffer to hold the error description.
1266 * \param size The size of the allocated buffer \a buf.
1268 * \retval 0 Success.
1269 * \retval ERANGE \a size was not large enough to hold the entire description
1270 * and \a buf is set to the truncated error string.
1272 LIBPWMD_API
int pwmd_strerror_r(gpg_error_t code
, char *buf
, size_t size
);