src/libpwmd.h.in

   1 /*
   2     Copyright (C) 2006-2016 Ben Kibbey <bjk@luxsci.net>
   3
   4     This file is part of libpwmd.
   5
   6     This library is free software; you can redistribute it and/or
   7     modify it under the terms of the GNU Lesser General Public
   8     License as published by the Free Software Foundation; either
   9     version 2.1 of the License, or (at your option) any later version.
  10
  11     This library is distributed in the hope that it will be useful,
  12     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14     Lesser General Public License for more details.
  15
  16     You should have received a copy of the GNU Lesser General Public
  17     License along with this library; if not, write to the Free Software
  18     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
  19     USA
  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
 270   /*! A socket set with pwmd_connect_fd(). */
 271   PWMD_SOCKET_USER
 272 } pwmd_socket_t;
 273
 274
 275 /*! \typedef pwmd_pinentry_t
 276  * \brief Local pinentry commands and not pwmd pinentry.
 277  *
 278  * These determine what prompt a local pinentry uses. For use with \ref
 279  * pwmd_getpin().
 280  */
 281 typedef enum
 282 {
 283   /*! When opening a file. */
 284   PWMD_PINENTRY_OPEN,
 285
 286   /*! When opening a file failed due to a bad passphrase. */
 287   PWMD_PINENTRY_OPEN_FAILED,
 288
 289   /*! When saving a file. */
 290   PWMD_PINENTRY_SAVE,
 291
 292   /*! For passphrase confirmation. */
 293   PWMD_PINENTRY_SAVE_CONFIRM,
 294
 295   /*! When saving a file and passphrase confirmation failed. */
 296   PWMD_PINENTRY_SAVE_FAILED,
 297
 298   /*! For confirmation of a user-defined prompt. */
 299   PWMD_PINENTRY_CONFIRM,
 300
 301   /*! For the default or user defined string set with \ref
 302    * PWMD_OPTION_PINENTRY_DESC. */
 303   PWMD_PINENTRY_USER,
 304
 305   /*! To terminate the pinentry process created with \ref pwmd_getpin(). */
 306   PWMD_PINENTRY_CLOSE
 307 } pwmd_pinentry_t;
 308
 309
 310 /*! \typedef pwmd_read_cb_t
 311  * \brief Custom socket read callback function.
 312  *
 313  * Use this function to override the libpwmd function used for reading from a
 314  * socket. Set with \ref pwmd_setopt().
 315  *
 316  * \param user A user data pointer which is set with \ref
 317  * PWMD_OPTION_READ_CB_DATA.
 318  * \param fd The file descriptor to read from.
 319  * \param data The buffer to store the read data to.
 320  * \param len The size of the data buffer.
 321  * \returns The amount of bytes read.
 322  * \see \ref pwmd_connect_fd()
 323  */
 324 typedef ssize_t (*pwmd_read_cb_t) (void *user, int fd, void *data, size_t len);
 325
 326
 327 /*! \typedef pwmd_write_cb_t
 328  * \brief Custom socket write callback function.
 329  *
 330  * Use this function to override the libpwmd function used for writing to a
 331  * socket. Set with \ref pwmd_setopt().
 332  *
 333  * \param user A user data pointer which is set with \ref
 334  * PWMD_OPTION_WRITE_CB_DATA.
 335  * \param fd The file descriptor to write to.
 336  * \param data The data to write.
 337  * \param len The amount of data bytes to write.
 338  * \returns The amount of bytes written.
 339  * \see \ref pwmd_connect_fd()
 340  */
 341 typedef ssize_t (*pwmd_write_cb_t) (void *user, int fd, const void *data,
 342                                     size_t len);
 343
 344
 345 /*! \typedef pwmd_status_cb_t
 346  * \brief Process status messages.
 347  *
 348  * The value of the option \ref PWMD_OPTION_STATUS_CB which is set with \ref
 349  * pwmd_setopt().
 350  *
 351  * \param user A user data pointer which is set with \ref
 352  * PWMD_OPTION_STATUS_DATA.
 353  * \param line The status message line received from the server.
 354  * \return 0 on success or an error code which will cause a command to fail.
 355  */
 356 typedef gpg_error_t (*pwmd_status_cb_t) (void *user, const char *line);
 357
 358
 359 /*! \typedef pwmd_inquire_cb_t
 360  * \brief Send data to the pwmd server.
 361  *
 362  * This is a callback function that is used for sending data to the server for
 363  * commands that need to reply to an INQUIRE server response. The reason for
 364  * this callback is to let the client send as many bytes as it wants rather
 365  * than the entire data at once.  It gets called during an internal \ref
 366  * assuan_transact() from an internal inquire callback function which in turn
 367  * calls this function by looping over its return value.
 368  *
 369  * \param user The user data pointer passed to the libpwmd function specifying
 370  * this callback.
 371  * \param keyword The name of this inquire. Could be a command name or some
 372  * keyword describing what needs to be sent. See the pwmd and \ref
 373  * gpg-agent(1) documentation for details.
 374  * \param rc The result of the last internal call to \ref assuan_send_data()
 375  * which did the sending of the data to the pwmd server. On the first call to
 376  * this callback it's value will always be 0 since no data has been sent yet.
 377  * This should be checked during each call to this function and should return
 378  * the same error code when set. Its purpose is to let the client clean up
 379  * before letting the command fail.
 380  * \param[out] data The next chunk of data to send or NULL.
 381  * \param[out] len The length of \a data or 0.
 382  *
 383  * \retval 0 There is more data to be sent.
 384  * \retval GPG_ERR_EOF No need to call this function again, the current
 385  * \a data is the last to send.
 386  * \retval code Any other error code which will cancel the INQUIRE.
 387  *
 388  * \note The sent data is processed line-per-line. The line is either newline
 389  * terminated or is buffered until ASSUAN_LINELENGTH bytes have been
 390  * allocated. Any remaining bytes are sent after the INQUIRE has finished.
 391  */
 392 typedef gpg_error_t (*pwmd_inquire_cb_t) (void *user, const char *keyword,
 393                                           gpg_error_t rc, char **data,
 394                                           size_t * len);
 395
 396
 397 /*! \typedef pwmd_knownhost_cb_t
 398  * \brief Verify a remote SSH connection.
 399  *
 400  * When the current SSH connections host key was not found in the known hosts
 401  * file, then this callback function can be used to confirm the addition of the
 402  * new host key to the known_hosts file. When \ref PWMD_OPTION_KNOWNHOST_CB is
 403  * not set then the default callback function will be used.
 404  *
 405  * \param user User data which was set with \ref PWMD_OPTION_KNOWNHOST_DATA.
 406  * \param host The hostname as passed to \ref pwmd_connect().
 407  * \param hostkey The raw binary data of the host key.
 408  * \param len The length of \a hostkey.
 409  * \retval 0 Add the host key to the known hosts file.
 410  * \retval GPG_ERR_NOT_CONFIRMED Do not add the host key and abort the
 411  * connection. This is the recommended error code although any other non-zero
 412  * return value will also abort the connection.
 413  *
 414  * \note If the known hosts file cannot be modified do to filesystem
 415  * restrictions when adding the new host key, no error is returned.  Instead,
 416  * the host key is added to the current connections host key cache and the
 417  * connection is accepted.
 418  *
 419  * \see \ref remote
 420  */
 421 typedef gpg_error_t (*pwmd_knownhost_cb_t) (void *user, const char *host,
 422                                             const char *hostkey,
 423                                             size_t len);
 424
 425
 426 /*! \enum pwmd_option_t
 427  * \brief libpwmd options.
 428  *
 429  * Options are set with \ref pwmd_setopt(). Some options must be set before a
 430  * connection is made to have any effect.
 431  *
 432  * \filepath
 433  */
 434 /* Note to self: dont change the order or insert. Only append. */
 435 typedef enum
 436 {
 437   /*! A string value which specifies the full path of the \ref pinentry(1)
 438    * binary. The default is specified at compile time.
 439    *
 440    * \note This only affects the local pinentry.
 441    * \see \ref pinentry
 442    */
 443   PWMD_OPTION_PINENTRY_PATH,
 444
 445
 446   /*! A string value which specifies the full path to the TTY that \ref
 447    * pinentry(1) will use to prompt on. When set and no DISPLAY is
 448    * available, \ref PWMD_OPTION_PINENTRY_TERM must also be set.
 449    *
 450    * \see \ref pinentry
 451    */
 452   PWMD_OPTION_PINENTRY_TTY,
 453
 454
 455   /*! A string value which specifies the terminal type (i.e., vt100) that
 456    * \ref pinentry(1) will use when no X11 display is available.
 457    *
 458    * \see \ref pinentry
 459    */
 460   PWMD_OPTION_PINENTRY_TERM,
 461
 462
 463   /*! A string value which specifies the X11 display that \ref pinentry(1)
 464    * will use. \ref pinentry(1) seems to make DISPLAY have a higher priority
 465    * than \ref PWMD_OPTION_PINENTRY_TTY.
 466    *
 467    * \see \ref pinentry
 468    */
 469   PWMD_OPTION_PINENTRY_DISPLAY,
 470
 471
 472   /*! A character string that \ref pinentry(1) will use in it's dialog
 473    * window.
 474    */
 475   PWMD_OPTION_PINENTRY_ERROR,
 476
 477
 478   /*! \copydoc PWMD_OPTION_PINENTRY_ERROR */
 479   PWMD_OPTION_PINENTRY_PROMPT,
 480
 481
 482   /*! \copydoc PWMD_OPTION_PINENTRY_ERROR */
 483   PWMD_OPTION_PINENTRY_DESC,
 484
 485
 486   /*! For \ref pinentry(1) localization. */
 487   PWMD_OPTION_PINENTRY_LC_CTYPE,
 488
 489
 490   /*! \copydoc PWMD_OPTION_PINENTRY_LC_CTYPE */
 491   PWMD_OPTION_PINENTRY_LC_MESSAGES,
 492
 493
 494   /*! An integer value that specifies the number of seconds \ref pinentry(1)
 495    * will wait for input before timing out and aborting the current command.
 496    * If 0, then no timeout will be used. The default is 30.
 497    *
 498    * \note This only affects the local pinentry.
 499    */
 500   PWMD_OPTION_PINENTRY_TIMEOUT,
 501
 502
 503   /*! An integer value that specifies the number of times to prompt for a
 504    * passphrase before returning an error.
 505    *
 506    * \note This only affects the local pinentry.
 507    */
 508   PWMD_OPTION_PINENTRY_TRIES,
 509
 510
 511   /*! A function of type \ref pwmd_status_cb_t that will process status
 512    * messages received from the pwmd server.
 513    */
 514   PWMD_OPTION_STATUS_CB,
 515
 516
 517   /*! A user data pointer which is passed to the status message function
 518    * \ref PWMD_OPTION_STATUS_CB. */
 519   PWMD_OPTION_STATUS_DATA,
 520
 521
 522   /*! A function of type \ref pwmd_knownhost_cb_t that will be used to
 523    * confirm a host key that was not found in the known hosts file.
 524    *
 525    * \see \ref remote
 526    */
 527   PWMD_OPTION_KNOWNHOST_CB,
 528
 529
 530   /*! User supplied data which is passed to the known host function \ref
 531    * PWMD_OPTION_KNOWNHOST_CB.
 532    *
 533    * \see \ref remote
 534    */
 535   PWMD_OPTION_KNOWNHOST_DATA,
 536
 537
 538   /*! When the total number of bytes to be sent via an INQUIRE is known,
 539    * this should be set so XFER status messages can be parsed correctly.
 540    * When not known or unset, 0 is used as the total argument to the XFER
 541    * status message. This option should be reset in every function that
 542    * uses an \ref pwmd_inquire_cb_t.
 543    *
 544    * \note During the INQUIRE, \ref PWMD_OPTION_STATUS_CB is called, when
 545    * set, after every iteration of the \ref pwmd_inquire_cb_t.
 546    *
 547    * \note This is a libpwmd feature. pwmd itself does not send XFER status
 548    * messages during an INQUIRE. Status messages can be parsed only when
 549    * \ref PWMD_OPTION_STATUS_CB is set.
 550    */
 551   PWMD_OPTION_INQUIRE_TOTAL,
 552
 553
 554   /*! When set to 1, lock the file mutex during \ref pwmd_open() as if the LOCK
 555    * command had been sent.
 556    */
 557   PWMD_OPTION_LOCK_ON_OPEN,
 558
 559
 560   /*! Use ssh-agent to retrieve the private key to authenticate with when
 561    * connecting to a remote pwmd server. */
 562   PWMD_OPTION_SSH_AGENT,
 563
 564
 565   /*! When 1, disable pinentry use. This will prevent both pwmd and libpwmd
 566    * from using a pinentry program and will prompt from the terminal if
 567    * available.
 568    *
 569    * \note This must be set before calling \ref pwmd_open().
 570    * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_LOCAL_PINENTRY
 571    */
 572   PWMD_OPTION_NO_PINENTRY,
 573
 574
 575   /*! When 1, libpwmd will disable pwmd's pinentry and use it's own
 576    *  pinentry. This option is set by default when the connection is a remote
 577    *  one.
 578    *
 579    * \note This must be set before calling \ref pwmd_open().
 580    */
 581   PWMD_OPTION_LOCAL_PINENTRY,
 582
 583
 584   /*! When set, override libpwmd's internal handling of server inquires with
 585    * the PASSPHRASE, NEW_PASSPHRASE and SIGN_PASSPHRASE keywords. Handling of
 586    * these keywords is done automatically when \ref PWMD_OPTION_NO_PINENTRY or
 587    * \ref PWMD_OPTION_LOCAL_PINENTRY is set or when the connection is a remote
 588    * one.
 589    *
 590    * \see \ref remote, \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_password()
 591    */
 592   PWMD_OPTION_OVERRIDE_INQUIRE,
 593
 594
 595   /*! An int specifying a timeout in seconds before a TCP connection or
 596    * data transfer function will timeout causing a connection or command to
 597    * fail. This option can be specified both before and after a connection
 598    * has been established. When 0, no timeout is used.
 599    */
 600   PWMD_OPTION_SOCKET_TIMEOUT,
 601
 602
 603   /*! An int specifying whether to enable TLS hostname verification against the
 604    * server certificate chain. Default is 0 or disabled. */
 605   PWMD_OPTION_TLS_VERIFY,
 606
 607
 608   /*! Set to 1 to not modify the signal handler to ignore SIGPIPE. The default
 609    * is 0, or to ignore this signal. */
 610   PWMD_OPTION_SIGPIPE,
 611
 612
 613   /*! Get the version of the pwmd server as an unsigned integer. This is a
 614    * read-only setting and is only available after connecting. */
 615   PWMD_OPTION_SERVER_VERSION,
 616
 617
 618   /*! The SSH identity file requires a passphrase. When set, prompt for the
 619    * passphrase after connecting. Note that only libssh2 built with OpenSSL
 620    * supports this feature as of libssh2-1.7.0. */
 621   PWMD_OPTION_SSH_NEEDS_PASSPHRASE,
 622
 623
 624   /*! Set SSH private identity passphrase. When set there is no need to set
 625    * \ref PWMD_OPTION_SSH_NEEDS_PASSPHRASE. The value of this option is
 626    * duplicated then freed after the call to \ref pwmd_connect(). Note that
 627    * only libssh2 built with OpenSSL supports this feature as of
 628    * libssh2-1.7.0. */
 629   PWMD_OPTION_SSH_PASSPHRASE,
 630
 631
 632   /*! The TLS cipher priority string to use for a TLS connection. The default
 633    * is SECURE256:SECURE192:SECURE128:-VERS-SSL3.0:-VERS-TLS1.0. */
 634   PWMD_OPTION_TLS_PRIORITY,
 635
 636   /*! The callback function of type \ref pwmd_read_cb_t to use to read from a
 637    * socket. */
 638   PWMD_OPTION_READ_CB,
 639
 640   /*! The data to pass to the custom read function \ref pwmd_read_cb_t. */
 641   PWMD_OPTION_READ_CB_DATA,
 642
 643   /*! The callback function of type \ref pwmd_write_cb_t to use to write to a
 644    * socket. */
 645   PWMD_OPTION_WRITE_CB,
 646
 647   /*! The data to pass to the custom write function \ref pwmd_write_cb_t. */
 648   PWMD_OPTION_WRITE_CB_DATA,
 649 } pwmd_option_t;
 650
 651
 652 /*! \def PWMD_FEATURE_PINENTRY
 653  * \hideinitializer
 654  * \brief Pinentry support.
 655  *
 656  * This is for a local or fork()'ed pinentry.
 657  */
 658 #define PWMD_FEATURE_PINENTRY   0x0001
 659
 660 /*! \def PWMD_FEATURE_QUALITY
 661  * \hideinitializer
 662  * \brief Password quality checking.
 663  *
 664  * A password quality meter is shown when the pinentry supports it.
 665  */
 666 #define PWMD_FEATURE_QUALITY    0x0002
 667
 668 /*! \def PWMD_FEATURE_SSH
 669  * \hideinitializer
 670  * \brief Remote connections over an SSH channel.
 671  *
 672  * \see \ref remote
 673  */
 674 #define PWMD_FEATURE_SSH        0x0004
 675
 676 /*! \def PWMD_FEATURE_GNUTLS
 677  * \hideinitializer
 678  * \brief Remote connections over TLS.
 679  *
 680  * \see \ref remote
 681  */
 682 #define PWMD_FEATURE_GNUTLS     0x0008
 683
 684
 685 /*! \brief libpwmd compile time features.
 686  *
 687  * Useful for clients to determine what features are compiled into libpwmd at
 688  * runtime.
 689  *
 690  * \return A bitmask of features.
 691  */
 692 LIBPWMD_API unsigned int pwmd_features ();
 693
 694
 695 /*! \brief Initialize the library.
 696  *
 697  * This function must be the first function called in the library before any
 698  * others. It sets up the memory allocators and internationalization among
 699  * other things.
 700  *
 701  * \return 0 on success or an error code.
 702  */
 703 LIBPWMD_API gpg_error_t pwmd_init (void);
 704
 705 /*! \brief Deinitialize the library.
 706  *
 707  * This function is mainly for cleaning up other libraries that
 708  * libpwmd links with to prevent memory and other leaks showing up in
 709  * a debugger. It should be the final libpwmd function call before
 710  * your app exits.
 711  */
 712 LIBPWMD_API void pwmd_deinit (void);
 713
 714
 715 /*! \brief Creates a new handle.
 716  *
 717  * Creates a new handle or context for use with the other functions.
 718  *
 719  * \param name If not NULL, the name of the application. The application name
 720  * is sent to the pwmd server after successfully connecting and is used in
 721  * pwmd logging.
 722  * \param[out] pwm A new handle for use with the other functions.
 723  *
 724  * \return 0 on success or an error code.
 725  */
 726 LIBPWMD_API gpg_error_t pwmd_new (const char *name, pwm_t **pwm);
 727
 728
 729 /*! \brief Set user data for a handle.
 730  *
 731  * Use this function to associate user data with a handle that can later be
 732  * retrieved with \ref pwmd_get_pointer().
 733  *
 734  * \param pwm A handle.
 735  * \param data A pointer to the user data.
 736  * \returns Nothing.
 737  */
 738 LIBPWMD_API void pwmd_set_pointer (pwm_t *pwm, void *data);
 739
 740
 741 /*! \brief Get user data for a handle.
 742  *
 743  * Return the user data pointer previously set with \ref pwmd_set_pointer().
 744  *
 745  * \param pwm A handle.
 746  * \returns A pointer to the user data.
 747  */
 748 LIBPWMD_API void *pwmd_get_pointer (pwm_t *pwm);
 749
 750
 751 /*! \brief Cancel an operation.
 752  *
 753  * This is limited in functionality as it will only cancel an initiating
 754  * connection to the pwmd server. Command cancellation is not yet supported.
 755  *
 756  * \param pwm A handle.
 757  * \return 0 on success or an error code.
 758  */
 759 LIBPWMD_API gpg_error_t pwmd_cancel (pwm_t *pwm);
 760
 761
 762 /*! \brief Associate an already connected socket with a handle.
 763  *
 764  * Sets a file descriptor for use with the custom read and write callbacks. The
 765  * callbacks must be set before calling this function.
 766  *
 767  * \param pwm A handle.
 768  * \param fd A connected file descriptor.
 769  * \return 0 on success or an error code.
 770  * \see \ref pwmd_read_cb_t, \ref pwmd_write_cb_t
 771  */
 772 LIBPWMD_API gpg_error_t pwmd_connect_fd (pwm_t *pwm, int fd);
 773
 774
 775 /*! \brief Establish a connection to a pwmd server.
 776  *
 777  * Connects to the pwmd server specified in \a url. The format of \a url is:
 778  * \par
 779  * file:///path/to/socket, or
 780  * \par
 781  * ssh[46]://[username@]hostname[:port], or
 782  * \par
 783  * tls[46]://hostname[:port]
 784  *
 785  *  If \a url is NULL then the default local pwmd socket \a ~/.pwmd/socket
 786  *  will be used.
 787  *
 788  *  The remaining arguments are parameters for the \a url.
 789  *
 790  *  For SSH connections, the first of the positional parameters should be the
 791  *  identity file to use and is required to be non-NULL unless \ref
 792  *  PWMD_OPTION_SSH_AGENT is set.  The final parameter is the known hosts file
 793  *  to use or NULL to use a default of \a ~/.ssh/knownhosts.
 794  *
 795  *  For TLS connections, the first positional parameter should be the client
 796  *  certificate filename. The second parameter should be the client
 797  *  certificate key filename. The third parameter should be the Certificate
 798  *  Authority (CA) file that was used to sign the server certificate. The
 799  *  final parameter is an SHA-256 hash of the server fingerprint to verify
 800  *  against, or NULL.
 801  *
 802  *  For local connections, any remaining parameters are ignored.
 803  *
 804  * \param pwm A handle.
 805  * \param url The socket to connect to.
 806  * \param ... Remaining parameters for the \a url.
 807  * \return 0 on success or an error code.
 808  * \filepath
 809  * \see \ref PWMD_OPTION_SSH_AGENT, \ref PWMD_OPTION_SOCKET_TIMEOUT,
 810  * pwmd_socket_type(), pwmd_disconnect(), \ref remote
 811  */
 812 LIBPWMD_API gpg_error_t pwmd_connect (pwm_t *pwm, const char *url, ...);
 813
 814 /*! \brief Get the error code of a failed GnuTLS function.
 815  *
 816  * When an TLS error occurs while connecting or during a command, this function
 817  * can be used to get the error code and error description.
 818  *
 819  * \param pwm A handle.
 820  * \param[out] str The textual representation of the gnutls error code.
 821  * \return 0 on success or a GnuTLS error code.
 822  */
 823 LIBPWMD_API int pwmd_gnutls_error (pwm_t *pwm, const char **str);
 824
 825 /*! \brief Set handle options.
 826  *
 827  * See \ref pwmd_option_t for option specific details.
 828  *
 829  * \param pwm A handle.
 830  * \param opt The option.
 831  * \param ... The option value.
 832  * \return 0 on success or an error code.
 833  */
 834 LIBPWMD_API gpg_error_t pwmd_setopt (pwm_t *pwm, int opt, ...);
 835
 836
 837 /*! \brief Get the value for a handle option.
 838  *
 839  * Retrieves the default or previously set value for a handle option. See
 840  * \ref pwmd_option_t for option specific details.
 841  *
 842  * \param pwm A handle.
 843  * \param opt The option.
 844  * \param ... A pointer to the option value type to store the value.
 845  * \return 0 on success or an error code.
 846  * \note The value is returned as a pointer and not duplicated.
 847  */
 848 LIBPWMD_API gpg_error_t pwmd_getopt (pwm_t *pwm, int opt, ...);
 849
 850
 851 /*! \brief Launch a local pinentry.
 852  *
 853  * Does not send any command to the pwmd server. This maybe useful if a
 854  * passphrase is needed while opening a file over a remote connection and
 855  * during an \ref pwmd_open() server inquire.
 856  *
 857  * This function may also be used to display a user confirmation dialog with
 858  * pinentry when \a which is \ref PWMD_PINENTRY_CONFIRM. The text show in the
 859  * pinentry is set with \ref pwmd_setopt().
 860  *
 861  * \param pwm A handle.
 862  * \param filename The filename to use in the pinentry dialog strings when
 863  * using the default pinentry strings.
 864  * \param[out] result The entered value in the pinentry dialog which should be
 865  * freed with \ref pwmd_free().
 866  * \param[out] len The length of \a result.
 867  * \param which Determines the default strings shown in the pinentry
 868  * dialog. \ref pwmd_setopt() may also be used to override the defaults. In
 869  * this case \ref PWMD_PINENTRY_USER should be used. \ref PWMD_PINENTRY_CLOSE
 870  * should be used to terminate the pinentry process when the pinentry is no
 871  * longer needed.
 872  *
 873  * \return 0 on success or an error.
 874  *
 875  * \see pwmd_password()
 876  */
 877 LIBPWMD_API gpg_error_t pwmd_getpin (pwm_t *pwm, const char *filename,
 878                                      char **result, size_t *len,
 879                                      pwmd_pinentry_t which);
 880
 881 /*! \brief Obtain a passphrase from a local pinentry.
 882  *
 883  * This is the same function that libpwmd uses during an inquire when using
 884  * the local pinentry and the inquire keyword is one of PASSPHRASE,
 885  * NEW_PASSPHRASE or SIGN_PASSPHRASE. Provided for convenience since it sets
 886  * proper pinentry strings and handles new passphrase confirmation.
 887  *
 888  * \param pwm A handle.
 889  * \param keyword The keyword to determine pinentry strings. Usually one of
 890  * PASSPHRASE, NEW_PASSPHRASE or SIGN_PASSPHRASE as sent by pwmd.
 891  * \param[out] result The obtained passphrase which should be freed with \ref
 892  * pwmd_free().
 893  * \param[out] size The length of \a result.
 894  *
 895  * \return 0 on success or an error.
 896  */
 897 LIBPWMD_API gpg_error_t pwmd_password (pwm_t *pwm, const char *keyword,
 898                                        char **result, size_t *size);
 899
 900 /*! \brief Test the quality of a passphrase.
 901  *
 902  * When built with passphrase quality checking, you can test the amount of
 903  * entropy a passphrase contains with this function. It simply wraps around the
 904  * zxcvbn-c quality checking function.
 905  *
 906  * \param passphrase The passphrase to test.
 907  * \param[out] result The entropy of the passphrase in bits.
 908  *
 909  * \return 0 on success or an error code.
 910  */
 911 LIBPWMD_API gpg_error_t pwmd_test_quality (const char *passphrase,
 912                                            double *result);
 913
 914 /*! \brief Open a file on the pwmd server.
 915  *
 916  * This will send the OPEN command to the server.
 917  *
 918  * To make use of \a callback, \ref PWMD_OPTION_OVERRIDE_INQUIRE must also be
 919  * set.
 920  *
 921  * \param pwm A handle.
 922  * \param filename The filename to open. The \a filename is not a full path
 923  * but the data filename only.
 924  * \param callback A callback function to invoke when pwmd inquires data from
 925  * the client.
 926  * \param data User data passed to the \a callback function.
 927  * \return 0 on success or an error code.
 928  * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref pinentry, \ref pwmd_password()
 929  */
 930 LIBPWMD_API gpg_error_t pwmd_open (pwm_t *pwm, const char *filename,
 931                                    pwmd_inquire_cb_t callback, void *data);
 932
 933
 934 /*! \brief Check for socket activity.
 935  *
 936  * This function should be called periodically to check for any pending status
 937  * messages sent from the server and when \em not in a command.
 938  *
 939  * \param pwm A handle.
 940  * \return 0 on success or an error code.
 941  *
 942  * \note This function makes use of \ref pwmd_status_cb_t.
 943  */
 944 LIBPWMD_API gpg_error_t pwmd_process (pwm_t *pwm);
 945
 946
 947 /*! \brief Generate a new key.
 948
 949  * Generate a new signing or encryption key or both. This will only
 950  * generate a key without saving the XML document to disk.
 951  *
 952  * The inquire \a callback function should be used when a GENKEY option
 953  * specified in \a args inquires data.
 954  *
 955  * \param pwm A handle.
 956  * \param args Any GENKEY protocol command options or NULL.
 957  * \param callback A callback function to invoke when pwmd inquires data from
 958  * the client.
 959  * \param user User data passed to the \a callback function.
 960  * \return 0 on success or an error code.
 961  * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_NO_PINENTRY,
 962  * \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_command(), \ref pinentry
 963  */
 964 LIBPWMD_API gpg_error_t pwmd_genkey (pwm_t *pwm, const char *args,
 965                                      pwmd_inquire_cb_t callback, void *user);
 966
 967
 968 /*! \brief Save a file on the pwmd server.
 969  *
 970  * This will send the SAVE command and write any changes to the document to
 971  * disk.
 972  *
 973  * The inquire \a callback function should be used when a SAVE option specified
 974  * in \a args inquires data.
 975  *
 976  * \param pwm A handle.
 977  * \param args Any SAVE protocol command options or NULL.
 978  * \param callback A callback function to invoke when pwmd inquires data from
 979  * the client.
 980  * \param user User data passed to the \a callback function.
 981  * \return 0 on success or an error code.
 982  * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_NO_PINENTRY,
 983  * \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_command(), \ref pinentry
 984  */
 985 LIBPWMD_API gpg_error_t pwmd_save (pwm_t *pwm, const char *args,
 986                                    pwmd_inquire_cb_t callback, void *user);
 987
 988
 989 /*! \brief Change the passphrase for a data file.
 990  *
 991  * This will send the PASSWD command to the server taking care of pinentry
 992  * settings.
 993  *
 994  * The inquire \a callback function should be used when a PASSWD option
 995  * specified in \a args inquires data.
 996  *
 997  * \param pwm A handle.
 998  * \param args Any PASSWD protocol command options or NULL.
 999  * \param callback A callback function to invoke when pwmd inquires data from
1000  * the client.
1001  * \param user User data passed to the \a callback function.
1002  * \return 0 on success or an error code.
1003  * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_NO_PINENTRY,
1004  * \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_command(), \ref pinentry
1005  */
1006 LIBPWMD_API gpg_error_t pwmd_passwd (pwm_t *pwm, const char *args,
1007                                      pwmd_inquire_cb_t callback, void *user);
1008
1009
1010 /*! \brief Send a command to the pwmd server.
1011  *
1012  * You should avoid sending the BYE command here because the assuan context
1013  * will be freed and bad things will happen. Use \ref pwmd_close() instead.
1014  *
1015  * For pwmd commands that use an INQUIRE to retrieve data from a client, the
1016  * \a callback parameter must be non-NULL and will be used to send the data to
1017  * pwmd.
1018  *
1019  * \param pwm A handle.
1020  * \param[out] result The result of the command when successful which must be
1021  * freed with \ref pwmd_free().
1022  * \param[out] len The length of \a result.
1023  * \param callback A callback function to invoke when pwmd inquires data from
1024  * the client.
1025  * \param user User data passed to the \a callback function.
1026  * \param cmd The command to send and any command arguments.
1027  * \return 0 on success or an error code.
1028  *
1029  * \note Not all commands return a \a result.
1030  */
1031 LIBPWMD_API gpg_error_t pwmd_command (pwm_t *pwm, char **result,
1032                                       size_t *len,
1033                                       pwmd_inquire_cb_t callback,
1034                                       void *user, const char *cmd, ...);
1035
1036
1037 /*! \brief Send a command to the pwmd server.
1038  *
1039  * Like \ref pwmd_command() but uses an argument pointer instead.
1040  *
1041  * \param pwm A handle.
1042  * \param[out] result The result of the command when successful which must be
1043  * freed with \ref pwmd_free().
1044  * \param[out] len The length of \a result.
1045  * \param callback A callback function to invoke when pwmd inquires data from
1046  * the client.
1047  * \param user User data passed to the \a callback function.
1048  * \param cmd The command to send.
1049  * \param ap The arguments to \a cmd.
1050  * \return 0 on success or an error code.
1051  *
1052  * \note Not all commands return a \a result.
1053  */
1054 LIBPWMD_API gpg_error_t pwmd_command_ap (pwm_t *pwm, char **result,
1055                                          size_t *len,
1056                                          pwmd_inquire_cb_t callback,
1057                                          void *user, const char *cmd,
1058                                          va_list ap);
1059
1060
1061 /*! \brief Close a connection to the pwmd server.
1062  *
1063  * This will close the connection but keep any previously set options for the
1064  * specified handle \a pwm. Calling \ref pwmd_connect() will re-acquire an
1065  * libassuan context.
1066  *
1067  * \param pwm A handle.
1068  * \return 0 on success or an error code.
1069  * \see \ref pwmd_close()
1070  */
1071 LIBPWMD_API gpg_error_t pwmd_disconnect (pwm_t *pwm);
1072
1073
1074 /*! \brief Close a handle.
1075  *
1076  * This will close the connection to a pwmd server and free any resources
1077  * associated with it.
1078  *
1079  * \param pwm A handle.
1080  * \return Nothing.
1081  * \see \ref pwmd_disconnect(), \ref pwmd_new()
1082  */
1083 LIBPWMD_API void pwmd_close (pwm_t *pwm);
1084
1085
1086 /*! \brief The type of connection a handle has.
1087  *
1088  * Useful when you need to know what kind of connection a handle has.
1089  *
1090  * \param pwm A handle.
1091  * \param[out] type The type of socket.
1092  * \return 0 on success or an error code.
1093  *
1094  * \see \ref pwmd_socket_t
1095  */
1096 LIBPWMD_API gpg_error_t pwmd_socket_type (pwm_t *pwm,
1097                                           pwmd_socket_t * type);
1098
1099 /*! \brief Get the file descriptor associated with a handle.
1100  *
1101  * May be useful to determine whether a handle is ready for reading or
1102  * writing by using select(2) or poll(2).
1103  *
1104  * \param pwm A handle.
1105  * \param[out] fd Set to the file descriptor associated with \a pwm.
1106  * \return 0 on success or an error code.
1107  */
1108 LIBPWMD_API gpg_error_t pwmd_fd (pwm_t *pwm, int *fd);
1109
1110
1111 /*! \brief Free a previously allocated pointer.
1112  *
1113  * Use this function to free resources allocated by the other libpwmd memory
1114  * functions. Do not use it to free allocations made by other allocators.
1115  *
1116  * The difference between the standard free() and this function is that
1117  * this one will zero out the contents of the pointer before freeing it.
1118  *
1119  * \param ptr The pointer to deallocate.
1120  * \return Nothing.
1121  * \see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(),
1122  * pwmd_command()
1123  */
1124 LIBPWMD_API void pwmd_free (void *ptr);
1125
1126
1127 /*! \brief A wrapper around malloc.
1128  *
1129  * Like malloc(), but lets libpwmd keep track of the pointer.
1130  *
1131  * \param size The number of bytes to allocate.
1132  * \return A newly allocated pointer or NULL if there wasn't enough memory.
1133  * \see malloc(3), pwmd_free()
1134  */
1135 LIBPWMD_API void *pwmd_malloc (size_t size);
1136
1137
1138 /*! \brief A wrapper around calloc().
1139  *
1140  * Like calloc(), but lets libpwmd keep track of the pointer.
1141  *
1142  * \param nmemb The number of elements to allocate.
1143  * \param size The number of bytes to allocate.
1144  * \return A newly allocated pointer or NULL if there wasn't enough memory.
1145  * \see calloc(3), pwmd_free()
1146  */
1147 LIBPWMD_API void *pwmd_calloc (size_t nmemb, size_t size);
1148
1149
1150 /*! \brief A wrapper around realloc().
1151  *
1152  * Like realloc(), but lets libpwmd keep track of the pointer.
1153  *
1154  * \param ptr The pointer to reallocate.
1155  * \param size The new number of bytes to allocate.
1156  * \return A newly allocated pointer or NULL if there wasn't enough memory.
1157  * \see realloc(3), pwmd_free()
1158  */
1159 LIBPWMD_API void *pwmd_realloc (void *ptr, size_t size);
1160
1161
1162 /*! \brief A wrapper around strdup().
1163  *
1164  * Like strdup(), but lets libpwmd keep track of the pointer.
1165  *
1166  * \param str The string to duplicate.
1167  * \return A newly allocated character pointer or NULL if there wasn't
1168  * enough memory.
1169  * \see strdup(3), pwmd_free()
1170  */
1171 LIBPWMD_API char *pwmd_strdup (const char *str);
1172
1173
1174 /*! \brief Duplicate a formatted string.
1175  *
1176  * Like \ref asprintf(3), but lets libpwmd keep track of the pointer.
1177  *
1178  * \param fmt The formatted string and any following arguments.
1179  * \return A newly allocated character pointer or NULL if there wasn't
1180  * enough memory.
1181  * \see pwmd_free()
1182  */
1183 LIBPWMD_API char *pwmd_strdup_printf (const char *fmt, ...);
1184
1185 #ifdef __cplusplus
1186 }
1187 #endif
1188
1189 #endif