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