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