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