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