src/libpwmd.h.in

   1 /* vim:tw=78:ts=8:sw=4:set ft=c:  */
   2 /*
   3     Copyright (C) 2006-2009 Ben Kibbey <bjk@luxsci.net>
   4
   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.
   9
  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.
  14
  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
  18 */
  19 /*! \headerfile libpwmd.h
  20  *
  21  * libpwmd is a library making it easy for applications to use the pwmd
  22  * server. Pwmd version 1.11 or later is required; either locally or remotely.
  23  */
  24
  25 /*! \section ssh SSH Details
  26  *
  27  * A remote connection to a pwmd server is possible by using an SSH channel
  28  * which spawns a shell and executes a proxy server that connects to the pwmd
  29  * local UNIX domain socket. Authentication is done by using SSH public key
  30  * (see \ref ssh-keygen(1)) authentication and verifying the host key against
  31  * a local file containing SHA1 hashes of known hosts. It's a lot like how the
  32  * standard OpenSSH does things only the known_hosts file is in a different
  33  * format.
  34  *
  35  * The server hash can be had by using \ref pwmd_get_hostkey() and storing the
  36  * result in a file. This file is then used as the \a known_hosts argument to
  37  * the SSH connection functions.
  38  *
  39  * Here's an example \ref authorized_keys(5) entry. The hash portion should be
  40  * the same as the contents of the generated \ref ssh-keygen(1) \a
  41  * identity.pub file which is passed as a parameter to the SSH connection
  42  * functions:
  43  *
  44  * \code
  45  * command="socat gopen:$HOME/.pwmd/socket -" <hash> ...
  46  * \endcode
  47  *
  48  * \note Only an SSH identity without a passphrase is supported. For now
  49  * anyway. This is a limitation of libssh2 (version 1.1 as of this writing).
  50  *
  51  * \x11
  52  */
  53
  54 /*! \section pinentry Pinentry Details
  55  *
  56  * \ref pinentry(1) is a program that prompts the user for input which is
  57  * normally a passphrase or a confirmation. libpwmd can use this program
  58  * either locally (X11 forwarding is not yet supported) or have the pwmd
  59  * server use it's pinentry to retrieve a passphrase when needed. How this is
  60  * done depends what function gets called and whether the pwmd connection is
  61  * over an SSH channel.
  62  *
  63  * There are a few options that tell pinentry how and where to prompt for a
  64  * needed passphrase. See the \ref pwmd_option_t section for details. These
  65  * options are not sent (when using pwmd's pinentry, not the local one) until
  66  * the pinentry is needed.
  67  *
  68  * If using a local pinentry by calling \ref pwmd_open2(), \ref pwmd_save2(),
  69  * \ref pwmd_open_async2() or pwmd_save_async2(), libpwmd will send the
  70  * command "OPTION PINENTRY=0" to the pwmd server. This is needed so pwmd wont
  71  * try to launch it's own pinentry on passphrase or confirmation failure. So
  72  * you may need to reset this option manually depending on your needs;
  73  * especially when changing pinentry methods when doing a save (the passphrase
  74  * may be set as empty since the remote pinentry is disabled!).
  75  *
  76  * Some pinentry options can also be specified in a local configuration file
  77  * \a "~/.pwmd/pinentry.conf". These options are initial values for each
  78  * pinentry invokation (not retries) and may be changed by setting the
  79  * appropriate \ref pwmd_option_t. Each option and value is separated with a
  80  * '=' on a single line. Unrecognized options are ignored. Here are the
  81  * recognized options:
  82  *
  83  * \param PATH The full path to the location of the pinentry binary.
  84  * \param DISPLAY The X11 display to use.
  85  * \param TTYNAME The full path to the tty that pinentry should prompt on.
  86  * \param TTYTYPE The terminal type of the tty which is required if DISPLAY is
  87  * not set.
  88  *
  89  * \filepath
  90  *
  91  * \note The initial values for the pinentry TTY, TERM and DISPLAY are set
  92  * during \ref pwmd_new() depending on the current environment. They may need
  93  * to be reset as needed.
  94  *
  95  * \note After establishing an SSH connection, the pwmd pinentry is disabled
  96  * by sending the command "OPTION PINENTRY=0". This is needed because there
  97  * currently isn't a way to have the remote pinentry use the local display.
  98  * You must be careful to use either a local pinentry or set a passphrase
  99  * manually with \ref pwmd_setopt() when a passphrase is required or needed.
 100  *
 101  * \x11
 102  *
 103  * \see \ref ssh
 104  */
 105
 106 /*! \section Errors
 107  *
 108  * libpwmd uses libgpg-error for all error codes.  Some are user defined
 109  * GPG_ERR_USER_N codes, but most are reused from the existing ones.  Error
 110  * codes can be described by using \ref pwmd_strerror(), or the thread-safe
 111  * \ref pwmd_strerror_r().
 112  *
 113  * \note Internally, some error codes are a bitmask of an error source. In
 114  * order to simplify the result codes, libpwmd strips any error source from
 115  * the error code before returning it.
 116  */
 117
 118 /*! \section example Example Client
 119  *
 120  * The following example will list the element tree of the data file specified
 121  * in the first command line argument.
 122  *
 123  * \code
 124  * #include <stdio.h>
 125  * #include <stdlib.h>
 126  * #include <libpwmd.h>
 127  *
 128  * int main(int argc, char **argv)
 129  * {
 130  *     pwm_t *pwm = pwmd_new(NULL);
 131  *     gpg_error_t rc = pwmd_connect(pwm, NULL);
 132  *     char *result;
 133  *
 134  *     if (!rc) {
 135  *         rc = pwmd_open(pwm, argv[1]);
 136  *
 137  *         if (!rc) {
 138  *             rc = pwmd_command(pwm, &result, "%s", "LIST");
 139  *
 140  *             if (!rc) {
 141  *                 printf("%s", result);
 142  *                 pwmd_free(result);
 143  *             }
 144  *         }
 145  *     }
 146  *
 147  *     pwmd_close(pwm);
 148  *
 149  *     if (rc)
 150  *         fprintf(stderr, "ERR: %s\n", pwmd_strerror(rc));
 151  *
 152  *     exit(rc ? 1 : 0);
 153  * }
 154  * \endcode
 155  */
 156
 157 /*! \file */
 158 #ifndef LIBPWMD_H
 159 #define LIBPWMD_H
 160
 161 #include <gpg-error.h>
 162 #include <stdarg.h>
 163
 164 #ifdef __cplusplus
 165 extern "C" {
 166 #endif
 167
 168 /*! \def LIBPWMD_VERSION
 169  *
 170  * The version of this library.
 171  */
 172 #define LIBPWMD_VERSION 0x@VER_MAJOR@@VER_COMPAT@@VER_PATCH@
 173
 174
 175 struct pwm_s;
 176 /*! \typedef pwm_t
 177  *
 178  * When a handle is mentioned in this documentation it is a pointer of this
 179  * type. A new handle is created with \ref pwmd_new().
 180  */
 181 typedef struct pwm_s pwm_t;
 182
 183
 184 /*! \typedef pwmd_async_t
 185  *
 186  * The return code of \ref pwmd_process() which is used for all asynchronous
 187  * commands.
 188  */
 189 typedef enum {
 190     /*! \internal */
 191     ASYNC_INIT,
 192
 193     /*! \ref pwmd_process() should be called again. */
 194     ASYNC_PROCESS,
 195
 196     /*! The command has completed. The result code should be checked for an
 197      * error. */
 198     ASYNC_DONE,
 199 } pwmd_async_t;
 200
 201
 202 /*! \typedef pwmd_ip_version_t
 203  *
 204  * The value of the option \ref PWMD_OPTION_IP_VERSION which is set with \ref
 205  * pwmd_setopt().
 206  */
 207 typedef enum {
 208     /*! Try both IPv6 and IPv4 addresses. Note that IPv6 is tried first. */
 209     PWMD_IP_ANY,
 210
 211     /*! Only try IPv4. */
 212     PWMD_IPV4,
 213
 214     /*! Only try IPv6. */
 215     PWMD_IPV6
 216 } pwmd_ip_version_t;
 217
 218
 219 /*! \def PWMD_FD_READABLE
 220  * \hideinitializer
 221  *
 222  * Set when the file descriptor is readable.
 223  */
 224 #define PWMD_FD_READABLE        0x01
 225
 226
 227 /*! \def PWMD_FD_WRITABLE
 228  * \hideinitializer
 229  *
 230  * Set when the file descriptor is writable.
 231  */
 232 #define PWMD_FD_WRITABLE        0x02
 233
 234
 235 /*!
 236  * For use with \ref pwmd_get_fds().
 237  */
 238 typedef struct {
 239     /*! The file descriptor. */
 240     int fd;
 241
 242     /*! A bitmask of \ref PWMD_FD_READABLE and \ref PWMD_FD_WRITABLE. */
 243     unsigned flags;
 244 } pwmd_fd_t;
 245
 246
 247 /*! \typedef pwmd_socket_t
 248  *
 249  * For use with \ref pwmd_socket_type().
 250  */
 251 typedef enum {
 252     /*! A UNIX domain socket. */
 253     PWMD_SOCKET_UDS,
 254
 255     /*! An SSH connection over a TCP socket. */
 256     PWMD_SOCKET_SSH
 257 } pwmd_socket_t;
 258
 259
 260 /*! \typedef pwmd_pinentry_t
 261  *
 262  * For use with \ref pwmd_getpin().
 263  */
 264 typedef enum {
 265     /*! When opening a file. */
 266     PWMD_PINENTRY_OPEN,
 267
 268     /*! When opening a file failed. */
 269     PWMD_PINENTRY_OPEN_FAILED,
 270
 271     /*! When saving a file. */
 272     PWMD_PINENTRY_SAVE,
 273
 274     /*! For passphrase confirmation. */
 275     PWMD_PINENTRY_SAVE_CONFIRM
 276 } pwmd_pinentry_t;
 277
 278
 279 /*! \typedef pwmd_passphrase_cb_t
 280  *
 281  * The value of the option \ref PWMD_OPTION_PASSPHRASE_CB which is set with
 282  * \ref pwmd_setopt().
 283  *
 284  * \param user A user data pointer which is set with \ref
 285  * PWMD_OPTION_PASSPHRASE_DATA.
 286  * \param[out] passphrase The passphrase which may be an empty string or NULL.
 287  * It is not modified by libpwmd but must remain allocated for as long as it
 288  * is needed.
 289  * \return 0 on success or an error code which will cause a command to fail.
 290  */
 291 typedef gpg_error_t (*pwmd_passphrase_cb_t)(void *user, char **passphrase);
 292
 293
 294 /*! \typedef pwmd_status_cb_t
 295  *
 296  * The value of the option \ref PWMD_OPTION_STATUS_CB which is set with \ref
 297  * pwmd_setopt().
 298  *
 299  * \param user A user data pointer which is set with \ref
 300  * PWMD_OPTION_STATUS_DATA.
 301  * \param line The status message line received from the server.
 302  * \return 0 on success or an error code which will cause a command to fail.
 303  */
 304 typedef int (*pwmd_status_cb_t)(void *user, const char *line);
 305
 306
 307 /*! \typedef pwmd_inquire_cb_t
 308  *
 309  * This is a callback function that gets passed to \ref pwmd_inquire(). It is
 310  * used for sending data to the server for commands that need to reply to an
 311  * INQUIRE server response (STORE and IMPORT). The reason for this callback is
 312  * to let the client send as many bytes as it wants rather than the entire
 313  * chunk at once.  It gets called during an internal \ref assuan_transact()
 314  * from an internal inquire callback function which in turn calls this
 315  * function by looping over its return value.
 316  *
 317  * \param user The user data pointer passed to \ref pwmd_inquire().
 318  * \param cmd The same as the \a cmd argument to \ref pwmd_inquire().
 319  * \param rc The result of the last internal call to \ref assuan_send_data()
 320  * which did the sending of the data to the pwmd server. On the first call to
 321  * this callback it's value will always be 0 since no data has been sent yet.
 322  * \param[out] data The next chunk of data to send or NULL.
 323  * \param[out] len The length of \a data or 0.
 324  *
 325  * \retval 0 There is more data to be sent.
 326  * \retval GPG_ERR_EOF No need to call this function again, the current
 327  * \a line is the last to send.
 328  * \retval code Any other error code which will terminate the INQUIRE.
 329  *
 330  * \note The sent data is processed line-per-line. The line is either newline
 331  * terminated or is buffered until ASSUAN_LINELENGTH bytes have been
 332  * allocated. Any remaining bytes are sent after the INQUIRE has finished.
 333  */
 334 typedef gpg_error_t (*pwmd_inquire_cb_t)(void *user, const char *cmd,
 335         gpg_error_t rc, char **data, size_t *len);
 336
 337
 338 /*! \enum pwmd_option_t
 339  *
 340  * libpwmd options which are set with \ref pwmd_setopt().
 341  *
 342  * \filepath
 343  */
 344 typedef enum {
 345     /*! A custom passphrase retrieval function which, when set, will be used
 346      * instead of \ref pinentry(1). This function will not be used if opening
 347      * a file and the passphrase is cached on the server or the file is a new
 348      * one. The value of this option should be a \ref pwmd_passphrase_cb_t.
 349      *
 350      * \note An empty string as the passphrase is allowed.
 351      */
 352     PWMD_OPTION_PASSPHRASE_CB,
 353
 354     /*! User supplied data which is passed to the custom passphrase function.
 355      * */
 356     PWMD_OPTION_PASSPHRASE_DATA,
 357
 358     /*! A string to use as the passphrase when doing an open or save. When not
 359      * NULL, this option has precedence over \ref PWMD_OPTION_PASSPHRASE_CB.
 360      *
 361      * \note An empty string as the passphrase is allowed.
 362      */
 363     PWMD_OPTION_PASSPHRASE,
 364
 365     /*! An integer value that specifies the number of tries before \ref
 366      * pinentry(1) will give up when opening a file with the wrong supplied
 367      * passphrase. The default is 3.
 368      *
 369      * \note This option has no effect when trying to save a file. The user
 370      * must either cancel the pinentry causing the save to fail or enter the
 371      * correct passphrase during passphrase confirmation.
 372      */
 373     PWMD_OPTION_PINENTRY_TRIES,
 374
 375     /*! A character string value which specifies the full path of the \ref
 376      * pinentry(1) binary. For the local \ref pinentry(1) method, the default
 377      * is specified at compile time.
 378      *
 379      * \see \ref pinentry
 380      */
 381     PWMD_OPTION_PINENTRY_PATH,
 382
 383     /*! A value which specifies the full path to the TTY that \ref pinentry(1)
 384      * will use to prompt on. When set and no DISPLAY is available, \ref
 385      * PWMD_OPTION_PINENTRY_TERM must also be set.
 386      *
 387      * \see \ref pinentry
 388      */
 389     PWMD_OPTION_PINENTRY_TTY,
 390
 391     /*! A value which specifies the terminal type (e.g., vt100) that \ref
 392      * pinentry(1) will use when no X11 display is available.
 393      *
 394      * \see \ref pinentry
 395      */
 396     PWMD_OPTION_PINENTRY_TERM,
 397
 398     /*! A value which specifies the X11 display that \ref pinentry(1) will
 399      * use.
 400      *
 401      * \x11
 402      *
 403      * \see \ref pinentry
 404      */
 405     PWMD_OPTION_PINENTRY_DISPLAY,
 406
 407     /*! A character string that \ref pinentry(1) will use in it's dialog
 408      * window.
 409      */
 410     PWMD_OPTION_PINENTRY_TITLE,
 411
 412     /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
 413     PWMD_OPTION_PINENTRY_PROMPT,
 414
 415     /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
 416     PWMD_OPTION_PINENTRY_DESC,
 417
 418     /*! For \ref pinentry(1) localization. */
 419     PWMD_OPTION_PINENTRY_LC_CTYPE,
 420
 421     /*! \copydoc PWMD_OPTION_PINENTRY_LC_CTYPE */
 422     PWMD_OPTION_PINENTRY_LC_MESSAGES,
 423
 424     /*! An integer value that specifies the number of seconds \ref pinentry(1)
 425      * will wait for input before timing out and aborting the current command.
 426      * If 0, then no timeout will be used. The default is 30.
 427      */
 428     PWMD_OPTION_PINENTRY_TIMEOUT,
 429
 430     /*! A function of type \ref pwmd_status_cb_t that will process status
 431      * messages received from the pwmd server.
 432      */
 433     PWMD_OPTION_STATUS_CB,
 434
 435     /*! A user data pointer which is passed to the status message function. */
 436     PWMD_OPTION_STATUS_DATA,
 437
 438     /*! The IP version of type \ref pwmd_ip_version_t that \ref
 439      * pwmd_ssh_connect() and \ref pwmd_ssh_connect_async() will use when
 440      * connecting to the remote pwmd server. The default is \ref PWMD_IP_ANY.
 441      *
 442      * \pre_conn_req
 443      */
 444     PWMD_OPTION_IP_VERSION,
 445 } pwmd_option_t;
 446
 447
 448 /*! \brief Initialize the library.
 449  *
 450  * This function must be the first function called in the library before any
 451  * others. It sets up the memory allocators and internationalization among
 452  * other things.
 453  *
 454  * \return 0 on success or an error code.
 455  */
 456 gpg_error_t pwmd_init(void);
 457
 458
 459 /*! \brief Creates a new handle.
 460  *
 461  * Creates a new handle for use with the other functions.
 462  *
 463  * \param name If not NULL, the name of the application. The application name
 464  * is sent to the pwmd server after successfully connecting.
 465  *
 466  * \return a new handle or NULL if there was not enough memory.
 467  */
 468 pwm_t *pwmd_new(const char *name)
 469     __attribute__ ((warn_unused_result));
 470
 471
 472 /*! \brief Connect to a local pwmd server.
 473  *
 474  * Connects to a local unix domain socket.
 475  *
 476  * \param pwm A handle.
 477  * \param path The socket path to connect to. If NULL, then a default of
 478  * \a "~/.pwmd/socket" will be used.
 479  * \return 0 on success or an error code.
 480  * \filepath
 481  * \see pwmd_ssh_connect(), pwmd_ssh_connect_async(), pwmd_disconnect()
 482  */
 483 gpg_error_t pwmd_connect(pwm_t *pwm, const char *path)
 484     __attribute__ ((warn_unused_result));
 485
 486
 487 /*! \brief Establish a remote connection to a pwmd server.
 488  *
 489  * Connects to a pwmd server over an SSH channel.
 490  *
 491  * \param pwm A handle.
 492  * \param host The hostname to connect to.
 493  * \param port The port or -1 for the default of 22.
 494  * \param identity The SSH identity file to use for authentication. This
 495  * should specify the private key. The public key is assumed to be \a
 496  * identity.pub.
 497  * \param user The username on the SSH server to login as. If NULL then
 498  * invoking username will be used.
 499  * \param known_hosts A file containing the public SSH server key hash in SHA1
 500  * format which may be obtained with \ref pwmd_get_hostkey().
 501  * \return 0 on success or an error code.
 502  * \filepath
 503  * \see pwmd_ssh_connect_async(), \ref PWMD_OPTION_IP_VERSION,
 504  * pwmd_disconnect(), \ref ssh
 505  */
 506 gpg_error_t pwmd_ssh_connect(pwm_t *pwm, const char *host, int port,
 507         const char *identity, const char *user, const char *known_hosts)
 508     __attribute__ ((warn_unused_result));
 509
 510
 511 /*! \brief Establish a remote connection to a pwmd server (asynchronously).
 512  *
 513  * This is a variant of \ref pwmd_ssh_connect() that will not block while doing
 514  * DNS lookups or while connecting.
 515  *
 516  * \process
 517  *
 518  * \param pwm A handle.
 519  * \param host The hostname to connect to.
 520  * \param port The port or -1 for the default of 22.
 521  * \param identity The SSH identity file to use for authentication. This
 522  * should specify the private key. The public key is assumed to be \a
 523  * identity.pub.
 524  * \param user The username on the SSH server to login as. If NULL, the
 525  * invoking username will be used.
 526  * \param known_hosts A file containing the public SSH server key hash in SHA1
 527  * format which may be obtained with \ref pwmd_get_hostkey().
 528  * \return 0 on success or an error code.
 529  * \filepath
 530  * \see pwmd_process(), \ref PWMD_OPTION_IP_VERSION, pwmd_disconnect(),
 531  * \ref ssh
 532  */
 533 gpg_error_t pwmd_ssh_connect_async(pwm_t *pwm, const char *host, int port,
 534         const char *identity, const char *user, const char *known_hosts)
 535     __attribute__ ((warn_unused_result));
 536
 537
 538 /*! \brief Establish a connection by parsing a URL.
 539  *
 540  * This allows for connecting to a pwmd server by parsing the given URL
 541  * string. Whether the connection is to a remote or local server depends on
 542  * the contents:
 543  * \code
 544  * socket://[path/to/local/socket]
 545  *
 546  * or
 547  *
 548  * ssh[46]://[username@]hostname[:port],identity,known_hosts
 549  * \endcode
 550  *
 551  * The parameters in square brackets are optional and if not specified then
 552  * defaults will be used. If neither socket specification is matched, the
 553  * \a url is assumed to be a socket://.
 554  *
 555  * \param pwm A handle.
 556  * \param url The string to parse.
 557  * \filepath
 558  * \return 0 on success or an error code.
 559  * \see \ref pwmd_socket_type(), pwmd_disconnect()
 560  */
 561 gpg_error_t pwmd_connect_url(pwm_t *pwm, const char *url)
 562     __attribute__ ((warn_unused_result));
 563
 564
 565 /*! \brief Establish a connection by parsing a URL (asynchronously).
 566  *
 567  * This allows for connecting to a pwmd server by parsing the given URL
 568  * string. Whether the connection is to a remote or local server depends on
 569  * the contents:
 570  * \code
 571  * socket://[path/to/local/socket]
 572  *
 573  * or
 574  *
 575  * ssh[46]://[username@]hostname[:port],identity,known_hosts
 576  * \endcode
 577  *
 578  * The parameters in square brackets are optional and if not specified then
 579  * defaults will be used. If neither socket specification is matched, the
 580  * \a url is assumed to be a socket://.
 581  *
 582  * \process
 583  *
 584  * \param pwm A handle.
 585  * \param url The string to parse.
 586  * \filepath
 587  * \return 0 on success or an error code.
 588  * \see \ref pwmd_socket_type(), pwmd_disconnect()
 589  */
 590 gpg_error_t pwmd_connect_url_async(pwm_t *pwm, const char *url)
 591     __attribute__ ((warn_unused_result));
 592
 593
 594 /*! \brief Retrieve a remote SSH host key.
 595  *
 596  * This key is needed for host verification of the remote pwmd server. You
 597  * should be sure that the remote host is really the host that your wanting to
 598  * connect to and not subject to a man-in-the-middle attack.
 599  *
 600  * \param pwm A handle.
 601  * \param host The hostname to connect to.
 602  * \param port The port or -1 for the default of 22.
 603  * \param[out] result The SHA1 sum of the server host key which must be freed
 604  * with \ref pwmd_free().
 605  * \return 0 on success or an error code.
 606  * \see pwmd_get_hostkey_async(), \ref ssh
 607  */
 608 gpg_error_t pwmd_get_hostkey(pwm_t *pwm, const char *host, int port,
 609         char **result)
 610     __attribute__ ((warn_unused_result));
 611
 612
 613 /*! \brief Retrieve a remote SSH host key (asynchronously).
 614  *
 615  * This key is needed for host verification of the remote pwmd server. You
 616  * should be sure that the remote host is really the host that your wanting to
 617  * connect to and not subject to a man-in-the-middle attack.
 618  *
 619  * \process
 620  *
 621  * \param pwm A handle.
 622  * \param host The hostname to connect to.
 623  * \param port The port or -1 for the default of 22.
 624  * \return 0 on success or an error code.
 625  * \see pwmd_get_hostkey(), \ref pwmd_process(), \ref ssh
 626  */
 627 gpg_error_t pwmd_get_hostkey_async(pwm_t *pwm, const char *host, int port)
 628     __attribute__ ((warn_unused_result));
 629
 630
 631 /*! \brief Get the associated file descriptor(s) for a handle.
 632  *
 633  * This function lets the application manually poll the available file
 634  * descriptors for the specified handle. It should be called after each
 635  * asynchronous function call and after each call to \ref pwmd_process() since
 636  * the polled file descriptors may have been closed since the previous call.
 637  *
 638  * After returning, \a n_fds is set to the number of available file
 639  * descriptors which are stored in \a fds. The .flags member of \ref pwmd_fd_t
 640  * specifies what can be monitored and is a bitmask of \ref PWMD_FD_READABLE
 641  * and \ref PWMD_FD_WRITABLE. When ready, \ref pwmd_process() should be
 642  * called.
 643  *
 644  * \param pwm A handle.
 645  * \param[out] fds Set to the file descriptor(s) of the associated handle.
 646  * \param[out] n_fds Initially the size of \a fds then updated to the number
 647  * of available file descriptors which are stored in \a fds.
 648  * \retval 0 on success or an error code.
 649  * \retval GPG_ERR_ERANGE There are more file descriptors than the amount
 650  * specified in \a n_fds. \a fds and \a n_fds are still usable though.
 651  * \see pwmd_process()
 652  */
 653 gpg_error_t pwmd_get_fds(pwm_t *pwm, pwmd_fd_t *fds, int *n_fds)
 654     __attribute__ ((warn_unused_result));
 655
 656
 657 /*! \brief Check for a unparsed buffered line.
 658  *
 659  * A buffered line is a line that was read from the server but has not yet
 660  * been processed. This function determines if there is such a line.
 661  *
 662  * \param pwm A handle.
 663  * \retval 0 if there is a pending line.
 664  * \retval GPG_ERR_NO_DATA if there is no pending line.
 665  * \see pwmd_process()
 666  */
 667 gpg_error_t pwmd_pending_line(pwm_t *pwm)
 668     __attribute__ ((warn_unused_result));
 669
 670
 671 /*! \brief Set handle options.
 672  *
 673  * See \ref pwmd_option_t for option specific details.
 674  *
 675  * \param pwm A handle.
 676  * \param opt The option and following value.
 677  * \return 0 on success or an error code.
 678  */
 679 gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...)
 680     __attribute__ ((warn_unused_result));
 681
 682
 683 /*! \brief Launch a local pinentry.
 684  *
 685  * Does not send any command to the server.
 686  *
 687  * \param pwm A handle.
 688  * \param filename The filename to use in the pinentry dialog strings.
 689  * \param[out] result The entered value in the pinentry dialog which should be
 690  * freed with \ref pwmd_free().
 691  * \param which For setting the pinentry dialog strings. \ref pwmd_setopt()
 692  * may also be used to override the defaults.
 693  *
 694  * \return 0 on success or an error.
 695  */
 696 gpg_error_t pwmd_getpin(pwm_t *pwm, const char *filename, char **result,
 697         pwmd_pinentry_t which)
 698     __attribute__ ((warn_unused_result));
 699
 700
 701 /*! \brief Open a file on the pwmd server.
 702  *
 703  * This will send the OPEN command to the server.
 704  *
 705  * \param pwm A handle.
 706  * \param filename The filename to open. The \a filename is not a full path
 707  * but the data file only.
 708  * \return 0 on success or an error code.
 709  * \see \ref pinentry
 710  */
 711 gpg_error_t pwmd_open(pwm_t *pwm, const char *filename)
 712     __attribute__ ((warn_unused_result));
 713
 714 /*! \brief Open a file on the pwmd server using a local pinentry.
 715  *
 716  * This will send the OPEN command to the server like \ref pwmd_open() but
 717  * will use the local pinentry and not pwmd's pinentry.
 718  *
 719  * \sigalrm
 720  *
 721  * \note This pinentry method is not thread safe. It needs to set a couple of
 722  * global variables for the pinentry timeout to work properly.
 723  *
 724  * \param pwm A handle.
 725  * \param filename The filename to open. The \a filename is not a full path
 726  * but the data file only.
 727  * \return 0 on success or an error code.
 728  * \retval GPG_ERR_PIN_BLOCKED Another handle is using the local pinentry.
 729  * \see \ref pinentry
 730  */
 731 gpg_error_t pwmd_open2(pwm_t *pwm, const char *filename)
 732     __attribute__ ((warn_unused_result));
 733
 734
 735 /*! \brief Open a file on the pwmd server asynchronously (fork method).
 736  *
 737  * This is kind of a hybrid of \ref pwmd_open2() and \ref pwmd_open_async().
 738  * It will use the local pinentry asynchronously and also do the OPEN command
 739  * asynchronously.
 740  *
 741  * \process
 742  *
 743  * \sigalrm
 744  *
 745  * \param pwm A handle.
 746  * \param filename The filename to open. The \a filename is not a full path
 747  * but the data file only.
 748  * \return 0 on success or an error code.
 749  * \see pwmd_process(), \ref pinentry
 750  */
 751 gpg_error_t pwmd_open_async2(pwm_t *pwm, const char *filename)
 752     __attribute__ ((warn_unused_result));
 753
 754
 755 /*! \brief Open a file on the pwmd server (asynchronously).
 756  *
 757  * This will send the OPEN command to the pwmd server. The difference from
 758  * \ref pwmd_open() is that it will not block if a pinentry is needed for
 759  * passphrase input.
 760  *
 761  * \process
 762  *
 763  * \param pwm A handle.
 764  * \param filename The filename to open. The \a filename is not a full path
 765  * but the data file only.
 766  * \return 0 on success or an error code.
 767  * \see pwmd_process(), \ref pinentry
 768  */
 769 gpg_error_t pwmd_open_async(pwm_t *pwm, const char *filename)
 770     __attribute__ ((warn_unused_result));
 771
 772
 773 /*! \brief Process an asynchronous function.
 774  *
 775  * After an asynchronous function has been called and has returned
 776  * successfully, this function must be called to process the command and
 777  * retrieve the result and return value.
 778  *
 779  * This function may also be called when not in a command to check for pending
 780  * status messages sent from the server or to process a pending line.
 781  *
 782  * \param pwm A handle.
 783  * \param[out] rc Set to the return code of the original command after
 784  * ASYNC_DONE has been returned. This value must be checked to determine if
 785  * the command succeeded.
 786  * \param[out] result Set to the result of the command when \a rc is 0. Note
 787  * that not all commands return a result.
 788  * \retval ASYNC_DONE The command has completed. \a rc should be checked to
 789  * determine if the command was successful or not.
 790  * \retval ASYNC_PROCESS The command is still running and this function should
 791  * be called again.
 792  * \see pwmd_get_fds(), pwmd_pending_line()
 793  */
 794 pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc, char **result)
 795     __attribute__ ((warn_unused_result));
 796
 797
 798 /*! \brief Save a file on the pwmd server.
 799  *
 800  * This will send the SAVE command.
 801  *
 802  * \param pwm A handle.
 803  * \return 0 on success or an error code.
 804  * \see \ref pinentry
 805  */
 806 gpg_error_t pwmd_save(pwm_t *pwm)
 807     __attribute__ ((warn_unused_result));
 808
 809
 810 /*! \brief Save a file on the pwmd server using the local pinentry.
 811  *
 812  * This will send the SAVE command like \ref pwmd_save() but will use a local
 813  * pinentry and not pwmd's pinentry.
 814  *
 815  * \param pwm A handle.
 816  * \return 0 on success or an error code.
 817  * \see \ref pinentry
 818  */
 819 gpg_error_t pwmd_save2(pwm_t *pwm)
 820     __attribute__ ((warn_unused_result));
 821
 822
 823 /*! \brief Save a file on the pwmd server asynchronously (fork method).
 824  *
 825  * This is kind of a hybrid of \ref pwmd_save2() and \ref pwmd_save_async().
 826  * It will use the local pinentry asynchronously and also do the SAVE command
 827  * asynchronously.
 828  *
 829  * \process
 830  *
 831  * \param pwm A handle.
 832  * \return 0 on success or an error code.
 833  * \see pwmd_process(), \ref pinentry
 834  */
 835 gpg_error_t pwmd_save_async2(pwm_t *pwm)
 836     __attribute__ ((warn_unused_result));
 837
 838
 839 /*! \brief Save changes to a file on the pwmd server (asynchronously).
 840  *
 841  * This will send the SAVE command to the pwmd server. The difference from
 842  * \ref pwmd_save() is that it will not block if a pinentry is needed for
 843  * passphrase input.
 844  *
 845  * \process
 846  *
 847  * \param pwm A handle.
 848  * \return 0 on success or an error code.
 849  * \see pwmd_process(), \ref pinentry
 850  */
 851 gpg_error_t pwmd_save_async(pwm_t *pwm)
 852     __attribute__ ((warn_unused_result));
 853
 854
 855 /*! \brief Send a command to the pwmd server.
 856  *
 857  * Sends a command to the pwmd server. You should avoid sending the BYE
 858  * command here because the assuan context will be freed and bad things will
 859  * happen. Use \ref pwmd_close() instead. For commands that use an INQUIRE to
 860  * send data to the server (STORE and IMPORT), \ref pwmd_inquire() must be
 861  * used and not this function.
 862  *
 863  * \param pwm A handle.
 864  * \param[out] result The result of the command when successful which must be
 865  * freed with \ref pwmd_free().
 866  * \param cmd The command to send and any following arguments.
 867  * \return 0 on success or an error code.
 868  *
 869  * \note Not all commands return a result.
 870  */
 871 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...)
 872     __attribute__ ((warn_unused_result));
 873
 874
 875 /*! \brief Send a command to the pwmd server.
 876  *
 877  * Like \ref pwmd_command() but uses an argument pointer instead.
 878  *
 879  * \param pwm A handle.
 880  * \param[out] result The result of the command when successful which must be
 881  * freed with \ref pwmd_free().
 882  * \param cmd The command to send.
 883  * \param ap The arguments to \a cmd.
 884  * \return 0 on success or an error code.
 885  *
 886  * \note Not all commands return a result.
 887  */
 888 gpg_error_t pwmd_command_ap(pwm_t *pwm, char **result, const char *cmd,
 889         va_list ap)
 890     __attribute__ ((warn_unused_result));
 891
 892
 893 /*! \brief Send data to a pwmd server.
 894  *
 895  * This lets commands that use an INQUIRE (STORE and IMPORT) send the data
 896  * to the server. Use this function rather than \ref pwmd_command() for these
 897  * pwmd commands.
 898  *
 899  * \param pwm A handle.
 900  * \param cmd The command (without arguments) to send that uses an INQUIRE.
 901  * \param func A callback function of type \ref pwmd_inquire_cb_t which sets
 902  * the data to be sent.
 903  * \param user A user data pointer passed to the callback function \a func.
 904  * \return 0 on success or an error code.
 905  *
 906  * \see pwmd_inquire_cb_t
 907  */
 908 gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_cb_t func,
 909         void *user)
 910     __attribute__ ((warn_unused_result));
 911
 912
 913 /*! \brief Close a connection to the pwmd server.
 914  *
 915  * This will close the connection but keep any previously set options for the
 916  * specified handle.
 917  *
 918  * \param pwm A handle.
 919  * \return 0 on success or an error code.
 920  * \see \ref pwmd_close()
 921  */
 922 gpg_error_t pwmd_disconnect(pwm_t *pwm)
 923     __attribute__ ((warn_unused_result));
 924
 925
 926 /*! \brief Close a handle.
 927  *
 928  * This will close the connection to a pwmd server and free any resources
 929  * associated with it.
 930  *
 931  * \param pwm A handle.
 932  * \return Nothing.
 933  * \see \ref pwmd_disconnect(), \ref pwmd_new()
 934  */
 935 void pwmd_close(pwm_t *pwm);
 936
 937
 938 /*! \brief The type of connection a handle has.
 939  *
 940  * Useful when you want to know what kind of connection a handle has.
 941  *
 942  * \param pwm A handle.
 943  * \param[out] type The type of socket.
 944  * \return 0 on success or an error code.
 945  * \see pwmd_connect_url()
 946  */
 947 gpg_error_t pwmd_socket_type(pwm_t *pwm, pwmd_socket_t *type)
 948     __attribute__ ((warn_unused_result));
 949
 950
 951 /*! \brief Free a previously allocated pointer.
 952  *
 953  * Use this function to free resources allocated by the other libpwmd memory
 954  * functions. Do not use it to free allocations made by other allocators.
 955  *
 956  * The difference between the standard free() and this function is that
 957  * this one will zero out the contents of the pointer before freeing it.
 958  *
 959  * \param ptr The pointer to deallocate.
 960  * \return Nothing.
 961  * \see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(),
 962  * pwmd_process(), pwmd_command()
 963  */
 964 void pwmd_free(void *ptr);
 965
 966
 967 /*! \brief A wrapper around malloc.
 968  *
 969  * Like malloc(), but lets libpwmd keep track of the pointer.
 970  *
 971  * \param size The number of bytes to allocate.
 972  * \return A newly allocated pointer or NULL if there wasn't enough memory.
 973  * \see malloc(3), pwmd_free()
 974  */
 975 void *pwmd_malloc(size_t size)
 976     __attribute__ ((warn_unused_result));
 977
 978
 979 /*! \brief A wrapper around calloc().
 980  *
 981  * Like calloc(), but lets libpwmd keep track of the pointer.
 982  *
 983  * \param nmemb The number of elements to allocate.
 984  * \param size The number of bytes to allocate.
 985  * \return A newly allocated pointer or NULL if there wasn't enough memory.
 986  * \see calloc(3), pwmd_free()
 987  */
 988 void *pwmd_calloc(size_t nmemb, size_t size)
 989     __attribute__ ((warn_unused_result));
 990
 991
 992 /*! \brief A wrapper around realloc().
 993  *
 994  * Like realloc(), but lets libpwmd keep track of the pointer.
 995  *
 996  * \note This function will try and allocate the entire \a size before freeing
 997  * the original pointer and returning the new one.
 998  *
 999  * \param ptr The pointer to reallocate.
1000  * \param size The new number of bytes to allocate.
1001  * \return A newly allocated pointer or NULL if there wasn't enough memory.
1002  * \see realloc(3), pwmd_free()
1003  */
1004 void *pwmd_realloc(void *ptr, size_t size)
1005     __attribute__ ((warn_unused_result));
1006
1007
1008 /*! \brief A wrapper around strdup().
1009  *
1010  * Like strdup(), but lets libpwmd keep track of the pointer.
1011  *
1012  * \param str The string to duplicate.
1013  * \return A newly allocated character pointer or NULL if there wasn't
1014  * enough memory.
1015  * \see strdup(3), pwmd_free()
1016  */
1017 char *pwmd_strdup(const char *str)
1018     __attribute__ ((warn_unused_result));
1019
1020 /*! \brief Duplicate a formatted string.
1021  *
1022  * Like \ref sprintf(3) but returns an allocated string.
1023  *
1024  * \param fmt The formatted string and any following arguments.
1025  * \return A newly allocated character pointer or NULL if there wasn't
1026  * enough memory.
1027  * \see pwmd_free()
1028  */
1029 char *pwmd_strdup_printf(const char *fmt, ...)
1030     __attribute__ ((warn_unused_result));
1031
1032 /*! \def EPWMD_ERROR
1033  *  \hideinitializer
1034  *
1035  * A general pwmd error with no suitable description.
1036  */
1037 #define EPWMD_ERROR             GPG_ERR_USER_1
1038
1039
1040 /*! \def EPWMD_MAX_SLOTS
1041  *  \hideinitializer
1042  *
1043  * The maximum number of cache slots has been reached. There is no available
1044  * slot for a new file.
1045  */
1046 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
1047
1048
1049 /*! \def EPWMD_LOOP
1050  *  \hideinitializer
1051  *
1052  * A recursion loop was detected while processing a "target" attribute.
1053  */
1054 #define EPWMD_LOOP              GPG_ERR_USER_3
1055
1056
1057 /*! \def EPWMD_NO_FILE
1058  *  \hideinitializer
1059  *
1060  * A command required an open file but no file has yet been opened.
1061  */
1062 #define EPWMD_NO_FILE           GPG_ERR_USER_4
1063
1064
1065 /*! \def EPWMD_LIBXML_ERROR
1066  *  \hideinitializer
1067  *
1068  * An XML parse or other libxml2 error occurred.
1069  */
1070 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_5
1071
1072
1073 /*! \def EPWMD_FILE_MODIFIED
1074  *  \hideinitializer
1075  *
1076  * The data file was modified either externally or by another client while
1077  * trying to process a command.
1078  */
1079 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_6
1080
1081
1082 /*! \def EPWMD_MAX
1083  *  \hideinitializer
1084  * \if cond1
1085  * \internal
1086  * \endif
1087  */
1088 #define EPWMD_MAX               GPG_ERR_USER_7
1089
1090
1091 /*! \brief Return a description of an error code.
1092  *
1093  * \param code The error code to describe.
1094  * \return A character description of the error code.
1095  * \see pwmd_strerror_r()
1096  */
1097 const char *pwmd_strerror(gpg_error_t code)
1098     __attribute__ ((warn_unused_result));
1099
1100
1101 /*! \brief Return a description of an error code (thread-safe).
1102  *
1103  * This is a thread-safe version of \ref pwmd_strerror().
1104  *
1105  * \param code The error code to describe.
1106  * \param[out] buf An allocated buffer to hold the error description.
1107  * \param size The size of the allocated buffer \a buf.
1108  *
1109  * \retval 0 Success.
1110  * \retval ERANGE \a size was not large enough to hold the entire description
1111  * and \a buf is set to the truncated error string.
1112  */
1113 int pwmd_strerror_r(gpg_error_t code, char *buf, size_t size);
1114
1115 #ifdef __cplusplus
1116 }
1117 #endif
1118
1119 #endif