Edit File: HACKING
A Hacker's Guide to GNUPG ================================ (Some notes on GNUPG internals.) ************************************************************ *** Please see the file HACKING in the GIT master branch *** *** for up-to-date information. *** ************************************************************ * 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.