Updated manual page.

[libpwmd.git] / libpwmd.3.in

.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH LIBPWMD 3 "27 Jan 2008" "Password Manager Daemon Library" "Password Manager Daemon Library"
.SH NAME

libpwmd \- pwmd client interface library
.SH SYNOPSIS
.nf
.B #include <libpwmd.h>
.sp
.BI "gpg_error_t pwmd_init(void);"
.BI "pwm_t *pwmd_connect(const char *" socket ", gpg_error_t *" error ");"
.BI "gpg_error_t pwmd_setopt(pwm_t *" pwm ", pwmd_option_t " opt ", ...);"
.BI "gpg_error_t pwmd_open(pwm_t *" pwm ", const char *" filename ");"
.BI "int pwmd_open_nb(pwm_t *" pwm ", gpg_error_t *" error ", const char *" filename ", int " timeout ");"
.BI "gpg_error_t pwmd_open_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
.BI "gpg_error_t pwmd_open_async(pwm_t *" pwm ", const char *" filename ");"
.BI "int pwmd_open_nb(pwm_t *" pwm ", gpg_error_t *" error ", const char *" filename ", int " timeout ");"
.BI "gpg_error_t pwmd_command(pwm_t *" pwm ", char **" result ", const char *" cmd ", " ... ");"
.BI "void pwmd_free_result(void *" result ");"
.BI "gpg_error_t pwmd_inquire(pwm_t *" pwm ", const char *" cmd ", pwmd_inquire_fn " func ", void *" data ");"
.BI "gpg_error_t pwmd_save(pwm_t *" pwm ");"
.BI "int pwmd_save_nb(pwm_t *" pwm ", gpg_error_t *" error ");"
.BI "gpg_error_t pwmd_save_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
.BI "gpg_error_t pwmd_save_async(pwm_t *" pwm ");"
.BI "pwmd_async_t pwmd_process(pwm_t *" pwm ", gpg_error_t *" error ");"
.BI "gpg_error_t pwmd_finalize(pwm_t *" pwm ");"
.BI "gpg_error_t pwmd_terminate_pinentry(pwm_t *" pwm ");"
.BI "void pwmd_close(pwm_t *" pwm ");"
.BI "const char *pwmd_strerror(gpg_error_t " error ");"
.P
.BI "typedef int (*" pwmd_status_fn ")(void *" data ", const char *" line ");"
.BI "typedef char *(*" pwmd_password_fn ")(pwm_t *" pwm ", void *" data ");"
.BI "typedef gpg_error_t (*" pwmd_inquire_fn ")(void *" data ", const char *" keyword ", gpg_error_t " rc ", char **" result ", size_t *" len ");"
.fi
.SH DESCRIPTION
.B libpwmd
is an library making it easy for applications to use
.BR pwmd (1).
.P
.TP
.BI "gpg_error_t pwmd_init(void);"
Initializes \fBlibpwmd\fP, \fBlibassuan\fP, \fBlibgpg-error\fP and
internationalization. Be sure to call this before using the other functions.
If your application uses
.BR gettext(3)
be sure to call
.BR setlocale(3)
and
.BR textdomain(3)
before calling this function.
.P
.TP
.BI "pwm_t *pwmd_connect(const char *" socket ", gpg_error_t *" error ");"
Connects to the specified \fIsocket\fP. If \fIsocket\fP is NULL then a default
of \fI~/.pwmd/socket\fP will be used. If there is an error while connecting
\fIerror\fP is set to the error code of the failed function and NULL is
returned. When successful a handle is returned for use with the other library
functions.
.P
.TP
.BI "gpg_error_t pwmd_setopt(pwm_t *" pwm ", pwmd_option_t " opt ", ...);"
Set the library option \fIopt\fP to the value of the next argument. Returns 0
on success or an error code. \fIopt\fP is one of the following:
.RS
.TP
.B PWMD_OPTION_PASSWORD_FUNC
Specifies a function to use to get a password. The next argument should be of
type \fIpwmd_password_fn\fP. The function should return a \fIchar
*\fP string which is the password or NULL if there is an
error.
.TP
.B PWMD_OPTION_PASSWORD_DATA
A user data pointer passed to the password function.
.TP
.B PWMD_OPTION_PINENTRY
Whether to use 
.BR pinentry (1)
to obtain the password when opening and saving a file on the server. The
following argument is an \fIint\fP and is \fI1\fP to enable
.BR pinentry (1)
use, and \fI0\fP to use the password which is set with
\fBPWMD_OPTION_PASSWORD\fP or \fBPWMD_OPTION_PASSWORD_FUNC\fP. When \fI1\fP,
.BR pwmd (1)
won't use pinentry but return an error instead.
.TP
.B PWMD_OPTION_PINENTRY_TRIES
The next argument if type \fIint\fP specifies the number of invalid password
tries before
.BR pinentry (1)
gives up. Only \fBpwmd_open\fP() and \fBpwmd_open_nb\fP() will use this
option. \fBpwmd_save\fP() and \fBpwmd_save_nb\fP() will continue to confirm a
password until either a match is entered or Cancel is selected.
.TP
.B PWMD_OPTION_PINENTRY_TTY
.TP
.B PWMD_OPTION_PINENTRY_TERM
.TP
.B PWMD_OPTION_PINENTRY_DISPLAY
.TP
.B PWMD_OPTION_PINENTRY_PATH
Sets the
.BR pinentry (1)
command line options. The next argument should be of type \fIchar *\fP. If not
set, then the current DISPLAY, if set, or tty will be used.
.P
.RS
If the file \fI~/.pwmd/pinentry.conf\fP exists then values for the above settings will
be read from this file. The format of the file is one NAME=VALUE per line where
NAME is one of TTYNAME, TTYTYPE, DISPLAY or PATH. The value for an existing
setting will be updated to the value contained in the file. Note that the
server can also use this file for its
.BR pinentry (1)
settings.
.RE
.TP
.B PWMD_OPTION_PINENTRY_TITLE
.TP
.B PWMD_OPTION_PINENTRY_DESC
.TP
.B PWMD_OPTION_PINENTRY_PROMPT
Sets the strings used in the 
.BR pinentry (1)
program.
The next argument is of type \fIchar *\fP. If not defined then a default will
be used.
.TP
.B PWMD_OPTION_PASSWORD
Sets the password to use for opening and saving a file when
\fBPWMD_OPTION_PINENTRY\fP is \fI0\fP. The following argument is the password
and is of type \fIchar *\fP.
.TP
.B PWMD_OPTION_STATUS_FUNC
.TP
.B PWMD_OPTION_STATUS_DATA
The callback of type \fBpwmd_status_fn\fP to be called when 
.BR pwmd (1)
sends a status message. This function should return \fB0\fP on success or a
\fBgpg_error_t\fP on failure. The data passed to the function can be set with
\fBPWMD_OPTION_STATUS_DATA\fP. Status message lines are prefixed with a
keyword followed by a space then the message. Read the \fBlibassuan\fP
documentation for more information. 
.RE
.P
.TP
.BI "gpg_error_t pwmd_open(pwm_t *" pwm ", const char *" filename ");"
Opens the specified \fIfilename\fP on the server. The password for the file is
gotten from one of the methods specified with \fBpwmd_setopt\fP().
An error code is returned on error or \fB0\fP on success.
.P
.TP
.BI "int pwmd_open_nb(pwm_t *" pwm ", gpg_error_t *" error ", const char *" filename ", int " timeout ");"
This is a nonblocking way of obtaining the password from
.BR pinentry (1)
when opening a file on the server. When successful, it returns a file
descriptor that
.BR select (2)
can use. When ready,
.BR read (2)
should read a \fIpwmd_nb_status_t\fP and then call
\fBpwmd_open_nb_finalize\fP() to update the handle. If there is an error,
\fB-1\fP is returned and \fIerror\fP is set. If \fIfilename\fP is already
cached on the server or doesn't exist on the filesystem and the open
succeeded, \fB-2\fP is returned. The \fItimeout\fP argument is the number of
seconds until the pinentry process will terminate. If \fB0\fP, the default, no
timeout will be used. Note that \fBPWMD_OPTION_PINENTRY\fP must be set and
that if a timeout is specified then the child process will modify it's
\fBSIGALRM\fP handler.
.P
.TP
.BI "gpg_error_t pwmd_open_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
For use with \fBpwmd_open_nb\fP(); it updates the handle \fIpwm\fP and closes
the file descriptor. This should be called right after the successful
.BR read (2)
of \fIstatus\fP from the file descriptor returned by \fBpwmd_open_nb\fP(). If
there was a protocol or
.BR pinentry (1)
error, an error code is returned. Otherwise \fB0\fP is returned.
.P
.TP
.BI "gpg_error_t pwmd_open_async(pwm_t *" pwm ", const char *" filename ");"
This is another method of opening a file in a non-blocking way. Instead of
\fBlibpwmd\fP executing \fBpinentry\fP after a fork(),
.BR pwmd (1)
will use its \fBpinentry\fP method. When successful \fB0\fP is returned and
\fBpwmd_process()\fP should be called until the command finishes.
.P
.TP
.BI "gpg_error_t pwmd_command(pwm_t *" pwm ", char **" result ", const char *" cmd ", " ... ");"
Sends a protocol command to the server. The function returns \fB0\fP
when successful and stores the result of the command format string \fIcmd\fP
to \fIresult\fP. The result should be free'd with \fBpwmd_free_result\fP().
Protocol commands that don't have a result will set \fIresult\fP to NULL. If
an error occurs then an error code is returned. Note: the BYE protocol
command should not be sent here. Use \fBpwmd_close\fP() instead. For commands
that utilize a server INQUIRE response (i.e., "STORE"), you must use
\fBpwmd_inquire\fP() and not this function.
.P
.TP
.BI "void pwmd_free_result(void *" result ");"
Deallocates the memory of \fBpwmd_command\fP() result. It is important to use
this function because
.B libpwmd
not only keeps track of all allocated memory used by other
.B libpwmd
functions, but also clears the memory contents for better security. Don't use
this to free your own allocated memory though.
.P
.TP
.BI "gpg_error_t pwmd_inquire(pwm_t *" pwm ", const char *" cmd ", pwmd_inquire_fn " func ", void *" data ");"
Commands which use an INQUIRE to send data (i.e., STORE) should use this
function and not \fBpwmd_command\fP(). \fIcmd\fP is the command to send and is
also the \fIkeyword\fP argument to the specified callback function \fIfunc\fP.
\fIdata\fP is user data passed to the callback function. Returns 0 on success
or an error code which may have been returned from the callback function.
.RS
.P
The callback function should return \fBGPG_ERR_EOF\fP when there is no more
data to be sent or to finish sending \fIresult\fP, if not NULL, and end the
INQUIRE. Or return \fB0\fP if there is more data to be sent, or an error code
to terminate the INQUIRE.
.RE
.P
.TP
.BI "gpg_error_t pwmd_save(pwm_t *" pwm ");"
Saves the changes to the file associated with the handle \fIpwm\fP. If not
called before \fBpwmd_close\fP() then any changes will be lost. If an error
occurs then an error code is returned. Otherwise \fB0\fP is returned.
.P
.TP
.BI "int pwmd_save_nb(pwm_t *" pwm ", gpg_error_t *" error ");"
This is a nonblocking way of obtaining the password from
.BR pinentry (1)
when saving an opened file. When successful, a file descriptor is returned
that
.BR select (2)
can use. When ready
.BR read (2)
should read a \fIpwmd_nb_status_t\fP and then call
\fBpwmd_save_nb_finalize\fP() to update the handle. If there was an error,
\fB-1\fP is returned and \fIerror\fP is set. If the file is cached on the
server and the save succeeded, \fB-2\fP is returned. Note that
\fBPWMD_OPTION_PINENTRY\fP must be set.
.P
.TP
.BI "gpg_error_t pwmd_save_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
For use with \fBpwmd_save_nb\fP(); it updates the handle \fIpwm\fP and closes
the file descriptor. This should be called right after the successful
.BR read (2)
of \fIstatus\fP from the file descriptor returned by \fBpwmd_save_nb\fP(). If
there was a protocol or
.BR pinentry (1)
error, an error code is returned. Otherwise \fB0\fP is returned.
.P
.TP
.BI "gpg_error_t pwmd_save_async(pwm_t *" pwm ");"
This is another method of saving a file in a non-blocking way. Instead of
\fBlibpwmd\fP executing \fBpinentry\fP after a fork(),
.BR pwmd (1)
will use its \fBpinentry\fP method. When successful \fB0\fP is returned and
\fBpwmd_process()\fP should be called until the command finishes.
.P
.TP
.BI "pwmd_async_t pwmd_process(pwm_t *" pwm ", gpg_error_t *" error ");"
For use with the asynchronous functions \fBpwmd_open_async()\fP and
\fBpwmd_save_async\fP(). This function returns \fBASYNC_PROCESS\fP when the
command is still running and should be called again until \fBASYNC_DONE\fP is
returned. When \fBASYNC_DONE\fP is returned, \fIerror\fP should be tested and
\fBpwmd_finalize()\fP should be called.
.P
.TP
.BI "gpg_error_t pwmd_finalize(pwm_t *" pwm ");"
After \fBpwmd_process()\fP returns \fBASYNC_DONE\fP, this function should be
called even if an error occured to reset the \fIpwm\fP handle for the next
asynchronous command.
.P
.TP
.BI "gpg_error_t pwmd_terminate_pinentry(pwm_t *" pwm ");"
Terminates a
.BR pinentry (1)
process associated with the handle \fIpwm\fP. This may be useful if your
application wants to use a timeout for password entry but doesn't use
\fBpwmd_open_nb\fP(). Returns \fB0\fP on success or an error code on failure.
.P
.TP
.BI "void pwmd_close(pwm_t *" pwm ");"
Closes the server connection and free's resources used by the handle
\fIpwm\fP.
.P
.TP
.BI "const char *pwmd_strerror(gpg_error_t " error ");"
Returns a string describing the error code \fIerror\fP which was set from one
of the above functions.

.SH FILES
.TP
.B ~/.pwmd/socket
Default connecting socket.
.TP
.B ~/.pwmd/pinentry.conf
Optional file containing pinentry settings.
.TP
.B @prefix@/lib/pkgconfig/libpwmd.pc
A
.BR pkg-config (1)
metadata file.
.TP
.B @prefix@/include/libpwmd.h
Installed location of header file.
.TP
.B @pinentry@
Default location of the
.BR pinentry (1)
binary.

.SH AUTHOR
Ben Kibbey <bjk@luxsci.net>
.br
.URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .

.SH "SEE ALSO"
.BR pwmd (1),
.BR pinentry (1),
.BR pkg-config (1)

And the \fBlibassuan\fP
.BR info (1)
documentation.