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  02110-1301  USA
  14 .de URL
  15 \\$2 \(laURL: \\$1 \(ra\\$3
  16 ..
  17 .if \n[.g] .mso www.tmac
  18 .TH LIBPWMD 3 "24 Feb 2009" "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 "gpg_error_t pwmd_init(void);"
  27 .BI "pwm_t *pwmd_connect(const char *" socket ", gpg_error_t *" error ");"
  28 .BI "gpg_error_t pwmd_assuan_ctx(pwm_t *" pwm ", assuan_context_t *" ctx ", int *" fd ");
  29 .BI "gpg_error_t pwmd_pending_line(pwm_t *" pwm ", char **" line ", size_t *" len ");
  30 .BI "gpg_error_t pwmd_setopt(pwm_t *" pwm ", pwmd_option_t " opt ", ...);"
  31 .BI "gpg_error_t pwmd_open(pwm_t *" pwm ", const char *" filename ");"
  32 .BI "int pwmd_open_nb(pwm_t *" pwm ", gpg_error_t *" error ", const char *" filename ", int " timeout ");"
  33 .BI "gpg_error_t pwmd_open_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
  34 .BI "gpg_error_t pwmd_open_async(pwm_t *" pwm ", const char *" filename ");"
  35 .BI "gpg_error_t pwmd_command(pwm_t *" pwm ", char **" result ", const char *" cmd ", " ... ");"
  36 .BI "gpg_error_t pwmd_command_ap(pwm_t *" pwm ", char **" result ", const char *" cmd ", va_list " ap ");"
  37 .BI "void pwmd_free_result(void *" result ");"
  38 .BI "gpg_error_t pwmd_inquire(pwm_t *" pwm ", const char *" cmd ", pwmd_inquire_fn " func ", void *" data ");"
  39 .BI "gpg_error_t pwmd_save(pwm_t *" pwm ");"
  40 .BI "int pwmd_save_nb(pwm_t *" pwm ", gpg_error_t *" error ");"
  41 .BI "gpg_error_t pwmd_save_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
  42 .BI "gpg_error_t pwmd_save_async(pwm_t *" pwm ");"
  43 .BI "pwmd_async_t pwmd_process(pwm_t *" pwm ", gpg_error_t *" error ");"
  44 .BI "gpg_error_t pwmd_finalize(pwm_t *" pwm ");"
  45 .BI "gpg_error_t pwmd_terminate_pinentry(pwm_t *" pwm ");"
  46 .BI "void pwmd_close(pwm_t *" pwm ");"
  47 .BI "const char *pwmd_strerror(gpg_error_t " error ");"
  48 .P
  49 .BI "typedef int (*" pwmd_status_fn ")(void *" data ", const char *" line ");"
  50 .BI "typedef char *(*" pwmd_password_fn ")(pwm_t *" pwm ", void *" data ");"
  51 .BI "typedef gpg_error_t (*" pwmd_inquire_fn ")(void *" data ", const char *" keyword ", gpg_error_t " rc ", char **" result ", size_t *" len ");"
  52 .fi
  53 .SH DESCRIPTION
  54 .B libpwmd
  55 is an library making it easy for applications to use
  56 .BR pwmd (1).
  57 .P
  58 .TP
  59 .BI "gpg_error_t pwmd_init(void);"
  60 Initializes \fBlibpwmd\fP, \fBlibassuan\fP, \fBlibgpg-error\fP and
  61 internationalization. Be sure to call this before using the other functions.
  62 If your application uses
  63 .BR gettext(3)
  64 be sure to call
  65 .BR setlocale(3)
  66 and
  67 .BR textdomain(3)
  68 before calling this function.
  69 .P
  70 .TP
  71 .BI "pwm_t *pwmd_connect(const char *" socket ", gpg_error_t *" error ");"
  72 Connects to the specified \fIsocket\fP. If \fIsocket\fP is NULL then a default
  73 of \fI~/.pwmd/socket\fP will be used. If there is an error while connecting
  74 then \fIerror\fP will be set to the error code of the failed function and NULL
  75 will be returned. When successful a handle is returned for use with the other
  76 library functions.
  77 .P
  78 .TP
  79 .BI "gpg_error_t pwmd_assuan_ctx(pwm_t *" pwm ", assuan_context_t *" ctx ", int *" fd ");
  80 Sets \fIctx\fP to the assuan context associated with the handle \fIpwm\fP and
  81 \fIfd\fP to the socket file descriptor. Returns \fB0\fP on success or an error
  82 code.
  83 .P
  84 .TP
  85 .BI "gpg_error_t pwmd_pending_line(pwm_t *" pwm ", char **" line ", size_t *" len ");
  86 This is a wrapper around \fBassuan_pending_line\fP() and
  87 \fBassuan_read_line\fP(). Returns \fB0\fP and sets \fIline\fP to the content
  88 and \fIlen\fP to the content length if there was a pending line or returns
  89 \fBGPG_ERR_NO_DATA\fP if there was none. Or any error from
  90 \fBassuan_read_line\fP().
  91 .P
  92 .TP
  93 .BI "gpg_error_t pwmd_setopt(pwm_t *" pwm ", pwmd_option_t " opt ", ...);"
  94 Set the library option \fIopt\fP to the value of the next argument. Returns 0
  95 on success or an error code. \fIopt\fP is one of the following:
  96 .RS
  97 .TP
  98 .B PWMD_OPTION_PASSWORD_FUNC
  99 Specifies a function to use to get a password. The next argument should be of
 100 type \fIpwmd_password_fn\fP. The function should return a \fIchar
 101 *\fP string which is the password or NULL if there was an error.
 102 .TP
 103 .B PWMD_OPTION_PASSWORD_DATA
 104 A user data pointer passed to the password function.
 105 .TP
 106 .B PWMD_OPTION_PINENTRY_TRIES
 107 The next argument if type \fIint\fP specifies the number of invalid password
 108 tries before
 109 .BR pinentry (1)
 110 gives up. Only \fBpwmd_open\fP(), \fBpwmd_open_async\fP() and
 111 \fBpwmd_open_nb\fP() will use this option. \fBpwmd_save\fP(),
 112 \fBpwmd_save_async\fP() and \fBpwmd_save_nb\fP() will continue to confirm a
 113 password until either a match is entered or Cancel is selected.
 114 .TP
 115 .B PWMD_OPTION_PINENTRY_TTY
 116 Sets the tty that pinentry will use to prompt for the passphrase. Note that
 117 \fBPWMD_OPTION_PINENTRY_DISPLAY\fP has precedence if the \fBDISPLAY\fP
 118 environment variable is set. The next argument should be of type \fIchar *\fP.
 119 .TP
 120 .B PWMD_OPTION_PINENTRY_TERM
 121 The terminal type when \fBPWMD_OPTION_PINENTRY_TTY\fP is set. Be sure to set
 122 this because ncurses will segfault if not. The next argument should be of type
 123 \fIchar *\fP.
 124 .TP
 125 .B PWMD_OPTION_PINENTRY_DISPLAY
 126 An X11 hostname and display for pinentry to connect to. This will be the same
 127 as the \fBDISPLAY\fP environment variable by default. The next argument should
 128 be of type \fIchar *\fP.
 129 .TP
 130 .B PWMD_OPTION_PINENTRY_PATH
 131 The full path to the pinentry binary. Only useful when \fBpwmd_open_nb\fP() or
 132 \fBpwmd_save_nb\fP() are used. The next argument should be of type
 133 \fIchar *\fP. The default is \fI@pinentry@\fP.
 134 .TP
 135 .B PWMD_OPTION_PINENTRY_LC_CTYPE
 136 The value of this option is passed to the
 137 .BR pinentry (1)
 138 command line. The next argument should be of type \fIchar *\fP.
 139
 140 .TP
 141 .B PWMD_OPTION_PINENTRY_LC_MESSAGES
 142 The value of this option is passed to the
 143 .BR pinentry (1)
 144 command line. The next argument should be of type \fIchar *\fP.
 145 .TP
 146 .B PWMD_OPTION_PINENTRY
 147 Whether to use
 148 .BR pinentry (1)
 149 to obtain the password when opening and saving a file on the server. The
 150 following argument is an \fIint\fP and is \fI1\fP to enable
 151 .BR pinentry (1)
 152 use, and \fI0\fP to use the password which is set with
 153 \fBPWMD_OPTION_PASSWORD\fP or \fBPWMD_OPTION_PASSWORD_FUNC\fP. When \fI1\fP,
 154 .BR pwmd (1)
 155 won't use pinentry but return an error instead. This option should not be set
 156 when using \fBpwmd_open_async\fP() or \fBpwmd_save_async\fP().
 157 .P
 158 .RS
 159 If the file \fI~/.pwmd/pinentry.conf\fP exists then values for the above
 160 settings will be read from this file. The format of the file is one NAME=VALUE
 161 per line where NAME is one of TTYNAME, TTYTYPE, DISPLAY or PATH. The value for
 162 an existing setting will be updated to the value contained in the file. Note
 163 that the
 164 .BR pwmd (1)
 165 server can also use this file for its
 166 .BR pinentry (1)
 167 settings.
 168 .RE
 169 .TP
 170 .B PWMD_OPTION_PINENTRY_TITLE
 171 .TP
 172 .B PWMD_OPTION_PINENTRY_DESC
 173 .TP
 174 .B PWMD_OPTION_PINENTRY_PROMPT
 175 Sets the strings used in the
 176 .BR pinentry (1)
 177 program.
 178 The next argument is of type \fIchar *\fP. If not defined then a default will
 179 be used.
 180 .TP
 181 .B PWMD_OPTION_PASSWORD
 182 Sets the password to use for opening and saving a file when
 183 \fBPWMD_OPTION_PINENTRY\fP is \fI0\fP. The following argument is the password
 184 and is of type \fIchar *\fP.
 185 .TP
 186 .B PWMD_OPTION_STATUS_FUNC
 187 .TP
 188 .B PWMD_OPTION_STATUS_DATA
 189 The callback of type \fBpwmd_status_fn\fP to be called when
 190 .BR pwmd (1)
 191 sends a status message. This function should return \fB0\fP on success or a
 192 \fBgpg_error_t\fP on failure. The data passed to the function can be set with
 193 \fBPWMD_OPTION_STATUS_DATA\fP. Status message lines are prefixed with a
 194 keyword followed by a space then the message. Read the \fBlibassuan\fP
 195 documentation for more information.
 196 .RE
 197 .P
 198 .TP
 199 .BI "gpg_error_t pwmd_open(pwm_t *" pwm ", const char *" filename ");"
 200 Opens the specified \fIfilename\fP on the server. The password for the file is
 201 gotten from one of the methods specified with \fBpwmd_setopt\fP().
 202 An error code is returned on error or \fB0\fP on success.
 203 .P
 204 .TP
 205 .BI "int pwmd_open_nb(pwm_t *" pwm ", gpg_error_t *" error ", const char *" filename ", int " timeout ");"
 206 This is a nonblocking way of obtaining the password from
 207 .BR pinentry (1)
 208 when opening a file on the server. When successful, it returns a file
 209 descriptor that
 210 .BR select (2)
 211 can use. When ready,
 212 .BR read (2)
 213 should read a \fIpwmd_nb_status_t\fP and then call
 214 \fBpwmd_open_nb_finalize\fP() to update the handle. If there is an error,
 215 \fB-1\fP is returned and \fIerror\fP is set. If \fIfilename\fP is already
 216 cached on the server or doesn't exist on the filesystem and the open
 217 succeeded, \fB-2\fP is returned. The \fItimeout\fP argument is the number of
 218 seconds until the pinentry process will terminate. If \fB0\fP, the default, no
 219 timeout will be used. Note that \fBPWMD_OPTION_PINENTRY\fP must be set and
 220 that if a timeout is specified then the child process will modify it's
 221 \fBSIGALRM\fP handler.
 222 .P
 223 .TP
 224 .BI "gpg_error_t pwmd_open_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
 225 For use with \fBpwmd_open_nb\fP(); it updates the handle \fIpwm\fP and closes
 226 the file descriptor. This should be called right after the successful
 227 .BR read (2)
 228 of \fIstatus\fP from the file descriptor returned by \fBpwmd_open_nb\fP(). If
 229 there was a protocol or
 230 .BR pinentry (1)
 231 error, an error code is returned. Otherwise \fB0\fP is returned.
 232 .P
 233 .TP
 234 .BI "gpg_error_t pwmd_open_async(pwm_t *" pwm ", const char *" filename ");"
 235 This is the preferred method of opening a file in a non-blocking way. Instead
 236 of \fBlibpwmd\fP forking and executing \fBpinentry\fP,
 237 .BR pwmd (1)
 238 will use its \fBpinentry\fP method. When successful \fB0\fP is returned and
 239 \fBpwmd_process()\fP should be called until the command completes.
 240 .P
 241 .TP
 242 .BI "gpg_error_t pwmd_command(pwm_t *" pwm ", char **" result ", const char *" cmd ", " ... ");"
 243 Sends a protocol command to the server. The function returns \fB0\fP
 244 when successful and stores the result of the command format string \fIcmd\fP
 245 to \fIresult\fP. The result should be free'd with \fBpwmd_free_result\fP().
 246 Protocol commands that don't have a result will set \fIresult\fP to NULL. If
 247 an error occurs then an error code is returned. Note: the BYE protocol
 248 command should not be sent here. Use \fBpwmd_close\fP() instead. For commands
 249 that utilize a server INQUIRE response (i.e., "STORE"), you must use
 250 \fBpwmd_inquire\fP() and not this function.
 251 .P
 252 .TP
 253 .BI "gpg_error_t pwmd_command_ap(pwm_t *" pwm ", char **" result ", const char *" fmt ", va_list " ap ");"
 254 Like \fBpwmd_command\fP() but takes a formatted argument list.
 255 .P
 256 .TP
 257 .BI "void pwmd_free_result(void *" result ");"
 258 Deallocates the memory of \fBpwmd_command\fP() result. It is important to use
 259 this function because
 260 .B libpwmd
 261 not only keeps track of all allocated memory used by other
 262 .B libpwmd
 263 functions, but also clears the memory contents for better security. Don't use
 264 this to free your own allocated memory though.
 265 .P
 266 .TP
 267 .BI "gpg_error_t pwmd_inquire(pwm_t *" pwm ", const char *" cmd ", pwmd_inquire_fn " func ", void *" data ");"
 268 Commands which use an INQUIRE to send data (i.e., STORE) should use this
 269 function and not \fBpwmd_command\fP(). \fIcmd\fP is the command to send and is
 270 also the \fIkeyword\fP argument to the specified callback function \fIfunc\fP.
 271 \fIdata\fP is user data passed to the callback function. Returns 0 on success
 272 or an error code which may have been returned from the callback function.
 273 .RS
 274 .P
 275 The callback function should return \fBGPG_ERR_EOF\fP when there is no more
 276 data to be sent or to finish sending \fIresult\fP, if not NULL, and end the
 277 INQUIRE. Or return \fB0\fP if there is more data to be sent, or an error code
 278 to terminate the INQUIRE.
 279 .RE
 280 .P
 281 .TP
 282 .BI "gpg_error_t pwmd_save(pwm_t *" pwm ");"
 283 Saves the changes to the file associated with the handle \fIpwm\fP. If not
 284 called before \fBpwmd_close\fP() then any changes will be lost. If an error
 285 occurs then an error code is returned. Otherwise \fB0\fP is returned.
 286 .P
 287 .TP
 288 .BI "int pwmd_save_nb(pwm_t *" pwm ", gpg_error_t *" error ");"
 289 This is a nonblocking way of obtaining the password from
 290 .BR pinentry (1)
 291 when saving an opened file. When successful, a file descriptor is returned
 292 that
 293 .BR select (2)
 294 can use. When ready
 295 .BR read (2)
 296 should read a \fIpwmd_nb_status_t\fP and then call
 297 \fBpwmd_save_nb_finalize\fP() to update the handle. If there was an error,
 298 \fB-1\fP is returned and \fIerror\fP is set. If the file is cached on the
 299 server and the save succeeded, \fB-2\fP is returned. Note that
 300 \fBPWMD_OPTION_PINENTRY\fP must be set.
 301 .P
 302 .TP
 303 .BI "gpg_error_t pwmd_save_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
 304 For use with \fBpwmd_save_nb\fP(); it updates the handle \fIpwm\fP and closes
 305 the file descriptor. This should be called right after the successful
 306 .BR read (2)
 307 of \fIstatus\fP from the file descriptor returned by \fBpwmd_save_nb\fP(). If
 308 there was a protocol or
 309 .BR pinentry (1)
 310 error, an error code is returned. Otherwise \fB0\fP is returned.
 311 .P
 312 .TP
 313 .BI "gpg_error_t pwmd_save_async(pwm_t *" pwm ");"
 314 This is the preferred method of saving a file in a non-blocking way. Instead
 315 of \fBlibpwmd\fP executing \fBpinentry\fP after a fork(),
 316 .BR pwmd (1)
 317 will use its \fBpinentry\fP method. When successful \fB0\fP is returned and
 318 \fBpwmd_process()\fP should be called until the command finishes.
 319 .P
 320 .TP
 321 .BI "pwmd_async_t pwmd_process(pwm_t *" pwm ", gpg_error_t *" error ");"
 322 For use with the asynchronous functions \fBpwmd_open_async()\fP and
 323 \fBpwmd_save_async\fP(). This function returns \fBASYNC_PROCESS\fP when the
 324 command is still running and should be called again until \fBASYNC_DONE\fP is
 325 returned. When \fBASYNC_DONE\fP is returned, \fIerror\fP should be tested and
 326 \fBpwmd_finalize()\fP should be called whether the command succeeded or not.
 327 .P
 328 .TP
 329 .BI "gpg_error_t pwmd_finalize(pwm_t *" pwm ");"
 330 After \fBpwmd_process()\fP returns \fBASYNC_DONE\fP, this function should be
 331 called even if an error occurred to reset the \fIpwm\fP handle for use with
 332 the next asynchronous command.
 333 .P
 334 .TP
 335 .BI "gpg_error_t pwmd_terminate_pinentry(pwm_t *" pwm ");"
 336 Terminates a
 337 .BR pinentry (1)
 338 process associated with the handle \fIpwm\fP. This may be useful if your
 339 application wants to use a timeout for password entry but doesn't use
 340 \fBpwmd_open_nb\fP() or \fBpwmd_open_async\fP(). Returns \fB0\fP on success or
 341 an error code on failure.
 342 .P
 343 .TP
 344 .BI "void pwmd_close(pwm_t *" pwm ");"
 345 Closes the server connection and free's resources used by the handle
 346 \fIpwm\fP.
 347 .P
 348 .TP
 349 .BI "const char *pwmd_strerror(gpg_error_t " error ");"
 350 Returns a string describing the error code \fIerror\fP which was set from one
 351 of the above functions.
 352
 353 .SH FILES
 354 .TP
 355 .B ~/.pwmd/socket
 356 Default connecting socket.
 357 .TP
 358 .B ~/.pwmd/pinentry.conf
 359 Optional file containing pinentry settings.
 360 .TP
 361 .B @prefix@/lib/pkgconfig/libpwmd.pc
 362 A
 363 .BR pkg-config (1)
 364 metadata file.
 365 .TP
 366 .B @prefix@/include/libpwmd.h
 367 Installed location of header file.
 368 .TP
 369 .B @pinentry@
 370 Default location of the
 371 .BR pinentry (1)
 372 binary.
 373
 374 .SH AUTHOR
 375 Ben Kibbey <bjk@luxsci.net>
 376 .br
 377 .URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .
 378
 379 .SH "SEE ALSO"
 380 .BR pwmd (1),
 381 .BR pinentry (1),
 382 .BR pkg-config (1)
 383
 384 And the \fBlibassuan\fP
 385 .BR info (1)
 386 documentation.