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  * \param pwm A handle.
 513  * \param filename The filename to open.
 514  * \return 0 on success or an error code.
 515  * \see \ref pinentry
 516  */
 517 gpg_error_t pwmd_open2(pwm_t *pwm, const char *filename)
 518     __attribute__ ((warn_unused_result));
 519
 520
 521 /*! \brief Open a file on the pwmd server asynchronously (fork method).
 522  *
 523  * This will send the OPEN command to the pwmd server. The difference from
 524  * \ref pwmd_open() is that it will not block if a pinentry is needed for
 525  * passphrase input.
 526  *
 527  * The difference from \ref pwmd_open_async() is that libpwmd will \ref fork()
 528  * a pinentry process rather than have pwmd use it's pinentry method. This may
 529  * be useful if the passphrase isn't cached on a remote pwmd server and a
 530  * remote \ref pinentry(1) is not possible.
 531  *
 532  * \ref pwmd_process() should be called until the command completes.
 533  *
 534  * \param pwm A handle.
 535  * \param filename The filename to open.
 536  * \return 0 on success or an error code.
 537  * \see pwmd_process(), \ref pinentry
 538  */
 539 gpg_error_t pwmd_open_async2(pwm_t *pwm, const char *filename)
 540     __attribute__ ((warn_unused_result));
 541
 542
 543 /*! \brief Open a file on the pwmd server asynchronously.
 544  *
 545  * This will send the OPEN command to the pwmd server. The difference from
 546  * \ref pwmd_open() is that it will not block if a pinentry is needed for
 547  * passphrase input.
 548  *
 549  * \ref pwmd_process() should be called until the command completes.
 550  *
 551  * \param pwm A handle.
 552  * \param filename The filename to open.
 553  * \return 0 on success or an error code.
 554  * \see pwmd_process(), \ref pinentry
 555  */
 556 gpg_error_t pwmd_open_async(pwm_t *pwm, const char *filename)
 557     __attribute__ ((warn_unused_result));
 558
 559
 560 /*! \brief Process an asynchronous function.
 561  *
 562  * After an asynchronous function has been called and has returned
 563  * successfully, this function must be called to process the command to
 564  * retrieve the result or return value.
 565  *
 566  * This function may also be called when not in a command to check for pending
 567  * status messages sent from the server or to process a pending line.
 568  *
 569  * \param pwm A handle.
 570  * \param rc Set to the return code of the command after ASYNC_DONE is
 571  * returned. This value must be checked to determine if the command succeeded.
 572  * \param[out] result Set to the result of the command when \a rc is 0. Note
 573  * that not all commands return a result.
 574  * \retval ASYNC_DONE The command has completed. \a rc should be checked to
 575  * determine if the command was successful or not.
 576  * \retval ASYNC_PROCESS The command is still running and this function should
 577  * be called again.
 578  * \see pwmd_get_fd(), pwmd_get_fd2(), pwmd_pending_line()
 579  */
 580 pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc, char **result)
 581     __attribute__ ((warn_unused_result));
 582
 583
 584 /*! \brief Save a file on the pwmd server.
 585  *
 586  * This will send the SAVE command.
 587  *
 588  * \param pwm A handle.
 589  * \return 0 on success or an error code.
 590  * \see \ref pinentry
 591  */
 592 gpg_error_t pwmd_save(pwm_t *pwm)
 593     __attribute__ ((warn_unused_result));
 594
 595
 596 /*! \brief Save a file on the pwmd server using the local pinentry.
 597  *
 598  * This will send the SAVE command like \ref pwmd_save() but will use a local
 599  * pinentry and not pwmd's pinentry.
 600  *
 601  * \param pwm A handle.
 602  * \return 0 on success or an error code.
 603  * \see \ref pinentry
 604  */
 605 gpg_error_t pwmd_save2(pwm_t *pwm)
 606     __attribute__ ((warn_unused_result));
 607
 608
 609 /*! \brief Save a file on the pwmd server asynchronously (fork method).
 610  *
 611  * This will send the SAVE command to the pwmd server. The difference from
 612  * \ref pwmd_save() is that it will not block if a pinentry is needed for
 613  * passphrase input.
 614  *
 615  * The difference from \ref pwmd_save_async() is that libpwmd will \ref fork()
 616  * a pinentry process rather than have pwmd use it's pinentry method. This may
 617  * be useful if the passphrase isn't cached on a remote pwmd server and a
 618  * remote \ref pinentry(1) is not possible.
 619  *
 620  * \ref pwmd_process() should be called until the command completes.
 621  *
 622  * \param pwm A handle.
 623  * \return 0 on success or an error code.
 624  * \see pwmd_process(), \ref pinentry
 625  */
 626 gpg_error_t pwmd_save_async2(pwm_t *pwm)
 627     __attribute__ ((warn_unused_result));
 628
 629
 630 /*! \brief Save changes to a file on the pwmd server asynchronously.
 631  *
 632  * This will send the SAVE command to the pwmd server. The difference from
 633  * \ref pwmd_save() is that it will not block if a pinentry is needed for
 634  * passphrase input.
 635  *
 636  * \ref pwmd_process() should be called until the command completes.
 637  *
 638  * \param pwm A handle.
 639  * \return 0 on success or an error code.
 640  * \see pwmd_process(), \ref pinentry
 641  */
 642 gpg_error_t pwmd_save_async(pwm_t *pwm)
 643     __attribute__ ((warn_unused_result));
 644
 645
 646 /*! \brief Send a command to the pwmd server.
 647  *
 648  * Sends a command to the pwmd server. You should avoid sending the BYE
 649  * command here because the assuan context will be freed and bad things will
 650  * happen. Use \ref pwmd_close() instead. For commands that use an INQUIRE to
 651  * send data to the server (STORE and IMPORT), \ref pwmd_inquire() should be
 652  * used and not this function.
 653  *
 654  * \param pwm A handle.
 655  * \param[out] result The result of the command when successful and which must
 656  * be freed with \ref pwmd_free(). Note that not all commands return a result.
 657  * \param cmd The command to send.
 658  * \param ... The arguments to \a cmd.
 659  * \return 0 on success or an error code.
 660  */
 661 gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...)
 662     __attribute__ ((warn_unused_result));
 663
 664
 665 /*! \brief Send a command to the pwmd server.
 666  *
 667  * Like \ref pwmd_command() but uses an argument pointer instead.
 668  *
 669  * \param pwm A handle.
 670  * \param[out] result The result of the command when successful which must be
 671  * freed with \ref pwmd_free(). Note that not all commands return a result.
 672  * \param cmd The command to send.
 673  * \param ap The arguments to \a cmd.
 674  * \return 0 on success or an error code.
 675  */
 676 gpg_error_t pwmd_command_ap(pwm_t *pwm, char **result, const char *cmd,
 677         va_list ap)
 678     __attribute__ ((warn_unused_result));
 679
 680
 681 /*! \brief Send data to a pwmd server.
 682  *
 683  * This lets commands that use an INQUIRE (STORE and IMPORT) send the data
 684  * to the server. Use this function rather than \ref pwmd_command() for these
 685  * commands.
 686  *
 687  * \param pwm A handle.
 688  * \param cmd The command to send that uses an INQUIRE.
 689  * \param func A callback function which sets the data to be sent.
 690  * \param user A user data pointer passed to the callback function \a func.
 691  * \return 0 on success or an error code.
 692  *
 693  * \see pwmd_inquire_cb_t
 694  */
 695 gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_cb_t func,
 696         void *user)
 697     __attribute__ ((warn_unused_result));
 698
 699
 700 /*! \brief Close a handle.
 701  *
 702  * This will close the connection to a pwmd server and free any resources
 703  * associated with it.
 704  *
 705  * \param pwm A handle.
 706  * \return Nothing.
 707  */
 708 void pwmd_close(pwm_t *pwm);
 709
 710
 711 /*! \brief Free a previously allocated pointer.
 712  *
 713  * Use this function to free resources allocated by the other libpwmd memory
 714  * functions. Do not use it to free your own allocations.
 715  *
 716  * The difference between the standard free() and this function is that
 717  * this one will zero out the contents of the pointer before freeing it.
 718  *
 719  * \param ptr The pointer to deallocate.
 720  * \return Nothing.
 721  * \see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(),
 722  * pwmd_process(), pwmd_command()
 723  */
 724 void pwmd_free(void *ptr);
 725
 726
 727 /*! \brief A wrapper around malloc.
 728  *
 729  * Like malloc(), but lets libpwmd keep track of the pointer.
 730  *
 731  * \param size The number of bytes to allocate.
 732  * \return A newly allocated pointer or NULL if there wasn't enough memory.
 733  * \see malloc(3), pwmd_free()
 734  */
 735 void *pwmd_malloc(size_t size)
 736     __attribute__ ((warn_unused_result));
 737
 738
 739 /*! \brief A wrapper around calloc().
 740  *
 741  * Like calloc(), but lets libpwmd keep track of the pointer.
 742  *
 743  * \param nmemb The number of bytes to allocate.
 744  * \param size The number of bytes to allocate.
 745  * \return A newly allocated pointer or NULL if there wasn't enough memory.
 746  * \see calloc(3), pwmd_free()
 747  */
 748 void *pwmd_calloc(size_t nmemb, size_t size)
 749     __attribute__ ((warn_unused_result));
 750
 751
 752 /*! \brief A wrapper around realloc().
 753  *
 754  * Like realloc(), but lets libpwmd keep track of the pointer. Note that this
 755  * function will try and allocate the entire \a size before freeing the
 756  * original pointer and returning the new one.
 757  *
 758  * \param ptr The pointer to reallocate.
 759  * \param size The new number of bytes to allocate.
 760  * \return A newly allocated pointer or NULL if there wasn't enough memory.
 761  * \see realloc(3), pwmd_free()
 762  */
 763 void *pwmd_realloc(void *ptr, size_t size)
 764     __attribute__ ((warn_unused_result));
 765
 766
 767 /*! \brief A wrapper around strdup().
 768  *
 769  * Like strdup(), but lets libpwmd keep track of the pointer.
 770  *
 771  * \param str The string to duplicate.
 772  * \return A newly allocated character pointer or NULL if there wasn't
 773  * enough memory.
 774  * \see strdup(3), pwmd_free()
 775  */
 776 char *pwmd_strdup(const char *str)
 777     __attribute__ ((warn_unused_result));
 778
 779 /*! \brief Duplicate a formatted string.
 780  *
 781  * Like sprintf() but returns an allocated string.
 782  *
 783  * \param fmt The formatted string.
 784  * \param ... Any format arguments to the string.
 785  * \return A newly allocated character pointer or NULL if there wasn't
 786  * enough memory.
 787  * \see pwmd_free()
 788  */
 789 char *pwmd_strdup_printf(const char *fmt, ...)
 790     __attribute__ ((warn_unused_result));
 791
 792 /*! \def EPWMD_ERROR
 793  *  \hideinitializer
 794  *
 795  * A general pwmd error with no suitable description.
 796  */
 797 #define EPWMD_ERROR             GPG_ERR_USER_1
 798
 799
 800 /*! \def EPWMD_MAX_SLOTS
 801  *  \hideinitializer
 802  *
 803  * The maximum number of cache slots has been reached. There is no available
 804  * slot for a new file.
 805  */
 806 #define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
 807
 808
 809 /*! \def EPWMD_LOOP
 810  *  \hideinitializer
 811  *
 812  * A recursion loop was detected while processing a "target" attribute.
 813  */
 814 #define EPWMD_LOOP              GPG_ERR_USER_3
 815
 816
 817 /*! \def EPWMD_NO_FILE
 818  *  \hideinitializer
 819  *
 820  * A command required an open file, but no file has yet been opened.
 821  */
 822 #define EPWMD_NO_FILE           GPG_ERR_USER_4
 823
 824
 825 /*! \def EPWMD_LIBXML_ERROR
 826  *  \hideinitializer
 827  *
 828  * An XML parse or other libxml2 error occurred.
 829  */
 830 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_5
 831
 832
 833 /*! \def EPWMD_FILE_MODIFIED
 834  *  \hideinitializer
 835  *
 836  * The data file was modified either externally or by another another client
 837  * while trying to process a command.
 838  */
 839 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_6
 840
 841
 842 /*! \def EPWMD_MAX
 843  *  \hideinitializer
 844  * \if cond1
 845  * \endif
 846  */
 847 #define EPWMD_MAX               GPG_ERR_USER_7
 848
 849
 850 /*! \brief Return a description of an error code.
 851  *
 852  * \param code The error code to describe.
 853  * \return A character description of the error code.
 854  * \see pwmd_strerror_r()
 855  */
 856 const char *pwmd_strerror(gpg_error_t code)
 857     __attribute__ ((warn_unused_result));
 858
 859
 860 /*! \brief Return a description of an error code (thread-safe).
 861  *
 862  * This is a thread-safe version of \ref pwmd_strerror().
 863  *
 864  * \param code The error code to describe.
 865  * \param[out] buf An allocated buffer to hold the error description.
 866  * \param size The size of the allocated buffer \a buf.
 867  *
 868  * \retval 0 Success.
 869  * \retval ERANGE \a size was not large enough to hold the entire description
 870  * and \a buf is set to the truncated error string.
 871  */
 872 int pwmd_strerror_r(gpg_error_t code, char *buf, size_t size);
 873
 874 #ifdef __cplusplus
 875 }
 876 #endif
 877
 878 #endif