Added support for a passphrase in the url string.

[libpwmd.git] / doc / libpwmd.3

.TH "libpwmd.h" 3 "9 Apr 2009" "Version 6.0.0" "libpwmd" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libpwmd.h \- 
.SH "Detailed Description"
.PP 
libpwmd is a library making it easy for applications to use the pwmd server.
.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. Authenication is done by using SSH public key (see \fBssh-keygen(1)\fP) authentication and verifying the host key against a local file containing SHA1 hashes of known hosts. It's alot like how the standard OpenSSH does things only the known_hosts file is in a different format.
.PP
The server hash can be had by using \fBpwmd_get_hostkey()\fP and storing the result in a file. This file is then used as the \fIknown_hosts\fP argument to the SSH connection functions.
.PP
Here's an example \fBauthorized_keys(5)\fP entry. The hash portion should be the same as the contents of the \fIidentity.pub\fP file which is passed as a parameter to the SSH connection functions:
.PP
.PP
.nf
 command='socat gopen:$HOME/.pwmd/socket -' <hash> ...
.fi
.PP
.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 (the connection is to a remote server not on this host) or have the pwmd server use it's pinentry to retrieve a passphrase when needed.
.PP
There are a few options that tell pinentry how and where to prompt for a passphrase. See the \fBpwmd_option_t\fP section for details. These options are not sent (when using pwmd's pinentry) 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 'OPTION PINENTRY=0' to the server. This is needed for pinentry retries (passphrase or confirmation failure). So if you need to change pinentry methods, then set this option as needed.
.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 invokation 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
\fBSee also:\fP
.RS 4
\fBSSH Details\fP
.RE
.PP
.SH "Example Client"
.PP
The following example will list the element tree of the data file specified in the first command line argument.
.PP
.PP
.nf
 #include <stdio.h>
 #include <libpwmd.h>

 int main()
 {
     pwm_t *pwm = pwmd_new(NULL);
     gpg_error_t rc = pwmd_connect(pwm, NULL);
     char *result;
     
     if (!rc) {
         rc = pwmd_open(pwm, argv[1]);

         if (!rc) {
             rc = pwmd_command(pwm, &result, '%s', 'LIST');

             if (!rc) {
                 printf('%s', result);
                 pwmd_free(result);
             }
         }
     }

     pwmd_close(pwm);
     
     if (rc)
         fprintf(stderr, 'ERR: %s\n', pwmd_strerror(rc));

     exit(rc ? 1 : 0);
 }
.fi
.PP
 
.SH SYNOPSIS
.br
.PP
.SS "Data Structures"

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

.in +1c
.ti -1c
.RI "#define \fBLIBPWMD_VERSION\fP"
.br
.ti -1c
.RI "#define \fBPWMD_FD_READABLE\fP"
.br
.ti -1c
.RI "#define \fBPWMD_FD_WRITABLE\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_ERROR\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_MAX_SLOTS\fP"
.br
.ti -1c
.RI "#define \fBEPWMD_LOOP\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
.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_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 }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "gpg_error_t \fBpwmd_init\fP (void)"
.br
.ti -1c
.RI "\fBpwm_t\fP * \fBpwmd_new\fP (const char *name)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *path)"
.br
.ti -1c
.RI "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 "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 "gpg_error_t \fBpwmd_connect_url\fP (\fBpwm_t\fP *pwm, const char *url)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_connect_url_async\fP (\fBpwm_t\fP *pwm, const char *url)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_get_hostkey\fP (\fBpwm_t\fP *pwm, const char *host, int port, char **result)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_get_hostkey_async\fP (\fBpwm_t\fP *pwm, const char *host, int port)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_get_fds\fP (\fBpwm_t\fP *pwm, pwmd_fd_t *fds, int *n_fds)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_pending_line\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_setopt\fP (\fBpwm_t\fP *pwm, \fBpwmd_option_t\fP opt,...)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_open\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_open2\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_open_async2\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_open_async\fP (\fBpwm_t\fP *pwm, const char *filename)"
.br
.ti -1c
.RI "\fBpwmd_async_t\fP \fBpwmd_process\fP (\fBpwm_t\fP *pwm, gpg_error_t *rc, char **result)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_save2\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_save_async2\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_save_async\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_command\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd,...)"
.br
.ti -1c
.RI "gpg_error_t \fBpwmd_command_ap\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd, va_list ap)"
.br
.ti -1c
.RI "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 "void \fBpwmd_close\fP (\fBpwm_t\fP *pwm)"
.br
.ti -1c
.RI "void \fBpwmd_free\fP (void *ptr)"
.br
.ti -1c
.RI "void * \fBpwmd_malloc\fP (size_t size)"
.br
.ti -1c
.RI "void * \fBpwmd_calloc\fP (size_t nmemb, size_t size)"
.br
.ti -1c
.RI "void * \fBpwmd_realloc\fP (void *ptr, size_t size)"
.br
.ti -1c
.RI "char * \fBpwmd_strdup\fP (const char *str)"
.br
.ti -1c
.RI "char * \fBpwmd_strdup_printf\fP (const char *fmt,...)"
.br
.ti -1c
.RI "const char * \fBpwmd_strerror\fP (gpg_error_t code)"
.br
.ti -1c
.RI "int \fBpwmd_strerror_r\fP (gpg_error_t code, char *buf, size_t size)"
.br
.in -1c
.SH "Define Documentation"
.PP 
.SS "#define EPWMD_ERROR"
.PP
A general pwmd error with no suitable description. 
.SS "#define EPWMD_FILE_MODIFIED"
.PP
The data file was modified either externally or by another another client while trying to process a command. 
.SS "#define EPWMD_LIBXML_ERROR"
.PP
An XML parse or other libxml2 error occurred. 
.SS "#define EPWMD_LOOP"
.PP
A recursion loop was detected while processing a 'target' attribute. 
.SS "#define EPWMD_MAX_SLOTS"
.PP
The maximum number of cache slots has been reached. There is no available slot for a new file. 
.SS "#define EPWMD_NO_FILE"
.PP
A command required an open file, but no file has yet been opened. 
.SS "#define LIBPWMD_VERSION"
.PP
The version of this library. 
.SS "#define PWMD_FD_READABLE"
.PP
Set when the file descriptor is readable. 
.SS "#define PWMD_FD_WRITABLE"
.PP
Set when the file descriptor is writable. 
.SH "Typedef Documentation"
.PP 
.SS "\fBpwm_t\fP"
.PP
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
This is a callback function that gets passed to \fBpwmd_inquire()\fP. It is used for sending data to the server for commands that return an INQUIRE 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 \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 will always be 0 because 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_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_passphrase_cb_t\fP"
.PP
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. 
.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
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. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code which will cause a command to fail. 
.RE
.PP

.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBpwmd_async_t\fP"
.PP
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
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 IPv6 and IPv4 addresses. Note that IPv6 is tried first. 
.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 which are set with \fBpwmd_setopt()\fP. 
.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 when 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 function pointer. 
.TP
\fB\fIPWMD_OPTION_PASSPHRASE_DATA \fP\fP
User supplied data which is passed to the custom password 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. 
.TP
\fB\fIPWMD_OPTION_PINENTRY_TRIES \fP\fP
An integer value that specifies the specified 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. 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
\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 pointer 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.
.PP
\fBNote:\fP
.RS 4
This option must be set before a connection is made when not the default. 
.RE
.PP

.SH "Function Documentation"
.PP 
.SS "void* pwmd_calloc (size_t nmemb, size_t size)"
.PP
A wrapper around calloc(). 
.PP
Like calloc(), but lets libpwmd keep track of the pointer.
.PP
\fBParameters:\fP
.RS 4
\fInmemb\fP The number of bytes 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 "void pwmd_close (\fBpwm_t\fP * pwm)"
.PP
Close a handle. 
.PP
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

.SS "gpg_error_t pwmd_command (\fBpwm_t\fP * pwm, char ** result, const char * cmd,  ...)"
.PP
Send a command to the pwmd server. 
.PP
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 should 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 and which must be freed with \fBpwmd_free()\fP. Note that not all commands return a result. 
.br
\fIcmd\fP The command to send. 
.br
\fI...\fP The arguments to \fIcmd\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP

.SS "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. 
.PP
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. Note that not all commands return a result. 
.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

.SS "gpg_error_t pwmd_connect (\fBpwm_t\fP * pwm, const char * path)"
.PP
Connect to a local pwmd server. 
.PP
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
\fBSee also:\fP
.RS 4
\fBpwmd_ssh_connect()\fP, \fBpwmd_ssh_connect_async()\fP 
.RE
.PP

.SS "gpg_error_t pwmd_connect_url (\fBpwm_t\fP * pwm, const char * url)"
.PP
Establish a connection by parsing a URL. 
.PP
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
 socket://[path/to/local/socket]

 or

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

.fi
.PP
.PP
The parameters in square brackets are optional and if not specified the defaults will be used.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIurl\fP The string to parse. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP

.SS "gpg_error_t pwmd_connect_url_async (\fBpwm_t\fP * pwm, const char * url)"
.PP
Establish a connection asynchronously by parsing a URL. 
.PP
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
 socket://[path/to/local/socket]

 or

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

.fi
.PP
.PP
The parameters in square brackets are optional and if not specified the defaults will be used.
.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
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP

.SS "void pwmd_free (void * ptr)"
.PP
Free a previously allocated pointer. 
.PP
Use this function to free resources allocated by the other libpwmd memory functions. Do not use it to free your own allocations.
.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 "gpg_error_t pwmd_get_fds (\fBpwm_t\fP * pwm, pwmd_fd_t * fds, int * n_fds)"
.PP
Get the associated file descriptor(s) for a handle. 
.PP
This function lets the application poll the available file descriptors for the specified handle. It should be called after each asynchronous function and after each call to \fBpwmd_process()\fP since the polled file descriptors may have been closed since the last call. It should also be called periodically to determine when to call \fBpwmd_process()\fP to parse any pending status messages.
.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 "gpg_error_t pwmd_get_hostkey (\fBpwm_t\fP * pwm, const char * host, int port, char ** result)"
.PP
Retrieve a remote SSH host key. 
.PP
This key is needed for host verification of the remote pwmd server.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIhost\fP The hostname to connect to. 
.br
\fIport\fP The port. 
.br
\fIresult\fP The server host key which must be freed with \fBpwmd_free()\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_get_hostkey_async()\fP, \fBSSH Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_get_hostkey_async (\fBpwm_t\fP * pwm, const char * host, int port)"
.PP
Retrieve a remote SSH host key asynchronously. 
.PP
This key is needed for host verification of the remote pwmd server.
.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. 
.br
\fIport\fP The port or a default if set to -1. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_get_hostkey()\fP, \fBpwmd_process()\fP, \fBSSH Details\fP 
.RE
.PP

.SS "gpg_error_t pwmd_init (void)"
.PP
Initialize the library. 
.PP
This function must be the first function called in the library before any others. It sets up internationalization among other things.
.PP
\fBReturns:\fP
.RS 4
0 Success. 
.RE
.PP

.SS "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. 
.PP
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 commands.
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIcmd\fP The command to send that uses an INQUIRE. 
.br
\fIfunc\fP A callback function 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 "void* pwmd_malloc (size_t size)"
.PP
A wrapper around malloc. 
.PP
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 "\fBpwm_t\fP* pwmd_new (const char * name)"
.PP
Creates a new handle. 
.PP
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.
.br
\fIname\fP The application name or NULL. 
.RE
.PP
\fBReturns:\fP
.RS 4
a new handle or NULL if there was not enough memory. 
.RE
.PP

.SS "gpg_error_t pwmd_open (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server. 
.PP
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. 
.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 "gpg_error_t pwmd_open2 (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server using a local pinentry. 
.PP
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.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIpwm\fP A handle. 
.br
\fIfilename\fP The filename to open. 
.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 "gpg_error_t pwmd_open_async (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server asynchronously. 
.PP
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. 
.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 "gpg_error_t pwmd_open_async2 (\fBpwm_t\fP * pwm, const char * filename)"
.PP
Open a file on the pwmd server asynchronously (fork method). 
.PP
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
The difference from \fBpwmd_open_async()\fP is that libpwmd will \fBfork()\fP a pinentry process rather than have pwmd use it's pinentry method. This may be useful if the passphrase isn't cached on a remote pwmd server and a remote \fBpinentry(1)\fP is not possible.
.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. 
.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 "gpg_error_t pwmd_pending_line (\fBpwm_t\fP * pwm)"
.PP
Check for a unparsed buffered line. 
.PP
A buffered line is a line that was read from the server but was not 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 pending data. 
.br
\fIGPG_ERR_NO_DATA\fP if there is no pending data. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP 
.RE
.PP

.SS "\fBpwmd_async_t\fP pwmd_process (\fBpwm_t\fP * pwm, gpg_error_t * rc, char ** result)"
.PP
Process an asynchronous function. 
.PP
After an asynchronous function has been called and has returned successfully, this function must be called to process the command to retrieve the result or 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 command after ASYNC_DONE is 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 "void* pwmd_realloc (void * ptr, size_t size)"
.PP
A wrapper around realloc(). 
.PP
Like realloc(), but lets libpwmd keep track of the pointer. Note that this function will try and allocate the entire \fIsize\fP before freeing the original pointer and returning the new one.
.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 "gpg_error_t pwmd_save (\fBpwm_t\fP * pwm)"
.PP
Save a file on the pwmd server. 
.PP
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 "gpg_error_t pwmd_save2 (\fBpwm_t\fP * pwm)"
.PP
Save a file on the pwmd server using the local pinentry. 
.PP
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 "gpg_error_t pwmd_save_async (\fBpwm_t\fP * pwm)"
.PP
Save changes to a file on the pwmd server asynchronously. 
.PP
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 "gpg_error_t pwmd_save_async2 (\fBpwm_t\fP * pwm)"
.PP
Save a file on the pwmd server asynchronously (fork method). 
.PP
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
The difference from \fBpwmd_save_async()\fP is that libpwmd will \fBfork()\fP a pinentry process rather than have pwmd use it's pinentry method. This may be useful if the passphrase isn't cached on a remote pwmd server and a remote \fBpinentry(1)\fP is not possible.
.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 "gpg_error_t pwmd_setopt (\fBpwm_t\fP * pwm, \fBpwmd_option_t\fP opt,  ...)"
.PP
Set library options. 
.PP
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 "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. 
.PP
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. 
.br
\fIport\fP The port or -1 for the default. 
.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. 
.br
\fIuser\fP The username on the SSH server to login as. If NULL then invoking user will be used. 
.br
\fIknown_hosts\fP A file containing the public SSH server key hash in SHA1 format. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_ssh_connect_async()\fP, \fBpwmd_process()\fP, \fBSSH Details\fP 
.RE
.PP

.SS "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. 
.PP
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. 
.br
\fIport\fP The port or -1 for the default. 
.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. 
.br
\fIuser\fP The username on the SSH server to login as. If NULL, the invoking username will be used. 
.br
\fIknown_hosts\fP A file containing the public SSH server key hash in SHA1 format. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success or an error code. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBpwmd_process()\fP, \fBSSH Details\fP 
.RE
.PP

.SS "char* pwmd_strdup (const char * str)"
.PP
A wrapper around strdup(). 
.PP
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 "char* pwmd_strdup_printf (const char * fmt,  ...)"
.PP
Duplicate a formatted string. 
.PP
Like sprintf() but returns an allocated string.
.PP
\fBParameters:\fP
.RS 4
\fIfmt\fP The formatted string. 
.br
\fI...\fP Any format arguments to the string. 
.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 "const char* pwmd_strerror (gpg_error_t code)"
.PP
Return a description of an error code. 
.PP
\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 "int pwmd_strerror_r (gpg_error_t code, char * buf, size_t size)"
.PP
Return a description of an error code (thread-safe). 
.PP
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

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