| blob | 4111fb96dbd95039beead3bc85d96940147574ad |
1 .TH "libpwmd.h" 3 "23 Jun 2009" "Version 6.0.2" "libpwmd" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 libpwmd.h - an API for accessing pwmd
6 .SH "Description"
7 .PP
8 libpwmd is a library making it easy for applications to use the pwmd server. Pwmd version 2.0 or later is required; either locally or remotely.
9 .SH "SSH Details"
10 .PP
11 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. Authentication is done by using SSH public key (see \fBssh-keygen(1)\fP) authentication and verifying the host key against a local OpenSSH known hosts formatted file.
12 .PP
13 The servers public key can be had by using \fBpwmd_get_hostkey()\fP and storing the result in a file or done automatially by using a callback function \fBpwmd_knownhost_cb_t\fP while connecting to the unknown host.
14 .PP
15 On the server side you'll need a proxy server to connect to the real pwmd server. Here's an example \fBauthorized_keys(5)\fP entry that will do this. The hash portion should be the same as the contents of the generated \fBssh-keygen(1)\fP \fIidentity.pub\fP file which is passed as a parameter to the SSH connection functions:
16 .PP
17 .PP
18 .nf
19 command='socat UNIX-CONNECT:$HOME/.pwmd/socket -' <hash> ...
20 .fi
21 .PP
22 .PP
23 \fBNote:\fP
24 .RS 4
25 Only an SSH identity without a passphrase is supported. For now anyway. This is a limitation of libssh2 (version 1.1 as of this writing).
26 .RE
27 .PP
28 \fBVersion:\fP
29 .RS 4
30 6.0.3 The first version to use the OpenSSH known hosts file format exclusively. Earlier versions used only an SHA1 hash of the host key.
31 .RE
32 .PP
33 \fBTodo\fP
34 .RS 4
35 X11 port forwarding so a remote pinentry can use the local display.
36 .RE
37 .PP
38 .SH "Pinentry Details"
39 .PP
40 \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 (X11 forwarding is not yet supported) or have the pwmd server use it's pinentry to retrieve a passphrase when needed. How this is done depends what function gets called and whether the pwmd connection is over an SSH channel.
41 .PP
42 There are a few options that tell pinentry how and where to prompt for a needed passphrase. See the \fBpwmd_option_t\fP section for details. These options are not sent (when using pwmd's pinentry, not the local one) until the pinentry is needed.
43 .PP
44 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 'SET ENABLE_PINENTRY=0' to the pwmd server. This is needed so pwmd wont try to launch it's own pinentry on passphrase or confirmation failure. So you may need to reset this option manually depending on your needs; especially when changing pinentry methods when doing a save (the passphrase may be set as empty since the remote pinentry is disabled!).
45 .PP
46 Some pinentry options can also be specified in a local configuration file \fI'~/.pwmd/pinentry.conf'\fP. These options are initial values for each pinentry invokation (not retries) 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:
47 .PP
48 \fBParameters:\fP
49 .RS 4
50 \fIPATH\fP The full path to the location of the pinentry binary.
51 .br
52 \fIDISPLAY\fP The X11 display to use.
53 .br
54 \fITTYNAME\fP The full path to the tty that pinentry should prompt on.
55 .br
56 \fITTYTYPE\fP The terminal type of the tty which is required if DISPLAY is not set.
57 .RE
58 .PP
59 \fBNote:\fP
60 .RS 4
61 When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user.
62 .PP
63 The initial values for the pinentry TTY, TERM and DISPLAY are set during \fBpwmd_new()\fP depending on the current environment. They may need to be reset as needed.
64 .PP
65 After establishing an SSH connection, the pwmd pinentry is disabled by sending the command 'SET ENABLE_PINENTRY=0'. This is needed because there currently isn't a way to have the remote pinentry use the local display. You must be careful to use either a local pinentry or set a passphrase manually with \fBpwmd_setopt()\fP when a passphrase is required or needed.
66 .RE
67 .PP
68 \fBTodo\fP
69 .RS 4
70 X11 port forwarding so a remote pinentry can use the local display.
71 .RE
72 .PP
73 \fBSee also:\fP
74 .RS 4
75 \fBSSH Details\fP
76 .RE
77 .PP
78 .SH "Errors"
79 .PP
80 libpwmd uses libgpg-error for all error codes. Some are user defined GPG_ERR_USER_N codes, but most are reused from the existing ones. Error codes can be described by using \fBpwmd_strerror()\fP, or the thread-safe \fBpwmd_strerror_r()\fP.
81 .PP
82 \fBNote:\fP
83 .RS 4
84 Internally, some error codes are a bitmask of an error source. In order to simplify the result codes, libpwmd strips any error source from the error code before returning it.
85 .RE
86 .PP
87 .SH "Example Client"
88 .PP
89 The following example will list the element tree of the data file specified in the first command line argument.
90 .PP
91 .PP
92 .nf
93 #include <stdio.h>
94 #include <stdlib.h>
95 #include <libpwmd.h>
97 int main(int argc, char **argv)
98 {
99 pwm_t *pwm = pwmd_new(NULL);
100 gpg_error_t rc = pwmd_connect(pwm, NULL);
101 char *result;
103 if (!rc) {
104 rc = pwmd_open(pwm, argv[1]);
106 if (!rc) {
107 rc = pwmd_command(pwm, &result, '%s', 'LIST');
109 if (!rc) {
110 printf('%s', result);
111 pwmd_free(result);
112 }
113 }
114 }
116 pwmd_close(pwm);
118 if (rc)
119 fprintf(stderr, 'ERR: %s\n', pwmd_strerror(rc));
121 exit(rc ? 1 : 0);
122 }
123 .fi
124 .PP
126 .SH SYNOPSIS
127 .br
128 .PP
129 .SS "Data Structures"
131 .in +1c
132 .ti -1c
133 .RI "struct \fBpwmd_fd_t\fP"
134 .br
135 .in -1c
136 .SS "Constants"
138 .in +1c
139 .ti -1c
140 .RI "#define \fBLIBPWMD_VERSION\fP 0x602"
141 .br
142 .ti -1c
143 .RI "#define \fBPWMD_FD_READABLE\fP"
144 .br
145 .ti -1c
146 .RI "#define \fBPWMD_FD_WRITABLE\fP"
147 .br
148 .ti -1c
149 .RI "#define \fBEPWMD_NO_FILE\fP"
150 .br
151 .ti -1c
152 .RI "#define \fBEPWMD_LIBXML_ERROR\fP"
153 .br
154 .ti -1c
155 .RI "#define \fBEPWMD_FILE_MODIFIED\fP"
156 .br
157 .ti -1c
158 .RI "#define \fBEPWMD_MAX\fP"
159 .br
160 .in -1c
161 .SS "Typedefs"
163 .in +1c
164 .ti -1c
165 .RI "typedef struct pwm_s \fBpwm_t\fP"
166 .br
167 .ti -1c
168 .RI "typedef gpg_error_t(* \fBpwmd_passphrase_cb_t\fP )(void *user, char **passphrase)"
169 .br
170 .ti -1c
171 .RI "typedef int(* \fBpwmd_status_cb_t\fP )(void *user, const char *line)"
172 .br
173 .ti -1c
174 .RI "typedef gpg_error_t(* \fBpwmd_inquire_cb_t\fP )(void *user, const char *cmd, gpg_error_t rc, char **data, size_t *len)"
175 .br
176 .ti -1c
177 .RI "typedef gpg_error_t(* \fBpwmd_knownhost_cb_t\fP )(void *user, const char *host, const char *key, size_t len)"
178 .br
179 .in -1c
180 .SS "Enumerations"
182 .in +1c
183 .ti -1c
184 .RI "enum \fBpwmd_async_t\fP { \fBASYNC_INIT\fP, \fBASYNC_PROCESS\fP, \fBASYNC_DONE\fP }"
185 .br
186 .ti -1c
187 .RI "enum \fBpwmd_ip_version_t\fP { \fBPWMD_IP_ANY\fP, \fBPWMD_IPV4\fP, \fBPWMD_IPV6\fP }"
188 .br
189 .ti -1c
190 .RI "enum \fBpwmd_socket_t\fP { \fBPWMD_SOCKET_LOCAL\fP, \fBPWMD_SOCKET_SSH\fP }"
191 .br
192 .ti -1c
193 .RI "enum \fBpwmd_pinentry_t\fP { \fBPWMD_PINENTRY_OPEN\fP, \fBPWMD_PINENTRY_OPEN_FAILED\fP, \fBPWMD_PINENTRY_SAVE\fP, \fBPWMD_PINENTRY_SAVE_CONFIRM\fP, \fBPWMD_PINENTRY_CONFIRM\fP, \fBPWMD_PINENTRY_DEFAULT\fP, \fBPWMD_PINENTRY_CLOSE\fP }"
194 .br
195 .ti -1c
196 .RI "enum \fBpwmd_option_t\fP { \fBPWMD_OPTION_PASSPHRASE_CB\fP, \fBPWMD_OPTION_PASSPHRASE_DATA\fP, \fBPWMD_OPTION_PASSPHRASE\fP, \fBPWMD_OPTION_KNOWNHOST_CB\fP, \fBPWMD_OPTION_KNOWNHOST_DATA\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, \fBPWMD_OPTION_INQUIRE_TOTAL\fP }"
197 .br
198 .in -1c
199 .SS "Functions"
201 .in +1c
202 .ti -1c
203 .RI "gpg_error_t \fBpwmd_init\fP (void)"
204 .br
205 .ti -1c
206 .RI "\fBpwm_t\fP * \fBpwmd_new\fP (const char *name)"
207 .br
208 .ti -1c
209 .RI "gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *path)"
210 .br
211 .ti -1c
212 .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)"
213 .br
214 .ti -1c
215 .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)"
216 .br
217 .ti -1c
218 .RI "gpg_error_t \fBpwmd_connect_url\fP (\fBpwm_t\fP *pwm, const char *url)"
219 .br
220 .ti -1c
221 .RI "gpg_error_t \fBpwmd_connect_url_async\fP (\fBpwm_t\fP *pwm, const char *url)"
222 .br
223 .ti -1c
224 .RI "gpg_error_t \fBpwmd_get_hostkey\fP (\fBpwm_t\fP *pwm, const char *host, int port, char **result)"
225 .br
226 .ti -1c
227 .RI "gpg_error_t \fBpwmd_get_hostkey_async\fP (\fBpwm_t\fP *pwm, const char *host, int port)"
228 .br
229 .ti -1c
230 .RI "gpg_error_t \fBpwmd_get_fds\fP (\fBpwm_t\fP *pwm, \fBpwmd_fd_t\fP *fds, int *n_fds)"
231 .br
232 .ti -1c
233 .RI "gpg_error_t \fBpwmd_pending_line\fP (\fBpwm_t\fP *pwm)"
234 .br
235 .ti -1c
236 .RI "gpg_error_t \fBpwmd_setopt\fP (\fBpwm_t\fP *pwm, \fBpwmd_option_t\fP opt,...)"
237 .br
238 .ti -1c
239 .RI "gpg_error_t \fBpwmd_getpin\fP (\fBpwm_t\fP *pwm, const char *filename, char **result, \fBpwmd_pinentry_t\fP which)"
240 .br
241 .ti -1c
242 .RI "gpg_error_t \fBpwmd_open\fP (\fBpwm_t\fP *pwm, const char *filename)"
243 .br
244 .ti -1c
245 .RI "gpg_error_t \fBpwmd_open2\fP (\fBpwm_t\fP *pwm, const char *filename)"
246 .br
247 .ti -1c
248 .RI "gpg_error_t \fBpwmd_open_async2\fP (\fBpwm_t\fP *pwm, const char *filename)"
249 .br
250 .ti -1c
251 .RI "gpg_error_t \fBpwmd_open_async\fP (\fBpwm_t\fP *pwm, const char *filename)"
252 .br
253 .ti -1c
254 .RI "\fBpwmd_async_t\fP \fBpwmd_process\fP (\fBpwm_t\fP *pwm, gpg_error_t *rc, char **result)"
255 .br
256 .ti -1c
257 .RI "gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm)"
258 .br
259 .ti -1c
260 .RI "gpg_error_t \fBpwmd_save2\fP (\fBpwm_t\fP *pwm)"
261 .br
262 .ti -1c
263 .RI "gpg_error_t \fBpwmd_save_async2\fP (\fBpwm_t\fP *pwm)"
264 .br
265 .ti -1c
266 .RI "gpg_error_t \fBpwmd_save_async\fP (\fBpwm_t\fP *pwm)"
267 .br
268 .ti -1c
269 .RI "gpg_error_t \fBpwmd_command\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd,...)"
270 .br
271 .ti -1c
272 .RI "gpg_error_t \fBpwmd_command_ap\fP (\fBpwm_t\fP *pwm, char **result, const char *cmd, va_list ap)"
273 .br
274 .ti -1c
275 .RI "gpg_error_t \fBpwmd_inquire\fP (\fBpwm_t\fP *pwm, const char *cmd, \fBpwmd_inquire_cb_t\fP func, void *user)"
276 .br
277 .ti -1c
278 .RI "gpg_error_t \fBpwmd_disconnect\fP (\fBpwm_t\fP *pwm)"
279 .br
280 .ti -1c
281 .RI "void \fBpwmd_close\fP (\fBpwm_t\fP *pwm)"
282 .br
283 .ti -1c
284 .RI "gpg_error_t \fBpwmd_socket_type\fP (\fBpwm_t\fP *pwm, \fBpwmd_socket_t\fP *type)"
285 .br
286 .ti -1c
287 .RI "void \fBpwmd_free\fP (void *ptr)"
288 .br
289 .ti -1c
290 .RI "void * \fBpwmd_malloc\fP (size_t size)"
291 .br
292 .ti -1c
293 .RI "void * \fBpwmd_calloc\fP (size_t nmemb, size_t size)"
294 .br
295 .ti -1c
296 .RI "void * \fBpwmd_realloc\fP (void *ptr, size_t size)"
297 .br
298 .ti -1c
299 .RI "char * \fBpwmd_strdup\fP (const char *str)"
300 .br
301 .ti -1c
302 .RI "char * \fBpwmd_strdup_printf\fP (const char *fmt,...)"
303 .br
304 .ti -1c
305 .RI "const char * \fBpwmd_strerror\fP (gpg_error_t code)"
306 .br
307 .ti -1c
308 .RI "int \fBpwmd_strerror_r\fP (gpg_error_t code, char *buf, size_t size)"
309 .br
310 .in -1c
311 .SH "Constant Details"
312 .PP
313 .SS "#define EPWMD_FILE_MODIFIED"
314 .PP
315 The data file was modified either externally or by another client while trying to process a command.
316 .SS "#define EPWMD_LIBXML_ERROR"
317 .PP
318 An XML parse or other libxml2 error occurred.
319 .SS "#define EPWMD_NO_FILE"
320 .PP
321 A command required an open file but no file has yet been opened.
322 .SS "#define LIBPWMD_VERSION 0x602"
323 .PP
324 The version of this library.
325 .SS "#define PWMD_FD_READABLE"
326 .PP
327 Set when the file descriptor is readable.
328 .SS "#define PWMD_FD_WRITABLE"
329 .PP
330 Set when the file descriptor is writable.
331 .SH "Typedef Details"
332 .PP
333 .SS "\fBpwm_t\fP"
334 .PP
335 When a handle is mentioned in this documentation it is a pointer of this type. A new handle is created with \fBpwmd_new()\fP.
336 .SS "\fBpwmd_inquire_cb_t\fP"
337 .PP
338 This is a callback function that gets passed to \fBpwmd_inquire()\fP. It is used for sending data to the server for commands that need to reply to an INQUIRE server 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 an internal \fBassuan_transact()\fP from an internal inquire callback function which in turn calls this function by looping over its return value.
339 .PP
340 \fBParameters:\fP
341 .RS 4
342 \fIuser\fP The user data pointer passed to \fBpwmd_inquire()\fP.
343 .br
344 \fIcmd\fP The same as the \fIcmd\fP argument to \fBpwmd_inquire()\fP.
345 .br
346 \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's value will always be 0 since no data has been sent yet.
347 .br
348 \fIdata\fP The next chunk of data to send or NULL.
349 .br
350 \fIlen\fP The length of \fIdata\fP or 0.
351 .RE
352 .PP
353 \fBReturn values:\fP
354 .RS 4
355 \fI0\fP There is more data to be sent.
356 .br
357 \fIGPG_ERR_EOF\fP No need to call this function again, the current \fIline\fP is the last to send.
358 .br
359 \fIcode\fP Any other error code which will terminate the INQUIRE.
360 .RE
361 .PP
362 \fBNote:\fP
363 .RS 4
364 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.
365 .RE
366 .PP
368 .SS "\fBpwmd_knownhost_cb_t\fP"
369 .PP
370 When \fBPWMD_OPTION_KNOWNHOST_CB\fP is set and a the current connections host key was not found in the known hosts file, then this callback function can be used to confirm the addition of the new host key to the known_hosts file.
371 .PP
372 \fBParameters:\fP
373 .RS 4
374 \fIuser\fP User data which was set with \fBPWMD_OPTION_KNOWNHOST_DATA\fP.
375 .br
376 \fIhost\fP The hostname as passed to the connecting function.
377 .br
378 \fIkey\fP The raw host key. Note that this differs from the format returned from \fBpwmd_get_hostkey()\fP.
379 .br
380 \fIlen\fP The host key length.
381 .RE
382 .PP
383 \fBReturn values:\fP
384 .RS 4
385 \fI0\fP Add the host key to the known hosts file.
386 .br
387 \fIGPG_ERR_NOT_CONFIRMED\fP Do not add the host key and abort the connection.
388 .RE
389 .PP
390 \fBNote:\fP
391 .RS 4
392 If the known hosts file cannot be modified do to filesystem restrictions when trying to add the new host key, no error is returned. Instead the host key is added to the current connections host key cache and the connection is considered verified.
393 .RE
394 .PP
395 \fBSee also:\fP
396 .RS 4
397 \fBSSH Details\fP
398 .RE
399 .PP
401 .SS "\fBpwmd_passphrase_cb_t\fP"
402 .PP
403 The value of the option \fBPWMD_OPTION_PASSPHRASE_CB\fP which is set with \fBpwmd_setopt()\fP.
404 .PP
405 \fBParameters:\fP
406 .RS 4
407 \fIuser\fP A user data pointer which is set with \fBPWMD_OPTION_PASSPHRASE_DATA\fP.
408 .br
409 \fIpassphrase\fP The passphrase which may be an empty string or NULL. It is not modified by libpwmd but must remain allocated for as long as it is needed.
410 .RE
411 .PP
412 \fBReturns:\fP
413 .RS 4
414 0 on success or an error code which will cause a command to fail.
415 .RE
416 .PP
418 .SS "\fBpwmd_status_cb_t\fP"
419 .PP
420 The value of the option \fBPWMD_OPTION_STATUS_CB\fP which is set with \fBpwmd_setopt()\fP.
421 .PP
422 \fBParameters:\fP
423 .RS 4
424 \fIuser\fP A user data pointer which is set with \fBPWMD_OPTION_STATUS_DATA\fP.
425 .br
426 \fIline\fP The status message line received from the server.
427 .RE
428 .PP
429 \fBReturns:\fP
430 .RS 4
431 0 on success or an error code which will cause a command to fail.
432 .RE
433 .PP
435 .SH "Enumeration Details"
436 .PP
437 .SS "enum \fBpwmd_async_t\fP"
438 .PP
439 The return code of \fBpwmd_process()\fP which is used for all asynchronous commands.
440 .PP
441 \fBEnumerator: \fP
442 .in +1c
443 .TP
444 \fB\fIASYNC_INIT \fP\fP
445 .PP
446 \fBFor internal use only.\fP
447 .RS 4
448 .RE
449 .PP
451 .TP
452 \fB\fIASYNC_PROCESS \fP\fP
453 \fBpwmd_process()\fP should be called again.
454 .TP
455 \fB\fIASYNC_DONE \fP\fP
456 The command has completed. The result code should be checked for an error.
457 .SS "enum \fBpwmd_ip_version_t\fP"
458 .PP
459 The value of the option \fBPWMD_OPTION_IP_VERSION\fP which is set with \fBpwmd_setopt()\fP.
460 .PP
461 \fBEnumerator: \fP
462 .in +1c
463 .TP
464 \fB\fIPWMD_IP_ANY \fP\fP
465 Try both IPv4 and IPv6 addresses. Note that IPv4 is tried first and that \fBPWMD_IP_ANY\fP only affects a hostname and not an IP address in the address specification.
466 .TP
467 \fB\fIPWMD_IPV4 \fP\fP
468 Only try IPv4.
469 .TP
470 \fB\fIPWMD_IPV6 \fP\fP
471 Only try IPv6.
472 .SS "enum \fBpwmd_option_t\fP"
473 .PP
474 libpwmd options which are set with \fBpwmd_setopt()\fP.
475 .PP
476 \fBNote:\fP
477 .RS 4
478 When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user.
479 .RE
480 .PP
482 .PP
483 \fBEnumerator: \fP
484 .in +1c
485 .TP
486 \fB\fIPWMD_OPTION_PASSPHRASE_CB \fP\fP
487 A custom passphrase retrieval function which, when set, will be used instead of \fBpinentry(1)\fP. This function will not be used if opening a file and 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.
488 .PP
489 \fBNote:\fP
490 .RS 4
491 An empty string as the passphrase is allowed.
492 .RE
493 .PP
495 .TP
496 \fB\fIPWMD_OPTION_PASSPHRASE_DATA \fP\fP
497 User supplied data which is passed to the custom passphrase function.
498 .TP
499 \fB\fIPWMD_OPTION_PASSPHRASE \fP\fP
500 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.
501 .PP
502 \fBNote:\fP
503 .RS 4
504 An empty string as the passphrase is allowed.
505 .RE
506 .PP
508 .TP
509 \fB\fIPWMD_OPTION_KNOWNHOST_CB \fP\fP
510 A function to confirm an unknown host hash which wasn't found in the known hosts file.
511 .PP
512 \fBSee also:\fP
513 .RS 4
514 \fBSSH Details\fP
515 .RE
516 .PP
518 .TP
519 \fB\fIPWMD_OPTION_KNOWNHOST_DATA \fP\fP
520 User supplied data which is passed to the known host function.
521 .PP
522 \fBSee also:\fP
523 .RS 4
524 \fBSSH Details\fP
525 .RE
526 .PP
528 .TP
529 \fB\fIPWMD_OPTION_PINENTRY_TRIES \fP\fP
530 An integer value that specifies the number of tries before \fBpinentry(1)\fP will give up when opening a file with the wrong supplied passphrase. The default is 3.
531 .PP
532 \fBNote:\fP
533 .RS 4
534 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.
535 .RE
536 .PP
538 .TP
539 \fB\fIPWMD_OPTION_PINENTRY_PATH \fP\fP
540 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.
541 .PP
542 \fBSee also:\fP
543 .RS 4
544 \fBPinentry Details\fP
545 .RE
546 .PP
548 .TP
549 \fB\fIPWMD_OPTION_PINENTRY_TTY \fP\fP
550 A value which specifies the full path to the TTY that \fBpinentry(1)\fP will use to prompt on. When set and no DISPLAY is available, \fBPWMD_OPTION_PINENTRY_TERM\fP must also be set.
551 .PP
552 \fBSee also:\fP
553 .RS 4
554 \fBPinentry Details\fP
555 .RE
556 .PP
558 .TP
559 \fB\fIPWMD_OPTION_PINENTRY_TERM \fP\fP
560 A value which specifies the terminal type (e.g., vt100) that \fBpinentry(1)\fP will use when no X11 display is available.
561 .PP
562 \fBSee also:\fP
563 .RS 4
564 \fBPinentry Details\fP
565 .RE
566 .PP
568 .TP
569 \fB\fIPWMD_OPTION_PINENTRY_DISPLAY \fP\fP
570 A value which specifies the X11 display that \fBpinentry(1)\fP will use.
571 .PP
572 \fBTodo\fP
573 .RS 4
574 X11 port forwarding so a remote pinentry can use the local display.
575 .RE
576 .PP
577 \fBSee also:\fP
578 .RS 4
579 \fBPinentry Details\fP
580 .RE
581 .PP
583 .TP
584 \fB\fIPWMD_OPTION_PINENTRY_TITLE \fP\fP
585 A character string that \fBpinentry(1)\fP will use in it's dialog window.
586 .TP
587 \fB\fIPWMD_OPTION_PINENTRY_PROMPT \fP\fP
588 A character string that \fBpinentry(1)\fP will use in it's dialog window.
589 .TP
590 \fB\fIPWMD_OPTION_PINENTRY_DESC \fP\fP
591 A character string that \fBpinentry(1)\fP will use in it's dialog window.
592 .TP
593 \fB\fIPWMD_OPTION_PINENTRY_LC_CTYPE \fP\fP
594 For \fBpinentry(1)\fP localization.
595 .TP
596 \fB\fIPWMD_OPTION_PINENTRY_LC_MESSAGES \fP\fP
597 For \fBpinentry(1)\fP localization.
598 .TP
599 \fB\fIPWMD_OPTION_PINENTRY_TIMEOUT \fP\fP
600 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.
601 .TP
602 \fB\fIPWMD_OPTION_STATUS_CB \fP\fP
603 A function of type \fBpwmd_status_cb_t\fP that will process status messages received from the pwmd server.
604 .TP
605 \fB\fIPWMD_OPTION_STATUS_DATA \fP\fP
606 A user data pointer which is passed to the status message function.
607 .TP
608 \fB\fIPWMD_OPTION_IP_VERSION \fP\fP
609 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. The default is \fBPWMD_IP_ANY\fP.
610 .PP
611 \fBNote:\fP
612 .RS 4
613 This option must be set before a connection is made when not the default.
614 .RE
615 .PP
617 .TP
618 \fB\fIPWMD_OPTION_INQUIRE_TOTAL \fP\fP
619 When the total number of bytes to be sent via an INQUIRE is known, this should be set so XFER status messages can be parsed correctly. When not known or unset, 0 is used as the total argument to the XFER status message. This option should be set before each call to \fBpwmd_inquire()\fP.
620 .PP
621 \fBNote:\fP
622 .RS 4
623 During the INQUIRE, PWMD_OPTION_STATUS_CB is called after every ASSUAN_LINELENGTH bytes have been successfully transferred.
624 .PP
625 This is a libpwmd feature. pwmd itself does not send XFER status messages during an INQUIRE. Status messages can be parsed only when PWMD_OPTION_STATUS_CB is set.
626 .RE
627 .PP
629 .SS "enum \fBpwmd_pinentry_t\fP"
630 .PP
631 For use with \fBpwmd_getpin()\fP.
632 .PP
633 \fBEnumerator: \fP
634 .in +1c
635 .TP
636 \fB\fIPWMD_PINENTRY_OPEN \fP\fP
637 When opening a file.
638 .TP
639 \fB\fIPWMD_PINENTRY_OPEN_FAILED \fP\fP
640 When opening a file failed.
641 .TP
642 \fB\fIPWMD_PINENTRY_SAVE \fP\fP
643 When saving a file.
644 .TP
645 \fB\fIPWMD_PINENTRY_SAVE_CONFIRM \fP\fP
646 For passphrase confirmation.
647 .TP
648 \fB\fIPWMD_PINENTRY_CONFIRM \fP\fP
649 For confirmation of a user-defined prompt.
650 .TP
651 \fB\fIPWMD_PINENTRY_DEFAULT \fP\fP
652 For the default or user defined string set with \fBPWMD_OPTION_PINENTRY_DESC\fP.
653 .TP
654 \fB\fIPWMD_PINENTRY_CLOSE \fP\fP
655 To terminate the pinentry process created with \fBpwmd_getpin()\fP.
656 .SS "enum \fBpwmd_socket_t\fP"
657 .PP
658 For use with \fBpwmd_socket_type()\fP.
659 .PP
660 \fBEnumerator: \fP
661 .in +1c
662 .TP
663 \fB\fIPWMD_SOCKET_LOCAL \fP\fP
664 A local domain socket.
665 .TP
666 \fB\fIPWMD_SOCKET_SSH \fP\fP
667 An SSH connection over a TCP socket.
668 .SH "Function Details"
669 .PP
670 .SS "void* pwmd_calloc (size_t nmemb, size_t size)"
671 .PP
672 A wrapper around calloc().
673 .PP
674 Like calloc(), but lets libpwmd keep track of the pointer.
675 .PP
676 \fBParameters:\fP
677 .RS 4
678 \fInmemb\fP The number of elements to allocate.
679 .br
680 \fIsize\fP The number of bytes to allocate.
681 .RE
682 .PP
683 \fBReturns:\fP
684 .RS 4
685 A newly allocated pointer or NULL if there wasn't enough memory.
686 .RE
687 .PP
688 \fBSee also:\fP
689 .RS 4
690 calloc(3), \fBpwmd_free()\fP
691 .RE
692 .PP
694 .SS "void pwmd_close (\fBpwm_t\fP * pwm)"
695 .PP
696 Close a handle.
697 .PP
698 This will close the connection to a pwmd server and free any resources associated with it.
699 .PP
700 \fBParameters:\fP
701 .RS 4
702 \fIpwm\fP A handle.
703 .RE
704 .PP
705 \fBReturns:\fP
706 .RS 4
707 Nothing.
708 .RE
709 .PP
710 \fBSee also:\fP
711 .RS 4
712 \fBpwmd_disconnect()\fP, \fBpwmd_new()\fP
713 .RE
714 .PP
716 .SS "gpg_error_t pwmd_command (\fBpwm_t\fP * pwm, char ** result, const char * cmd, ...)"
717 .PP
718 Send a command to the pwmd server.
719 .PP
720 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 must be used and not this function.
721 .PP
722 \fBParameters:\fP
723 .RS 4
724 \fIpwm\fP A handle.
725 .br
726 \fIresult\fP The result of the command when successful which must be freed with \fBpwmd_free()\fP.
727 .br
728 \fIcmd\fP The command to send and any following arguments.
729 .RE
730 .PP
731 \fBReturns:\fP
732 .RS 4
733 0 on success or an error code.
734 .RE
735 .PP
736 \fBNote:\fP
737 .RS 4
738 Not all commands return a result.
739 .RE
740 .PP
742 .SS "gpg_error_t pwmd_command_ap (\fBpwm_t\fP * pwm, char ** result, const char * cmd, va_list ap)"
743 .PP
744 Send a command to the pwmd server.
745 .PP
746 Like \fBpwmd_command()\fP but uses an argument pointer instead.
747 .PP
748 \fBParameters:\fP
749 .RS 4
750 \fIpwm\fP A handle.
751 .br
752 \fIresult\fP The result of the command when successful which must be freed with \fBpwmd_free()\fP.
753 .br
754 \fIcmd\fP The command to send.
755 .br
756 \fIap\fP The arguments to \fIcmd\fP.
757 .RE
758 .PP
759 \fBReturns:\fP
760 .RS 4
761 0 on success or an error code.
762 .RE
763 .PP
764 \fBNote:\fP
765 .RS 4
766 Not all commands return a result.
767 .RE
768 .PP
770 .SS "gpg_error_t pwmd_connect (\fBpwm_t\fP * pwm, const char * path)"
771 .PP
772 Connect to a local pwmd server.
773 .PP
774 Connects to a local unix domain socket.
775 .PP
776 \fBParameters:\fP
777 .RS 4
778 \fIpwm\fP A handle.
779 .br
780 \fIpath\fP The socket path to connect to. If NULL, then a default of \fI'~/.pwmd/socket'\fP will be used.
781 .RE
782 .PP
783 \fBReturns:\fP
784 .RS 4
785 0 on success or an error code.
786 .RE
787 .PP
788 \fBNote:\fP
789 .RS 4
790 When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user.
791 .RE
792 .PP
793 \fBSee also:\fP
794 .RS 4
795 \fBpwmd_ssh_connect()\fP, \fBpwmd_ssh_connect_async()\fP, \fBpwmd_disconnect()\fP
796 .RE
797 .PP
799 .SS "gpg_error_t pwmd_connect_url (\fBpwm_t\fP * pwm, const char * url)"
800 .PP
801 Establish a connection by parsing a URL.
802 .PP
803 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:
804 .PP
805 .nf
806 file://[path/to/local/socket]
808 or
810 ssh[46]://[username@]hostname[:port],identity,known_hosts
812 .fi
813 .PP
814 .PP
815 The parameters in square brackets are optional and if not specified then defaults will be used. If neither socket specification is matched, the \fIurl\fP is assumed to be a file://.
816 .PP
817 \fBParameters:\fP
818 .RS 4
819 \fIpwm\fP A handle.
820 .br
821 \fIurl\fP The string to parse.
822 .RE
823 .PP
824 \fBNote:\fP
825 .RS 4
826 When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user.
827 .RE
828 .PP
829 \fBReturns:\fP
830 .RS 4
831 0 on success or an error code.
832 .RE
833 .PP
834 \fBSee also:\fP
835 .RS 4
836 \fBpwmd_socket_type()\fP, \fBpwmd_disconnect()\fP
837 .RE
838 .PP
840 .SS "gpg_error_t pwmd_connect_url_async (\fBpwm_t\fP * pwm, const char * url)"
841 .PP
842 Establish a connection by parsing a URL (asynchronously).
843 .PP
844 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:
845 .PP
846 .nf
847 file://[path/to/local/socket]
849 or
851 ssh[46]://[username@]hostname[:port],identity,known_hosts
853 .fi
854 .PP
855 .PP
856 The parameters in square brackets are optional and if not specified then defaults will be used. If neither socket specification is matched, the \fIurl\fP is assumed to be a file://.
857 .PP
858 \fBpwmd_process()\fP should be called until the command completes.
859 .PP
860 \fBParameters:\fP
861 .RS 4
862 \fIpwm\fP A handle.
863 .br
864 \fIurl\fP The string to parse.
865 .RE
866 .PP
867 \fBNote:\fP
868 .RS 4
869 When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user.
870 .RE
871 .PP
872 \fBReturns:\fP
873 .RS 4
874 0 on success or an error code.
875 .RE
876 .PP
877 \fBSee also:\fP
878 .RS 4
879 \fBpwmd_socket_type()\fP, \fBpwmd_disconnect()\fP
880 .RE
881 .PP
883 .SS "gpg_error_t pwmd_disconnect (\fBpwm_t\fP * pwm)"
884 .PP
885 Close a connection to the pwmd server.
886 .PP
887 This will close the connection but keep any previously set options for the specified handle.
888 .PP
889 \fBParameters:\fP
890 .RS 4
891 \fIpwm\fP A handle.
892 .RE
893 .PP
894 \fBReturns:\fP
895 .RS 4
896 0 on success or an error code.
897 .RE
898 .PP
899 \fBSee also:\fP
900 .RS 4
901 \fBpwmd_close()\fP
902 .RE
903 .PP
905 .SS "void pwmd_free (void * ptr)"
906 .PP
907 Free a previously allocated pointer.
908 .PP
909 Use this function to free resources allocated by the other libpwmd memory functions. Do not use it to free allocations made by other allocators.
910 .PP
911 The difference between the standard free() and this function is that this one will zero out the contents of the pointer before freeing it.
912 .PP
913 \fBParameters:\fP
914 .RS 4
915 \fIptr\fP The pointer to deallocate.
916 .RE
917 .PP
918 \fBReturns:\fP
919 .RS 4
920 Nothing.
921 .RE
922 .PP
923 \fBSee also:\fP
924 .RS 4
925 \fBpwmd_malloc()\fP, \fBpwmd_calloc()\fP, \fBpwmd_realloc()\fP, \fBpwmd_strdup()\fP, \fBpwmd_process()\fP, \fBpwmd_command()\fP
926 .RE
927 .PP
929 .SS "gpg_error_t pwmd_get_fds (\fBpwm_t\fP * pwm, \fBpwmd_fd_t\fP * fds, int * n_fds)"
930 .PP
931 Get the associated file descriptor(s) for a handle.
932 .PP
933 This function lets the application manually poll the available file descriptors for the specified handle. It should be called after each asynchronous function call and after each call to \fBpwmd_process()\fP since the polled file descriptors may have been closed since the previous call.
934 .PP
935 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.
936 .PP
937 \fBParameters:\fP
938 .RS 4
939 \fIpwm\fP A handle.
940 .br
941 \fIfds\fP Set to the file descriptor(s) of the associated handle.
942 .br
943 \fIn_fds\fP Initially the size of \fIfds\fP then updated to the number of available file descriptors which are stored in \fIfds\fP.
944 .RE
945 .PP
946 \fBReturn values:\fP
947 .RS 4
948 \fI0\fP on success or an error code.
949 .br
950 \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.
951 .RE
952 .PP
953 \fBSee also:\fP
954 .RS 4
955 \fBpwmd_process()\fP
956 .RE
957 .PP
959 .SS "gpg_error_t pwmd_get_hostkey (\fBpwm_t\fP * pwm, const char * host, int port, char ** result)"
960 .PP
961 Retrieve a remote SSH public host key.
962 .PP
963 This key is needed for host verification of the remote pwmd server. You should be sure that the remote host is really the host that your wanting to connect to and not subject to a man-in-the-middle attack.
964 .PP
965 \fBParameters:\fP
966 .RS 4
967 \fIpwm\fP A handle.
968 .br
969 \fIhost\fP The hostname to connect to.
970 .br
971 \fIport\fP The port or -1 for the default of 22.
972 .br
973 \fIresult\fP An OpenSSH known hosts formatted line containing the servers public key which should be freed with \fBpwmd_free()\fP.
974 .RE
975 .PP
976 \fBReturns:\fP
977 .RS 4
978 0 on success or an error code.
979 .RE
980 .PP
981 \fBVersion:\fP
982 .RS 4
983 6.0.3 The connection is kept open but not verified after returning. It can be resumed from one of the SSH connection functions.
984 .RE
985 .PP
986 \fBSee also:\fP
987 .RS 4
988 \fBpwmd_get_hostkey_async()\fP, \fBpwmd_ssh_connect()\fP, \fBSSH Details\fP
989 .RE
990 .PP
992 .SS "gpg_error_t pwmd_get_hostkey_async (\fBpwm_t\fP * pwm, const char * host, int port)"
993 .PP
994 Retrieve a remote SSH host key (asynchronously).
995 .PP
996 This key is needed for host verification of the remote pwmd server. You should be sure that the remote host is really the host that your wanting to connect to and not subject to a man-in-the-middle attack.
997 .PP
998 \fBpwmd_process()\fP should be called until the command completes.
999 .PP
1000 \fBParameters:\fP
1001 .RS 4
1002 \fIpwm\fP A handle.
1003 .br
1004 \fIhost\fP The hostname to connect to.
1005 .br
1006 \fIport\fP The port or -1 for the default of 22.
1007 .RE
1008 .PP
1009 \fBReturns:\fP
1010 .RS 4
1011 0 on success or an error code.
1012 .RE
1013 .PP
1014 \fBVersion:\fP
1015 .RS 4
1016 6.0.3 The connection is kept open but not verified after returning. It can be resumed from one of the SSH connection functions.
1017 .RE
1018 .PP
1019 \fBSee also:\fP
1020 .RS 4
1021 \fBpwmd_get_hostkey()\fP, \fBpwmd_ssh_connect_async()\fP, \fBpwmd_process()\fP, \fBSSH Details\fP
1022 .RE
1023 .PP
1025 .SS "gpg_error_t pwmd_getpin (\fBpwm_t\fP * pwm, const char * filename, char ** result, \fBpwmd_pinentry_t\fP which)"
1026 .PP
1027 Launch a local pinentry.
1028 .PP
1029 Does not send any command to the server. Maybe useful if a passphrase is needed before opening a file over a remote connection. This passphrase can then be set with \fBpwmd_setopt()\fP.
1030 .PP
1031 This function may also be used to display a user confirmation dialog with pinentry when \fIwhich\fP is \fBPWMD_PINENTRY_CONFIRM\fP. The text to prompt with is set with \fBPWMD_OPTION_PINENTRY_TITLE\fP.
1032 .PP
1033 \fBParameters:\fP
1034 .RS 4
1035 \fIpwm\fP A handle.
1036 .br
1037 \fIfilename\fP The filename to use in the pinentry dialog strings.
1038 .br
1039 \fIresult\fP The entered value in the pinentry dialog which should be freed with \fBpwmd_free()\fP.
1040 .br
1041 \fIwhich\fP Determines the default strings shown in the pinentry dialog. \fBpwmd_setopt()\fP may also be used to override the defaults. In this case \fBPWMD_PINENTRY_DEFAULT\fP should be used. \fBPWMD_PINENTRY_CLOSE\fP should be used to terminate the pinentry process when the pinentry is no longer needed.
1042 .RE
1043 .PP
1044 \fBReturns:\fP
1045 .RS 4
1046 0 on success or an error.
1047 .RE
1048 .PP
1050 .SS "gpg_error_t pwmd_init (void)"
1051 .PP
1052 Initialize the library.
1053 .PP
1054 This function must be the first function called in the library before any others. It sets up the memory allocators and internationalization among other things.
1055 .PP
1056 \fBReturns:\fP
1057 .RS 4
1058 0 on success or an error code.
1059 .RE
1060 .PP
1062 .SS "gpg_error_t pwmd_inquire (\fBpwm_t\fP * pwm, const char * cmd, \fBpwmd_inquire_cb_t\fP func, void * user)"
1063 .PP
1064 Send data to a pwmd server.
1065 .PP
1066 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 pwmd commands.
1067 .PP
1068 \fBParameters:\fP
1069 .RS 4
1070 \fIpwm\fP A handle.
1071 .br
1072 \fIcmd\fP The command (without arguments) to send that uses an INQUIRE.
1073 .br
1074 \fIfunc\fP A callback function of type \fBpwmd_inquire_cb_t\fP which sets the data to be sent.
1075 .br
1076 \fIuser\fP A user data pointer passed to the callback function \fIfunc\fP.
1077 .RE
1078 .PP
1079 \fBReturns:\fP
1080 .RS 4
1081 0 on success or an error code.
1082 .RE
1083 .PP
1084 \fBSee also:\fP
1085 .RS 4
1086 \fBpwmd_inquire_cb_t\fP
1087 .RE
1088 .PP
1090 .SS "void* pwmd_malloc (size_t size)"
1091 .PP
1092 A wrapper around malloc.
1093 .PP
1094 Like malloc(), but lets libpwmd keep track of the pointer.
1095 .PP
1096 \fBParameters:\fP
1097 .RS 4
1098 \fIsize\fP The number of bytes to allocate.
1099 .RE
1100 .PP
1101 \fBReturns:\fP
1102 .RS 4
1103 A newly allocated pointer or NULL if there wasn't enough memory.
1104 .RE
1105 .PP
1106 \fBSee also:\fP
1107 .RS 4
1108 malloc(3), \fBpwmd_free()\fP
1109 .RE
1110 .PP
1112 .SS "\fBpwm_t\fP* pwmd_new (const char * name)"
1113 .PP
1114 Creates a new handle.
1115 .PP
1116 Creates a new handle for use with the other functions.
1117 .PP
1118 \fBParameters:\fP
1119 .RS 4
1120 \fIname\fP If not NULL, the name of the application. The application name is sent to the pwmd server after successfully connecting.
1121 .RE
1122 .PP
1123 \fBReturns:\fP
1124 .RS 4
1125 a new handle or NULL if there was not enough memory.
1126 .RE
1127 .PP
1129 .SS "gpg_error_t pwmd_open (\fBpwm_t\fP * pwm, const char * filename)"
1130 .PP
1131 Open a file on the pwmd server.
1132 .PP
1133 This will send the OPEN command to the server.
1134 .PP
1135 \fBParameters:\fP
1136 .RS 4
1137 \fIpwm\fP A handle.
1138 .br
1139 \fIfilename\fP The filename to open. The \fIfilename\fP is not a full path but the data file only.
1140 .RE
1141 .PP
1142 \fBReturns:\fP
1143 .RS 4
1144 0 on success or an error code.
1145 .RE
1146 .PP
1147 \fBSee also:\fP
1148 .RS 4
1149 \fBPinentry Details\fP
1150 .RE
1151 .PP
1153 .SS "gpg_error_t pwmd_open2 (\fBpwm_t\fP * pwm, const char * filename)"
1154 .PP
1155 Open a file on the pwmd server using a local pinentry.
1156 .PP
1157 This will send the OPEN command to the server like \fBpwmd_open()\fP but will use the local pinentry and not pwmd's pinentry.
1158 .PP
1159 \fBNote:\fP
1160 .RS 4
1161 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.
1162 .PP
1163 This pinentry method is not thread safe. It needs to set a couple of global variables for the pinentry timeout to work properly.
1164 .RE
1165 .PP
1166 \fBParameters:\fP
1167 .RS 4
1168 \fIpwm\fP A handle.
1169 .br
1170 \fIfilename\fP The filename to open. The \fIfilename\fP is not a full path but the data file only.
1171 .RE
1172 .PP
1173 \fBReturns:\fP
1174 .RS 4
1175 0 on success or an error code.
1176 .RE
1177 .PP
1178 \fBReturn values:\fP
1179 .RS 4
1180 \fIGPG_ERR_PIN_BLOCKED\fP Another handle is using the local pinentry.
1181 .RE
1182 .PP
1183 \fBSee also:\fP
1184 .RS 4
1185 \fBPinentry Details\fP
1186 .RE
1187 .PP
1189 .SS "gpg_error_t pwmd_open_async (\fBpwm_t\fP * pwm, const char * filename)"
1190 .PP
1191 Open a file on the pwmd server (asynchronously).
1192 .PP
1193 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.
1194 .PP
1195 \fBpwmd_process()\fP should be called until the command completes.
1196 .PP
1197 \fBParameters:\fP
1198 .RS 4
1199 \fIpwm\fP A handle.
1200 .br
1201 \fIfilename\fP The filename to open. The \fIfilename\fP is not a full path but the data file only.
1202 .RE
1203 .PP
1204 \fBReturns:\fP
1205 .RS 4
1206 0 on success or an error code.
1207 .RE
1208 .PP
1209 \fBSee also:\fP
1210 .RS 4
1211 \fBpwmd_process()\fP, \fBPinentry Details\fP
1212 .RE
1213 .PP
1215 .SS "gpg_error_t pwmd_open_async2 (\fBpwm_t\fP * pwm, const char * filename)"
1216 .PP
1217 Open a file on the pwmd server asynchronously (fork method).
1218 .PP
1219 This is kind of a hybrid of \fBpwmd_open2()\fP and \fBpwmd_open_async()\fP. It will use the local pinentry asynchronously and also do the OPEN command asynchronously.
1220 .PP
1221 \fBpwmd_process()\fP should be called until the command completes.
1222 .PP
1223 \fBNote:\fP
1224 .RS 4
1225 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.
1226 .RE
1227 .PP
1228 \fBParameters:\fP
1229 .RS 4
1230 \fIpwm\fP A handle.
1231 .br
1232 \fIfilename\fP The filename to open. The \fIfilename\fP is not a full path but the data file only.
1233 .RE
1234 .PP
1235 \fBReturns:\fP
1236 .RS 4
1237 0 on success or an error code.
1238 .RE
1239 .PP
1240 \fBSee also:\fP
1241 .RS 4
1242 \fBpwmd_process()\fP, \fBPinentry Details\fP
1243 .RE
1244 .PP
1246 .SS "gpg_error_t pwmd_pending_line (\fBpwm_t\fP * pwm)"
1247 .PP
1248 Check for a unparsed buffered line.
1249 .PP
1250 A buffered line is a line that was read from the server but has not yet been processed. This function determines if there is such a line.
1251 .PP
1252 \fBParameters:\fP
1253 .RS 4
1254 \fIpwm\fP A handle.
1255 .RE
1256 .PP
1257 \fBReturn values:\fP
1258 .RS 4
1259 \fI0\fP if there is a pending line.
1260 .br
1261 \fIGPG_ERR_NO_DATA\fP if there is no pending line.
1262 .RE
1263 .PP
1264 \fBSee also:\fP
1265 .RS 4
1266 \fBpwmd_process()\fP
1267 .RE
1268 .PP
1270 .SS "\fBpwmd_async_t\fP pwmd_process (\fBpwm_t\fP * pwm, gpg_error_t * rc, char ** result)"
1271 .PP
1272 Process an asynchronous function.
1273 .PP
1274 After an asynchronous function has been called and has returned successfully, this function must be called to process the command and retrieve the result and return value.
1275 .PP
1276 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.
1277 .PP
1278 \fBParameters:\fP
1279 .RS 4
1280 \fIpwm\fP A handle.
1281 .br
1282 \fIrc\fP Set to the return code of the original command after ASYNC_DONE has been returned. This value must be checked to determine if the command succeeded.
1283 .br
1284 \fIresult\fP Set to the result of the command when \fIrc\fP is 0. Note that not all commands return a result.
1285 .RE
1286 .PP
1287 \fBReturn values:\fP
1288 .RS 4
1289 \fIASYNC_DONE\fP The command has completed. \fIrc\fP should be checked to determine if the command was successful or not.
1290 .br
1291 \fIASYNC_PROCESS\fP The command is still running and this function should be called again.
1292 .RE
1293 .PP
1294 \fBSee also:\fP
1295 .RS 4
1296 \fBpwmd_get_fds()\fP, \fBpwmd_pending_line()\fP
1297 .RE
1298 .PP
1300 .SS "void* pwmd_realloc (void * ptr, size_t size)"
1301 .PP
1302 A wrapper around realloc().
1303 .PP
1304 Like realloc(), but lets libpwmd keep track of the pointer.
1305 .PP
1306 \fBNote:\fP
1307 .RS 4
1308 This function will try and allocate the entire \fIsize\fP before freeing the original pointer and returning the new one.
1309 .RE
1310 .PP
1311 \fBParameters:\fP
1312 .RS 4
1313 \fIptr\fP The pointer to reallocate.
1314 .br
1315 \fIsize\fP The new number of bytes to allocate.
1316 .RE
1317 .PP
1318 \fBReturns:\fP
1319 .RS 4
1320 A newly allocated pointer or NULL if there wasn't enough memory.
1321 .RE
1322 .PP
1323 \fBSee also:\fP
1324 .RS 4
1325 realloc(3), \fBpwmd_free()\fP
1326 .RE
1327 .PP
1329 .SS "gpg_error_t pwmd_save (\fBpwm_t\fP * pwm)"
1330 .PP
1331 Save a file on the pwmd server.
1332 .PP
1333 This will send the SAVE command.
1334 .PP
1335 \fBParameters:\fP
1336 .RS 4
1337 \fIpwm\fP A handle.
1338 .RE
1339 .PP
1340 \fBReturns:\fP
1341 .RS 4
1342 0 on success or an error code.
1343 .RE
1344 .PP
1345 \fBSee also:\fP
1346 .RS 4
1347 \fBPinentry Details\fP
1348 .RE
1349 .PP
1351 .SS "gpg_error_t pwmd_save2 (\fBpwm_t\fP * pwm)"
1352 .PP
1353 Save a file on the pwmd server using the local pinentry.
1354 .PP
1355 This will send the SAVE command like \fBpwmd_save()\fP but will use a local pinentry and not pwmd's pinentry.
1356 .PP
1357 \fBParameters:\fP
1358 .RS 4
1359 \fIpwm\fP A handle.
1360 .RE
1361 .PP
1362 \fBReturns:\fP
1363 .RS 4
1364 0 on success or an error code.
1365 .RE
1366 .PP
1367 \fBSee also:\fP
1368 .RS 4
1369 \fBPinentry Details\fP
1370 .RE
1371 .PP
1373 .SS "gpg_error_t pwmd_save_async (\fBpwm_t\fP * pwm)"
1374 .PP
1375 Save changes to a file on the pwmd server (asynchronously).
1376 .PP
1377 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.
1378 .PP
1379 \fBpwmd_process()\fP should be called until the command completes.
1380 .PP
1381 \fBParameters:\fP
1382 .RS 4
1383 \fIpwm\fP A handle.
1384 .RE
1385 .PP
1386 \fBReturns:\fP
1387 .RS 4
1388 0 on success or an error code.
1389 .RE
1390 .PP
1391 \fBSee also:\fP
1392 .RS 4
1393 \fBpwmd_process()\fP, \fBPinentry Details\fP
1394 .RE
1395 .PP
1397 .SS "gpg_error_t pwmd_save_async2 (\fBpwm_t\fP * pwm)"
1398 .PP
1399 Save a file on the pwmd server asynchronously (fork method).
1400 .PP
1401 This is kind of a hybrid of \fBpwmd_save2()\fP and \fBpwmd_save_async()\fP. It will use the local pinentry asynchronously and also do the SAVE command asynchronously.
1402 .PP
1403 \fBpwmd_process()\fP should be called until the command completes.
1404 .PP
1405 \fBParameters:\fP
1406 .RS 4
1407 \fIpwm\fP A handle.
1408 .RE
1409 .PP
1410 \fBReturns:\fP
1411 .RS 4
1412 0 on success or an error code.
1413 .RE
1414 .PP
1415 \fBSee also:\fP
1416 .RS 4
1417 \fBpwmd_process()\fP, \fBPinentry Details\fP
1418 .RE
1419 .PP
1421 .SS "gpg_error_t pwmd_setopt (\fBpwm_t\fP * pwm, \fBpwmd_option_t\fP opt, ...)"
1422 .PP
1423 Set handle options.
1424 .PP
1425 See \fBpwmd_option_t\fP for option specific details.
1426 .PP
1427 \fBParameters:\fP
1428 .RS 4
1429 \fIpwm\fP A handle.
1430 .br
1431 \fIopt\fP The option and following value.
1432 .RE
1433 .PP
1434 \fBReturns:\fP
1435 .RS 4
1436 0 on success or an error code.
1437 .RE
1438 .PP
1440 .SS "gpg_error_t pwmd_socket_type (\fBpwm_t\fP * pwm, \fBpwmd_socket_t\fP * type)"
1441 .PP
1442 The type of connection a handle has.
1443 .PP
1444 Useful when you want to know what kind of connection a handle has.
1445 .PP
1446 \fBParameters:\fP
1447 .RS 4
1448 \fIpwm\fP A handle.
1449 .br
1450 \fItype\fP The type of socket.
1451 .RE
1452 .PP
1453 \fBReturns:\fP
1454 .RS 4
1455 0 on success or an error code.
1456 .RE
1457 .PP
1458 \fBSee also:\fP
1459 .RS 4
1460 \fBpwmd_connect_url()\fP
1461 .RE
1462 .PP
1464 .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)"
1465 .PP
1466 Establish a remote connection to a pwmd server.
1467 .PP
1468 Connects to a pwmd server over an SSH channel.
1469 .PP
1470 \fBParameters:\fP
1471 .RS 4
1472 \fIpwm\fP A handle.
1473 .br
1474 \fIhost\fP The hostname to connect to or NULL to resume a connection previously started with \fBpwmd_get_hostkey()\fP.
1475 .br
1476 \fIport\fP The port or -1 for the default of 22.
1477 .br
1478 \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.
1479 .br
1480 \fIuser\fP The username on the SSH server to login as. If NULL then invoking username will be used.
1481 .br
1482 \fIknown_hosts\fP An OpenSSH known hosts formatted file containing public SSH server hashes which may be obtained with \fBpwmd_get_hostkey()\fP or via \fBpwmd_knownhost_cb_t\fP during a connection.
1483 .RE
1484 .PP
1485 \fBReturns:\fP
1486 .RS 4
1487 0 on success or an error code.
1488 .RE
1489 .PP
1490 \fBNote:\fP
1491 .RS 4
1492 When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user.
1493 .RE
1494 .PP
1495 \fBSee also:\fP
1496 .RS 4
1497 \fBpwmd_ssh_connect_async()\fP, \fBPWMD_OPTION_IP_VERSION\fP, \fBpwmd_disconnect()\fP, \fBSSH Details\fP
1498 .RE
1499 .PP
1501 .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)"
1502 .PP
1503 Establish a remote connection to a pwmd server (asynchronously).
1504 .PP
1505 This is a variant of \fBpwmd_ssh_connect()\fP that will not block while doing DNS lookups or while connecting.
1506 .PP
1507 \fBpwmd_process()\fP should be called until the command completes.
1508 .PP
1509 \fBParameters:\fP
1510 .RS 4
1511 \fIpwm\fP A handle.
1512 .br
1513 \fIhost\fP The hostname to connect to or NULL to resume a connection previously started with \fBpwmd_get_hostkey()\fP.
1514 .br
1515 \fIport\fP The port or -1 for the default of 22.
1516 .br
1517 \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.
1518 .br
1519 \fIuser\fP The username on the SSH server to login as. If NULL, the invoking username will be used.
1520 .br
1521 \fIknown_hosts\fP An OpenSSH known hosts formatted file containing public SSH server hashes which may be obtained with \fBpwmd_get_hostkey()\fP or via \fBpwmd_knownhost_cb_t\fP during a connection.
1522 .RE
1523 .PP
1524 \fBReturns:\fP
1525 .RS 4
1526 0 on success or an error code.
1527 .RE
1528 .PP
1529 \fBNote:\fP
1530 .RS 4
1531 When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user.
1532 .RE
1533 .PP
1534 \fBSee also:\fP
1535 .RS 4
1536 \fBpwmd_process()\fP, \fBPWMD_OPTION_IP_VERSION\fP, \fBpwmd_disconnect()\fP, \fBSSH Details\fP
1537 .RE
1538 .PP
1540 .SS "char* pwmd_strdup (const char * str)"
1541 .PP
1542 A wrapper around strdup().
1543 .PP
1544 Like strdup(), but lets libpwmd keep track of the pointer.
1545 .PP
1546 \fBParameters:\fP
1547 .RS 4
1548 \fIstr\fP The string to duplicate.
1549 .RE
1550 .PP
1551 \fBReturns:\fP
1552 .RS 4
1553 A newly allocated character pointer or NULL if there wasn't enough memory.
1554 .RE
1555 .PP
1556 \fBSee also:\fP
1557 .RS 4
1558 strdup(3), \fBpwmd_free()\fP
1559 .RE
1560 .PP
1562 .SS "char* pwmd_strdup_printf (const char * fmt, ...)"
1563 .PP
1564 Duplicate a formatted string.
1565 .PP
1566 Like \fBsprintf(3)\fP but returns an allocated string.
1567 .PP
1568 \fBParameters:\fP
1569 .RS 4
1570 \fIfmt\fP The formatted string and any following arguments.
1571 .RE
1572 .PP
1573 \fBReturns:\fP
1574 .RS 4
1575 A newly allocated character pointer or NULL if there wasn't enough memory.
1576 .RE
1577 .PP
1578 \fBSee also:\fP
1579 .RS 4
1580 \fBpwmd_free()\fP
1581 .RE
1582 .PP
1584 .SS "const char* pwmd_strerror (gpg_error_t code)"
1585 .PP
1586 Return a description of an error code.
1587 .PP
1588 \fBParameters:\fP
1589 .RS 4
1590 \fIcode\fP The error code to describe.
1591 .RE
1592 .PP
1593 \fBReturns:\fP
1594 .RS 4
1595 A character description of the error code.
1596 .RE
1597 .PP
1598 \fBSee also:\fP
1599 .RS 4
1600 \fBpwmd_strerror_r()\fP
1601 .RE
1602 .PP
1604 .SS "int pwmd_strerror_r (gpg_error_t code, char * buf, size_t size)"
1605 .PP
1606 Return a description of an error code (thread-safe).
1607 .PP
1608 This is a thread-safe version of \fBpwmd_strerror()\fP.
1609 .PP
1610 \fBParameters:\fP
1611 .RS 4
1612 \fIcode\fP The error code to describe.
1613 .br
1614 \fIbuf\fP An allocated buffer to hold the error description.
1615 .br
1616 \fIsize\fP The size of the allocated buffer \fIbuf\fP.
1617 .RE
1618 .PP
1619 \fBReturn values:\fP
1620 .RS 4
1621 \fI0\fP Success.
1622 .br
1623 \fIERANGE\fP \fIsize\fP was not large enough to hold the entire description and \fIbuf\fP is set to the truncated error string.
1624 .RE
1625 .PP
1627 .SH "Author"
1628 .PP
1629 Generated automatically by Doxygen for libpwmd from the source code.