*** empty log message ***

3 files changed, 138 insertions, 11 deletions

diff --git a/doc/HACKING b/doc/HACKING
new file mode 100644
index 000000000..27faa87c5
--- /dev/null
+++ b/doc/HACKING
@@ -0,0 +1,92 @@
+			  A Hacker's Guide to GNUPG
+		       ================================
+		       (Some notes on GNUPG internals.)
+
+
+
+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.
+
+
+
+Logging
+-------
+
+
+
+
+
+
+Option parsing
+---------------
+GNUPG does not use getopt or GNU getopt but functions of it's own.  See
+util/argparse.c for details.  The advantage of these funtions is that
+it is more easy to display and maintain the help texts for the options.
+The same option table is also used to parse resource files.
+
+
+
+What is an iobuf
+----------------
+This is the data structure used for most I/O of gnupg.	It is similiar
+to System V Streams but much simpler.  It should be replaced by a cleaner
+and faster implementation.  We are doing to much copying and the semantics
+of "filter" removing are not very clean.  EOF handling is also a problem.
+
+
+
+How to use the message digest functions
+---------------------------------------
+cipher/md.c implements an interface to hash (message diesgt 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
+-------------------------------
+
+
+
+
+How to use the public key functions
+-----------------------------------
+
+
diff --git a/doc/Makefile.am b/doc/Makefile.am
index dc2ee585b..9c83575b0 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,9 +1,18 @@
 ## Process this file with automake to create Makefile.in
 
-EXTRA_DIST = DETAILS rfcs gpg.1pod gpg.1 FAQ
+EXTRA_DIST = DETAILS rfcs gpg.1pod gpg.1 FAQ  HACKING
 
 man_MANS = gpg.1
 
+
+
+install-data-hook:
+	 if test -f $(man1dir)/gpgm.1; then rm $(man1dir)/gpgm.1; fi
+	 ln -s $(man1dir)/gpg.1 $(man1dir)/gpgm.1 \
+	    || ln $(man1dir)/gpg.1 $(man1dir)/gpgm.1
+
+
+
 %: %pod
 	 pod2man $< --section=`echo $@ | sed 's/^.*(?)$$/$$&/'`\
 		    --release="`date -r $< '+%d %b %Y'`"\
diff --git a/doc/gpg.1pod b/doc/gpg.1pod
index 93b1a199f..40c930b45 100644
--- a/doc/gpg.1pod
+++ b/doc/gpg.1pod
@@ -75,7 +75,7 @@ B<-k> [I<username>] [I<keyring>]
     B<-kvc>   List fingerprints
     B<-kvvc>  List fingerprints and signatures
 
-B<--list-keys>	[I<names>]
+B<--list-keys>  [I<names>]
     List all keys from the public keyrings, or just the
     ones given on the command line.
 
@@ -83,7 +83,7 @@ B<--list-secret-keys> [I<names>]
     List all keys from the secret keyrings, or just the
     ones given on the command line.
 
-B<--list-sigs>	[I<names>]
+B<--list-sigs>  [I<names>]
     Same as B<--list-keys>, but the signatures are listed
     too.
 
@@ -201,7 +201,7 @@ B<--import-ownertrust> [I<filename>]
 
 Long options can be put in an options file (default F<~/.gnupg/options>);
 do not write the 2 dashes, but simply the name of the option and any
-arguments if required.	Lines with a hash as the first non-white-space
+arguments if required.  Lines with a hash as the first non-white-space
 character are ignored. Commands may be put in this file too, but that
 does not make sense.
 
@@ -324,6 +324,26 @@ B<--digest-algo> I<name>
     program with the option B<--verbose> yields a list of
     supported algorithms.
 
+B<--s2k-cipher-algo> I<name>
+    Use I<name> as the cipher algorithm used to protect secret
+    keys.  The default cipher is BLOWFISH.  This cipher is
+    also used for conventional encryption if B<--cipher-algo>
+    is not given.
+
+B<--s2k-digest-algo> I<name>
+    Use I<name> as the digest algorithm used to mangle the
+    passphrases.  The default algorithm is RIPE-MD-160.
+    This digest algorithm is also used for conventional
+    encryption if B<--digest-algo> is not given.
+
+B<--s2k-mode> I<number>
+    Selects how passphrases are mangled: A number of I<0>
+    uses the plain passphrase (which is not recommended),
+    a I<1> (default) adds a salt to the passphrase and
+    I<3> interates the whole process a couple of times.
+    Unless -B<--rfc1991> is used, this mode is also used
+    for conventional encryption.
+
 B<--compress-algo> I<number>
     Use compress algorithm I<number>. Default is I<2> which is
     RFC1950 compression; you may use I<1> to use the old zlib
@@ -333,6 +353,12 @@ B<--compress-algo> I<number>
     If this is not used the OpenPGP behaviour is used; i.e.
     the compression algorith is selected from the preferences.
 
+B<--digest-algo> I<name>
+    Use I<name> as message digest algorithm. Running the
+    program with the option B<--verbose> yields a list of
+    supported algorithms.
+
+
 B<--throw-keyid>
     Do not put the keyid into encrypted packets.  This option
     hides the receiver of the message and is a countermeasure
@@ -385,11 +411,11 @@ a signature was bad and other errorcode for fatal errors.
 
 =head1 EXAMPLES
 
-  -se -r Bob [file]	     sign and encrypt for user Bob
-  -sat [file]		     make a clear text signature
-  -sb  [file]		     make a detached signature
-  -k   [userid] 	     show keys
-  -kc  [userid] 	     show fingerprint
+  -se -r Bob [file]          sign and encrypt for user Bob
+  -sat [file]                make a clear text signature
+  -sb  [file]                make a detached signature
+  -k   [userid]              show keys
+  -kc  [userid]              show fingerprint
 
 =head1 ENVIRONMENT
 
@@ -404,13 +430,13 @@ F<~/.gnupg/pubring.gpg>     The public keyring
 
 F<~/.gnupg/trustdb.gpg>     The trust database
 
-F<~/.gnupg/options>	    May contain options
+F<~/.gnupg/options>         May contain options
 
 F</usr[/local]/lib/gnupg/>  Default location for extensions
 
 =head1 SEE ALSO
 
-gpgm(1)  gpgd(1)
+gpg(1)  gpgm(1)
 
 
 =head1 WARNINGS