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