Fix Coverity issue #100363.

[libpwmd.git] / src / libpwmd.h.in

/* vim:tw=78:ts=8:sw=4:set ft=c:  */
/*
    Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013
    Ben Kibbey <bjk@luxsci.net>

    This file is part of libpwmd.

    Libpwmd is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 2 of the License, or
    (at your option) any later version.

    Libpwmd is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Libpwmd.  If not, see <http://www.gnu.org/licenses/>.
*/
/*! \headerfile libpwmd.h
 *
 * libpwmd is a library making it easy for applications to use the pwmd
 * server. Pwmd version 3.0 or later is required; either locally or remotely.
 */

/*! \section threads Threads
 *
 * \ref libpwmd should be thread-safe on a per handle bases. Meaning that only
 * one thread should access a \ref pwm_t handle at a time.
 */

/*! \section remote Remote Connection Details
 *
 * There are two methods of connecting to a remote pwmd server: over SSH
 * and over TLS.
 *
 * Connections over SSH are done by creating an SSH channel to spawn a
 * shell that executes a proxy server to connect to the pwmd local
 * Unix Domain Socket. Authentication is done by using SSH public key
 * (see \ref ssh-keygen(1)) authentication and verifying the host key
 * against a local OpenSSH known hosts formatted file.
 *
 * An unknown servers public key can be added to a known hosts file after user
 * confirmation by setting the callback function \ref pwmd_knownhost_cb_t
 * before connecting to the unknown host.
 *
 * On the server side you'll need a proxy server to connect to the pwmd
 * server. Below is an example of an \ref authorized_keys(5) entry that will
 * do this.  The \a public_key portion should be the same as the contents of
 * the \ref ssh-keygen(1) \a identity.pub file generated on the client
 * machine. The private key should be passed as the \a identity parameter to
 * \ref pwmd_connect():
 *
 * \code
 * command="socat UNIX-CONNECT:$HOME/.pwmd/socket -" <public_key> ...
 * \endcode
 *
 * \note Only an SSH identity without a passphrase is supported. For now
 * anyway. This is a limitation of libssh2 (version 1.2.8 as of this writing).
 *
 * \version 6.0.3
 * The first version to use the OpenSSH known hosts file format exclusively.
 * Earlier versions used only an SHA1 hash of the host key.
 *
 * Pwmd itself can accept TLS connections so no proxy program is
 * needed as is when using SSH. Like SSH connections, TLS connections
 * are created with \ref pwmd_connect(). You will need to generate a
 * client key and X509 certificate and then sign it with the same
 * certificate authority (CA) that the pwmd server certificate was
 * signed with.
 *
 * Certificates are similar to SSH public and private keys but a little harder
 * to setup correctly. See the \ref certtool(1) (recommended) and \ref
 * openssl(1) manual pages for details.
 */

/*! \section pinentry Pinentry Details
 *
 * \ref pinentry(1) is a program that prompts the user for input which is
 * normally a passphrase or a confirmation. libpwmd can use this program
 * either locally (X11 forwarding is not yet supported) or have the pwmd
 * server or gpg-agent use it's pinentry to retrieve a passphrase when
 * needed.
 *
 * There are a few options that tell pinentry how and where to prompt for a
 * needed passphrase. See the \ref pwmd_option_t section for details. These
 * options are only sent to pwmd in \ref pwmd_open() and only when pinentry
 * use has not been disabled and when not over an remote connnection.
 *
 * Some pinentry options may also be specified in the local configuration file
 * \a "~/.pwmd/pinentry.conf". These options are initial values for each
 * pinentry invokation (not retries) and may be changed by setting the
 * appropriate \ref pwmd_option_t. Options and values are separated with a '='
 * on a single line. Unrecognized options are ignored. Here are the recognized
 * options:
 *
 * \param PATH The full path to the location of the pinentry binary. Only
 * useful for the local pinentry.
 * \param DISPLAY The X11 display to use.
 * \param TTYNAME The full path to the tty that pinentry should prompt on.
 * \param TTYTYPE The terminal type of the tty which is required if DISPLAY is
 * not set.
 * \param LC_MESSAGES Adjust for the current locale.
 * \param LC_CTYPE Adjust for the current locale.
 *
 * \filepath
 *
 * \note The initial values for the pinentry TTY, TERM and DISPLAY are set
 * during \ref pwmd_new() depending on the current environment. They can be
 * reset or changed as needed.
 *
 * \note After establishing a remote connection, pwmd's pinentry is disabled
 * by passing the "--no-pinentry" option to the OPEN protocol command during
 * \ref pwmd_open() since X11 forwarding has not been implemented. A local
 * pinentry will be used in the case of a remote connection.
 *
 * \see \ref remote
 */

/*! \section Errors
 *
 * libpwmd uses libgpg-error for all error codes.  Error codes can be
 * described by using \ref gpg_strerror(), or the thread-safe \ref
 * gpg_strerror_r().
 *
 * \note libgpg-error returns an error code as a bitmask of an error source
 * and the error code. Determining the error source can help you find where
 * the error occured, beit from \ref pinentry(1), \ref gpg-agent(1), \ref
 * libgcrypt, \ref pwmd(1) or \ref libpwmd(3). pwmd uses the \ref
 * GPG_ERR_SOURCE_USER_1 error source and libpwmd uses \ref
 * GPG_ERR_SOURCE_USER_2. To find the error source of an error code the \ref
 * gpg-error(1) command line utility may be of use. Also see the \ref
 * libgpg-error documentation for error code manipulation.
 */

/*! \file */
#ifndef LIBPWMD_H
#define LIBPWMD_H

#ifndef LIBPWMD_API
#define LIBPWMD_API
#endif

#ifdef GPG_ERR_SOURCE_DEFAULT
#error "GPG_ERR_SOURCE_DEFAULT already defined."
#else
#define GPG_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_2
#endif
#include <gpg-error.h>
#include <stdarg.h>

#ifdef __cplusplus
extern "C"
{
#endif

/*! \def LIBPWMD_VERSION
 * \brief Version information.
 *
 * The version of this library.
 */
#define LIBPWMD_VERSION 0x@VER_MAJOR_HEX@@VER_MINOR_HEX@@VER_PATCH_HEX@


/*! \def LIBPWMD_VERSION_MAJOR
 * \brief Version information.
 *
 * The major release number of this library.
 */
#define LIBPWMD_VERSION_MAJOR @VER_MAJOR@


/*! \def LIBPWMD_VERSION_MINOR
 * \brief Version information.
 *
 * The minor release number of this library.
 */
#define LIBPWMD_VERSION_MINOR @VER_MINOR@


/*! \def LIBPWMD_VERSION_PATCH
 * \brief Version information.
 *
 * The patch level of this library.
 */
#define LIBPWMD_VERSION_PATCH @VER_PATCH@


/*! \def LIBPWMD_VERSION_STR
 * \brief Version information.
 *
 * A string representation of the version of this library.
 */
#define LIBPWMD_VERSION_STR @VER_STRING@


/*! \brief Returns this version of libpwmd.
 *
 * As a string.
 * \return A string.
 */
LIBPWMD_API const char *pwmd_version ();


struct pwm_s;
/*! \typedef pwm_t
 * \brief A libpwmd handle.
 *
 * When a pwmd handle or context is mentioned in this documentation it
 * is a pointer of this type. A new handle is created with \ref
 * pwmd_new().
 */
typedef struct pwm_s pwm_t;


/*! \typedef pwmd_socket_t
 * \brief The type of socket a handle is connected to.
 *
 * For use with \ref pwmd_socket_type().
 */
typedef enum
{
  /*! A local UNIX domain socket. */
  PWMD_SOCKET_LOCAL,

  /*! An SSH channel over a TCP socket. */
  PWMD_SOCKET_SSH,

  /*! A TLS connection over a TCP socket. */
  PWMD_SOCKET_TLS
} pwmd_socket_t;


/*! \typedef pwmd_pinentry_t
 * \brief Local pinentry commands and not pwmd pinentry.
 *
 * These determine what prompt a local or fork()'ed pinentry uses. For use
 * with \ref pwmd_getpin().
 */
typedef enum
{
  /*! When opening a file. */
  PWMD_PINENTRY_OPEN,

  /*! When opening a file failed due to a bad passphrase. */
  PWMD_PINENTRY_OPEN_FAILED,

  /*! When saving a file. */
  PWMD_PINENTRY_SAVE,

  /*! For passphrase confirmation. */
  PWMD_PINENTRY_SAVE_CONFIRM,

  /*! When saving a file and passphrase confirmation failed. */
  PWMD_PINENTRY_SAVE_FAILED,

  /*! For confirmation of a user-defined prompt. */
  PWMD_PINENTRY_CONFIRM,

  /*! For the default or user defined string set with \ref
   * PWMD_OPTION_PINENTRY_DESC. */
  PWMD_PINENTRY_USER,

  /*! To terminate the pinentry process created with \ref pwmd_getpin(). */
  PWMD_PINENTRY_CLOSE
} pwmd_pinentry_t;


/*! \typedef pwmd_status_cb_t
 * \brief Process status messages.
 *
 * The value of the option \ref PWMD_OPTION_STATUS_CB which is set with \ref
 * pwmd_setopt().
 *
 * \param user A user data pointer which is set with \ref
 * PWMD_OPTION_STATUS_DATA.
 * \param line The status message line received from the server.
 * \return 0 on success or an error code which will cause a command to fail.
 */
typedef gpg_error_t (*pwmd_status_cb_t) (void *user, const char *line);


/*! \typedef pwmd_inquire_cb_t
 * \brief Send data to the pwmd server.
 *
 * This is a callback function that is used for sending data to the server for
 * commands that need to reply to an INQUIRE server response. The reason for
 * this callback is to let the client send as many bytes as it wants rather
 * than the entire data at once.  It gets called during an internal \ref
 * assuan_transact() from an internal inquire callback function which in turn
 * calls this function by looping over its return value.
 *
 * \param user The user data pointer passed to the libpwmd function specifying
 * this callback.
 * \param keyword The name of this inquire. Could be a command name or some
 * keyword describing what needs to be sent. See the pwmd and \ref
 * gpg-agent(1) documentation for details.
 * \param rc The result of the last internal call to \ref assuan_send_data()
 * which did the sending of the data to the pwmd server. On the first call to
 * this callback it's value will always be 0 since no data has been sent yet.
 * This should be checked during each call to this function and should return
 * the same error code when set. Its purpose is to let the client clean up
 * before letting the command fail.
 * \param[out] data The next chunk of data to send or NULL.
 * \param[out] len The length of \a data or 0.
 *
 * \retval 0 There is more data to be sent.
 * \retval GPG_ERR_EOF No need to call this function again, the current
 * \a data is the last to send.
 * \retval code Any other error code which will cancel the INQUIRE.
 *
 * \note The sent data is processed line-per-line. The line is either newline
 * terminated or is buffered until ASSUAN_LINELENGTH bytes have been
 * allocated. Any remaining bytes are sent after the INQUIRE has finished.
 */
typedef gpg_error_t (*pwmd_inquire_cb_t) (void *user, const char *keyword,
                                          gpg_error_t rc, char **data,
                                          size_t * len);


/*! \typedef pwmd_knownhost_cb_t
 * \brief Verify a remote SSH connection.
 *
 * When \ref PWMD_OPTION_KNOWNHOST_CB is set and a the current connections
 * host key was not found in the known hosts file, then this callback function
 * can be used to confirm the addition of the new host key to the known_hosts
 * file.
 *
 * \param user User data which was set with \ref PWMD_OPTION_KNOWNHOST_DATA.
 * \param host The hostname as passed to \ref pwmd_connect().
 * \param hostkey The raw binary data of the host key.
 * \param len The length of \a hostkey.
 * \retval 0 Add the host key to the known hosts file.
 * \retval GPG_ERR_NOT_CONFIRMED Do not add the host key and abort the
 * connection. This is the recommended error code although any other non-zero
 * return value will also abort the connection.
 *
 * \note If the known hosts file cannot be modified do to filesystem
 * restrictions when trying to add the new host key, no error is returned.
 * Instead, the host key is added to the current connections host key cache
 * and the connection is accepted.
 *
 * \see \ref remote
 */
typedef gpg_error_t (*pwmd_knownhost_cb_t) (void *user, const char *host,
                                            const char *hostkey,
                                            size_t len);


/*! \enum pwmd_option_t
 * \brief libpwmd options.
 *
 * Options are set with \ref pwmd_setopt(). Some options must be set before a
 * connection is made to have any effect.
 *
 * \filepath
 */
/* Note to self: dont change the order or insert. Only append. */
typedef enum
{
  /*! A string value which specifies the full path of the \ref pinentry(1)
   * binary. The default is specified at compile time.
   *
   * \note This only affects the local pinentry.
   * \see \ref pinentry
   */
  PWMD_OPTION_PINENTRY_PATH,

  /*! A string value which specifies the full path to the TTY that \ref
   * pinentry(1) will use to prompt on. When set and no DISPLAY is
   * available, \ref PWMD_OPTION_PINENTRY_TERM must also be set.
   *
   * \see \ref pinentry
   */
  PWMD_OPTION_PINENTRY_TTY,

  /*! A string value which specifies the terminal type (i.e., vt100) that
   * \ref pinentry(1) will use when no X11 display is available.
   *
   * \see \ref pinentry
   */
  PWMD_OPTION_PINENTRY_TERM,

  /*! A string value which specifies the X11 display that \ref pinentry(1)
   * will use. \ref pinentry(1) seems to make DISPLAY have a higher priority
   * than \ref PWMD_OPTION_PINENTRY_TTY.
   *
   * \see \ref pinentry
   */
  PWMD_OPTION_PINENTRY_DISPLAY,

  /*! A character string that \ref pinentry(1) will use in it's dialog
   * window.
   */
  PWMD_OPTION_PINENTRY_ERROR,

  /*! \copydoc PWMD_OPTION_PINENTRY_ERROR */
  PWMD_OPTION_PINENTRY_PROMPT,

  /*! \copydoc PWMD_OPTION_PINENTRY_ERROR */
  PWMD_OPTION_PINENTRY_DESC,

  /*! For \ref pinentry(1) localization. */
  PWMD_OPTION_PINENTRY_LC_CTYPE,

  /*! \copydoc PWMD_OPTION_PINENTRY_LC_CTYPE */
  PWMD_OPTION_PINENTRY_LC_MESSAGES,

  /*! An integer value that specifies the number of seconds \ref pinentry(1)
   * will wait for input before timing out and aborting the current command.
   * If 0, then no timeout will be used. The default is 30.
   *
   * \note This only affects the local pinentry.
   */
  PWMD_OPTION_PINENTRY_TIMEOUT,

  /*! An integer value that specifies the number of times to prompt for a
   * passphrase before returning an error.
   *
   * \note This only affects the local pinentry.
   */
  PWMD_OPTION_PINENTRY_TRIES,

  /*! A function of type \ref pwmd_status_cb_t that will process status
   * messages received from the pwmd server.
   */
  PWMD_OPTION_STATUS_CB,

  /*! A user data pointer which is passed to the status message function
   * \ref PWMD_OPTION_STATUS_CB. */
  PWMD_OPTION_STATUS_DATA,

  /*! A function of type \ref pwmd_knownhost_cb_t that will be used to
   * confirm a host key that was not found in the known hosts file.
   *
   * \see \ref remote
   */
  PWMD_OPTION_KNOWNHOST_CB,

  /*! User supplied data which is passed to the known host function \ref
   * PWMD_OPTION_KNOWNHOST_CB.
   *
   * \see \ref remote
   */
  PWMD_OPTION_KNOWNHOST_DATA,

  /*! When the total number of bytes to be sent via an INQUIRE is known,
   * this should be set so XFER status messages can be parsed correctly.
   * When not known or unset, 0 is used as the total argument to the XFER
   * status message. This option should be reset in every function that
   * uses an \ref pwmd_inquire_cb_t.
   *
   * \note During the INQUIRE, \ref PWMD_OPTION_STATUS_CB is called, when
   * set, after every iteration of the \ref pwmd_inquire_cb_t.
   *
   * \note This is a libpwmd feature. pwmd itself does not send XFER status
   * messages during an INQUIRE. Status messages can be parsed only when
   * \ref PWMD_OPTION_STATUS_CB is set.
   */
  PWMD_OPTION_INQUIRE_TOTAL,

  /*! When set to 1, lock the file mutex after opening a file as if the LOCK
   * command had been sent.
   */
  PWMD_OPTION_LOCK_ON_OPEN,

  /*! Use ssh-agent to retrieve the private key to authenticate when
   * connecting to a remote pwmd server. */
  PWMD_OPTION_SSH_AGENT,

  /*! When 1, disable pinentry use. This will prevent both pwmd and libpwmd
   * from using a pinentry program and will prompt from a terminal if
   * available.
   *
   * \note This must be set before calling \ref pwmd_open().
   * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE.
   */
  PWMD_OPTION_NO_PINENTRY,

  /*! When 1, libpwmd will disable pwmd's pinentry and use it's own
   * fork(2)'ed pinentry.
   *
   * \note This must be set before calling \ref pwmd_open().
   */
  PWMD_OPTION_LOCAL_PINENTRY,

  /*! When set, override libpwmd's handling of server inquires with the
   * PASSPHRASE and NEW_PASSPHRASE keywords. Handling of these keywords is
   * done automatically when \ref PWMD_OPTION_NO_PINENTRY or \ref
   * PWMD_OPTION_LOCAL_PINENTRY is set or when the connection is a remote
   * one.
   *
   * \see \ref remote, \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_password()
   */
  PWMD_OPTION_OVERRIDE_INQUIRE,

  /*! An int specifying a timeout in seconds before a TCP connection or
   * transfer function will timeout causing a connection or command to
   * fail. This option can be specified both before and after a connection
   * has been established. When 0, no timeout is used.
   */
  PWMD_OPTION_SOCKET_TIMEOUT,

  /*! An int specifying whether to enable TLS hostname verification on the
   * server certificate chain. Default is 0 or disabled. */
  PWMD_OPTION_TLS_VERIFY,

  /*! Set to 1 to not modify the signal handler to ignore SIGPIPE. The default
   * is 0, or to ignore this signal. */
  PWMD_OPTION_SIGPIPE,
} pwmd_option_t;


/*! \def PWMD_FEATURE_PINENTRY
 * \hideinitializer
 * \brief Pinentry support.
 *
 * This is for a local or fork()'ed pinentry.
 */
#define PWMD_FEATURE_PINENTRY   0x0001

/*! \def PWMD_FEATURE_CRACK
 * \hideinitializer
 * \brief Password quality checking.
 *
 * A password quality meter is shown when the pinentry supports it.
 */
#define PWMD_FEATURE_CRACK      0x0002

/*! \def PWMD_FEATURE_SSH
 * \hideinitializer
 * \brief Remote connections over an SSH channel.
 *
 * \see \ref remote
 */
#define PWMD_FEATURE_SSH        0x0004

/*! \def PWMD_FEATURE_GNUTLS
 * \hideinitializer
 * \brief Remote connections over TLS.
 *
 * \see \ref remote
 */
#define PWMD_FEATURE_GNUTLS     0x0008


/*! \brief libpwmd compile time features.
 *
 * Useful for clients to determine what features are compiled into libpwmd at
 * runtime.
 *
 * \return A bitmask of features.
 */
LIBPWMD_API unsigned int pwmd_features ();


/*! \brief Initialize the library.
 *
 * This function must be the first function called in the library before any
 * others. It sets up the memory allocators and internationalization among
 * other things.
 *
 * \return 0 on success or an error code.
 */
LIBPWMD_API gpg_error_t pwmd_init (void);

/*! \brief Deinitialize the library.
 *
 * This function is mainly for cleaning up other libraries that
 * libpwmd links with to prevent memory and other leaks showing up in
 * a debugger. It should be the final libpwmd function call before
 * your app exits.
 */
LIBPWMD_API void pwmd_deinit (void);


/*! \brief Creates a new handle.
 *
 * Creates a new handle for use with the other functions.
 *
 * \param name If not NULL, the name of the application. The application name
 * is sent to the pwmd server after successfully connecting and is used in
 * pwmd logging.
 * \param[in] pwm A new handle for use with the other functions.
 *
 * \return 0 on success or an error code.
 */
LIBPWMD_API gpg_error_t pwmd_new (const char *name, pwm_t ** pwm);


/*! \brief Set user data for a handle.
 *
 * Use this function to associate user data with a handle that can later be
 * retrieved with \ref pwmd_get_pointer().
 *
 * \param pwm A handle.
 * \param data A pointer to the user data.
 * \returns Nothing.
 */
LIBPWMD_API void pwmd_set_pointer (pwm_t *pwm, void *data);


/*! \brief Get user data for a handle.
 *
 * Return the user data pointer previously set with \ref pwmd_set_pointer().
 *
 * \param pwm A handle.
 * \returns A pointer to the user data.
 */
LIBPWMD_API void *pwmd_get_pointer (pwm_t *pwm);


/*! \brief Establish a connection to a pwmd server.
 *
 * Connects to the pwmd server specified in \a url. The format of \a url is:
 * \par
 * file:///path/to/socket, or
 * \par
 * ssh[46]://[username@]hostname[:port], or
 * \par
 * tls[46]://hostname[:port]
 *
 *  If \a url is NULL then the default local pwmd socket \a ~/.pwmd/socket
 *  will be used.
 *
 *  The remaining arguments are parameters for the \a url.
 *
 *  For SSH connections, the first of the positional parameters should be the
 *  identity file to use and is required to be non-NULL unless \ref
 *  PWMD_OPTION_SSH_AGENT is set.  The final parameter is the known hosts file
 *  to use or NULL to use a default of \a ~/.ssh/knownhosts.
 *
 *  For TLS connections, the first positional parameter should be the client
 *  certificate filename. The second parameter should be the client
 *  certificate key filename. The third parameter should be the Certificate
 *  Authority (CA) file that was used to sign the server certificate. The
 *  fourth parameter should be a TLS cipher priority string or NULL to use the
 *  default of "SECURE256". The final parameter is an SHA-256 hash of the
 *  server fingerprint or NULL.
 *
 *  For local connections, any remaining parameters are ignored.
 *
 * \param pwm A handle.
 * \param url The socket to connect to.
 * \param ... Remaining parameters for the \a url.
 * \return 0 on success or an error code.
 * \filepath
 * \see \ref PWMD_OPTION_SSH_AGENT, \ref PWMD_OPTION_SOCKET_TIMEOUT,
 * pwmd_socket_type(), pwmd_disconnect(),
 * \ref remote
 */
LIBPWMD_API gpg_error_t pwmd_connect (pwm_t * pwm, const char *url, ...);

/*! \brief Get the error code of a failed TLS function.
 *
 * When an TLS error occurs while connecting or during a command, this function
 * can be used to get the error code.
 *
 * \param pwm A handle.
 * \return 0 on success or an \ref gnutls error code.
 */
LIBPWMD_API int pwmd_tls_error (pwm_t * pwm);

/*! \brief Set handle options.
 *
 * See \ref pwmd_option_t for option specific details.
 *
 * \param pwm A handle.
 * \param opt The option.
 * \param ... The option value.
 * \return 0 on success or an error code.
 */
LIBPWMD_API gpg_error_t pwmd_setopt (pwm_t * pwm, pwmd_option_t opt, ...);


/*! \brief Get the value for a handle option.
 *
 * Retrieves the default or previously set value for a handle option. See
 * \ref pwmd_option_t for option specific details.
 *
 * \param pwm A handle.
 * \param opt The option.
 * \param ... A pointer to the option value type to store the value.
 * \return 0 on success or an error code.
 * \note The value is returned as a pointer and not duplicated.
 */
LIBPWMD_API gpg_error_t pwmd_getopt (pwm_t * pwm, pwmd_option_t opt, ...);


/*! \brief Launch a local pinentry.
 *
 * Does not send any command to the pwmd server. This maybe useful if a
 * passphrase is needed while opening a file over a remote connection and
 * during an \ref pwmd_open() server inquire.
 *
 * This function may also be used to display a user confirmation dialog with
 * pinentry when \a which is \ref PWMD_PINENTRY_CONFIRM. The text to prompt
 * with is set with \ref PWMD_OPTION_PINENTRY_DESC.
 *
 * \param pwm A handle.
 * \param filename The filename to use in the pinentry dialog strings.
 * \param[in] result The entered value in the pinentry dialog which should be
 * freed with \ref pwmd_free().
 * \param[in] len The length of \a result.
 * \param which Determines the default strings shown in the pinentry
 * dialog. \ref pwmd_setopt() may also be used to override the defaults. In
 * this case \ref PWMD_PINENTRY_USER should be used. \ref PWMD_PINENTRY_CLOSE
 * should be used to terminate the pinentry process when the pinentry is no
 * longer needed.
 *
 * \return 0 on success or an error.
 *
 * \see pwmd_password()
 */
LIBPWMD_API gpg_error_t pwmd_getpin (pwm_t * pwm, const char *filename,
                                     char **result, size_t * len,
                                     pwmd_pinentry_t which);

/*! \brief Obtain a passphrase from a local pinentry.
 *
 * This is the same function that libpwmd uses during an inquire when using
 * the local pinentry and the inquire keyword is either PASSPHRASE or
 * NEW_PASSPHRASE. Provided for convenience since it sets proper pinentry
 * strings and handles new passphrase confirmation.
 *
 * \param pwm A handle.
 * \param keyword The keyword to determine pinentry strings. Usually
 * PASSPHRASE or NEW_PASSPHRASE.
 * \param[in] data The obtained passphrase which should be freed with \ref
 * pwmd_free().
 * \param[in] size The length of \a data.
 *
 * \return 0 on success or an error.
 */
LIBPWMD_API gpg_error_t pwmd_password (pwm_t * pwm, const char *keyword,
                                       char **data, size_t * size);

/*! \brief Open a file on the pwmd server.
 *
 * This will send the OPEN command to the server.
 *
 * The inquire \a callback function should be used when \ref
 * PWMD_OPTION_NO_PINENTRY is set and is used to send the passphrase when
 * needed.
 *
 * \param pwm A handle.
 * \param filename The filename to open. The \a filename is not a full path
 * but the data filename only.
 * \param callback A callback function to invoke when pwmd inquires data from
 * the client.
 * \param data User data passed to the \a callback function.
 * \return 0 on success or an error code.
 * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref pinentry, pwmd_password()
 */
LIBPWMD_API gpg_error_t pwmd_open (pwm_t * pwm, const char *filename,
                                   pwmd_inquire_cb_t callback, void *data);


/*! \brief Check for socket activity.
 *
 * This function should be called periodically to check for any pending status
 * messages sent from the server and when \em not in a command.
 *
 * \param pwm A handle.
 * \return 0 on success or an error code.
 *
 * \note This function makes use of \ref pwmd_status_cb_t.
 */
LIBPWMD_API gpg_error_t pwmd_process (pwm_t * pwm);


/*! \brief Save a file on the pwmd server.
 *
 * This will send the SAVE command and write any changes to the document to
 * disk.
 *
 * The inquire \a callback function should be used when \ref
 * PWMD_OPTION_NO_PINENTRY is set or when a SAVE option specified in \a args
 * inquires more data. This function will also disable the pwmd pinentry when
 * \ref PWMD_OPTION_NO_PINENTRY or \ref PWMD_OPTION_LOCAL_PINENTRY is set. It
 * will not restore the pwmd pinentry mode that was previously set before
 * calling this function.
 *
 * \param pwm A handle.
 * \param args Any SAVE protocol command options or NULL.
 * \param callback A callback function to invoke when pwmd inquires data from
 * the client.
 * \param user User data passed to the \a callback function.
 * \return 0 on success or an error code.
 * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_NO_PINENTRY,
 * \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_command(), \ref pinentry
 */
LIBPWMD_API gpg_error_t pwmd_save (pwm_t * pwm, const char *args,
                                   pwmd_inquire_cb_t callback, void *user);


/*! \brief Change the passphrase for a data file.
 *
 * This will send the PASSWD command to the server taking care of pinentry
 * settings.
 *
 * The inquire \a callback function should be used when \ref
 * PWMD_OPTION_OVERRIDE_INQUIRE is set. This function will disable the pwmd
 * pinentry when \ref PWMD_OPTION_NO_PINENTRY or \ref
 * PWMD_OPTION_LOCAL_PINENTRY is set. It will not restore the pwmd pinentry
 * mode that was previously set before calling this function.
 *
 * \param pwm A handle.
 * \param args Any PASSWD protocol command options or NULL.
 * \param callback A callback function to invoke when pwmd inquires data from
 * the client.
 * \param user User data passed to the \a callback function.
 * \return 0 on success or an error code.
 * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_NO_PINENTRY,
 * \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_command(), \ref pinentry
 */
LIBPWMD_API gpg_error_t pwmd_passwd (pwm_t * pwm, const char *args,
                                     pwmd_inquire_cb_t callback, void *user);


/*! \brief Send a command to the pwmd server.
 *
 * You should avoid sending the BYE command here because the assuan context
 * will be freed and bad things will happen. Use \ref pwmd_close() instead.
 *
 * For pwmd commands that use an INQUIRE to retrieve data from a client, the
 * \a callback parameter must be non-NULL and will be used to send the data to
 * pwmd.
 *
 * \param pwm A handle.
 * \param[in] result The result of the command when successful which must be
 * freed with \ref pwmd_free().
 * \param[in] len The length of \a result.
 * \param callback A callback function to invoke when pwmd inquires data from
 * the client.
 * \param user User data passed to the \a callback function.
 * \param cmd The command to send and any following arguments.
 * \return 0 on success or an error code.
 *
 * \note Not all commands return a \a result.
 */
LIBPWMD_API gpg_error_t pwmd_command (pwm_t * pwm, char **result,
                                      size_t * len,
                                      pwmd_inquire_cb_t callback,
                                      void *user, const char *cmd, ...);


/*! \brief Send a command to the pwmd server.
 *
 * Like \ref pwmd_command() but uses an argument pointer instead.
 *
 * \param pwm A handle.
 * \param[in] result The result of the command when successful which must be
 * freed with \ref pwmd_free().
 * \param[in] len The length of \a result.
 * \param callback A callback function to invoke when pwmd inquires data from
 * the client.
 * \param user User data passed to the \a callback function.
 * \param cmd The command to send.
 * \param ap The arguments to \a cmd.
 * \return 0 on success or an error code.
 *
 * \note Not all commands return a \a result.
 */
LIBPWMD_API gpg_error_t pwmd_command_ap (pwm_t * pwm, char **result,
                                         size_t * len,
                                         pwmd_inquire_cb_t callback,
                                         void *user, const char *cmd,
                                         va_list ap);


/*! \brief Close a connection to the pwmd server.
 *
 * This will close the connection but keep any previously set options for the
 * specified handle. Calling \ref pwmd_connect() will re-acquire an libassuan
 * context.
 *
 * \param pwm A handle.
 * \return 0 on success or an error code.
 * \see \ref pwmd_close()
 */
LIBPWMD_API gpg_error_t pwmd_disconnect (pwm_t * pwm);


/*! \brief Close a handle.
 *
 * This will close the connection to a pwmd server and free any resources
 * associated with it.
 *
 * \param pwm A handle.
 * \return Nothing.
 * \see \ref pwmd_disconnect(), \ref pwmd_new()
 */
LIBPWMD_API void pwmd_close (pwm_t * pwm);


/*! \brief The type of connection a handle has.
 *
 * Useful when you want to know what kind of connection a handle has.
 *
 * \param pwm A handle.
 * \param[out] type The type of socket.
 * \return 0 on success or an error code.
 *
 * \see \ref pwmd_socket_t
 */
LIBPWMD_API gpg_error_t pwmd_socket_type (pwm_t * pwm,
                                          pwmd_socket_t * type);

/*! \brief Get the file descriptor associated with a handle.
 *
 * May be useful to determine whether a handle is ready for reading or
 * writing by using select(2) or poll(2).
 *
 * \param pwm A handle.
 * \param[out] fd Set to the file descriptor associated with \a pwm.
 * \return 0 on success or an error code.
 */
LIBPWMD_API gpg_error_t pwmd_fd (pwm_t * pwm, int *fd);


/*! \brief Free a previously allocated pointer.
 *
 * Use this function to free resources allocated by the other libpwmd memory
 * functions. Do not use it to free allocations made by other allocators.
 *
 * The difference between the standard free() and this function is that
 * this one will zero out the contents of the pointer before freeing it.
 *
 * \param ptr The pointer to deallocate.
 * \return Nothing.
 * \see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(),
 * pwmd_command()
 */
LIBPWMD_API void pwmd_free (void *ptr);


/*! \brief A wrapper around malloc.
 *
 * Like malloc(), but lets libpwmd keep track of the pointer.
 *
 * \param size The number of bytes to allocate.
 * \return A newly allocated pointer or NULL if there wasn't enough memory.
 * \see malloc(3), pwmd_free()
 */
LIBPWMD_API void *pwmd_malloc (size_t size);


/*! \brief A wrapper around calloc().
 *
 * Like calloc(), but lets libpwmd keep track of the pointer.
 *
 * \param nmemb The number of elements to allocate.
 * \param size The number of bytes to allocate.
 * \return A newly allocated pointer or NULL if there wasn't enough memory.
 * \see calloc(3), pwmd_free()
 */
LIBPWMD_API void *pwmd_calloc (size_t nmemb, size_t size);


/*! \brief A wrapper around realloc().
 *
 * Like realloc(), but lets libpwmd keep track of the pointer.
 *
 * \param ptr The pointer to reallocate.
 * \param size The new number of bytes to allocate.
 * \return A newly allocated pointer or NULL if there wasn't enough memory.
 * \see realloc(3), pwmd_free()
 */
LIBPWMD_API void *pwmd_realloc (void *ptr, size_t size);


/*! \brief A wrapper around strdup().
 *
 * Like strdup(), but lets libpwmd keep track of the pointer.
 *
 * \param str The string to duplicate.
 * \return A newly allocated character pointer or NULL if there wasn't
 * enough memory.
 * \see strdup(3), pwmd_free()
 */
LIBPWMD_API char *pwmd_strdup (const char *str);


/*! \brief Duplicate a formatted string.
 *
 * Like \ref asprintf(3), but lets libpwmd keep track of the pointer.
 *
 * \param fmt The formatted string and any following arguments.
 * \return A newly allocated character pointer or NULL if there wasn't
 * enough memory.
 * \see pwmd_free()
 */
LIBPWMD_API char *pwmd_strdup_printf (const char *fmt, ...);

/*! \brief Convenience declaration.
 *
 * This allows an application wanting both a TLS connection and libpwmd secure
 * memory management in GnuTLS, not needing to have the GnuTLS development
 * files installed. This function should be called before \ref pwmd_init().
 *
 * It is not done in \ref pwmd_init() itself since the application may have
 * already initialized GnuTLS by some other means.
 */
extern void gnutls_global_set_mem_functions (
                                             // gnutls_alloc_function
                                             void *(*)(size_t),
                                             // gnutls_alloc_function (secure)
                                             void *(*)(size_t),
                                             // gnutls_is_secure_function
                                             int (*)(const void *),
                                             // gnutls_realloc_function
                                             void *(*)(void *, size_t),
                                             // gnutls_free_function
                                             void (*)(void *));

#ifdef __cplusplus
}
#endif

#endif