1 .TH "libpwmd.h" 3 "Tue Jan 3 2012" "Version 7.0.0" "libpwmd" \" -*- nroff -*-
5 libpwmd.h - an API for accessing pwmd
8 libpwmd is a library making it easy for applications to use the pwmd server\&. Pwmd version 3\&.0 or later is required; either locally or remotely\&.
11 \fBlibpwmd\fP should be thread-safe on a per handle bases\&. Meaning that only one thread should access a \fBpwm_t\fP handle at a time\&.
14 A remote connection to a pwmd server is possible by using an SSH channel to spawn a shell that executes a proxy server to connect 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\&.
16 An unknown servers public key can be added to a known hosts file after user confirmation by setting the callback function \fBpwmd_knownhost_cb_t\fP before connecting to the unknown host\&.
18 On the server side you'll need a proxy server to connect to the real pwmd server\&. Below is an example of an \fBauthorized_keys(5)\fP entry that will do this\&. The \fIpublic_key\fP portion should be the same as the contents of the generated \fBssh-keygen(1)\fP \fIidentity\&.pub\fP file\&. The private key should be passed as the \fIidentity\fP parameter in \fBpwmd_connect()\fP:
22 command='socat UNIX-CONNECT:$HOME/\&.pwmd/socket -' <public_key> \&.\&.\&.
28 Only an SSH identity without a passphrase is supported\&. For now anyway\&. This is a limitation of libssh2 (version 1\&.2\&.8 as of this writing)\&.
33 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\&.
38 X11 port forwarding so a remote pinentry can use the local display\&.
41 .SH "Pinentry Details"
43 \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 (really gpg-agent) use it's pinentry to retrieve a passphrase when needed\&.
45 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 only sent to pwmd in \fBpwmd_open()\fP and only when pinentry use has not been disabled and not over an SSH connnection\&.
47 Some pinentry options may also be specified in the 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\&. Options and values are separated with a '=' on a single line\&. Unrecognized options are ignored\&. Here are the recognized options:
51 \fIPATH\fP The full path to the location of the pinentry binary\&. Only useful for the local pinentry\&.
53 \fIDISPLAY\fP The X11 display to use\&.
55 \fITTYNAME\fP The full path to the tty that pinentry should prompt on\&.
57 \fITTYTYPE\fP The terminal type of the tty which is required if DISPLAY is not set\&.
62 When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user\&.
64 The initial values for the pinentry TTY, TERM and DISPLAY are set during \fBpwmd_new()\fP depending on the current environment\&. They can be reset or changed as needed\&.
66 After establishing an SSH connection, pwmd's pinentry is disabled by passing the '--no-pinentry' option during \fBpwmd_open()\fP since X11 forwarding has not been implemented\&.
71 X11 port forwarding so a remote pinentry can use the local display\&.
82 libpwmd uses libgpg-error for all error codes\&. Error codes can be described by using \fBgpg_strerror()\fP, or the thread-safe \fBgpg_strerror_r()\fP\&.
86 libgpg-error returns an error code as a bitmask of an error source and the error code\&. Determining the error source can help you find where the error occured, beit from \fBpinentry(1)\fP, \fBgpg-agent(1)\fP, \fBlibgcrypt\fP, \fBpwmd(1)\fP or \fBlibpwmd(3)\fP\&. pwmd uses the \fBGPG_ERR_SOURCE_USER_1\fP error source and libpwmd uses \fBGPG_ERR_SOURCE_USER_2\fP\&. To find the error source of an error code the \fBgpg-error(1)\fP command line utility may be of use\&. Also see the \fBlibgpg-error\fP documentation for error code manipulation\&.
97 .RI "#define \fBLIBPWMD_API\fP"
100 .RI "#define \fBGPG_ERR_SOURCE_DEFAULT\fP GPG_ERR_SOURCE_USER_2"
103 .RI "#define \fBLIBPWMD_VERSION\fP 0x700"
106 .RI "#define \fBLIBPWMD_VERSION_MAJOR\fP 7"
109 .RI "#define \fBLIBPWMD_VERSION_MINOR\fP 0"
112 .RI "#define \fBLIBPWMD_VERSION_PATCH\fP 0"
115 .RI "#define \fBLIBPWMD_VERSION_STR\fP '7\&.0\&.0-dev'"
118 .RI "#define \fBPWMD_FEATURE_PINENTRY\fP"
121 .RI "#define \fBPWMD_FEATURE_CRACK\fP"
124 .RI "#define \fBPWMD_FEATURE_SSH\fP"
131 .RI "typedef struct pwm_s \fBpwm_t\fP"
134 .RI "typedef gpg_error_t(* \fBpwmd_status_cb_t\fP )(void *user, const char *line)"
137 .RI "typedef gpg_error_t(* \fBpwmd_inquire_cb_t\fP )(void *user, const char *keyword, gpg_error_t rc, char **data, size_t *len)"
140 .RI "typedef gpg_error_t(* \fBpwmd_knownhost_cb_t\fP )(void *user, const char *host, const char *hostkey, size_t len)"
147 .RI "enum \fBpwmd_socket_t\fP { \fBPWMD_SOCKET_LOCAL\fP, \fBPWMD_SOCKET_SSH\fP }"
150 .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_SAVE_FAILED\fP, \fBPWMD_PINENTRY_CONFIRM\fP, \fBPWMD_PINENTRY_USER\fP, \fBPWMD_PINENTRY_CLOSE\fP }"
153 .RI "enum \fBpwmd_option_t\fP { \fBPWMD_OPTION_PINENTRY_PATH\fP, \fBPWMD_OPTION_PINENTRY_TTY\fP, \fBPWMD_OPTION_PINENTRY_TERM\fP, \fBPWMD_OPTION_PINENTRY_DISPLAY\fP, \fBPWMD_OPTION_PINENTRY_ERROR\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_PINENTRY_TRIES\fP, \fBPWMD_OPTION_STATUS_CB\fP, \fBPWMD_OPTION_STATUS_DATA\fP, \fBPWMD_OPTION_KNOWNHOST_CB\fP, \fBPWMD_OPTION_KNOWNHOST_DATA\fP, \fBPWMD_OPTION_INQUIRE_TOTAL\fP, \fBPWMD_OPTION_LOCK_ON_OPEN\fP, \fBPWMD_OPTION_SSH_AGENT\fP, \fBPWMD_OPTION_NO_PINENTRY\fP, \fBPWMD_OPTION_LOCAL_PINENTRY\fP, \fBPWMD_OPTION_OVERRIDE_INQUIRE\fP, \fBPWMD_OPTION_SSH_TIMEOUT\fP, \fBPWMD_OPTION_SSH_KEEPALIVE\fP }"
160 .RI "LIBPWMD_API const char * \fBpwmd_version\fP ()"
163 .RI "LIBPWMD_API unsigned int \fBpwmd_features\fP ()"
166 .RI "LIBPWMD_API gpg_error_t \fBpwmd_init\fP (void)"
169 .RI "LIBPWMD_API gpg_error_t \fBpwmd_new\fP (const char *name, \fBpwm_t\fP **pwm)"
172 .RI "LIBPWMD_API gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *url, const char *identity, const char *knownhosts)"
175 .RI "LIBPWMD_API gpg_error_t \fBpwmd_setopt\fP (\fBpwm_t\fP *pwm, \fBpwmd_option_t\fP opt,\&.\&.\&.)"
178 .RI "LIBPWMD_API gpg_error_t \fBpwmd_getpin\fP (\fBpwm_t\fP *pwm, const char *filename, char **result, size_t *len, \fBpwmd_pinentry_t\fP which)"
181 .RI "LIBPWMD_API gpg_error_t \fBpwmd_password\fP (\fBpwm_t\fP *pwm, const char *keyword, char **data, size_t *size)"
184 .RI "LIBPWMD_API gpg_error_t \fBpwmd_open\fP (\fBpwm_t\fP *pwm, const char *filename, \fBpwmd_inquire_cb_t\fP callback, void *data)"
187 .RI "LIBPWMD_API gpg_error_t \fBpwmd_process\fP (\fBpwm_t\fP *pwm)"
190 .RI "LIBPWMD_API gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm, const char *args, \fBpwmd_inquire_cb_t\fP callback, void *user)"
193 .RI "LIBPWMD_API gpg_error_t \fBpwmd_command\fP (\fBpwm_t\fP *pwm, char **result, size_t *len, \fBpwmd_inquire_cb_t\fP callback, void *user, const char *cmd,\&.\&.\&.)"
196 .RI "LIBPWMD_API gpg_error_t \fBpwmd_command_ap\fP (\fBpwm_t\fP *pwm, char **result, size_t *len, \fBpwmd_inquire_cb_t\fP callback, void *user, const char *cmd, va_list ap)"
199 .RI "LIBPWMD_API gpg_error_t \fBpwmd_disconnect\fP (\fBpwm_t\fP *pwm)"
202 .RI "LIBPWMD_API void \fBpwmd_close\fP (\fBpwm_t\fP *pwm)"
205 .RI "LIBPWMD_API gpg_error_t \fBpwmd_socket_type\fP (\fBpwm_t\fP *pwm, \fBpwmd_socket_t\fP *type)"
208 .RI "LIBPWMD_API gpg_error_t \fBpwmd_fd\fP (\fBpwm_t\fP *pwm, int *fd)"
211 .RI "LIBPWMD_API void \fBpwmd_free\fP (void *ptr)"
214 .RI "LIBPWMD_API void * \fBpwmd_malloc\fP (size_t size)"
217 .RI "LIBPWMD_API void * \fBpwmd_calloc\fP (size_t nmemb, size_t size)"
220 .RI "LIBPWMD_API void * \fBpwmd_realloc\fP (void *ptr, size_t size)"
223 .RI "LIBPWMD_API char * \fBpwmd_strdup\fP (const char *str)"
226 .RI "LIBPWMD_API char * \fBpwmd_strdup_printf\fP (const char *fmt,\&.\&.\&.)"
229 .SH "Constant Details"
231 .SS "#define \fBLIBPWMD_VERSION\fP 0x700"
233 Version information\&. The version of this library\&.
234 .SS "#define \fBLIBPWMD_VERSION_MAJOR\fP 7"
236 Version information\&. The major release number of this library\&.
237 .SS "#define \fBLIBPWMD_VERSION_MINOR\fP 0"
239 Version information\&. The minor release number of this library\&.
240 .SS "#define \fBLIBPWMD_VERSION_PATCH\fP 0"
242 Version information\&. The patch level of this library\&.
243 .SS "#define \fBLIBPWMD_VERSION_STR\fP '7\&.0\&.0-dev'"
245 Version information\&. A string representation of the version of this library\&.
246 .SS "#define \fBPWMD_FEATURE_CRACK\fP"
248 Password quality checking\&. A password quality meter is shown when the pinentry supports it\&.
249 .SS "#define \fBPWMD_FEATURE_PINENTRY\fP"
251 Pinentry support\&. This is for a local or fork()'ed pinentry\&.
252 .SS "#define \fBPWMD_FEATURE_SSH\fP"
254 Remote connections over an SSH channel\&. \fBSee also:\fP
260 .SH "Typedef Details"
264 libpwmd handle\&. When a handle or context is mentioned in this documentation it is a pointer of this type\&. A new handle is created with \fBpwmd_new()\fP\&.
265 .SS "\fBpwmd_inquire_cb_t\fP"
267 Send data to the pwmd server\&. This is a callback function that is used for sending data to the server for commands that need to reply to an INQUIRE server response\&. The reason for this callback is to let the client send as many bytes as it wants rather than the entire data 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\&.
271 \fIuser\fP The user data pointer passed to the libpwmd function specifying this callback\&.
273 \fIkeyword\fP The name of this inquire\&. Could be a command name or some keyword describing what needs to be sent\&. See the pwmd and \fBgpg-agent(1)\fP documentation for details\&.
275 \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\&. This should be checked during each call to this function and should return the same error code when set\&. Its purpose is to let the client clean up before letting the command fail\&.
277 \fIdata\fP The next chunk of data to send or NULL\&.
279 \fIlen\fP The length of \fIdata\fP or 0\&.
284 \fI0\fP There is more data to be sent\&.
286 \fIGPG_ERR_EOF\fP No need to call this function again, the current \fIdata\fP is the last to send\&.
288 \fIcode\fP Any other error code which will cancel the INQUIRE\&.
293 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\&.
297 .SS "\fBpwmd_knownhost_cb_t\fP"
299 Verify a remote SSH connection\&. 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\&.
303 \fIuser\fP User data which was set with \fBPWMD_OPTION_KNOWNHOST_DATA\fP\&.
305 \fIhost\fP The hostname as passed to \fBpwmd_connect()\fP\&.
307 \fIhostkey\fP The raw binary data of the host key\&.
309 \fIlen\fP The length of \fIhostkey\fP\&.
314 \fI0\fP Add the host key to the known hosts file\&.
316 \fIGPG_ERR_NOT_CONFIRMED\fP Do not add the host key and abort the connection\&. This is the recommended error code although any other non-zero return value will also abort the connection\&.
321 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 accepted\&.
330 .SS "\fBpwmd_status_cb_t\fP"
332 Process status messages\&. The value of the option \fBPWMD_OPTION_STATUS_CB\fP which is set with \fBpwmd_setopt()\fP\&.
336 \fIuser\fP A user data pointer which is set with \fBPWMD_OPTION_STATUS_DATA\fP\&.
338 \fIline\fP The status message line received from the server\&.
343 0 on success or an error code which will cause a command to fail\&.
347 .SH "Enumeration Details"
349 .SS "enum \fBpwmd_option_t\fP"
351 libpwmd options\&. Options are set with \fBpwmd_setopt()\fP\&. Some options must be set before a connection is made to have any effect\&.
355 When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user\&.
363 \fB\fIPWMD_OPTION_PINENTRY_PATH \fP\fP
364 A string value which specifies the full path of the \fBpinentry(1)\fP binary\&. The default is specified at compile time\&.
368 This only affects the local pinentry\&.
373 \fBPinentry Details\fP
378 \fB\fIPWMD_OPTION_PINENTRY_TTY \fP\fP
379 A string 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\&.
383 \fBPinentry Details\fP
388 \fB\fIPWMD_OPTION_PINENTRY_TERM \fP\fP
389 A string value which specifies the terminal type (i\&.e\&., vt100) that \fBpinentry(1)\fP will use when no X11 display is available\&.
393 \fBPinentry Details\fP
398 \fB\fIPWMD_OPTION_PINENTRY_DISPLAY \fP\fP
399 A string value which specifies the X11 display that \fBpinentry(1)\fP will use\&. \fBpinentry(1)\fP seems to make DISPLAY have a higher priority than \fBPWMD_OPTION_PINENTRY_TTY\fP\&.
403 X11 port forwarding so a remote pinentry can use the local display\&.
409 \fBPinentry Details\fP
414 \fB\fIPWMD_OPTION_PINENTRY_ERROR \fP\fP
415 A character string that \fBpinentry(1)\fP will use in it's dialog window\&.
417 \fB\fIPWMD_OPTION_PINENTRY_PROMPT \fP\fP
418 A character string that \fBpinentry(1)\fP will use in it's dialog window\&.
420 \fB\fIPWMD_OPTION_PINENTRY_DESC \fP\fP
421 A character string that \fBpinentry(1)\fP will use in it's dialog window\&.
423 \fB\fIPWMD_OPTION_PINENTRY_LC_CTYPE \fP\fP
424 For \fBpinentry(1)\fP localization\&.
426 \fB\fIPWMD_OPTION_PINENTRY_LC_MESSAGES \fP\fP
427 For \fBpinentry(1)\fP localization\&.
429 \fB\fIPWMD_OPTION_PINENTRY_TIMEOUT \fP\fP
430 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\&.
434 This only affects the local pinentry\&.
439 \fB\fIPWMD_OPTION_PINENTRY_TRIES \fP\fP
440 An integer value that specifies the number of times to prompt for a passphrase before returning an error\&.
444 This only affects the local pinentry\&.
449 \fB\fIPWMD_OPTION_STATUS_CB \fP\fP
450 A function of type \fBpwmd_status_cb_t\fP that will process status messages received from the pwmd server\&.
452 \fB\fIPWMD_OPTION_STATUS_DATA \fP\fP
453 A user data pointer which is passed to the status message function \fBPWMD_OPTION_STATUS_CB\fP\&.
455 \fB\fIPWMD_OPTION_KNOWNHOST_CB \fP\fP
456 A function of type \fBpwmd_knownhost_cb_t\fP that will be used to confirm a host key that was not found in the known hosts file\&.
465 \fB\fIPWMD_OPTION_KNOWNHOST_DATA \fP\fP
466 User supplied data which is passed to the known host function \fBPWMD_OPTION_KNOWNHOST_CB\fP\&.
475 \fB\fIPWMD_OPTION_INQUIRE_TOTAL \fP\fP
476 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 every function that uses an \fBpwmd_inquire_cb_t\fP\&.
480 During the INQUIRE, \fBPWMD_OPTION_STATUS_CB\fP is called, when set, after every iteration of the \fBpwmd_inquire_cb_t\fP\&.
482 This is a libpwmd feature\&. pwmd itself does not send XFER status messages during an INQUIRE\&. Status messages can be parsed only when \fBPWMD_OPTION_STATUS_CB\fP is set\&.
487 \fB\fIPWMD_OPTION_LOCK_ON_OPEN \fP\fP
488 When set to 1, lock the file mutex after opening a file as if the LOCK command had been sent\&.
490 \fB\fIPWMD_OPTION_SSH_AGENT \fP\fP
491 Use ssh-agent to retrieve the private key to authenticate when connecting to a remote pwmd server\&.
493 \fB\fIPWMD_OPTION_NO_PINENTRY \fP\fP
494 When 1, disable pinentry use\&. This will prevent both pwmd and libpwmd from using a pinentry program\&.
498 This must be set before calling \fBpwmd_open()\fP\&.
503 \fB\fIPWMD_OPTION_LOCAL_PINENTRY \fP\fP
504 When 1, libpwmd will disable pwmd's pinentry and use it's own fork(2)'ed pinentry\&.
508 This must be set before calling \fBpwmd_open()\fP\&.
513 \fB\fIPWMD_OPTION_OVERRIDE_INQUIRE \fP\fP
514 When set, override libpwmd's handling of server inquires with the PASSPHRASE and NEW_PASSPHRASE keywords\&. This handling is done automatically when \fBPWMD_OPTION_NO_PINENTRY\fP or \fBPWMD_OPTION_LOCAL_PINENTRY\fP is set or when the connection is over an SSH channel\&.
518 \fBSSH Details\fP, \fBPWMD_OPTION_LOCAL_PINENTRY\fP, \fBpwmd_password()\fP
523 X11 port forwarding so a remote pinentry can use the local display\&.
528 \fB\fIPWMD_OPTION_SSH_TIMEOUT \fP\fP
529 An int specifying a timeout in seconds before a blocking ssh function will timeout causing a command to fail\&.
531 \fB\fIPWMD_OPTION_SSH_KEEPALIVE \fP\fP
532 An int specifying an interval in seconds that \fBpwmd_process()\fP will send a keepalive message to the remote SSH server\&.
533 .SS "enum \fBpwmd_pinentry_t\fP"
535 Local pinentry commands and not pwmd pinentry\&. These determine what prompt a local or fork()'ed pinentry uses\&. For use with \fBpwmd_getpin()\fP\&.
540 \fB\fIPWMD_PINENTRY_OPEN \fP\fP
541 When opening a file\&.
543 \fB\fIPWMD_PINENTRY_OPEN_FAILED \fP\fP
544 When opening a file failed\&.
546 \fB\fIPWMD_PINENTRY_SAVE \fP\fP
547 When saving a file\&.
549 \fB\fIPWMD_PINENTRY_SAVE_CONFIRM \fP\fP
550 For passphrase confirmation\&.
552 \fB\fIPWMD_PINENTRY_SAVE_FAILED \fP\fP
553 When saving a file and passphrase confirmation failed\&.
555 \fB\fIPWMD_PINENTRY_CONFIRM \fP\fP
556 For confirmation of a user-defined prompt\&.
558 \fB\fIPWMD_PINENTRY_USER \fP\fP
559 For the default or user defined string set with \fBPWMD_OPTION_PINENTRY_DESC\fP\&.
561 \fB\fIPWMD_PINENTRY_CLOSE \fP\fP
562 To terminate the pinentry process created with \fBpwmd_getpin()\fP\&.
563 .SS "enum \fBpwmd_socket_t\fP"
565 The type of socket a handle is connected to\&. For use with \fBpwmd_socket_type()\fP\&.
570 \fB\fIPWMD_SOCKET_LOCAL \fP\fP
571 A local UNIX domain socket\&.
573 \fB\fIPWMD_SOCKET_SSH \fP\fP
574 An SSH channel over a TCP socket\&.
575 .SH "Function Details"
577 .SS "LIBPWMD_API void* \fBpwmd_calloc\fP (size_tnmemb, size_tsize)"
579 A wrapper around calloc()\&. Like calloc(), but lets libpwmd keep track of the pointer\&.
583 \fInmemb\fP The number of elements to allocate\&.
585 \fIsize\fP The number of bytes to allocate\&.
590 A newly allocated pointer or NULL if there wasn't enough memory\&.
595 calloc(3), \fBpwmd_free()\fP
599 .SS "LIBPWMD_API void \fBpwmd_close\fP (\fBpwm_t\fP *pwm)"
601 Close a handle\&. This will close the connection to a pwmd server and free any resources associated with it\&.
605 \fIpwm\fP A handle\&.
615 \fBpwmd_disconnect()\fP, \fBpwmd_new()\fP
619 .SS "LIBPWMD_API gpg_error_t \fBpwmd_command\fP (\fBpwm_t\fP *pwm, char **result, size_t *len, \fBpwmd_inquire_cb_t\fPcallback, void *user, const char *cmd, \&.\&.\&.)"
621 Send 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\&.
623 For pwmd commands that use an INQUIRE to retrieve data from a client, the \fIcallback\fP parameter must be non-NULL and will be used to send the data to pwmd\&.
627 \fIpwm\fP A handle\&.
629 \fIresult\fP The result of the command when successful which must be freed with \fBpwmd_free()\fP\&.
631 \fIlen\fP The length of \fIresult\fP\&.
633 \fIcallback\fP A callback function to invoke when pwmd inquires data from the client\&.
635 \fIuser\fP User data passed to the \fIcallback\fP function\&.
637 \fIcmd\fP The command to send and any following arguments\&.
642 0 on success or an error code\&.
647 Not all commands return a \fIresult\fP\&.
651 .SS "LIBPWMD_API gpg_error_t \fBpwmd_command_ap\fP (\fBpwm_t\fP *pwm, char **result, size_t *len, \fBpwmd_inquire_cb_t\fPcallback, void *user, const char *cmd, va_listap)"
653 Send a command to the pwmd server\&. Like \fBpwmd_command()\fP but uses an argument pointer instead\&.
657 \fIpwm\fP A handle\&.
659 \fIresult\fP The result of the command when successful which must be freed with \fBpwmd_free()\fP\&.
661 \fIlen\fP The length of \fIresult\fP\&.
663 \fIcallback\fP A callback function to invoke when pwmd inquires data from the client\&.
665 \fIuser\fP User data passed to the \fIcallback\fP function\&.
667 \fIcmd\fP The command to send\&.
669 \fIap\fP The arguments to \fIcmd\fP\&.
674 0 on success or an error code\&.
679 Not all commands return a \fIresult\fP\&.
683 .SS "LIBPWMD_API gpg_error_t \fBpwmd_connect\fP (\fBpwm_t\fP *pwm, const char *url, const char *identity, const char *knownhosts)"
685 Establish a connection to a pwmd server\&. Connects to a pwmd server specified in \fIurl\fP\&. The format of \fIurl\fP is: file:///path/to/socket or ssh[46]://[username@]hostname[:port]
687 If \fIurl\fP is NULL then the default local pwmd socket \fI~/\fP\&.pwmd/socket will be used\&. The \fIidentity\fP and \fIknownhosts\fP parameters are ignored when connecting to a local socket\&.
691 \fIpwm\fP A handle\&.
693 \fIurl\fP The socket to connect to\&.
695 \fIidentity\fP The SSH identity file to use\&. This is the location of the private identity file\&. This parameter is required unless \fBPWMD_OPTION_SSH_AGENT\fP is set\&.
697 \fIknownhosts\fP The SSH knownhosts file to use\&. If NULL, a default of \fI~/\fP\&.ssh/knownhosts will be used\&.
702 0 on success or an error code\&.
707 When the first character of a filename parameter is a tilde (~), it will be expanded to the home directory of the current user\&.
712 \fBPWMD_OPTION_SSH_AGENT\fP, \fBpwmd_socket_type()\fP, \fBpwmd_disconnect()\fP, \fBSSH Details\fP
716 .SS "LIBPWMD_API gpg_error_t \fBpwmd_disconnect\fP (\fBpwm_t\fP *pwm)"
718 Close a connection to the pwmd server\&. This will close the connection but keep any previously set options for the specified handle\&. Calling \fBpwmd_connect()\fP will re-acquire an libassuan context\&.
722 \fIpwm\fP A handle\&.
727 0 on success or an error code\&.
736 .SS "LIBPWMD_API gpg_error_t \fBpwmd_fd\fP (\fBpwm_t\fP *pwm, int *fd)"
738 Get the file descriptor associated with a handle\&. May be useful to determine whether a handle is ready for reading or writing by using select(2) or poll(2)\&.
742 \fIpwm\fP A handle\&.
744 \fIfd\fP Set to the file descriptor associated with \fIpwm\fP\&.
749 0 on success or an error code\&.
753 .SS "LIBPWMD_API unsigned int \fBpwmd_features\fP ()"
755 libpwmd compile time features\&. Useful for clients to determine what features are compiled into libpwmd at runtime\&.
759 A bitmask of features\&.
763 .SS "LIBPWMD_API void \fBpwmd_free\fP (void *ptr)"
765 Free a previously allocated pointer\&. Use this function to free resources allocated by the other libpwmd memory functions\&. Do not use it to free allocations made by other allocators\&.
767 The difference between the standard free() and this function is that this one will zero out the contents of the pointer before freeing it\&.
771 \fIptr\fP The pointer to deallocate\&.
781 \fBpwmd_malloc()\fP, \fBpwmd_calloc()\fP, \fBpwmd_realloc()\fP, \fBpwmd_strdup()\fP, \fBpwmd_command()\fP
785 .SS "LIBPWMD_API gpg_error_t \fBpwmd_getpin\fP (\fBpwm_t\fP *pwm, const char *filename, char **result, size_t *len, \fBpwmd_pinentry_t\fPwhich)"
787 Launch a local pinentry\&. Does not send any command to the pwmd server\&. This maybe useful if a passphrase is needed while opening a file over a remote connection and during an \fBpwmd_open()\fP server inquire\&.
789 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_DESC\fP\&.
793 \fIpwm\fP A handle\&.
795 \fIfilename\fP The filename to use in the pinentry dialog strings\&.
797 \fIresult\fP The entered value in the pinentry dialog which should be freed with \fBpwmd_free()\fP\&.
799 \fIlen\fP The length of \fIresult\fP\&.
801 \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_USER\fP should be used\&. \fBPWMD_PINENTRY_CLOSE\fP should be used to terminate the pinentry process when the pinentry is no longer needed\&.
806 0 on success or an error\&.
811 \fBpwmd_password()\fP
815 .SS "LIBPWMD_API gpg_error_t \fBpwmd_init\fP (void)"
817 Initialize the library\&. 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\&.
821 0 on success or an error code\&.
825 .SS "LIBPWMD_API void* \fBpwmd_malloc\fP (size_tsize)"
827 A wrapper around malloc\&. Like malloc(), but lets libpwmd keep track of the pointer\&.
831 \fIsize\fP The number of bytes to allocate\&.
836 A newly allocated pointer or NULL if there wasn't enough memory\&.
841 malloc(3), \fBpwmd_free()\fP
845 .SS "LIBPWMD_API gpg_error_t \fBpwmd_new\fP (const char *name, \fBpwm_t\fP **pwm)"
847 Creates a new handle\&. Creates a new handle for use with the other functions\&.
851 \fIname\fP If not NULL, the name of the application\&. The application name is sent to the pwmd server after successfully connecting and is used in pwmd logging\&.
853 \fIpwm\fP A new handle for use with the other functions\&.
858 0 on success or an error code\&.
862 .SS "LIBPWMD_API gpg_error_t \fBpwmd_open\fP (\fBpwm_t\fP *pwm, const char *filename, \fBpwmd_inquire_cb_t\fPcallback, void *data)"
864 Open a file on the pwmd server\&. This will send the OPEN command to the server\&.
866 The inquire \fIcallback\fP function should be used when \fBPWMD_OPTION_NO_PINENTRY\fP is set and is used to send the passphrase when needed\&.
870 \fIpwm\fP A handle\&.
872 \fIfilename\fP The filename to open\&. The \fIfilename\fP is not a full path but the data filename only\&.
874 \fIcallback\fP A callback function to invoke when pwmd inquires data from the client\&.
876 \fIdata\fP User data passed to the \fIcallback\fP function\&.
881 0 on success or an error code\&.
886 \fBPinentry Details\fP, \fBpwmd_password()\fP
890 .SS "LIBPWMD_API gpg_error_t \fBpwmd_password\fP (\fBpwm_t\fP *pwm, const char *keyword, char **data, size_t *size)"
892 Obtain a passphrase from a local pinentry\&. This is the same function that libpwmd uses during an inquire when using the local pinentry and the inquire keyword is either PASSPHRASE or NEW_PASSPHRASE\&. Provided for convenience since it sets proper pinentry strings and handles new passphrase confirmation\&.
896 \fIpwm\fP A handle\&.
898 \fIkeyword\fP The keyword to determine pinentry strings\&. Usually PASSPHRASE or NEW_PASSPHRASE\&.
900 \fIdata\fP The obtained passphrase which should be freed with \fBpwmd_free()\fP\&.
902 \fIsize\fP The length of \fIdata\fP\&.
907 0 on success or an error\&.
912 It is an error for \fIsize\fP to be zero when inquiring a \fIkeyword\fP of PASSPHRASE\&. In this case GPG_ERR_CANCELED will be returned\&.
916 .SS "LIBPWMD_API gpg_error_t \fBpwmd_process\fP (\fBpwm_t\fP *pwm)"
918 Check for socket activity\&. This function should be called periodically to check for any pending status messages sent from the server and when \fInot\fP in a command\&.
922 \fIpwm\fP A handle\&.
927 0 on success or an error code\&.
932 This function makes use of \fBpwmd_status_cb_t\fP\&.
936 .SS "LIBPWMD_API void* \fBpwmd_realloc\fP (void *ptr, size_tsize)"
938 A wrapper around realloc()\&. Like realloc(), but lets libpwmd keep track of the pointer\&.
942 \fIptr\fP The pointer to reallocate\&.
944 \fIsize\fP The new number of bytes to allocate\&.
949 A newly allocated pointer or NULL if there wasn't enough memory\&.
954 realloc(3), \fBpwmd_free()\fP
958 .SS "LIBPWMD_API gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm, const char *args, \fBpwmd_inquire_cb_t\fPcallback, void *user)"
960 Save a file on the pwmd server\&. This will send the SAVE command and write any changes to the document to disk\&.
962 The inquire \fIcallback\fP function should be used when \fBPWMD_OPTION_NO_PINENTRY\fP is set or when a SAVE option specified in \fIargs\fP requires more data\&.
966 \fIpwm\fP A handle\&.
968 \fIargs\fP Any SAVE protocol command options or NULL\&.
970 \fIcallback\fP A callback function to invoke when pwmd inquires data from the client\&.
972 \fIuser\fP User data passed to the \fIcallback\fP function\&.
977 0 on success or an error code\&.
982 \fBpwmd_command()\fP, \fBPinentry Details\fP, \fBSSH Details\fP
986 .SS "LIBPWMD_API gpg_error_t \fBpwmd_setopt\fP (\fBpwm_t\fP *pwm, \fBpwmd_option_t\fPopt, \&.\&.\&.)"
988 Set handle options\&. See \fBpwmd_option_t\fP for option specific details\&.
992 \fIpwm\fP A handle\&.
994 \fIopt\fP The option and following option value\&.
999 0 on success or an error code\&.
1003 .SS "LIBPWMD_API gpg_error_t \fBpwmd_socket_type\fP (\fBpwm_t\fP *pwm, \fBpwmd_socket_t\fP *type)"
1005 The type of connection a handle has\&. Useful when you want to know what kind of connection a handle has\&.
1009 \fIpwm\fP A handle\&.
1011 \fItype\fP The type of socket\&.
1016 0 on success or an error code\&.
1025 .SS "LIBPWMD_API char* \fBpwmd_strdup\fP (const char *str)"
1027 A wrapper around strdup()\&. Like strdup(), but lets libpwmd keep track of the pointer\&.
1031 \fIstr\fP The string to duplicate\&.
1036 A newly allocated character pointer or NULL if there wasn't enough memory\&.
1041 strdup(3), \fBpwmd_free()\fP
1045 .SS "LIBPWMD_API char* \fBpwmd_strdup_printf\fP (const char *fmt, \&.\&.\&.)"
1047 Duplicate a formatted string\&. Like \fBasprintf(3)\fP, but lets libpwmd keep track of the pointer\&.
1051 \fIfmt\fP The formatted string and any following arguments\&.
1056 A newly allocated character pointer or NULL if there wasn't enough memory\&.
1065 .SS "LIBPWMD_API const char* \fBpwmd_version\fP ()"
1067 Returns this version of libpwmd\&. As a string\&.
1077 Generated automatically by Doxygen for libpwmd from the source code\&.