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