From c9c5c5283120e1e471e6e9abddce35a9e3253999 Mon Sep 17 00:00:00 2001 From: Ben Kibbey Date: Thu, 2 Apr 2009 22:35:41 -0400 Subject: [PATCH] Documented pinentry. --- doc/libpwmd.3 | 164 +++++++++++++++++++++++++++++++++++++++++++------------ src/libpwmd.h.in | 54 ++++++++++++++---- 2 files changed, 172 insertions(+), 46 deletions(-) diff --git a/doc/libpwmd.3 b/doc/libpwmd.3 index 30d31504..baa5b70e 100644 --- a/doc/libpwmd.3 +++ b/doc/libpwmd.3 @@ -1,4 +1,4 @@ -.TH "libpwmd.h" 3 "1 Apr 2009" "Version 6.0.0" "libpwmd" \" -*- nroff -*- +.TH "libpwmd.h" 3 "2 Apr 2009" "Version 6.0.0" "libpwmd" \" -*- nroff -*- .ad l .nh .SH NAME @@ -60,7 +60,7 @@ libpwmd.h \- .RI "enum \fBpwmd_ip_version_t\fP { \fBPWMD_IP_ANY\fP, \fBPWMD_IPV4\fP, \fBPWMD_IPV6\fP }" .br .ti -1c -.RI "enum \fBpwmd_option_t\fP { \fBPWMD_OPTION_PASSPHRASE_CB\fP, \fBPWMD_OPTION_PASSPHRASE_DATA\fP, \fBPWMD_OPTION_PINENTRY\fP, \fBPWMD_OPTION_PINENTRY_TRIES\fP, \fBPWMD_OPTION_PINENTRY_PATH\fP, \fBPWMD_OPTION_PINENTRY_TTY\fP, \fBPWMD_OPTION_PINENTRY_DISPLAY\fP, \fBPWMD_OPTION_PINENTRY_TERM\fP, \fBPWMD_OPTION_PASSPHRASE\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 }" +.RI "enum \fBpwmd_option_t\fP { \fBPWMD_OPTION_PASSPHRASE_CB\fP, \fBPWMD_OPTION_PASSPHRASE_DATA\fP, \fBPWMD_OPTION_PASSPHRASE\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 }" .br .in -1c .SS "Functions" @@ -91,7 +91,7 @@ libpwmd.h \- .RI "gpg_error_t \fBpwmd_get_fd\fP (\fBpwm_t\fP *pwm, int *fd)" .br .ti -1c -.RI "gpg_error_t \fBpwmd_get_fd2\fP (\fBpwm_t\fP *pwm, int *fd)" +.RI "gpg_error_t \fBpwmd_get_async2_fd\fP (\fBpwm_t\fP *pwm, int *fd)" .br .ti -1c .RI "gpg_error_t \fBpwmd_pending_line\fP (\fBpwm_t\fP *pwm)" @@ -103,6 +103,9 @@ libpwmd.h \- .RI "gpg_error_t \fBpwmd_open\fP (\fBpwm_t\fP *pwm, const char *filename)" .br .ti -1c +.RI "gpg_error_t \fBpwmd_open2\fP (\fBpwm_t\fP *pwm, const char *filename)" +.br +.ti -1c .RI "gpg_error_t \fBpwmd_open_async2\fP (\fBpwm_t\fP *pwm, const char *filename)" .br .ti -1c @@ -115,6 +118,9 @@ libpwmd.h \- .RI "gpg_error_t \fBpwmd_save\fP (\fBpwm_t\fP *pwm)" .br .ti -1c +.RI "gpg_error_t \fBpwmd_save2\fP (\fBpwm_t\fP *pwm)" +.br +.ti -1c .RI "gpg_error_t \fBpwmd_save_async2\fP (\fBpwm_t\fP *pwm)" .br .ti -1c @@ -148,6 +154,9 @@ libpwmd.h \- .RI "char * \fBpwmd_strdup\fP (const char *str)" .br .ti -1c +.RI "char * \fBpwmd_strdup_printf\fP (const char *fmt,...)" +.br +.ti -1c .RI "const char * \fBpwmd_strerror\fP (gpg_error_t code)" .br .ti -1c @@ -165,10 +174,35 @@ libpwmd is a library making it easy for applications to use the pwmd server. .PP .SH "Pinentry Details" .PP +\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 (the connection is to a remote server not on this host) or have the pwmd server use it's pinentry to retrieve a passphrase when needed. +.PP +There are a few options that tell pinentry how and where to prompt for a passphrase. See the \fBpwmd_option_t\fP section for details. These options are not sent (when using pwmd's pinentry) until the pinentry is needed. +.PP +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 'OPTION PINENTRY=0' to the server. This is needed for pinentry retries (passphrase or confirmation failure). So if you need to change pinentry methods, then set this option as needed. +.PP +Some pinentry options can also be specified in a local configuration file \fI'~/.pwmd/pinentry.conf'\fP. These options are initial values for each invokation 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: +.PP +.PD 0 +.IP "\(bu" 2 +\fBPATH\fP The full path to the location of the pinentry binary. +.IP "\(bu" 2 +\fBDISPLAY\fP The X11 display to use. +.IP "\(bu" 2 +\fBTTYNAME\fP The full path to the tty that pinentry should prompt on. +.IP "\(bu" 2 +\fBTTYTYPE\fP The terminal type of the tty which is required if DISPLAY is not set. +.PP +\fB\fP.RS 4 + +.RE +.PP \fBTodo\fP .RS 4 +X11 forwarding. .RE .PP + +.PP .SH "Example Client" .PP The following example will list the element tree of the data file specified in the first command line argument. @@ -351,20 +385,8 @@ A custom passphrase retrieval function which, when set, will be used instead of \fB\fIPWMD_OPTION_PASSPHRASE_DATA \fP\fP User supplied data which is passed to the custom password function. .TP -\fB\fIPWMD_OPTION_PINENTRY \fP\fP -When 1, disable use of the pwmd pinentry. Note that \fBPWMD_OPTION_PASSPHRASE_CB\fP and \fBPWMD_OPTION_PASSPHRASE\fP have precedence over this option. -.PP -\fBNote:\fP -.RS 4 -This option must be set before calling \fBpwmd_open_async2()\fP or \fBpwmd_save_async2()\fP. -.RE -.PP -\fBSee also:\fP -.RS 4 -\fBPinentry Details\fP -.RE -.PP - +\fB\fIPWMD_OPTION_PASSPHRASE \fP\fP +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. .TP \fB\fIPWMD_OPTION_PINENTRY_TRIES \fP\fP An integer value that specifies the specified the number of tries before \fBpinentry(1)\fP will give up when opening a file with the wrong supplied passphrase. The default is 3. @@ -377,10 +399,7 @@ This option has no effect when trying to save a file. The user must either cance .TP \fB\fIPWMD_OPTION_PINENTRY_PATH \fP\fP -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. When using pwmd's \fBpinentry(1)\fP, setting this option will immediately set pwmd's \fBpinentry(1)\fP unless \fBPWMD_OPTION_PINENTRY\fP is set. -.TP -\fB\fIPWMD_OPTION_PINENTRY_TTY \fP\fP -A value which specifies the full path to the tty that \fBpinentry(1)\fP will use. When set and no DISPLAY is available, \fBPWMD_OPTION_PINENTRY_TERM\fP must also be set. +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. .PP \fBSee also:\fP .RS 4 @@ -389,8 +408,8 @@ A value which specifies the full path to the tty that \fBpinentry(1)\fP will use .PP .TP -\fB\fIPWMD_OPTION_PINENTRY_DISPLAY \fP\fP -A value which specifies the X11 display that \fBpinentry(1)\fP will use. +\fB\fIPWMD_OPTION_PINENTRY_TTY \fP\fP +A value which specifies the full path to the tty that \fBpinentry(1)\fP will use. When set and no DISPLAY is available, \fBPWMD_OPTION_PINENTRY_TERM\fP must also be set. .PP \fBSee also:\fP .RS 4 @@ -409,8 +428,15 @@ A value which specifies the terminal type (e.g., vt100) that \fBpinentry(1)\fP w .PP .TP -\fB\fIPWMD_OPTION_PASSPHRASE \fP\fP -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. +\fB\fIPWMD_OPTION_PINENTRY_DISPLAY \fP\fP +A value which specifies the X11 display that \fBpinentry(1)\fP will use. +.PP +\fBSee also:\fP +.RS 4 +\fBPinentry Details\fP +.RE +.PP + .TP \fB\fIPWMD_OPTION_PINENTRY_TITLE \fP\fP A character string that \fBpinentry(1)\fP will use in it's dialog window. @@ -582,11 +608,11 @@ Nothing. .RE .PP -.SS "gpg_error_t pwmd_get_fd (\fBpwm_t\fP * pwm, int * fd)" +.SS "gpg_error_t pwmd_get_async2_fd (\fBpwm_t\fP * pwm, int * fd)" .PP -Get the socket file descriptor. +Get the file descriptor of the local pinentry method. .PP -This will allow polling of the file descriptor associated with the assuan context and in turn the pwmd server. It can be used to determine whether \fBpwmd_process()\fP should be called to process status messages. +This will allow polling of the file descriptor associated with the pipe of the forked pinentry process from \fBpwmd_open_async2()\fP and \fBpwmd_save_async2()\fP. .PP \fBParameters:\fP .RS 4 @@ -602,15 +628,15 @@ This will allow polling of the file descriptor associated with the assuan contex .PP \fBSee also:\fP .RS 4 -\fBpwmd_process()\fP +\fBpwmd_process()\fP, \fBpwmd_open_async2()\fP, \fBpwmd_save_async2()\fP .RE .PP -.SS "gpg_error_t pwmd_get_fd2 (\fBpwm_t\fP * pwm, int * fd)" +.SS "gpg_error_t pwmd_get_fd (\fBpwm_t\fP * pwm, int * fd)" .PP -Get the file descriptor of the local pinentry method. +Get the socket file descriptor. .PP -This will allow polling of the file descriptor associated with the pipe of the forked pinentry process from \fBpwmd_open_async2()\fP and \fBpwmd_save_async2()\fP. +This will allow polling of the file descriptor associated with the assuan context and in turn the pwmd server. It can be used to determine whether \fBpwmd_process()\fP should be called to process status messages. .PP \fBParameters:\fP .RS 4 @@ -626,7 +652,7 @@ This will allow polling of the file descriptor associated with the pipe of the f .PP \fBSee also:\fP .RS 4 -\fBpwmd_process()\fP, \fBpwmd_open_async2()\fP, \fBpwmd_save_async2()\fP +\fBpwmd_process()\fP .RE .PP @@ -791,6 +817,30 @@ This will send the OPEN command to the server. .RE .PP +.SS "gpg_error_t pwmd_open2 (\fBpwm_t\fP * pwm, const char * filename)" +.PP +Open a file on the pwmd server using a local pinentry. +.PP +This will send the OPEN command to the server like \fBpwmd_open()\fP but will use the local pinentry and not pwmd's pinentry. +.PP +\fBParameters:\fP +.RS 4 +\fIpwm\fP A handle. +.br +\fIfilename\fP The filename to open. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success or an error code. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBPinentry Details\fP +.RE +.PP + .SS "gpg_error_t pwmd_open_async (\fBpwm_t\fP * pwm, const char * filename)" .PP Open a file on the pwmd server asynchronously. @@ -895,7 +945,7 @@ This function may also be called when not in a command to check for pending stat .PP \fBSee also:\fP .RS 4 -\fBpwmd_get_fd()\fP, \fBpwmd_get_fd2()\fP, \fBpwmd_pending_line()\fP +\fBpwmd_get_fd()\fP, pwmd_get_fd2(), \fBpwmd_pending_line()\fP .RE .PP @@ -945,6 +995,28 @@ This will send the SAVE command. .RE .PP +.SS "gpg_error_t pwmd_save2 (\fBpwm_t\fP * pwm)" +.PP +Save a file on the pwmd server using the local pinentry. +.PP +This will send the SAVE command like \fBpwmd_save()\fP but will use a local pinentry and not pwmd's pinentry. +.PP +\fBParameters:\fP +.RS 4 +\fIpwm\fP A handle. +.RE +.PP +\fBReturns:\fP +.RS 4 +0 on success or an error code. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBPinentry Details\fP +.RE +.PP + .SS "gpg_error_t pwmd_save_async (\fBpwm_t\fP * pwm)" .PP Save changes to a file on the pwmd server asynchronously. @@ -1114,6 +1186,30 @@ strdup(3), \fBpwmd_free()\fP .RE .PP +.SS "char* pwmd_strdup_printf (const char * fmt, ...)" +.PP +Duplicate a formatted string. +.PP +Like sprintf() but returns an allocated string. +.PP +\fBParameters:\fP +.RS 4 +\fIfmt\fP The formatted string. +.br +\fI...\fP Any format arguments to the string. +.RE +.PP +\fBReturns:\fP +.RS 4 +A newly allocated character pointer or NULL if there wasn't enough memory. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBpwmd_free()\fP +.RE +.PP + .SS "const char* pwmd_strerror (gpg_error_t code)" .PP Return a description of an error code. diff --git a/src/libpwmd.h.in b/src/libpwmd.h.in index 1dc6fcbf..45ebf73d 100644 --- a/src/libpwmd.h.in +++ b/src/libpwmd.h.in @@ -29,7 +29,35 @@ /*! \section pinentry Pinentry Details * - * \todo + * \ref pinentry(1) is a program that prompts the user for input which is + * normally a passphrase or a confirmation. libpwmd can use this program + * either locally (the connection is to a remote server not on this host) or + * have the pwmd server use it's pinentry to retrieve a passphrase when + * needed. + * + * There are a few options that tell pinentry how and where to prompt for a + * passphrase. See the \ref pwmd_option_t section for details. These options + * are not sent (when using pwmd's pinentry) until the pinentry is needed. + * + * If using a local pinentry by calling \ref pwmd_open2(), \ref pwmd_save2(), + * \ref pwmd_open_async2() or pwmd_save_async2(), libpwmd will send the + * command "OPTION PINENTRY=0" to the server. This is needed for pinentry + * retries (passphrase or confirmation failure). So if you need to change + * pinentry methods, then set this option as needed. + * + * Some pinentry options can also be specified in a local configuration file + * \a "~/.pwmd/pinentry.conf". These options are initial values for each + * invokation and may be changed by setting the appropriate \ref + * pwmd_option_t. Each option and value is separated with a '=' on a single + * line. Unrecognized options are ignored. Here are the recognized options: + * + * \arg \b PATH The full path to the location of the pinentry binary. + * \arg \b DISPLAY The X11 display to use. + * \arg \b TTYNAME The full path to the tty that pinentry should prompt on. + * \arg \b TTYTYPE The terminal type of the tty which is required if DISPLAY is + * not set. + * \par + * \todo X11 forwarding. */ /*! \section example Example Client @@ -205,6 +233,11 @@ typedef enum { /*! User supplied data which is passed to the custom password function. */ PWMD_OPTION_PASSPHRASE_DATA, + /*! A string to use as the passphrase when doing an open or save. When not + * NULL, this option has precedence over \ref PWMD_OPTION_PASSPHRASE_CB. + */ + PWMD_OPTION_PASSPHRASE, + /*! An integer value that specifies the specified the number of tries * before \ref pinentry(1) will give up when opening a file with the wrong * supplied passphrase. The default is 3. @@ -218,6 +251,8 @@ typedef enum { /*! A character string value which specifies the full path of the \ref * pinentry(1) binary. For the local \ref pinentry(1) method, the default * is specified at compile time. + * + * \see \ref pinentry */ PWMD_OPTION_PINENTRY_PATH, @@ -229,13 +264,6 @@ typedef enum { */ PWMD_OPTION_PINENTRY_TTY, - /*! A value which specifies the X11 display that \ref pinentry(1) will - * use. - * - * \see \ref pinentry - */ - PWMD_OPTION_PINENTRY_DISPLAY, - /*! A value which specifies the terminal type (e.g., vt100) that \ref * pinentry(1) will use when no X11 display is available. * @@ -243,10 +271,12 @@ typedef enum { */ PWMD_OPTION_PINENTRY_TERM, - /*! A string to use as the passphrase when doing an open or save. When not - * NULL, this option has precedence over \ref PWMD_OPTION_PASSPHRASE_CB. + /*! A value which specifies the X11 display that \ref pinentry(1) will + * use. + * + * \see \ref pinentry */ - PWMD_OPTION_PASSPHRASE, + PWMD_OPTION_PINENTRY_DISPLAY, /*! A character string that \ref pinentry(1) will use in it's dialog * window. @@ -756,7 +786,7 @@ char *pwmd_strdup(const char *str) * enough memory. * \see pwmd_free() */ -char *pwmd_strdup_printf(const char *str, ...) +char *pwmd_strdup_printf(const char *fmt, ...) __attribute__ ((warn_unused_result)); /*! \def EPWMD_ERROR -- 2.11.4.GIT