Fix pwmd_save() to determine whether to use pinentry.

[libpwmd.git] / doc / libpwmd.3

.TH "libpwmd.h" 3 "Sun Feb 24 2013" "Version 7.0.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\&.0 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: an SSH channel, or over TLS\&. Connections over SSH are less reliable than TLS connections since a proxy program is needed to connect to the pwmd UNIX Domain Socket\&. The kernel that pwmd runs under may buffer the UDS data before it reaches the proxy program and there isn't a portable way to modify kernel buffer settings\&. For larger transfers of data this is noticeable by the hanging of the command that initiated the transfer\&.
.PP
If you really do need an SSH connection you can do so by using 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\&.
.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
\fBNote:\fP
.RS 4
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)\&.
.RE
.PP
\fBVersion:\fP
.RS 4
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\&.
.RE
.PP
As mentioned, TLS connections are more reliable since there is no proxy program needed to connect to the pwmd server\&. pwmd itself can accept TLS connections and like SSH connections they are created with \fBpwmd_connect()\fP\&. You'll need to generate a client key and X509 certificate 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 get 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 or gpg-agent use it's 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 only sent to pwmd in \fBpwmd_open()\fP and only when pinentry use has not been disabled and when not over an remote connnection\&.
.PP
Some pinentry options may also be specified in the local configuration file \fI'~/\&.pwmd/pinentry\&.conf'\fP\&. These options are initial values for each pinentry invokation (not retries) and may be changed by setting the appropriate \fBpwmd_option_t\fP\&. Options and values are separated with a '=' on a single line\&. Unrecognized options are ignored\&. Here are the recognized options:
.PP
\fBParameters:\fP
.RS 4
\fIPATH\fP The full path to the location of the pinentry binary\&. Only useful for the local pinentry\&. 
.br
\fIDISPLAY\fP The X11 display to use\&. 
.br
\fITTYNAME\fP The full path to the tty that pinentry should prompt on\&. 
.br
\fITTYTYPE\fP The terminal type of the tty which is required if DISPLAY is not set\&. 
.br
\fILC_MESSAGES\fP Adjust for the current locale\&. 
.br
\fILC_CTYPE\fP Adjust for the current locale\&.
.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\&.
.PP
The initial values for the pinentry TTY, TERM and DISPLAY are set during \fBpwmd_new()\fP depending on the current environment\&. They can be reset or changed as needed\&.
.PP
After establishing a remote connection, pwmd's pinentry is disabled by passing the '&ndash;no-pinentry' option to the OPEN protocol command during \fBpwmd_open()\fP since X11 forwarding has not been implemented\&. A local pinentry will be used in the case of a remote connection\&.
.RE
.PP
\fBSee Also:\fP
.RS 4
\fBRemote Connection Details\fP
.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 find where the error occured, beit 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 find the error source 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   0x070000"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_MAJOR\fP   7"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_MINOR\fP   0"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_PATCH\fP   0"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_STR\fP   '7\&.0\&.0-dev'"
.br
.ti -1c
.RI "#define \fBPWMD_FEATURE_PINENTRY\fP"
.br
.ti -1c
.RI "#define \fBPWMD_FEATURE_CRACK\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 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 }"
.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 }"
.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 gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *url,\&.\&.\&.)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_setopt\fP (\fBpwm_t\fP *pwm, \fBpwmd_option_t\fP 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 **data, size_t *size)"
.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_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_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
.ti -1c
.RI "void \fBgnutls_global_set_mem_functions\fP (void *(*)(size_t), void *(*)(size_t), int(*)(const void *), void *(*)(void *, size_t), void(*)(void *))"
.br
.in -1c
.SH "Constant Details"
.PP 
.SS "#define LIBPWMD_VERSION   0x070000"

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

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

.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   '7\&.0\&.0-dev'"

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

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

.PP
Remote connections over TLS\&. \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_SSH"

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

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

.PP
libpwmd handle\&. When a 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 \fBPWMD_OPTION_KNOWNHOST_CB\fP 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\&.
.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 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\&.
.RE
.PP
\fBSee Also:\fP
.RS 4
\fBRemote Connection Details\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

.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 after opening a file 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 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\&.
.PP
\fBNote:\fP
.RS 4
This must be set before calling \fBpwmd_open()\fP\&. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_LOCAL_PINENTRY \fP\fP
When 1, libpwmd will disable pwmd's pinentry and use it's own fork(2)'ed pinentry\&.
.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 handling of server inquires with the PASSPHRASE and NEW_PASSPHRASE keywords\&. This handling 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 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 on the server certificate chain\&. Default is 0 or disabled\&. 
.SS "enum \fBpwmd_pinentry_t\fP"

.PP
Local pinentry commands and not pwmd pinentry\&. These determine what prompt a local or fork()'ed 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\&. 
.SH "Function Details"
.PP 
.SS "void gnutls_global_set_mem_functions (void **)(size_t, void **)(size_t, int(*)(const void *), void **)(void *, size_t, void(*)(void *))"

.PP
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 \fBpwmd_init()\fP\&.
.PP
It is not done in \fBpwmd_init()\fP itself since the application may have already initialized GnuTLS by some other means\&. 
.SS "LIBPWMD_API void* pwmd_calloc (size_tnmemb, size_tsize)"

.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 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\fPcallback, 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 following 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\fPcallback, void *user, const char *cmd, va_listap)"

.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 fourth parameter should be a TLS cipher priority string or NULL to use the default of 'SECURE256'\&. The final parameter is an SHA-1 hash of the server fingerprint 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 void pwmd_deinit (void)"

.PP
Deinitialize the library\&. This function is mainly for cleaning up other libraries that libpwmd links with to prevent leaks showing up 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\&. 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_getpin (\fBpwm_t\fP *pwm, const char *filename, char **result, size_t *len, \fBpwmd_pinentry_t\fPwhich)"

.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 to prompt with is set with \fBPWMD_OPTION_PINENTRY_DESC\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIfilename\fP The filename to use in the pinentry dialog 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 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_tsize)"

.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 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\fPcallback, void *data)"

.PP
Open a file on the pwmd server\&. This will send the OPEN command to the server\&.
.PP
The inquire \fIcallback\fP function should be used when \fBPWMD_OPTION_NO_PINENTRY\fP is set and is used to send the passphrase when needed\&.
.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_password (\fBpwm_t\fP *pwm, const char *keyword, char **data, 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 either PASSPHRASE or NEW_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 PASSPHRASE or NEW_PASSPHRASE\&. 
.br
\fIdata\fP The obtained passphrase which should be freed with \fBpwmd_free()\fP\&. 
.br
\fIsize\fP The length of \fIdata\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_tsize)"

.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\fPcallback, 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 \fBPWMD_OPTION_NO_PINENTRY\fP is set or when a SAVE option specified in \fIargs\fP inquires more data\&. This function will also disable the pwmd pinentry when \fBPWMD_OPTION_NO_PINENTRY\fP or \fBPWMD_OPTION_LOCAL_PINENTRY\fP is set\&. It will not restore the pwmd pinentry mode that was previously set before calling this function\&.
.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 gpg_error_t pwmd_setopt (\fBpwm_t\fP *pwm, \fBpwmd_option_t\fPopt, \&.\&.\&.)"

.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 and following 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 want 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 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\&.