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