Various fixes and new features.

Enhanced gpg-connect-agent.

5 files changed, 78 insertions, 181 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index ae2e15743..832753d66 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,12 @@
+2006-09-13  Werner Koch  <wk@g10code.com>
+
+	* gpg.texi (GPG Esoteric Options): Fixed typo in
+	--require-cross-certification and made it the default.
+
+2006-09-11  Werner Koch  <wk@g10code.com>
+
+	* HACKING: Cleaned up.
+
 2006-09-08  Werner Koch  <wk@g10code.com>
 
 	* yat2m.c (parse_file): Ignore @node lines immediately.
diff --git a/doc/HACKING b/doc/HACKING
index 5efb6c947..07f09c56b 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -6,76 +6,6 @@
 		   ===> Under construction <=======
 
 
-SOURCE FILES
-============
-
-Here is a list of directories with source files:
-
-jnlib/  utility functions
-kbx/    keybox library
-g10/    the gpg program here called gpg2
-sm/     the gpgsm program
-agent/  the gpg-agent
-scd/    the smartcard daemon
-doc/    documentation
-
-
-
-
-CVS Access
-==========
-
-NOTE: CVS access has been disabled while we are migrating to Subversion.
-Watch www.gnupg.org for instarctions on how to use the Subversion repository.
-
-Anonymous read-only CVS access is available:
-
-  cvs -z3 -d :pserver:anoncvs@cvs.gnupg.org:/cvs/gnupg login
-
-use the password "anoncvs".  To check out the the complete
-archive use:
-
-  cvs -z3 -d :pserver:anoncvs@cvs.gnupg.org:/cvs/gnupg \
-        checkout -R STABLE-BRANCH-1-0 gnupg
-
-This service is provided to help you in hunting bugs and not to deliver
-stable snapshots; it may happen that it even does not compile, so please
-don't complain. CVS may put a high load on a server, so please don't poll
-poll for new updates but wait for an announcement; to receive this you may
-want to subscribe to:
-
-    gnupg-commit-watchers@gnupg.org
-
-by sending a mail with subject "subscribe" to
-
-    gnupg-commit-watchers-request@gnupg.org
-
-
-You must run scripts/autogen.sh before doing the ./configure,
-as this creates some needed while which are not in the CVS.
-autogen.sh should checks that you have all required tools
-installed.
-
-
-RSYNC access
-============
-The FTP archive is also available by anonymous rsync.  A daily snapshot
-of the CVS head revision is also available.  See rsync(1) and try
-"rsync ftp.gnupg.org::" to see available resources.
-
-
-
-Special Tools
-=============
-Documentation is based on the docbook DTD.  Actually we have only the
-man page for now.  To build a man page you need the docbook-to-man
-tool and all the other thinks needed for SGML processing.  Debian
-comes with the docbook tools and you only need this docbook-to-man
-script which is comes with gtk-doc or download it from
-ftp.openit.de:/pub/devel/sgml.	If you don't have it everything
-should still work fine but you will have only a dummy man page.
-
-
 RFCs
 ====
 
@@ -98,44 +28,23 @@ RFCs
 
 
 
-Debug Flags
------------
-Use the option "--debug n" to output debug information. This option
-can be used multiple times, all values are ORed; n maybe prefixed with
-0x to use hex-values.
-
-     value  used for
-     -----  ----------------------------------------------
-      1     packet reading/writing
-      2     MPI details
-      4     ciphers and primes (may reveal sensitive data)
-      8     iobuf filter functions
-      16    iobuf stuff
-      32    memory allocation stuff
-      64    caching
-      128   show memory statistics at exit
-      256   trust verification stuff
-
-
-
-
 Directory Layout
 ----------------
-  ./		Readme, configure
-  ./scripts	Scripts needed by configure and others
-  ./doc 	Documentation
-  ./util	General purpose utility function
-  ./mpi 	Multi precision integer library
-  ./cipher	Cryptographic functions
-  ./g10 	GnuPG application
-  ./tools	Some helper and demo programs
-  ./keybox	The keybox library (under construction)
-  ./gcrypt	Stuff needed to build libgcrypt (under construction)
+  ./	       Readme, configure
+  ./agent      Gpg-agent and related tools
+  ./doc        Documentation
+  ./doc        Documentation
+  ./g10        Gpg program here called gpg2
+  ./jnlib      Utility functions
+  ./kbx        Keybox library
+  ./scd        Smartcard daemon
+  ./scripts    Scripts needed by configure and others
+  ./sm         Gpgsm program
 
 
 Detailed Roadmap
 ----------------
-g10/g10.c	Main module with option parsing and all the stuff you have
+g10/gpg.c	Main module with option parsing and all the stuff you have
 		to do on startup.  Also has the exout handler and some
 		helper functions.
 g10/sign.c      Create signature and optionally encrypt
@@ -208,17 +117,28 @@ Memory allocation
 -----------------
 Use only the functions:
 
-    m_alloc()
-    m_alloc_clear()
-    m_strdup()
-    m_free()
-
-If you want to store a passphrase or some other sensitive data you may
-want to use m_alloc_secure() instead of m_alloc(), as this puts the data
-into a memory region which is protected from swapping (on some platforms).
-m_free() works for both.  This functions will not return if there is not
-enough memory available.
-
+    xmalloc
+    xmalloc_secure
+    xtrymalloc
+    xtrymalloc_secure
+    xcalloc
+    xcalloc_secure
+    xtrycalloc
+    xtrycalloc_secure
+    xrealloc
+    xtryrealloc
+    xstrdup
+    xtrystrdup
+    xfree
+
+
+The *secure versions allocated memory in the secure memory. That is,
+swapping out of this memory is avoided and is gets overwritten on
+free.  Use this for passphrases, session keys and other sensitive
+material.  This memory set aside for secure memory is linited to a few
+k.  In general the function don't print a memeory message and
+terminate the process if there is not enough memory available.  The
+"try" versions of the functions return NULL instead.
 
 
 Logging
@@ -254,68 +174,3 @@ the other way: constructing messages using pushed filters but it may be
 easier to understand.
 
 
-How to use the message digest functions
----------------------------------------
-cipher/md.c implements an interface to hash (message digest functions).
-
-a) If you have a common part of data and some variable parts
-   and you need to hash of the concatenated parts, you can use this:
-	md = md_open(...)
-	md_write( md,  common_part )
-	md1 = md_copy( md )
-	md_write(md1, part1)
-	md_final(md1);
-	digest1 = md_read(md1)
-	md2 = md_copy( md )
-	md_write(md2, part2)
-	md_final(md2);
-	digest2 = md_read(md2)
-
-   An example are key signatures; the key packet is the common part
-   and the user-id packets are the variable parts.
-
-b) If you need a running digest you should use this:
-	md = md_open(...)
-	md_write( md, part1 )
-	digest_of_part1 = md_digest( md );
-	md_write( md, part2 )
-	digest_of_part1_cat_part2 = md_digest( md );
-	....
-
-Both methods may be combined. [Please see the source for the real syntax]
-
-
-
-
-How to use the cipher functions
--------------------------------
-cipher/cipher.c implements the interface to symmetric encryption functions.
-As usual you have a function to open a cipher (which returns a handle to be used
-with all other functions), some functions to set the key and other stuff and
-a encrypt and decrypt function which does the real work.  You probably know
-how to work with files - so it should really be easy to work with these
-functions.  Here is an example:
-
-    CIPHER_HANDLE hd;
-
-    hd = cipher_open( CIPHER_ALGO_TWOFISH, CIPHER_MODE_CFB, 0 );
-    if( !hd )
-	oops( use other function to check for the real error );
-    rc = cipher_setkey( hd, key256bit, 32 ) )
-    if( rc )
-	oops( weak key or something like this );
-    cipher_setiv( hd, some_IV_or_NULL_for_all_zeroes );
-    cipher_encrypt( hd, plain, cipher, size );
-    cipher_close( hd );
-
-
-
-How to use the public key functions
------------------------------------
-cipher/pubkey.c implements the interface to asymmetric encryption and
-signature functions. This is basically the same as with the symmetric
-counterparts, but due to their nature it is a little bit more complicated.
-
-   [Give an example]
-
-
diff --git a/doc/gpg.texi b/doc/gpg.texi
index 219ff15f4..f744c1a22 100644
--- a/doc/gpg.texi
+++ b/doc/gpg.texi
@@ -2178,12 +2178,11 @@ content of an encrypted message; using this option you can do this without
 handing out the secret key.
 
 @item --require-cross-certification
-@itemx --no-require-certification
+@itemx --no-require-cross-certification
 When verifying a signature made from a subkey, ensure that the cross
 certification "back signature" on the subkey is present and valid.
 This protects against a subtle attack against subkeys that can sign.
-Currently defaults to --no-require-cross-certification, but will be
-changed to --require-cross-certification in the future.
+Defaults to --require-cross-certification for @command{gpg2}.
 
 @item --ask-sig-expire
 @itemx --no-ask-sig-expire
diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi
index 5de9efbe9..a7a24022f 100644
--- a/doc/gpgsm.texi
+++ b/doc/gpgsm.texi
@@ -184,11 +184,20 @@ is available.
 List certificates matching @var{pattern} using an external server.  This
 utilizes the @code{dirmngr} service.  
 
+@item --list-chain
+@opindex list-chain
+Same as @option{--list-keys} but also prints all keys making up the chain.
+
+
 @item --dump-keys
 @opindex dump-keys
 List all available certificates stored in the local key database using a
 format useful mainly for debugging.
 
+@item --dump-chain
+@opindex dump-chain
+Same as @option{--dump-keys} but also prints all keys making up the chain.
+
 @item --dump-secret-keys
 @opindex dump-secret-keys
 List all available certificates for which a corresponding a secret key
diff --git a/doc/tools.texi b/doc/tools.texi
index 4e9a80d8e..dec548905 100644
--- a/doc/tools.texi
+++ b/doc/tools.texi
@@ -989,6 +989,22 @@ Connect to socket @var{name} assuming this is an Assuan style server.
 Do not run any special initializations or environment checks.  This may
 be used to directly connect to any Assuan style socket server.
 
+@item -E
+@itemx --exec
+@opindex exec
+Take the rest of the command line as a program and it's arguments and
+execute it as an assuan server. Here is how you would run @command{gpgsm}:
+@smallexample
+ gpg-connect-agent --exec gpgsm --server
+@end smallexample
+
+
+@item --no-ext-connect
+@opindex no-ext-connect
+When using @option{-S} or @option{--exec}, @command{gpg-connect-agent}
+connects to the assuan server in extended mode to allow descriptor
+passing.  This option makes it use the old mode.
+
 @end table
 
 @mansect control commands
@@ -1020,6 +1036,15 @@ Print all definitions
 @item /cleardef
 Delete all definitions
 
+@item /sendfd @var{file} @var{mode}
+Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
+mode string) and send the file descriptor to the server.  This is
+usually followed by a command like @code{INPUT FD} to set the
+input source for other commands.
+
+@item /recvfd
+Not yet implemented.
+
 @item /help
 Print a list of available control commands.