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