contrib: Add helper to build Android dependencies.

[libpwmd.git] / doc / libpwmd.3

.TH "libpwmd.h" 3 "Wed Sep 28 2022" "Version 8.4.3" "libpwmd" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libpwmd.h - an API for accessing pwmd
.SH SYNOPSIS
.br
.PP
.SS "Macros"

.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   0x080403"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_MAJOR\fP   8"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_MINOR\fP   4"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_PATCH\fP   3"
.br
.ti -1c
.RI "#define \fBLIBPWMD_VERSION_STR\fP   '8\&.4\&.3'"
.br
.ti -1c
.RI "#define \fBPWMD_FEATURE_PINENTRY\fP"
.br
.ti -1c
.RI "#define \fBPWMD_FEATURE_QUALITY\fP"
.br
.ti -1c
.RI "#define \fBPWMD_FEATURE_SSH\fP"
.br
.ti -1c
.RI "#define \fBPWMD_FEATURE_GNUTLS\fP"
.br
.in -1c
.SS "Typedefs"

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

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

.in +1c
.ti -1c
.RI "LIBPWMD_API const char * \fBpwmd_version\fP ()"
.br
.ti -1c
.RI "LIBPWMD_API unsigned int \fBpwmd_features\fP ()"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_init\fP (void)"
.br
.ti -1c
.RI "LIBPWMD_API void \fBpwmd_deinit\fP (void)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_new\fP (const char *name, \fBpwm_t\fP **pwm)"
.br
.ti -1c
.RI "LIBPWMD_API void \fBpwmd_set_pointer\fP (\fBpwm_t\fP *pwm, void *data)"
.br
.ti -1c
.RI "LIBPWMD_API void * \fBpwmd_get_pointer\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_cancel\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_connect_fd\fP (\fBpwm_t\fP *pwm, int fd)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *url,\&.\&.\&.)"
.br
.ti -1c
.RI "LIBPWMD_API int \fBpwmd_gnutls_error\fP (\fBpwm_t\fP *pwm, const char **str)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_setopt\fP (\fBpwm_t\fP *pwm, int opt,\&.\&.\&.)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_getopt\fP (\fBpwm_t\fP *pwm, int opt,\&.\&.\&.)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_getpin\fP (\fBpwm_t\fP *pwm, const char *filename, char **result, size_t *len, \fBpwmd_pinentry_t\fP which)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_password\fP (\fBpwm_t\fP *pwm, const char *keyword, char **result, size_t *size)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_test_quality\fP (const char *passphrase, double *result)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_open\fP (\fBpwm_t\fP *pwm, const char *filename, \fBpwmd_inquire_cb_t\fP callback, void *data)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_process\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_genkey\fP (\fBpwm_t\fP *pwm, const char *args, \fBpwmd_inquire_cb_t\fP callback, void *user)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm, const char *args, \fBpwmd_inquire_cb_t\fP callback, void *user)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_passwd\fP (\fBpwm_t\fP *pwm, const char *args, \fBpwmd_inquire_cb_t\fP callback, void *user)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_command\fP (\fBpwm_t\fP *pwm, char **result, size_t *len, \fBpwmd_inquire_cb_t\fP callback, void *user, const char *cmd,\&.\&.\&.)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_command_ap\fP (\fBpwm_t\fP *pwm, char **result, size_t *len, \fBpwmd_inquire_cb_t\fP callback, void *user, const char *cmd, va_list ap)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_disconnect\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API void \fBpwmd_close\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_socket_type\fP (\fBpwm_t\fP *pwm, \fBpwmd_socket_t\fP *type)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_fd\fP (\fBpwm_t\fP *pwm, int *fd)"
.br
.ti -1c
.RI "LIBPWMD_API void \fBpwmd_free\fP (void *ptr)"
.br
.ti -1c
.RI "LIBPWMD_API void * \fBpwmd_malloc\fP (size_t size)"
.br
.ti -1c
.RI "LIBPWMD_API void * \fBpwmd_calloc\fP (size_t nmemb, size_t size)"
.br
.ti -1c
.RI "LIBPWMD_API void * \fBpwmd_realloc\fP (void *ptr, size_t size)"
.br
.ti -1c
.RI "LIBPWMD_API char * \fBpwmd_strdup\fP (const char *str)"
.br
.ti -1c
.RI "LIBPWMD_API char * \fBpwmd_strdup_printf\fP (const char *fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_bulk\fP (\fBpwm_t\fP *pwm, char **result, size_t *len, \fBpwmd_inquire_cb_t\fP callback, void *user, const char *cmds, size_t size)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_bulk_append\fP (char **result, const char *id, size_t id_size, const char *cmd, const char *data, size_t data_size, size_t *offset)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_bulk_append_rc\fP (char **result, gpg_error_t *rcs, const char *id, size_t id_size, const char *cmd, const char *data, size_t data_size, size_t *offset)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_bulk_finalize\fP (char **result)"
.br
.ti -1c
.RI "LIBPWMD_API gpg_error_t \fBpwmd_bulk_result\fP (const char *str, size_t size, const char *id, size_t id_size, size_t *offset, const char **result, size_t *result_len, gpg_error_t *cmd_rc)"
.br
.in -1c
.SH "Detailed Description"
.PP 
libpwmd is a library making it easy for applications to use the pwmd server\&. Pwmd version 3\&.2 or later is required; either locally or remotely\&.
.SH "Threads"
.PP
\fBlibpwmd\fP should be thread-safe on a per handle bases\&. Meaning that only one thread should access a \fBpwm_t\fP handle at a time\&.
.SH "Remote Connection Details"
.PP
There are two methods of connecting to a remote pwmd server: over SSH and over TLS\&.
.PP
Connections over SSH are done by creating an SSH channel to spawn a shell that executes a proxy server to connect to the pwmd local Unix Domain Socket\&. Authentication is done by using SSH public key (see \fBssh-keygen(1)\fP) authentication and verifying the host key against a local OpenSSH known hosts formatted file\&.
.PP
An unknown servers public key can be added to a known hosts file after user confirmation by setting the callback function \fBpwmd_knownhost_cb_t\fP before connecting to the unknown host\&.
.PP
On the server side you'll need a proxy server to connect to the pwmd server\&. Below is an example of an \fBauthorized_keys(5)\fP entry that will do this\&. The \fIpublic_key\fP portion should be the same as the contents of the \fBssh-keygen(1)\fP \fIidentity\&.pub\fP file generated on the client machine\&. The private key should be passed as the \fIidentity\fP parameter to \fBpwmd_connect()\fP:
.PP
.PP
.nf
command="socat UNIX-CONNECT:$HOME/\&.pwmd/socket -" <public_key> \&.\&.\&.
.fi
.PP
.PP
Pwmd itself can accept TLS connections so no proxy program is needed as is when using SSH\&. Like SSH connections, TLS connections are created with \fBpwmd_connect()\fP\&. You will need to generate a client key and X509 certificate and then sign it with the same certificate authority (CA) that the pwmd server certificate was signed with\&.
.PP
Certificates are similar to SSH public and private keys but a little harder to setup correctly\&. See the \fBcerttool(1)\fP (recommended) and \fBopenssl(1)\fP manual pages for details\&.
.SH "Pinentry Details"
.PP
\fBpinentry(1)\fP is a program that prompts the user for input which is normally a passphrase or a confirmation\&. libpwmd can use this program either locally (X11 forwarding is not yet supported) or have the pwmd server (read: \fBgpg-agent(1)\fP) call pinentry to retrieve a passphrase when needed\&.
.PP
There are a few options that tell pinentry how and where to prompt for a needed passphrase\&. See the \fBpwmd_option_t\fP section for details\&. These options are sent to pwmd during \fBpwmd_open()\fP, \fBpwmd_save()\fP and \fBpwmd_passwd()\fP only when pinentry use has not been disabled (\fBPWMD_OPTION_NO_PINENTRY\fP) and when not over a remote connection\&.
.PP
Some pinentry options may also be specified in the local configuration file \fI'~/\&.config/libpwmd\&.conf'\fP\&.
.PP
\fBNote\fP
.RS 4
When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user\&.
.PP
The initial values for the pinentry TTY, TERM and DISPLAY are set during \fBpwmd_new()\fP depending on the current environment\&. They are then updated to the values specified in \fI~/\fP\&.config/libpwmd\&.conf\&. They can then be reset or changed as needed by using \fBpwmd_setopt()\fP\&.
.PP
After establishing a remote connection, pwmd's pinentry is disabled by sending the pwmd option \fI'disable-pinentry'\fP during \fBpwmd_open()\fP\&. A local pinentry will be used instead\&.
.RE
.PP
\fBSee also\fP
.RS 4
\fBRemote Connection Details\fP, \fBConfiguration File\fP
.RE
.PP
.SH "Configuration File"
.PP
Initial values overriding libpwmd defaults for a handle may be specified in the configuration file \fI~/\fP\&.config/libpwmd\&.conf\&. This file is read only once during \fBpwmd_new()\fP\&. Option values may be updated by setting the associated option with \fBpwmd_setopt()\fP\&. Blank lines and lines beginning with a '#' are ignored as are unrecognized options\&. See the documentation for each option for its' value type\&. Valid options are:
.PP
\fBpinentry-path\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_PATH\fP\&. This option is deprecated and does nothing\&.
.RE
.PP
\fBpinentry-display\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_DISPLAY\fP\&.
.RE
.PP
\fBpinentry-ttyname\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_TTY\fP\&.
.RE
.PP
\fBpinentry-ttytype\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_TERM\fP\&.
.RE
.PP
\fBpinentry-lc-messages\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_LC_MESSAGES\fP\&.
.RE
.PP
\fBpinentry-lc-ctype\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_LC_CTYPE\fP\&.
.RE
.PP
\fBpinentry-timeout\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_TIMEOUT\fP\&.
.RE
.PP
\fBpinentry-tries\fP
.RS 4
Same as \fBPWMD_OPTION_PINENTRY_TRIES\fP\&.
.RE
.PP
\fBno-pinentry\fP
.RS 4
Same as \fBPWMD_OPTION_NO_PINENTRY\fP\&.
.RE
.PP
\fBlocal-pinentry\fP
.RS 4
Same as \fBPWMD_OPTION_LOCAL_PINENTRY\fP\&.
.RE
.PP
\fBno-ssh-agent\fP
.RS 4
Same as \fBPWMD_OPTION_SSH_AGENT\fP\&.
.RE
.PP
\fBno-tls-verify\fP
.RS 4
Same as \fBPWMD_OPTION_TLS_VERIFY\fP\&.
.RE
.PP
\fBtls-priority\fP
.RS 4
Same as \fBPWMD_OPTION_TLS_PRIORITY\fP\&.
.RE
.PP
\fBsocket-timeout\fP
.RS 4
Same as \fBPWMD_OPTION_SOCKET_TIMEOUT\fP\&.
.RE
.PP
\fBno-lock\fP
.RS 4
Same as \fBPWMD_OPTION_LOCK_ON_OPEN\fP\&.
.RE
.PP
\fBlock-timeout\fP
.RS 4
Same as \fBPWMD_OPTION_LOCK_TIMEOUT\fP\&.
.RE
.PP
\fBinclude\fP
.RS 4
Path to file containing additional libpwmd\&.conf settings\&.
.RE
.PP
.SH "Errors"
.PP
libpwmd uses libgpg-error for all error codes\&. Error codes can be described by using \fBgpg_strerror()\fP, or the thread-safe \fBgpg_strerror_r()\fP\&.
.PP
\fBNote\fP
.RS 4
libgpg-error returns an error code as a bitmask of an error source and the error code\&. Determining the error source can help you determine where the error occurred, be it from \fBpinentry(1)\fP, \fBgpg-agent(1)\fP, \fBlibgcrypt\fP, \fBpwmd(1)\fP or \fBlibpwmd(3)\fP\&. pwmd uses the \fBGPG_ERR_SOURCE_USER_1\fP error source and libpwmd uses \fBGPG_ERR_SOURCE_USER_2\fP\&. To view the error source and description of an error code the \fBgpg-error(1)\fP command line utility may be of use\&. Also see the \fBlibgpg-error\fP texinfo documentation for error code manipulation\&. 
.RE
.PP

.SH "Macro Definition Documentation"
.PP 
.SS "#define LIBPWMD_VERSION   0x080403"

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

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

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

.PP
Version information\&. The patch level of this library\&. 
.SS "#define LIBPWMD_VERSION_STR   '8\&.4\&.3'"

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

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

.SS "#define PWMD_FEATURE_PINENTRY"

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

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

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

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

.PP
A libpwmd handle\&. When a pwmd handle or context is mentioned in this documentation it is a pointer of this type\&. A new handle is created with \fBpwmd_new()\fP\&. 
.SS "pwmd_inquire_cb_t"

.PP
Send data to the pwmd server\&. This is a callback function that is used for sending data to the server for commands that need to reply to an INQUIRE server response\&. The reason for this callback is to let the client send as many bytes as it wants rather than the entire data at once\&. It gets called during an internal \fBassuan_transact()\fP from an internal inquire callback function which in turn calls this function by looping over its return value\&.
.PP
\fBParameters\fP
.RS 4
\fIuser\fP The user data pointer passed to the libpwmd function specifying this callback\&. 
.br
\fIkeyword\fP The name of this inquire\&. Could be a command name or some keyword describing what needs to be sent\&. See the pwmd and \fBgpg-agent(1)\fP documentation for details\&. 
.br
\fIrc\fP The result of the last internal call to \fBassuan_send_data()\fP which did the sending of the data to the pwmd server\&. On the first call to this callback it's value will always be 0 since no data has been sent yet\&. This should be checked during each call to this function and should return the same error code when set\&. Its purpose is to let the client clean up before letting the command fail\&. 
.br
\fIdata\fP The next chunk of data to send or NULL\&. 
.br
\fIlen\fP The length of \fIdata\fP or 0\&.
.RE
.PP
\fBReturn values\fP
.RS 4
\fI0\fP There is more data to be sent\&. 
.br
\fIGPG_ERR_EOF\fP No need to call this function again, the current \fIdata\fP is the last to send\&. 
.br
\fIcode\fP Any other error code which will cancel the INQUIRE\&.
.RE
.PP
\fBNote\fP
.RS 4
The sent data is processed line-per-line\&. The line is either newline terminated or is buffered until ASSUAN_LINELENGTH bytes have been allocated\&. Any remaining bytes are sent after the INQUIRE has finished\&. 
.RE
.PP

.SS "pwmd_knownhost_cb_t"

.PP
Verify a remote SSH connection\&. When the current SSH connections host key was not found in the known hosts file, then this callback function can be used to confirm the addition of the new host key to the known_hosts file\&. When \fBPWMD_OPTION_KNOWNHOST_CB\fP is not set then the default callback function will be used\&.
.PP
\fBParameters\fP
.RS 4
\fIuser\fP User data which was set with \fBPWMD_OPTION_KNOWNHOST_DATA\fP\&. 
.br
\fIhost\fP The hostname as passed to \fBpwmd_connect()\fP\&. 
.br
\fIhostkey\fP The raw binary data of the host key\&. 
.br
\fIlen\fP The length of \fIhostkey\fP\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI0\fP Add the host key to the known hosts file\&. 
.br
\fIGPG_ERR_NOT_CONFIRMED\fP Do not add the host key and abort the connection\&. This is the recommended error code although any other non-zero return value will also abort the connection\&.
.RE
.PP
\fBNote\fP
.RS 4
If the known hosts file cannot be modified do to filesystem restrictions when adding the new host key, no error is returned\&. Instead, the host key is added to the current connections host key cache and the connection is accepted\&.
.RE
.PP
\fBSee also\fP
.RS 4
\fBRemote Connection Details\fP 
.RE
.PP

.SS "pwmd_passphrase_cb_t"

.PP
Obtain a passphrase during SSH authentication\&. If your SSH identity file requires a passphrase then this callback can be used to obtain it\&. When \fBPWMD_OPTION_PASSPHRASE_CB\fP is not set then the default callback function will be used\&.
.PP
\fBParameters\fP
.RS 4
\fIuser\fP User data which was set with \fBPWMD_OPTION_PASSPHRASE_DATA\fP\&. 
.br
\fIhost\fP The hostname as passed to \fBpwmd_connect()\fP\&. 
.br
\fIfilename\fP The identity file to decrypt\&. 
.br
\fIpassphrase\fP The passphrase to use for decryption which must be allocated with \fBpwmd_strdup()\fP, \fBpwmd_malloc()\fP or \fBpwmd_calloc\fP ()\&. It will be freed by libpwmd\&. 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI0\fP The passphrase was set successfullly and continue authentication\&. 
.br
\fInon-zero\fP Abort the connection\&.
.RE
.PP
\fBSee also\fP
.RS 4
\fBRemote Connection Details\fP 
.RE
.PP

.SS "pwmd_read_cb_t"

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

.SS "pwmd_status_cb_t"

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

.SS "pwmd_write_cb_t"

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

.SH "Enumeration Type Documentation"
.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\&. This option is deprecated and does nothing\&.
.PP
\fBNote\fP
.RS 4
This only affects the local pinentry\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBPinentry Details\fP 
.RE
.PP

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

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

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

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

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

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

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

.TP
\fB\fIPWMD_OPTION_INQUIRE_TOTAL \fP\fP
When the total number of bytes to be sent via an INQUIRE is known, this should be set so XFER status messages can be parsed correctly\&. When not known or unset, 0 is used as the total argument to the XFER status message\&. This option should be reset in every function that uses an \fBpwmd_inquire_cb_t\fP\&.
.PP
\fBNote\fP
.RS 4
During the INQUIRE, \fBPWMD_OPTION_STATUS_CB\fP is called, when set, after every iteration of the \fBpwmd_inquire_cb_t\fP\&.
.PP
This is a libpwmd feature\&. pwmd itself does not send XFER status messages during an INQUIRE\&. Status messages can be parsed only when \fBPWMD_OPTION_STATUS_CB\fP is set\&. 
.RE
.PP

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

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

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

.TP
\fB\fIPWMD_OPTION_SOCKET_TIMEOUT \fP\fP
An int specifying a timeout in seconds before a TCP connection or data transfer function will timeout causing a connection or command to fail\&. This option can be specified both before and after a connection has been established\&. When 0, no timeout is used\&. 
.TP
\fB\fIPWMD_OPTION_TLS_VERIFY \fP\fP
An int specifying whether to enable TLS hostname verification against the server certificate chain\&. Default is 0 or disabled\&. 
.TP
\fB\fIPWMD_OPTION_SIGPIPE \fP\fP
Set to 1 to not modify the signal handler to ignore SIGPIPE\&. The default is 0, or to ignore this signal\&. 
.TP
\fB\fIPWMD_OPTION_SERVER_VERSION \fP\fP
Get the version of the pwmd server as an unsigned integer\&. This is a read-only setting and is only available after connecting\&. 
.TP
\fB\fIPWMD_OPTION_SSH_NEEDS_PASSPHRASE \fP\fP
The SSH identity file requires a passphrase\&. When set, prompt for the passphrase after connecting\&. This option has been deprecated\&. Libpwmd will prompt for a password when needed\&. 
.TP
\fB\fIPWMD_OPTION_SSH_PASSPHRASE \fP\fP
Set SSH private identity passphrase\&. The value of this option is duplicated then freed after the call to \fBpwmd_connect()\fP\&. 
.TP
\fB\fIPWMD_OPTION_TLS_PRIORITY \fP\fP
The TLS cipher priority string to use for a TLS connection\&. The default is SECURE256:SECURE192:SECURE128:-VERS-SSL3\&.0:-VERS-TLS1\&.0\&. 
.TP
\fB\fIPWMD_OPTION_READ_CB \fP\fP
The callback function of type \fBpwmd_read_cb_t\fP to use to read from a socket\&. 
.TP
\fB\fIPWMD_OPTION_READ_CB_DATA \fP\fP
The data to pass to the custom read function \fBpwmd_read_cb_t\fP\&. 
.TP
\fB\fIPWMD_OPTION_WRITE_CB \fP\fP
The callback function of type \fBpwmd_write_cb_t\fP to use to write to a socket\&. 
.TP
\fB\fIPWMD_OPTION_WRITE_CB_DATA \fP\fP
The data to pass to the custom write function \fBpwmd_write_cb_t\fP\&. 
.TP
\fB\fIPWMD_OPTION_LOCK_TIMEOUT \fP\fP
The time in tenths of a second to wait for another client to release the mutex associated with a data file before returning an error\&. See the pwmd(1) manual for details\&. 
.TP
\fB\fIPWMD_OPTION_STATE_STATUS \fP\fP
Whether to inform pwmd that you would like to receive client state changes for other clients via a status message\&. 
.TP
\fB\fIPWMD_OPTION_PASSPHRASE_CB \fP\fP
A function of type \fBpwmd_passphrase_cb_t\fP that will be used to obtain a passphrase to use for decryption of an SSH identity file\&.
.PP
\fBSee also\fP
.RS 4
\fBRemote Connection Details\fP 
.RE
.PP

.TP
\fB\fIPWMD_OPTION_PASSPHRASE_DATA \fP\fP
User supplied data which is passed to the passphrase function \fBPWMD_OPTION_PASSPHRASE_CB\fP\&.
.PP
\fBSee also\fP
.RS 4
\fBRemote Connection Details\fP 
.RE
.PP

.SS "enum \fBpwmd_pinentry_t\fP"

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

.PP
The type of socket a handle is connected to\&. For use with \fBpwmd_socket_type()\fP\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIPWMD_SOCKET_LOCAL \fP\fP
A local UNIX domain socket\&. 
.TP
\fB\fIPWMD_SOCKET_SSH \fP\fP
An SSH channel over a TCP socket\&. 
.TP
\fB\fIPWMD_SOCKET_TLS \fP\fP
A TLS connection over a TCP socket\&. 
.TP
\fB\fIPWMD_SOCKET_USER \fP\fP
A socket set with \fBpwmd_connect_fd()\fP\&. 
.SH "Function Documentation"
.PP 
.SS "LIBPWMD_API gpg_error_t pwmd_bulk (\fBpwm_t\fP * pwm, char ** result, size_t * len, \fBpwmd_inquire_cb_t\fP callback, void * user, const char * cmds, size_t size)"

.PP
Send multiple commands in sequence\&. Multiple commands may be sent to a pwmd server by using the \fCBULK\fP protocol command to send an s-expression containing all of the commands to send along with their unique identifiers and command data\&. See the \fCpwmd\fP documentation for details about this command\&.
.PP
This function uses the \fIINQUIRE\fP variation of the \fCBULK\fP command\&. If you do not need to use any callback functions for any command in \fIcmds\fP, then you can avoid the extra socket IO that an inquire uses by calling \fBpwmd_command()\fP instead\&.
.PP
\fBpwmd_bulk_append()\fP may be used to create a command list with the required syntax\&.
.PP
This function returns the result of all commands and can be easily parsed with \fBpwmd_bulk_result()\fP\&.
.PP
\fBParameters\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIresult\fP The result of all commands in the \fCpwmd\fP bulk-result syntax and 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
\fIcmds\fP The canonical s-expression bulk command list to send\&. 
.br
\fIsize\fP The length of \fIcmds\fP\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBpwmd_bulk_append()\fP, \fBpwmd_bulk_append_rc()\fP, \fBpwmd_bulk_finalize()\fP, \fBpwmd_bulk_result()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_bulk_append (char ** result, const char * id, size_t id_size, const char * cmd, const char * data, size_t data_size, size_t * offset)"

.PP
Create or append a command to a command list\&. This function creates the required \fCpwmd\fP s-expression syntax for use with \fBpwmd_bulk()\fP from the function parameters\&.
.PP
\fBParameters\fP
.RS 4
\fIresult\fP A newly allocated or modified command list containing the s-expression syntax to be passed to the \fCBULK\fP protocol command\&. Can be used more than once to append more commands to the same \fIresult\fP\&. 
.br
\fIid\fP A unique identifier for this command\&. 
.br
\fIid_size\fP The length of \fIid\fP\&. 
.br
\fIcmd\fP The protocol command name to send\&. 
.br
\fIdata\fP Data for the command which may be NULL\&. 
.br
\fIdata_size\fP The length of \fIdata\fP\&. 
.br
\fIoffset\fP When not \fCNULL\fP, the position in \fIresult\fP where this command syntax will be inserted\&. It is updated to point to the end position of the newly created syntax\&. When \fCNULL\fP, the syntax is appended to the end of \fIresult\fP\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBpwmd_bulk_append_rc()\fP, \fBpwmd_bulk_finalize()\fP, \fBpwmd_bulk_result()\fP, \fBpwmd_bulk()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_bulk_append_rc (char ** result, gpg_error_t * rcs, const char * id, size_t id_size, const char * cmd, const char * data, size_t data_size, size_t * offset)"

.PP
Add return code syntax to a command list\&. Creates the needed s-expression syntax to consider a return code for a previously added command by using the \fIoffset\fP result of \fBpwmd_bulk_append()\fP\&. When the return code for the previous command matches one or more of the specified \fIrcs\fP, the new command branch created from the parameters is run\&.
.PP
Normally, the \fIoffset\fP will point to the end of the previously added command, and by using the same \fIoffset\fP you can test multiple return codes for the same command\&.
.PP
To consider the return code for a command that was added with this function, decrement the \fIoffset\fP by \fC1\fP to place the specified command syntax inside the previous commands parentheses\&.
.PP
The \fIrcs\fP parameter is an array of \fCgpg_error_t\fP error codes and must be terminated with \fCGPG_ERR_MISSING_ERRNO\fP\&.
.PP
\fBParameters\fP
.RS 4
\fIresult\fP A modified command list containing the s-expression syntax to be passed to the \fCBULK\fP protocol command\&. Can be used more than once to consider multiple return codes for a previous command\&. 
.br
\fIrcs\fP The return code(s) to test for\&. 
.br
\fIid\fP A unique identifier for this command\&. 
.br
\fIid_size\fP The length of \fIid\fP\&. 
.br
\fIcmd\fP The protocol command name to send\&. 
.br
\fIdata\fP Data for the command which may be NULL\&. 
.br
\fIdata_size\fP The length of \fIdata\fP\&. 
.br
\fIoffset\fP Where in \fIresult\fP to insert the return code s-expression syntax\&. It is updated to point to the end position of the newly created syntax\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBpwmd_bulk_append()\fP, \fBpwmd_bulk_finalize()\fP, \fBpwmd_bulk_result()\fP, \fBpwmd_bulk()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_bulk_finalize (char ** result)"

.PP
Finalize a bulk command list\&. This function must be called after the final command is added to a command list\&. It fixes up the syntax for the bulk command list\&.
.PP
\fBParameters\fP
.RS 4
\fIresult\fP The bulk command list created with \fBpwmd_bulk_append()\fP\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBpwmd_bulk_append()\fP, \fBpwmd_bulk_append_rc()\fP, \fBpwmd_bulk()\fP 
.RE
.PP

.SS "LIBPWMD_API gpg_error_t pwmd_bulk_result (const char * str, size_t size, const char * id, size_t id_size, size_t * offset, const char ** result, size_t * result_len, gpg_error_t * cmd_rc)"

.PP
Extract the result of a bulk command\&. Pass the result of the \fCBULK\fP command to this function to extract the return value and any command data for a given command \fIid\fP\&. The \fIoffset\fP is adjusted to point to the next commnand \fIid\fP so the order of processing command results should be in the same sequence as was passed to the \fCBULK\fP command\&.
.PP
\fBParameters\fP
.RS 4
\fIstr\fP The resulting s-expression as returned from \fBpwmd_bulk()\fP\&. 
.br
\fIsize\fP The length of \fIstr\fP\&. 
.br
\fIid\fP The command ID to extract\&. 
.br
\fIid_size\fP The length of \fIid\fP\&. 
.br
\fIoffset\fP The offset of \fIstr\fP to start searching for \fIid\fP\&. When \fIid\fP is found in \fIstr\fP, the \fIoffset\fP is updated to point past the data of the current \fIid\fP\&. 
.br
\fIresult\fP The data of the command or NULL if there was none\&. This is a pointer to a location in \fIstr\fP\&. 
.br
\fIresult_len\fP The length of \fIresult\fP\&. 
.br
\fIcmd_rc\fP The return code of the command\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBpwmd_bulk()\fP 
.RE
.PP

.SS "LIBPWMD_API void * pwmd_calloc (size_t nmemb, size_t size)"

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

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

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

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

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

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

.PP
Send a command to the pwmd server\&. You should avoid sending the BYE command here because the assuan context will be freed and bad things will happen\&. Use \fBpwmd_close()\fP instead\&.
.PP
For pwmd commands that use an INQUIRE to retrieve data from a client, the \fIcallback\fP parameter must be non-NULL and will be used to send the data to pwmd\&.
.PP
\fBParameters\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIresult\fP The result of the command when successful which must be freed with \fBpwmd_free()\fP\&. 
.br
\fIlen\fP The length of \fIresult\fP\&. 
.br
\fIcallback\fP A callback function to invoke when pwmd inquires data from the client\&. 
.br
\fIuser\fP User data passed to the \fIcallback\fP function\&. 
.br
\fIcmd\fP The command to send and any command arguments\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success or an error code\&.
.RE
.PP
\fBNote\fP
.RS 4
Not all commands return a \fIresult\fP\&. 
.RE
.PP

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

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

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

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

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

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

.SS "LIBPWMD_API void pwmd_deinit (void)"

.PP
Deinitialize the library\&. This function is mainly for cleaning up other libraries that libpwmd links with to prevent memory and other leaks showing up in a debugger\&. It should be the final libpwmd function call before your app exits\&. 
.SS "LIBPWMD_API gpg_error_t pwmd_disconnect (\fBpwm_t\fP * pwm)"

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

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

.PP
Get the file descriptor associated with a handle\&. May be useful to determine whether a handle is ready for reading or writing by using select(2) or poll(2)\&.
.PP
\fBParameters\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIfd\fP Set to the file descriptor associated with \fIpwm\fP\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP

.SS "LIBPWMD_API unsigned int pwmd_features ()"

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

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

.PP
Free a previously allocated pointer\&. Use this function to free resources allocated by the other libpwmd memory functions\&. Do not use it to free allocations made by other allocators\&.
.PP
The difference between the standard free() and this function is that this one will zero out the contents of the pointer before freeing it\&.
.PP
\fBParameters\fP
.RS 4
\fIptr\fP The pointer to deallocate\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBpwmd_malloc()\fP, \fBpwmd_calloc()\fP, \fBpwmd_realloc()\fP, \fBpwmd_strdup()\fP, \fBpwmd_command()\fP 
.RE
.PP

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

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

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

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

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

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

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

.PP
Launch a local pinentry\&. Does not send any command to the pwmd server\&. This maybe useful if a passphrase is needed while opening a file over a remote connection and during an \fBpwmd_open()\fP server inquire\&.
.PP
This function may also be used to display a user confirmation dialog with pinentry when \fIwhich\fP is \fBPWMD_PINENTRY_CONFIRM\fP\&. The text show in the pinentry is set with \fBpwmd_setopt()\fP\&.
.PP
\fBParameters\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIfilename\fP The filename to use in the pinentry dialog strings when using the default pinentry strings\&. 
.br
\fIresult\fP The entered value in the pinentry dialog which should be freed with \fBpwmd_free()\fP\&. 
.br
\fIlen\fP The length of \fIresult\fP\&. 
.br
\fIwhich\fP Determines the default strings shown in the pinentry dialog\&. \fBpwmd_setopt()\fP may also be used to override the defaults\&. In this case \fBPWMD_PINENTRY_USER\fP should be used\&. \fBPWMD_PINENTRY_CLOSE\fP should be used to terminate the pinentry process when the pinentry is no longer needed\&.
.RE
.PP
\fBReturns\fP
.RS 4
0 on success or an error\&.
.RE
.PP
\fBSee also\fP
.RS 4
\fBpwmd_password()\fP 
.RE
.PP

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

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

.SS "LIBPWMD_API gpg_error_t pwmd_init (void)"

.PP
Initialize the library\&. This function must be the first function called in the library before any others\&. It sets up the memory allocators and internationalization among other things\&.
.PP
\fBReturns\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP

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

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

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

.PP
Creates a new handle\&. Creates a new handle or context for use with the other functions\&.
.PP
\fBParameters\fP
.RS 4
\fIname\fP If not NULL, the name of the application\&. The application name is sent to the pwmd server after successfully connecting and is used in pwmd logging\&. 
.br
\fIpwm\fP A new handle for use with the other functions\&.
.RE
.PP
\fBReturns\fP
.RS 4
0 on success or an error code\&. 
.RE
.PP

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

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

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

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

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

.PP
Obtain a passphrase from a local pinentry\&. This is the same function that libpwmd uses during an inquire when using the local pinentry and the inquire keyword is one of PASSPHRASE, NEW_PASSPHRASE or SIGN_PASSPHRASE\&. Provided for convenience since it sets proper pinentry strings and handles new passphrase confirmation\&.
.PP
\fBParameters\fP
.RS 4
\fIpwm\fP A handle\&. 
.br
\fIkeyword\fP The keyword to determine pinentry strings\&. Usually one of PASSPHRASE, NEW_PASSPHRASE or SIGN_PASSPHRASE as sent by pwmd\&. 
.br
\fIresult\fP The obtained passphrase which should be freed with \fBpwmd_free()\fP\&. 
.br
\fIsize\fP The length of \fIresult\fP\&.
.RE
.PP
\fBReturns\fP
.RS 4
0 on success or an error\&. 
.RE
.PP

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

.SS "LIBPWMD_API const char * pwmd_version ()"

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

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