src/libpwmd.h.in

   1 /* vim:tw=78:ts=8:sw=4:set ft=c:  */
   2 /*
   3     Copyright (C) 2006-2009 Ben Kibbey <bjk@luxsci.net>
   4
   5     This program is free software; you can redistribute it and/or modify
   6     it under the terms of the GNU General Public License as published by
   7     the Free Software Foundation; either version 2 of the License, or
   8     (at your option) any later version.
   9
  10     This program is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU General Public License for more details.
  14
  15     You should have received a copy of the GNU General Public License
  16     along with this program; if not, write to the Free Software
  17     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02110-1301  USA
  18 */
  19 /*! \headerfile libpwmd.h
  20  *
  21  * libpwmd is a library making it easy for applications to use the pwmd
  22  * server. Pwmd version 2.0 or later is required; either locally or remotely.
  23  */
  24
  25 /*! \section threads Multiple Threads
  26  *
  27  * \ref libpwmd should be thread-safe on a per handle bases. Meaning that only
  28  * one thread should access a \ref pwm_t handle at a time.
  29  *
  30  * There is a limitation that when compiled with \ref pth(3) support SSH
  31  * connections cannot make use of the \ref pth(3) IO functions and therefore
  32  * will block while waiting on IO operations in other threads (as of libssh2
  33  * 1.2.8).
  34  */
  35
  36 /*! \section ssh SSH Details
  37  *
  38  * A remote connection to a pwmd server is possible by using an SSH channel
  39  * which spawns a shell and executes a proxy server that connects to the pwmd
  40  * local Unix Domain Socket. Authentication is done by using SSH public key
  41  * (see \ref ssh-keygen(1)) authentication and verifying the host key against
  42  * a local OpenSSH known hosts formatted file.
  43  *
  44  * The servers public key can be had by using \ref pwmd_get_hostkey() and
  45  * storing the result in a file or done automatially by using a callback
  46  * function \ref pwmd_knownhost_cb_t while connecting to the unknown host.
  47  *
  48  * On the server side you'll need a proxy server to connect to the real pwmd
  49  * server. Here's an example \ref authorized_keys(5) entry that will do this.
  50  * The \a public_key portion should be the same as the contents of the
  51  * generated \ref ssh-keygen(1) \a identity.pub file which is passed as a
  52  * parameter to the SSH connection functions:
  53  *
  54  * \code
  55  * command="socat UNIX-CONNECT:$HOME/.pwmd/socket -" <public_key> ...
  56  * \endcode
  57  *
  58  * \note Only an SSH identity without a passphrase is supported. For now
  59  * anyway. This is a limitation of libssh2 (version 1.1 as of this writing).
  60  *
  61  * \version 6.0.3
  62  * The first version to use the OpenSSH known hosts file format exclusively.
  63  * Earlier versions used only an SHA1 hash of the host key.
  64  *
  65  * \x11
  66  */
  67
  68 /*! \section pinentry Pinentry Details
  69  *
  70  * \ref pinentry(1) is a program that prompts the user for input which is
  71  * normally a passphrase or a confirmation. libpwmd can use this program
  72  * either locally (X11 forwarding is not yet supported) or have the pwmd
  73  * server use it's pinentry to retrieve a passphrase when needed. How this is
  74  * done depends what function gets called and whether the pwmd connection is
  75  * over an SSH channel.
  76  *
  77  * There are a few options that tell pinentry how and where to prompt for a
  78  * needed passphrase. See the \ref pwmd_option_t section for details. These
  79  * options are not sent (when using pwmd's pinentry, not the local one) until
  80  * the pinentry is needed.
  81  *
  82  * If using a local pinentry by calling \ref pwmd_open2(), \ref pwmd_save2(),
  83  * \ref pwmd_open_async2() or pwmd_save_async2(), libpwmd will send the
  84  * command "SET ENABLE_PINENTRY=0" to the pwmd server. This is needed so pwmd
  85  * wont try to launch it's own pinentry on passphrase or confirmation failure.
  86  * So you may need to reset this option manually depending on your needs;
  87  * especially when changing pinentry methods when doing a save (the passphrase
  88  * may be set as empty since the remote pinentry is disabled!).
  89  *
  90  * Some pinentry options can also be specified in a local configuration file
  91  * \a "~/.pwmd/pinentry.conf". These options are initial values for each
  92  * pinentry invokation (not retries) and may be changed by setting the
  93  * appropriate \ref pwmd_option_t. Each option and value is separated with a
  94  * '=' on a single line. Unrecognized options are ignored. Here are the
  95  * recognized options:
  96  *
  97  * \param PATH The full path to the location of the pinentry binary.
  98  * \param DISPLAY The X11 display to use.
  99  * \param TTYNAME The full path to the tty that pinentry should prompt on.
 100  * \param TTYTYPE The terminal type of the tty which is required if DISPLAY is
 101  * not set.
 102  *
 103  * \filepath
 104  *
 105  * \note The initial values for the pinentry TTY, TERM and DISPLAY are set
 106  * during \ref pwmd_new() depending on the current environment. They may need
 107  * to be reset as needed.
 108  *
 109  * \note After establishing an SSH connection, the pwmd pinentry is disabled
 110  * by sending the command "SET ENABLE_PINENTRY=0". This is needed because
 111  * there currently isn't a way to have the remote pinentry use the local
 112  * display.  You must be careful to use either a local pinentry or set a
 113  * passphrase manually with \ref pwmd_setopt() when a passphrase is required
 114  * or needed.
 115  *
 116  * \x11
 117  *
 118  * \see \ref ssh
 119  */
 120
 121 /*! \section Errors
 122  *
 123  * libpwmd uses libgpg-error for all error codes.  Some are user defined
 124  * GPG_ERR_USER_N codes, but most are reused from the existing ones.  Error
 125  * codes can be described by using \ref pwmd_strerror(), or the thread-safe
 126  * \ref pwmd_strerror_r().
 127  *
 128  * \note libgpg-error normally returns an error code as a bitmask of an error
 129  * source and the actual error code. In order to simplify the result codes,
 130  * libpwmd strips any error source from the error code before returning it.
 131  */
 132
 133 /*! \file */
 134 #ifndef LIBPWMD_H
 135 #define LIBPWMD_H
 136
 137 #ifndef LIBPWMD_API
 138 #define LIBPWMD_API
 139 #endif
 140
 141 #include <gpg-error.h>
 142 #include <stdarg.h>
 143
 144 #ifdef __cplusplus
 145 extern "C" {
 146 #endif
 147
 148 /*! \def LIBPWMD_VERSION
 149  * \brief Version information.
 150  *
 151  * The version of this library.
 152  */
 153 #define LIBPWMD_VERSION 0x@VER_MAJOR@@VER_MINOR@@VER_PATCH@
 154
 155
 156 /*! \def LIBPWMD_VERSION_MAJOR
 157  * \brief Version information.
 158  *
 159  * The major release number of this library.
 160  */
 161 #define LIBPWMD_VERSION_MAJOR @VER_MAJOR@
 162
 163
 164 /*! \def LIBPWMD_VERSION_MINOR
 165  * \brief Version information.
 166  *
 167  * The minor release number of this library.
 168  */
 169 #define LIBPWMD_VERSION_MINOR @VER_MINOR@
 170
 171
 172 /*! \def LIBPWMD_VERSION_PATCH
 173  * \brief Version information.
 174  *
 175  * The patch level of this library.
 176  */
 177 #define LIBPWMD_VERSION_PATCH @VER_PATCH@
 178
 179
 180 /*! \def LIBPWMD_VERSION_STR
 181  * \brief Version information.
 182  *
 183  * A string representation of the version of this library.
 184  */
 185 #define LIBPWMD_VERSION_STR @VER_STRING@
 186
 187
 188 /*! \brief Returns this version of libpwmd.
 189  *
 190  * As a string.
 191  * \return A string.
 192  */
 193 LIBPWMD_API const char *pwmd_version();
 194
 195
 196 struct pwm_s;
 197 /*! \typedef pwm_t
 198  * \brief libpwmd handle.
 199  *
 200  * When a handle is mentioned in this documentation it is a pointer of this
 201  * type. A new handle is created with \ref pwmd_new().
 202  */
 203 typedef struct pwm_s pwm_t;
 204
 205
 206 /*! \typedef pwmd_async_t
 207  * \brief Asynchronous return value.
 208  *
 209  * The return code of \ref pwmd_process() which is used for all asynchronous
 210  * commands.
 211  */
 212 typedef enum {
 213     /*! \internal */
 214     ASYNC_INIT,
 215
 216     /*! \ref pwmd_process() should be called again. */
 217     ASYNC_PROCESS,
 218
 219     /*! The command has completed. The result code should be checked for an
 220      * error. */
 221     ASYNC_DONE,
 222 } pwmd_async_t;
 223
 224
 225 /*! \typedef pwmd_ip_version_t
 226  * \brief IP protocol version for remote SSH connections.
 227  *
 228  * The value of the option \ref PWMD_OPTION_IP_VERSION which is set with \ref
 229  * pwmd_setopt().
 230  */
 231 typedef enum {
 232     /*! Try both IPv4 and IPv6 addresses. Note that IPv6 is tried first and
 233      * that \ref PWMD_IP_ANY only affects a hostname and not an IP address in
 234      * the address specification. */
 235     PWMD_IP_ANY,
 236
 237     /*! Only try IPv4. */
 238     PWMD_IPV4,
 239
 240     /*! Only try IPv6. */
 241     PWMD_IPV6
 242 } pwmd_ip_version_t;
 243
 244
 245 /*! \def PWMD_FD_READABLE
 246  * \brief For use with \ref pwmd_get_fds().
 247  *
 248  * Set when the file descriptor is readable.
 249  */
 250 #define PWMD_FD_READABLE        0x01
 251
 252
 253 /*! \def PWMD_FD_WRITABLE
 254  * \brief For use with \ref pwmd_get_fds().
 255  *
 256  * Set when the file descriptor is writable.
 257  */
 258 #define PWMD_FD_WRITABLE        0x02
 259
 260
 261 /*! For use with \ref pwmd_get_fds(). */
 262 typedef struct {
 263     /*! The file descriptor. */
 264     int fd;
 265
 266     /*! A bitmask of \ref PWMD_FD_READABLE and \ref PWMD_FD_WRITABLE. */
 267     unsigned flags;
 268 } pwmd_fd_t;
 269
 270
 271 /*! \typedef pwmd_socket_t
 272  * \brief The type of socket a handle is connected to.
 273  *
 274  * For use with \ref pwmd_socket_type().
 275  */
 276 typedef enum {
 277     /*! A local domain socket. */
 278     PWMD_SOCKET_LOCAL,
 279
 280     /*! An SSH connection over a TCP socket. */
 281     PWMD_SOCKET_SSH
 282 } pwmd_socket_t;
 283
 284
 285 /*! \typedef pwmd_pinentry_t
 286  * \brief Local pinentry commands and not pwmd pinentry.
 287  *
 288  * For use with \ref pwmd_getpin().
 289  */
 290 typedef enum {
 291     /*! When opening a file. */
 292     PWMD_PINENTRY_OPEN,
 293
 294     /*! When opening a file failed. */
 295     PWMD_PINENTRY_OPEN_FAILED,
 296
 297     /*! When saving a file. */
 298     PWMD_PINENTRY_SAVE,
 299
 300     /*! For passphrase confirmation. */
 301     PWMD_PINENTRY_SAVE_CONFIRM,
 302
 303     /*! For confirmation of a user-defined prompt. */
 304     PWMD_PINENTRY_CONFIRM,
 305
 306     /*! For the default or user defined string set with \ref
 307      * PWMD_OPTION_PINENTRY_DESC. */
 308     PWMD_PINENTRY_DEFAULT,
 309
 310     /*! To terminate the pinentry process created with \ref pwmd_getpin(). */
 311     PWMD_PINENTRY_CLOSE
 312 } pwmd_pinentry_t;
 313
 314
 315 /*! \typedef pwmd_passphrase_cb_t
 316  * \brief Custom passphrase retrieval function.
 317  *
 318  * The value of the option \ref PWMD_OPTION_PASSPHRASE_CB which is set with
 319  * \ref pwmd_setopt().
 320  *
 321  * \param user A user data pointer which is set with \ref
 322  * PWMD_OPTION_PASSPHRASE_DATA.
 323  * \param[out] passphrase The passphrase which may be an empty string or NULL.
 324  * It is not modified by libpwmd but must remain allocated for as long as it
 325  * is needed.
 326  * \return 0 on success or an error code which will cause a command to fail.
 327  */
 328 typedef gpg_error_t (*pwmd_passphrase_cb_t)(void *user, char **passphrase);
 329
 330
 331 /*! \typedef pwmd_status_cb_t
 332  * \brief Process status messages.
 333  *
 334  * The value of the option \ref PWMD_OPTION_STATUS_CB which is set with \ref
 335  * pwmd_setopt().
 336  *
 337  * \param user A user data pointer which is set with \ref
 338  * PWMD_OPTION_STATUS_DATA.
 339  * \param line The status message line received from the server.
 340  * \return 0 on success or an error code which will cause a command to fail.
 341  */
 342 typedef int (*pwmd_status_cb_t)(void *user, const char *line);
 343
 344
 345 /*! \typedef pwmd_inquire_cb_t
 346  * \brief Send data to the pwmd server.
 347  *
 348  * This is a callback function that gets passed to \ref pwmd_inquire(). It is
 349  * used for sending data to the server for commands that need to reply to an
 350  * INQUIRE server response (STORE and IMPORT). The reason for this callback is
 351  * to let the client send as many bytes as it wants rather than the entire
 352  * chunk at once.  It gets called during an internal \ref assuan_transact()
 353  * from an internal inquire callback function which in turn calls this
 354  * function by looping over its return value.
 355  *
 356  * \param user The user data pointer passed to \ref pwmd_inquire().
 357  * \param cmd The same as the \a cmd argument to \ref pwmd_inquire().
 358  * \param rc The result of the last internal call to \ref assuan_send_data()
 359  * which did the sending of the data to the pwmd server. On the first call to
 360  * this callback it's value will always be 0 since no data has been sent yet.
 361  * \param[out] data The next chunk of data to send or NULL.
 362  * \param[out] len The length of \a data or 0.
 363  *
 364  * \retval 0 There is more data to be sent.
 365  * \retval GPG_ERR_CANCELED Cancel the current inquire.
 366  * \retval GPG_ERR_EOF No need to call this function again, the current
 367  * \a line is the last to send.
 368  * \retval code Any other error code which will terminate the INQUIRE.
 369  *
 370  * \note The sent data is processed line-per-line. The line is either newline
 371  * terminated or is buffered until ASSUAN_LINELENGTH bytes have been
 372  * allocated. Any remaining bytes are sent after the INQUIRE has finished.
 373  */
 374 typedef gpg_error_t (*pwmd_inquire_cb_t)(void *user, const char *cmd,
 375         gpg_error_t rc, char **data, size_t *len);
 376
 377
 378 /*! \typedef pwmd_knownhost_cb_t
 379  * \brief Verify a remote SSH connection.
 380  *
 381  * When \ref PWMD_OPTION_KNOWNHOST_CB is set and a the current connections
 382  * host key was not found in the known hosts file, then this callback function
 383  * can be used to confirm the addition of the new host key to the known_hosts
 384  * file.
 385  *
 386  * \param user User data which was set with \ref PWMD_OPTION_KNOWNHOST_DATA.
 387  * \param host The hostname as passed to the connecting function.
 388  * \param key The raw host key. Note that this differs from the format
 389  * returned from \ref pwmd_get_hostkey().
 390  * \param len The host key length.
 391  * \retval 0 Add the host key to the known hosts file.
 392  * \retval GPG_ERR_NOT_CONFIRMED Do not add the host key and abort the
 393  * connection.
 394  *
 395  * \note If the known hosts file cannot be modified do to filesystem
 396  * restrictions when trying to add the new host key, no error is returned.
 397  * Instead the host key is added to the current connections host key cache and
 398  * the connection is considered verified.
 399  *
 400  * \see \ref ssh
 401  */
 402 typedef gpg_error_t (*pwmd_knownhost_cb_t)(void *user, const char *host,
 403         const char *key, size_t len);
 404
 405
 406 /*! \enum pwmd_option_t
 407  * \brief libpwmd options.
 408  *
 409  * Options are set with \ref pwmd_setopt().
 410  *
 411  * \filepath
 412  */
 413 typedef enum {
 414     /*! A custom passphrase retrieval function which, when set, will be used
 415      * instead of \ref pinentry(1). This function will not be used if opening
 416      * a file and the passphrase is cached on the server or the file is a new
 417      * one. The value of this option should be a \ref pwmd_passphrase_cb_t.
 418      *
 419      * \note An empty string as the passphrase is allowed.
 420      */
 421     PWMD_OPTION_PASSPHRASE_CB,
 422
 423     /*! User supplied data which is passed to the custom passphrase function.
 424      * */
 425     PWMD_OPTION_PASSPHRASE_DATA,
 426
 427     /*! A string to use as the passphrase when doing an open or save. When not
 428      * NULL, this option has precedence over \ref PWMD_OPTION_PASSPHRASE_CB.
 429      *
 430      * \note An empty string as the passphrase is allowed.
 431      */
 432     PWMD_OPTION_PASSPHRASE,
 433
 434     /*! An integer value that specifies the number of tries before \ref
 435      * pinentry(1) will give up when opening a file with the wrong supplied
 436      * passphrase. The default is 3.
 437      *
 438      * \note This option has no effect when trying to save a file. The user
 439      * must either cancel the pinentry causing the save to fail or enter the
 440      * correct passphrase during passphrase confirmation.
 441      */
 442     PWMD_OPTION_PINENTRY_TRIES,
 443
 444     /*! A character string value which specifies the full path of the \ref
 445      * pinentry(1) binary. For the local \ref pinentry(1) method, the default
 446      * is specified at compile time.
 447      *
 448      * \see \ref pinentry
 449      */
 450     PWMD_OPTION_PINENTRY_PATH,
 451
 452     /*! A value which specifies the full path to the TTY that \ref pinentry(1)
 453      * will use to prompt on. When set and no DISPLAY is available, \ref
 454      * PWMD_OPTION_PINENTRY_TERM must also be set.
 455      *
 456      * \see \ref pinentry
 457      */
 458     PWMD_OPTION_PINENTRY_TTY,
 459
 460     /*! A value which specifies the terminal type (e.g., vt100) that \ref
 461      * pinentry(1) will use when no X11 display is available.
 462      *
 463      * \see \ref pinentry
 464      */
 465     PWMD_OPTION_PINENTRY_TERM,
 466
 467     /*! A value which specifies the X11 display that \ref pinentry(1) will
 468      * use.
 469      *
 470      * \x11
 471      *
 472      * \see \ref pinentry
 473      */
 474     PWMD_OPTION_PINENTRY_DISPLAY,
 475
 476     /*! A character string that \ref pinentry(1) will use in it's dialog
 477      * window.
 478      */
 479     PWMD_OPTION_PINENTRY_TITLE,
 480
 481     /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
 482     PWMD_OPTION_PINENTRY_PROMPT,
 483
 484     /*! \copydoc PWMD_OPTION_PINENTRY_TITLE */
 485     PWMD_OPTION_PINENTRY_DESC,
 486
 487     /*! For \ref pinentry(1) localization. */
 488     PWMD_OPTION_PINENTRY_LC_CTYPE,
 489
 490     /*! \copydoc PWMD_OPTION_PINENTRY_LC_CTYPE */
 491     PWMD_OPTION_PINENTRY_LC_MESSAGES,
 492
 493     /*! An integer value that specifies the number of seconds \ref pinentry(1)
 494      * will wait for input before timing out and aborting the current command.
 495      * If 0, then no timeout will be used. The default is 30.
 496      */
 497     PWMD_OPTION_PINENTRY_TIMEOUT,
 498
 499     /*! A function of type \ref pwmd_status_cb_t that will process status
 500      * messages received from the pwmd server.
 501      */
 502     PWMD_OPTION_STATUS_CB,
 503
 504     /*! A user data pointer which is passed to the status message function. */
 505     PWMD_OPTION_STATUS_DATA,
 506
 507     /*! The IP version of type \ref pwmd_ip_version_t that \ref
 508      * pwmd_ssh_connect() and \ref pwmd_ssh_connect_async() will use when
 509      * connecting to the remote pwmd server. The default is \ref PWMD_IP_ANY.
 510      *
 511      * \pre_conn_req
 512      */
 513     PWMD_OPTION_IP_VERSION,
 514
 515     /*! A function to confirm an unknown host hash which wasn't found in the
 516      * known hosts file.
 517      *
 518      * \see \ref ssh
 519      */
 520     PWMD_OPTION_KNOWNHOST_CB,
 521
 522     /*! User supplied data which is passed to the known host function.
 523      *
 524      * \see \ref ssh
 525      */
 526     PWMD_OPTION_KNOWNHOST_DATA,
 527
 528     /*! When the total number of bytes to be sent via an INQUIRE is known,
 529      * this should be set so XFER status messages can be parsed correctly.
 530      * When not known or unset, 0 is used as the total argument to the XFER
 531      * status message. This option should be set before each call to
 532      * \ref pwmd_inquire().
 533      *
 534      * \note During the INQUIRE, PWMD_OPTION_STATUS_CB is called after every
 535      * ASSUAN_LINELENGTH bytes have been successfully transferred.
 536      *
 537      * \note This is a libpwmd feature. pwmd itself does not send XFER status
 538      * messages during an INQUIRE. Status messages can be parsed only when
 539      * PWMD_OPTION_STATUS_CB is set.
 540      */
 541     PWMD_OPTION_INQUIRE_TOTAL,
 542
 543     /*! When set to 1, lock the file mutex after opening a file as if the LOCK
 544      * command had been sent.
 545      */
 546     PWMD_OPTION_LOCK_ON_OPEN,
 547
 548     /*! A long integer specifying the number of iterations to encrypt with.
 549      * When -1 then the next save operation will use the current iteration
 550      * setting and no command will be sent to alter it.
 551      */
 552     PWMD_OPTION_ITERATIONS,
 553
 554     /*! A string specifying the cipher to use to encrypt with. See the pwmd(1)
 555      * manual page for available ciphers.
 556      */
 557     PWMD_OPTION_CIPHER,
 558
 559     /*! When 1, tell pwmd that the passphrase is Base64 encoded. pwmd will
 560      * decode the passphrase before encryption and decryption. */
 561     PWMD_OPTION_BASE64,
 562
 563     /*! Use ssh-agent to retrieve private key to authenticate. */
 564     PWMD_OPTION_SSH_AGENT,
 565
 566     /*! When 1, disable pinentry use. This will prevent pwmd and libpwmd from
 567      * using a pinentry. */
 568     PWMD_OPTION_NO_PINENTRY,
 569 } pwmd_option_t;
 570
 571
 572 /*! \def PWMD_FEATURE_PINENTRY
 573  * \hideinitializer
 574  * \brief Pinentry support.
 575  *
 576  * This is for a local pinentry when calling \ref pwmd_open2() and \ref
 577  * pwmd_save2().
 578  */
 579 #define PWMD_FEATURE_PINENTRY   0x0001
 580
 581 /*! \def PWMD_FEATURE_CRACK
 582  * \hideinitializer
 583  * \brief Password quality checking.
 584  *
 585  * A password quality meter is shown when the pinentry supports it.
 586  */
 587 #define PWMD_FEATURE_CRACK      0x0002
 588
 589 /*! \def PWMD_FEATURE_SSH
 590  * \hideinitializer
 591  * \brief Remote connections over an SSH channel.
 592  *
 593  * Refer to \ref ssh for how to get this to work.
 594  */
 595 #define PWMD_FEATURE_SSH        0x0004
 596
 597
 598 /*! \brief libpwmd compile time features.
 599  *
 600  * Useful for clients to determine what features are compiled into libpwmd at
 601  * runtime.
 602  *
 603  * \return A bitmask of features.
 604  */
 605 LIBPWMD_API unsigned int pwmd_features();
 606
 607
 608 /*! \brief Initialize the library.
 609  *
 610  * This function must be the first function called in the library before any
 611  * others. It sets up the memory allocators and internationalization among
 612  * other things.
 613  *
 614  * \return 0 on success or an error code.
 615  */
 616 LIBPWMD_API gpg_error_t pwmd_init(void);
 617
 618
 619 /*! \brief Creates a new handle.
 620  *
 621  * Creates a new handle for use with the other functions.
 622  *
 623  * \param name If not NULL, the name of the application. The application name
 624  * is sent to the pwmd server after successfully connecting.
 625  *
 626  * \return a new handle or NULL if there was not enough memory.
 627  */
 628 LIBPWMD_API pwm_t *pwmd_new(const char *name);
 629
 630
 631 /*! \brief Connect to a local pwmd server.
 632  *
 633  * Connects to a local unix domain socket.
 634  *
 635  * \param pwm A handle.
 636  * \param path The socket path to connect to. If NULL, then a default of
 637  * \a "~/.pwmd/socket" will be used.
 638  * \return 0 on success or an error code.
 639  * \filepath
 640  * \see pwmd_ssh_connect(), pwmd_ssh_connect_async(), pwmd_disconnect()
 641  */
 642 LIBPWMD_API gpg_error_t pwmd_connect(pwm_t *pwm, const char *path);
 643
 644
 645 /*! \brief Establish a remote connection to a pwmd server.
 646  *
 647  * Connects to a pwmd server over an SSH channel.
 648  *
 649  * \param pwm A handle.
 650  * \param host The hostname to connect to or NULL to resume a connection
 651  * previously started with \ref pwmd_get_hostkey().
 652  * \param port The port or -1 for the default of 22.
 653  * \param identity The SSH identity file to use for authentication. This
 654  * should specify the private key. The public key is assumed to be \a
 655  * identity.pub. This parameter is not used if \ref PWMD_OPTION_SSH_AGENT is
 656  * set.
 657  * \param user The username on the SSH server to login as. If NULL then
 658  * invoking username will be used.
 659  * \param known_hosts An OpenSSH known hosts formatted file containing public
 660  * SSH server hashes which may be obtained with \ref pwmd_get_hostkey() or via
 661  * \ref pwmd_knownhost_cb_t during a connection. If NULL, the default of
 662  * \a "~/.ssh/known_hosts" will be used.
 663  * \return 0 on success or an error code.
 664  * \filepath
 665  * \see pwmd_ssh_connect_async(), \ref PWMD_OPTION_IP_VERSION,
 666  * pwmd_disconnect(), \ref ssh
 667  */
 668 LIBPWMD_API gpg_error_t pwmd_ssh_connect(pwm_t *pwm, const char *host,
 669         int port, const char *identity, const char *user, const char
 670         *known_hosts);
 671
 672
 673 /*! \brief Establish a remote connection to a pwmd server (asynchronously).
 674  *
 675  * This is a variant of \ref pwmd_ssh_connect() that will not block while doing
 676  * DNS lookups or while connecting.
 677  *
 678  * \process
 679  *
 680  * \param pwm A handle.
 681  * \param host The hostname to connect to or NULL to resume a connection
 682  * previously started with \ref pwmd_get_hostkey().
 683  * \param port The port or -1 for the default of 22.
 684  * \param identity The SSH identity file to use for authentication. This
 685  * should specify the private key. The public key is assumed to be \a
 686  * identity.pub. This parameter is not used if \ref PWMD_OPTION_SSH_AGENT is
 687  * set.
 688  * \param user The username on the SSH server to login as. If NULL, the
 689  * invoking username will be used.
 690  * \param known_hosts An OpenSSH known hosts formatted file containing public
 691  * SSH server hashes which may be obtained with \ref pwmd_get_hostkey() or via
 692  * \ref pwmd_knownhost_cb_t during a connection. If NULL, the default of
 693  * \a "~/.ssh/known_hosts" will be used.
 694  * \return 0 on success or an error code.
 695  * \filepath
 696  * \see pwmd_process(), \ref PWMD_OPTION_IP_VERSION, pwmd_disconnect(),
 697  * \ref ssh
 698  */
 699 LIBPWMD_API gpg_error_t pwmd_ssh_connect_async(pwm_t *pwm, const char *host,
 700         int port, const char *identity, const char *user, const char
 701         *known_hosts);
 702
 703
 704 /*! \brief Establish a connection by parsing a URL.
 705  *
 706  * This allows for connecting to a pwmd server by parsing the given URL
 707  * string. Whether the connection is to a remote or local server depends on
 708  * the contents:
 709  * \code
 710  * file://[path/to/local/socket]
 711  *
 712  * or
 713  *
 714  * ssh[46]://[username@]hostname[:port][,identity,known_hosts]
 715  * \endcode
 716  *
 717  * The parameters in square brackets are optional and if not specified then
 718  * defaults will be used. If neither socket specification is matched, the
 719  * \a url is assumed to be a file://.
 720  *
 721  * \param pwm A handle.
 722  * \param url The string to parse.
 723  * \filepath
 724  * \return 0 on success or an error code.
 725  * \see \ref pwmd_socket_type(), pwmd_disconnect()
 726  */
 727 LIBPWMD_API gpg_error_t pwmd_connect_url(pwm_t *pwm, const char *url);
 728
 729
 730 /*! \brief Establish a connection by parsing a URL (asynchronously).
 731  *
 732  * This allows for connecting to a pwmd server by parsing the given URL
 733  * string. Whether the connection is to a remote or local server depends on
 734  * the contents:
 735  * \code
 736  * file://[path/to/local/socket]
 737  *
 738  * or
 739  *
 740  * ssh[46]://[username@]hostname[:port][,identity,known_hosts]
 741  * \endcode
 742  *
 743  * The parameters in square brackets are optional and if not specified then
 744  * defaults will be used. If neither socket specification is matched, the
 745  * \a url is assumed to be a file://.
 746  *
 747  * \process
 748  *
 749  * \param pwm A handle.
 750  * \param url The string to parse.
 751  * \filepath
 752  * \return 0 on success or an error code.
 753  * \see \ref pwmd_socket_type(), pwmd_disconnect()
 754  */
 755 LIBPWMD_API gpg_error_t pwmd_connect_url_async(pwm_t *pwm, const char *url);
 756
 757
 758 /*! \brief Retrieve a remote SSH public host key.
 759  *
 760  * This key is needed for host verification of the remote pwmd server. You
 761  * should be sure that the remote host is really the host that your wanting to
 762  * connect to and not subject to a man-in-the-middle attack.
 763  *
 764  * \param pwm A handle.
 765  * \param host The hostname or IP to connect to.
 766  * \param port The port or -1 for the default of 22.
 767  * \param[out] result An OpenSSH known hosts formatted string containing the
 768  * servers public key which should be freed with \ref pwmd_free(). If the
 769  * \a host was a hostname then two newline separated known host entries will
 770  * be returned; one for the hostname and one for the resolved IP address. The
 771  * IP known host entry will always be the second in the string.
 772  * \return 0 on success or an error code.
 773  *
 774  * \version 6.0.3
 775  * The connection is kept open but not verified after returning. It can be
 776  * resumed from one of the SSH connection functions.
 777  *
 778  * \see pwmd_get_hostkey_async(), pwmd_ssh_connect(), \ref ssh
 779  */
 780 LIBPWMD_API gpg_error_t pwmd_get_hostkey(pwm_t *pwm, const char *host, int port,
 781         char **result);
 782
 783
 784 /*! \brief Retrieve a remote SSH host key (asynchronously).
 785  *
 786  * This key is needed for host verification of the remote pwmd server. You
 787  * should be sure that the remote host is really the host that your wanting to
 788  * connect to and not subject to a man-in-the-middle attack.
 789  *
 790  * \process
 791  *
 792  * \param pwm A handle.
 793  * \param host The hostname or IP to connect to.
 794  * \param port The port or -1 for the default of 22.
 795  * \return 0 on success or an error code. The result is obtained from \ref
 796  * pwmd_process() should be freed with \ref pwmd_free(). It has the same
 797  * format as the result from \ref pwmd_get_hostkey().
 798  *
 799  * \version 6.0.3
 800  * The connection is kept open but not verified after returning. It can be
 801  * resumed from one of the SSH connection functions.
 802  *
 803  * \see pwmd_get_hostkey(), pwmd_ssh_connect_async(), \ref pwmd_process(),
 804  * \ref ssh
 805  */
 806 LIBPWMD_API gpg_error_t pwmd_get_hostkey_async(pwm_t *pwm, const char *host,
 807         int port);
 808
 809
 810 /*! \brief Get the associated file descriptor(s) for a handle.
 811  *
 812  * This function lets the application manually poll the available file
 813  * descriptors for the specified handle. It should be called after each
 814  * asynchronous function call and after each call to \ref pwmd_process() since
 815  * the polled file descriptors may have been closed since the previous call.
 816  *
 817  * After returning, \a n_fds is set to the number of available file
 818  * descriptors which are stored in \a fds. The .flags member of \ref pwmd_fd_t
 819  * specifies what can be monitored and is a bitmask of \ref PWMD_FD_READABLE
 820  * and \ref PWMD_FD_WRITABLE. When ready, \ref pwmd_process() should be
 821  * called.
 822  *
 823  * \param pwm A handle.
 824  * \param[out] fds Set to the file descriptor(s) of the associated handle.
 825  * \param[out] n_fds Initially the size of \a fds then updated to the number
 826  * of available file descriptors which are stored in \a fds.
 827  * \retval 0 on success or an error code.
 828  * \retval GPG_ERR_ERANGE There are more file descriptors than the amount
 829  * specified in \a n_fds. \a fds and \a n_fds are still usable though.
 830  * \see pwmd_process()
 831  */
 832 LIBPWMD_API gpg_error_t pwmd_get_fds(pwm_t *pwm, pwmd_fd_t *fds, int *n_fds);
 833
 834
 835 /*! \brief Check for a unparsed buffered line.
 836  *
 837  * A buffered line is a line that was read from the server but has not yet
 838  * been processed. This function determines if there is such a line.
 839  *
 840  * \param pwm A handle.
 841  * \retval 0 if there is a pending line.
 842  * \retval GPG_ERR_NO_DATA if there is no pending line.
 843  * \see pwmd_process()
 844  */
 845 LIBPWMD_API gpg_error_t pwmd_pending_line(pwm_t *pwm);
 846
 847
 848 /*! \brief Set handle options.
 849  *
 850  * See \ref pwmd_option_t for option specific details.
 851  *
 852  * \param pwm A handle.
 853  * \param opt The option and following value.
 854  * \return 0 on success or an error code.
 855  */
 856 LIBPWMD_API gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...);
 857
 858
 859 /*! \brief Launch a local pinentry.
 860  *
 861  * Does not send any command to the server. Maybe useful if a passphrase is
 862  * needed before opening a file over a remote connection. This passphrase can
 863  * then be set with \ref pwmd_setopt().
 864  *
 865  * This function may also be used to display a user confirmation dialog with
 866  * pinentry when \a which is \ref PWMD_PINENTRY_CONFIRM. The text to prompt
 867  * with is set with \ref PWMD_OPTION_PINENTRY_TITLE.
 868  *
 869  * \param pwm A handle.
 870  * \param filename The filename to use in the pinentry dialog strings.
 871  * \param[out] result The entered value in the pinentry dialog which should be
 872  * freed with \ref pwmd_free().
 873  * \param which Determines the default strings shown in the pinentry
 874  * dialog. \ref pwmd_setopt() may also be used to override the defaults. In
 875  * this case \ref PWMD_PINENTRY_DEFAULT should be used. \ref
 876  * PWMD_PINENTRY_CLOSE should be used to terminate the pinentry process when
 877  * the pinentry is no longer needed.
 878  *
 879  * \return 0 on success or an error.
 880  */
 881 LIBPWMD_API gpg_error_t pwmd_getpin(pwm_t *pwm, const char *filename,
 882         char **result, pwmd_pinentry_t which);
 883
 884
 885 /*! \brief Open a file on the pwmd server.
 886  *
 887  * This will send the OPEN command to the server.
 888  *
 889  * \param pwm A handle.
 890  * \param filename The filename to open. The \a filename is not a full path
 891  * but the data file only.
 892  * \return 0 on success or an error code.
 893  * \see \ref pinentry
 894  */
 895 LIBPWMD_API gpg_error_t pwmd_open(pwm_t *pwm, const char *filename);
 896
 897
 898 /*! \brief Open a file on the pwmd server by using a server inquire.
 899  *
 900  * This is a convenience function to the OPEN command using \ref
 901  * pwmd_inquire() in that it passes the OPEN options that were set with \ref
 902  * pwmd_setopt() for you. It uses the specified callback function to retreive
 903  * the passphrase.
 904  *
 905  * \note Only the passphrase should be sent when using this function and not
 906  * any filename argument. That argument will be sent automatically when using
 907  * this function.
 908  *
 909  * \note Pinentry is disabled when using this function.
 910  *
 911  * \param pwm A handle.
 912  * \param filename The filename to open. The \a filename is not a full path
 913  * but the data file only.
 914  * \param func A callback function of type \ref pwmd_inquire_cb_t which sets
 915  * the passphrase to be sent. This acts as a normal \ref pwmd_inquire() would.
 916  * \param user A user data pointer passed to the callback function \a func.
 917  * \return 0 on success or an error code.
 918  * \see \ref PWMD_OPTION_BASE64
 919  */
 920 LIBPWMD_API gpg_error_t pwmd_open_inquire(pwm_t *pwm, const char *filename,
 921         pwmd_inquire_cb_t func, void *user);
 922
 923
 924 /*! \brief Open a file on the pwmd server using a local pinentry.
 925  *
 926  * This will send the OPEN command to the server like \ref pwmd_open() but
 927  * will use the local pinentry and not pwmd's pinentry.
 928  *
 929  * \sigalrm
 930  *
 931  * \note This pinentry method is not thread safe. It needs to set a couple of
 932  * global variables for the pinentry timeout to work properly.
 933  *
 934  * \param pwm A handle.
 935  * \param filename The filename to open. The \a filename is not a full path
 936  * but the data file only.
 937  * \return 0 on success or an error code.
 938  * \retval GPG_ERR_PIN_BLOCKED Another handle is using the local pinentry.
 939  * \see \ref pinentry
 940  */
 941 LIBPWMD_API gpg_error_t pwmd_open2(pwm_t *pwm, const char *filename);
 942
 943
 944 /*! \brief Open a file on the pwmd server asynchronously (fork method).
 945  *
 946  * This is kind of a hybrid of \ref pwmd_open2() and \ref pwmd_open_async().
 947  * It will use the local pinentry asynchronously and also do the OPEN command
 948  * asynchronously.
 949  *
 950  * \process
 951  *
 952  * \sigalrm
 953  *
 954  * \param pwm A handle.
 955  * \param filename The filename to open. The \a filename is not a full path
 956  * but the data file only.
 957  * \return 0 on success or an error code.
 958  * \see pwmd_process(), \ref pinentry
 959  */
 960 LIBPWMD_API gpg_error_t pwmd_open_async2(pwm_t *pwm, const char *filename);
 961
 962
 963 /*! \brief Open a file on the pwmd server (asynchronously).
 964  *
 965  * This will send the OPEN command to the pwmd server. The difference from
 966  * \ref pwmd_open() is that it will not block if a pinentry is needed for
 967  * passphrase input.
 968  *
 969  * \process
 970  *
 971  * \param pwm A handle.
 972  * \param filename The filename to open. The \a filename is not a full path
 973  * but the data file only.
 974  * \return 0 on success or an error code.
 975  * \see pwmd_process(), \ref pinentry
 976  */
 977 LIBPWMD_API gpg_error_t pwmd_open_async(pwm_t *pwm, const char *filename);
 978
 979
 980 /*! \brief Process an asynchronous function.
 981  *
 982  * After an asynchronous function has been called and has returned
 983  * successfully, this function must be called to process the command and
 984  * retrieve the result and return value.
 985  *
 986  * This function may also be called when not in a command to check for pending
 987  * status messages sent from the server or to process a pending line.
 988  *
 989  * \param pwm A handle.
 990  * \param[out] rc Set to the return code of the original command after
 991  * ASYNC_DONE has been returned. This value must be checked to determine if
 992  * the command succeeded.
 993  * \param[out] result Set to the result of the command when \a rc is 0. Note
 994  * that not all commands return a result.
 995  * \retval ASYNC_DONE The command has completed. \a rc should be checked to
 996  * determine if the command was successful or not.
 997  * \retval ASYNC_PROCESS The command is still running and this function should
 998  * be called again.
 999  * \see pwmd_get_fds(), pwmd_pending_line()
1000  */
1001 LIBPWMD_API pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc,
1002         char **result);
1003
1004
1005 /*! \brief Save a file on the pwmd server.
1006  *
1007  * This will send the SAVE command.
1008  *
1009  * \param pwm A handle.
1010  * \return 0 on success or an error code.
1011  * \see \ref pinentry
1012  */
1013 LIBPWMD_API gpg_error_t pwmd_save(pwm_t *pwm);
1014
1015
1016 /*! \brief Save a file on the pwmd server by using a server inquire.
1017  *
1018  * This is a convenience function to the SAVE command using \ref
1019  * pwmd_inquire() in that it passes the SAVE options that were set with \ref
1020  * pwmd_setopt() for you. It uses the specified callback function to retreive
1021  * the passphrase.
1022  *
1023  * \note Pinentry is disabled when using this function.
1024  *
1025  * \param pwm A handle.
1026  * \param func A callback function of type \ref pwmd_inquire_cb_t which sets
1027  * the passphrase to be sent. This acts as a normal \ref pwmd_inquire() would.
1028  * \param user A user data pointer passed to the callback function \a func.
1029  * \return 0 on success or an error code.
1030  * \see \ref PWMD_OPTION_BASE64
1031  */
1032 LIBPWMD_API gpg_error_t pwmd_save_inquire(pwm_t *pwm, pwmd_inquire_cb_t func,
1033         void *user);
1034
1035
1036 /*! \brief Save a file on the pwmd server using the local pinentry.
1037  *
1038  * This will send the SAVE command like \ref pwmd_save() but will use a local
1039  * pinentry and not pwmd's pinentry.
1040  *
1041  * \param pwm A handle.
1042  * \return 0 on success or an error code.
1043  * \see \ref pinentry
1044  */
1045 LIBPWMD_API gpg_error_t pwmd_save2(pwm_t *pwm);
1046
1047
1048 /*! \brief Save a file on the pwmd server asynchronously (fork method).
1049  *
1050  * This is kind of a hybrid of \ref pwmd_save2() and \ref pwmd_save_async().
1051  * It will use the local pinentry asynchronously and also do the SAVE command
1052  * asynchronously.
1053  *
1054  * \process
1055  *
1056  * \param pwm A handle.
1057  * \return 0 on success or an error code.
1058  * \see pwmd_process(), \ref pinentry
1059  */
1060 LIBPWMD_API gpg_error_t pwmd_save_async2(pwm_t *pwm);
1061
1062
1063 /*! \brief Save changes to a file on the pwmd server (asynchronously).
1064  *
1065  * This will send the SAVE command to the pwmd server. The difference from
1066  * \ref pwmd_save() is that it will not block if a pinentry is needed for
1067  * passphrase input.
1068  *
1069  * \process
1070  *
1071  * \param pwm A handle.
1072  * \return 0 on success or an error code.
1073  * \see pwmd_process(), \ref pinentry
1074  */
1075 LIBPWMD_API gpg_error_t pwmd_save_async(pwm_t *pwm);
1076
1077
1078 /*! \brief Send a command to the pwmd server.
1079  *
1080  * Sends a command to the pwmd server. You should avoid sending the BYE
1081  * command here because the assuan context will be freed and bad things will
1082  * happen. Use \ref pwmd_close() instead. For commands that use an INQUIRE to
1083  * send data to the server (STORE and IMPORT), \ref pwmd_inquire() must be
1084  * used and not this function.
1085  *
1086  * \param pwm A handle.
1087  * \param[out] result The result of the command when successful which must be
1088  * freed with \ref pwmd_free().
1089  * \param cmd The command to send and any following arguments.
1090  * \return 0 on success or an error code.
1091  *
1092  * \note Not all commands return a result.
1093  */
1094 LIBPWMD_API gpg_error_t pwmd_command(pwm_t *pwm, char **result,
1095         const char *cmd, ...);
1096
1097
1098 /*! \brief Send a command to the pwmd server.
1099  *
1100  * Like \ref pwmd_command() but uses an argument pointer instead.
1101  *
1102  * \param pwm A handle.
1103  * \param[out] result The result of the command when successful which must be
1104  * freed with \ref pwmd_free().
1105  * \param cmd The command to send.
1106  * \param ap The arguments to \a cmd.
1107  * \return 0 on success or an error code.
1108  *
1109  * \note Not all commands return a result.
1110  */
1111 LIBPWMD_API gpg_error_t pwmd_command_ap(pwm_t *pwm, char **result,
1112         const char *cmd, va_list ap);
1113
1114
1115 /*! \brief Send data to a pwmd server.
1116  *
1117  * This lets commands that use an INQUIRE (STORE and IMPORT) send the data
1118  * to the server. Use this function rather than \ref pwmd_command() for these
1119  * pwmd commands.
1120  *
1121  * \param pwm A handle.
1122  * \param cmd The \ref pwmd(1) command to send including any options.
1123  * \param func A callback function of type \ref pwmd_inquire_cb_t which sets
1124  * the data to be sent.
1125  * \param user A user data pointer passed to the callback function \a func.
1126  * \return 0 on success or an error code.
1127  *
1128  * \see pwmd_inquire_cb_t
1129  */
1130 LIBPWMD_API gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd,
1131         pwmd_inquire_cb_t func, void *user);
1132
1133
1134 /*! \brief Close a connection to the pwmd server.
1135  *
1136  * This will close the connection but keep any previously set options for the
1137  * specified handle.
1138  *
1139  * \param pwm A handle.
1140  * \return 0 on success or an error code.
1141  * \see \ref pwmd_close()
1142  */
1143 LIBPWMD_API gpg_error_t pwmd_disconnect(pwm_t *pwm);
1144
1145
1146 /*! \brief Close a handle.
1147  *
1148  * This will close the connection to a pwmd server and free any resources
1149  * associated with it.
1150  *
1151  * \param pwm A handle.
1152  * \return Nothing.
1153  * \see \ref pwmd_disconnect(), \ref pwmd_new()
1154  */
1155 LIBPWMD_API void pwmd_close(pwm_t *pwm);
1156
1157
1158 /*! \brief The type of connection a handle has.
1159  *
1160  * Useful when you want to know what kind of connection a handle has.
1161  *
1162  * \param pwm A handle.
1163  * \param[out] type The type of socket.
1164  * \return 0 on success or an error code.
1165  * \see pwmd_connect_url()
1166  */
1167 LIBPWMD_API gpg_error_t pwmd_socket_type(pwm_t *pwm, pwmd_socket_t *type);
1168
1169
1170 /*! \brief Free a previously allocated pointer.
1171  *
1172  * Use this function to free resources allocated by the other libpwmd memory
1173  * functions. Do not use it to free allocations made by other allocators.
1174  *
1175  * The difference between the standard free() and this function is that
1176  * this one will zero out the contents of the pointer before freeing it.
1177  *
1178  * \param ptr The pointer to deallocate.
1179  * \return Nothing.
1180  * \see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(),
1181  * pwmd_process(), pwmd_command()
1182  */
1183 LIBPWMD_API void pwmd_free(void *ptr);
1184
1185
1186 /*! \brief A wrapper around malloc.
1187  *
1188  * Like malloc(), but lets libpwmd keep track of the pointer.
1189  *
1190  * \param size The number of bytes to allocate.
1191  * \return A newly allocated pointer or NULL if there wasn't enough memory.
1192  * \see malloc(3), pwmd_free()
1193  */
1194 LIBPWMD_API void *pwmd_malloc(size_t size);
1195
1196
1197 /*! \brief A wrapper around calloc().
1198  *
1199  * Like calloc(), but lets libpwmd keep track of the pointer.
1200  *
1201  * \param nmemb The number of elements to allocate.
1202  * \param size The number of bytes to allocate.
1203  * \return A newly allocated pointer or NULL if there wasn't enough memory.
1204  * \see calloc(3), pwmd_free()
1205  */
1206 LIBPWMD_API void *pwmd_calloc(size_t nmemb, size_t size);
1207
1208
1209 /*! \brief A wrapper around realloc().
1210  *
1211  * Like realloc(), but lets libpwmd keep track of the pointer.
1212  *
1213  * \note This function will try and allocate the entire \a size before freeing
1214  * the original pointer and returning the new one.
1215  *
1216  * \param ptr The pointer to reallocate.
1217  * \param size The new number of bytes to allocate.
1218  * \return A newly allocated pointer or NULL if there wasn't enough memory.
1219  * \see realloc(3), pwmd_free()
1220  */
1221 LIBPWMD_API void *pwmd_realloc(void *ptr, size_t size);
1222
1223
1224 /*! \brief A wrapper around strdup().
1225  *
1226  * Like strdup(), but lets libpwmd keep track of the pointer.
1227  *
1228  * \param str The string to duplicate.
1229  * \return A newly allocated character pointer or NULL if there wasn't
1230  * enough memory.
1231  * \see strdup(3), pwmd_free()
1232  */
1233 LIBPWMD_API char *pwmd_strdup(const char *str);
1234
1235
1236 /*! \brief Duplicate a formatted string.
1237  *
1238  * Like \ref sprintf(3) but returns an allocated string.
1239  *
1240  * \param fmt The formatted string and any following arguments.
1241  * \return A newly allocated character pointer or NULL if there wasn't
1242  * enough memory.
1243  * \see pwmd_free()
1244  */
1245 LIBPWMD_API char *pwmd_strdup_printf(const char *fmt, ...);
1246
1247
1248 /*! \def EPWMD_NO_FILE
1249  * \hideinitializer
1250  * \brief No data file has been opened.
1251  *
1252  * Some commands don't require an open data file but most do.
1253  */
1254 #define EPWMD_NO_FILE           GPG_ERR_USER_1
1255
1256
1257 /*! \def EPWMD_LIBXML_ERROR
1258  * \hideinitializer
1259  * \brief libxml2 error.
1260  *
1261  * This can be a memory allocation error or a parse error. The details of the
1262  * error cannot be obtained with libpwmd. You'd have to connect to the pwmd
1263  * socket and do the command directly to get the actual error.
1264  */
1265 #define EPWMD_LIBXML_ERROR      GPG_ERR_USER_2
1266
1267
1268 /*! \def EPWMD_FILE_MODIFIED
1269  * \hideinitializer
1270  * \brief The data file has been modified.
1271  *
1272  * Rather than process the next command this error is returned to prevent
1273  * overwriting new data which may have been saved by another client.
1274  */
1275 #define EPWMD_FILE_MODIFIED     GPG_ERR_USER_3
1276
1277
1278 /*! \def EPWMD_MAX
1279  * \hideinitializer
1280  * \if cond1
1281  * \internal
1282  * \endif
1283  * \brief libgpg-error error code offset.
1284  *
1285  * If you use your own libgpg-error codes then this should be the base of
1286  * them.
1287  */
1288 #define EPWMD_MAX               GPG_ERR_USER_4
1289
1290
1291 /*! \brief Return a description of an error code.
1292  *
1293  * \param code The error code to describe.
1294  * \return A character description of the error code.
1295  * \see pwmd_strerror_r()
1296  */
1297 LIBPWMD_API const char *pwmd_strerror(gpg_error_t code);
1298
1299
1300 /*! \brief Return a description of an error code (thread-safe).
1301  *
1302  * This is a thread-safe version of \ref pwmd_strerror().
1303  *
1304  * \param code The error code to describe.
1305  * \param[out] buf An allocated buffer to hold the error description.
1306  * \param size The size of the allocated buffer \a buf.
1307  *
1308  * \retval 0 Success.
1309  * \retval ERANGE \a size was not large enough to hold the entire description
1310  * and \a buf is set to the truncated error string.
1311  */
1312 LIBPWMD_API int pwmd_strerror_r(gpg_error_t code, char *buf, size_t size);
1313
1314 #ifdef __cplusplus
1315 }
1316 #endif
1317
1318 #endif