src/libpwmd.h.in

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