src/libpwmd.h.in

   1 /* vim:tw=78:ts=8:sw=4:set ft=c:  */
   2 /*
   3     Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2015
   4     Ben Kibbey <bjk@luxsci.net>
   5
   6     This file is part of libpwmd.
   7
   8     Libpwmd is free software: you can redistribute it and/or modify
   9     it under the terms of the GNU General Public License as published by
  10     the Free Software Foundation, either version 2 of the License, or
  11     (at your option) any later version.
  12
  13     Libpwmd is distributed in the hope that it will be useful,
  14     but WITHOUT ANY WARRANTY; without even the implied warranty of
  15     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16     GNU General Public License for more details.
  17
  18     You should have received a copy of the GNU General Public License
  19     along with Libpwmd.  If not, see <http://www.gnu.org/licenses/>.
  20 */
  21 /*! \headerfile libpwmd.h
  22  *
  23  * libpwmd is a library making it easy for applications to use the pwmd
  24  * server. Pwmd version 3.0 or later is required; either locally or remotely.
  25  */
  26
  27 /*! \section threads Threads
  28  *
  29  * \ref libpwmd should be thread-safe on a per handle bases. Meaning that only
  30  * one thread should access a \ref pwm_t handle at a time.
  31  */
  32
  33 /*! \section remote Remote Connection Details
  34  *
  35  * There are two methods of connecting to a remote pwmd server: over SSH
  36  * and over TLS.
  37  *
  38  * Connections over SSH are done by creating an SSH channel to spawn a
  39  * shell that executes a proxy server to connect to the pwmd local
  40  * Unix Domain Socket. Authentication is done by using SSH public key
  41  * (see \ref ssh-keygen(1)) authentication and verifying the host key
  42  * against a local OpenSSH known hosts formatted file.
  43  *
  44  * An unknown servers public key can be added to a known hosts file after user
  45  * confirmation by setting the callback function \ref pwmd_knownhost_cb_t
  46  * before connecting to the unknown host.
  47  *
  48  * On the server side you'll need a proxy server to connect to the pwmd
  49  * server. Below is an example of an \ref authorized_keys(5) entry that will
  50  * do this.  The \a public_key portion should be the same as the contents of
  51  * the \ref ssh-keygen(1) \a identity.pub file generated on the client
  52  * machine. The private key should be passed as the \a identity parameter to
  53  * \ref pwmd_connect():
  54  *
  55  * \code
  56  * command="socat UNIX-CONNECT:$HOME/.pwmd/socket -" <public_key> ...
  57  * \endcode
  58  *
  59  * \note Only an SSH identity without a passphrase is supported. For now
  60  * anyway. This is a limitation of libssh2 (version 1.2.8 as of this writing).
  61  *
  62  * \version 6.0.3
  63  * The first version to use the OpenSSH known hosts file format exclusively.
  64  * Earlier versions used only an SHA1 hash of the host key.
  65  *
  66  * Pwmd itself can accept TLS connections so no proxy program is
  67  * needed as is when using SSH. Like SSH connections, TLS connections
  68  * are created with \ref pwmd_connect(). You will need to generate a
  69  * client key and X509 certificate and then sign it with the same
  70  * certificate authority (CA) that the pwmd server certificate was
  71  * signed with.
  72  *
  73  * Certificates are similar to SSH public and private keys but a little harder
  74  * to setup correctly. See the \ref certtool(1) (recommended) and \ref
  75  * openssl(1) manual pages for details.
  76  */
  77
  78 /*! \section pinentry Pinentry Details
  79  *
  80  * \ref pinentry(1) is a program that prompts the user for input which is
  81  * normally a passphrase or a confirmation. libpwmd can use this program
  82  * either locally (X11 forwarding is not yet supported) or have the pwmd
  83  * server or gpg-agent use it's pinentry to retrieve a passphrase when
  84  * needed.
  85  *
  86  * There are a few options that tell pinentry how and where to prompt for a
  87  * needed passphrase. See the \ref pwmd_option_t section for details. These
  88  * options are sent to pwmd during \ref pwmd_open(), \ref pwmd_passwd() and
  89  * \ref pwmd_save() and only when pinentry use has not been disabled and when
  90  * not over a remote connnection.
  91  *
  92  * \note The initial values for the pinentry TTY, TERM and DISPLAY are set
  93  * during \ref pwmd_new() depending on the current environment. They can be
  94  * reset or changed as needed.
  95  *
  96  * \note After establishing a remote connection, pwmd's pinentry is disabled
  97  * by passing the "--no-pinentry" option to the OPEN protocol command during
  98  * \ref pwmd_open() since X11 forwarding has not been implemented. A local
  99  * pinentry will be used in the case of a remote connection.
 100  *
 101  * \see \ref remote
 102  */
 103
 104 /*! \section Errors
 105  *
 106  * libpwmd uses libgpg-error for all error codes.  Error codes can be
 107  * described by using \ref gpg_strerror(), or the thread-safe \ref
 108  * gpg_strerror_r().
 109  *
 110  * \note libgpg-error returns an error code as a bitmask of an error source
 111  * and the error code. Determining the error source can help you find where
 112  * the error occured, beit from \ref pinentry(1), \ref gpg-agent(1), \ref
 113  * libgcrypt, \ref pwmd(1) or \ref libpwmd(3). pwmd uses the \ref
 114  * GPG_ERR_SOURCE_USER_1 error source and libpwmd uses \ref
 115  * GPG_ERR_SOURCE_USER_2. To find the error source of an error code the \ref
 116  * gpg-error(1) command line utility may be of use. Also see the \ref
 117  * libgpg-error documentation for error code manipulation.
 118  */
 119
 120 /*! \file */
 121 #ifndef LIBPWMD_H
 122 #define LIBPWMD_H
 123
 124 #ifndef LIBPWMD_API
 125 #define LIBPWMD_API
 126 #endif
 127
 128 #ifdef GPG_ERR_SOURCE_DEFAULT
 129 #error "GPG_ERR_SOURCE_DEFAULT already defined."
 130 #else
 131 #define GPG_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_2
 132 #endif
 133 #include <gpg-error.h>
 134 #include <stdarg.h>
 135
 136 #ifdef __cplusplus
 137 extern "C"
 138 {
 139 #endif
 140
 141 /*! \def LIBPWMD_VERSION
 142  * \brief Version information.
 143  *
 144  * The version of this library.
 145  */
 146 #define LIBPWMD_VERSION 0x@VER_MAJOR_HEX@@VER_MINOR_HEX@@VER_PATCH_HEX@
 147
 148
 149 /*! \def LIBPWMD_VERSION_MAJOR
 150  * \brief Version information.
 151  *
 152  * The major release number of this library.
 153  */
 154 #define LIBPWMD_VERSION_MAJOR @VER_MAJOR@
 155
 156
 157 /*! \def LIBPWMD_VERSION_MINOR
 158  * \brief Version information.
 159  *
 160  * The minor release number of this library.
 161  */
 162 #define LIBPWMD_VERSION_MINOR @VER_MINOR@
 163
 164
 165 /*! \def LIBPWMD_VERSION_PATCH
 166  * \brief Version information.
 167  *
 168  * The patch level of this library.
 169  */
 170 #define LIBPWMD_VERSION_PATCH @VER_PATCH@
 171
 172
 173 /*! \def LIBPWMD_VERSION_STR
 174  * \brief Version information.
 175  *
 176  * A string representation of the version of this library.
 177  */
 178 #define LIBPWMD_VERSION_STR @VER_STRING@
 179
 180
 181 /*! \brief Returns this version of libpwmd.
 182  *
 183  * As a string.
 184  * \return A string.
 185  */
 186 LIBPWMD_API const char *pwmd_version ();
 187
 188
 189 struct pwm_s;
 190 /*! \typedef pwm_t
 191  * \brief A libpwmd handle.
 192  *
 193  * When a pwmd handle or context is mentioned in this documentation it
 194  * is a pointer of this type. A new handle is created with \ref
 195  * pwmd_new().
 196  */
 197 typedef struct pwm_s pwm_t;
 198
 199
 200 /*! \typedef pwmd_socket_t
 201  * \brief The type of socket a handle is connected to.
 202  *
 203  * For use with \ref pwmd_socket_type().
 204  */
 205 typedef enum
 206 {
 207   /*! A local UNIX domain socket. */
 208   PWMD_SOCKET_LOCAL,
 209
 210   /*! An SSH channel over a TCP socket. */
 211   PWMD_SOCKET_SSH,
 212
 213   /*! A TLS connection over a TCP socket. */
 214   PWMD_SOCKET_TLS
 215 } pwmd_socket_t;
 216
 217
 218 /*! \typedef pwmd_pinentry_t
 219  * \brief Local pinentry commands and not pwmd pinentry.
 220  *
 221  * These determine what prompt a local or fork()'ed pinentry uses. For use
 222  * with \ref pwmd_getpin().
 223  */
 224 typedef enum
 225 {
 226   /*! When opening a file. */
 227   PWMD_PINENTRY_OPEN,
 228
 229   /*! When opening a file failed due to a bad passphrase. */
 230   PWMD_PINENTRY_OPEN_FAILED,
 231
 232   /*! When saving a file. */
 233   PWMD_PINENTRY_SAVE,
 234
 235   /*! For passphrase confirmation. */
 236   PWMD_PINENTRY_SAVE_CONFIRM,
 237
 238   /*! When saving a file and passphrase confirmation failed. */
 239   PWMD_PINENTRY_SAVE_FAILED,
 240
 241   /*! For confirmation of a user-defined prompt. */
 242   PWMD_PINENTRY_CONFIRM,
 243
 244   /*! For the default or user defined string set with \ref
 245    * PWMD_OPTION_PINENTRY_DESC. */
 246   PWMD_PINENTRY_USER,
 247
 248   /*! To terminate the pinentry process created with \ref pwmd_getpin(). */
 249   PWMD_PINENTRY_CLOSE
 250 } pwmd_pinentry_t;
 251
 252
 253 /*! \typedef pwmd_status_cb_t
 254  * \brief Process status messages.
 255  *
 256  * The value of the option \ref PWMD_OPTION_STATUS_CB which is set with \ref
 257  * pwmd_setopt().
 258  *
 259  * \param user A user data pointer which is set with \ref
 260  * PWMD_OPTION_STATUS_DATA.
 261  * \param line The status message line received from the server.
 262  * \return 0 on success or an error code which will cause a command to fail.
 263  */
 264 typedef gpg_error_t (*pwmd_status_cb_t) (void *user, const char *line);
 265
 266
 267 /*! \typedef pwmd_inquire_cb_t
 268  * \brief Send data to the pwmd server.
 269  *
 270  * This is a callback function that is used for sending data to the server for
 271  * commands that need to reply to an INQUIRE server response. The reason for
 272  * this callback is to let the client send as many bytes as it wants rather
 273  * than the entire data at once.  It gets called during an internal \ref
 274  * assuan_transact() from an internal inquire callback function which in turn
 275  * calls this function by looping over its return value.
 276  *
 277  * \param user The user data pointer passed to the libpwmd function specifying
 278  * this callback.
 279  * \param keyword The name of this inquire. Could be a command name or some
 280  * keyword describing what needs to be sent. See the pwmd and \ref
 281  * gpg-agent(1) documentation for details.
 282  * \param rc The result of the last internal call to \ref assuan_send_data()
 283  * which did the sending of the data to the pwmd server. On the first call to
 284  * this callback it's value will always be 0 since no data has been sent yet.
 285  * This should be checked during each call to this function and should return
 286  * the same error code when set. Its purpose is to let the client clean up
 287  * before letting the command fail.
 288  * \param[out] data The next chunk of data to send or NULL.
 289  * \param[out] len The length of \a data or 0.
 290  *
 291  * \retval 0 There is more data to be sent.
 292  * \retval GPG_ERR_EOF No need to call this function again, the current
 293  * \a data is the last to send.
 294  * \retval code Any other error code which will cancel the INQUIRE.
 295  *
 296  * \note The sent data is processed line-per-line. The line is either newline
 297  * terminated or is buffered until ASSUAN_LINELENGTH bytes have been
 298  * allocated. Any remaining bytes are sent after the INQUIRE has finished.
 299  */
 300 typedef gpg_error_t (*pwmd_inquire_cb_t) (void *user, const char *keyword,
 301                                           gpg_error_t rc, char **data,
 302                                           size_t * len);
 303
 304
 305 /*! \typedef pwmd_knownhost_cb_t
 306  * \brief Verify a remote SSH connection.
 307  *
 308  * When \ref PWMD_OPTION_KNOWNHOST_CB is set and a the current connections
 309  * host key was not found in the known hosts file, then this callback function
 310  * can be used to confirm the addition of the new host key to the known_hosts
 311  * file.
 312  *
 313  * \param user User data which was set with \ref PWMD_OPTION_KNOWNHOST_DATA.
 314  * \param host The hostname as passed to \ref pwmd_connect().
 315  * \param hostkey The raw binary data of the host key.
 316  * \param len The length of \a hostkey.
 317  * \retval 0 Add the host key to the known hosts file.
 318  * \retval GPG_ERR_NOT_CONFIRMED Do not add the host key and abort the
 319  * connection. This is the recommended error code although any other non-zero
 320  * return value will also abort the connection.
 321  *
 322  * \note If the known hosts file cannot be modified do to filesystem
 323  * restrictions when trying to add the new host key, no error is returned.
 324  * Instead, the host key is added to the current connections host key cache
 325  * and the connection is accepted.
 326  *
 327  * \see \ref remote
 328  */
 329 typedef gpg_error_t (*pwmd_knownhost_cb_t) (void *user, const char *host,
 330                                             const char *hostkey,
 331                                             size_t len);
 332
 333
 334 /*! \enum pwmd_option_t
 335  * \brief libpwmd options.
 336  *
 337  * Options are set with \ref pwmd_setopt(). Some options must be set before a
 338  * connection is made to have any effect.
 339  *
 340  * \filepath
 341  */
 342 /* Note to self: dont change the order or insert. Only append. */
 343 typedef enum
 344 {
 345   /*! A string value which specifies the full path of the \ref pinentry(1)
 346    * binary. The default is specified at compile time.
 347    *
 348    * \note This only affects the local pinentry.
 349    * \see \ref pinentry
 350    */
 351   PWMD_OPTION_PINENTRY_PATH,
 352
 353   /*! A string value which specifies the full path to the TTY that \ref
 354    * pinentry(1) will use to prompt on. When set and no DISPLAY is
 355    * available, \ref PWMD_OPTION_PINENTRY_TERM must also be set.
 356    *
 357    * \see \ref pinentry
 358    */
 359   PWMD_OPTION_PINENTRY_TTY,
 360
 361   /*! A string value which specifies the terminal type (i.e., vt100) that
 362    * \ref pinentry(1) will use when no X11 display is available.
 363    *
 364    * \see \ref pinentry
 365    */
 366   PWMD_OPTION_PINENTRY_TERM,
 367
 368   /*! A string value which specifies the X11 display that \ref pinentry(1)
 369    * will use. \ref pinentry(1) seems to make DISPLAY have a higher priority
 370    * than \ref PWMD_OPTION_PINENTRY_TTY.
 371    *
 372    * \see \ref pinentry
 373    */
 374   PWMD_OPTION_PINENTRY_DISPLAY,
 375
 376   /*! A character string that \ref pinentry(1) will use in it's dialog
 377    * window.
 378    */
 379   PWMD_OPTION_PINENTRY_ERROR,
 380
 381   /*! \copydoc PWMD_OPTION_PINENTRY_ERROR */
 382   PWMD_OPTION_PINENTRY_PROMPT,
 383
 384   /*! \copydoc PWMD_OPTION_PINENTRY_ERROR */
 385   PWMD_OPTION_PINENTRY_DESC,
 386
 387   /*! For \ref pinentry(1) localization. */
 388   PWMD_OPTION_PINENTRY_LC_CTYPE,
 389
 390   /*! \copydoc PWMD_OPTION_PINENTRY_LC_CTYPE */
 391   PWMD_OPTION_PINENTRY_LC_MESSAGES,
 392
 393   /*! An integer value that specifies the number of seconds \ref pinentry(1)
 394    * will wait for input before timing out and aborting the current command.
 395    * If 0, then no timeout will be used. The default is 30.
 396    *
 397    * \note This only affects the local pinentry.
 398    */
 399   PWMD_OPTION_PINENTRY_TIMEOUT,
 400
 401   /*! An integer value that specifies the number of times to prompt for a
 402    * passphrase before returning an error.
 403    *
 404    * \note This only affects the local pinentry.
 405    */
 406   PWMD_OPTION_PINENTRY_TRIES,
 407
 408   /*! A function of type \ref pwmd_status_cb_t that will process status
 409    * messages received from the pwmd server.
 410    */
 411   PWMD_OPTION_STATUS_CB,
 412
 413   /*! A user data pointer which is passed to the status message function
 414    * \ref PWMD_OPTION_STATUS_CB. */
 415   PWMD_OPTION_STATUS_DATA,
 416
 417   /*! A function of type \ref pwmd_knownhost_cb_t that will be used to
 418    * confirm a host key that was not found in the known hosts file.
 419    *
 420    * \see \ref remote
 421    */
 422   PWMD_OPTION_KNOWNHOST_CB,
 423
 424   /*! User supplied data which is passed to the known host function \ref
 425    * PWMD_OPTION_KNOWNHOST_CB.
 426    *
 427    * \see \ref remote
 428    */
 429   PWMD_OPTION_KNOWNHOST_DATA,
 430
 431   /*! When the total number of bytes to be sent via an INQUIRE is known,
 432    * this should be set so XFER status messages can be parsed correctly.
 433    * When not known or unset, 0 is used as the total argument to the XFER
 434    * status message. This option should be reset in every function that
 435    * uses an \ref pwmd_inquire_cb_t.
 436    *
 437    * \note During the INQUIRE, \ref PWMD_OPTION_STATUS_CB is called, when
 438    * set, after every iteration of the \ref pwmd_inquire_cb_t.
 439    *
 440    * \note This is a libpwmd feature. pwmd itself does not send XFER status
 441    * messages during an INQUIRE. Status messages can be parsed only when
 442    * \ref PWMD_OPTION_STATUS_CB is set.
 443    */
 444   PWMD_OPTION_INQUIRE_TOTAL,
 445
 446   /*! When set to 1, lock the file mutex after opening a file as if the LOCK
 447    * command had been sent.
 448    */
 449   PWMD_OPTION_LOCK_ON_OPEN,
 450
 451   /*! Use ssh-agent to retrieve the private key to authenticate when
 452    * connecting to a remote pwmd server. */
 453   PWMD_OPTION_SSH_AGENT,
 454
 455   /*! When 1, disable pinentry use. This will prevent both pwmd and libpwmd
 456    * from using a pinentry program and will prompt from a terminal if
 457    * available.
 458    *
 459    * \note This must be set before calling \ref pwmd_open().
 460    * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE.
 461    */
 462   PWMD_OPTION_NO_PINENTRY,
 463
 464   /*! When 1, libpwmd will disable pwmd's pinentry and use it's own
 465    * fork(2)'ed pinentry.
 466    *
 467    * \note This must be set before calling \ref pwmd_open().
 468    */
 469   PWMD_OPTION_LOCAL_PINENTRY,
 470
 471   /*! When set, override libpwmd's handling of server inquires with the
 472    * PASSPHRASE, NEW_PASSPHRASE and SIGN_PASSPHRASE keywords. Handling of these
 473    * keywords is done automatically when \ref PWMD_OPTION_NO_PINENTRY or \ref
 474    * PWMD_OPTION_LOCAL_PINENTRY is set or when the connection is a remote one.
 475    *
 476    * \see \ref remote, \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_password()
 477    */
 478   PWMD_OPTION_OVERRIDE_INQUIRE,
 479
 480   /*! An int specifying a timeout in seconds before a TCP connection or
 481    * transfer function will timeout causing a connection or command to
 482    * fail. This option can be specified both before and after a connection
 483    * has been established. When 0, no timeout is used.
 484    */
 485   PWMD_OPTION_SOCKET_TIMEOUT,
 486
 487   /*! An int specifying whether to enable TLS hostname verification on the
 488    * server certificate chain. Default is 0 or disabled. */
 489   PWMD_OPTION_TLS_VERIFY,
 490
 491   /*! Set to 1 to not modify the signal handler to ignore SIGPIPE. The default
 492    * is 0, or to ignore this signal. */
 493   PWMD_OPTION_SIGPIPE,
 494
 495   /*! Get the version of the pwmd server as an unsigned integer. This is a
 496    * read-only setting and is only available after connecting. */
 497   PWMD_OPTION_SERVER_VERSION,
 498
 499   /*! The identity file requires a passphrase. When set, prompt for the
 500    * passphrase after connecting. Note that only libssh2 built with OpenSSL
 501    * supports this feature as of libssh2 1.7.0. */
 502   PWMD_OPTION_SSH_NEEDS_PASSPHRASE,
 503 } pwmd_option_t;
 504
 505
 506 /*! \def PWMD_FEATURE_PINENTRY
 507  * \hideinitializer
 508  * \brief Pinentry support.
 509  *
 510  * This is for a local or fork()'ed pinentry.
 511  */
 512 #define PWMD_FEATURE_PINENTRY   0x0001
 513
 514 /*! \def PWMD_FEATURE_CRACK
 515  * \hideinitializer
 516  * \brief Password quality checking.
 517  *
 518  * A password quality meter is shown when the pinentry supports it.
 519  */
 520 #define PWMD_FEATURE_CRACK      0x0002
 521
 522 /*! \def PWMD_FEATURE_SSH
 523  * \hideinitializer
 524  * \brief Remote connections over an SSH channel.
 525  *
 526  * \see \ref remote
 527  */
 528 #define PWMD_FEATURE_SSH        0x0004
 529
 530 /*! \def PWMD_FEATURE_GNUTLS
 531  * \hideinitializer
 532  * \brief Remote connections over TLS.
 533  *
 534  * \see \ref remote
 535  */
 536 #define PWMD_FEATURE_GNUTLS     0x0008
 537
 538
 539 /*! \brief libpwmd compile time features.
 540  *
 541  * Useful for clients to determine what features are compiled into libpwmd at
 542  * runtime.
 543  *
 544  * \return A bitmask of features.
 545  */
 546 LIBPWMD_API unsigned int pwmd_features ();
 547
 548
 549 /*! \brief Initialize the library.
 550  *
 551  * This function must be the first function called in the library before any
 552  * others. It sets up the memory allocators and internationalization among
 553  * other things.
 554  *
 555  * \return 0 on success or an error code.
 556  */
 557 LIBPWMD_API gpg_error_t pwmd_init (void);
 558
 559 /*! \brief Deinitialize the library.
 560  *
 561  * This function is mainly for cleaning up other libraries that
 562  * libpwmd links with to prevent memory and other leaks showing up in
 563  * a debugger. It should be the final libpwmd function call before
 564  * your app exits.
 565  */
 566 LIBPWMD_API void pwmd_deinit (void);
 567
 568
 569 /*! \brief Creates a new handle.
 570  *
 571  * Creates a new handle for use with the other functions.
 572  *
 573  * \param name If not NULL, the name of the application. The application name
 574  * is sent to the pwmd server after successfully connecting and is used in
 575  * pwmd logging.
 576  * \param[out] pwm A new handle for use with the other functions.
 577  *
 578  * \return 0 on success or an error code.
 579  */
 580 LIBPWMD_API gpg_error_t pwmd_new (const char *name, pwm_t ** pwm);
 581
 582
 583 /*! \brief Set user data for a handle.
 584  *
 585  * Use this function to associate user data with a handle that can later be
 586  * retrieved with \ref pwmd_get_pointer().
 587  *
 588  * \param pwm A handle.
 589  * \param data A pointer to the user data.
 590  * \returns Nothing.
 591  */
 592 LIBPWMD_API void pwmd_set_pointer (pwm_t *pwm, void *data);
 593
 594
 595 /*! \brief Get user data for a handle.
 596  *
 597  * Return the user data pointer previously set with \ref pwmd_set_pointer().
 598  *
 599  * \param pwm A handle.
 600  * \returns A pointer to the user data.
 601  */
 602 LIBPWMD_API void *pwmd_get_pointer (pwm_t *pwm);
 603
 604
 605 /*! \brief Cancel an operation.
 606  *
 607  * This is limited in functionality as it will only cancel an initiating
 608  * connection to the pwmd server for the time being.
 609  *
 610  * \param pwm A handle.
 611  * \return 0 on success or an error code.
 612  */
 613 LIBPWMD_API gpg_error_t pwmd_cancel (pwm_t * pwm);
 614
 615
 616 /*! \brief Establish a connection to a pwmd server.
 617  *
 618  * Connects to the pwmd server specified in \a url. The format of \a url is:
 619  * \par
 620  * file:///path/to/socket, or
 621  * \par
 622  * ssh[46]://[username@]hostname[:port], or
 623  * \par
 624  * tls[46]://hostname[:port]
 625  *
 626  *  If \a url is NULL then the default local pwmd socket \a ~/.pwmd/socket
 627  *  will be used.
 628  *
 629  *  The remaining arguments are parameters for the \a url.
 630  *
 631  *  For SSH connections, the first of the positional parameters should be the
 632  *  identity file to use and is required to be non-NULL unless \ref
 633  *  PWMD_OPTION_SSH_AGENT is set.  The final parameter is the known hosts file
 634  *  to use or NULL to use a default of \a ~/.ssh/knownhosts.
 635  *
 636  *  For TLS connections, the first positional parameter should be the client
 637  *  certificate filename. The second parameter should be the client
 638  *  certificate key filename. The third parameter should be the Certificate
 639  *  Authority (CA) file that was used to sign the server certificate. The
 640  *  fourth parameter should be a TLS cipher priority string or NULL to use the
 641  *  default of "SECURE256". The final parameter is an SHA-256 hash of the
 642  *  server fingerprint or NULL.
 643  *
 644  *  For local connections, any remaining parameters are ignored.
 645  *
 646  * \param pwm A handle.
 647  * \param url The socket to connect to.
 648  * \param ... Remaining parameters for the \a url.
 649  * \return 0 on success or an error code.
 650  * \filepath
 651  * \see \ref PWMD_OPTION_SSH_AGENT, \ref PWMD_OPTION_SOCKET_TIMEOUT,
 652  * pwmd_socket_type(), pwmd_disconnect(),
 653  * \ref remote
 654  */
 655 LIBPWMD_API gpg_error_t pwmd_connect (pwm_t * pwm, const char *url, ...);
 656
 657 /*! \brief Get the error code of a failed TLS function.
 658  *
 659  * When an TLS error occurs while connecting or during a command, this function
 660  * can be used to get the error code.
 661  *
 662  * \param pwm A handle.
 663  * \return 0 on success or an \ref gnutls error code.
 664  */
 665 LIBPWMD_API int pwmd_tls_error (pwm_t * pwm)
 666      __attribute__ ((__deprecated__));
 667
 668 /*! \brief Get the error code of a failed GnuTLS function.
 669  *
 670  * When an TLS error occurs while connecting or during a command, this function
 671  * can be used to get the error code.
 672  *
 673  * \param pwm A handle.
 674  * \param[out] str The textual representation of the gnutls error code.
 675  * \return 0 on success or an \ref gnutls error code.
 676  */
 677 LIBPWMD_API int pwmd_gnutls_error (pwm_t * pwm, const char **str);
 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.
 685  * \param ... The option value.
 686  * \return 0 on success or an error code.
 687  */
 688 LIBPWMD_API gpg_error_t pwmd_setopt (pwm_t * pwm, pwmd_option_t opt, ...);
 689
 690
 691 /*! \brief Get the value for a handle option.
 692  *
 693  * Retrieves the default or previously set value for a handle option. See
 694  * \ref pwmd_option_t for option specific details.
 695  *
 696  * \param pwm A handle.
 697  * \param opt The option.
 698  * \param ... A pointer to the option value type to store the value.
 699  * \return 0 on success or an error code.
 700  * \note The value is returned as a pointer and not duplicated.
 701  */
 702 LIBPWMD_API gpg_error_t pwmd_getopt (pwm_t * pwm, pwmd_option_t opt, ...);
 703
 704
 705 /*! \brief Launch a local pinentry.
 706  *
 707  * Does not send any command to the pwmd server. This maybe useful if a
 708  * passphrase is needed while opening a file over a remote connection and
 709  * during an \ref pwmd_open() server inquire.
 710  *
 711  * This function may also be used to display a user confirmation dialog with
 712  * pinentry when \a which is \ref PWMD_PINENTRY_CONFIRM. The text to prompt
 713  * with is set with \ref PWMD_OPTION_PINENTRY_DESC.
 714  *
 715  * \param pwm A handle.
 716  * \param filename The filename to use in the pinentry dialog strings.
 717  * \param[out] result The entered value in the pinentry dialog which should be
 718  * freed with \ref pwmd_free().
 719  * \param[out] len The length of \a result.
 720  * \param which Determines the default strings shown in the pinentry
 721  * dialog. \ref pwmd_setopt() may also be used to override the defaults. In
 722  * this case \ref PWMD_PINENTRY_USER should be used. \ref PWMD_PINENTRY_CLOSE
 723  * should be used to terminate the pinentry process when the pinentry is no
 724  * longer needed.
 725  *
 726  * \return 0 on success or an error.
 727  *
 728  * \see pwmd_password()
 729  */
 730 LIBPWMD_API gpg_error_t pwmd_getpin (pwm_t * pwm, const char *filename,
 731                                      char **result, size_t * len,
 732                                      pwmd_pinentry_t which);
 733
 734 /*! \brief Obtain a passphrase from a local pinentry.
 735  *
 736  * This is the same function that libpwmd uses during an inquire when using
 737  * the local pinentry and the inquire keyword is one of PASSPHRASE,
 738  * NEW_PASSPHRASE or SIGN_PASSPHRASE. Provided for convenience since it sets
 739  * proper pinentry strings and handles new passphrase confirmation.
 740  *
 741  * \param pwm A handle.
 742  * \param keyword The keyword to determine pinentry strings. Usually
 743  * PASSPHRASE or NEW_PASSPHRASE.
 744  * \param[out] data The obtained passphrase which should be freed with \ref
 745  * pwmd_free().
 746  * \param[out] size The length of \a data.
 747  *
 748  * \return 0 on success or an error.
 749  */
 750 LIBPWMD_API gpg_error_t pwmd_password (pwm_t * pwm, const char *keyword,
 751                                        char **data, size_t * size);
 752
 753 /*! \brief Open a file on the pwmd server.
 754  *
 755  * This will send the OPEN command to the server.
 756  *
 757  * The inquire \a callback function should be used when \ref
 758  * PWMD_OPTION_NO_PINENTRY is set and is used to send the passphrase when
 759  * needed.
 760  *
 761  * \param pwm A handle.
 762  * \param filename The filename to open. The \a filename is not a full path
 763  * but the data filename only.
 764  * \param callback A callback function to invoke when pwmd inquires data from
 765  * the client.
 766  * \param data User data passed to the \a callback function.
 767  * \return 0 on success or an error code.
 768  * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref pinentry, pwmd_password()
 769  */
 770 LIBPWMD_API gpg_error_t pwmd_open (pwm_t * pwm, const char *filename,
 771                                    pwmd_inquire_cb_t callback, void *data);
 772
 773
 774 /*! \brief Check for socket activity.
 775  *
 776  * This function should be called periodically to check for any pending status
 777  * messages sent from the server and when \em not in a command.
 778  *
 779  * \param pwm A handle.
 780  * \return 0 on success or an error code.
 781  *
 782  * \note This function makes use of \ref pwmd_status_cb_t.
 783  */
 784 LIBPWMD_API gpg_error_t pwmd_process (pwm_t * pwm);
 785
 786
 787 /*! \brief Save a file on the pwmd server.
 788  *
 789  * This will send the SAVE command and write any changes to the document to
 790  * disk.
 791  *
 792  * The inquire \a callback function should be used when \ref
 793  * PWMD_OPTION_NO_PINENTRY is set or when a SAVE option specified in \a args
 794  * inquires more data. This function will also disable the pwmd pinentry when
 795  * \ref PWMD_OPTION_NO_PINENTRY or \ref PWMD_OPTION_LOCAL_PINENTRY is set. It
 796  * will not restore the pwmd pinentry mode that was previously set before
 797  * calling this function.
 798  *
 799  * \param pwm A handle.
 800  * \param args Any SAVE protocol command options or NULL.
 801  * \param callback A callback function to invoke when pwmd inquires data from
 802  * the client.
 803  * \param user User data passed to the \a callback function.
 804  * \return 0 on success or an error code.
 805  * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_NO_PINENTRY,
 806  * \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_command(), \ref pinentry
 807  */
 808 LIBPWMD_API gpg_error_t pwmd_save (pwm_t * pwm, const char *args,
 809                                    pwmd_inquire_cb_t callback, void *user);
 810
 811
 812 /*! \brief Change the passphrase for a data file.
 813  *
 814  * This will send the PASSWD command to the server taking care of pinentry
 815  * settings.
 816  *
 817  * The inquire \a callback function should be used when \ref
 818  * PWMD_OPTION_OVERRIDE_INQUIRE is set. This function will disable the pwmd
 819  * pinentry when \ref PWMD_OPTION_NO_PINENTRY or \ref
 820  * PWMD_OPTION_LOCAL_PINENTRY is set. It will not restore the pwmd pinentry
 821  * mode that was previously set before calling this function.
 822  *
 823  * \param pwm A handle.
 824  * \param args Any PASSWD protocol command options or NULL.
 825  * \param callback A callback function to invoke when pwmd inquires data from
 826  * the client.
 827  * \param user User data passed to the \a callback function.
 828  * \return 0 on success or an error code.
 829  * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_NO_PINENTRY,
 830  * \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_command(), \ref pinentry
 831  */
 832 LIBPWMD_API gpg_error_t pwmd_passwd (pwm_t * pwm, const char *args,
 833                                      pwmd_inquire_cb_t callback, void *user);
 834
 835
 836 /*! \brief Send a command to the pwmd server.
 837  *
 838  * You should avoid sending the BYE command here because the assuan context
 839  * will be freed and bad things will happen. Use \ref pwmd_close() instead.
 840  *
 841  * For pwmd commands that use an INQUIRE to retrieve data from a client, the
 842  * \a callback parameter must be non-NULL and will be used to send the data to
 843  * pwmd.
 844  *
 845  * \param pwm A handle.
 846  * \param[out] result The result of the command when successful which must be
 847  * freed with \ref pwmd_free().
 848  * \param[out] len The length of \a result.
 849  * \param callback A callback function to invoke when pwmd inquires data from
 850  * the client.
 851  * \param user User data passed to the \a callback function.
 852  * \param cmd The command to send and any following arguments.
 853  * \return 0 on success or an error code.
 854  *
 855  * \note Not all commands return a \a result.
 856  */
 857 LIBPWMD_API gpg_error_t pwmd_command (pwm_t * pwm, char **result,
 858                                       size_t * len,
 859                                       pwmd_inquire_cb_t callback,
 860                                       void *user, const char *cmd, ...);
 861
 862
 863 /*! \brief Send a command to the pwmd server.
 864  *
 865  * Like \ref pwmd_command() but uses an argument pointer instead.
 866  *
 867  * \param pwm A handle.
 868  * \param[out] result The result of the command when successful which must be
 869  * freed with \ref pwmd_free().
 870  * \param[out] len The length of \a result.
 871  * \param callback A callback function to invoke when pwmd inquires data from
 872  * the client.
 873  * \param user User data passed to the \a callback function.
 874  * \param cmd The command to send.
 875  * \param ap The arguments to \a cmd.
 876  * \return 0 on success or an error code.
 877  *
 878  * \note Not all commands return a \a result.
 879  */
 880 LIBPWMD_API gpg_error_t pwmd_command_ap (pwm_t * pwm, char **result,
 881                                          size_t * len,
 882                                          pwmd_inquire_cb_t callback,
 883                                          void *user, const char *cmd,
 884                                          va_list ap);
 885
 886
 887 /*! \brief Close a connection to the pwmd server.
 888  *
 889  * This will close the connection but keep any previously set options for the
 890  * specified handle. Calling \ref pwmd_connect() will re-acquire an libassuan
 891  * context.
 892  *
 893  * \param pwm A handle.
 894  * \return 0 on success or an error code.
 895  * \see \ref pwmd_close()
 896  */
 897 LIBPWMD_API gpg_error_t pwmd_disconnect (pwm_t * pwm);
 898
 899
 900 /*! \brief Close a handle.
 901  *
 902  * This will close the connection to a pwmd server and free any resources
 903  * associated with it.
 904  *
 905  * \param pwm A handle.
 906  * \return Nothing.
 907  * \see \ref pwmd_disconnect(), \ref pwmd_new()
 908  */
 909 LIBPWMD_API void pwmd_close (pwm_t * pwm);
 910
 911
 912 /*! \brief The type of connection a handle has.
 913  *
 914  * Useful when you want to know what kind of connection a handle has.
 915  *
 916  * \param pwm A handle.
 917  * \param[out] type The type of socket.
 918  * \return 0 on success or an error code.
 919  *
 920  * \see \ref pwmd_socket_t
 921  */
 922 LIBPWMD_API gpg_error_t pwmd_socket_type (pwm_t * pwm,
 923                                           pwmd_socket_t * type);
 924
 925 /*! \brief Get the file descriptor associated with a handle.
 926  *
 927  * May be useful to determine whether a handle is ready for reading or
 928  * writing by using select(2) or poll(2).
 929  *
 930  * \param pwm A handle.
 931  * \param[out] fd Set to the file descriptor associated with \a pwm.
 932  * \return 0 on success or an error code.
 933  */
 934 LIBPWMD_API gpg_error_t pwmd_fd (pwm_t * pwm, int *fd);
 935
 936
 937 /*! \brief Free a previously allocated pointer.
 938  *
 939  * Use this function to free resources allocated by the other libpwmd memory
 940  * functions. Do not use it to free allocations made by other allocators.
 941  *
 942  * The difference between the standard free() and this function is that
 943  * this one will zero out the contents of the pointer before freeing it.
 944  *
 945  * \param ptr The pointer to deallocate.
 946  * \return Nothing.
 947  * \see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(),
 948  * pwmd_command()
 949  */
 950 LIBPWMD_API void pwmd_free (void *ptr);
 951
 952
 953 /*! \brief A wrapper around malloc.
 954  *
 955  * Like malloc(), but lets libpwmd keep track of the pointer.
 956  *
 957  * \param size The number of bytes to allocate.
 958  * \return A newly allocated pointer or NULL if there wasn't enough memory.
 959  * \see malloc(3), pwmd_free()
 960  */
 961 LIBPWMD_API void *pwmd_malloc (size_t size);
 962
 963
 964 /*! \brief A wrapper around calloc().
 965  *
 966  * Like calloc(), but lets libpwmd keep track of the pointer.
 967  *
 968  * \param nmemb The number of elements to allocate.
 969  * \param size The number of bytes to allocate.
 970  * \return A newly allocated pointer or NULL if there wasn't enough memory.
 971  * \see calloc(3), pwmd_free()
 972  */
 973 LIBPWMD_API void *pwmd_calloc (size_t nmemb, size_t size);
 974
 975
 976 /*! \brief A wrapper around realloc().
 977  *
 978  * Like realloc(), but lets libpwmd keep track of the pointer.
 979  *
 980  * \param ptr The pointer to reallocate.
 981  * \param size The new number of bytes to allocate.
 982  * \return A newly allocated pointer or NULL if there wasn't enough memory.
 983  * \see realloc(3), pwmd_free()
 984  */
 985 LIBPWMD_API void *pwmd_realloc (void *ptr, size_t size);
 986
 987
 988 /*! \brief A wrapper around strdup().
 989  *
 990  * Like strdup(), but lets libpwmd keep track of the pointer.
 991  *
 992  * \param str The string to duplicate.
 993  * \return A newly allocated character pointer or NULL if there wasn't
 994  * enough memory.
 995  * \see strdup(3), pwmd_free()
 996  */
 997 LIBPWMD_API char *pwmd_strdup (const char *str);
 998
 999
1000 /*! \brief Duplicate a formatted string.
1001  *
1002  * Like \ref asprintf(3), but lets libpwmd keep track of the pointer.
1003  *
1004  * \param fmt The formatted string and any following arguments.
1005  * \return A newly allocated character pointer or NULL if there wasn't
1006  * enough memory.
1007  * \see pwmd_free()
1008  */
1009 LIBPWMD_API char *pwmd_strdup_printf (const char *fmt, ...);
1010
1011 #ifdef __cplusplus
1012 }
1013 #endif
1014
1015 #endif