libpwmd.3.in

   1 .\" This program is free software; you can redistribute it and/or modify
   2 .\" it under the terms of the GNU General Public License as published by
   3 .\" the Free Software Foundation; either version 2 of the License, or
   4 .\" (at your option) any later version.
   5 .\"
   6 .\" This program is distributed in the hope that it will be useful,
   7 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
   8 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   9 .\" GNU General Public License for more details.
  10 .\"
  11 .\" You should have received a copy of the GNU General Public License
  12 .\" along with this program; if not, write to the Free Software
  13 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  14 .de URL
  15 \\$2 \(laURL: \\$1 \(ra\\$3
  16 ..
  17 .if \n[.g] .mso www.tmac
  18 .TH LIBPWMD 3 "24 Jun 2007" "Password Manager Daemon Library" "Password Manager Daemon Library"
  19 .SH NAME
  20
  21 libpwmd \- pwmd client interface library
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <libpwmd.h>
  25 .sp
  26 .BI "int pwmd_init(void);"
  27 .BI "pwm_t *pwmd_connect(const char " *socket ", gpg_error_t " *error ");"
  28 .BI "int pwmd_get_password(pwm_t " *pwm ", gpg_error_t " *error ", const char " *filename ");"
  29 .BI "int pwmd_setopt(pwm_t " *pwm ", gpg_error_t " *error ", pwmd_option " opt ", ...);"
  30 .BI "int pwmd_open(pwm_t " *pwm ", gpg_error_t " *error ", const char " *filename ");"
  31 .BI "int pwmd_command(pwm_t " *pwm ", char " **result ", gpg_error_t " *error ", const char " *cmd ", " ... ");"
  32 .BI "void pwmd_free_result(void " *result ");"
  33 .BI "int pwmd_save(pwm_t " *pwm ", gpg_error_t " *error ");"
  34 .BI "void pwmd_close(pwm_t " *pwm ");"
  35 .BI "const char *pwmd_strerror(gpg_error_t " error ");"
  36 .P
  37 .BI "typedef char *(" pwmd_password_func ")(void *" data ");"
  38 .P
  39 .BI "typedef struct {"
  40 .BI "    char " password[ASSUAN_LINELENGTH] ";"
  41 .BI "    gpg_error_t " error ";"
  42 .BI "} " pwmd_password_s ";"
  43 .fi
  44 .SH DESCRIPTION
  45 .B libpwmd
  46 is an library making it easy for applications to use
  47 .BR pwmd (1).
  48 .P
  49 .TP
  50 .B "int pwmd_init(void);"
  51 Initializes libassuan and libgpg-error stuff.
  52 .P
  53 .TP
  54 .B "pwm_t *pwmd_connect(const char " *socket ", gpg_error_t " *error ");"
  55 \fBpwmd_connect\fP() connects to the specified \fIsocket\fP. If \fIsocket\fP
  56 is NULL then a default of \fI~/.pwmd/socket\fP will be used. If there is an
  57 error while connecting \fIerror\fP is set to the error code of the failed
  58 function and NULL is returned. When successful a handle is returned for use in
  59 the other library functions.
  60 .P
  61 .TP
  62 .B "int pwmd_get_password(pwm_t " *pwm ", gpg_error_t " *error ", const char " *filename ");"
  63 This is a non-blocking
  64 .BR pinentry (1)
  65 password retrieval function. When successful it returns a file descriptor that
  66 .BR select (2)
  67 can use to determine when a password can be read with
  68 .BR read (2)
  69 to open the file \fIfilename\fP.
  70 .BR read (2)
  71 should read a \fIpwmd_password_s\fP and check \fI.error\fP for an
  72 error code returned by
  73 .BR pinentry (1).
  74 If there is an error during
  75 .BR pipe (2)
  76 or
  77 .BR fork (2),
  78 the function returns -1 and \fIerror\fP is set to the error code of the failed
  79 function. If the file is cached on the server or the file is nonexistant, a
  80 password is not needed and -2 is returned. After the password has been gotten,
  81 call \fBpwmd_setopt\fP() to set the password and make sure
  82 .B PWMD_OPTION_PINENTRY
  83 is unset. Security note: it's up to the caller to clear the password; usually
  84 with
  85 .BR memset (3).
  86 .P
  87 .TP
  88 .B "int pwmd_setopt(pwm_t " *pwm ", gpg_error_t " *error ", pwmd_option " opt ", ...);"
  89 \fBpwmd_setopt\fP() set the library option \fIopt\fP to the value of the next
  90 argument where \fIopt\fP is one of the following:
  91 .RS
  92 .TP
  93 .B PWMD_OPTION_PASSWORD_FUNC
  94 Specifies a function to use to get a password. The next argument should be of
  95 type \fBpwmd_password_func\fP. The function should return a \fIchar
  96 *\fP string which is the password or NULL if there is an
  97 error.
  98 .TP
  99 .B PWMD_OPTION_PASSWORD_DATA
 100 A user data pointer passed to the password function.
 101 .TP
 102 .B PWMD_OPTION_PINENTRY
 103 Whether to use
 104 .BR pinentry (1)
 105 to obtain the password when opening and saving a file on the server. The
 106 following argument is an \fIint\fP and is \fI1\fP to enable
 107 .BR pinentry (1)
 108 use, and \fI0\fP to use the password which is set with
 109 \fBPWMD_OPTION_PASSWORD\fP.
 110 .TP
 111 .B PWMD_OPTION_PINENTRY_TTY
 112 .TP
 113 .B PWMD_OPTION_PINENTRY_TERM
 114 .TP
 115 .B PWMD_OPTION_PINENTRY_DISPLAY
 116 Sets the
 117 .BR pinentry (1)
 118 command line options. The next argument should be of type \fIchar *\fP. If not
 119 set, then the current DISPLAY, if set, or tty will be used.
 120 .TP
 121 .B PWMD_OPTION_TITLE
 122 .TP
 123 .B PWMD_OPTION_DESC
 124 .TP
 125 .B PWMD_OPTION_PROMPT
 126 Sets the strings used in the
 127 .BR pinentry (1)
 128 program.
 129 The next argument is of type \fIchar *\fP. If not defined then a default will
 130 be used.
 131 .TP
 132 .B PWMD_OPTION_PASSWORD
 133 Sets the password to use for opening and saving a file when
 134 \fBPWMD_OPTION_PINENTRY\fP is \fI0\fP. The following argument is the password
 135 and is of type \fIchar *\fP.
 136 .RE
 137 .RE
 138 .P
 139 .TP
 140 .B "int pwmd_open(pwm_t " *pwm ", gpg_error_t " *error ", const char " *filename ");"
 141 \fBpwmd_open\fP() opens the specified \fIfilename\fP on the server. The
 142 password for the file is gotten from either
 143 .BR pinentry (1)
 144 or the value set with \fBpwmd_setopt\fP(). \fBPWMD_ERROR\fP is returned on
 145 error with \fIerror\fP set to the error code of the failed function.
 146 Otherwise \fBPWMD_OK\fP is returned.
 147 .P
 148 .TP
 149 .B "int pwmd_command(pwm_t " *pwm ", char " **result ", gpg_error_t " *error ", const char " *cmd ", " ... ");"
 150 \fBpwmd_command\fP() sends a protocol command to the server. The function
 151 returns \fBPWMD_OK\fP when successful and stores the result of the command
 152 \fIcmd\fP to \fIresult\fP. The result should be free'd with
 153 \fBpwmd_free_result\fP(). Protocol commands that don't have a result will set
 154 \fIresult\fP to NULL. If an error occurs then \fBPWMD_ERROR\fP is returned and
 155 \fIerror\fP is set to the error code.
 156 .P
 157 .TP
 158 .B "void pwmd_free_result(void " *result ");"
 159 Deallocates the memory of \fBpwmd_command\fP() result. It is important to use
 160 this function because
 161 .B libpwmd
 162 not only keeps track of all allocated memory used by other
 163 .B libpwmd
 164 functions, but also clears the memory contents for better security. Don't use
 165 this to free your own allocated memory.
 166 .P
 167 .TP
 168 .B "int pwmd_save(pwm_t " *pwm ", gpg_error_t " *error ");"
 169 \fBpwmd_save\fP() saves the changes to the opened file. If not called before
 170 disconnecting from the server then any changes will be lost. If an error
 171 occurs then \fBPWMD_ERROR\fP is returned and \fIerror\fP is set to the error
 172 code of the failed function. Otherwise \fBPWMD_OK\fP is returned.
 173 .P
 174 .TP
 175 .B "void pwmd_close(pwm_t " *pwm ");"
 176 \fBpwmd_close\fP() closes the connection to the server and frees resources
 177 used by the handle \fIpwm\fP.
 178 .P
 179 .TP
 180 .B "const char *pwmd_strerror(gpg_error_t " error ");"
 181 \fBpwmd_strerror\fP() returns a string describing the error code
 182 \fIerror\fP which was set from one of the above functions.
 183
 184 .SH FILES
 185 .TP
 186 .B ~/.pwmd/socket
 187 Default connecting socket.
 188 .TP
 189 .B @prefix@/lib/pkgconfig/libpwmd.pc
 190 A
 191 .BR pkg-config (1)
 192 metadata file.
 193 .TP
 194 .B @prefix@/include/libpwmd.h
 195 Installed location of header file.
 196
 197 .SH AUTHOR
 198 Ben Kibbey <bjk@luxsci.net>
 199 .br
 200 .URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .
 201
 202 .SH "SEE ALSO"
 203 .BR pwmd (1),
 204 .BR pinentry (1),
 205 .BR pkg-config (1)