Changed pwmd_fd() to return a gpg_error_t.

[libpwmd.git] / doc / libpwmd.3

.TH "libpwmd.h" 3 "Tue Jan 3 2012" "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 "SSH Details"
.PP
A remote connection to a pwmd server is possible 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 real 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 generated \fBssh-keygen(1)\fP \fIidentity\&.pub\fP file\&. The private key should be passed as the \fIidentity\fP parameter in \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
\fBTodo\fP
.RS 4
X11 port forwarding so a remote pinentry can use the local display\&. 
.RE
.PP
.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 (really 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 not over an SSH 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\&.
.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 an SSH connection, pwmd's pinentry is disabled by passing the '--no-pinentry' option during \fBpwmd_open()\fP since X11 forwarding has not been implemented\&.
.RE
.PP
\fBTodo\fP
.RS 4
X11 port forwarding so a remote pinentry can use the local display\&.
.RE
.PP
.PP
\fBSee also:\fP
.RS 4
\fBSSH 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   0x700"
.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
.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 }"
.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_SSH_TIMEOUT\fP, \fBPWMD_OPTION_SSH_KEEPALIVE\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 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, const char *identity, const char *knownhosts)"
.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
.in -1c
.SH "Constant Details"
.PP 
.SS "#define \fBLIBPWMD_VERSION\fP   0x700"
.PP
Version information\&. The version of this library\&. 
.SS "#define \fBLIBPWMD_VERSION_MAJOR\fP   7"
.PP
Version information\&. The major release number of this library\&. 
.SS "#define \fBLIBPWMD_VERSION_MINOR\fP   0"
.PP
Version information\&. The minor release number of this library\&. 
.SS "#define \fBLIBPWMD_VERSION_PATCH\fP   0"
.PP
Version information\&. The patch level of this library\&. 
.SS "#define \fBLIBPWMD_VERSION_STR\fP   '7\&.0\&.0-dev'"
.PP
Version information\&. A string representation of the version of this library\&. 
.SS "#define \fBPWMD_FEATURE_CRACK\fP"
.PP
Password quality checking\&. A password quality meter is shown when the pinentry supports it\&. 
.SS "#define \fBPWMD_FEATURE_PINENTRY\fP"
.PP
Pinentry support\&. This is for a local or fork()'ed pinentry\&. 
.SS "#define \fBPWMD_FEATURE_SSH\fP"
.PP
Remote connections over an SSH channel\&. \fBSee also:\fP
.RS 4
\fBSSH 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 "\fBpwmd_inquire_cb_t\fP"
.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 "\fBpwmd_knownhost_cb_t\fP"
.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
\fBSSH Details\fP 
.RE
.PP

.SS "\fBpwmd_status_cb_t\fP"
.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
\fBTodo\fP
.RS 4
X11 port forwarding so a remote pinentry can use the local display\&.
.RE
.PP
.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
\fBSSH 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
\fBSSH 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 set before each call 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 over an SSH channel\&.
.PP
\fBSee also:\fP
.RS 4
\fBSSH Details\fP, \fBPWMD_OPTION_LOCAL_PINENTRY\fP, \fBpwmd_password()\fP 
.RE
.PP
\fBTodo\fP
.RS 4
X11 port forwarding so a remote pinentry can use the local display\&. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_SSH_TIMEOUT \fP\fP
An int specifying a timeout in seconds before a blocking ssh function will timeout causing a command to fail\&. 
.TP
\fB\fIPWMD_OPTION_SSH_KEEPALIVE \fP\fP
An int specifying an interval in seconds that \fBpwmd_process()\fP will send a keepalive message to the remote SSH server\&. 
.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\&. 
.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\&. 
.SH "Function Details"
.PP 
.SS "LIBPWMD_API void* \fBpwmd_calloc\fP (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 \fBpwmd_close\fP (\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 \fBpwmd_command\fP (\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 \fBpwmd_command_ap\fP (\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 \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *url, const char *identity, const char *knownhosts)"
.PP
Establish a connection to a pwmd server\&. Connects to a pwmd server specified in \fIurl\fP\&. The format of \fIurl\fP is: file:///path/to/socket or ssh[46]://[username@]hostname[:port]
.PP
If \fIurl\fP is NULL then the default local pwmd socket \fI~/\fP\&.pwmd/socket will be used\&. The \fIidentity\fP and \fIknownhosts\fP parameters are ignored when connecting to a local socket\&.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIurl\fP The socket to connect to\&. 
.br
\fIidentity\fP The SSH identity file to use\&. This is the location of the private identity file\&. This parameter is required unless \fBPWMD_OPTION_SSH_AGENT\fP is set\&. 
.br
\fIknownhosts\fP The SSH knownhosts file to use\&. If NULL, a default of \fI~/\fP\&.ssh/knownhosts will be used\&. 
.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_socket_type()\fP, \fBpwmd_disconnect()\fP, \fBSSH Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t \fBpwmd_disconnect\fP (\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 \fBpwmd_fd\fP (\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 \fBpwmd_features\fP ()"
.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 \fBpwmd_free\fP (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 \fBpwmd_getpin\fP (\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 \fBpwmd_init\fP (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* \fBpwmd_malloc\fP (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 \fBpwmd_new\fP (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 \fBpwmd_open\fP (\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
\fBPinentry Details\fP, \fBpwmd_password()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t \fBpwmd_password\fP (\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
\fBNote:\fP
.RS 4
It is an error for \fIsize\fP to be zero when inquiring a \fIkeyword\fP of PASSPHRASE\&. In this case GPG_ERR_CANCELED will be returned\&. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t \fBpwmd_process\fP (\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* \fBpwmd_realloc\fP (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 \fBpwmd_save\fP (\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 requires more 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_command()\fP, \fBPinentry Details\fP, \fBSSH Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t \fBpwmd_setopt\fP (\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 \fBpwmd_socket_type\fP (\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* \fBpwmd_strdup\fP (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* \fBpwmd_strdup_printf\fP (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* \fBpwmd_version\fP ()"
.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\&.