gnupg/doc/HACKING

		      A Hacker's Guide to GNUPG
		   ================================
		   (Some notes on GNUPG internals.)


		   ===> Under construction <=======


CVS Access
==========
Anonymous read-only CVS access is available:

  cvs -z6 -d :pserver:anonymous@ftp.guug.de:/home/koch/cvs login

use the password "anonymous".  To check out the the complete
archive use:

  cvs -z6 -d :pserver:anonymous@ftp.guug.de:/home/koch/cvs checkout 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@isil.d.shuttle.de

by sending a mail with "subscribe" in the body to

    gnupg-commit-watchers-request@isil.d.shuttle.de


Please run scripts/autogen.sh to create some required files.


RFCs
====

1423  Privacy Enhancement for Internet Electronic Mail:
      Part III: Algorithms, Modes, and Identifiers.

1489  Registration of a Cyrillic Character Set.

1750  Randomness Recommendations for Security.

1991  PGP Message Exchange Formats.

2015  MIME Security with Pretty Good Privacy (PGP).

2144  The CAST-128 Encryption Algorithm.

2279  UTF-8, a transformation format of ISO 10646.

2440  OpenPGP.



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
  ./gcrypt	Stuff needed to build libgcrypt





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 functions 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 similar
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 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
-------------------------------




How to use the public key functions
-----------------------------------