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