doc/HACKING

   1                       A Hacker's Guide to GNUPG
   2                    ================================
   3                    (Some notes on GNUPG internals.)
   4
   5       ************************************************************
   6       *** Please see the file HACKING in the GIT master branch ***
   7       ***            for up-to-date information.               ***
   8       ************************************************************
   9
  10
  11 * No more ChangeLog files
  12
  13 Do not modify any of the ChangeLog files in GnuPG.  Starting on
  14 December 1st, 2011 we put change information only in the GIT commit
  15 log, and generate a top-level ChangeLog file from logs at "make dist"
  16 time.  As such, there are strict requirements on the form of the
  17 commit log messages.  The old ChangeLog files have all be renamed to
  18 ChangeLog-2011
  19
  20
  21 * Commit log requirements
  22
  23 Your commit log should always start with a one-line summary, the second
  24 line should be blank, and the remaining lines are usually ChangeLog-style
  25 entries for all affected files.  However, it's fine -- even recommended --
  26 to write a few lines of prose describing the change, when the summary
  27 and ChangeLog entries don't give enough of the big picture.  Omit the
  28 leading TABs that you're used to seeing in a "real" ChangeLog file, but
  29 keep the maximum line length at 72 or smaller, so that the generated
  30 ChangeLog lines, each with its leading TAB, will not exceed 80 columns.
  31
  32
  33
  34
  35 ===> What follows is probably out of date <===
  36
  37
  38
  39 RFCs
  40 ====
  41
  42 1423  Privacy Enhancement for Internet Electronic Mail:
  43       Part III: Algorithms, Modes, and Identifiers.
  44
  45 1489  Registration of a Cyrillic Character Set.
  46
  47 1750  Randomness Recommendations for Security.
  48
  49 1991  PGP Message Exchange Formats.
  50
  51 2015  MIME Security with Pretty Good Privacy (PGP).
  52
  53 2144  The CAST-128 Encryption Algorithm.
  54
  55 2279  UTF-8, a transformation format of ISO 10646.
  56
  57 2440  OpenPGP.
  58
  59
  60
  61 Directory Layout
  62 ----------------
  63   ./           Readme, configure
  64   ./agent      Gpg-agent and related tools
  65   ./doc        Documentation
  66   ./doc        Documentation
  67   ./g10        Gpg program here called gpg2
  68   ./jnlib      Utility functions
  69   ./kbx        Keybox library
  70   ./scd        Smartcard daemon
  71   ./scripts    Scripts needed by configure and others
  72   ./sm         Gpgsm program
  73
  74
  75 Detailed Roadmap
  76 ----------------
  77 g10/gpg.c       Main module with option parsing and all the stuff you have
  78                 to do on startup.  Also has the exout handler and some
  79                 helper functions.
  80 g10/sign.c      Create signature and optionally encrypt
  81
  82 g10/parse-packet.c
  83 g10/build-packet.c
  84 g10/free-packet.c
  85                 Parsing and creating of OpenPGP message packets.
  86
  87 g10/getkey.c    Key selection code
  88 g10/pkclist.c   Build a list of public keys
  89 g10/skclist.c   Build a list of secret keys
  90 g10/ringedit.c  Keyring I/O
  91 g10/keydb.h
  92
  93 g10/keyid.c     Helper functions to get the keyid, fingerprint etc.
  94
  95
  96 g10/trustdb.c
  97 g10/trustdb.h
  98 g10/tdbdump.c
  99                Management of the trustdb.gpg
 100
 101 g10/compress.c Filter to handle compression
 102 g10/filter.h   Declarations for all filter functions
 103 g10/delkey.c   Delete a key
 104 g10/kbnode.c   Helper for the KBNODE linked list
 105 g10/main.h     Prototypes and some constants
 106 g10/mainproc.c Message processing
 107 g10/armor.c    Ascii armor filter
 108 g10/mdfilter.c Filter to calculate hashs
 109 g10/textfilter.c Filter to handle CR/LF and trailing white space
 110 g10/cipher.c   En-/Decryption filter
 111 g10/misc.c     Utlity functions
 112 g10/options.h  Structure with all the command line options
 113                and related constants
 114 g10/openfile.c Create/Open Files
 115 g10/tdbio.c    I/O handling for the trustdb.gpg
 116 g10/tdbio.h
 117 g10/hkp.h      Keyserver access
 118 g10/hkp.c
 119 g10/packet.h   Defintion of OpenPGP structures.
 120 g10/passphrase.c  Passphrase handling code
 121 g10/pubkey-enc.c
 122 g10/seckey-cert.c
 123 g10/seskey.c
 124 g10/import.c
 125 g10/export.c
 126 g10/comment.c
 127 g10/status.c
 128 g10/status.h
 129 g10/sign.c
 130 g10/plaintext.c
 131 g10/encr-data.c
 132 g10/encode.c
 133 g10/revoke.c
 134 g10/keylist.c
 135 g10/sig-check.c
 136 g10/signal.c
 137 g10/helptext.c
 138 g10/verify.c
 139 g10/decrypt.c
 140 g10/keyedit.c
 141 g10/dearmor.c
 142 g10/keygen.c
 143
 144
 145
 146 Memory allocation
 147 -----------------
 148 Use only the functions:
 149
 150     xmalloc
 151     xmalloc_secure
 152     xtrymalloc
 153     xtrymalloc_secure
 154     xcalloc
 155     xcalloc_secure
 156     xtrycalloc
 157     xtrycalloc_secure
 158     xrealloc
 159     xtryrealloc
 160     xstrdup
 161     xtrystrdup
 162     xfree
 163
 164
 165 The *secure versions allocated memory in the secure memory. That is,
 166 swapping out of this memory is avoided and is gets overwritten on
 167 free.  Use this for passphrases, session keys and other sensitive
 168 material.  This memory set aside for secure memory is linited to a few
 169 k.  In general the function don't print a memeory message and
 170 terminate the process if there is not enough memory available.  The
 171 "try" versions of the functions return NULL instead.
 172
 173
 174 Logging
 175 -------
 176
 177
 178
 179
 180
 181
 182 Option parsing
 183 ---------------
 184 GNUPG does not use getopt or GNU getopt but functions of it's own.  See
 185 util/argparse.c for details.  The advantage of these functions is that
 186 it is more easy to display and maintain the help texts for the options.
 187 The same option table is also used to parse resource files.
 188
 189
 190
 191 What is an IOBUF
 192 ----------------
 193 This is the data structure used for most I/O of gnupg.  It is similar
 194 to System V Streams but much simpler.  Because OpenPGP messages are nested
 195 in different ways; the use of such a system has big advantages.  Here is
 196 an example, how it works:  If the parser sees a packet header with a partial
 197 length, it pushes the block_filter onto the IOBUF to handle these partial
 198 length packets: from now on you don't have to worry about this.  When it sees
 199 a compressed packet it pushes the uncompress filter and the next read byte
 200 is one which has already been uncompressed by this filter. Same goes for
 201 enciphered packet, plaintext packets and so on.  The file g10/encode.c
 202 might be a good staring point to see how it is used  - actually this is
 203 the other way: constructing messages using pushed filters but it may be
 204 easier to understand.
 205
 206