pwmc: some progress indicator for non-blocking functions when DEBUG is

[libpwmd.git] / doc / libpwmd.3

.TH "libpwmd.h" 3 "Fri Dec 31 2010" "Version 6.0.4" "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 2.0 or later is required; either locally or remotely.
.SH "Multiple 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.
.PP
There is a limitation that when compiled with \fBpth(3)\fP support SSH connections cannot make use of the \fBpth(3)\fP IO functions and therefore will block while waiting on IO operations in other threads (as of libssh2 1.2.8).
.SH "SSH Details"
.PP
A remote connection to a pwmd server is possible by using an SSH channel which spawns a shell and executes a proxy server that connects 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
The servers public key can be had by using \fBpwmd_get_hostkey()\fP and storing the result in a file or done automatially by using a callback function \fBpwmd_knownhost_cb_t\fP while connecting to the unknown host.
.PP
On the server side you'll need a proxy server to connect to the real pwmd server. Here's an example \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 which is passed as a parameter to the SSH connection functions:
.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.1 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 use it's pinentry to retrieve a passphrase when needed. How this is done depends what function gets called and whether the pwmd connection is over an SSH channel.
.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 not sent (when using pwmd's pinentry, not the local one) until the pinentry is needed.
.PP
If using a local pinentry by calling \fBpwmd_open2()\fP, \fBpwmd_save2()\fP, \fBpwmd_open_async2()\fP or \fBpwmd_save_async2()\fP, libpwmd will send the command 'SET ENABLE_PINENTRY=0' to the pwmd server. This is needed so pwmd wont try to launch it's own pinentry on passphrase or confirmation failure. So you may need to reset this option manually depending on your needs; especially when changing pinentry methods when doing a save (the passphrase may be set as empty since the remote pinentry is disabled!).
.PP
Some pinentry options can also be specified in a 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. Each option and value is 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. 
.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 may need to be reset as needed.
.PP
After establishing an SSH connection, the pwmd pinentry is disabled by sending the command 'SET ENABLE_PINENTRY=0'. This is needed because there currently isn't a way to have the remote pinentry use the local display. You must be careful to use either a local pinentry or set a passphrase manually with \fBpwmd_setopt()\fP when a passphrase is required or needed.
.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. Some are user defined GPG_ERR_USER_N codes, but most are reused from the existing ones. Error codes can be described by using \fBpwmd_strerror()\fP, or the thread-safe \fBpwmd_strerror_r()\fP.
.PP
\fBNote:\fP
.RS 4
libgpg-error normally returns an error code as a bitmask of an error source and the actual error code. In order to simplify the result codes, libpwmd strips any error source from the error code before returning it. 
.RE
.PP

.SH SYNOPSIS
.br
.PP
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBpwmd_fd_t\fP"
.br
.in -1c
.SS "Constants"

.in +1c
.ti -1c
.RI "#define \fBLIBPWMD_API\fP"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION\fP   0x604"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_MAJOR\fP   6"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_MINOR\fP   0"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_PATCH\fP   4"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_STR\fP   '6.0.4-git'"
.br
.ti -1c
.RI "#define \fBPWMD_FD_READABLE\fP   0x01"
.br
.ti -1c
.RI "#define \fBPWMD_FD_WRITABLE\fP   0x02"
.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 \fBEPWMD_NO_FILE\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_LIBXML_ERROR\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_FILE_MODIFIED\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_MAX\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_passphrase_cb_t\fP )(void *user, char **passphrase)"
.br
.ti -1c
.RI "typedef int(* \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 *cmd, 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 *key, size_t len)"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBpwmd_async_t\fP { \fBASYNC_INIT\fP, \fBASYNC_PROCESS\fP, \fBASYNC_DONE\fP }"
.br
.ti -1c
.RI "enum \fBpwmd_ip_version_t\fP { \fBPWMD_IP_ANY\fP, \fBPWMD_IPV4\fP, \fBPWMD_IPV6\fP }"
.br
.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_CONFIRM\fP, \fBPWMD_PINENTRY_DEFAULT\fP, \fBPWMD_PINENTRY_CLOSE\fP }"
.br
.ti -1c
.RI "enum \fBpwmd_option_t\fP { \fBPWMD_OPTION_PASSPHRASE_CB\fP, \fBPWMD_OPTION_PASSPHRASE_DATA\fP, \fBPWMD_OPTION_PASSPHRASE\fP, \fBPWMD_OPTION_PINENTRY_TRIES\fP, \fBPWMD_OPTION_PINENTRY_PATH\fP, \fBPWMD_OPTION_PINENTRY_TTY\fP, \fBPWMD_OPTION_PINENTRY_TERM\fP, \fBPWMD_OPTION_PINENTRY_DISPLAY\fP, \fBPWMD_OPTION_PINENTRY_TITLE\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_STATUS_CB\fP, \fBPWMD_OPTION_STATUS_DATA\fP, \fBPWMD_OPTION_IP_VERSION\fP, \fBPWMD_OPTION_KNOWNHOST_CB\fP, \fBPWMD_OPTION_KNOWNHOST_DATA\fP, \fBPWMD_OPTION_INQUIRE_TOTAL\fP, \fBPWMD_OPTION_LOCK_ON_OPEN\fP, \fBPWMD_OPTION_ITERATIONS\fP, \fBPWMD_OPTION_CIPHER\fP, \fBPWMD_OPTION_BASE64\fP, \fBPWMD_OPTION_SSH_AGENT\fP, \fBPWMD_OPTION_NO_PINENTRY\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 \fBpwm_t\fP * \fBpwmd_new\fP (const char *name)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *path)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_ssh_connect\fP (\fBpwm_t\fP *pwm, const char *host, int port, const char *identity, const char *user, const char *known_hosts)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_ssh_connect_async\fP (\fBpwm_t\fP *pwm, const char *host, int port, const char *identity, const char *user, const char *known_hosts)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_connect_url\fP (\fBpwm_t\fP *pwm, const char *url)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_connect_url_async\fP (\fBpwm_t\fP *pwm, const char *url)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_get_hostkey\fP (\fBpwm_t\fP *pwm, const char *host, int port, char **result)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_get_hostkey_async\fP (\fBpwm_t\fP *pwm, const char *host, int port)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_get_fds\fP (\fBpwm_t\fP *pwm, \fBpwmd_fd_t\fP *fds, int *n_fds)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_pending_line\fP (\fBpwm_t\fP *pwm)"
.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, \fBpwmd_pinentry_t\fP which)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_open\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_open_inquire\fP (\fBpwm_t\fP *pwm, const char *filename, \fBpwmd_inquire_cb_t\fP func, void *user)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_open2\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_open_async2\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_open_async\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "LIBPWMD_API \fBpwmd_async_t\fP \fBpwmd_process\fP (\fBpwm_t\fP *pwm, gpg_error_t *rc, char **result)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_save_inquire\fP (\fBpwm_t\fP *pwm, \fBpwmd_inquire_cb_t\fP func, void *user)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_save2\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_save_async2\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_save_async\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_command\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd,...)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_command_ap\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd, va_list ap)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_inquire\fP (\fBpwm_t\fP *pwm, const char *cmd, \fBpwmd_inquire_cb_t\fP func, void *user)"
.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 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 "LIBPWMD_API const char * \fBpwmd_strerror\fP (gpg_error_t code)"
.br
.ti -1c
.RI "LIBPWMD_API int \fBpwmd_strerror_r\fP (gpg_error_t code, char *buf, size_t size)"
.br
.in -1c
.SH "Constant Details"
.PP 
.SS "#define EPWMD_FILE_MODIFIED"
.PP
The data file has been modified. Rather than process the next command this error is returned to prevent overwriting new data which may have been saved by another client. 
.SS "#define EPWMD_LIBXML_ERROR"
.PP
libxml2 error. This can be a memory allocation error or a parse error. The details of the error cannot be obtained with libpwmd. You'd have to connect to the pwmd socket and do the command directly to get the actual error. 
.SS "#define EPWMD_MAX"
.PP
libgpg-error error code offset. If you use your own libgpg-error codes then this should be the base of them. 
.SS "#define EPWMD_NO_FILE"
.PP
No data file has been opened. Some commands don't require an open data file but most do. 
.SS "#define LIBPWMD_VERSION   0x604"
.PP
Version information. The version of this library. 
.SS "#define LIBPWMD_VERSION_MAJOR   6"
.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   4"
.PP
Version information. The patch level of this library. 
.SS "#define LIBPWMD_VERSION_STR   '6.0.4-git'"
.PP
Version information. A string representation of the version of this library. 
.SS "#define PWMD_FD_READABLE   0x01"
.PP
For use with \fBpwmd_get_fds()\fP. Set when the file descriptor is readable. 
.SS "#define PWMD_FD_WRITABLE   0x02"
.PP
For use with \fBpwmd_get_fds()\fP. Set when the file descriptor is writable. 
.SS "#define PWMD_FEATURE_CRACK"
.PP
Password quality checking. A password quality meter is shown when the pinentry supports it. 
.SS "#define PWMD_FEATURE_PINENTRY"
.PP
Pinentry support. This is for a local pinentry when calling \fBpwmd_open2()\fP and \fBpwmd_save2()\fP. 
.SS "#define PWMD_FEATURE_SSH"
.PP
Remote connections over an SSH channel. Refer to \fBSSH Details\fP for how to get this to work. 
.SH "Typedef Details"
.PP 
.SS "\fBpwm_t\fP"
.PP
libpwmd handle. When a handle 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 gets passed to \fBpwmd_inquire()\fP. It is used for sending data to the server for commands that need to reply to an INQUIRE server response (STORE and IMPORT). The reason for this callback is to let the client send as many bytes as it wants rather than the entire chunk 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 \fBpwmd_inquire()\fP. 
.br
\fIcmd\fP The same as the \fIcmd\fP argument to \fBpwmd_inquire()\fP. 
.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. 
.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_CANCELED\fP Cancel the current inquire. 
.br
\fIGPG_ERR_EOF\fP No need to call this function again, the current \fIline\fP is the last to send. 
.br
\fIcode\fP Any other error code which will terminate 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 the connecting function. 
.br
\fIkey\fP The raw host key. Note that this differs from the format returned from \fBpwmd_get_hostkey()\fP. 
.br
\fIlen\fP The host key length. 
.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.
.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 considered verified.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBSSH Details\fP 
.RE
.PP

.SS "\fBpwmd_passphrase_cb_t\fP"
.PP
Custom passphrase retrieval function. The value of the option \fBPWMD_OPTION_PASSPHRASE_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_PASSPHRASE_DATA\fP. 
.br
\fIpassphrase\fP The passphrase which may be an empty string or NULL. It is not modified by libpwmd but must remain allocated for as long as it is needed. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code which will cause a command to fail. 
.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_async_t\fP"
.PP
Asynchronous return value. The return code of \fBpwmd_process()\fP which is used for all asynchronous commands. 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fIASYNC_INIT \fP\fP
.PP
\fBFor internal use only.\fP
.RS 4
.RE
.PP

.TP
\fB\fIASYNC_PROCESS \fP\fP
\fBpwmd_process()\fP should be called again. 
.TP
\fB\fIASYNC_DONE \fP\fP
The command has completed. The result code should be checked for an error. 
.SS "enum \fBpwmd_ip_version_t\fP"
.PP
IP protocol version for remote SSH connections. The value of the option \fBPWMD_OPTION_IP_VERSION\fP which is set with \fBpwmd_setopt()\fP. 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fIPWMD_IP_ANY \fP\fP
Try both IPv4 and IPv6 addresses. Note that IPv6 is tried first and that \fBPWMD_IP_ANY\fP only affects a hostname and not an IP address in the address specification. 
.TP
\fB\fIPWMD_IPV4 \fP\fP
Only try IPv4. 
.TP
\fB\fIPWMD_IPV6 \fP\fP
Only try IPv6. 
.SS "enum \fBpwmd_option_t\fP"
.PP
libpwmd options. Options are set with \fBpwmd_setopt()\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. 
.RE
.PP

.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fIPWMD_OPTION_PASSPHRASE_CB \fP\fP
A custom passphrase retrieval function which, when set, will be used instead of \fBpinentry(1)\fP. This function will not be used if opening a file and the passphrase is cached on the server or the file is a new one. The value of this option should be a \fBpwmd_passphrase_cb_t\fP.
.PP
\fBNote:\fP
.RS 4
An empty string as the passphrase is allowed. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PASSPHRASE_DATA \fP\fP
User supplied data which is passed to the custom passphrase function. 
.TP
\fB\fIPWMD_OPTION_PASSPHRASE \fP\fP
A string to use as the passphrase when doing an open or save. When not NULL, this option has precedence over \fBPWMD_OPTION_PASSPHRASE_CB\fP.
.PP
\fBNote:\fP
.RS 4
An empty string as the passphrase is allowed. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_TRIES \fP\fP
An integer value that specifies the number of tries before \fBpinentry(1)\fP will give up when opening a file with the wrong supplied passphrase. The default is 3.
.PP
\fBNote:\fP
.RS 4
This option has no effect when trying to save a file. The user must either cancel the pinentry causing the save to fail or enter the correct passphrase during passphrase confirmation. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_PATH \fP\fP
A character string value which specifies the full path of the \fBpinentry(1)\fP binary. For the local \fBpinentry(1)\fP method, the default is specified at compile time.
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PINENTRY_TTY \fP\fP
A 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 value which specifies the terminal type (e.g., 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 value which specifies the X11 display that \fBpinentry(1)\fP will use.
.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_TITLE \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. 
.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. 
.TP
\fB\fIPWMD_OPTION_IP_VERSION \fP\fP
The IP version of type \fBpwmd_ip_version_t\fP that \fBpwmd_ssh_connect()\fP and \fBpwmd_ssh_connect_async()\fP will use when connecting to the remote pwmd server. The default is \fBPWMD_IP_ANY\fP.
.PP
\fBNote:\fP
.RS 4
This option must be set before a connection is made when not the default. 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_KNOWNHOST_CB \fP\fP
A function to confirm an unknown host hash which wasn't 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.
.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 to \fBpwmd_inquire()\fP.
.PP
\fBNote:\fP
.RS 4
During the INQUIRE, PWMD_OPTION_STATUS_CB is called after every ASSUAN_LINELENGTH bytes have been successfully transferred.
.PP
This is a libpwmd feature. pwmd itself does not send XFER status messages during an INQUIRE. Status messages can be parsed only when PWMD_OPTION_STATUS_CB 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_ITERATIONS \fP\fP
A long integer specifying the number of iterations to encrypt with. When -1 then the next save operation will use the current iteration setting and no command will be sent to alter it. 
.TP
\fB\fIPWMD_OPTION_CIPHER \fP\fP
A string specifying the cipher to use to encrypt with. See the pwmd(1) manual page for available ciphers. 
.TP
\fB\fIPWMD_OPTION_BASE64 \fP\fP
When 1, tell pwmd that the passphrase is Base64 encoded. pwmd will decode the passphrase before encryption and decryption. 
.TP
\fB\fIPWMD_OPTION_SSH_AGENT \fP\fP
Use ssh-agent to retrieve private key to authenticate. 
.TP
\fB\fIPWMD_OPTION_NO_PINENTRY \fP\fP
When 1, disable pinentry use. This will prevent pwmd and libpwmd from using a pinentry. 
.SS "enum \fBpwmd_pinentry_t\fP"
.PP
Local pinentry commands and not pwmd pinentry. 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_CONFIRM \fP\fP
For confirmation of a user-defined prompt. 
.TP
\fB\fIPWMD_PINENTRY_DEFAULT \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 domain socket. 
.TP
\fB\fIPWMD_SOCKET_SSH \fP\fP
An SSH connection over a TCP socket. 
.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 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, const char * cmd,  ...)"
.PP
Send a command to the pwmd server. Sends 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. For commands that use an INQUIRE to send data to the server (STORE and IMPORT), \fBpwmd_inquire()\fP must be used and not this function.
.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
\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 result. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_command_ap (\fBpwm_t\fP * pwm, char ** result, 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
\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 result. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_connect (\fBpwm_t\fP * pwm, const char * path)"
.PP
Connect to a local pwmd server. Connects to a local unix domain socket.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIpath\fP The socket path to connect to. If NULL, then a default of \fI'~/.pwmd/socket'\fP 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_ssh_connect()\fP, \fBpwmd_ssh_connect_async()\fP, \fBpwmd_disconnect()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_connect_url (\fBpwm_t\fP * pwm, const char * url)"
.PP
Establish a connection by parsing a URL. This allows for connecting to a pwmd server by parsing the given URL string. Whether the connection is to a remote or local server depends on the contents: 
.PP
.nf
 file://[path/to/local/socket]

 or

 ssh[46]://[username@]hostname[:port][,identity,known_hosts]

.fi
.PP
.PP
The parameters in square brackets are optional and if not specified then defaults will be used. If neither socket specification is matched, the \fIurl\fP is assumed to be a file://.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIurl\fP The string to parse. 
.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
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_socket_type()\fP, \fBpwmd_disconnect()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_connect_url_async (\fBpwm_t\fP * pwm, const char * url)"
.PP
Establish a connection by parsing a URL (asynchronously). This allows for connecting to a pwmd server by parsing the given URL string. Whether the connection is to a remote or local server depends on the contents: 
.PP
.nf
 file://[path/to/local/socket]

 or

 ssh[46]://[username@]hostname[:port][,identity,known_hosts]

.fi
.PP
.PP
The parameters in square brackets are optional and if not specified then defaults will be used. If neither socket specification is matched, the \fIurl\fP is assumed to be a file://.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIurl\fP The string to parse. 
.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
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_socket_type()\fP, \fBpwmd_disconnect()\fP 
.RE
.PP

.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.
.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 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_process()\fP, \fBpwmd_command()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_get_fds (\fBpwm_t\fP * pwm, \fBpwmd_fd_t\fP * fds, int * n_fds)"
.PP
Get the associated file descriptor(s) for a handle. This function lets the application manually poll the available file descriptors for the specified handle. It should be called after each asynchronous function call and after each call to \fBpwmd_process()\fP since the polled file descriptors may have been closed since the previous call.
.PP
After returning, \fIn_fds\fP is set to the number of available file descriptors which are stored in \fIfds\fP. The .flags member of \fBpwmd_fd_t\fP specifies what can be monitored and is a bitmask of \fBPWMD_FD_READABLE\fP and \fBPWMD_FD_WRITABLE\fP. When ready, \fBpwmd_process()\fP should be called.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIfds\fP Set to the file descriptor(s) of the associated handle. 
.br
\fIn_fds\fP Initially the size of \fIfds\fP then updated to the number of available file descriptors which are stored in \fIfds\fP. 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP on success or an error code. 
.br
\fIGPG_ERR_ERANGE\fP There are more file descriptors than the amount specified in \fIn_fds\fP. \fIfds\fP and \fIn_fds\fP are still usable though. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_get_hostkey (\fBpwm_t\fP * pwm, const char * host, int port, char ** result)"
.PP
Retrieve a remote SSH public host key. This key is needed for host verification of the remote pwmd server. You should be sure that the remote host is really the host that your wanting to connect to and not subject to a man-in-the-middle attack.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIhost\fP The hostname or IP to connect to. 
.br
\fIport\fP The port or -1 for the default of 22. 
.br
\fIresult\fP An OpenSSH known hosts formatted string containing the servers public key which should be freed with \fBpwmd_free()\fP. If the \fIhost\fP was a hostname then two newline separated known host entries will be returned; one for the hostname and one for the resolved IP address. The IP known host entry will always be the second in the string. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code.
.RE
.PP
\fBVersion:\fP
.RS 4
6.0.3 The connection is kept open but not verified after returning. It can be resumed from one of the SSH connection functions.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_get_hostkey_async()\fP, \fBpwmd_ssh_connect()\fP, \fBSSH Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_get_hostkey_async (\fBpwm_t\fP * pwm, const char * host, int port)"
.PP
Retrieve a remote SSH host key (asynchronously). This key is needed for host verification of the remote pwmd server. You should be sure that the remote host is really the host that your wanting to connect to and not subject to a man-in-the-middle attack.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIhost\fP The hostname or IP to connect to. 
.br
\fIport\fP The port or -1 for the default of 22. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. The result is obtained from \fBpwmd_process()\fP should be freed with \fBpwmd_free()\fP. It has the same format as the result from \fBpwmd_get_hostkey()\fP.
.RE
.PP
\fBVersion:\fP
.RS 4
6.0.3 The connection is kept open but not verified after returning. It can be resumed from one of the SSH connection functions.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_get_hostkey()\fP, \fBpwmd_ssh_connect_async()\fP, \fBpwmd_process()\fP, \fBSSH Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_getpin (\fBpwm_t\fP * pwm, const char * filename, char ** result, \fBpwmd_pinentry_t\fP which)"
.PP
Launch a local pinentry. Does not send any command to the server. Maybe useful if a passphrase is needed before opening a file over a remote connection. This passphrase can then be set with \fBpwmd_setopt()\fP.
.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_TITLE\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
\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_DEFAULT\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

.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 gpg_error_t pwmd_inquire (\fBpwm_t\fP * pwm, const char * cmd, \fBpwmd_inquire_cb_t\fP func, void * user)"
.PP
Send data to a pwmd server. This lets commands that use an INQUIRE (STORE and IMPORT) send the data to the server. Use this function rather than \fBpwmd_command()\fP for these pwmd commands.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIcmd\fP The \fBpwmd(1)\fP command to send including any options. 
.br
\fIfunc\fP A callback function of type \fBpwmd_inquire_cb_t\fP which sets the data to be sent. 
.br
\fIuser\fP A user data pointer passed to the callback function \fIfunc\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_inquire_cb_t\fP 
.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 \fBpwm_t\fP* pwmd_new (const char * name)"
.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.
.RE
.PP
\fBReturns:\fP
.RS 4
a new handle or NULL if there was not enough memory. 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_open (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server. This will send the OPEN command to the server.
.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 file only. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_open2 (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server using a local pinentry. This will send the OPEN command to the server like \fBpwmd_open()\fP but will use the local pinentry and not pwmd's pinentry.
.PP
\fBNote:\fP
.RS 4
This function will catch SIGALRM during the lifetime of the pinentry process and set it to SIG_DFL when finished. This is needed for pinentry timeouts.
.PP
This pinentry method is not thread safe. It needs to set a couple of global variables for the pinentry timeout to work properly.
.RE
.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 file only. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIGPG_ERR_PIN_BLOCKED\fP Another handle is using the local pinentry. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_open_async (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server (asynchronously). This will send the OPEN command to the pwmd server. The difference from \fBpwmd_open()\fP is that it will not block if a pinentry is needed for passphrase input.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.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 file only. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP, \fBPinentry Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_open_async2 (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server asynchronously (fork method). This is kind of a hybrid of \fBpwmd_open2()\fP and \fBpwmd_open_async()\fP. It will use the local pinentry asynchronously and also do the OPEN command asynchronously.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.PP
\fBNote:\fP
.RS 4
This function will catch SIGALRM during the lifetime of the pinentry process and set it to SIG_DFL when finished. This is needed for pinentry timeouts.
.RE
.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 file only. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP, \fBPinentry Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_open_inquire (\fBpwm_t\fP * pwm, const char * filename, \fBpwmd_inquire_cb_t\fP func, void * user)"
.PP
Open a file on the pwmd server by using a server inquire. This is a convenience function to the OPEN command using \fBpwmd_inquire()\fP in that it passes the OPEN options that were set with \fBpwmd_setopt()\fP for you. It uses the specified callback function to retreive the passphrase.
.PP
\fBNote:\fP
.RS 4
Only the passphrase should be sent when using this function and not any filename argument. That argument will be sent automatically when using this function.
.PP
Pinentry is disabled when using this function.
.RE
.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 file only. 
.br
\fIfunc\fP A callback function of type \fBpwmd_inquire_cb_t\fP which sets the passphrase to be sent. This acts as a normal \fBpwmd_inquire()\fP would. 
.br
\fIuser\fP A user data pointer passed to the callback function \fIfunc\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPWMD_OPTION_BASE64\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_pending_line (\fBpwm_t\fP * pwm)"
.PP
Check for a unparsed buffered line. A buffered line is a line that was read from the server but has not yet been processed. This function determines if there is such a line.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP if there is a pending line. 
.br
\fIGPG_ERR_NO_DATA\fP if there is no pending line. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP 
.RE
.PP

.SS "LIBPWMD_API \fBpwmd_async_t\fP pwmd_process (\fBpwm_t\fP * pwm, gpg_error_t * rc, char ** result)"
.PP
Process an asynchronous function. After an asynchronous function has been called and has returned successfully, this function must be called to process the command and retrieve the result and return value.
.PP
This function may also be called when not in a command to check for pending status messages sent from the server or to process a pending line.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIrc\fP Set to the return code of the original command after ASYNC_DONE has been returned. This value must be checked to determine if the command succeeded. 
.br
\fIresult\fP Set to the result of the command when \fIrc\fP is 0. Note that not all commands return a result. 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIASYNC_DONE\fP The command has completed. \fIrc\fP should be checked to determine if the command was successful or not. 
.br
\fIASYNC_PROCESS\fP The command is still running and this function should be called again. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_get_fds()\fP, \fBpwmd_pending_line()\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
\fBNote:\fP
.RS 4
This function will try and allocate the entire \fIsize\fP before freeing the original pointer and returning the new one.
.RE
.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)"
.PP
Save a file on the pwmd server. This will send the SAVE 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
\fBSee also:\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_save2 (\fBpwm_t\fP * pwm)"
.PP
Save a file on the pwmd server using the local pinentry. This will send the SAVE command like \fBpwmd_save()\fP but will use a local pinentry and not pwmd's pinentry.
.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
\fBPinentry Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_save_async (\fBpwm_t\fP * pwm)"
.PP
Save changes to a file on the pwmd server (asynchronously). This will send the SAVE command to the pwmd server. The difference from \fBpwmd_save()\fP is that it will not block if a pinentry is needed for passphrase input.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.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_process()\fP, \fBPinentry Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_save_async2 (\fBpwm_t\fP * pwm)"
.PP
Save a file on the pwmd server asynchronously (fork method). This is kind of a hybrid of \fBpwmd_save2()\fP and \fBpwmd_save_async()\fP. It will use the local pinentry asynchronously and also do the SAVE command asynchronously.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.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_process()\fP, \fBPinentry Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_save_inquire (\fBpwm_t\fP * pwm, \fBpwmd_inquire_cb_t\fP func, void * user)"
.PP
Save a file on the pwmd server by using a server inquire. This is a convenience function to the SAVE command using \fBpwmd_inquire()\fP in that it passes the SAVE options that were set with \fBpwmd_setopt()\fP for you. It uses the specified callback function to retreive the passphrase.
.PP
\fBNote:\fP
.RS 4
Pinentry is disabled when using this function.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIfunc\fP A callback function of type \fBpwmd_inquire_cb_t\fP which sets the passphrase to be sent. This acts as a normal \fBpwmd_inquire()\fP would. 
.br
\fIuser\fP A user data pointer passed to the callback function \fIfunc\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBPWMD_OPTION_BASE64\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_setopt (\fBpwm_t\fP * pwm, \fBpwmd_option_t\fP 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 and following 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_connect_url()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_ssh_connect (\fBpwm_t\fP * pwm, const char * host, int port, const char * identity, const char * user, const char * known_hosts)"
.PP
Establish a remote connection to a pwmd server. Connects to a pwmd server over an SSH channel.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIhost\fP The hostname to connect to or NULL to resume a connection previously started with \fBpwmd_get_hostkey()\fP. 
.br
\fIport\fP The port or -1 for the default of 22. 
.br
\fIidentity\fP The SSH identity file to use for authentication. This should specify the private key. The public key is assumed to be \fIidentity.pub\fP. This parameter is not used if \fBPWMD_OPTION_SSH_AGENT\fP is set. 
.br
\fIuser\fP The username on the SSH server to login as. If NULL then invoking username will be used. 
.br
\fIknown_hosts\fP An OpenSSH known hosts formatted file containing public SSH server hashes which may be obtained with \fBpwmd_get_hostkey()\fP or via \fBpwmd_knownhost_cb_t\fP during a connection. If NULL, the default of \fI'~/.ssh/known_hosts'\fP 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_ssh_connect_async()\fP, \fBPWMD_OPTION_IP_VERSION\fP, \fBpwmd_disconnect()\fP, \fBSSH Details\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_ssh_connect_async (\fBpwm_t\fP * pwm, const char * host, int port, const char * identity, const char * user, const char * known_hosts)"
.PP
Establish a remote connection to a pwmd server (asynchronously). This is a variant of \fBpwmd_ssh_connect()\fP that will not block while doing DNS lookups or while connecting.
.PP
\fBpwmd_process()\fP should be called until the command completes.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIhost\fP The hostname to connect to or NULL to resume a connection previously started with \fBpwmd_get_hostkey()\fP. 
.br
\fIport\fP The port or -1 for the default of 22. 
.br
\fIidentity\fP The SSH identity file to use for authentication. This should specify the private key. The public key is assumed to be \fIidentity.pub\fP. This parameter is not used if \fBPWMD_OPTION_SSH_AGENT\fP is set. 
.br
\fIuser\fP The username on the SSH server to login as. If NULL, the invoking username will be used. 
.br
\fIknown_hosts\fP An OpenSSH known hosts formatted file containing public SSH server hashes which may be obtained with \fBpwmd_get_hostkey()\fP or via \fBpwmd_knownhost_cb_t\fP during a connection. If NULL, the default of \fI'~/.ssh/known_hosts'\fP 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_process()\fP, \fBPWMD_OPTION_IP_VERSION\fP, \fBpwmd_disconnect()\fP, \fBSSH Details\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 \fBsprintf(3)\fP but returns an allocated string.
.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_strerror (gpg_error_t code)"
.PP
Return a description of an error code. \fBParameters:\fP
.RS 4
\fIcode\fP The error code to describe. 
.RE
.PP
\fBReturns:\fP
.RS 4
A character description of the error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_strerror_r()\fP 
.RE
.PP

.SS "LIBPWMD_API int pwmd_strerror_r (gpg_error_t code, char * buf, size_t size)"
.PP
Return a description of an error code (thread-safe). This is a thread-safe version of \fBpwmd_strerror()\fP.
.PP
\fBParameters:\fP
.RS 4
\fIcode\fP The error code to describe. 
.br
\fIbuf\fP An allocated buffer to hold the error description. 
.br
\fIsize\fP The size of the allocated buffer \fIbuf\fP.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP Success. 
.br
\fIERANGE\fP \fIsize\fP was not large enough to hold the entire description and \fIbuf\fP is set to the truncated error string. 
.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.