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