2 Copyright (C) 2006-2016 Ben Kibbey <bjk@luxsci.net>
4 This file is part of libpwmd.
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Lesser General Public
8 License as published by the Free Software Foundation; either
9 version 2.1 of the License, or (at your option) any later version.
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Lesser General Public License for more details.
16 You should have received a copy of the GNU Lesser General Public
17 License along with this library; if not, write to the Free Software
18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
21 /*! \headerfile libpwmd.h
23 * libpwmd is a library making it easy for applications to use the pwmd server.
24 * Pwmd version 3.1 or later is required; either locally or remotely.
27 /*! \section threads Threads
29 * \ref libpwmd should be thread-safe on a per handle bases. Meaning that only
30 * one thread should access a \ref pwm_t handle at a time.
33 /*! \section remote Remote Connection Details
35 * There are two methods of connecting to a remote pwmd server: over SSH and
38 * Connections over SSH are done by creating an SSH channel to spawn a shell
39 * that executes a proxy server to connect to the pwmd local Unix Domain
40 * Socket. Authentication is done by using SSH public key (see \ref
41 * ssh-keygen(1)) authentication and verifying the host key against a local
42 * OpenSSH known hosts formatted file. A passphrase protected private SSH key
43 * is supported when \ref PWMD_OPTION_SSH_NEEDS_PASSPHRASE is set.
45 * An unknown servers public key can be added to a known hosts file after user
46 * confirmation by setting the callback function \ref pwmd_knownhost_cb_t
47 * before connecting to the unknown host.
49 * On the server side you'll need a proxy server to connect to the pwmd server.
50 * Below is an example of an \ref authorized_keys(5) entry that will do this.
51 * The \a public_key portion should be the same as the contents of the \ref
52 * ssh-keygen(1) \a identity.pub file generated on the client machine. The
53 * private key should be passed as the \a identity parameter to \ref
57 * command="socat UNIX-CONNECT:$HOME/.pwmd/socket -" <public_key> ...
60 * Pwmd itself can accept TLS connections so no proxy program is needed as is
61 * when using SSH. Like SSH connections, TLS connections are created with \ref
62 * pwmd_connect(). You will need to generate a client key and X509 certificate
63 * and then sign it with the same certificate authority (CA) that the pwmd
64 * server certificate was signed with.
66 * Certificates are similar to SSH public and private keys but a little harder
67 * to setup correctly. See the \ref certtool(1) (recommended) and \ref
68 * openssl(1) manual pages for details.
71 /*! \section pinentry Pinentry Details
73 * \ref pinentry(1) is a program that prompts the user for input which is
74 * normally a passphrase or a confirmation. libpwmd can use this program either
75 * locally (X11 forwarding is not yet supported) or have the pwmd server (read:
76 * \ref gpg-agent(1)) call pinentry to retrieve a passphrase when needed.
78 * There are a few options that tell pinentry how and where to prompt for a
79 * needed passphrase. See the \ref pwmd_option_t section for details. These
80 * options are sent to pwmd during \ref pwmd_open(), \ref pwmd_save() and \ref
81 * pwmd_passwd() only when pinentry use has not been disabled (\ref
82 * PWMD_OPTION_NO_PINENTRY) and when not over a remote connection.
84 * Some pinentry options may also be specified in the local configuration file
85 * \a "~/.config/libpwmd.conf".
89 * \note The initial values for the pinentry TTY, TERM and DISPLAY are set
90 * during \ref pwmd_new() depending on the current environment. They are then
91 * updated to the values specified in \a ~/.config/libpwmd.conf. They can then
92 * be reset or changed as needed by using \ref pwmd_setopt().
94 * \note After establishing a remote connection, pwmd's pinentry is disabled by
95 * sending the pwmd option \a "disable-pinentry" during \ref pwmd_open(). A
96 * local pinentry will be used instead.
98 * \see \ref remote, \ref configuration
101 /*! \section configuration Configuration File
103 * Initial values overriding libpwmd defaults for a handle may be specified in
104 * the configuration file \a ~/.config/libpwmd.conf. This file is read only
105 * once during \ref pwmd_new(). Option values may be updated by setting the
106 * associated option with \ref pwmd_setopt(). Blank lines and lines beginning
107 * with a '#' are ignored as are unrecognized options. See the documentation
108 * for each option for its' value type. Valid options are:
111 * Same as \ref PWMD_OPTION_PINENTRY_PATH.
113 * \par pinentry-display
114 * Same as \ref PWMD_OPTION_PINENTRY_DISPLAY.
116 * \par pinentry-ttyname
117 * Same as \ref PWMD_OPTION_PINENTRY_TTY.
119 * \par pinentry-ttytype
120 * Same as \ref PWMD_OPTION_PINENTRY_TERM.
122 * \par pinentry-lc-messages
123 * Same as \ref PWMD_OPTION_PINENTRY_LC_MESSAGES.
125 * \par pinentry-lc-ctype
126 * Same as \ref PWMD_OPTION_PINENTRY_LC_CTYPE.
128 * \par pinentry-timeout
129 * Same as \ref PWMD_OPTION_PINENTRY_TIMEOUT.
131 * \par pinentry-tries
132 * Same as \ref PWMD_OPTION_PINENTRY_TRIES.
135 * Same as \ref PWMD_OPTION_NO_PINENTRY.
137 * \par local-pinentry
138 * Same as \ref PWMD_OPTION_LOCAL_PINENTRY.
141 * Same as \ref PWMD_OPTION_SSH_AGENT.
144 * Same as \ref PWMD_OPTION_TLS_VERIFY.
147 * Same as \ref PWMD_OPTION_TLS_PRIORITY.
149 * \par socket-timeout
150 * Same as \ref PWMD_OPTION_SOCKET_TIMEOUT.
153 * Same as \ref PWMD_OPTION_LOCK_ON_OPEN.
156 * Path to file containing additional libpwmd.conf settings.
161 * libpwmd uses libgpg-error for all error codes. Error codes can be described
162 * by using \ref gpg_strerror(), or the thread-safe \ref gpg_strerror_r().
164 * \note libgpg-error returns an error code as a bitmask of an error source and
165 * the error code. Determining the error source can help you determine where
166 * the error occurred, be it from \ref pinentry(1), \ref gpg-agent(1), \ref
167 * libgcrypt, \ref pwmd(1) or \ref libpwmd(3). pwmd uses the \ref
168 * GPG_ERR_SOURCE_USER_1 error source and libpwmd uses \ref
169 * GPG_ERR_SOURCE_USER_2. To view the error source and description of an error
170 * code the \ref gpg-error(1) command line utility may be of use. Also see the
171 * \ref libgpg-error documentation for error code manipulation.
182 #ifdef GPG_ERR_SOURCE_DEFAULT
183 #error "GPG_ERR_SOURCE_DEFAULT already defined."
185 #define GPG_ERR_SOURCE_DEFAULT GPG_ERR_SOURCE_USER_2
187 #include <gpg-error.h>
195 /*! \def LIBPWMD_VERSION
196 * \brief Version information.
198 * The version of this library.
200 #define LIBPWMD_VERSION 0x@VER_MAJOR_HEX@@VER_MINOR_HEX@@VER_PATCH_HEX@
203 /*! \def LIBPWMD_VERSION_MAJOR
204 * \brief Version information.
206 * The major release number of this library.
208 #define LIBPWMD_VERSION_MAJOR @VER_MAJOR@
211 /*! \def LIBPWMD_VERSION_MINOR
212 * \brief Version information.
214 * The minor release number of this library.
216 #define LIBPWMD_VERSION_MINOR @VER_MINOR@
219 /*! \def LIBPWMD_VERSION_PATCH
220 * \brief Version information.
222 * The patch level of this library.
224 #define LIBPWMD_VERSION_PATCH @VER_PATCH@
227 /*! \def LIBPWMD_VERSION_STR
228 * \brief Version information.
230 * A string representation of the version of this library.
232 #define LIBPWMD_VERSION_STR @VER_STRING@
235 /*! \brief Returns this version of libpwmd.
240 LIBPWMD_API
const char *pwmd_version ();
245 * \brief A libpwmd handle.
247 * When a pwmd handle or context is mentioned in this documentation it
248 * is a pointer of this type. A new handle is created with \ref
251 typedef struct pwm_s pwm_t
;
254 /*! \typedef pwmd_socket_t
255 * \brief The type of socket a handle is connected to.
257 * For use with \ref pwmd_socket_type().
261 /*! A local UNIX domain socket. */
264 /*! An SSH channel over a TCP socket. */
267 /*! A TLS connection over a TCP socket. */
270 /*! A socket set with pwmd_connect_fd(). */
275 /*! \typedef pwmd_pinentry_t
276 * \brief Local pinentry commands and not pwmd pinentry.
278 * These determine what prompt a local pinentry uses. For use with \ref
283 /*! When opening a file. */
286 /*! When opening a file failed due to a bad passphrase. */
287 PWMD_PINENTRY_OPEN_FAILED
,
289 /*! When saving a file. */
292 /*! For passphrase confirmation. */
293 PWMD_PINENTRY_SAVE_CONFIRM
,
295 /*! When saving a file and passphrase confirmation failed. */
296 PWMD_PINENTRY_SAVE_FAILED
,
298 /*! For confirmation of a user-defined prompt. */
299 PWMD_PINENTRY_CONFIRM
,
301 /*! For the default or user defined string set with \ref
302 * PWMD_OPTION_PINENTRY_DESC. */
305 /*! To terminate the pinentry process created with \ref pwmd_getpin(). */
310 /*! \typedef pwmd_read_cb_t
311 * \brief Custom socket read callback function.
313 * Use this function to override the libpwmd function used for reading from a
314 * socket. Set with \ref pwmd_setopt().
316 * \param user A user data pointer which is set with \ref
317 * PWMD_OPTION_READ_CB_DATA.
318 * \param fd The file descriptor to read from.
319 * \param data The buffer to store the read data to.
320 * \param len The size of the data buffer.
321 * \returns The amount of bytes read.
322 * \see \ref pwmd_connect_fd()
324 typedef ssize_t (*pwmd_read_cb_t
) (void *user
, int fd
, void *data
, size_t len
);
327 /*! \typedef pwmd_write_cb_t
328 * \brief Custom socket write callback function.
330 * Use this function to override the libpwmd function used for writing to a
331 * socket. Set with \ref pwmd_setopt().
333 * \param user A user data pointer which is set with \ref
334 * PWMD_OPTION_WRITE_CB_DATA.
335 * \param fd The file descriptor to write to.
336 * \param data The data to write.
337 * \param len The amount of data bytes to write.
338 * \returns The amount of bytes written.
339 * \see \ref pwmd_connect_fd()
341 typedef ssize_t (*pwmd_write_cb_t
) (void *user
, int fd
, const void *data
,
345 /*! \typedef pwmd_status_cb_t
346 * \brief Process status messages.
348 * The value of the option \ref PWMD_OPTION_STATUS_CB which is set with \ref
351 * \param user A user data pointer which is set with \ref
352 * PWMD_OPTION_STATUS_DATA.
353 * \param line The status message line received from the server.
354 * \return 0 on success or an error code which will cause a command to fail.
356 typedef gpg_error_t (*pwmd_status_cb_t
) (void *user
, const char *line
);
359 /*! \typedef pwmd_inquire_cb_t
360 * \brief Send data to the pwmd server.
362 * This is a callback function that is used for sending data to the server for
363 * commands that need to reply to an INQUIRE server response. The reason for
364 * this callback is to let the client send as many bytes as it wants rather
365 * than the entire data at once. It gets called during an internal \ref
366 * assuan_transact() from an internal inquire callback function which in turn
367 * calls this function by looping over its return value.
369 * \param user The user data pointer passed to the libpwmd function specifying
371 * \param keyword The name of this inquire. Could be a command name or some
372 * keyword describing what needs to be sent. See the pwmd and \ref
373 * gpg-agent(1) documentation for details.
374 * \param rc The result of the last internal call to \ref assuan_send_data()
375 * which did the sending of the data to the pwmd server. On the first call to
376 * this callback it's value will always be 0 since no data has been sent yet.
377 * This should be checked during each call to this function and should return
378 * the same error code when set. Its purpose is to let the client clean up
379 * before letting the command fail.
380 * \param[out] data The next chunk of data to send or NULL.
381 * \param[out] len The length of \a data or 0.
383 * \retval 0 There is more data to be sent.
384 * \retval GPG_ERR_EOF No need to call this function again, the current
385 * \a data is the last to send.
386 * \retval code Any other error code which will cancel the INQUIRE.
388 * \note The sent data is processed line-per-line. The line is either newline
389 * terminated or is buffered until ASSUAN_LINELENGTH bytes have been
390 * allocated. Any remaining bytes are sent after the INQUIRE has finished.
392 typedef gpg_error_t (*pwmd_inquire_cb_t
) (void *user
, const char *keyword
,
393 gpg_error_t rc
, char **data
,
397 /*! \typedef pwmd_knownhost_cb_t
398 * \brief Verify a remote SSH connection.
400 * When the current SSH connections host key was not found in the known hosts
401 * file, then this callback function can be used to confirm the addition of the
402 * new host key to the known_hosts file. When \ref PWMD_OPTION_KNOWNHOST_CB is
403 * not set then the default callback function will be used.
405 * \param user User data which was set with \ref PWMD_OPTION_KNOWNHOST_DATA.
406 * \param host The hostname as passed to \ref pwmd_connect().
407 * \param hostkey The raw binary data of the host key.
408 * \param len The length of \a hostkey.
409 * \retval 0 Add the host key to the known hosts file.
410 * \retval GPG_ERR_NOT_CONFIRMED Do not add the host key and abort the
411 * connection. This is the recommended error code although any other non-zero
412 * return value will also abort the connection.
414 * \note If the known hosts file cannot be modified do to filesystem
415 * restrictions when adding the new host key, no error is returned. Instead,
416 * the host key is added to the current connections host key cache and the
417 * connection is accepted.
421 typedef gpg_error_t (*pwmd_knownhost_cb_t
) (void *user
, const char *host
,
426 /*! \enum pwmd_option_t
427 * \brief libpwmd options.
429 * Options are set with \ref pwmd_setopt(). Some options must be set before a
430 * connection is made to have any effect.
434 /* Note to self: dont change the order or insert. Only append. */
437 /*! A string value which specifies the full path of the \ref pinentry(1)
438 * binary. The default is specified at compile time.
440 * \note This only affects the local pinentry.
443 PWMD_OPTION_PINENTRY_PATH
,
446 /*! A string value which specifies the full path to the TTY that \ref
447 * pinentry(1) will use to prompt on. When set and no DISPLAY is
448 * available, \ref PWMD_OPTION_PINENTRY_TERM must also be set.
452 PWMD_OPTION_PINENTRY_TTY
,
455 /*! A string value which specifies the terminal type (i.e., vt100) that
456 * \ref pinentry(1) will use when no X11 display is available.
460 PWMD_OPTION_PINENTRY_TERM
,
463 /*! A string value which specifies the X11 display that \ref pinentry(1)
464 * will use. \ref pinentry(1) seems to make DISPLAY have a higher priority
465 * than \ref PWMD_OPTION_PINENTRY_TTY.
469 PWMD_OPTION_PINENTRY_DISPLAY
,
472 /*! A character string that \ref pinentry(1) will use in it's dialog
475 PWMD_OPTION_PINENTRY_ERROR
,
478 /*! \copydoc PWMD_OPTION_PINENTRY_ERROR */
479 PWMD_OPTION_PINENTRY_PROMPT
,
482 /*! \copydoc PWMD_OPTION_PINENTRY_ERROR */
483 PWMD_OPTION_PINENTRY_DESC
,
486 /*! For \ref pinentry(1) localization. */
487 PWMD_OPTION_PINENTRY_LC_CTYPE
,
490 /*! \copydoc PWMD_OPTION_PINENTRY_LC_CTYPE */
491 PWMD_OPTION_PINENTRY_LC_MESSAGES
,
494 /*! An integer value that specifies the number of seconds \ref pinentry(1)
495 * will wait for input before timing out and aborting the current command.
496 * If 0, then no timeout will be used. The default is 30.
498 * \note This only affects the local pinentry.
500 PWMD_OPTION_PINENTRY_TIMEOUT
,
503 /*! An integer value that specifies the number of times to prompt for a
504 * passphrase before returning an error.
506 * \note This only affects the local pinentry.
508 PWMD_OPTION_PINENTRY_TRIES
,
511 /*! A function of type \ref pwmd_status_cb_t that will process status
512 * messages received from the pwmd server.
514 PWMD_OPTION_STATUS_CB
,
517 /*! A user data pointer which is passed to the status message function
518 * \ref PWMD_OPTION_STATUS_CB. */
519 PWMD_OPTION_STATUS_DATA
,
522 /*! A function of type \ref pwmd_knownhost_cb_t that will be used to
523 * confirm a host key that was not found in the known hosts file.
527 PWMD_OPTION_KNOWNHOST_CB
,
530 /*! User supplied data which is passed to the known host function \ref
531 * PWMD_OPTION_KNOWNHOST_CB.
535 PWMD_OPTION_KNOWNHOST_DATA
,
538 /*! When the total number of bytes to be sent via an INQUIRE is known,
539 * this should be set so XFER status messages can be parsed correctly.
540 * When not known or unset, 0 is used as the total argument to the XFER
541 * status message. This option should be reset in every function that
542 * uses an \ref pwmd_inquire_cb_t.
544 * \note During the INQUIRE, \ref PWMD_OPTION_STATUS_CB is called, when
545 * set, after every iteration of the \ref pwmd_inquire_cb_t.
547 * \note This is a libpwmd feature. pwmd itself does not send XFER status
548 * messages during an INQUIRE. Status messages can be parsed only when
549 * \ref PWMD_OPTION_STATUS_CB is set.
551 PWMD_OPTION_INQUIRE_TOTAL
,
554 /*! When set to 1, lock the file mutex during \ref pwmd_open() as if the LOCK
555 * command had been sent.
557 PWMD_OPTION_LOCK_ON_OPEN
,
560 /*! Use ssh-agent to retrieve the private key to authenticate with when
561 * connecting to a remote pwmd server. */
562 PWMD_OPTION_SSH_AGENT
,
565 /*! When 1, disable pinentry use. This will prevent both pwmd and libpwmd
566 * from using a pinentry program and will prompt from the terminal if
569 * \note This must be set before calling \ref pwmd_open().
570 * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_LOCAL_PINENTRY
572 PWMD_OPTION_NO_PINENTRY
,
575 /*! When 1, libpwmd will disable pwmd's pinentry and use it's own
576 * pinentry. This option is set by default when the connection is a remote
579 * \note This must be set before calling \ref pwmd_open().
581 PWMD_OPTION_LOCAL_PINENTRY
,
584 /*! When set, override libpwmd's internal handling of server inquires with
585 * the PASSPHRASE, NEW_PASSPHRASE and SIGN_PASSPHRASE keywords. Handling of
586 * these keywords is done automatically when \ref PWMD_OPTION_NO_PINENTRY or
587 * \ref PWMD_OPTION_LOCAL_PINENTRY is set or when the connection is a remote
590 * \see \ref remote, \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_password()
592 PWMD_OPTION_OVERRIDE_INQUIRE
,
595 /*! An int specifying a timeout in seconds before a TCP connection or
596 * data transfer function will timeout causing a connection or command to
597 * fail. This option can be specified both before and after a connection
598 * has been established. When 0, no timeout is used.
600 PWMD_OPTION_SOCKET_TIMEOUT
,
603 /*! An int specifying whether to enable TLS hostname verification against the
604 * server certificate chain. Default is 0 or disabled. */
605 PWMD_OPTION_TLS_VERIFY
,
608 /*! Set to 1 to not modify the signal handler to ignore SIGPIPE. The default
609 * is 0, or to ignore this signal. */
613 /*! Get the version of the pwmd server as an unsigned integer. This is a
614 * read-only setting and is only available after connecting. */
615 PWMD_OPTION_SERVER_VERSION
,
618 /*! The SSH identity file requires a passphrase. When set, prompt for the
619 * passphrase after connecting. Note that only libssh2 built with OpenSSL
620 * supports this feature as of libssh2-1.7.0. */
621 PWMD_OPTION_SSH_NEEDS_PASSPHRASE
,
624 /*! Set SSH private identity passphrase. When set there is no need to set
625 * \ref PWMD_OPTION_SSH_NEEDS_PASSPHRASE. The value of this option is
626 * duplicated then freed after the call to \ref pwmd_connect(). Note that
627 * only libssh2 built with OpenSSL supports this feature as of
629 PWMD_OPTION_SSH_PASSPHRASE
,
632 /*! The TLS cipher priority string to use for a TLS connection. The default
633 * is SECURE256:SECURE192:SECURE128:-VERS-SSL3.0:-VERS-TLS1.0. */
634 PWMD_OPTION_TLS_PRIORITY
,
636 /*! The callback function of type \ref pwmd_read_cb_t to use to read from a
640 /*! The data to pass to the custom read function \ref pwmd_read_cb_t. */
641 PWMD_OPTION_READ_CB_DATA
,
643 /*! The callback function of type \ref pwmd_write_cb_t to use to write to a
645 PWMD_OPTION_WRITE_CB
,
647 /*! The data to pass to the custom write function \ref pwmd_write_cb_t. */
648 PWMD_OPTION_WRITE_CB_DATA
,
652 /*! \def PWMD_FEATURE_PINENTRY
654 * \brief Pinentry support.
656 * This is for a local or fork()'ed pinentry.
658 #define PWMD_FEATURE_PINENTRY 0x0001
660 /*! \def PWMD_FEATURE_QUALITY
662 * \brief Password quality checking.
664 * A password quality meter is shown when the pinentry supports it.
666 #define PWMD_FEATURE_QUALITY 0x0002
668 /*! \def PWMD_FEATURE_SSH
670 * \brief Remote connections over an SSH channel.
674 #define PWMD_FEATURE_SSH 0x0004
676 /*! \def PWMD_FEATURE_GNUTLS
678 * \brief Remote connections over TLS.
682 #define PWMD_FEATURE_GNUTLS 0x0008
685 /*! \brief libpwmd compile time features.
687 * Useful for clients to determine what features are compiled into libpwmd at
690 * \return A bitmask of features.
692 LIBPWMD_API
unsigned int pwmd_features ();
695 /*! \brief Initialize the library.
697 * This function must be the first function called in the library before any
698 * others. It sets up the memory allocators and internationalization among
701 * \return 0 on success or an error code.
703 LIBPWMD_API gpg_error_t
pwmd_init (void);
705 /*! \brief Deinitialize the library.
707 * This function is mainly for cleaning up other libraries that
708 * libpwmd links with to prevent memory and other leaks showing up in
709 * a debugger. It should be the final libpwmd function call before
712 LIBPWMD_API
void pwmd_deinit (void);
715 /*! \brief Creates a new handle.
717 * Creates a new handle or context for use with the other functions.
719 * \param name If not NULL, the name of the application. The application name
720 * is sent to the pwmd server after successfully connecting and is used in
722 * \param[out] pwm A new handle for use with the other functions.
724 * \return 0 on success or an error code.
726 LIBPWMD_API gpg_error_t
pwmd_new (const char *name
, pwm_t
**pwm
);
729 /*! \brief Set user data for a handle.
731 * Use this function to associate user data with a handle that can later be
732 * retrieved with \ref pwmd_get_pointer().
734 * \param pwm A handle.
735 * \param data A pointer to the user data.
738 LIBPWMD_API
void pwmd_set_pointer (pwm_t
*pwm
, void *data
);
741 /*! \brief Get user data for a handle.
743 * Return the user data pointer previously set with \ref pwmd_set_pointer().
745 * \param pwm A handle.
746 * \returns A pointer to the user data.
748 LIBPWMD_API
void *pwmd_get_pointer (pwm_t
*pwm
);
751 /*! \brief Cancel an operation.
753 * This is limited in functionality as it will only cancel an initiating
754 * connection to the pwmd server. Command cancellation is not yet supported.
756 * \param pwm A handle.
757 * \return 0 on success or an error code.
759 LIBPWMD_API gpg_error_t
pwmd_cancel (pwm_t
*pwm
);
762 /*! \brief Associate an already connected socket with a handle.
764 * Sets a file descriptor for use with the custom read and write callbacks. The
765 * callbacks must be set before calling this function.
767 * \param pwm A handle.
768 * \param fd A connected file descriptor.
769 * \return 0 on success or an error code.
770 * \see \ref pwmd_read_cb_t, \ref pwmd_write_cb_t
772 LIBPWMD_API gpg_error_t
pwmd_connect_fd (pwm_t
*pwm
, int fd
);
775 /*! \brief Establish a connection to a pwmd server.
777 * Connects to the pwmd server specified in \a url. The format of \a url is:
779 * file:///path/to/socket, or
781 * ssh[46]://[username@]hostname[:port], or
783 * tls[46]://hostname[:port]
785 * If \a url is NULL then the default local pwmd socket \a ~/.pwmd/socket
788 * The remaining arguments are parameters for the \a url.
790 * For SSH connections, the first of the positional parameters should be the
791 * identity file to use and is required to be non-NULL unless \ref
792 * PWMD_OPTION_SSH_AGENT is set. The final parameter is the known hosts file
793 * to use or NULL to use a default of \a ~/.ssh/knownhosts.
795 * For TLS connections, the first positional parameter should be the client
796 * certificate filename. The second parameter should be the client
797 * certificate key filename. The third parameter should be the Certificate
798 * Authority (CA) file that was used to sign the server certificate. The
799 * final parameter is an SHA-256 hash of the server fingerprint to verify
802 * For local connections, any remaining parameters are ignored.
804 * \param pwm A handle.
805 * \param url The socket to connect to.
806 * \param ... Remaining parameters for the \a url.
807 * \return 0 on success or an error code.
809 * \see \ref PWMD_OPTION_SSH_AGENT, \ref PWMD_OPTION_SOCKET_TIMEOUT,
810 * pwmd_socket_type(), pwmd_disconnect(), \ref remote
812 LIBPWMD_API gpg_error_t
pwmd_connect (pwm_t
*pwm
, const char *url
, ...);
814 /*! \brief Get the error code of a failed GnuTLS function.
816 * When an TLS error occurs while connecting or during a command, this function
817 * can be used to get the error code and error description.
819 * \param pwm A handle.
820 * \param[out] str The textual representation of the gnutls error code.
821 * \return 0 on success or a GnuTLS error code.
823 LIBPWMD_API
int pwmd_gnutls_error (pwm_t
*pwm
, const char **str
);
825 /*! \brief Set handle options.
827 * See \ref pwmd_option_t for option specific details.
829 * \param pwm A handle.
830 * \param opt The option.
831 * \param ... The option value.
832 * \return 0 on success or an error code.
834 LIBPWMD_API gpg_error_t
pwmd_setopt (pwm_t
*pwm
, int opt
, ...);
837 /*! \brief Get the value for a handle option.
839 * Retrieves the default or previously set value for a handle option. See
840 * \ref pwmd_option_t for option specific details.
842 * \param pwm A handle.
843 * \param opt The option.
844 * \param ... A pointer to the option value type to store the value.
845 * \return 0 on success or an error code.
846 * \note The value is returned as a pointer and not duplicated.
848 LIBPWMD_API gpg_error_t
pwmd_getopt (pwm_t
*pwm
, int opt
, ...);
851 /*! \brief Launch a local pinentry.
853 * Does not send any command to the pwmd server. This maybe useful if a
854 * passphrase is needed while opening a file over a remote connection and
855 * during an \ref pwmd_open() server inquire.
857 * This function may also be used to display a user confirmation dialog with
858 * pinentry when \a which is \ref PWMD_PINENTRY_CONFIRM. The text show in the
859 * pinentry is set with \ref pwmd_setopt().
861 * \param pwm A handle.
862 * \param filename The filename to use in the pinentry dialog strings when
863 * using the default pinentry strings.
864 * \param[out] result The entered value in the pinentry dialog which should be
865 * freed with \ref pwmd_free().
866 * \param[out] len The length of \a result.
867 * \param which Determines the default strings shown in the pinentry
868 * dialog. \ref pwmd_setopt() may also be used to override the defaults. In
869 * this case \ref PWMD_PINENTRY_USER should be used. \ref PWMD_PINENTRY_CLOSE
870 * should be used to terminate the pinentry process when the pinentry is no
873 * \return 0 on success or an error.
875 * \see pwmd_password()
877 LIBPWMD_API gpg_error_t
pwmd_getpin (pwm_t
*pwm
, const char *filename
,
878 char **result
, size_t *len
,
879 pwmd_pinentry_t which
);
881 /*! \brief Obtain a passphrase from a local pinentry.
883 * This is the same function that libpwmd uses during an inquire when using
884 * the local pinentry and the inquire keyword is one of PASSPHRASE,
885 * NEW_PASSPHRASE or SIGN_PASSPHRASE. Provided for convenience since it sets
886 * proper pinentry strings and handles new passphrase confirmation.
888 * \param pwm A handle.
889 * \param keyword The keyword to determine pinentry strings. Usually one of
890 * PASSPHRASE, NEW_PASSPHRASE or SIGN_PASSPHRASE as sent by pwmd.
891 * \param[out] result The obtained passphrase which should be freed with \ref
893 * \param[out] size The length of \a result.
895 * \return 0 on success or an error.
897 LIBPWMD_API gpg_error_t
pwmd_password (pwm_t
*pwm
, const char *keyword
,
898 char **result
, size_t *size
);
900 /*! \brief Test the quality of a passphrase.
902 * When built with passphrase quality checking, you can test the amount of
903 * entropy a passphrase contains with this function. It simply wraps around the
904 * zxcvbn-c quality checking function.
906 * \param passphrase The passphrase to test.
907 * \param[out] result The entropy of the passphrase in bits.
909 * \return 0 on success or an error code.
911 LIBPWMD_API gpg_error_t
pwmd_test_quality (const char *passphrase
,
914 /*! \brief Open a file on the pwmd server.
916 * This will send the OPEN command to the server.
918 * To make use of \a callback, \ref PWMD_OPTION_OVERRIDE_INQUIRE must also be
921 * \param pwm A handle.
922 * \param filename The filename to open. The \a filename is not a full path
923 * but the data filename only.
924 * \param callback A callback function to invoke when pwmd inquires data from
926 * \param data User data passed to the \a callback function.
927 * \return 0 on success or an error code.
928 * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref pinentry, \ref pwmd_password()
930 LIBPWMD_API gpg_error_t
pwmd_open (pwm_t
*pwm
, const char *filename
,
931 pwmd_inquire_cb_t callback
, void *data
);
934 /*! \brief Check for socket activity.
936 * This function should be called periodically to check for any pending status
937 * messages sent from the server and when \em not in a command.
939 * \param pwm A handle.
940 * \return 0 on success or an error code.
942 * \note This function makes use of \ref pwmd_status_cb_t.
944 LIBPWMD_API gpg_error_t
pwmd_process (pwm_t
*pwm
);
947 /*! \brief Generate a new key.
949 * Generate a new signing or encryption key or both. This will only
950 * generate a key without saving the XML document to disk.
952 * The inquire \a callback function should be used when a GENKEY option
953 * specified in \a args inquires data.
955 * \param pwm A handle.
956 * \param args Any GENKEY protocol command options or NULL.
957 * \param callback A callback function to invoke when pwmd inquires data from
959 * \param user User data passed to the \a callback function.
960 * \return 0 on success or an error code.
961 * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_NO_PINENTRY,
962 * \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_command(), \ref pinentry
964 LIBPWMD_API gpg_error_t
pwmd_genkey (pwm_t
*pwm
, const char *args
,
965 pwmd_inquire_cb_t callback
, void *user
);
968 /*! \brief Save a file on the pwmd server.
970 * This will send the SAVE command and write any changes to the document to
973 * The inquire \a callback function should be used when a SAVE option specified
974 * in \a args inquires data.
976 * \param pwm A handle.
977 * \param args Any SAVE protocol command options or NULL.
978 * \param callback A callback function to invoke when pwmd inquires data from
980 * \param user User data passed to the \a callback function.
981 * \return 0 on success or an error code.
982 * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_NO_PINENTRY,
983 * \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_command(), \ref pinentry
985 LIBPWMD_API gpg_error_t
pwmd_save (pwm_t
*pwm
, const char *args
,
986 pwmd_inquire_cb_t callback
, void *user
);
989 /*! \brief Change the passphrase for a data file.
991 * This will send the PASSWD command to the server taking care of pinentry
994 * The inquire \a callback function should be used when a PASSWD option
995 * specified in \a args inquires data.
997 * \param pwm A handle.
998 * \param args Any PASSWD protocol command options or NULL.
999 * \param callback A callback function to invoke when pwmd inquires data from
1001 * \param user User data passed to the \a callback function.
1002 * \return 0 on success or an error code.
1003 * \see \ref PWMD_OPTION_OVERRIDE_INQUIRE, \ref PWMD_OPTION_NO_PINENTRY,
1004 * \ref PWMD_OPTION_LOCAL_PINENTRY, \ref pwmd_command(), \ref pinentry
1006 LIBPWMD_API gpg_error_t
pwmd_passwd (pwm_t
*pwm
, const char *args
,
1007 pwmd_inquire_cb_t callback
, void *user
);
1010 /*! \brief Send a command to the pwmd server.
1012 * You should avoid sending the BYE command here because the assuan context
1013 * will be freed and bad things will happen. Use \ref pwmd_close() instead.
1015 * For pwmd commands that use an INQUIRE to retrieve data from a client, the
1016 * \a callback parameter must be non-NULL and will be used to send the data to
1019 * \param pwm A handle.
1020 * \param[out] result The result of the command when successful which must be
1021 * freed with \ref pwmd_free().
1022 * \param[out] len The length of \a result.
1023 * \param callback A callback function to invoke when pwmd inquires data from
1025 * \param user User data passed to the \a callback function.
1026 * \param cmd The command to send and any command arguments.
1027 * \return 0 on success or an error code.
1029 * \note Not all commands return a \a result.
1031 LIBPWMD_API gpg_error_t
pwmd_command (pwm_t
*pwm
, char **result
,
1033 pwmd_inquire_cb_t callback
,
1034 void *user
, const char *cmd
, ...);
1037 /*! \brief Send a command to the pwmd server.
1039 * Like \ref pwmd_command() but uses an argument pointer instead.
1041 * \param pwm A handle.
1042 * \param[out] result The result of the command when successful which must be
1043 * freed with \ref pwmd_free().
1044 * \param[out] len The length of \a result.
1045 * \param callback A callback function to invoke when pwmd inquires data from
1047 * \param user User data passed to the \a callback function.
1048 * \param cmd The command to send.
1049 * \param ap The arguments to \a cmd.
1050 * \return 0 on success or an error code.
1052 * \note Not all commands return a \a result.
1054 LIBPWMD_API gpg_error_t
pwmd_command_ap (pwm_t
*pwm
, char **result
,
1056 pwmd_inquire_cb_t callback
,
1057 void *user
, const char *cmd
,
1061 /*! \brief Close a connection to the pwmd server.
1063 * This will close the connection but keep any previously set options for the
1064 * specified handle \a pwm. Calling \ref pwmd_connect() will re-acquire an
1065 * libassuan context.
1067 * \param pwm A handle.
1068 * \return 0 on success or an error code.
1069 * \see \ref pwmd_close()
1071 LIBPWMD_API gpg_error_t
pwmd_disconnect (pwm_t
*pwm
);
1074 /*! \brief Close a handle.
1076 * This will close the connection to a pwmd server and free any resources
1077 * associated with it.
1079 * \param pwm A handle.
1081 * \see \ref pwmd_disconnect(), \ref pwmd_new()
1083 LIBPWMD_API
void pwmd_close (pwm_t
*pwm
);
1086 /*! \brief The type of connection a handle has.
1088 * Useful when you need to know what kind of connection a handle has.
1090 * \param pwm A handle.
1091 * \param[out] type The type of socket.
1092 * \return 0 on success or an error code.
1094 * \see \ref pwmd_socket_t
1096 LIBPWMD_API gpg_error_t
pwmd_socket_type (pwm_t
*pwm
,
1097 pwmd_socket_t
* type
);
1099 /*! \brief Get the file descriptor associated with a handle.
1101 * May be useful to determine whether a handle is ready for reading or
1102 * writing by using select(2) or poll(2).
1104 * \param pwm A handle.
1105 * \param[out] fd Set to the file descriptor associated with \a pwm.
1106 * \return 0 on success or an error code.
1108 LIBPWMD_API gpg_error_t
pwmd_fd (pwm_t
*pwm
, int *fd
);
1111 /*! \brief Free a previously allocated pointer.
1113 * Use this function to free resources allocated by the other libpwmd memory
1114 * functions. Do not use it to free allocations made by other allocators.
1116 * The difference between the standard free() and this function is that
1117 * this one will zero out the contents of the pointer before freeing it.
1119 * \param ptr The pointer to deallocate.
1121 * \see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(),
1124 LIBPWMD_API
void pwmd_free (void *ptr
);
1127 /*! \brief A wrapper around malloc.
1129 * Like malloc(), but lets libpwmd keep track of the pointer.
1131 * \param size The number of bytes to allocate.
1132 * \return A newly allocated pointer or NULL if there wasn't enough memory.
1133 * \see malloc(3), pwmd_free()
1135 LIBPWMD_API
void *pwmd_malloc (size_t size
);
1138 /*! \brief A wrapper around calloc().
1140 * Like calloc(), but lets libpwmd keep track of the pointer.
1142 * \param nmemb The number of elements to allocate.
1143 * \param size The number of bytes to allocate.
1144 * \return A newly allocated pointer or NULL if there wasn't enough memory.
1145 * \see calloc(3), pwmd_free()
1147 LIBPWMD_API
void *pwmd_calloc (size_t nmemb
, size_t size
);
1150 /*! \brief A wrapper around realloc().
1152 * Like realloc(), but lets libpwmd keep track of the pointer.
1154 * \param ptr The pointer to reallocate.
1155 * \param size The new number of bytes to allocate.
1156 * \return A newly allocated pointer or NULL if there wasn't enough memory.
1157 * \see realloc(3), pwmd_free()
1159 LIBPWMD_API
void *pwmd_realloc (void *ptr
, size_t size
);
1162 /*! \brief A wrapper around strdup().
1164 * Like strdup(), but lets libpwmd keep track of the pointer.
1166 * \param str The string to duplicate.
1167 * \return A newly allocated character pointer or NULL if there wasn't
1169 * \see strdup(3), pwmd_free()
1171 LIBPWMD_API
char *pwmd_strdup (const char *str
);
1174 /*! \brief Duplicate a formatted string.
1176 * Like \ref asprintf(3), but lets libpwmd keep track of the pointer.
1178 * \param fmt The formatted string and any following arguments.
1179 * \return A newly allocated character pointer or NULL if there wasn't
1183 LIBPWMD_API
char *pwmd_strdup_printf (const char *fmt
, ...);