doc/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_TIMEOUT
 147 Set the timeout in seconds until
 148 .BR pinentry (1)
 149 terminates while waiting for a passphrase. Only useful when
 150 .BR pwmd (1)
 151 is used for passphrase retrieval.
 152 .TP
 153 .B PWMD_OPTION_PINENTRY
 154 Whether to use
 155 .BR pinentry (1)
 156 to obtain the password when opening and saving a file on the server. The
 157 following argument is an \fIint\fP and is \fI1\fP to enable \fIlocal\fP
 158 .BR pinentry (1)
 159 use, and \fI0\fP to use the password which is set with
 160 \fBPWMD_OPTION_PASSWORD\fP or \fBPWMD_OPTION_PASSWORD_FUNC\fP or the
 161 .BR pwmd (1)
 162 pinentry. When \fI1\fP,
 163 .BR pwmd (1)
 164 won't use pinentry but return an error instead. This option should not be set
 165 when using \fBpwmd_open_async\fP() or \fBpwmd_save_async\fP().
 166 .P
 167 .RS
 168 If the file \fI~/.pwmd/pinentry.conf\fP exists then values for the above
 169 settings will be read from this file. The format of the file is one NAME=VALUE
 170 per line where NAME is one of TTYNAME, TTYTYPE, DISPLAY or PATH. The value for
 171 an existing setting will be updated to the value contained in the file. Note
 172 that the
 173 .BR pwmd (1)
 174 server can also use this file for its
 175 .BR pinentry (1)
 176 settings.
 177 .RE
 178 .TP
 179 .B PWMD_OPTION_PINENTRY_TITLE
 180 .TP
 181 .B PWMD_OPTION_PINENTRY_DESC
 182 .TP
 183 .B PWMD_OPTION_PINENTRY_PROMPT
 184 Sets the strings used in the
 185 .BR pinentry (1)
 186 program.
 187 The next argument is of type \fIchar *\fP. If not defined then a default will
 188 be used.
 189 .TP
 190 .B PWMD_OPTION_PASSWORD
 191 Sets the password to use for opening and saving a file when
 192 \fBPWMD_OPTION_PINENTRY\fP is \fI0\fP. The following argument is the password
 193 and is of type \fIchar *\fP.
 194 .TP
 195 .B PWMD_OPTION_STATUS_FUNC
 196 .TP
 197 .B PWMD_OPTION_STATUS_DATA
 198 The callback of type \fBpwmd_status_fn\fP to be called when
 199 .BR pwmd (1)
 200 sends a status message. This function should return \fB0\fP on success or a
 201 \fBgpg_error_t\fP on failure. The data passed to the function can be set with
 202 \fBPWMD_OPTION_STATUS_DATA\fP. Status message lines are prefixed with a
 203 keyword followed by a space then the message. Read the \fBlibassuan\fP
 204 documentation for more information.
 205 .RE
 206 .P
 207 .TP
 208 .BI "gpg_error_t pwmd_open(pwm_t *" pwm ", const char *" filename ");"
 209 Opens the specified \fIfilename\fP on the server. The password for the file is
 210 gotten from one of the methods specified with \fBpwmd_setopt\fP().
 211 An error code is returned on error or \fB0\fP on success.
 212 .P
 213 .TP
 214 .BI "int pwmd_open_nb(pwm_t *" pwm ", gpg_error_t *" error ", const char *" filename ", int " timeout ");"
 215 This is a nonblocking way of obtaining the password from
 216 .BR pinentry (1)
 217 when opening a file on the server. When successful, it returns a file
 218 descriptor that
 219 .BR select (2)
 220 can use. When ready,
 221 .BR read (2)
 222 should read a \fIpwmd_nb_status_t\fP and then call
 223 \fBpwmd_open_nb_finalize\fP() to update the handle. If there is an error,
 224 \fB-1\fP is returned and \fIerror\fP is set. If \fIfilename\fP is already
 225 cached on the server or doesn't exist on the filesystem and the open
 226 succeeded, \fB-2\fP is returned. The \fItimeout\fP argument is the number of
 227 seconds until the pinentry process will terminate. If \fB0\fP, the default, no
 228 timeout will be used. Note that \fBPWMD_OPTION_PINENTRY\fP must be set and
 229 that if a timeout is specified then the child process will modify it's
 230 \fBSIGALRM\fP handler.
 231 .P
 232 .TP
 233 .BI "gpg_error_t pwmd_open_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
 234 For use with \fBpwmd_open_nb\fP(); it updates the handle \fIpwm\fP and closes
 235 the file descriptor. This should be called right after the successful
 236 .BR read (2)
 237 of \fIstatus\fP from the file descriptor returned by \fBpwmd_open_nb\fP(). If
 238 there was a protocol or
 239 .BR pinentry (1)
 240 error, an error code is returned. Otherwise \fB0\fP is returned.
 241 .P
 242 .TP
 243 .BI "gpg_error_t pwmd_open_async(pwm_t *" pwm ", const char *" filename ");"
 244 This is the preferred method of opening a file in a non-blocking way. Instead
 245 of \fBlibpwmd\fP forking and executing \fBpinentry\fP,
 246 .BR pwmd (1)
 247 will use its \fBpinentry\fP method. When successful \fB0\fP is returned and
 248 \fBpwmd_process()\fP should be called until the command completes.
 249 .P
 250 .TP
 251 .BI "gpg_error_t pwmd_command(pwm_t *" pwm ", char **" result ", const char *" cmd ", " ... ");"
 252 Sends a protocol command to the server. The function returns \fB0\fP
 253 when successful and stores the result of the command format string \fIcmd\fP
 254 to \fIresult\fP. The result should be free'd with \fBpwmd_free_result\fP().
 255 Protocol commands that don't have a result will set \fIresult\fP to NULL. If
 256 an error occurs then an error code is returned. Note: the BYE protocol
 257 command should not be sent here. Use \fBpwmd_close\fP() instead. For commands
 258 that utilize a server INQUIRE response (i.e., "STORE"), you must use
 259 \fBpwmd_inquire\fP() and not this function.
 260 .P
 261 .TP
 262 .BI "gpg_error_t pwmd_command_ap(pwm_t *" pwm ", char **" result ", const char *" fmt ", va_list " ap ");"
 263 Like \fBpwmd_command\fP() but takes a formatted argument list.
 264 .P
 265 .TP
 266 .BI "void pwmd_free_result(void *" result ");"
 267 Deallocates the memory of \fBpwmd_command\fP() result. It is important to use
 268 this function because
 269 .B libpwmd
 270 not only keeps track of all allocated memory used by other
 271 .B libpwmd
 272 functions, but also clears the memory contents for better security. Don't use
 273 this to free your own allocated memory though.
 274 .P
 275 .TP
 276 .BI "gpg_error_t pwmd_inquire(pwm_t *" pwm ", const char *" cmd ", pwmd_inquire_fn " func ", void *" data ");"
 277 Commands which use an INQUIRE to send data (i.e., STORE) should use this
 278 function and not \fBpwmd_command\fP(). \fIcmd\fP is the command to send and is
 279 also the \fIkeyword\fP argument to the specified callback function \fIfunc\fP.
 280 \fIdata\fP is user data passed to the callback function. Returns 0 on success
 281 or an error code which may have been returned from the callback function.
 282 .RS
 283 .P
 284 The callback function should return \fBGPG_ERR_EOF\fP when there is no more
 285 data to be sent or to finish sending \fIresult\fP, if not NULL, and end the
 286 INQUIRE. Or return \fB0\fP if there is more data to be sent, or an error code
 287 to terminate the INQUIRE.
 288 .RE
 289 .P
 290 .TP
 291 .BI "gpg_error_t pwmd_save(pwm_t *" pwm ");"
 292 Saves the changes to the file associated with the handle \fIpwm\fP. If not
 293 called before \fBpwmd_close\fP() then any changes will be lost. If an error
 294 occurs then an error code is returned. Otherwise \fB0\fP is returned.
 295 .P
 296 .TP
 297 .BI "int pwmd_save_nb(pwm_t *" pwm ", gpg_error_t *" error ");"
 298 This is a nonblocking way of obtaining the password from
 299 .BR pinentry (1)
 300 when saving an opened file. When successful, a file descriptor is returned
 301 that
 302 .BR select (2)
 303 can use. When ready
 304 .BR read (2)
 305 should read a \fIpwmd_nb_status_t\fP and then call
 306 \fBpwmd_save_nb_finalize\fP() to update the handle. If there was an error,
 307 \fB-1\fP is returned and \fIerror\fP is set. If the file is cached on the
 308 server and the save succeeded, \fB-2\fP is returned. Note that
 309 \fBPWMD_OPTION_PINENTRY\fP must be set.
 310 .P
 311 .TP
 312 .BI "gpg_error_t pwmd_save_nb_finalize(pwm_t *" pwm ", pwmd_nb_status_t *" status ");"
 313 For use with \fBpwmd_save_nb\fP(); it updates the handle \fIpwm\fP and closes
 314 the file descriptor. This should be called right after the successful
 315 .BR read (2)
 316 of \fIstatus\fP from the file descriptor returned by \fBpwmd_save_nb\fP(). If
 317 there was a protocol or
 318 .BR pinentry (1)
 319 error, an error code is returned. Otherwise \fB0\fP is returned.
 320 .P
 321 .TP
 322 .BI "gpg_error_t pwmd_save_async(pwm_t *" pwm ");"
 323 This is the preferred method of saving a file in a non-blocking way. Instead
 324 of \fBlibpwmd\fP executing \fBpinentry\fP after a fork(),
 325 .BR pwmd (1)
 326 will use its \fBpinentry\fP method. When successful \fB0\fP is returned and
 327 \fBpwmd_process()\fP should be called until the command finishes.
 328 .P
 329 .TP
 330 .BI "pwmd_async_t pwmd_process(pwm_t *" pwm ", gpg_error_t *" error ");"
 331 For use with the asynchronous functions \fBpwmd_open_async()\fP and
 332 \fBpwmd_save_async\fP(). This function returns \fBASYNC_PROCESS\fP when the
 333 command is still running and should be called again until \fBASYNC_DONE\fP is
 334 returned. When \fBASYNC_DONE\fP is returned, \fIerror\fP should be tested and
 335 \fBpwmd_finalize()\fP should be called whether the command succeeded or not.
 336 .P
 337 .TP
 338 .BI "gpg_error_t pwmd_finalize(pwm_t *" pwm ");"
 339 After \fBpwmd_process()\fP returns \fBASYNC_DONE\fP, this function should be
 340 called even if an error occurred to reset the \fIpwm\fP handle for use with
 341 the next asynchronous command.
 342 .P
 343 .TP
 344 .BI "gpg_error_t pwmd_terminate_pinentry(pwm_t *" pwm ");"
 345 Terminates a
 346 .BR pinentry (1)
 347 process associated with the handle \fIpwm\fP. This may be useful if your
 348 application wants to use a timeout for password entry but doesn't use
 349 \fBpwmd_open_nb\fP() or \fBpwmd_open_async\fP(). Returns \fB0\fP on success or
 350 an error code on failure.
 351 .P
 352 .TP
 353 .BI "void pwmd_close(pwm_t *" pwm ");"
 354 Closes the server connection and free's resources used by the handle
 355 \fIpwm\fP.
 356 .P
 357 .TP
 358 .BI "const char *pwmd_strerror(gpg_error_t " error ");"
 359 Returns a string describing the error code \fIerror\fP which was set from one
 360 of the above functions.
 361
 362 .SH FILES
 363 .TP
 364 .B ~/.pwmd/socket
 365 Default connecting socket.
 366 .TP
 367 .B ~/.pwmd/pinentry.conf
 368 Optional file containing pinentry settings.
 369 .TP
 370 .B @prefix@/lib/pkgconfig/libpwmd.pc
 371 A
 372 .BR pkg-config (1)
 373 metadata file.
 374 .TP
 375 .B @prefix@/include/libpwmd.h
 376 Installed location of header file.
 377 .TP
 378 .B @pinentry@
 379 Default location of the
 380 .BR pinentry (1)
 381 binary.
 382
 383 .SH AUTHOR
 384 Ben Kibbey <bjk@luxsci.net>
 385 .br
 386 .URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .
 387
 388 .SH "SEE ALSO"
 389 .BR pwmd (1),
 390 .BR pinentry (1),
 391 .BR pkg-config (1)
 392
 393 And the \fBlibassuan\fP
 394 .BR info (1)
 395 documentation.