From 7b462e58d0a5aee5b77e45ce2ddc03d3dbe2a5c9 Mon Sep 17 00:00:00 2001 From: Ben Kibbey Date: Sun, 5 Apr 2009 11:40:47 -0400 Subject: [PATCH] Minor documentation cleanups. Debian package control updates. --- NEWS | 408 ++------------------------ README | 3 - debian/changelog | 88 +----- debian/control | 12 +- debian/copyright | 4 +- debian/docs | 2 +- debian/{libpwmd5.dirs => libpwmd6.dirs} | 0 debian/{libpwmd5.install => libpwmd6.install} | 0 debian/lintian.overrides | 2 +- debian/rules | 4 +- doc/doxygen.conf.in.in | 4 +- doc/libpwmd.3 | 178 +++++------ po/libpwmd.pot | 42 ++- src/libpwmd.h.in | 19 +- 14 files changed, 175 insertions(+), 591 deletions(-) rewrite NEWS (97%) rewrite debian/changelog (98%) rename debian/{libpwmd5.dirs => libpwmd6.dirs} (100%) rename debian/{libpwmd5.install => libpwmd6.install} (100%) diff --git a/NEWS b/NEWS dissimilarity index 97% index 87bd400c..b0998487 100644 --- a/NEWS +++ b/NEWS @@ -1,384 +1,24 @@ -libPWMD v6.0.0 --------------- -This version breaks API compatibility so be sure to adjust your patches. There -are quite a few new features and changes in this release; the main one being -remote socket support by using libssh2 to connect to an SSH server (see -README.SSH for details) and how pwmd_process() works. Here are the API -changes: - - removed: pwmd_open_nb(), pwmd_save_nb(), pwmd_open_nb_finalize(), - pwmd_save_nb_finalize(), pwmd_terminate_pinentry(), pwmd_assuan_ctx(), - pwmd_free_result() - - added: pwmd_new(), pwmd_get_fd(), pwmd_get_fd2(), pwmd_free(), - pwmd_malloc(), pwmd_realloc(), pwmd_calloc(), pwmd_strdup(), - pwmd_open_async2(), pwmd_save_async2(), pwmd_ssh_connect(), - pwmd_ssh_connect_async(), pwmd_get_hostkey(), - pwmd_get_hostkey_async(), pwmd_strerror_r() - - options: PWMD_OPTION_IP_VERSION - -See the manual page or libpwmd.h for details. The pwmc options have also -changed to use getopt_long() so be sure to read pwmc.1 also. - - -libPWMD v5.0.8 --------------- -Ported to libpth. Two versions of libpwmd will be built when libpth is -available and --with-pth is passed to configure (the default). The libpth -version will be called libpwmd-pth and clients should link with -lpwmd-pth or -use the libpwmd-pth.pc pkg-config metadata file. Pass --without-pth to -configure to disable libpth support. - -pwmd_open_nb(), pwmd_save_nb(), pwmd_open_nb_finalize() and -pwmd_save_nb_finalize() are no longer flagged as deprecated. Clients that -connect to a pwmd that cannot use pinentry can use these functions to locally -get a passphrase from pinentry. - -pwmd_open_nb() and pwmd_save_nb() will set the error code to zero before -returning a valid file descriptor. Only for convenience. - - -libPWMD v5.0.7 --------------- -There is now a GIT repository allowing anonymous checkouts and a web interface -at http://repo.or.cz/w/libpwmd.git. To clone the repository: - - git clone git://repo.or.cz/libpwmd.git - - To get the latest changes: - - git pull - -Fixed setting the pinentry title string when an invalid password was entered. - -g++ compile time fix. - - -libPWMD v5.0.6 --------------- -pwmc now sends the LOCK command after opening the data file. - -Added pwmc command line option -t to specify the pinentry timeout. - -Requires pinentry 0.7.5 or later when using pwmd_open_nb(). This version uses -gpg error codes. - -pwmd_open() now uses pwmd's pinentry method rather than forking. This makes -version 1.11 of pwmd a requirement. - -pwmd_open_async() now honors PWMD_OPTION_PINENTRY_TRIES. - - -libPWMD v5.0.5 --------------- -Fixed pwmd_process() to make sure all pending data has read. - -A couple minor bugfixes. - - -libPWMD v5.0.4 --------------- -Added pwmc command line option -i to specify the number of iterations when -saving (-S). Requires pwmd v1.9. - - -libPWMD v5.0.3 --------------- -This release is mainly fixes and features for asynchronous clients. - -Added pwmd_assuan_ctx() to return both the assuan context and socket file -descriptor associated with the specified pwm_t handle. - -Added pwmd_pending_line() which is a wrapper around assuan_pending_line() and -assuan_read_line(). - -Don't return an error if the data file is unreadable when pwmd_open() is -called. - -The socket file descriptor is set to block when doing an INQUIRE. Fixes -GPG_ERR_EAGAIN being returned from assuan_transact(). - -Fixed status messages when using pwmd_process(). - -Removed assuan.h client dependency. - - -libPWMD v5.0.2 --------------- -Added pwmd_open_async(), pwmd_save_async(), pwmd_process(), pwmd_finalize() -and pwmd_async_t. This will replace pwmd_open_nb(), pwmd_open_nb_finalize(), -pwmd_save_nb(), pwmd_save_nb_finalize() and pwmd_nb_state_t in a future -version. These new functions allow pwmd to use its pinentry method rather than -having libpwmd fork() and launch pinentry for nonblocking IO. - -When DEBUG is defined, a few new command line options are available to pwmc to -test password retrieval methods. - - -libPWMD v5.0.1 --------------- -Let pwmc handle the new IMPORT command. - -Fixed disconnecting pinentry. - -When the inquire callback returns GPG_ERR_EOF and 'result' is not NULL, send -the rest of 'result' before terminating the callback. - - -libPWMD v5.0.0 --------------- -This version breaks backward compatibility and requires pwmd 1.4 or later. The -reason is because of how commands that use the INQUIRE response (the "STORE" -command) from the server has changed. To do a INQUIRE command, use the new -pwmd_inquire() function and not pwmd_command(). The reason for this is to use -less memory when large amounts of data is to be sent. The entire data doesn't -need to be stored in a buffer before sending. It can be sent ASSUAN_LINELENGTH -bytes at a time (~1000) and also removes the one-line-per-command restriction; -the data can contain newline characters. See pwmc.c for example usage. - -Updated to use new pwmd error codes. - -Fixed pwmd_connect() not setting the error parameter on success. - -Only one command can be processed with pwmc do to the new INQUIRE code. This -removes pwmc command line option -E. - -Added pwmc command line option -I to read INQUIRE (STORE command) data -from the specified file descriptor. Reading from a file descriptor rather from -a pipe can save memory when large amounts of data is being sent. See the pwmc -manual page for example usage. - -The result of a pwmc command is not modified at all (newline characters). - -Send OPTION CLIENT NAME=pwmc when pwmc connects to the server. - -Server status messages are printed to stderr by default. Use the new command -line option -X to suppress status messages. - -Since pwmd 1.4 includes it's own pinentry support, setting -PWMD_OPTION_PINENTRY with pwmd_setopt() will send "OPTION PINENTRY=0" to the -server to prevent pwmd from using its pinentry support. - -Renamed 'configure' option --with-pinentry-path to --with-pinentry. - -Look for ~/.pwmd/pinentry.conf rather than ~/.pwmd/env. The variable names -have also changed. They are now: TTYNAME, TTYTYPE, DISPLAY and PATH. - -A few bugfixes. See ChangeLog for details. - - -libPWMD v4.0.3 --------------- -Added --with-pinentry-path to configure to set the default location of the -pinentry binary. The default is /usr/bin/pinentry. - -The timeout (if set) is cancelled after pinentry returns since this means -input was read. - -PWMD no longer returns EPWMD_FILE_NOT_FOUND anywhere. It is up to the client -to figure out if the file is new or not by using the GETCONFIG protocol -command. - -Added the -d command line switch to pwmc. This will redirect any command -output to the specified file descriptor. If your using pinentry to retrieve a -password from the same tty as pwmc and redirecting output, this is needed. - -Added pwmc command line options -D, -T and -N. These can set the pinentry -display, tty and terminal type. - -A couple of minor bugfixes. - - -libPWMD v4.0.2 --------------- -Added gettext support. - -Don't free the password when set with pwmd_setopt() until pwmd_close() is -called. Fixes pwmc -p for example. - -Fixed pwmc and looping when an error occurs and pinentry is used to get the -password. - - -libPWMD v4.0.1 --------------- -FreeBSD compile-time fix. - -pwmd_open() will return GPG_ERR_TIMEOUT after pwmd_terminate_pinentry() is -called. - -Warn about unused function results at compile-time. - - -libPWMD v4.0.0 --------------- -Fixed gpg-error descriptions. Client's linked to this version of libpwmd -should be using pwmd v0.10 or later. - -Made the pwm_t structure private. - -Library functions returning PWMD_OK or PWMD_ERROR now are prototyped to return -a type of gpg_error_t. This removes the extra needed parameter when calling -these functions. When these functions succeed, 0 is returned. Otherwise it's -an error code that pwmd_strerror() can describe. - -Renamed pwmd_option to pwmd_option_t. - -Added PWMD_OPTION_STATUS_FUNC and PWMD_OPTION_STATUS_DATA. The set function -will be called when pwmd sends a status (S) line. The function should return 0 -on success or a gpg_error_t which will fail the current command with the -returned error code. - -Renamed PWMD_OPTION_[TITLE|PROMPT|DESC] to PWMD_OPTION_PINENTRY_... - -When using pinentry for password retrieval, PWMD_OPTION_PINENTRY_TRIES can -be set to specify the number of times before giving up after an invalid -password. - -The custom memory de/allocator symbols are now hidden. - -Renamed pwmd_password_func to pwmd_password_fn. A pwm_t * is also a required -argument. - -Renamed pwmd_status_func to pwmd_status_fn. - -Removed pwmd_get_password(). This has been replaced by pwmd_open_nb() and -pwmd_save_nb(). These function's will return a file descriptor that select() -can use when a file isn't cached. When available for a read(), a -pwmd_nb_status_t should be read and then passed to pwmd_open_nb_finalize() or -pwmd_save_nb_finalize() to update the pwm handle. pwmd_open_nb() also has an -option to specify the number of seconds until the pinentry process will -timeout. - -Added pwmd_terminate_pinentry() which will kill the pinentry process -associated with the specified pwm handle. Use this if you need a pinentry -timeout but don't call pwmd_open_nb(). - -Added pwmc command line option -t to specified the pinentry timeout. - -When a file ~/.pwmd/env exists, it is read before calling pinentry. This file -contains NAME=VALUE pinentry settings where NAME is one of TTY, TERM or -DISPLAY. These settings will overwrite the ones set by pwmd_setopt(). This -allows a daemon process to use pinentry after it's cache entry has been -removed. - -Quite a few API changes and bugfixes. Read libpwmd.3 for details. - - -libPWMD v3.0.0 --------------- -Now uses the assuan protocol for communicating with pwmd. This changes things -quite a bit. Read on... - -Uses more secure memory allocation. Kinda. It mainly just zero's out what is -allocated before free()'ing it. - -Added pwmd_init(). Call this before anything else. - -Added pwmd_open() and pwmd_save(). This removes PWMD_OPEN and PWMD_SAVE. - -Removed PWMD_COMMAND. pwmd_command() now accepts a format string as the -command. - -Added pwmd_free_result(). Use this to free a result from pwmd_command(). - -Removed PWMD_SETOPT. Changed to pwmd_setopt(). - -Added options for setting up the pinentry terminal and display. - -Added pwmd_get_password(). This is a nonblocking way of calling pinentry. It -returns a file descriptor that select() can use to read from when a password -is ready to be read from with read() (mostly ripped from Elinks' -start_thread()). Thanks Kalle Olavi Niemitalo for the idea. - -Now uses libgpg-error error codes. - -Fixed pwmc and the BYE command. - -A few other changes. Read the libpwmd.h header file, libpwmd.3 and ChangeLog -for all the details. - - -libPWMD v2.0.3 --------------- -Split pwmd and libpwmd into their own packages. - -Added PWMD_SETOPT options PWMD_OPTION_PASSWORD_FUNC and -PWMD_OPTION_PASSWORD_DATA to specify a custom password retrieval function for -use with the PWMD_OPEN and PWMD_SAVE commands. - -gpg-agent(1) is no longer used for interacting with pinentry(1). Now libassuan -calls pinentry directly. This adds PWMD_OPTION_PINENTRY_PATH to specify the -location of the pinentry program. The default is /usr/bin/pinentry. New -programs should use PWMD_OPTION_PINENTRY instead of PWMD_OPTION_USEAGENT and -EPWMD_PINENTRY_ERROR instead of EPWMD_AGENT_ERROR. - - -libPWMD v2.0.2 --------------- -Added a manual page. - -Removed pwmd_list_free(). The prototype disappeared but I forgot to remove the -code. - - -libPWMD v2.0.1 --------------- -Restore the working directory after connecting to the socket. - -Changed the gpg-agent title and description strings in pwmc. - -Fixed a segfault when looking for the empty string in a result from -pwmd_command(). - - -libPWMD v2.0.0 --------------- -Most of the PWMD_* commands have been removed. PWMD_OPEN, PWMD_SAVE, -PWMD_SETOPT and the new PWMD_COMMAND remain. PWMD_COMMAND takes a char* -argument being the protocol command along with any argument to send to the -server. This is alot simpler and less error prone than before. Also the -library won't need to be updated if a protocol command changed or is added. - -Fixed PWMD_SAVE and asking for a password when the file was cached. - -Added pwmc. This is a command line client for pwmd. It reads protocol commands -from stdin. - -Removed pwmd_base64_encode() and pwmd_base64_decode(). - -Added a pkg-config meta file. - - -libPWMD v1.0.1 --------------- -Added PWMD_ATTR_GET to get an attribute value from an element path. - -pwmd_base64_decode() bugfix. Don't assume the return value is a character -array by nul-terminating it. - -Added pwmd_list_free() to free a "list" result. - -Can compile with g++ and maybe other C++ compilers. - -Fixed some memory leaks. - -Bugfix for the protocol parser. - - -libPWMD v1.0.0 --------------- -Changed the version number as suggested by the libtool docs. - -pwmd_base64_decode() bugfix. The returned string wasn't NULL terminated. - -Updates for the OPEN and SAVE protocol commands. libPWMD no longer base64 -encodes the key. - -Updates for the new ATTR protocol command. - - -libPWMD v0.0.1 --------------- -Initial release. +libPWMD v6.0.0 +-------------- +This version breaks API compatibility with previous version (hence the major +version bump) so be sure to adjust your patches. There are quite a few new +features and changes in this release; the main one being remote socket support +by using libssh2 to connect to an SSH server (see README.SSH for details) and +how pwmd_process() works. Here are the API changes: + + Removed: pwmd_open_nb(), pwmd_save_nb(), pwmd_open_nb_finalize(), + pwmd_save_nb_finalize(), pwmd_terminate_pinentry(), pwmd_assuan_ctx(), + pwmd_free_result() + + Added: pwmd_new(), pwmd_get_fds(), pwmd_free(), pwmd_malloc(), + pwmd_realloc(), pwmd_calloc(), pwmd_strdup(), + pwmd_strdup_printf(),pwmd_open_async2(), pwmd_save_async2(), + pwmd_ssh_connect(), pwmd_ssh_connect_async(), pwmd_get_hostkey(), + pwmd_get_hostkey_async(), pwmd_strerror_r(), pwmd_open2(), + pwmd_save2() + + Options removed: PWMD_OPTION_PINENTRY + Options added: PWMD_OPTION_IP_VERSION + +See the manual page or libpwmd.h for details. The pwmc options have also +changed to use getopt_long() so be sure to read pwmc.1 also. diff --git a/README b/README index f6f0eeb1..15f56ffc 100644 --- a/README +++ b/README @@ -5,9 +5,6 @@ them to the pwmd server. Requirements: - libassuan - http://www.gnupg.org - Communication protocol. Version 1.0.5 or later is required. - libgpg-error - http://www.gnupg.org libassuan returns gpg error codes. diff --git a/debian/changelog b/debian/changelog dissimilarity index 98% index 76816c05..90b96c72 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,78 +1,10 @@ -libpwmd (5.0.8-1) testing; urgency=low - - * New upstream. - - -- Ben Kibbey Sun, 28 Sep 2008 18:01:51 -0400 - -libpwmd (5.0.6-1) testing; urgency=low - - * New upstream. - * Standards version 3.8.0. - * No longer Recommend pinentry but Depend on pwmd v1.11 or later. - * Removed ${misc:Depends} from control file. - - -- Ben Kibbey Sat, 05 Jul 2008 17:39:24 -0400 - -libpwmd (5.0.5-1) testing; urgency=low - - * New upstream. - - -- Ben Kibbey Sun, 06 Apr 2008 12:52:31 -0400 - -libpwmd (5.0.4-1) testing; urgency=low - - * New upstream. - * Require pwmd >= 1.9. - - -- Ben Kibbey Sat, 08 Mar 2008 11:32:36 -0500 - -libpwmd (5.0.3-1) testing; urgency=low - - * New upstream. - - -- Ben Kibbey Sat, 01 Mar 2008 10:08:00 -0500 - -libpwmd (5.0.2-1) testing; urgency=low - - * New upstream. - - -- Ben Kibbey Sun, 27 Jan 2008 08:32:04 -0500 - -libpwmd (5.0.1-1) testing; urgency=low - - * New upstream. - - -- Ben Kibbey Sat, 12 Jan 2008 14:50:03 -0500 - -libpwmd (5.0.0-1) testing; urgency=low - - * Fixed some lintian warnings. This changes the package name to include the - major version number. - * Standards-Version 3.7.3. - * New upstream. - - -- Ben Kibbey Sat, 05 Jan 2008 12:22:11 -0500 - -libpwmd (4.0.3-1) testing; urgency=low - - * New upstream. - - -- Ben Kibbey Mon, 03 Sep 2007 10:49:25 -0400 - -libpwmd (4.0.2-1) testing; urgency=low - - * New upstream. - - -- Ben Kibbey Sat, 11 Aug 2007 12:49:03 -0400 - -libpwmd (4.0.1-1) testing; urgency=low - - * New upstream. - - -- Ben Kibbey Sat, 04 Aug 2007 15:12:34 -0400 - -libpwmd (4.0.0-1) testing; urgency=low - - * Initial release. - - -- Ben Kibbey Sat, 14 Jul 2007 12:41:32 -0400 +libpwmd (6.0.0-1) testing; urgency=low + + * Initial release. + * Recommends pinentry >= 0.7.5. + * Recommends pwmd >= 1.11 rather than requiring it since remote connections + can be made. + * Updated to standards version 3.8.1. + * Don't build with libpth2 support. + + -- Ben Kibbey Sun, 05 Apr 2009 11:29:32 -0400 diff --git a/debian/control b/debian/control index ee4dd14f..8dabc57f 100644 --- a/debian/control +++ b/debian/control @@ -3,18 +3,20 @@ Priority: optional Maintainer: Ben Kibbey Homepage: http://bjk.sourceforge.net/pwmd/ Build-Depends: debhelper (>= 5), autotools-dev -Standards-Version: 3.8.0 +Standards-Version: 3.8.1 Section: libs -Package: libpwmd5 +Package: libpwmd6 Homepage: http://bjk.sourceforge.net/pwmd/ Section: libs Architecture: any -Depends: ${shlibs:Depends}, pwmd (>= 1.11) +Depends: ${shlibs:Depends} +Recommends: pwmd (>= 1.11), pinentry-curses (>= 0.7.5) | pinentry-gtk (>= 0.7.5) | pinentry-gtk2 (>= 0.7.5) | pinentry-qt (>= 0.7.5) Provides: libpwmd Description: library for applications making use of pwmd A library that makes it easy for applications to use Password Manager Daemon. - Supports (non-blocking) password retrieval from pinentry and secure memory - management. A command line client is also included. + Supports (non-blocking) password retrieval from pinentry, secure memory + management and remote connections over an SSH channel. A command line client + is also included. . This package contains both the shared library and the development files. diff --git a/debian/copyright b/debian/copyright index 7122f346..08046738 100644 --- a/debian/copyright +++ b/debian/copyright @@ -9,7 +9,7 @@ Upstream Author: Copyright: - Copyright (C) 2008 Ben Kibbey + Copyright (C) 2009 Ben Kibbey License: @@ -27,5 +27,5 @@ License: License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. -The Debian packaging is (C) 2008, Ben Kibbey and +The Debian packaging is (C) 2009, Ben Kibbey and is licensed under the GPL, see `/usr/share/common-licenses/GPL'. diff --git a/debian/docs b/debian/docs index b6ddd31c..f83a5ead 100644 --- a/debian/docs +++ b/debian/docs @@ -1,3 +1,3 @@ -ChangeLog.old NEWS README +README.SSH diff --git a/debian/libpwmd5.dirs b/debian/libpwmd6.dirs similarity index 100% rename from debian/libpwmd5.dirs rename to debian/libpwmd6.dirs diff --git a/debian/libpwmd5.install b/debian/libpwmd6.install similarity index 100% rename from debian/libpwmd5.install rename to debian/libpwmd6.install diff --git a/debian/lintian.overrides b/debian/lintian.overrides index 1b1562fb..c35f9af7 100644 --- a/debian/lintian.overrides +++ b/debian/lintian.overrides @@ -1 +1 @@ -libpwmd5: non-dev-pkg-with-shlib-symlink +libpwmd6: non-dev-pkg-with-shlib-symlink diff --git a/debian/rules b/debian/rules index d17a0c5b..516d535e 100755 --- a/debian/rules +++ b/debian/rules @@ -42,7 +42,7 @@ endif ifneq "$(wildcard /usr/share/misc/config.guess)" "" cp -f /usr/share/misc/config.guess config.guess endif - ./configure --host=$(DEB_HOST_GNU_TYPE) --build=$(DEB_BUILD_GNU_TYPE) --prefix=/usr --mandir=\$${prefix}/share/man --infodir=\$${prefix}/share/info CFLAGS="$(CFLAGS)" LDFLAGS="-Wl,-z,defs" + ./configure --without-pth --host=$(DEB_HOST_GNU_TYPE) --build=$(DEB_BUILD_GNU_TYPE) --prefix=/usr --mandir=\$${prefix}/share/man --infodir=\$${prefix}/share/info CFLAGS="$(CFLAGS)" LDFLAGS="-Wl,-z,defs" build: build-stamp @@ -88,7 +88,7 @@ binary-arch: build install dh_testroot dh_installchangelogs ChangeLog dh_installdocs - dh_installexamples + #dh_installexamples dh_install --sourcedir=debian/tmp # dh_installmenu # dh_installdebconf diff --git a/doc/doxygen.conf.in.in b/doc/doxygen.conf.in.in index 79ae1abc..73315547 100644 --- a/doc/doxygen.conf.in.in +++ b/doc/doxygen.conf.in.in @@ -160,7 +160,7 @@ MULTILINE_CPP_IS_BRIEF = NO # If set to NO, the detailed description appears after the member # documentation. -DETAILS_AT_TOP = NO +DETAILS_AT_TOP = YES # If the INHERIT_DOCS tag is set to YES (the default) then an undocumented # member inherits the documentation from any documented member that it @@ -186,7 +186,7 @@ TAB_SIZE = 8 # will result in a user-defined paragraph with heading "Side Effects:". # You can put \n's in the value part of an alias to insert newlines. -ALIASES = "pre_conn_req=\note This option must be set before a connection is made when not the default." "sigalrm=\note 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." +ALIASES = "pre_conn_req=\note This option must be set before a connection is made when not the default." "sigalrm=\note 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." "process=\ref pwmd_process() should be called until the command completes." # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C # sources only. Doxygen will then generate output that is more tailored for C. diff --git a/doc/libpwmd.3 b/doc/libpwmd.3 index bc4563bf..aa082e3c 100644 --- a/doc/libpwmd.3 +++ b/doc/libpwmd.3 @@ -1,8 +1,94 @@ -.TH "libpwmd.h" 3 "4 Apr 2009" "Version 6.0.0" "libpwmd" \" -*- nroff -*- +.TH "libpwmd.h" 3 "5 Apr 2009" "Version 6.0.0" "libpwmd" \" -*- nroff -*- .ad l .nh .SH NAME libpwmd.h \- +.SH "Detailed Description" +.PP +libpwmd is a library making it easy for applications to use the pwmd server. +.SH "SSH Details" +.PP +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. Authenication is done by using SSH public key (see \fBssh-keygen(1)\fP) authentication and verifying the host key against a local file containing SHA1 hashes of known hosts. It's alot like how the standard OpenSSH does things only the known_hosts file is in a different format. +.PP +The server hash can be had by using \fBpwmd_get_hostkey()\fP and storing the result in a file. This file is then used as the \fIknown_hosts\fP argument to the SSH connection functions. +.PP +Here's an example \fBauthorized_keys(5)\fP entry. The hash portion should be the same as the contents of the \fIidentity.pub\fP file which is passed as a parameter to the SSH connection functions: +.PP +.PP +.nf + command='socat gopen:$HOME/.pwmd/socket -' ... +.fi +.PP +.PP +\fBTodo\fP +.RS 4 +X11 port forwarding so a remote pinentry can use the local display. +.RE +.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 +\fBParameters:\fP +.RS 4 +\fIPATH\fP The full path to the location of the pinentry binary. +.br +\fIDISPLAY\fP The X11 display to use. +.br +\fITTYNAME\fP The full path to the tty that pinentry should prompt on. +.br +\fITTYTYPE\fP The terminal type of the tty which is required if DISPLAY is not set. +.RE +.PP +\fBSee also:\fP +.RS 4 +\fBSSH Details\fP +.RE +.PP +.SH "Example Client" +.PP +The following example will list the element tree of the data file specified in the first command line argument. +.PP +.PP +.nf + #include + #include + + int main() + { + pwm_t *pwm = pwmd_new(NULL); + gpg_error_t rc = pwmd_connect(pwm, NULL); + char *result; + + if (!rc) { + rc = pwmd_open(pwm, argv[1]); + + if (!rc) { + rc = pwmd_command(pwm, &result, '%s', 'LIST'); + + if (!rc) { + printf('%s', result); + pwmd_free(result); + } + } + } + + pwmd_close(pwm); + + if (rc) + fprintf(stderr, 'ERR: %s\n', pwmd_strerror(rc)); + + exit(rc ? 1 : 0); + } +.fi +.PP + .SH SYNOPSIS .br .PP @@ -173,92 +259,6 @@ libpwmd.h \- .RI "int \fBpwmd_strerror_r\fP (gpg_error_t code, char *buf, size_t size)" .br .in -1c -.SH "Detailed Description" -.PP -libpwmd is a library making it easy for applications to use the pwmd server. -.SH "SSH Details" -.PP -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. Authenication is done by using SSH public key (see \fBssh-keygen(1)\fP) authentication and verifying the host key against a local file containing SHA1 hashes of known hosts. It's alot like how the standard OpenSSH does things only the known_hosts file is in a different format. -.PP -The server hash can be had by using \fBpwmd_get_hostkey()\fP and storing the result in a file. This file is then used as the \fIknown_hosts\fP argument to the SSH connection functions. -.PP -Here's an example \fBauthorized_keys(5)\fP entry. The hash portion should be the same as the contents of the \fIidentity.pub\fP file which is passed as a parameter to the SSH connection functions: -.PP -.PP -.nf - command='socat gopen:$HOME/.pwmd/socket -' ... -.fi -.PP -.PP -\fBTodo\fP -.RS 4 -X11 port forwarding so a remote pinentry can use the local display. -.RE -.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 -\fBParameters:\fP -.RS 4 -\fIPATH\fP The full path to the location of the pinentry binary. -.br -\fIDISPLAY\fP The X11 display to use. -.br -\fITTYNAME\fP The full path to the tty that pinentry should prompt on. -.br -\fITTYTYPE\fP The terminal type of the tty which is required if DISPLAY is not set. -.RE -.PP -\fBSee also:\fP -.RS 4 -\fBSSH Details\fP -.RE -.PP -.SH "Example Client" -.PP -The following example will list the element tree of the data file specified in the first command line argument. -.PP -.PP -.nf - #include - #include - - int main() - { - pwm_t *pwm = pwmd_new(NULL); - gpg_error_t rc = pwmd_connect(pwm, NULL); - char *result; - - if (!rc) { - rc = pwmd_open(pwm, argv[1]); - - if (!rc) { - rc = pwmd_command(pwm, &result, '%s', 'LIST'); - - if (!rc) { - printf('%s', result); - pwmd_free(result); - } - } - } - - pwmd_close(pwm); - - if (rc) - fprintf(stderr, 'ERR: %s\n', pwmd_strerror(rc)); - - exit(rc ? 1 : 0); - } -.fi -.PP - .SH "Define Documentation" .PP .SS "#define EPWMD_ERROR" @@ -714,7 +714,7 @@ This key is needed for host verification of the remote pwmd server. .PP \fBSee also:\fP .RS 4 -\fBpwmd_get_hostkey()\fP, \fBSSH Details\fP +\fBpwmd_get_hostkey()\fP, \fBpwmd_process()\fP, \fBSSH Details\fP .RE .PP @@ -961,7 +961,7 @@ This function may also be called when not in a command to check for pending stat .PP \fBSee also:\fP .RS 4 -pwmd_get_fd(), pwmd_get_fd2(), \fBpwmd_pending_line()\fP +\fBpwmd_get_fds()\fP, \fBpwmd_pending_line()\fP .RE .PP diff --git a/po/libpwmd.pot b/po/libpwmd.pot index 6ae819ef..5d813f63 100644 --- a/po/libpwmd.pot +++ b/po/libpwmd.pot @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: bjk@luxsci.net\n" -"POT-Creation-Date: 2009-03-31 21:59-0400\n" +"POT-Creation-Date: 2009-04-04 22:39-0400\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -16,47 +16,57 @@ msgstr "" "Content-Type: text/plain; charset=CHARSET\n" "Content-Transfer-Encoding: 8bit\n" -#: src/libpwmd.c:118 +#: src/libpwmd.c:112 msgid "Unknown error" msgstr "" -#: src/libpwmd.c:120 +#: src/libpwmd.c:114 msgid "No cache slots available" msgstr "" -#: src/libpwmd.c:122 +#: src/libpwmd.c:116 msgid "Recursion loop" msgstr "" -#: src/libpwmd.c:124 +#: src/libpwmd.c:118 msgid "No file is open" msgstr "" -#: src/libpwmd.c:126 +#: src/libpwmd.c:120 msgid "General LibXML error" msgstr "" -#: src/libpwmd.c:128 +#: src/libpwmd.c:122 msgid "File modified" msgstr "" -#: src/libpwmd.c:1400 -msgid "LibPWMD" +#: src/libpwmd.c:1455 +msgid "Password Manager Daemon" msgstr "" -#: src/libpwmd.c:1406 +#: src/libpwmd.c:1461 msgid "Passphrase:" msgstr "" -#: src/libpwmd.c:1412 -msgid "Enter a passphrase." +#: src/libpwmd.c:1468 +#, c-format +msgid "" +"A passphrase is required to open the file \"%s\". Please%%0Aenter the " +"passphrase below." +msgstr "" + +#: src/libpwmd.c:1470 +#, c-format +msgid "" +"A passphrase is required to save to the file \"%s\". Please%%0Aenter the " +"passphrase below." msgstr "" -#: src/libpwmd.c:1420 src/libpwmd.c:1911 +#: src/libpwmd.c:1489 src/libpwmd.c:2114 msgid "Invalid passphrase, please try again." msgstr "" -#: src/libpwmd.c:1423 +#: src/libpwmd.c:1493 msgid "Please type the passphrase again for confirmation." msgstr "" @@ -71,7 +81,7 @@ msgid "" "\n" "Usage: pwmc [options] [file]\n" " --debug \n" -" pinentry method (0=pwmd, 1=pwmd async, 2=libpwmd)\n" +" pinentry method (0=pwmd, 1=libpwmd, 2=pwmd async, 3=libpwmd async)\n" " --tries \n" " number of pinentry tries before failing (3)\n" " --host, -h \n" @@ -94,7 +104,7 @@ msgid "" " pinentry timeout\n" " --no-status\n" " disable showing of status messages from the server\n" -" --name \n" +" --name, -n \n" " set the client name\n" " --socket \n" " local socket to connect to (~/.pwmd/socket)\n" diff --git a/src/libpwmd.h.in b/src/libpwmd.h.in index 8153210c..43faa09e 100644 --- a/src/libpwmd.h.in +++ b/src/libpwmd.h.in @@ -188,6 +188,7 @@ typedef enum { */ #define PWMD_FD_READABLE 0x01 + /*! \def PWMD_FD_WRITABLE * \hideinitializer * @@ -195,6 +196,7 @@ typedef enum { */ #define PWMD_FD_WRITABLE 0x02 + /*! \typedef pwmd_fd_t * * For use with \ref pwmd_get_fds(). @@ -207,6 +209,7 @@ typedef struct { unsigned flags; } pwmd_fd_t; + /*! \typedef pwmd_passphrase_cb_t * * The value of the option \ref PWMD_OPTION_PASSPHRASE_CB which is set with @@ -430,7 +433,7 @@ gpg_error_t pwmd_ssh_connect(pwm_t *pwm, const char *host, int port, * This is a variant of \ref pwmd_ssh_connect() that will not block while doing * DNS lookups or while connecting. * - * \ref pwmd_process() should be called until the command completes. + * \process * * \param pwm A handle. * \param host The hostname to connect to. @@ -471,13 +474,13 @@ gpg_error_t pwmd_get_hostkey(pwm_t *pwm, const char *host, int port, * * This key is needed for host verification of the remote pwmd server. * - * \ref pwmd_process() should be called until the command completes. + * \process * * \param pwm A handle. * \param host The hostname to connect to. * \param port The port or a default if set to -1. * \return 0 on success or an error code. - * \see pwmd_get_hostkey(), \ref ssh + * \see pwmd_get_hostkey(), \ref pwmd_process(), \ref ssh */ gpg_error_t pwmd_get_hostkey_async(pwm_t *pwm, const char *host, int port) __attribute__ ((warn_unused_result)); @@ -577,7 +580,7 @@ gpg_error_t pwmd_open2(pwm_t *pwm, const char *filename) * be useful if the passphrase isn't cached on a remote pwmd server and a * remote \ref pinentry(1) is not possible. * - * \ref pwmd_process() should be called until the command completes. + * \process * * \sigalrm * @@ -596,7 +599,7 @@ gpg_error_t pwmd_open_async2(pwm_t *pwm, const char *filename) * \ref pwmd_open() is that it will not block if a pinentry is needed for * passphrase input. * - * \ref pwmd_process() should be called until the command completes. + * \process * * \param pwm A handle. * \param filename The filename to open. @@ -625,7 +628,7 @@ gpg_error_t pwmd_open_async(pwm_t *pwm, const char *filename) * determine if the command was successful or not. * \retval ASYNC_PROCESS The command is still running and this function should * be called again. - * \see pwmd_get_fd(), pwmd_get_fd2(), pwmd_pending_line() + * \see pwmd_get_fds(), pwmd_pending_line() */ pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc, char **result) __attribute__ ((warn_unused_result)); @@ -667,7 +670,7 @@ gpg_error_t pwmd_save2(pwm_t *pwm) * be useful if the passphrase isn't cached on a remote pwmd server and a * remote \ref pinentry(1) is not possible. * - * \ref pwmd_process() should be called until the command completes. + * \process * * \param pwm A handle. * \return 0 on success or an error code. @@ -683,7 +686,7 @@ gpg_error_t pwmd_save_async2(pwm_t *pwm) * \ref pwmd_save() is that it will not block if a pinentry is needed for * passphrase input. * - * \ref pwmd_process() should be called until the command completes. + * \process * * \param pwm A handle. * \return 0 on success or an error code. -- 2.11.4.GIT