gnupg/doc/HACKING

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


* No more ChangeLog files

Do not modify any of the ChangeLog files in GnuPG.  Starting on
December 1st, 2011 we put change information only in the GIT commit
log, and generate a top-level ChangeLog file from logs at "make dist"
time.  As such, there are strict requirements on the form of the
commit log messages.  The old ChangeLog files have all be renamed to
ChangeLog-2011


* Commit log requirements

Your commit log should always start with a one-line summary, the second
line should be blank, and the remaining lines are usually ChangeLog-style
entries for all affected files.  However, it's fine -- even recommended --
to write a few lines of prose describing the change, when the summary
and ChangeLog entries don't give enough of the big picture.  Omit the
leading TABs that you're used to seeing in a "real" ChangeLog file, but
keep the maximum line length at 72 or smaller, so that the generated
ChangeLog lines, each with its leading TAB, will not exceed 80 columns.
If you want to add text which shall not be copied to the ChangeLog,
separate it by a line consisting of two dashes at the begin of a line.


===> What follows is probably out of date <===


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 (obsolete)

2144  The CAST-128 Encryption Algorithm.

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

2440  OpenPGP (obsolete).

3156  MIME Security with Pretty Good Privacy (PGP).

4880  Current OpenPGP specification.



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.