gnupg/doc/HACKING

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


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


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.



Directory Layout
----------------
  ./	       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/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

g10/parse-packet.c
g10/build-packet.c
g10/free-packet.c
		Parsing and creating of OpenPGP message packets.

g10/getkey.c    Key selection code
g10/pkclist.c   Build a list of public keys
g10/skclist.c   Build a list of secret keys
g10/ringedit.c  Keyring I/O
g10/keydb.h

g10/keyid.c	Helper functions to get the keyid, fingerprint etc.


g10/trustdb.c    
g10/trustdb.h
g10/tdbdump.c
               Management of the trustdb.gpg

g10/compress.c Filter to handle compression
g10/filter.h   Declarations for all filter functions
g10/delkey.c   Delete a key
g10/kbnode.c   Helper for the KBNODE linked list
g10/main.h     Prototypes and some constants
g10/mainproc.c Message processing
g10/armor.c    Ascii armor filter 
g10/mdfilter.c Filter to calculate hashs
g10/textfilter.c Filter to handle CR/LF and trailing white space
g10/cipher.c   En-/Decryption filter
g10/misc.c     Utlity functions
g10/options.h  Structure with all the command line options
               and related constants
g10/openfile.c Create/Open Files
g10/tdbio.c    I/O handling for the trustdb.gpg
g10/tdbio.h
g10/hkp.h      Keyserver access
g10/hkp.c
g10/packet.h   Defintion of OpenPGP structures.
g10/passphrase.c  Passphrase handling code
g10/pubkey-enc.c  
g10/seckey-cert.c
g10/seskey.c
g10/import.c
g10/export.c
g10/comment.c
g10/status.c
g10/status.h
g10/sign.c
g10/plaintext.c
g10/encr-data.c
g10/encode.c
g10/revoke.c
g10/keylist.c
g10/sig-check.c
g10/signal.c
g10/helptext.c
g10/verify.c
g10/decrypt.c
g10/keyedit.c
g10/dearmor.c
g10/keygen.c



Memory allocation
-----------------
Use only the functions:

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






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.  Because OpenPGP messages are nested
in different ways; the use of such a system has big advantages.  Here is
an example, how it works:  If the parser sees a packet header with a partial
length, it pushes the block_filter onto the IOBUF to handle these partial
length packets: from now on you don't have to worry about this.  When it sees
a compressed packet it pushes the uncompress filter and the next read byte
is one which has already been uncompressed by this filter. Same goes for
enciphered packet, plaintext packets and so on.  The file g10/encode.c
might be a good staring point to see how it is used  - actually this is
the other way: constructing messages using pushed filters but it may be
easier to understand.