Port to Windows.

[libpwmd.git] / doc / libpwmd.3

.TH "libpwmd.h" 3 "Tue Jan 31 2017" "Version 8.1.0" "libpwmd" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libpwmd.h - an API for accessing pwmd
.SH "Description"
.PP 
libpwmd is a library making it easy for applications to use the pwmd server\&. Pwmd version 3\&.1 or later is required; either locally or remotely\&.
.SH "Threads"
.PP
\fBlibpwmd\fP should be thread-safe on a per handle bases\&. Meaning that only one thread should access a \fBpwm_t\fP handle at a time\&.
.SH "Remote Connection Details"
.PP
There are two methods of connecting to a remote pwmd server: over SSH and over TLS\&.
.PP
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 \fBssh-keygen(1)\fP) authentication and verifying the host key against a local OpenSSH known hosts formatted file\&. A passphrase protected private SSH key is supported when \fBPWMD_OPTION_SSH_NEEDS_PASSPHRASE\fP is set\&.
.PP
An unknown servers public key can be added to a known hosts file after user confirmation by setting the callback function \fBpwmd_knownhost_cb_t\fP before connecting to the unknown host\&.
.PP
On the server side you'll need a proxy server to connect to the pwmd server\&. Below is an example of an \fBauthorized_keys(5)\fP entry that will do this\&. The \fIpublic_key\fP portion should be the same as the contents of the \fBssh-keygen(1)\fP \fIidentity\&.pub\fP file generated on the client machine\&. The private key should be passed as the \fIidentity\fP parameter to \fBpwmd_connect()\fP:
.PP
.PP
.nf
command="socat UNIX-CONNECT:$HOME/\&.pwmd/socket -" <public_key> \&.\&.\&.
.fi
.PP
.PP
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 \fBpwmd_connect()\fP\&. 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\&.
.PP
Certificates are similar to SSH public and private keys but a little harder to setup correctly\&. See the \fBcerttool(1)\fP (recommended) and \fBopenssl(1)\fP manual pages for details\&.
.SH "Pinentry Details"
.PP
\fBpinentry(1)\fP 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 (read: \fBgpg-agent(1)\fP) call pinentry to retrieve a passphrase when needed\&.
.PP
There are a few options that tell pinentry how and where to prompt for a needed passphrase\&. See the \fBpwmd_option_t\fP section for details\&. These options are sent to pwmd during \fBpwmd_open()\fP, \fBpwmd_save()\fP and \fBpwmd_passwd()\fP only when pinentry use has not been disabled (\fBPWMD_OPTION_NO_PINENTRY\fP) and when not over a remote connection\&.
.PP
Some pinentry options may also be specified in the local configuration file \fI'~/\&.config/libpwmd\&.conf'\fP\&.
.PP
\fBNote:\fP
.RS 4
When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user\&.
.PP
The initial values for the pinentry TTY, TERM and DISPLAY are set during \fBpwmd_new()\fP depending on the current environment\&. They are then updated to the values specified in \fI~/\fP\&.config/libpwmd\&.conf\&. They can then be reset or changed as needed by using \fBpwmd_setopt()\fP\&.
.PP
After establishing a remote connection, pwmd's pinentry is disabled by sending the pwmd option \fI'disable-pinentry'\fP during \fBpwmd_open()\fP\&. A local pinentry will be used instead\&.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBRemote Connection Details\fP, \fBConfiguration File\fP
.RE
.PP
.SH "Configuration File"
.PP
Initial values overriding libpwmd defaults for a handle may be specified in the configuration file \fI~/\fP\&.config/libpwmd\&.conf\&. This file is read only once during \fBpwmd_new()\fP\&. Option values may be updated by setting the associated option with \fBpwmd_setopt()\fP\&. Blank lines and lines beginning with a '#' are ignored as are unrecognized options\&. See the documentation for each option for its' value type\&. Valid options are:
.PP
\fBpinentry-path\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_PATH\fP\&.
.RE
.PP
\fBpinentry-display\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_DISPLAY\fP\&.
.RE
.PP
\fBpinentry-ttyname\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_TTY\fP\&.
.RE
.PP
\fBpinentry-ttytype\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_TERM\fP\&.
.RE
.PP
\fBpinentry-lc-messages\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_LC_MESSAGES\fP\&.
.RE
.PP
\fBpinentry-lc-ctype\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_LC_CTYPE\fP\&.
.RE
.PP
\fBpinentry-timeout\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_TIMEOUT\fP\&.
.RE
.PP
\fBpinentry-tries\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_TRIES\fP\&.
.RE
.PP
\fBno-pinentry\fP
.RS 4
Same as \fBPWMD_OPTION_NO_PINENTRY\fP\&.
.RE
.PP
\fBlocal-pinentry\fP
.RS 4
Same as \fBPWMD_OPTION_LOCAL_PINENTRY\fP\&.
.RE
.PP
\fBno-ssh-agent\fP
.RS 4
Same as \fBPWMD_OPTION_SSH_AGENT\fP\&.
.RE
.PP
\fBno-tls-verify\fP
.RS 4
Same as \fBPWMD_OPTION_TLS_VERIFY\fP\&.
.RE
.PP
\fBtls-priority\fP
.RS 4
Same as \fBPWMD_OPTION_TLS_PRIORITY\fP\&.
.RE
.PP
\fBsocket-timeout\fP
.RS 4
Same as \fBPWMD_OPTION_SOCKET_TIMEOUT\fP\&.
.RE
.PP
\fBno-lock\fP
.RS 4
Same as \fBPWMD_OPTION_LOCK_ON_OPEN\fP\&.
.RE
.PP
\fBinclude\fP
.RS 4
Path to file containing additional libpwmd\&.conf settings\&.
.RE
.PP
.SH "Errors"
.PP
libpwmd uses libgpg-error for all error codes\&. Error codes can be described by using \fBgpg_strerror()\fP, or the thread-safe \fBgpg_strerror_r()\fP\&.
.PP
\fBNote:\fP
.RS 4
libgpg-error returns an error code as a bitmask of an error source and the error code\&. Determining the error source can help you determine where the error occurred, be it from \fBpinentry(1)\fP, \fBgpg-agent(1)\fP, \fBlibgcrypt\fP, \fBpwmd(1)\fP or \fBlibpwmd(3)\fP\&. pwmd uses the \fBGPG_ERR_SOURCE_USER_1\fP error source and libpwmd uses \fBGPG_ERR_SOURCE_USER_2\fP\&. To view the error source and description of an error code the \fBgpg-error(1)\fP command line utility may be of use\&. Also see the \fBlibgpg-error\fP documentation for error code manipulation\&. 
.RE
.PP

.SH SYNOPSIS
.br
.PP
.SS "Constants"

.in +1c
.ti -1c
.RI "#define \fBLIBPWMD_API\fP"
.br
.ti -1c
.RI "#define \fBGPG_ERR_SOURCE_DEFAULT\fP   GPG_ERR_SOURCE_USER_2"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION\fP   0x080100"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_MAJOR\fP   8"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_MINOR\fP   1"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_PATCH\fP   0"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_STR\fP   '8\&.1\&.0\-dev'"
.br
.ti -1c
.RI "#define \fBPWMD_FEATURE_PINENTRY\fP"
.br
.ti -1c
.RI "#define \fBPWMD_FEATURE_QUALITY\fP"
.br
.ti -1c
.RI "#define \fBPWMD_FEATURE_SSH\fP"
.br
.ti -1c
.RI "#define \fBPWMD_FEATURE_GNUTLS\fP"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct pwm_s \fBpwm_t\fP"
.br
.ti -1c
.RI "typedef ssize_t(* \fBpwmd_read_cb_t\fP) (void *user, int fd, void *data, size_t len)"
.br
.ti -1c
.RI "typedef ssize_t(* \fBpwmd_write_cb_t\fP) (void *user, int fd, const void *data, size_t len)"
.br
.ti -1c
.RI "typedef gpg_error_t(* \fBpwmd_status_cb_t\fP) (void *user, const char *line)"
.br
.ti -1c
.RI "typedef gpg_error_t(* \fBpwmd_inquire_cb_t\fP) (void *user, const char *keyword, gpg_error_t rc, char **data, size_t *len)"
.br
.ti -1c
.RI "typedef gpg_error_t(* \fBpwmd_knownhost_cb_t\fP) (void *user, const char *host, const char *hostkey, size_t len)"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBpwmd_socket_t\fP { \fBPWMD_SOCKET_LOCAL\fP, \fBPWMD_SOCKET_SSH\fP, \fBPWMD_SOCKET_TLS\fP, \fBPWMD_SOCKET_USER\fP }"
.br
.ti -1c
.RI "enum \fBpwmd_pinentry_t\fP { \fBPWMD_PINENTRY_OPEN\fP, \fBPWMD_PINENTRY_OPEN_FAILED\fP, \fBPWMD_PINENTRY_SAVE\fP, \fBPWMD_PINENTRY_SAVE_CONFIRM\fP, \fBPWMD_PINENTRY_SAVE_FAILED\fP, \fBPWMD_PINENTRY_CONFIRM\fP, \fBPWMD_PINENTRY_USER\fP, \fBPWMD_PINENTRY_CLOSE\fP }"
.br
.ti -1c
.RI "enum \fBpwmd_option_t\fP { \fBPWMD_OPTION_PINENTRY_PATH\fP, \fBPWMD_OPTION_PINENTRY_TTY\fP, \fBPWMD_OPTION_PINENTRY_TERM\fP, \fBPWMD_OPTION_PINENTRY_DISPLAY\fP, \fBPWMD_OPTION_PINENTRY_ERROR\fP, \fBPWMD_OPTION_PINENTRY_PROMPT\fP, \fBPWMD_OPTION_PINENTRY_DESC\fP, \fBPWMD_OPTION_PINENTRY_LC_CTYPE\fP, \fBPWMD_OPTION_PINENTRY_LC_MESSAGES\fP, \fBPWMD_OPTION_PINENTRY_TIMEOUT\fP, \fBPWMD_OPTION_PINENTRY_TRIES\fP, \fBPWMD_OPTION_STATUS_CB\fP, \fBPWMD_OPTION_STATUS_DATA\fP, \fBPWMD_OPTION_KNOWNHOST_CB\fP, \fBPWMD_OPTION_KNOWNHOST_DATA\fP, \fBPWMD_OPTION_INQUIRE_TOTAL\fP, \fBPWMD_OPTION_LOCK_ON_OPEN\fP, \fBPWMD_OPTION_SSH_AGENT\fP, \fBPWMD_OPTION_NO_PINENTRY\fP, \fBPWMD_OPTION_LOCAL_PINENTRY\fP, \fBPWMD_OPTION_OVERRIDE_INQUIRE\fP, \fBPWMD_OPTION_SOCKET_TIMEOUT\fP, \fBPWMD_OPTION_TLS_VERIFY\fP, \fBPWMD_OPTION_SIGPIPE\fP, \fBPWMD_OPTION_SERVER_VERSION\fP, \fBPWMD_OPTION_SSH_NEEDS_PASSPHRASE\fP, \fBPWMD_OPTION_SSH_PASSPHRASE\fP, \fBPWMD_OPTION_TLS_PRIORITY\fP, \fBPWMD_OPTION_READ_CB\fP, \fBPWMD_OPTION_READ_CB_DATA\fP, \fBPWMD_OPTION_WRITE_CB\fP, \fBPWMD_OPTION_WRITE_CB_DATA\fP }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "LIBPWMD_API const char * \fBpwmd_version\fP ()"
.br
.ti -1c
.RI "LIBPWMD_API unsigned int \fBpwmd_features\fP ()"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_init\fP (void)"
.br
.ti -1c
.RI "LIBPWMD_API void \fBpwmd_deinit\fP (void)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_new\fP (const char *name, \fBpwm_t\fP **pwm)"
.br
.ti -1c
.RI "LIBPWMD_API void \fBpwmd_set_pointer\fP (\fBpwm_t\fP *pwm, void *data)"
.br
.ti -1c
.RI "LIBPWMD_API void * \fBpwmd_get_pointer\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_cancel\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_connect_fd\fP (\fBpwm_t\fP *pwm, int fd)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *url,\&.\&.\&.)"
.br
.ti -1c
.RI "LIBPWMD_API int \fBpwmd_gnutls_error\fP (\fBpwm_t\fP *pwm, const char **str)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_setopt\fP (\fBpwm_t\fP *pwm, int opt,\&.\&.\&.)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_getopt\fP (\fBpwm_t\fP *pwm, int opt,\&.\&.\&.)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_getpin\fP (\fBpwm_t\fP *pwm, const char *filename, char **result, size_t *len, \fBpwmd_pinentry_t\fP which)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_password\fP (\fBpwm_t\fP *pwm, const char *keyword, char **result, size_t *size)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_test_quality\fP (const char *passphrase, double *result)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_open\fP (\fBpwm_t\fP *pwm, const char *filename, \fBpwmd_inquire_cb_t\fP callback, void *data)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_process\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_genkey\fP (\fBpwm_t\fP *pwm, const char *args, \fBpwmd_inquire_cb_t\fP callback, void *user)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm, const char *args, \fBpwmd_inquire_cb_t\fP callback, void *user)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_passwd\fP (\fBpwm_t\fP *pwm, const char *args, \fBpwmd_inquire_cb_t\fP callback, void *user)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_command\fP (\fBpwm_t\fP *pwm, char **result, size_t *len, \fBpwmd_inquire_cb_t\fP callback, void *user, const char *cmd,\&.\&.\&.)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_command_ap\fP (\fBpwm_t\fP *pwm, char **result, size_t *len, \fBpwmd_inquire_cb_t\fP callback, void *user, const char *cmd, va_list ap)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_disconnect\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API void \fBpwmd_close\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_socket_type\fP (\fBpwm_t\fP *pwm, \fBpwmd_socket_t\fP *type)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_fd\fP (\fBpwm_t\fP *pwm, int *fd)"
.br
.ti -1c
.RI "LIBPWMD_API void \fBpwmd_free\fP (void *ptr)"
.br
.ti -1c
.RI "LIBPWMD_API void * \fBpwmd_malloc\fP (size_t size)"
.br
.ti -1c
.RI "LIBPWMD_API void * \fBpwmd_calloc\fP (size_t nmemb, size_t size)"
.br
.ti -1c
.RI "LIBPWMD_API void * \fBpwmd_realloc\fP (void *ptr, size_t size)"
.br
.ti -1c
.RI "LIBPWMD_API char * \fBpwmd_strdup\fP (const char *str)"
.br
.ti -1c
.RI "LIBPWMD_API char * \fBpwmd_strdup_printf\fP (const char *fmt,\&.\&.\&.)"
.br
.in -1c
.SH "Constant Details"
.PP 
.SS "#define LIBPWMD_VERSION   0x080100"

.PP
Version information\&. The version of this library\&. 
.SS "#define LIBPWMD_VERSION_MAJOR   8"

.PP
Version information\&. The major release number of this library\&. 
.SS "#define LIBPWMD_VERSION_MINOR   1"

.PP
Version information\&. The minor release number of this library\&. 
.SS "#define LIBPWMD_VERSION_PATCH   0"

.PP
Version information\&. The patch level of this library\&. 
.SS "#define LIBPWMD_VERSION_STR   '8\&.1\&.0\-dev'"

.PP
Version information\&. A string representation of the version of this library\&. 
.SS "#define PWMD_FEATURE_GNUTLS"

.PP
Remote connections over TLS\&. 
.PP
\fBSee also:\fP
.RS 4
\fBRemote Connection Details\fP 
.RE
.PP

.SS "#define PWMD_FEATURE_PINENTRY"

.PP
Pinentry support\&. This is for a local or fork()'ed pinentry\&. 
.SS "#define PWMD_FEATURE_QUALITY"

.PP
Password quality checking\&. A password quality meter is shown when the pinentry supports it\&. 
.SS "#define PWMD_FEATURE_SSH"

.PP
Remote connections over an SSH channel\&. 
.PP
\fBSee also:\fP
.RS 4
\fBRemote Connection Details\fP 
.RE
.PP

.SH "Typedef Details"
.PP 
.SS "\fBpwm_t\fP"

.PP
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 \fBpwmd_new()\fP\&. 
.SS "pwmd_inquire_cb_t"

.PP
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 \fBassuan_transact()\fP from an internal inquire callback function which in turn calls this function by looping over its return value\&.
.PP
\fBParameters:\fP
.RS 4
\fIuser\fP The user data pointer passed to the libpwmd function specifying this callback\&. 
.br
\fIkeyword\fP The name of this inquire\&. Could be a command name or some keyword describing what needs to be sent\&. See the pwmd and \fBgpg-agent(1)\fP documentation for details\&. 
.br
\fIrc\fP The result of the last internal call to \fBassuan_send_data()\fP 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\&. 
.br
\fIdata\fP The next chunk of data to send or NULL\&. 
.br
\fIlen\fP The length of \fIdata\fP or 0\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP There is more data to be sent\&. 
.br
\fIGPG_ERR_EOF\fP No need to call this function again, the current \fIdata\fP is the last to send\&. 
.br
\fIcode\fP Any other error code which will cancel the INQUIRE\&.
.RE
.PP
\fBNote:\fP
.RS 4
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\&. 
.RE
.PP

.SS "pwmd_knownhost_cb_t"

.PP
Verify a remote SSH connection\&. When the current SSH 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\&. When \fBPWMD_OPTION_KNOWNHOST_CB\fP is not set then the default callback function will be used\&.
.PP
\fBParameters:\fP
.RS 4
\fIuser\fP User data which was set with \fBPWMD_OPTION_KNOWNHOST_DATA\fP\&. 
.br
\fIhost\fP The hostname as passed to \fBpwmd_connect()\fP\&. 
.br
\fIhostkey\fP The raw binary data of the host key\&. 
.br
\fIlen\fP The length of \fIhostkey\fP\&. 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP Add the host key to the known hosts file\&. 
.br
\fIGPG_ERR_NOT_CONFIRMED\fP 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\&.
.RE
.PP
\fBNote:\fP
.RS 4
If the known hosts file cannot be modified do to filesystem restrictions when adding 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\&.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBRemote Connection Details\fP 
.RE
.PP

.SS "pwmd_read_cb_t"

.PP
Custom socket read callback function\&. Use this function to override the libpwmd function used for reading from a socket\&. Set with \fBpwmd_setopt()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIuser\fP A user data pointer which is set with \fBPWMD_OPTION_READ_CB_DATA\fP\&. 
.br
\fIfd\fP The file descriptor to read from\&. 
.br
\fIdata\fP The buffer to store the read data to\&. 
.br
\fIlen\fP The size of the data buffer\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
The amount of bytes read\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_connect_fd()\fP 
.RE
.PP

.SS "pwmd_status_cb_t"

.PP
Process status messages\&. The value of the option \fBPWMD_OPTION_STATUS_CB\fP which is set with \fBpwmd_setopt()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIuser\fP A user data pointer which is set with \fBPWMD_OPTION_STATUS_DATA\fP\&. 
.br
\fIline\fP The status message line received from the server\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code which will cause a command to fail\&. 
.RE
.PP

.SS "pwmd_write_cb_t"

.PP
Custom socket write callback function\&. Use this function to override the libpwmd function used for writing to a socket\&. Set with \fBpwmd_setopt()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIuser\fP A user data pointer which is set with \fBPWMD_OPTION_WRITE_CB_DATA\fP\&. 
.br
\fIfd\fP The file descriptor to write to\&. 
.br
\fIdata\fP The data to write\&. 
.br
\fIlen\fP The amount of data bytes to write\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
The amount of bytes written\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_connect_fd()\fP 
.RE
.PP

.SH "Enumeration Details"
.PP 
.SS "enum \fBpwmd_option_t\fP"

.PP
libpwmd options\&. Options are set with \fBpwmd_setopt()\fP\&. Some options must be set before a connection is made to have any effect\&.
.PP
\fBNote:\fP
.RS 4
When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user\&. 
.RE
.PP

.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIPWMD_OPTION_PINENTRY_PATH \fP\fP
A string value which specifies the full path of the \fBpinentry(1)\fP binary\&. The default is specified at compile time\&.
.PP
\fBNote:\fP
.RS 4
This only affects the local pinentry\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_TTY \fP\fP
A string value which specifies the full path to the TTY that \fBpinentry(1)\fP will use to prompt on\&. When set and no DISPLAY is available, \fBPWMD_OPTION_PINENTRY_TERM\fP must also be set\&.
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_TERM \fP\fP
A string value which specifies the terminal type (i\&.e\&., vt100) that \fBpinentry(1)\fP will use when no X11 display is available\&.
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_DISPLAY \fP\fP
A string value which specifies the X11 display that \fBpinentry(1)\fP will use\&. \fBpinentry(1)\fP seems to make DISPLAY have a higher priority than \fBPWMD_OPTION_PINENTRY_TTY\fP\&.
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_ERROR \fP\fP
A character string that \fBpinentry(1)\fP will use in it's dialog window\&. 
.TP
\fB\fIPWMD_OPTION_PINENTRY_PROMPT \fP\fP
A character string that \fBpinentry(1)\fP will use in it's dialog window\&. 
.TP
\fB\fIPWMD_OPTION_PINENTRY_DESC \fP\fP
A character string that \fBpinentry(1)\fP will use in it's dialog window\&. 
.TP
\fB\fIPWMD_OPTION_PINENTRY_LC_CTYPE \fP\fP
For \fBpinentry(1)\fP localization\&. 
.TP
\fB\fIPWMD_OPTION_PINENTRY_LC_MESSAGES \fP\fP
For \fBpinentry(1)\fP localization\&. 
.TP
\fB\fIPWMD_OPTION_PINENTRY_TIMEOUT \fP\fP
An integer value that specifies the number of seconds \fBpinentry(1)\fP will wait for input before timing out and aborting the current command\&. If 0, then no timeout will be used\&. The default is 30\&.
.PP
\fBNote:\fP
.RS 4
This only affects the local pinentry\&. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_TRIES \fP\fP
An integer value that specifies the number of times to prompt for a passphrase before returning an error\&.
.PP
\fBNote:\fP
.RS 4
This only affects the local pinentry\&. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_STATUS_CB \fP\fP
A function of type \fBpwmd_status_cb_t\fP that will process status messages received from the pwmd server\&. 
.TP
\fB\fIPWMD_OPTION_STATUS_DATA \fP\fP
A user data pointer which is passed to the status message function \fBPWMD_OPTION_STATUS_CB\fP\&. 
.TP
\fB\fIPWMD_OPTION_KNOWNHOST_CB \fP\fP
A function of type \fBpwmd_knownhost_cb_t\fP that will be used to confirm a host key that was not found in the known hosts file\&.
.PP
\fBSee also:\fP
.RS 4
\fBRemote Connection Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_KNOWNHOST_DATA \fP\fP
User supplied data which is passed to the known host function \fBPWMD_OPTION_KNOWNHOST_CB\fP\&.
.PP
\fBSee also:\fP
.RS 4
\fBRemote Connection Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_INQUIRE_TOTAL \fP\fP
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 \fBpwmd_inquire_cb_t\fP\&.
.PP
\fBNote:\fP
.RS 4
During the INQUIRE, \fBPWMD_OPTION_STATUS_CB\fP is called, when set, after every iteration of the \fBpwmd_inquire_cb_t\fP\&.
.PP
This is a libpwmd feature\&. pwmd itself does not send XFER status messages during an INQUIRE\&. Status messages can be parsed only when \fBPWMD_OPTION_STATUS_CB\fP is set\&. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_LOCK_ON_OPEN \fP\fP
When set to 1, lock the file mutex during \fBpwmd_open()\fP as if the LOCK command had been sent\&. 
.TP
\fB\fIPWMD_OPTION_SSH_AGENT \fP\fP
Use ssh-agent to retrieve the private key to authenticate with when connecting to a remote pwmd server\&. 
.TP
\fB\fIPWMD_OPTION_NO_PINENTRY \fP\fP
When 1, disable pinentry use\&. This will prevent both pwmd and libpwmd from using a pinentry program and will prompt from the terminal if available\&.
.PP
\fBNote:\fP
.RS 4
This must be set before calling \fBpwmd_open()\fP\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPWMD_OPTION_OVERRIDE_INQUIRE\fP, \fBPWMD_OPTION_LOCAL_PINENTRY\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_LOCAL_PINENTRY \fP\fP
When 1, libpwmd will disable pwmd's pinentry and use it's own pinentry\&. This option is set by default when the connection is a remote one\&.
.PP
\fBNote:\fP
.RS 4
This must be set before calling \fBpwmd_open()\fP\&. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_OVERRIDE_INQUIRE \fP\fP
When set, override libpwmd's internal handling of server inquires with the PASSPHRASE, NEW_PASSPHRASE and SIGN_PASSPHRASE keywords\&. Handling of these keywords is done automatically when \fBPWMD_OPTION_NO_PINENTRY\fP or \fBPWMD_OPTION_LOCAL_PINENTRY\fP is set or when the connection is a remote one\&.
.PP
\fBSee also:\fP
.RS 4
\fBRemote Connection Details\fP, \fBPWMD_OPTION_LOCAL_PINENTRY\fP, \fBpwmd_password()\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_SOCKET_TIMEOUT \fP\fP
An int specifying a timeout in seconds before a TCP connection or data 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\&. 
.TP
\fB\fIPWMD_OPTION_TLS_VERIFY \fP\fP
An int specifying whether to enable TLS hostname verification against the server certificate chain\&. Default is 0 or disabled\&. 
.TP
\fB\fIPWMD_OPTION_SIGPIPE \fP\fP
Set to 1 to not modify the signal handler to ignore SIGPIPE\&. The default is 0, or to ignore this signal\&. 
.TP
\fB\fIPWMD_OPTION_SERVER_VERSION \fP\fP
Get the version of the pwmd server as an unsigned integer\&. This is a read-only setting and is only available after connecting\&. 
.TP
\fB\fIPWMD_OPTION_SSH_NEEDS_PASSPHRASE \fP\fP
The SSH identity file requires a passphrase\&. When set, prompt for the passphrase after connecting\&. Note that only libssh2 built with OpenSSL supports this feature as of libssh2-1\&.7\&.0\&. 
.TP
\fB\fIPWMD_OPTION_SSH_PASSPHRASE \fP\fP
Set SSH private identity passphrase\&. When set there is no need to set \fBPWMD_OPTION_SSH_NEEDS_PASSPHRASE\fP\&. The value of this option is duplicated then freed after the call to \fBpwmd_connect()\fP\&. Note that only libssh2 built with OpenSSL supports this feature as of libssh2-1\&.7\&.0\&. 
.TP
\fB\fIPWMD_OPTION_TLS_PRIORITY \fP\fP
The TLS cipher priority string to use for a TLS connection\&. The default is SECURE256:SECURE192:SECURE128:-VERS-SSL3\&.0:-VERS-TLS1\&.0\&. 
.TP
\fB\fIPWMD_OPTION_READ_CB \fP\fP
The callback function of type \fBpwmd_read_cb_t\fP to use to read from a socket\&. 
.TP
\fB\fIPWMD_OPTION_READ_CB_DATA \fP\fP
The data to pass to the custom read function \fBpwmd_read_cb_t\fP\&. 
.TP
\fB\fIPWMD_OPTION_WRITE_CB \fP\fP
The callback function of type \fBpwmd_write_cb_t\fP to use to write to a socket\&. 
.TP
\fB\fIPWMD_OPTION_WRITE_CB_DATA \fP\fP
The data to pass to the custom write function \fBpwmd_write_cb_t\fP\&. 
.SS "enum \fBpwmd_pinentry_t\fP"

.PP
Local pinentry commands and not pwmd pinentry\&. These determine what prompt a local pinentry uses\&. For use with \fBpwmd_getpin()\fP\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIPWMD_PINENTRY_OPEN \fP\fP
When opening a file\&. 
.TP
\fB\fIPWMD_PINENTRY_OPEN_FAILED \fP\fP
When opening a file failed due to a bad passphrase\&. 
.TP
\fB\fIPWMD_PINENTRY_SAVE \fP\fP
When saving a file\&. 
.TP
\fB\fIPWMD_PINENTRY_SAVE_CONFIRM \fP\fP
For passphrase confirmation\&. 
.TP
\fB\fIPWMD_PINENTRY_SAVE_FAILED \fP\fP
When saving a file and passphrase confirmation failed\&. 
.TP
\fB\fIPWMD_PINENTRY_CONFIRM \fP\fP
For confirmation of a user-defined prompt\&. 
.TP
\fB\fIPWMD_PINENTRY_USER \fP\fP
For the default or user defined string set with \fBPWMD_OPTION_PINENTRY_DESC\fP\&. 
.TP
\fB\fIPWMD_PINENTRY_CLOSE \fP\fP
To terminate the pinentry process created with \fBpwmd_getpin()\fP\&. 
.SS "enum \fBpwmd_socket_t\fP"

.PP
The type of socket a handle is connected to\&. For use with \fBpwmd_socket_type()\fP\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIPWMD_SOCKET_LOCAL \fP\fP
A local UNIX domain socket\&. 
.TP
\fB\fIPWMD_SOCKET_SSH \fP\fP
An SSH channel over a TCP socket\&. 
.TP
\fB\fIPWMD_SOCKET_TLS \fP\fP
A TLS connection over a TCP socket\&. 
.TP
\fB\fIPWMD_SOCKET_USER \fP\fP
A socket set with \fBpwmd_connect_fd()\fP\&. 
.SH "Function Details"
.PP 
.SS "LIBPWMD_API void* pwmd_calloc (size_t nmemb, size_t size)"

.PP
A wrapper around calloc()\&. Like calloc(), but lets libpwmd keep track of the pointer\&.
.PP
\fBParameters:\fP
.RS 4
\fInmemb\fP The number of elements to allocate\&. 
.br
\fIsize\fP The number of bytes to allocate\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
A newly allocated pointer or NULL if there wasn't enough memory\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
calloc(3), \fBpwmd_free()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_cancel (\fBpwm_t\fP * pwm)"

.PP
Cancel an operation\&. This is limited in functionality as it will only cancel an initiating connection to the pwmd server\&. Command cancellation is not yet supported\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP

.SS "LIBPWMD_API void pwmd_close (\fBpwm_t\fP * pwm)"

.PP
Close a handle\&. This will close the connection to a pwmd server and free any resources associated with it\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Nothing\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_disconnect()\fP, \fBpwmd_new()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_command (\fBpwm_t\fP * pwm, char ** result, size_t * len, \fBpwmd_inquire_cb_t\fP callback, void * user, const char * cmd,  \&.\&.\&.)"

.PP
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 \fBpwmd_close()\fP instead\&.
.PP
For pwmd commands that use an INQUIRE to retrieve data from a client, the \fIcallback\fP parameter must be non-NULL and will be used to send the data to pwmd\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIresult\fP The result of the command when successful which must be freed with \fBpwmd_free()\fP\&. 
.br
\fIlen\fP The length of \fIresult\fP\&. 
.br
\fIcallback\fP A callback function to invoke when pwmd inquires data from the client\&. 
.br
\fIuser\fP User data passed to the \fIcallback\fP function\&. 
.br
\fIcmd\fP The command to send and any command arguments\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&.
.RE
.PP
\fBNote:\fP
.RS 4
Not all commands return a \fIresult\fP\&. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_command_ap (\fBpwm_t\fP * pwm, char ** result, size_t * len, \fBpwmd_inquire_cb_t\fP callback, void * user, const char * cmd, va_list ap)"

.PP
Send a command to the pwmd server\&. Like \fBpwmd_command()\fP but uses an argument pointer instead\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIresult\fP The result of the command when successful which must be freed with \fBpwmd_free()\fP\&. 
.br
\fIlen\fP The length of \fIresult\fP\&. 
.br
\fIcallback\fP A callback function to invoke when pwmd inquires data from the client\&. 
.br
\fIuser\fP User data passed to the \fIcallback\fP function\&. 
.br
\fIcmd\fP The command to send\&. 
.br
\fIap\fP The arguments to \fIcmd\fP\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&.
.RE
.PP
\fBNote:\fP
.RS 4
Not all commands return a \fIresult\fP\&. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_connect (\fBpwm_t\fP * pwm, const char * url,  \&.\&.\&.)"

.PP
Establish a connection to a pwmd server\&. Connects to the pwmd server specified in \fIurl\fP\&. The format of \fIurl\fP is: 
.PP
\fB\fP
.RS 4
file:///path/to/socket, or 
.RE
.PP
\fB\fP
.RS 4
ssh[46]://[username@]hostname[:port], or 
.RE
.PP
\fB\fP
.RS 4
tls[46]://hostname[:port]
.RE
.PP
If \fIurl\fP is NULL then the default local pwmd socket \fI~/\fP\&.pwmd/socket will be used\&.
.PP
The remaining arguments are parameters for the \fIurl\fP\&.
.PP
For SSH connections, the first of the positional parameters should be the identity file to use and is required to be non-NULL unless \fBPWMD_OPTION_SSH_AGENT\fP is set\&. The final parameter is the known hosts file to use or NULL to use a default of \fI~/\fP\&.ssh/knownhosts\&.
.PP
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 final parameter is an SHA-256 hash of the server fingerprint to verify against, or NULL\&.
.PP
For local connections, any remaining parameters are ignored\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIurl\fP The socket to connect to\&. 
.br
\fI\&.\&.\&.\fP Remaining parameters for the \fIurl\fP\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBNote:\fP
.RS 4
When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPWMD_OPTION_SSH_AGENT\fP, \fBPWMD_OPTION_SOCKET_TIMEOUT\fP, \fBpwmd_socket_type()\fP, \fBpwmd_disconnect()\fP, \fBRemote Connection Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_connect_fd (\fBpwm_t\fP * pwm, int fd)"

.PP
Associate an already connected socket with a handle\&. Sets a file descriptor for use with the custom read and write callbacks\&. The callbacks must be set before calling this function\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIfd\fP A connected file descriptor\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_read_cb_t\fP, \fBpwmd_write_cb_t\fP 
.RE
.PP

.SS "LIBPWMD_API void pwmd_deinit (void)"

.PP
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\&. 
.SS "LIBPWMD_API gpg_error_t pwmd_disconnect (\fBpwm_t\fP * pwm)"

.PP
Close a connection to the pwmd server\&. This will close the connection but keep any previously set options for the specified handle \fIpwm\fP\&. Calling \fBpwmd_connect()\fP will re-acquire an libassuan context\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_close()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_fd (\fBpwm_t\fP * pwm, int * fd)"

.PP
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)\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIfd\fP Set to the file descriptor associated with \fIpwm\fP\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP

.SS "LIBPWMD_API unsigned int pwmd_features ()"

.PP
libpwmd compile time features\&. Useful for clients to determine what features are compiled into libpwmd at runtime\&.
.PP
\fBReturns:\fP
.RS 4
A bitmask of features\&. 
.RE
.PP

.SS "LIBPWMD_API void pwmd_free (void * ptr)"

.PP
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\&.
.PP
The difference between the standard free() and this function is that this one will zero out the contents of the pointer before freeing it\&.
.PP
\fBParameters:\fP
.RS 4
\fIptr\fP The pointer to deallocate\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Nothing\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_malloc()\fP, \fBpwmd_calloc()\fP, \fBpwmd_realloc()\fP, \fBpwmd_strdup()\fP, \fBpwmd_command()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_genkey (\fBpwm_t\fP * pwm, const char * args, \fBpwmd_inquire_cb_t\fP callback, void * user)"

.PP
Generate a new key\&. Generate a new signing or encryption key or both\&. This will only generate a key without saving the XML document to disk\&.
.PP
The inquire \fIcallback\fP function should be used when a GENKEY option specified in \fIargs\fP inquires data\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIargs\fP Any GENKEY protocol command options or NULL\&. 
.br
\fIcallback\fP A callback function to invoke when pwmd inquires data from the client\&. 
.br
\fIuser\fP User data passed to the \fIcallback\fP function\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPWMD_OPTION_OVERRIDE_INQUIRE\fP, \fBPWMD_OPTION_NO_PINENTRY\fP, \fBPWMD_OPTION_LOCAL_PINENTRY\fP, \fBpwmd_command()\fP, \fBPinentry Details\fP 
.RE
.PP

.SS "LIBPWMD_API void* pwmd_get_pointer (\fBpwm_t\fP * pwm)"

.PP
Get user data for a handle\&. Return the user data pointer previously set with \fBpwmd_set_pointer()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
A pointer to the user data\&. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_getopt (\fBpwm_t\fP * pwm, int opt,  \&.\&.\&.)"

.PP
Get the value for a handle option\&. Retrieves the default or previously set value for a handle option\&. See \fBpwmd_option_t\fP for option specific details\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIopt\fP The option\&. 
.br
\fI\&.\&.\&.\fP A pointer to the option value type to store the value\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBNote:\fP
.RS 4
The value is returned as a pointer and not duplicated\&. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_getpin (\fBpwm_t\fP * pwm, const char * filename, char ** result, size_t * len, \fBpwmd_pinentry_t\fP which)"

.PP
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 \fBpwmd_open()\fP server inquire\&.
.PP
This function may also be used to display a user confirmation dialog with pinentry when \fIwhich\fP is \fBPWMD_PINENTRY_CONFIRM\fP\&. The text show in the pinentry is set with \fBpwmd_setopt()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIfilename\fP The filename to use in the pinentry dialog strings when using the default pinentry strings\&. 
.br
\fIresult\fP The entered value in the pinentry dialog which should be freed with \fBpwmd_free()\fP\&. 
.br
\fIlen\fP The length of \fIresult\fP\&. 
.br
\fIwhich\fP Determines the default strings shown in the pinentry dialog\&. \fBpwmd_setopt()\fP may also be used to override the defaults\&. In this case \fBPWMD_PINENTRY_USER\fP should be used\&. \fBPWMD_PINENTRY_CLOSE\fP should be used to terminate the pinentry process when the pinentry is no longer needed\&.
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error\&.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_password()\fP 
.RE
.PP

.SS "LIBPWMD_API int pwmd_gnutls_error (\fBpwm_t\fP * pwm, const char ** str)"

.PP
Get the error code of a failed GnuTLS function\&. When an TLS error occurs while connecting or during a command, this function can be used to get the error code and error description\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIstr\fP The textual representation of the gnutls error code\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or a GnuTLS error code\&. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_init (void)"

.PP
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\&.
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP

.SS "LIBPWMD_API void* pwmd_malloc (size_t size)"

.PP
A wrapper around malloc\&. Like malloc(), but lets libpwmd keep track of the pointer\&.
.PP
\fBParameters:\fP
.RS 4
\fIsize\fP The number of bytes to allocate\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
A newly allocated pointer or NULL if there wasn't enough memory\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
malloc(3), \fBpwmd_free()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_new (const char * name, \fBpwm_t\fP ** pwm)"

.PP
Creates a new handle\&. Creates a new handle or context for use with the other functions\&.
.PP
\fBParameters:\fP
.RS 4
\fIname\fP 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\&. 
.br
\fIpwm\fP A new handle for use with the other functions\&.
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_open (\fBpwm_t\fP * pwm, const char * filename, \fBpwmd_inquire_cb_t\fP callback, void * data)"

.PP
Open a file on the pwmd server\&. This will send the OPEN command to the server\&.
.PP
To make use of \fIcallback\fP, \fBPWMD_OPTION_OVERRIDE_INQUIRE\fP must also be set\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIfilename\fP The filename to open\&. The \fIfilename\fP is not a full path but the data filename only\&. 
.br
\fIcallback\fP A callback function to invoke when pwmd inquires data from the client\&. 
.br
\fIdata\fP User data passed to the \fIcallback\fP function\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPWMD_OPTION_OVERRIDE_INQUIRE\fP, \fBPinentry Details\fP, \fBpwmd_password()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_passwd (\fBpwm_t\fP * pwm, const char * args, \fBpwmd_inquire_cb_t\fP callback, void * user)"

.PP
Change the passphrase for a data file\&. This will send the PASSWD command to the server taking care of pinentry settings\&.
.PP
The inquire \fIcallback\fP function should be used when a PASSWD option specified in \fIargs\fP inquires data\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIargs\fP Any PASSWD protocol command options or NULL\&. 
.br
\fIcallback\fP A callback function to invoke when pwmd inquires data from the client\&. 
.br
\fIuser\fP User data passed to the \fIcallback\fP function\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPWMD_OPTION_OVERRIDE_INQUIRE\fP, \fBPWMD_OPTION_NO_PINENTRY\fP, \fBPWMD_OPTION_LOCAL_PINENTRY\fP, \fBpwmd_command()\fP, \fBPinentry Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_password (\fBpwm_t\fP * pwm, const char * keyword, char ** result, size_t * size)"

.PP
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 one of PASSPHRASE, NEW_PASSPHRASE or SIGN_PASSPHRASE\&. Provided for convenience since it sets proper pinentry strings and handles new passphrase confirmation\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIkeyword\fP The keyword to determine pinentry strings\&. Usually one of PASSPHRASE, NEW_PASSPHRASE or SIGN_PASSPHRASE as sent by pwmd\&. 
.br
\fIresult\fP The obtained passphrase which should be freed with \fBpwmd_free()\fP\&. 
.br
\fIsize\fP The length of \fIresult\fP\&.
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error\&. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_process (\fBpwm_t\fP * pwm)"

.PP
Check for socket activity\&. This function should be called periodically to check for any pending status messages sent from the server and when \fInot\fP in a command\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&.
.RE
.PP
\fBNote:\fP
.RS 4
This function makes use of \fBpwmd_status_cb_t\fP\&. 
.RE
.PP

.SS "LIBPWMD_API void* pwmd_realloc (void * ptr, size_t size)"

.PP
A wrapper around realloc()\&. Like realloc(), but lets libpwmd keep track of the pointer\&.
.PP
\fBParameters:\fP
.RS 4
\fIptr\fP The pointer to reallocate\&. 
.br
\fIsize\fP The new number of bytes to allocate\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
A newly allocated pointer or NULL if there wasn't enough memory\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
realloc(3), \fBpwmd_free()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_save (\fBpwm_t\fP * pwm, const char * args, \fBpwmd_inquire_cb_t\fP callback, void * user)"

.PP
Save a file on the pwmd server\&. This will send the SAVE command and write any changes to the document to disk\&.
.PP
The inquire \fIcallback\fP function should be used when a SAVE option specified in \fIargs\fP inquires data\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIargs\fP Any SAVE protocol command options or NULL\&. 
.br
\fIcallback\fP A callback function to invoke when pwmd inquires data from the client\&. 
.br
\fIuser\fP User data passed to the \fIcallback\fP function\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPWMD_OPTION_OVERRIDE_INQUIRE\fP, \fBPWMD_OPTION_NO_PINENTRY\fP, \fBPWMD_OPTION_LOCAL_PINENTRY\fP, \fBpwmd_command()\fP, \fBPinentry Details\fP 
.RE
.PP

.SS "LIBPWMD_API void pwmd_set_pointer (\fBpwm_t\fP * pwm, void * data)"

.PP
Set user data for a handle\&. Use this function to associate user data with a handle that can later be retrieved with \fBpwmd_get_pointer()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIdata\fP A pointer to the user data\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Nothing\&. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_setopt (\fBpwm_t\fP * pwm, int opt,  \&.\&.\&.)"

.PP
Set handle options\&. See \fBpwmd_option_t\fP for option specific details\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIopt\fP The option\&. 
.br
\fI\&.\&.\&.\fP The option value\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_socket_type (\fBpwm_t\fP * pwm, \fBpwmd_socket_t\fP * type)"

.PP
The type of connection a handle has\&. Useful when you need to know what kind of connection a handle has\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fItype\fP The type of socket\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_socket_t\fP 
.RE
.PP

.SS "LIBPWMD_API char* pwmd_strdup (const char * str)"

.PP
A wrapper around strdup()\&. Like strdup(), but lets libpwmd keep track of the pointer\&.
.PP
\fBParameters:\fP
.RS 4
\fIstr\fP The string to duplicate\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
A newly allocated character pointer or NULL if there wasn't enough memory\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
strdup(3), \fBpwmd_free()\fP 
.RE
.PP

.SS "LIBPWMD_API char* pwmd_strdup_printf (const char * fmt,  \&.\&.\&.)"

.PP
Duplicate a formatted string\&. Like \fBasprintf(3)\fP, but lets libpwmd keep track of the pointer\&.
.PP
\fBParameters:\fP
.RS 4
\fIfmt\fP The formatted string and any following arguments\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
A newly allocated character pointer or NULL if there wasn't enough memory\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_free()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_test_quality (const char * passphrase, double * result)"

.PP
Test the quality of a passphrase\&. When built with passphrase quality checking, you can test the amount of entropy a passphrase contains with this function\&. It simply wraps around the zxcvbn-c quality checking function\&.
.PP
\fBParameters:\fP
.RS 4
\fIpassphrase\fP The passphrase to test\&. 
.br
\fIresult\fP The entropy of the passphrase in bits\&.
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP

.SS "LIBPWMD_API const char* pwmd_version ()"

.PP
Returns this version of libpwmd\&. As a string\&. 
.PP
\fBReturns:\fP
.RS 4
A string\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libpwmd from the source code\&.