From e2a18079d157bc53750cdc808c9092234d0e1e15 Mon Sep 17 00:00:00 2001 From: Ben Kibbey Date: Mon, 30 Mar 2009 21:49:02 -0400 Subject: [PATCH] Updated the documentation. Use doxygen to generate the API documentation from src/libpwmd.h.in. Need a Makefile rule, so this isn't done yet. Added README.SSH and doc/doxygen.conf. --- ChangeLog.old | 787 ------------------------------ Makefile.am | 3 +- NEWS | 24 + README | 28 +- README.SSH | 40 ++ TODO | 4 + configure.ac | 9 +- doc/Makefile.am | 2 + doc/doxygen.conf | 1417 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ src/libpwmd.c | 34 +- src/libpwmd.h.in | 1164 ++++++++++++++++++++++++++------------------ 11 files changed, 2222 insertions(+), 1290 deletions(-) delete mode 100644 ChangeLog.old create mode 100644 README.SSH create mode 100644 doc/doxygen.conf rewrite src/libpwmd.h.in (77%) diff --git a/ChangeLog.old b/ChangeLog.old deleted file mode 100644 index 4277363e..00000000 --- a/ChangeLog.old +++ /dev/null @@ -1,787 +0,0 @@ -commit 90f97b68b84df4a847cfe7e9f84d04f2399a5e32 -Author: Ben Kibbey -Date: Sat Feb 10 10:21:49 2007 -0500 - - Split pwmd and libpwmd into their own projects. - - -commit 03dcb8c366bd38ec2dc5fc6a28fd39e82a70ceb7 -Author: Ben Kibbey -Date: Tue Feb 6 21:04:32 2007 -0500 - - Added PWMD_OPTION_PINENTRY_PATH. - - -commit 164b6e489d90e18b5ccd299bddaa888094b88ab7 -Author: Ben Kibbey -Date: Tue Feb 6 20:46:19 2007 -0500 - - Fail if there is no DISPLAY or ttyname(). - - -commit 8fa3cee66e4b9e1ddf8926222b4a58221616fb5c -Author: Ben Kibbey -Date: Tue Feb 6 20:39:31 2007 -0500 - - Set 'error' to EPWMD_ERROR when --disable-pinentry is specified. - - Updated docs. - - -commit 43bc25280248ee3be95864234c751c9944a3dcd9 -Author: Ben Kibbey -Date: Tue Feb 6 20:28:06 2007 -0500 - - Added --disable-pinentry to configure.ac. When specified, the - PWMD_OPTION_PINENTRY (or the depreciated PWMD_OPTION_USEAGENT) - PWMD_SETOPT command will return PWMD_ERROR from pwmd_command() and set - 'error' to 0. - - -commit 5922a62ab5ca44d4ae7bb92c14df00189e7d1104 -Author: Ben Kibbey -Date: Tue Feb 6 19:24:48 2007 -0500 - - gpg-agent(1) is no longer used. The password is gotten from - pinentry(1) via libassuan. PWMD_OPTION_PINENTRY should be used instead - of PWMD_OPTION_USEAGENT. - - -commit 9d432a9bd2c3a6b37aab42438e2854b52f052e5e -Author: Ben Kibbey -Date: Mon Feb 5 08:04:51 2007 -0500 - - Added PWMD_OPTION_PASSWORD_FUNC and PWMD_OPTION_PASSWORD_DATA to - specify a custom password retrieval function. - - -commit 4fe7392c2101f6e19cba705740ba29cc7bcd4d42 -Author: Ben Kibbey -Date: Sat Feb 3 10:54:43 2007 -0500 - - Version 0.7/2.0.2. - - -commit 5cfb770b3a38bc3cd8ffb61b43af530c20dbb51f -Author: Ben Kibbey -Date: Sat Feb 3 10:23:56 2007 -0500 - - Added a libpwmd manual page. - - -commit 33e50c50f69cfba61cfe61c54be31ce994bfabd4 -Author: Ben Kibbey -Date: Sat Jan 27 22:26:20 2007 -0500 - - Removed the unused pwmd_list_free(). - - -commit 24de99461934fa8a5b6ccb15d915d7547ada756c -Author: Ben Kibbey -Date: Sat Jan 27 20:35:11 2007 -0500 - - Forgot to add libpwmd.pc.in. Fixed. - - -commit 406b465e540e8c7533837ca13cba9331fd5bdcf5 -Author: Ben Kibbey -Date: Sat Jan 27 07:48:03 2007 -0500 - - g++ compiling fix. - - -commit 9cbd8aa1223bb6480c417c1572b7f8eac95a2bbb -Author: Ben Kibbey -Date: Thu Jan 25 20:07:56 2007 -0500 - - Don't include libpwmd.pc in the archive. It's generated from - libpwmd.pc.in. - - Version updates. - - -commit 044a8ebea725e2bab91f4ac53c272119a3445125 -Author: Ben Kibbey -Date: Thu Jan 25 19:03:06 2007 -0500 - - Set the title and description strings when using gpg-agent. - - -commit 0461ed45d0df02dcebf8b11c39b0d0678f981318 -Author: Ben Kibbey -Date: Thu Jan 25 19:02:34 2007 -0500 - - Make sure the result exists before checking for an empty string. - - -commit dad5ddad8b3e3ab408bd2aa7fd5e22a19c240bcd -Author: Ben Kibbey -Date: Thu Jan 25 19:52:47 2007 -0500 - - Restore the working directory after connecting to the socket. - - -commit 9d3cf81263533fd75e526012e2af40b5ab2ee0fd -Author: Ben Kibbey -Date: Sat Jan 20 11:34:04 2007 -0500 - - Fixed a typo with install-data-hook and make sure ${libdir}/pkgconfig - is owner writeable which fixes 'make distcheck'. - - -commit 02fe3b039ddd54409f3932f2bbb5b3cd6295106a -Author: Ben Kibbey -Date: Sat Jan 20 11:18:13 2007 -0500 - - Updates. - - -commit 0388955445edee9e7b84800cfbde7e377b4bd542 -Author: Ben Kibbey -Date: Sat Jan 20 11:11:19 2007 -0500 - - Added a note about element values with newline or tab characters. - - -commit e85f5e0faa8e664cd9a8eabae3e74ff9e0195532 -Author: Ben Kibbey -Date: Sat Jan 20 11:06:17 2007 -0500 - - Removed pwmd_base64_encode()/decode() from the library. Let the client - do it. - - -commit 7b59a0ef8c8f105185a4972cfc915dcb30c73ac8 -Author: Ben Kibbey -Date: Fri Jan 19 22:53:09 2007 -0500 - - Update. - - -commit b36f5682a4984414953cf456a189205ead5a446d -Author: Ben Kibbey -Date: Fri Jan 19 18:17:33 2007 -0500 - - Added EPWMD_FILE_MODIFIED. When the SAVE command tries to save to the - filename with a mtime newer than the OPEN mtime. - - -commit a6faa6119e678952ded94b9db7a36b1c973ff219 -Author: Ben Kibbey -Date: Thu Jan 18 22:44:46 2007 -0500 - - Added uninstall-hook to remove libpwmd.pc. - - -commit 86166dcc478839dd65b0d5e8b7d9085395405d06 -Author: Ben Kibbey -Date: Thu Jan 18 22:20:05 2007 -0500 - - install-data-hook fix. - - -commit 6b0a1c773c3688521de937d48f90a8704f6555e1 -Author: Ben Kibbey -Date: Thu Jan 18 21:40:50 2007 -0500 - - Don't require -a or -p with pwmc. The file may be cached on the - server. - - -commit a138e9aaba904d7b8fc28839b709cc40e5acf641 -Author: Ben Kibbey -Date: Thu Jan 18 19:01:29 2007 -0500 - - Install a pkg-config meta file to $libdir/pkgconfig. - - -commit a289f1a672f54061e2988c24b651c1529176090c -Author: Ben Kibbey -Date: Wed Jan 17 22:21:10 2007 -0500 - - Updated NEWS. - - -commit 517435b1442a88394d602440e303cc1dad1cfc96 -Author: Ben Kibbey -Date: Wed Jan 17 22:07:56 2007 -0500 - - Added pwmc.1. - - -commit db5c899f4a4ea580942346e2308d4de2aad682c1 -Author: Ben Kibbey -Date: Wed Jan 17 21:56:27 2007 -0500 - - Update command line usage. - - -commit 528dc66cea26160092bf1db499d64f210170a093 -Author: Ben Kibbey -Date: Wed Jan 17 21:50:47 2007 -0500 - - Write an pwmd_command() error to stderr. - - -commit 97082395ad3311b24113d411254ac17b54be4049 -Author: Ben Kibbey -Date: Wed Jan 17 21:43:50 2007 -0500 - - Added -E to exit after a command error. - - -commit 372f1f48ae9bbbfe63b8ace3dab6dcd4c3ca73d1 -Author: Ben Kibbey -Date: Wed Jan 17 21:39:29 2007 -0500 - - Fixed setting result to an empty value (but not NULL); - - -commit 50b72a29b1cc3155fa3386c1a90252cfab44ca55 -Author: Ben Kibbey -Date: Wed Jan 17 21:35:58 2007 -0500 - - Clear the contents of the input buffer before free()ing. - - -commit ad5b286e06d248a4bd3ed0d32fadbb6ea060b682 -Author: Ben Kibbey -Date: Wed Jan 17 21:29:17 2007 -0500 - - Fix for protocol command lengths > 8196. - - -commit 01ab5b278a15341bf3304f10cb0721a84d5741c0 -Author: Ben Kibbey -Date: Wed Jan 17 20:54:49 2007 -0500 - - Fixed segfault with a NULL result from protocol parser. - - -commit 324bf575a057f47293a42d1e637ac5ae7648ce3c -Author: Ben Kibbey -Date: Wed Jan 17 20:45:22 2007 -0500 - - Fixed PWMD_SAVE with gpg-agent. - - -commit aa7c1f3b78e241df7a6633ae964327199f3217c8 -Author: Ben Kibbey -Date: Wed Jan 17 18:55:31 2007 -0500 - - Removed most PWMD_* commands. The remaining ones are PWMD_SETOPT, - PWMD_OPEN, PWMD_SAVE and the new PWMD_COMMAND to send a protocol - command with arguments. It's alot simpler to use and doesn't require - a library update if a new protocol command is added. - - -commit 49197f39fe724e5b742869901d594f2858605a1c -Author: Ben Kibbey -Date: Tue Jan 16 22:45:20 2007 -0500 - - Added a simpler client than example client. It's more of a utility. It - reads stdin for protocol commands and prints the result (if any). - Installs to PREFIX/bin. - - -commit 10ab90bfc7d288d546e4ad797f332a45d1d7eaa2 -Author: Ben Kibbey -Date: Tue Jan 16 22:24:58 2007 -0500 - - Added PWMD_RAW to send a raw protocol command. The result will be of - type char*. - - -commit 52256e4ce07bda6aecfe96dcb506c8f9037bdad6 -Author: Ben Kibbey -Date: Sun Jan 14 22:08:28 2007 -0500 - - If PWMD_OPTION_USEAGENT is set when PWMD_SAVE is invoked, use the - cached key if available. - - -commit b0c0e9dc19df0519e0010f15843e5e1c6fbc1090 -Author: Ben Kibbey -Date: Sun Jan 14 10:10:54 2007 -0500 - - Version 0.4/1.0.1. - - -commit 7dfb077a32ecd7a07367880fb90e11855cb6c07e -Author: Ben Kibbey -Date: Sat Jan 13 21:23:31 2007 -0500 - - Lost EPWMD_ATTR_NOT_FOUND somehow. Re-added. - - -commit 37a9b6f5ca0e6095c31ef83a3995acf3053eaac4 -Author: Ben Kibbey -Date: Sat Jan 13 18:54:38 2007 -0500 - - Call va_end() after a command. - - -commit 6260cee91ba7a3c2ac20048c8fd8835fb88d379d -Author: Ben Kibbey -Date: Sat Jan 13 18:14:27 2007 -0500 - - Make sure error is the errno of the failed call in pwmd_connect(). - - -commit ac8c0460f8e301a98a0e852eeb306b3b0cadb91d -Author: Ben Kibbey -Date: Sat Jan 13 13:51:00 2007 -0500 - - Fixed a double free(). - - -commit 9b0baad3c83ac605912b033840c2b553c5749cb8 -Author: Ben Kibbey -Date: Fri Jan 12 20:42:40 2007 -0500 - - Update NEWS. - - -commit 8baf2f67c6e52298693f4608993f26e87ffb8f2c -Author: Ben Kibbey -Date: Fri Jan 12 20:39:55 2007 -0500 - - Protocol parser fix for an "invalid write". Thanks Valgrind. - - Clear the server IO buffer before free()'ing. - - Fixed some memory leaks. Thanks Valgrind. - - -commit ebda53008c0c2bd6ac8d53bc395d41e35f30e914 -Author: Ben Kibbey -Date: Thu Jan 11 22:14:14 2007 -0500 - - NEWS updates. - - -commit 3c59d25e1c2b49256647d79e5804eead319bbcf7 -Author: Ben Kibbey -Date: Thu Jan 11 22:10:48 2007 -0500 - - Added pwmd_list_free() to free a list result. - - -commit a36631169510fdc334bb3d2923dc2a6cb6d7a1e9 -Author: Ben Kibbey -Date: Thu Jan 11 20:45:17 2007 -0500 - - Update PWMD_LIST_ACCOUNT docs. - - -commit b915489cdad54201297c566705af09d61fe78332 -Author: Ben Kibbey -Date: Wed Jan 10 18:33:46 2007 -0500 - - Fix for compiling the library with g++. - - -commit 5ac800320b1a4f08ea8d6128081cf76c1a41e97a -Author: Ben Kibbey -Date: Tue Jan 9 19:01:46 2007 -0500 - - Added PWMD_ATTR_GET. - - Brain hemmorage with pwmd_base64_decode() on the previous - modification. Don't null terminate the g_base64_decode() value. Take - another argument of *size. - - Some libpwmd.h doc fixes. - - -commit 6c5221593ecbcae79926055f67bb2e0384e7f98f -Author: Ben Kibbey -Date: Sun Jan 7 08:52:42 2007 -0500 - - Version 0.3. - - -commit ef2ada377b1d2b0ad0dadde51d14b9c41a0b6be2 -Author: Ben Kibbey -Date: Sat Jan 6 17:48:40 2007 -0500 - - Added libpwmd/NEWS. - - Added a changelog Makefile target. - - -commit 7a9dd8b8f1296f93dad94a5530b04aa5461c15e8 -Author: Ben Kibbey -Date: Sat Jan 6 16:05:36 2007 -0500 - - Make sure the wanted file is a regular file or link. - - Update protocol errors in libpwmd. - - -commit 992e8550c5dfbdc39bee56efabf71332974798a1 -Author: Ben Kibbey -Date: Sat Jan 6 15:31:34 2007 -0500 - - Update PROTOCOL. - - Check for termios.h. - - -commit e0d8bf19a30a35ab9cf0ecc5eeb297e39964d334 -Author: Ben Kibbey -Date: Sat Jan 6 15:24:07 2007 -0500 - - Update for the OPEN and SAVE protocol commands. They won't be base 64 - decoded on the server. - - -commit 73cfd2fa7f14630e0e860339d096f5c91b3b28c7 -Author: Ben Kibbey -Date: Sat Jan 6 09:27:26 2007 -0500 - - Fix for pwmd_base64_decode(). g_base64_decode() doesn't NULL terminate - the return value. - - -commit f0437d75fa2c6d56a413538953c6b6e3be2283d2 -Author: Ben Kibbey -Date: Sat Jan 6 09:17:20 2007 -0500 - - Added a note in libpwmd.h about base 64 values and the STORE command. - - Update the example client to use base 64 encoded values. - - -commit cb0f5bbd6ec2437609eb9b12cd77ab5fdf6670ad -Author: Ben Kibbey -Date: Sat Jan 6 08:07:00 2007 -0500 - - send_to_daemon() cleanup. - - -commit f3651170b52233613b0593dbf8a4b5ab99030282 -Author: Ben Kibbey -Date: Sat Jan 6 00:08:45 2007 -0500 - - Added 'version' Makefile target. - - -commit e193d945e3db5c8ab4483178115e8890a32563d0 -Author: Ben Kibbey -Date: Fri Jan 5 22:28:33 2007 -0500 - - Versioning was wrong for libtool's -version-info flag. This should fix - it. - - -commit 4de7d5fabe5a43b2037933c94c6999b746be96ff -Author: Ben Kibbey -Date: Fri Jan 5 22:07:38 2007 -0500 - - Update copyright. - - -commit f474565aad48195be3f28c3453309b0aa289c13e -Author: Ben Kibbey -Date: Fri Jan 5 21:37:59 2007 -0500 - - Let ATTR LIST show the "name" attribute for all elements. - - -commit bb545c1da28d742ecc4d3ce8ff64a1e9394bba8f -Author: Ben Kibbey -Date: Thu Jan 4 22:51:15 2007 -0500 - - Updates for the new ATTR command. - - -commit 9b90c1b53596c5d40a6f273494776737d4669833 -Author: Ben Kibbey -Date: Mon Jan 1 08:23:13 2007 -0500 - - Remove home directory lookups in the example client and pass NULL if - no socket path was specified (-s). - - -commit 4ee9989cea266688507e2e296029125b831d8935 -Author: Ben Kibbey -Date: Sun Dec 31 07:02:29 2006 -0500 - - Update docs. - - -commit 932ece28b50d52d16b2fd6ba534a2da096da7d53 -Author: Ben Kibbey -Date: Sat Dec 30 20:56:46 2006 -0500 - - Update PWMD_OPEN. - - -commit f55b28ebd9df0c4f75fc1e562a1010733310ba7c -Author: Ben Kibbey -Date: Sat Dec 30 20:53:56 2006 -0500 - - Dont include assuan.h in libpwmd.h and change pwm->ctx to void *. - - -commit a0d8e717887a83dc1986738805dc24dae6920815 -Author: Ben Kibbey -Date: Sat Dec 30 17:40:42 2006 -0500 - - If pwmd_connect() is passed a NULL path to the socket, open the - default of ~/.pwmd/socket. - - -commit ae4b055549356e3d6496fab36ac0ff13ffb7bc49 -Author: Ben Kibbey -Date: Sat Dec 30 17:11:16 2006 -0500 - - Put the protocol error codes in libpwmd.h (oops). - - -commit 2b87f3ae9e97f3a2e222846b2e1db53c3ed2e3cd -Author: Ben Kibbey -Date: Sat Dec 30 13:22:14 2006 -0500 - - Have pwmd_command() return EPMD_KEY when there is no key found or the - key is blank. - - Check the file cache when not using gpg-agent too. - - -commit d15a5fbfb21fa283c6daf022b6cab9064c42f546 -Author: Ben Kibbey -Date: Sat Dec 30 13:01:56 2006 -0500 - - Return EPWMD_ERROR when in unknown error occurs from pwmd_command(). - - Return EPWMD_BADKEY when no password has been set and not using - gpg-agent. - - -commit d555db61fb09d0c79bc50f67f4afc2394e7dc141 -Author: Ben Kibbey -Date: Sat Dec 30 11:37:01 2006 -0500 - - Added KnownBugs. - - -commit 4dbfc232e68e7e5887768c364a3880eace70ddb5 -Author: Ben Kibbey -Date: Sat Dec 30 11:15:03 2006 -0500 - - Check for assuan.h. - - Satisfy autoscan. - - Updates to docs. - - -commit 9f653a747bc302d17ae6e9086840c6fdbe30d5bb -Author: Ben Kibbey -Date: Sat Dec 30 08:27:31 2006 -0500 - - pwmd_command() will return PWMD_AGENT_ERROR and set error to -1 if - gpg-agent fails for any reason. - - Fix segfault when GPG_AGENT_INFO isn't set. - - Return PWMD_PERROR and set error to EPWMD_BADKEY if there is an empty - password from gpg-agent. - - -commit 9151cc42cc67fef8294018f63bcdadb80a06024d -Author: Ben Kibbey -Date: Sat Dec 30 08:04:45 2006 -0500 - - Add pwmd_error.[ch] to the repository. - - -commit ebb0fdd7d487a55808da9dfc1b596436a8a380a7 -Author: Ben Kibbey -Date: Fri Dec 29 19:36:17 2006 -0500 - - Have pwmd_command() set error argument to the protocol error code when - returning PWMD_PERROR. pwmd_strerror() can be used to get the protocol - error string. - - More error checking. - - Updated exampleclient.c. - - Reset the password on gpg-agent as soon as possible and only use - pwmd's cache. This removes PWMD_OPTION_CLEARPASSWORD. - - -commit c2383348b9796dcd201cbb65f08267a8e319971d -Author: Ben Kibbey -Date: Wed Dec 27 22:48:30 2006 -0500 - - Update docs. - - -commit 1411757afb264c644b6fdd7d86f291cd05484074 -Author: Ben Kibbey -Date: Wed Dec 27 22:36:07 2006 -0500 - - Added libpwmd/TODO to the repository. - - -commit 7eaa57482dd7ad1118f7e1a7d4f36b05bb72e318 -Author: Ben Kibbey -Date: Wed Dec 27 22:30:48 2006 -0500 - - Readd exampleclient.c to the repository. - - -commit d65f371c1a8797f5061bcd78d25b57dc69cffafb -Author: Ben Kibbey -Date: Wed Dec 27 22:25:34 2006 -0500 - - Add libassuan stuff borrowed from GnuPG to the repository. - - -commit 127d05e67e67e02a881621d094b0eb819ff41df5 -Author: Ben Kibbey -Date: Wed Dec 27 22:18:20 2006 -0500 - - Added the PWMD_CACHE command to the library. - - Updated exampleclient to use caching. - - Use libassuan.m4 to find libassuan. - - Added custom titles, prompts and descriptions to the pinentry program - which can be set via PWMD_SETOPT. - - -commit 6cf1d15a1e6c2db2148e8c90da0616c06bcfb287 -Author: Ben Kibbey -Date: Mon Dec 25 00:28:14 2006 -0500 - - Changed command PWMD_SET to PWMD_SETATTR. - - Now links to libassuan and works with gpg-agent. Still somewhat - useless as the password isn't cached between connections. This also - adds a new command PWMD_SETOPT and changes the behavior of the - PWMD_OPEN and PWMD_SAVE commands. Read libpwmd.h for details. - - -commit f8d8e33b8a67ba12eca840050a9d70d315bee11a -Author: Ben Kibbey -Date: Sun Dec 24 09:20:25 2006 -0500 - - Show the result of PWMD_SET failure. - - -commit a707fdcba9d359841c1d2986ef4d68e2beb4058f -Author: Ben Kibbey -Date: Sun Dec 24 07:49:56 2006 -0500 - - Added INSTALL to the archive. - - -commit 7ed09602281dfedef20dddcf74f40ac4716b2fe6 -Author: Ben Kibbey -Date: Sun Dec 24 07:45:34 2006 -0500 - - Statically link sampleclient to libpwmd. - - -commit aa3b6a8717f657fa15294a73232121d3bc4223ad -Author: Ben Kibbey -Date: Sun Dec 24 07:35:44 2006 -0500 - - Update docs. - - Add ChangeLog to the archive. - - Add -s to sampleclient to specify the socket path. - - Add PWMD_SAVE test to sample client and update PWMD_OPEN to use a - password if the file exists. - - -commit 8aad48633a73cd71faf9a55f61ea7e1399637fcd -Author: Ben Kibbey -Date: Sat Dec 23 23:19:32 2006 -0500 - - Fix the result when there's an error. - - Fix a couple memory leaks. - - Fix the socket path in pwmd_connect(). Now it's the real socket path - and not a directory. - - Redo va_args in pwmd_command(). Misread the manpage. - - Fix the PWMD_OPEN command with a password. - - The PWMD_SAVE command takes NULL as the password to specify gpg-agent - use. If non-NULL, the it's the password to use. - - Added sampleclient.c. - - -commit ed9772db91b47374fc477d7b5a615adc4e400471 -Author: Ben Kibbey -Date: Sat Dec 23 21:18:32 2006 -0500 - - Updates for the libgcrypt commit. - - -commit 0bb079bf4db7024064622951aceab8c88547140b -Author: Ben Kibbey -Date: Sat Dec 23 18:00:38 2006 -0500 - - Small cleanup. - - -commit acbdbf75c8e2907f68fda66d8f30875ec6cc2b7e -Author: Ben Kibbey -Date: Fri Dec 22 19:06:41 2006 -0500 - - Fix for the PWMD_SET command. - - -commit f38a9ef36fe03e5a5574a028842d132bf9e588b0 -Author: Ben Kibbey -Date: Fri Dec 22 18:56:38 2006 -0500 - - The pwmd_command() now takes a variable number of arguments for a command. - - -commit c0bc75961f074cb19202dcb1274d092e9db9862e -Author: Ben Kibbey -Date: Sun Dec 17 15:26:09 2006 -0500 - - Temporary fix for 100% CPU usage after the client connects. For some - reason poll() from glib2 acts as though it's a non-blocking file - descriptor or something and source_check() and source_prepare() get - stuck in a loop until data is ready on the socket. - - -commit e7bf4248bac2ed6d4620f707b7844d6ceb7af980 -Author: Ben Kibbey -Date: Sun Dec 17 15:02:42 2006 -0500 - - Require glib2 for base64 decoding which adds pwmd_base64_decode(). - - If there is no filename with the PWMD_OPEN command then use "default" - as the filename. - - -commit c1211cb68b6ecedc9a3046718384c62fba945e1a -Author: Ben Kibbey -Date: Sat Dec 16 14:14:21 2006 -0500 - - Fix the GET command result. - - -commit 5e6c9e6773b2601a7735d9c2c97c481a0beba8fb -Author: Ben Kibbey -Date: Sat Dec 16 14:02:29 2006 -0500 - - Added libpwmd. - diff --git a/Makefile.am b/Makefile.am index 432bf9cb..8fa16b48 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,5 +1,4 @@ -EXTRA_DIST = TODO ChangeLog ChangeLog.old INSTALL KnownBugs NEWS debian \ - ABOUT-NLS +EXTRA_DIST = TODO ChangeLog INSTALL KnownBugs NEWS debian ABOUT-NLS SUBDIRS = doc assuan src po ACLOCAL_AMFLAGS = -I m4 -I/usr/local/share/aclocal diff --git a/NEWS b/NEWS index 42b554a4..87bd400c 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,27 @@ +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 diff --git a/README b/README index b4173327..f6f0eeb1 100644 --- a/README +++ b/README @@ -1,7 +1,7 @@ -This is a library making it easy to patch applications to work with PWMD. Read -libpwmd.h or libpwmd(3) for all the details. There is an included command line -client 'pwmc' that reads protocol commands from stdin and sends them to the -pwmd server. +This is a library making it easy to patch applications to send commands to +PWMD. Read libpwmd.h or libpwmd(3) for all the details. There is an included +command line client 'pwmc' that reads protocol commands from stdin and sends +them to the pwmd server. Requirements: @@ -17,15 +17,25 @@ Requirements: pwmd - http://bjk.sourceforge.net/pwmd/ Version 1.11 or later is required. -For functions that require a pinentry (e.g., pwmd_open_nb() and -pwmd_save_nb()) pinentry(1) can be used to get the password. If ---disable-pinentry is not passed to configure, then you'll need: +If you want remote SSH support: + + libssh2 - http://libssh2.org + Version 1.0 has been tested to work. + + libc-ares - http://c-ares.haxx.se + For asynchronous DNS lookups. Version 1.5.2 has been tested + to work. + +For functions that require a local pinentry (and not pwmd's pinentry) can be +used to retreive the passphrase. If --disable-pinentry is not passed to +configure, then you'll need: pinentry - http://www.gnupg.org/aegypten There are various interfaces for password entry: console/curses, X11/GTK2, X11/QT. The X11 versions also - support console/curses. If you plan on using pwmd_open_nb() - then pinentry v0.7.5 or later is required. + support console/curses. If you plan on using + pwmd_open_asyn2() then pinentry v0.7.5 or later is + required. GIT Repository -------------- diff --git a/README.SSH b/README.SSH new file mode 100644 index 00000000..3643adc8 --- /dev/null +++ b/README.SSH @@ -0,0 +1,40 @@ +Beginning with version 6 of libpwmd remote access to a pwmd server using +libssh2 has been available. The functions pwmd_ssh_connect() and +pwmd_ssh_connect_async() are used to connect to the server. After resolving +the hostname and connecting, an ssh session is created and the hostkey is +verified against a file containing known hosts. Note that only public key +authentication is supported. + +After verification succeeds, a channel is opened which spawns a shell. This +shell should execute a proxy to the pwmd server by connecting to the local +socket. I use 'socat', it's really handy. + +In order to get this to work you need to put the following in your +~/.ssh/authorized_keys file. It should be prepended to the hash of the public +key that your libpwmd client will use: + + command="socat gopen:$HOME/.pwmd/socket -" + +So now when libpwmd spawns the SSH shell, 'socat' will read the stdin of the +SSH shell and redirect it to the pwmd connection. The output of pwmd works the +same way, only in reverse. + +You can use pwmc to try it out: + + # Get the servers public key. Make sure the hostname is correct and not + # hijacked when getting the hostkey. + pwmc --get-hostkey --host hostname > host_file + + # Generate an SSH key that the client will use. Copy the contents of + # the generated public key to the SSH servers authorized_keys file and + # prepend the above mentioned line to it. You will need both the generated + # public and private keys when connecting to the server. + ssh-keygen -f keyfile + + # List the contents of the pwmd 'datafile' on the remote SSH server by + # connecting as the specified 'user'. + echo list | pwmc --host hostname --known-hosts host_file \ + --user user --identity keyfile datafile + +Ben Kibbey +http://bjk.sourceforge.net/pwmd/ diff --git a/TODO b/TODO index e69de29b..27b3d39f 100644 --- a/TODO +++ b/TODO @@ -0,0 +1,4 @@ +X11 forwarding over an SSH channel. If a passphrase is required when doing a +pwmd_open() or pwmd_save(), the remote pinentry can use the local DISPLAY. + +Language bindings for perl and python would be nice. diff --git a/configure.ac b/configure.ac index 6e2c8565..4e4f753b 100644 --- a/configure.ac +++ b/configure.ac @@ -1,6 +1,6 @@ dnl Process this file with autoconf to produce a configure script. AC_PREREQ(2.59) -AC_INIT(libpwmd, 5.0.9, [Ben Kibbey bjk@luxsci.net]) +AC_INIT(libpwmd, 6.0.0-dev, [Ben Kibbey bjk@luxsci.net]) AC_CONFIG_AUX_DIR(build) AC_CANONICAL_TARGET AM_INIT_AUTOMAKE([foreign]) @@ -13,13 +13,12 @@ AM_GNU_GETTEXT([external]) AM_GNU_GETTEXT_VERSION([0.16.1]) AC_CONFIG_SUBDIRS([assuan]) -VER_MAJOR="`echo "$VERSION" | sed 's/\([[0-9]]*\)\.\([[0-9]]*\)\.\([[0-9]]*\)/\1/'`" -VER_COMPAT="`echo "$VERSION" | sed 's/\([[0-9]]*\)\.\([[0-9]]*\)\.\([[0-9]]*\)/\2/'`" -VER_PATCH="`echo "$VERSION" | sed 's/\([[0-9]]*\)\.\([[0-9]]*\)\.\([[0-9]]*\)/\3/'`" +VER_MAJOR="`echo "$VERSION" | sed 's/\([[0-9]]*\)\.\([[0-9]]*\)\.\([[0-9]]*\).*/\1/'`" +VER_COMPAT="`echo "$VERSION" | sed 's/\([[0-9]]*\)\.\([[0-9]]*\)\.\([[0-9]]*\).*/\2/'`" +VER_PATCH="`echo "$VERSION" | sed 's/\([[0-9]]*\)\.\([[0-9]]*\)\.\([[0-9]]*\).*/\3/'`" AC_SUBST(VER_MAJOR) AC_SUBST(VER_COMPAT) AC_SUBST(VER_PATCH) -AC_SUBST(VER_COMPAT) case "$target_os" in darwin*) diff --git a/doc/Makefile.am b/doc/Makefile.am index 5be569e0..b4c616b0 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,2 +1,4 @@ +EXTRA_DIST = doxygen.conf + dist_man3_MANS = libpwmd.3 dist_man1_MANS = pwmc.1 diff --git a/doc/doxygen.conf b/doc/doxygen.conf new file mode 100644 index 00000000..9658ac62 --- /dev/null +++ b/doc/doxygen.conf @@ -0,0 +1,1417 @@ +# Doxyfile 1.5.6 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project +# +# All text after a hash (#) is considered a comment and will be ignored +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" ") + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# http://www.gnu.org/software/libiconv for the list of possible encodings. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# by quotes) that should identify the project. + +PROJECT_NAME = libpwmd + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = 6.0.0 + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would +# otherwise cause performance problems for the file system. + +CREATE_SUBDIRS = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, +# Croatian, Czech, Danish, Dutch, Farsi, Finnish, French, German, Greek, +# Hungarian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, Polish, +# Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish, +# and Ukrainian. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = NO + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" +# "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = YES + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like regular Qt-style comments +# (thus requiring an explicit @brief command for a brief description.) + +JAVADOC_AUTOBRIEF = NO + +# If the QT_AUTOBRIEF tag is set to YES then Doxygen will +# interpret the first line (until the first dot) of a Qt-style +# comment as the brief description. If set to NO, the comments +# will behave just like regular Qt-style comments (thus requiring +# an explicit \brief command for a brief description.) + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the DETAILS_AT_TOP tag is set to YES then Doxygen +# will output the detailed description near the top, like JavaDoc. +# If set to NO, the detailed description appears after the member +# documentation. + +DETAILS_AT_TOP = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will +# be part of the file/class/namespace that contains it. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 8 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# 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 = + +# 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. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = YES + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java +# sources only. Doxygen will then generate output that is more tailored for +# Java. For instance, namespaces will be presented as packages, qualified +# scopes will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources only. Doxygen will then generate output that is more tailored for +# Fortran. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for +# VHDL. + +OPTIMIZE_OUTPUT_VHDL = NO + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should +# set this tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. +# func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. +# Doxygen will parse them like normal C++ but will assume all classes use public +# instead of private inheritance when no explicit protection keyword is present. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate getter +# and setter methods for a property. Setting this option to YES (the default) +# will make doxygen to replace the get and set methods by a property in the +# documentation. This will only work if the methods are indeed getting or +# setting a simple type. If this is not the case, or you want to show the +# methods anyway, you should set this option to NO. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum +# is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically +# be useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. + +TYPEDEF_HIDES_STRUCT = NO + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = NO + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = NO + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = NO + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base +# name of the file that contains the anonymous namespace. By default +# anonymous namespace are hidden. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = NO + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the +# hierarchy of group names into alphabetical order. If set to NO (the default) +# the group names will appear in their defined order. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or define consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and defines in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +# If the sources in your project are distributed over multiple directories +# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy +# in the documentation. The default is NO. + +SHOW_DIRECTORIES = NO + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. +# This will remove the Files entry from the Quick Index and from the +# Folder Tree View (if specified). The default is YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the +# Namespaces page. This will remove the Namespaces entry from the Quick Index +# and from the Folder Tree View (if specified). The default is YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command , where is the value of +# the FILE_VERSION_FILTER tag, and is the name of an input file +# provided by doxygen. Whatever the program writes to standard output +# is used as the file version. See the manual for examples. + +FILE_VERSION_FILTER = + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = YES + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = YES + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = YES + +# This WARN_NO_PARAMDOC option can be abled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of +# documentation. + +WARN_NO_PARAMDOC = YES + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could +# be obtained via FILE_VERSION_FILTER) + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = /home/me/projects/libpwmd/src + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is +# also the default input encoding. Doxygen uses libiconv (or the iconv built +# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for +# the list of possible encodings. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx +# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 + +FILE_PATTERNS = *.h.in + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = NO + +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. + +EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or +# directories that are symbolic links (a Unix filesystem feature) are excluded +# from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories +# for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command , where +# is the value of the INPUT_FILTER tag, and is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. If FILTER_PATTERNS is specified, this tag will be +# ignored. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER +# is applied to all files. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = NO + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = NO + +# If the REFERENCES_RELATION tag is set to YES +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = NO + +# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) +# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from +# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will +# link to the source code. Otherwise they will link to the documentstion. + +REFERENCES_LINK_SOURCE = YES + +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You +# will need version 4.8.6 or higher. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = NO + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = NO + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own +# stylesheet in the HTML output directory as well, or it will be erased! + +HTML_STYLESHEET = + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_DOCSET tag is set to YES, additional index files +# will be generated that can be used as input for Apple's Xcode 3 +# integrated development environment, introduced with OSX 10.5 (Leopard). +# To create a documentation set, doxygen will generate a Makefile in the +# HTML output directory. Running make will produce the docset in that +# directory and running "make install" will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find +# it at startup. + +GENERATE_DOCSET = NO + +# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the +# feed. A documentation feed provides an umbrella under which multiple +# documentation sets from a single provider (such as a company or product suite) +# can be grouped. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that +# should uniquely identify the documentation set bundle. This should be a +# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen +# will append .docset to the name. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. For this to work a browser that supports +# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox +# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). + +HTML_DYNAMIC_SECTIONS = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING +# is used to encode HtmlHelp index (hhk), content (hhc) and project file +# content. + +CHM_INDEX_ENCODING = + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. + +DISABLE_INDEX = NO + +# This tag can be used to set the number of enum values (range [1..20]) +# that doxygen will group on one line in the generated HTML documentation. + +ENUM_VALUES_PER_LINE = 4 + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. +# If the tag value is set to FRAME, a side panel will be generated +# containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, +# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are +# probably better off using the HTML help feature. Other possible values +# for this tag are: HIERARCHIES, which will generate the Groups, Directories, +# and Class Hiererachy pages using a tree view instead of an ordered list; +# ALL, which combines the behavior of FRAME and HIERARCHIES; and NONE, which +# disables this behavior completely. For backwards compatibility with previous +# releases of Doxygen, the values YES and NO are equivalent to FRAME and NONE +# respectively. + +GENERATE_TREEVIEW = NONE + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +# Use this tag to change the font size of Latex formulas included +# as images in the HTML documentation. The default is 10. Note that +# when you change the font size after a successful doxygen run you need +# to manually remove any form_*.png images from the HTML output directory +# to force them to be regenerated. + +FORMULA_FONTSIZE = 10 + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, a4wide, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = YES + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = NO + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = YES + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that +# enabling this will significantly increase the size of the XML output. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. This is useful +# if you want to understand what is going on. On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_DEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# in the INCLUDE_PATH (see below) will be search if a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line, have an all uppercase name, and do not end with a semicolon. Such +# function macros are typically used for boiler-plate code, and will confuse +# the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool +# does not have to be run to correct the links. +# Note that each tag file must have a unique name +# (where the name does NOT include the path) +# If a tag file is not located in the directory in which doxygen +# is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option is superseded by the HAVE_DOT option below. This is only a +# fallback. It is recommended to install and use dot, since it yields more +# powerful graphs. + +CLASS_DIAGRAMS = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see +# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = NO + +# By default doxygen will write a font called FreeSans.ttf to the output +# directory and reference it in all dot files that doxygen generates. This +# font does not include all possible unicode characters however, so when you need +# these (or just want a differently looking font) you can specify the font name +# using DOT_FONTNAME. You need need to make sure dot is able to find the font, +# which can be done by putting it in a standard location or by setting the +# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory +# containing the font. + +DOT_FONTNAME = FreeSans + +# By default doxygen will tell dot to use the output directory to look for the +# FreeSans.ttf font (which doxygen will put there itself). If you specify a +# different font using DOT_FONTNAME you can set the path where dot +# can find it using this tag. + +DOT_FONTPATH = + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# the CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = YES + +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for groups, showing the direct groups dependencies + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH and HAVE_DOT options are set to YES then +# doxygen will generate a call dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable call graphs +# for selected functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then +# doxygen will generate a caller dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable caller +# graphs for selected functions only using the \callergraph command. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories +# in a graphical way. The dependency relations are determined by the #include +# relations between the files in the directories. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are png, jpg, or gif +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of +# nodes that will be shown in the graph. If the number of nodes in a graph +# becomes larger than this value, doxygen will truncate the graph, which is +# visualized by representing a node as a red box. Note that doxygen if the +# number of direct children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note +# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is enabled by default, which results in a transparent +# background. Warning: Depending on the platform used, enabling this option +# may lead to badly anti-aliased labels on the edges of a graph (i.e. they +# become hard to read). + +DOT_TRANSPARENT = YES + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) +# support this, this feature is disabled by default. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- + +# The SEARCHENGINE tag specifies whether or not a search engine should be +# used. If set to NO the values of all tags below this one will be ignored. + +SEARCHENGINE = NO diff --git a/src/libpwmd.c b/src/libpwmd.c index 558de4ec..5b8b7562 100644 --- a/src/libpwmd.c +++ b/src/libpwmd.c @@ -126,24 +126,22 @@ static const char *_pwmd_strerror(gpg_error_t e) return N_("General LibXML error"); case GPG_ERR_USER_6: return N_("File modified"); - case GPG_ERR_USER_7: - return N_("Access denied"); } } return NULL; } -const char *pwmd_strerror(gpg_error_t e) +const char *pwmd_strerror(gpg_error_t code) { - const char *p = _pwmd_strerror(e); + const char *p = _pwmd_strerror(code); - return p ? p : gpg_strerror(e); + return p ? p : gpg_strerror(code); } -int pwmd_strerror_r(gpg_error_t e, char *buf, size_t size) +int pwmd_strerror_r(gpg_error_t code, char *buf, size_t size) { - const char *p = _pwmd_strerror(e); + const char *p = _pwmd_strerror(code); if (p) { snprintf(buf, size, "%s", p); @@ -154,7 +152,7 @@ int pwmd_strerror_r(gpg_error_t e, char *buf, size_t size) return 0; } - return gpg_strerror_r(e, buf, size); + return gpg_strerror_r(code, buf, size); } gpg_error_t pwmd_init() @@ -778,7 +776,6 @@ gpg_error_t pwmd_ssh_connect(pwm_t *pwm, const char *host, int port, return _do_pwmd_tcp_connect(pwm, host, port, identity, user, known_hosts, 0); } -/* Must free the result with pwmd_free(). */ gpg_error_t pwmd_get_hostkey(const char *host, int port, char **result) { char *hostkey; @@ -1230,7 +1227,7 @@ pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc, char **result) *rc = nb.error; - if (*rc == EPWMD_BADKEY && pwm->cmd == ASYNC_CMD_SAVE2) { + if (*rc == GPG_ERR_INV_PASSPHRASE && pwm->cmd == ASYNC_CMD_SAVE2) { reset_async(pwm, 0); *rc = pwmd_save_async2(pwm); return ASYNC_PROCESS; @@ -1248,7 +1245,7 @@ pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc, char **result) *rc = do_open_command(pwm, pwm->filename, nb.password); memset(&nb, 0, sizeof(pwmd_nb_status_t)); - if (*rc == EPWMD_BADKEY) { + if (*rc == GPG_ERR_INV_PASSPHRASE) { if (++pwm->pin_try < pwm->pinentry_tries) { int n = pwm->pin_try; @@ -1300,7 +1297,8 @@ pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc, char **result) *rc = parse_assuan_line(pwm); /* For pinentry retries. */ - if (pwm->cmd == ASYNC_CMD_OPEN && gpg_err_code(*rc) == EPWMD_BADKEY && + if (pwm->cmd == ASYNC_CMD_OPEN && + gpg_err_code(*rc) == GPG_ERR_INV_PASSPHRASE && ++pwm->pin_try < pwm->pinentry_tries) { pwm->state = ASYNC_INIT; *rc = pwmd_open_async(pwm, pwm->filename); @@ -1676,10 +1674,6 @@ gpg_error_t pwmd_command_ap(pwm_t *pwm, char **result, const char *cmd, return error; } -/* - * Avoid sending the BYE command here. libassuan will close the file - * descriptor and release the assuan context. Use pwmd_close() instead. - */ gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) { va_list ap; @@ -1799,7 +1793,7 @@ static gpg_error_t do_pwmd_open(pwm_t *pwm, const char *filename, int nb) rc = pwmd_command(pwm, &result, "ISCACHED %s", filename); - if (rc == EPWMD_CACHE_NOT_FOUND) { + if (rc == GPG_ERR_NOT_FOUND) { if (pwm->passfunc) { password = (char *)pwm->passfunc(pwm->passdata); goto gotpassword; @@ -1907,7 +1901,7 @@ gotpassword: pwmd_free(password); #ifdef WITH_PINENTRY - if (rc == EPWMD_BADKEY) { + if (rc == GPG_ERR_INV_PASSPHRASE) { if (pin_try-- > 0 && !nb) { rc = pwmd_command(pwm, &result, "OPTION TITLE=%s", N_("Invalid passphrase, please try again.")); @@ -1990,7 +1984,7 @@ again: pwmd_free(*password); pwmd_free(result); pinentry_disconnect(pwm); - error = EPWMD_BADKEY; + error = GPG_ERR_INV_PASSPHRASE; return error; } @@ -2033,7 +2027,7 @@ static gpg_error_t do_pwmd_save(pwm_t *pwm, int nb) if (pwm->use_pinentry || pwm->passfunc) { rc = pwmd_command(pwm, &result, "ISCACHED %s", pwm->filename); - if (rc == EPWMD_CACHE_NOT_FOUND) { + if (rc == GPG_ERR_NOT_FOUND) { if (pwm->passfunc) password = (char *)(*pwm->passfunc)(pwm->passdata); #ifdef WITH_PINENTRY diff --git a/src/libpwmd.h.in b/src/libpwmd.h.in dissimilarity index 77% index fd3460bf..1efa1f85 100644 --- a/src/libpwmd.h.in +++ b/src/libpwmd.h.in @@ -1,467 +1,697 @@ -/* vim:tw=78:ts=8:sw=4:set ft=c: */ -/* - Copyright (C) 2006-2009 Ben Kibbey - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02110-1301 USA -*/ -#ifndef LIBPWMD_H -#define LIBPWMD_H - -#define LIBPWMD_VERSION 0x@VER_MAJOR@@VER_COMPAT@@VER_PATCH@ - -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -/* - * A handle is a pointer to a pwm_t that is returned with pwmd_connect(). - */ -struct pwm_s; -typedef struct pwm_s pwm_t; - -/* - * For use with pwmd_process(). pwmd_open_async() and pwmd_save_async() use - * this data type. - */ -typedef enum { - ASYNC_INIT, - ASYNC_PROCESS, - ASYNC_DONE, -} pwmd_async_t; - -typedef enum { - PWMD_IP_ANY, - PWMD_IPV4, - PWMD_IPV6 -} pwmd_ip_version_t; - -/* - * A custom callback password retrieval function which is set with - * pwmd_setopt(). This has priority over other retrieval methods if set. - */ -typedef const char *(*pwmd_password_fn)(void *data); - -/* - * A callback to be set with pwmd_setopt() that processes Assuan protocol - * status messages. The 'line' is the status message which is prefixed with - * the status keyword. - */ -typedef int (*pwmd_status_fn)(void *data, const char *line); - -/* - * A callback function that is passed to pwmd_inquire(). 'data' is the user - * data that was passed to pwmd_inquire(). 'keyword' is the same as the 'cmd' - * argument to pwmd_inquire(). - * - * 'rc' is the return code from assuan_send_data() and is initially 0 on the - * first call to the set callback. This gives the client a chance to cleanup - * if assuan_send_data() fails for some reason and should probably return the - * same error code, if set, after doing so. - * - * 'result' should be set to the data to be sent which is of 'len' bytes. The - * data is not modified. - * - * The function should return GPG_ERR_EOF when no more data needs to be sent - * or to finish sending the set 'result' and end the INQUIRE, 0 if there is - * more data pending or an error code which will terminate the INQUIRE. - */ -typedef gpg_error_t (*pwmd_inquire_fn)(void *data, const char *keyword, - gpg_error_t rc, char **result, size_t *len); - -/* - * Library options which are set with pwmd_setopt(). - */ -typedef enum { - /* - * PWMD_OPTION_PASSWORD_FUNC - * - * Function to retrieve a password. This function should return an - * string which is the password or NULL on error. - */ - PWMD_OPTION_PASSWORD_FUNC, - - /* - * PWMD_OPTION_PASSWORD_DATA - * - * Data passed to the password function. - */ - PWMD_OPTION_PASSWORD_DATA, - - /* - * PWMD_OPTION_PINENTRY - * - * The following argument should be of type int and set to 1 to enable the - * use of pinentry(1) to retrieve passwords. Setting to 0 will disable - * using pinentry and the password must be set with PWMD_OPTION_PASSWORD - * or gotten from PWMD_OPTION_PASSWORD_FUNC. The pwmd command "OPTION - * PINENTRY=0" is sent when this option is set (1) to prevent pinentry - * from being called on the pwmd server and enabled when unset. - */ - PWMD_OPTION_PINENTRY, - - /* - * PWMD_OPTION_PINENTRY_TRIES - * - * The number of password tries before giving up. If the pinentry "Cancel" - * button is selected, pinentry will abort. Must be > 0. The default is 3. - */ - PWMD_OPTION_PINENTRY_TRIES, - - /* - * PWMD_OPTION_PINENTRY_PATH - * - * The full pathname to the pinentry program. If not specified, - * /usr/bin/pinentry will be used. - */ - PWMD_OPTION_PINENTRY_PATH, - - /* - * PWMD_OPTION_PINENTRY_TTY - * - * pinentry --ttyname. - */ - PWMD_OPTION_PINENTRY_TTY, - - /* - * PWMD_OPTION_PINENTRY_DISPLAY - * - * pinentry --display - */ - PWMD_OPTION_PINENTRY_DISPLAY, - - /* - * PWMD_OPTION_PINENTRY_TERM - * - * pinentry --ttytype - */ - PWMD_OPTION_PINENTRY_TERM, - - /* - * PWMD_OPTION_PASSWORD - * - * The following argument should be of type char* which specifies the - * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and - * PWMD_OPTION_PINENTRY is 0. The password will be kept in memory until - * pwmd_close() is called so setting this option isn't needed each time - * pwmd_open() or pwmd_save() is called regardless of pwmd cache settings. - */ - PWMD_OPTION_PASSWORD, - - /* - * PWMD_OPTION_PINENTRY_TITLE - * PWMD_OPTION_PINENTRY_PROMPT - * PWMD_OPTION_PINENTRY_DESC - * - * The following argument is of type char* which specifies either the - * title, prompt or description in the pinentry program when - * PWMD_OPTION_PINENTRY is set. Note that any CR, LF or % must be percent - * escape (the hexidecimal value of the character). - */ - PWMD_OPTION_PINENTRY_TITLE, - PWMD_OPTION_PINENTRY_PROMPT, - PWMD_OPTION_PINENTRY_DESC, - - /* Internationalization: --lc-ctype and --lc-messages options to - * pinentry. */ - PWMD_OPTION_PINENTRY_LC_CTYPE, - PWMD_OPTION_PINENTRY_LC_MESSAGES, - - /* PWMD_OPTION_PINENTRY_TIMEOUT - * - * The pinentry timeout in seconds. - */ - PWMD_OPTION_PINENTRY_TIMEOUT, - - /* - * PWMD_OPTION_STATUS_FUNC - * - * A function to be called when a status line is sent from pwmd. This - * function should return 0 on success or a gpg-error error code. This - * function won't be used when getting a password with pinentry. - */ - PWMD_OPTION_STATUS_FUNC, - - /* - * PWMD_OPTION_STATUS_DATA - * - * Data passed to the status function. - */ - PWMD_OPTION_STATUS_DATA, - - /* - * PWMD_OPTION_IP_VERSION - * - * The protocol to use when doing DNS resolves. The argument should be a - * pwmd_ip_version_t. - */ - PWMD_OPTION_IP_VERSION, -} pwmd_option_t; - -/* - * Initialize the library. This sets up various things and must be called - * before the other functions. - */ -gpg_error_t pwmd_init(void); - -/* Creates a new handle for use with the other library functions. The 'name' - * parameter specifies the name of the application using this library. - * - * Returns a new handle on success or NULL if there was not enough memory. - */ -pwm_t *pwmd_new(const char *name) __attribute__ ((warn_unused_result)); - -/* - * Connects to the socket specified by 'socket_path'. If socket_path is NULL, - * then a default of ~/.pwmd/socket will be used. Returns a new handle for use - * with the other functions or NULL if there was an error in which case - * 'error' is set to an error code which may be described by pwmd_strerror(). - */ -gpg_error_t pwmd_connect(pwm_t *pwm, const char *socket_path) __attribute__ ((warn_unused_result)); - -/* - * Connects to the remote host "host". Both Ipv4 and IPv6 addresses are - * supported. The "port" parameter may be -1 which uses the default pwmd - * port (6466). - * - * The "cert" and "key" parameters should be the location of the client - * certificate and client certificate key files to use during authentication. - * If NULL, then the defaults ~/.pwmd/client-cert.pem and - * ~/.pwmd/client-key.pem will be used. The "ca" parameter is the certificate - * authority that the server certificate was signed with. If NULL, the default - * ~/.pwmd/ca-cert.pem will be used. - * - * The "verify" parameter, when 1, will verify the hostname in the peer - * certificate. The "cipher" parameter specifies the cipher suite to use for - * the session. - * - * Returns a new handle for use with the other functions or NULL if there was - * an error in which case 'error' is set to an error code which may be - * described by pwmd_strerror(). - */ -gpg_error_t pwmd_ssh_connect(pwm_t *pwm, const char *hostname, int port, const char *identity, const char *user, const char *known_hosts) __attribute__ ((warn_unused_result)); - -/* Like pwmd_ssh_connect() but this function wont block while doing DNS - * lookups and connecting. You should call pwmd_process() only when this - * function succeeds (see pwmd_process() for more information). - */ -gpg_error_t pwmd_ssh_connect_async(pwm_t *pwm, const char *hostname, int port, - const char *identity, const char *user, const char *known_hosts) __attribute__ ((warn_unused_result)); - -/* Retrieve the SSH server SHA1 host key. The result must be freed with - * pwmd_free(). - */ -gpg_error_t pwmd_get_hostkey(const char *hostname, int port, char **result) __attribute__ ((warn_unused_result)); -gpg_error_t pwmd_get_hostkey_async(pwm_t *pwm, const char *hostname, int port) __attribute__ ((warn_unused_result)); - -/* - * Sets 'fd' to the file descriptor which is connected to the pwmd server. - * You can select() or poll() this fd to determine when to call - * pwmd_process(). Returns 0 on success or an error code. - * - * Note that this FD is the assuan context FD and not set during the TCP - * connection phase when used with pwmd_ssh_connect_async() or - * pwmd_get_hostkey_async(). You must wait until pwmd_process() returns - * ASYNC_DONE (then check for an error) and then call this function. - */ -gpg_error_t pwmd_get_fd(pwm_t *pwm, int *fd) __attribute__ ((warn_unused_result)); - -/* This sets fd to the file descriptor used in the pwmd_open_async2() and - * pwmd_save_async2() functions. Returns 0 on success or an error which would - * only happen if the file decsriptor is invalid (the metioned functions - * haven't been called). - */ -gpg_error_t pwmd_get_fd2(pwm_t *pwm, int *fd) __attribute__ ((warn_unused_result)); - -/* Returns 0 if there is a pending (buffered) line needing to be processed. In - * this case, pwmd_process() should be called. Returns GPG_ERR_NO_DATA if - * there is no pending line. - * - * Pending lines usually only happen when out of a command (not a running - * command) and are usually status messages. - */ -gpg_error_t pwmd_pending_line(pwm_t *pwm) __attribute__ ((warn_unused_result)); - -/* - * Sets a libpwmd option 'opt'. The next argument should be of the data type - * required for the option. Returns 0 on success or an error code. - */ -gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...) __attribute__ ((warn_unused_result)); - -/* - * Opens a file 'filename' (the OPEN command). The filename is not a full path - * but only filename which is looked for in the pwmd configured data - * directory. How the password is gotten depends on the options set with - * pwmd_setopt() and whether the file is cached on the server. Returns 0 on - * success or an error code. - */ -gpg_error_t pwmd_open(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result)); - -/* - * This is like pwmd_open() but won't block the process when pinentry is used - * to retrieve the password. It returns -2 when the file is cached (ISCACHED) - * on the server or if the file doesn't exist on the file system (a new file). - * Otherwise it returns a file descriptor that select() can use. When ready - * for a read, a pwmd_nb_status_t should be read. If there is a system error - * (pipe() or fork()), then -1 is returned and 'error' is set to an error code - * that pwmd_strerror() can describe. See pwmd_open_nb_finalize(). - * - * Setting PWMD_OPTION_PINENTRY_TIMEOUT specifies the number of seconds until - * the pinentry terminates. Setting to 0 (the default) will disable timeouts. - * Note that the child process will reset the SIGALRM handler (if any) to it's - * own handler and that the actual OPEN command isn't calculated as part of - * the elapsed time. - * - * Be sure to set PWMD_OPTION_PINENTRY. - */ -gpg_error_t pwmd_open_async2(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result)); - -/* - * This is the preferred way to do a non-blocking open. The difference from - * pwmd_open_nb() is that libpwmd wont fork() to get the pin. Instead, it will - * let pwmd use it's pinentry retrieval method. When successful this function - * returns 0 and pwmd_process() should be called until the command completes. - * - * If pwmd is unable to use pinentry, and non-blocking is needed, then - * pwmd_open_nb() can be used instead. - */ -gpg_error_t pwmd_open_async(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result)); -; - -/* - * When the asynchronous commands pwmd_ssh_connect_async(), pwmd_open_async() - * or pwmd_save_async() succeed (return 0 or non-NULL), this function - * should be called until ASYNC_DONE is returned. It will return ASYNC_PROCESS - * when the command is still running. After ASYNC_DONE is returned, any error - * that may have occurred is stored in 'rc'. If an error occurred or not, - * pwmd_finalize() must be called to reset a control variable so the next - * asynchronous command may be performed. - * - * The result should not be modified by the client. It should be freed by - * calling pwmd_free() before the next asynchronous command. - */ -pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc, char **result) __attribute__ ((warn_unused_result)); -; - -/* - * Sends the SAVE command to the associated handle 'pwm'. If a password is - * required, how it is gotten depends on options set with pwmd_setopt(). - * Returns 0 on success or an error code. - */ -gpg_error_t pwmd_save(pwm_t *pwm) __attribute__ ((warn_unused_result)); - -/* - * This is like pwmd_save() but won't block the process when pinentry is used - * to retrieve the password. It returns -2 when the file is cached (ISCACHED) - * on the server or if the file doesn't exist on the file system (a new file). - * Otherwise it returns a file descriptor that select() can use. When ready - * for a read, read() should read a pwmd_nb_status_t. If there is a system - * error (pipe() or fork()), then -1 is returned and 'error' is set to an - * error code that pwmd_strerror() can describe. See pwmd_save_nb_finalize(). - * - * PWMD_OPTION_PINENTRY_TIMEOUT is ignored when using this method. If a - * password is required, pinentry won't timeout but will wait until either it - * is canceled or a successful passphrase is entered. - * - * Be sure to set PWMD_OPTION_PINENTRY. - */ -gpg_error_t pwmd_save_async2(pwm_t *pwm) __attribute__ ((warn_unused_result)); - -/* - * Like pwmd_save_nb() but uses pwmd to launch pinentry rather than having - * libpwmd fork(). This function returns 0 on success and pwmd_process() - * should be called until the command completes. - */ -gpg_error_t pwmd_save_async(pwm_t *pwm) __attribute__ ((warn_unused_result)); -; - -/* - * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the - * command fails an error code is returned which may be described by passing - * the error to pwmd_strerror(). If successful the function returns 0 and the - * 'result' is the character data of the command or NULL if there was none. - * - * For commands which use an INQUIRE (i.e., STORE), use pwmd_inquire() and not - * pwmd_command(). - * - * A note about the BYE command: Client's should not send this command - * directly with pwmd_command(). They should use pwmd_close() instead because - * libassuan will close the file descriptors with the associated context. - */ -gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) __attribute__ ((warn_unused_result)); -gpg_error_t pwmd_command_ap(pwm_t *pwm, char **result, const char *cmd, - va_list ap) __attribute__ ((warn_unused_result)); - -/* - * Commands which use an INQUIRE to send data (i.e., STORE) should use this - * function and not pwmd_command(). 'cmd' is the command to send and is also - * the 'keyword' argument passed to the callback function 'func'. 'data' is - * user data passed to the callback function. Returns 0 on success or an - * error code which may have been returned from the callback function. - */ -gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_fn func, - void *data) __attribute__ ((warn_unused_result)); - - -/* - * Closes the connection to the socket and frees the resources of the handle. - * Returns no value. - */ -void pwmd_close(pwm_t *pwm); - - -/* Secure memory allocators. pwmd_free() should be called on all command - * results. */ -void pwmd_free(void *ptr); -void *pwmd_malloc(size_t size); -void *pwmd_calloc(size_t nmemb, size_t size); -void *pwmd_realloc(void *ptr, size_t size); -char *pwmd_strdup(const char *str); - -/* - * Protocol error codes. - */ -#define EPWMD_BADKEY GPG_ERR_INV_PASSPHRASE -#define EPWMD_COMMAND_SYNTAX GPG_ERR_SYNTAX -#define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_ELEMENT_NOT_FOUND -#define EPWMD_ACCOUNT_EXISTS GPG_ERR_AMBIGUOUS_NAME -#define EPWMD_CACHE_NOT_FOUND GPG_ERR_NOT_FOUND -#define EPWMD_ATTR_SYNTAX GPG_ERR_SYNTAX -#define EPWMD_ATTR_NOT_FOUND GPG_ERR_NOT_FOUND -#define EPWMD_INVALID_FILENAME GPG_ERR_INV_VALUE -#define EPWMD_EMPTY_ELEMENT GPG_ERR_NO_VALUE -#define EPWMD_INVALID_ELEMENT GPG_ERR_INV_VALUE -#define EPWMD_ERROR GPG_ERR_USER_1 -#define EPWMD_MAX_SLOTS GPG_ERR_USER_2 -#define EPWMD_LOOP GPG_ERR_USER_3 -#define EPWMD_NO_FILE GPG_ERR_USER_4 -#define EPWMD_LIBXML_ERROR GPG_ERR_USER_5 -#define EPWMD_FILE_MODIFIED GPG_ERR_USER_6 -#define EPWMD_FILE_ACCESS GPG_ERR_USER_7 -#define EPWMD_MAX GPG_ERR_USER_8 - -/* - * Return a string describing a pwmd protocol error code. - */ -const char *pwmd_strerror(gpg_error_t error); -int pwmd_strerror_r(gpg_error_t error, char *buf, size_t size); - -#ifdef __cplusplus -} -#endif - -#endif +/* vim:tw=78:ts=8:sw=4:set ft=c: */ +/* + Copyright (C) 2006-2009 Ben Kibbey + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02110-1301 USA +*/ +/*! @headerfile libpwmd.h + * + * libpwmd is a library making it easy for applications to use the pwmd + * server. + */ + +/*! @section ssh SSH Details + * + * @todo + */ + +/*! @section pinentry Pinentry Details + * + * @todo + */ + +/*! @section example Example Client + * + * The following example will list the element tree of the data file specified + * in the first command line argument. + * + * @code + * #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); + * } + * @endcode + */ +/*! @file */ +#ifndef LIBPWMD_H +#define LIBPWMD_H + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +struct pwm_s; +/*! @typedef pwm_t + * + * When a handle is mentioned in this documentation it is a pointer of this + * type. A new handle is allocated with @ref pwmd_new(). + */ +typedef struct pwm_s pwm_t; + +/*! @typedef pwmd_async_t + * + * The return code of @ref pwmd_process() which is used for all asynchronous + * commands. + */ +typedef enum { + ASYNC_INIT, + ASYNC_PROCESS, + ASYNC_DONE, +} pwmd_async_t; + +/*! @typedef pwmd_ip_version_t + * + * The value of the option PWMD_OPTION_IP_VERSION which is set with @ref + * pwmd_setopt(). + */ +typedef enum { + PWMD_IP_ANY, + PWMD_IPV4, + PWMD_IPV6 +} pwmd_ip_version_t; + +/*! @typedef pwmd_password_fn + * + * The value of the option PWMD_OPTION_PASSWORD_FUNC which is set with @ref + * pwmd_setopt(). + * + * @param data A user data pointer which is set with PWMD_OPTION_PASSWORD_DATA. + * @return NULL on failure or the password which is not modified by libpwmd. + */ +typedef const char *(*pwmd_password_fn)(void *data); + +/*! @typedef pwmd_status_fn + * + * The value of the option PWMD_OPTION_STATUS_FUNC which is set with @ref + * pwmd_setopt(). + * + * @param data A user data pointer which is set with PWMD_OPTION_STATUS_DATA. + * @param line The status message line. + * @return 0 on success or an error code which will cause a command to fail. + */ +typedef int (*pwmd_status_fn)(void *data, const char *line); + +/*! @typedef pwmd_inquire_fn + * + * @todo + */ +typedef gpg_error_t (*pwmd_inquire_fn)(void *data, const char *keyword, + gpg_error_t rc, char **line, size_t *len); + +/*! @enum pwmd_option_t + * + * libpwmd options which are set with @ref pwmd_setopt(). + */ +typedef enum { + /*! A custom password retrieval function which, when set, will be used + * instead of @ref pinentry(1). This function will not be used when the + * passphrase is cached on the server or the file is a new one. The value + * of this option should be a @ref pwmd_password_fn function pointer. + */ + PWMD_OPTION_PASSWORD_FUNC, + + /*! User supplied data which is passed to the custom password function. */ + PWMD_OPTION_PASSWORD_DATA, + + /*! @bug The pwmd_open_async2() and pwmd_save_async() functions should + * send the required command before doing anything else. + * + * @see @ref pinentry + */ + PWMD_OPTION_PINENTRY, + + /*! 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. + * + * @note This option has no effect when trying to save a file. The user + * must either cancel the pinentry causing the save to fail or enter the + * correct passphrase during passphrase confirmation. + */ + PWMD_OPTION_PINENTRY_TRIES, + + /*! 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. When using pwmd's @ref pinentry(1), + * setting this option will immediately set pwmd's @ref pinentry(1) unless + * @ref PWMD_OPTION_PINENTRY is set. + */ + PWMD_OPTION_PINENTRY_PATH, + + /*! A value which specifies the full path to the tty that @ref pinentry(1) + * will use. When set and no DISPLAY is available, @ref + * PWMD_OPTION_PINENTRY_TERM must also be set. + * + * @see @ref pinentry + */ + 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. + * + * @see @ref pinentry + */ + PWMD_OPTION_PINENTRY_TERM, + + /*! A string to use as the passphrase when doing an open or save. + * + * @note The option @ref PWMD_OPTION_PINENTRY must be set for this option + * to work. + */ + PWMD_OPTION_PASSWORD, + + /*! A character string that @ref pinentry(1) will use in it's dialog + * window. + */ + PWMD_OPTION_PINENTRY_TITLE, + + /*! A character string that @ref pinentry(1) will use in it's dialog + * window. + */ + PWMD_OPTION_PINENTRY_PROMPT, + + /*! A character string that @ref pinentry(1) will use in it's dialog + * window. + */ + PWMD_OPTION_PINENTRY_DESC, + + /*! For @ref pinentry(1) localization. */ + PWMD_OPTION_PINENTRY_LC_CTYPE, + + /*! For @ref pinentry(1) localization. */ + PWMD_OPTION_PINENTRY_LC_MESSAGES, + + /*! An integer value that specifies the number of seconds @ref pinentry(1) + * will wait for input before timing out and aborting the current command. + * If 0, then no timeout will be used. The default is 30. + */ + PWMD_OPTION_PINENTRY_TIMEOUT, + + /*! A function pointer of type @ref pwmd_status_fn that will process + * status messages received from the pwmd server. + */ + PWMD_OPTION_STATUS_FUNC, + + /*! A user data pointer which is passed to the status message function. */ + PWMD_OPTION_STATUS_DATA, + + /*! The IP version of type @ref pwmd_ip_version_t that @ref + * pwmd_ssh_connect() or @ref pwmd_ssh_connect_async() will use when + * connecting to the remote pwmd server. + * + * @note This option must be set before trying to connect. + */ + PWMD_OPTION_IP_VERSION, +} pwmd_option_t; + +/*! @brief Initialize the library. + * + * This function must be the first function called in the library before any + * others. It sets up internationalization among other things. + * + * @return 0 Success. + */ +gpg_error_t pwmd_init(void); + +/*! @brief Creates a new handle. + * + * Creates a new handle for use with the other functions. + * + * @param name If not NULL, the name of the application. The application name + * is sent to the pwmd server after successfully connecting. + * + * @param name The application name or NULL. + * @return a new handle or NULL if there was not enough memory. + */ +pwm_t *pwmd_new(const char *name) __attribute__ ((warn_unused_result)); + +/*! @brief Connect to a local pwmd server. + * + * Connects to the unix domain socket. + * + * @param pwm A handle. + * @param path The socket path to connect to. If NULL, then a default of + * @a ~/.pwmd/socket will be used. + * @return 0 on success or an error code. + * @see pwmd_ssh_connect(), pwmd_ssh_connect_async() + */ +gpg_error_t pwmd_connect(pwm_t *pwm, const char *path) + __attribute__ ((warn_unused_result)); + +/*! @brief Establish a remote connection to a pwmd server. + * + * Connects to a pwmd server over an SSH channel. + * + * @param pwm A handle. + * @param host The hostname to connect to. + * @param port The port or -1 for the default. + * @param identity The SSH identity to use for authentication. + * @param user The username on the SSH server to login as. If NULL then + * invoking user will be used. + * @param known_hosts A file containing the public SSH server key hash in SHA1 + * format. + * @return 0 on success or an error code. + * @see pwmd_ssh_connect_async(), pwmd_process(), @ref ssh + * @todo X11 forwarding. + */ +gpg_error_t pwmd_ssh_connect(pwm_t *pwm, const char *host, int port, const char *identity, const char *user, const char *known_hosts) __attribute__ ((warn_unused_result)); + +/*! @brief Establish a remote connection to a pwmd server asynchronously. + * + * 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. + * + * @param pwm A handle. + * @param host The hostname to connect to. + * @param port The port or -1 for the default. + * @param identity The SSH identity to use for authentication. + * @param user The username on the SSH server to login as. If NULL, the + * invoking username will be used. + * @param known_hosts A file containing the public SSH server key hash in SHA1 + * format. + * @return 0 on success or an error code. + * @see pwmd_ssh_connect(), pwmd_process(), @ref ssh + * @todo X11 forwarding. + */ +gpg_error_t pwmd_ssh_connect_async(pwm_t *pwm, const char *host, int port, const char *identity, const char *user, const char *known_hosts) __attribute__ ((warn_unused_result)); + +/*! @brief Retrieve a remote SSH host key. + * + * This key is needed for authentication with the server. + * + * @param host The hostname to connect to. + * @param port The port. + * @param result The server host key which must be freed with @ref pwmd_free(). + * @return 0 on success or an error code. + * @see pwmd_get_hostkey_async(), @ref ssh + */ +gpg_error_t pwmd_get_hostkey(const char *host, int port, char **result) __attribute__ ((warn_unused_result)); + +/*! @brief Retrieve a remote SSH host key asynchronously. + * + * This key is needed to authenticate with the server. + * + * @ref pwmd_process() should be called until the command completes. + * + * @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 + */ +gpg_error_t pwmd_get_hostkey_async(pwm_t *pwm, const char *host, int port) __attribute__ ((warn_unused_result)); + +/*! @brief Get the socket file descriptor. + * + * 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 + * @ref pwmd_process() should be called to process status messages. + * + * @param pwm A handle. + * @param fd Set to the file descriptor of the associated handle. + * @return 0 on success or an error code. + * @see pwmd_process() + */ +gpg_error_t pwmd_get_fd(pwm_t *pwm, int *fd) __attribute__ ((warn_unused_result)); + +/*! @brief Get the file descriptor of the local pinentry method. + * + * This will allow polling of the file descriptor associated with the pipe of + * the forked pinentry from @ref pwmd_open_async2() or @ref pwmd_save_async2(). + * + * @param pwm A handle. + * @param fd Set to the file descriptor of the associated handle. + * @return 0 on success or an error code. + * @see pwmd_process(), pwmd_open_async2(), pwmd_save_async2() + */ +gpg_error_t pwmd_get_fd2(pwm_t *pwm, int *fd) __attribute__ ((warn_unused_result)); + +/*! @brief Check for a unparsed buffered line. + * + * A buffered line is a line that was read from the server but was not + * processed. This function determines if there is such a line. + * + * @param pwm A handle. + * @retval 0 if there is pending data. + * @retval GPG_ERR_NO_DATA if there is no pending data. + * @see pwmd_process() + */ +gpg_error_t pwmd_pending_line(pwm_t *pwm) __attribute__ ((warn_unused_result)); + +/*! @brief Set library options. + * + * Set a library option. + * + * @param pwm A handle. + * @param opt The option. + * @param ... The option value. + * @return 0 on success or an error code. + */ +gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...) __attribute__ ((warn_unused_result)); + +/*! @brief Open a file on the pwmd server. + * + * This will send the OPEN command to the server. + * + * @param pwm A handle. + * @param filename The filename to open. + * @return 0 on success or an error code. + */ +gpg_error_t pwmd_open(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result)); + +/*! @brief Open a file on the pwmd server asynchronously (fork method). + * + * This will send the OPEN command to the pwmd server. The difference from + * @ref pwmd_open() is that it will not block if a pinentry is needed for + * passphrase input. + * + * The difference from @ref pwmd_open_async() is that libpwmd will fork() a + * pinentry process rather than have pwmd use it's pinentry method. This + * may be needed if the passphrase isn't cached on a remote pwmd server and + * passphrase retrieval is needed. + * + * @ref pwmd_process() should be called until the command completes. + * + * @param pwm A handle. + * @param filename The filename to open. + * @return 0 on success or an error code. + * @see pwmd_process(), pinentry(1) + */ +gpg_error_t pwmd_open_async2(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result)); + +/*! @brief Open a file on the pwmd server asynchronously. + * + * This will send the OPEN command to the pwmd server. The difference from + * @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. + * + * @param pwm A handle. + * @param filename The filename to open. + * @return 0 on success or an error code. + * @see pwmd_process(), pinentry(1) + */ +gpg_error_t pwmd_open_async(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result)); + +/*! @brief Process an asynchronous function. + * + * After an asynchronous function has been called and has returned + * successfully, this function must be called to process the command to + * retrieve the result or return value. + * + * This function may also be called when not in a command to check for pending + * status messages sent from the server or to process a pending line. + * + * @param pwm A handle. + * @param rc Set to the return code of the command after ASYNC_DONE is + * returned. This value must be checked to determine if the command succeeded. + * @param result Set to the result of the command when @a rc is 0. Note that + * not all commands return a result. + * @retval ASYNC_DONE The command has completed. @a rc should be checked to + * 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() + */ +pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc, char **result) __attribute__ ((warn_unused_result)); + +/*! @brief Save a file on the pwmd server. + * + * This will send the SAVE command. + * + * @param pwm A handle. + * @return 0 on success or an error code. + */ +gpg_error_t pwmd_save(pwm_t *pwm) __attribute__ ((warn_unused_result)); + +/*! @brief Save a file on the pwmd server asynchronously (fork method). + * + * This will send the SAVE command to the pwmd server. The difference from + * @ref pwmd_save() is that it will not block if a pinentry is needed for + * passphrase input. + * + * The difference from @ref pwmd_save_async() is that libpwmd will fork() a + * pinentry process rather than have pwmd use it's pinentry method. This + * may be needed if the passphrase isn't cached on a remote pwmd server and + * passphrase retrieval is needed. + * + * @ref pwmd_process() should be called until the command completes. + * + * @param pwm A handle. + * @return 0 on success or an error code. + * @see pwmd_process(), pinentry(1) + */ +gpg_error_t pwmd_save_async2(pwm_t *pwm) __attribute__ ((warn_unused_result)); + +/*! @brief Save changes to a file on the pwmd server asynchronously. + * + * This will send the SAVE command to the pwmd server. The difference from + * @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. + * + * @param pwm A handle. + * @return 0 on success or an error code. + * @see pwmd_process(), pinentry(1) + */ +gpg_error_t pwmd_save_async(pwm_t *pwm) __attribute__ ((warn_unused_result)); + +/*! @brief Send a command to the pwmd server. + * + * Sends a command to the pwmd server. You should avoid sending the BYE + * command here because the assuan context will be freed and bad things will + * happen. Use @ref pwmd_close() instead. For commands that use an INQUIRE to + * receive data, @ref pwmd_inquire() should be used and not this function. + * + * @param pwm A handle. + * @param result The result of the command when successful which must be freed + * with @ref pwmd_free(). Note that not all commands return a result. + * @param cmd The command to send. + * @param ... The arguments to @a cmd. + * @return 0 on success or an error code. + */ +gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) __attribute__ ((warn_unused_result)); + +/*! @brief Send a command to the pwmd server. + * + * Like @ref pwmd_command() but uses an argument pointer instead. + * + * @param pwm A handle. + * @param result The result of the command when successful which must be freed + * with @ref pwmd_free(). Note that not all commands return a result. + * @param cmd The command to send. + * @param ap The arguments to @a cmd. + * @return 0 on success or an error code. + */ +gpg_error_t pwmd_command_ap(pwm_t *pwm, char **result, const char *cmd, + va_list ap) __attribute__ ((warn_unused_result)); + +/*! @brief Send data to a pwmd server. + * + * This lets commands that use an INQUIRE (STORE and INPORT) send data. + * + * @param pwm A handle. + * @param cmd The command that uses an INQUIRE. + * @param func A callback function which sets the data to be sent. + * @param data A user data pointer passed to the callback function @a func. + * @return 0 on success or an error code. + * @bug Should be rewritten to send an entire buffer and have a new function + * pwmd_inquire_async() to send the data in chunks. + */ +gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_fn func, + void *data) __attribute__ ((warn_unused_result)); + +/*! @brief Close a handle. + * + * This will close the connection to a pwmd server and free any resources + * associated with it. + * + * @param pwm A handle. + * @return Nothing. + */ +void pwmd_close(pwm_t *pwm); + +/*! @brief Free a previously allocated pointer. + * + * Use this function to free resources allocated by the other libpwmd memory + * functions. Do not use it to free your own allocations. + * + * The difference between the standard free() and this function is that + * this one will zero out the contents of the pointer before freeing it. + * + * @param ptr The pointer to deallocate. + * @return Nothing. + * @see pwmd_malloc(), pwmd_calloc(), pwmd_realloc(), pwmd_strdup(), + * pwmd_process(), pwmd_command() + */ +void pwmd_free(void *ptr); + +/*! @brief A wrapper around malloc. + * + * Like malloc(), but lets libpwmd keep track of the pointer. + * + * @param size The number of bytes to allocate. + * @return A newly allocated pointer or NULL if there wasn't enough memory. + * @see malloc(3), pwmd_free() + */ +void *pwmd_malloc(size_t size); + +/*! @brief A wrapper around calloc(). + * + * Like calloc(), but lets libpwmd keep track of the pointer. + * + * @param nmemb The number of bytes to allocate. + * @param size The number of bytes to allocate. + * @return A newly allocated pointer or NULL if there wasn't enough memory. + * @see calloc(3), pwmd_free() + */ +void *pwmd_calloc(size_t nmemb, size_t size); + +/*! @brief A wrapper around realloc(). + * + * Like realloc(), but lets libpwmd keep track of the pointer. Note that this + * function will try and allocate the entire @a size before freeing the + * original pointer and returning the new one. + * + * @param ptr The pointer to reallocate. + * @param size The new number of bytes to allocate. + * @return A newly allocated pointer or NULL if there wasn't enough memory. + * @see realloc(3), pwmd_free() + */ +void *pwmd_realloc(void *ptr, size_t size); + +/*! @brief A wrapper around strdup(). + * + * Like strdup(), but lets libpwmd keep track of the pointer. + * + * @param str The string to duplicate. + * @return A newly allocated character pointer or NULL if there wasn't + * enough memory. + * @see strdup(3), pwmd_free() + */ +char *pwmd_strdup(const char *str); + +/*! @def EPWMD_ERROR + * + * A general pwmd error with no suitable description. + */ +#define EPWMD_ERROR GPG_ERR_USER_1 + +/*! @def EPWMD_MAX_SLOTS + * + * There are no available cache slots for a new file. + * + * @bug Remove for pwmd 2.0. + */ +#define EPWMD_MAX_SLOTS GPG_ERR_USER_2 + +/*! @def EPWMD_LOOP + * + * A recursion loop was detected while processing a "target" attribute. + */ +#define EPWMD_LOOP GPG_ERR_USER_3 + +/*! @def EPWMD_NO_FILE + * + * A command required an open file but no file has been opened. + */ +#define EPWMD_NO_FILE GPG_ERR_USER_4 + +/*! @def EPWMD_LIBXML_ERROR + * + * An XML parse or other error occurred. The details can be found in the error + * description. + */ +#define EPWMD_LIBXML_ERROR GPG_ERR_USER_5 + +/*! @def EPWMD_FILE_MODIFIED + * + * The data file was modified by another client or externally while trying to + * process a command. + */ +#define EPWMD_FILE_MODIFIED GPG_ERR_USER_6 + +/*! @def EPWMD_MAX + * @if cond1 + * @endif + */ +#define EPWMD_MAX GPG_ERR_USER_7 + +/*! @brief Return a description of an error code. + * + * @param code The error code to describe. + * @return A character description of the error code. + * @see pwmd_strerror_r() + */ +const char *pwmd_strerror(gpg_error_t code); + +/*! @brief Return a description of an error code (thread-safe). + * + * This is a thread-safe version of @ref pwmd_strerror(). + * + * @param code The error code to describe. + * @param buf An allocated buffer to hold the error description. + * @param size The size of the allocated buffer @a buf. + * + * @retval 0 Success. + * @retval ERANGE @a size was not large enough to hold the entire description + * and @a buf is set to the truncated error string. + */ +int pwmd_strerror_r(gpg_error_t code, char *buf, size_t size); + +#ifdef __cplusplus +} +#endif + +#endif -- 2.11.4.GIT