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