doc/HACKING

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