src/libpwmd.h.in

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