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