doc/HACKING

   1                       A Hacker's Guide to GNUPG
   2                    ================================
   3                    (Some notes on GNUPG internals.)
   4
   5
   6                    ===> Under construction <=======
   7
   8
   9 CVS Access
  10 ==========
  11
  12 NOTE: CVS access has been disabled while we are migrating to Subversion.
  13 Watch www.gnupg.org for instarctions on how to use the Subversion repository.
  14
  15 Anonymous read-only CVS access is available:
  16
  17   cvs -z3 -d :pserver:anoncvs@cvs.gnupg.org:/cvs/gnupg login
  18
  19 use the password "anoncvs".  To check out the the complete
  20 archive use:
  21
  22   cvs -z3 -d :pserver:anoncvs@cvs.gnupg.org:/cvs/gnupg \
  23         checkout -R STABLE-BRANCH-1-0 gnupg
  24
  25 This service is provided to help you in hunting bugs and not to deliver
  26 stable snapshots; it may happen that it even does not compile, so please
  27 don't complain. CVS may put a high load on a server, so please don't poll
  28 poll for new updates but wait for an announcement; to receive this you may
  29 want to subscribe to:
  30
  31     gnupg-commit-watchers@gnupg.org
  32
  33 by sending a mail with subject "subscribe" to
  34
  35     gnupg-commit-watchers-request@gnupg.org
  36
  37
  38 You must run scripts/autogen.sh before doing the ./configure,
  39 as this creates some needed while which are not in the CVS.
  40 autogen.sh should checks that you have all required tools
  41 installed.
  42
  43
  44 RSYNC access
  45 ============
  46 The FTP archive is also available by anonymous rsync.  A daily snapshot
  47 of the CVS head revision is also available.  See rsync(1) and try
  48 "rsync ftp.gnupg.org::" to see available resources.
  49
  50
  51
  52 Special Tools
  53 =============
  54 Documentation is based on the docbook DTD.  Actually we have only the
  55 man page for now.  To build a man page you need the docbook-to-man
  56 tool and all the other thinks needed for SGML processing.  Debian
  57 comes with the docbook tools and you only need this docbook-to-man
  58 script which is comes with gtk-doc or download it from
  59 ftp.openit.de:/pub/devel/sgml.  If you don't have it everything
  60 should still work fine but you will have only a dummy man page.
  61
  62
  63 RFCs
  64 ====
  65
  66 1423  Privacy Enhancement for Internet Electronic Mail:
  67       Part III: Algorithms, Modes, and Identifiers.
  68
  69 1489  Registration of a Cyrillic Character Set.
  70
  71 1750  Randomness Recommendations for Security.
  72
  73 1991  PGP Message Exchange Formats.
  74
  75 2015  MIME Security with Pretty Good Privacy (PGP).
  76
  77 2144  The CAST-128 Encryption Algorithm.
  78
  79 2279  UTF-8, a transformation format of ISO 10646.
  80
  81 2440  OpenPGP.
  82
  83
  84
  85 Debug Flags
  86 -----------
  87 Use the option "--debug n" to output debug information. This option
  88 can be used multiple times, all values are ORed; n maybe prefixed with
  89 0x to use hex-values.
  90
  91      value  used for
  92      -----  ----------------------------------------------
  93       1     packet reading/writing
  94       2     MPI details
  95       4     ciphers and primes (may reveal sensitive data)
  96       8     iobuf filter functions
  97       16    iobuf stuff
  98       32    memory allocation stuff
  99       64    caching
 100       128   show memory statistics at exit
 101       256   trust verification stuff
 102
 103
 104
 105
 106 Directory Layout
 107 ----------------
 108   ./            Readme, configure
 109   ./scripts     Scripts needed by configure and others
 110   ./doc         Documentation
 111   ./util        General purpose utility function
 112   ./mpi         Multi precision integer library
 113   ./cipher      Cryptographic functions
 114   ./g10         GnuPG application
 115   ./tools       Some helper and demo programs
 116   ./keybox      The keybox library (under construction)
 117   ./gcrypt      Stuff needed to build libgcrypt (under construction)
 118
 119
 120 Detailed Roadmap
 121 ----------------
 122 g10/g10.c       Main module with option parsing and all the stuff you have
 123                 to do on startup.  Also has the exout handler and some
 124                 helper functions.
 125 g10/sign.c      Create signature and optionally encrypt
 126
 127 g10/parse-packet.c
 128 g10/build-packet.c
 129 g10/free-packet.c
 130                 Parsing and creating of OpenPGP message packets.
 131
 132 g10/getkey.c    Key selection code
 133 g10/pkclist.c   Build a list of public keys
 134 g10/skclist.c   Build a list of secret keys
 135 g10/ringedit.c  Keyring I/O
 136 g10/keydb.h
 137
 138 g10/keyid.c     Helper functions to get the keyid, fingerprint etc.
 139
 140
 141 g10/trustdb.c
 142 g10/trustdb.h
 143 g10/tdbdump.c
 144                Management of the trustdb.gpg
 145
 146 g10/compress.c Filter to handle compression
 147 g10/filter.h   Declarations for all filter functions
 148 g10/delkey.c   Delete a key
 149 g10/kbnode.c   Helper for the KBNODE linked list
 150 g10/main.h     Prototypes and some constants
 151 g10/mainproc.c Message processing
 152 g10/armor.c    Ascii armor filter
 153 g10/mdfilter.c Filter to calculate hashs
 154 g10/textfilter.c Filter to handle CR/LF and trailing white space
 155 g10/cipher.c   En-/Decryption filter
 156 g10/misc.c     Utlity functions
 157 g10/options.h  Structure with all the command line options
 158                and related constants
 159 g10/openfile.c Create/Open Files
 160 g10/tdbio.c    I/O handling for the trustdb.gpg
 161 g10/tdbio.h
 162 g10/hkp.h      Keyserver access
 163 g10/hkp.c
 164 g10/packet.h   Defintion of OpenPGP structures.
 165 g10/passphrase.c  Passphrase handling code
 166 g10/pubkey-enc.c
 167 g10/seckey-cert.c
 168 g10/seskey.c
 169 g10/import.c
 170 g10/export.c
 171 g10/comment.c
 172 g10/status.c
 173 g10/status.h
 174 g10/sign.c
 175 g10/plaintext.c
 176 g10/encr-data.c
 177 g10/encode.c
 178 g10/revoke.c
 179 g10/keylist.c
 180 g10/sig-check.c
 181 g10/signal.c
 182 g10/helptext.c
 183 g10/verify.c
 184 g10/decrypt.c
 185 g10/keyedit.c
 186 g10/dearmor.c
 187 g10/keygen.c
 188
 189
 190
 191 Memory allocation
 192 -----------------
 193 Use only the functions:
 194
 195     m_alloc()
 196     m_alloc_clear()
 197     m_strdup()
 198     m_free()
 199
 200 If you want to store a passphrase or some other sensitive data you may
 201 want to use m_alloc_secure() instead of m_alloc(), as this puts the data
 202 into a memory region which is protected from swapping (on some platforms).
 203 m_free() works for both.  This functions will not return if there is not
 204 enough memory available.
 205
 206
 207
 208 Logging
 209 -------
 210
 211
 212
 213
 214
 215
 216 Option parsing
 217 ---------------
 218 GNUPG does not use getopt or GNU getopt but functions of it's own.  See
 219 util/argparse.c for details.  The advantage of these functions is that
 220 it is more easy to display and maintain the help texts for the options.
 221 The same option table is also used to parse resource files.
 222
 223
 224
 225 What is an IOBUF
 226 ----------------
 227 This is the data structure used for most I/O of gnupg.  It is similar
 228 to System V Streams but much simpler.  Because OpenPGP messages are nested
 229 in different ways; the use of such a system has big advantages.  Here is
 230 an example, how it works:  If the parser sees a packet header with a partial
 231 length, it pushes the block_filter onto the IOBUF to handle these partial
 232 length packets: from now on you don't have to worry about this.  When it sees
 233 a compressed packet it pushes the uncompress filter and the next read byte
 234 is one which has already been uncompressed by this filter. Same goes for
 235 enciphered packet, plaintext packets and so on.  The file g10/encode.c
 236 might be a good staring point to see how it is used  - actually this is
 237 the other way: constructing messages using pushed filters but it may be
 238 easier to understand.
 239
 240
 241 How to use the message digest functions
 242 ---------------------------------------
 243 cipher/md.c implements an interface to hash (message digest functions).
 244
 245 a) If you have a common part of data and some variable parts
 246    and you need to hash of the concatenated parts, you can use this:
 247         md = md_open(...)
 248         md_write( md,  common_part )
 249         md1 = md_copy( md )
 250         md_write(md1, part1)
 251         md_final(md1);
 252         digest1 = md_read(md1)
 253         md2 = md_copy( md )
 254         md_write(md2, part2)
 255         md_final(md2);
 256         digest2 = md_read(md2)
 257
 258    An example are key signatures; the key packet is the common part
 259    and the user-id packets are the variable parts.
 260
 261 b) If you need a running digest you should use this:
 262         md = md_open(...)
 263         md_write( md, part1 )
 264         digest_of_part1 = md_digest( md );
 265         md_write( md, part2 )
 266         digest_of_part1_cat_part2 = md_digest( md );
 267         ....
 268
 269 Both methods may be combined. [Please see the source for the real syntax]
 270
 271
 272
 273
 274 How to use the cipher functions
 275 -------------------------------
 276 cipher/cipher.c implements the interface to symmetric encryption functions.
 277 As usual you have a function to open a cipher (which returns a handle to be used
 278 with all other functions), some functions to set the key and other stuff and
 279 a encrypt and decrypt function which does the real work.  You probably know
 280 how to work with files - so it should really be easy to work with these
 281 functions.  Here is an example:
 282
 283     CIPHER_HANDLE hd;
 284
 285     hd = cipher_open( CIPHER_ALGO_TWOFISH, CIPHER_MODE_CFB, 0 );
 286     if( !hd )
 287         oops( use other function to check for the real error );
 288     rc = cipher_setkey( hd, key256bit, 32 ) )
 289     if( rc )
 290         oops( weak key or something like this );
 291     cipher_setiv( hd, some_IV_or_NULL_for_all_zeroes );
 292     cipher_encrypt( hd, plain, cipher, size );
 293     cipher_close( hd );
 294
 295
 296
 297 How to use the public key functions
 298 -----------------------------------
 299 cipher/pubkey.c implements the interface to asymmetric encryption and
 300 signature functions. This is basically the same as with the symmetric
 301 counterparts, but due to their nature it is a little bit more complicated.
 302
 303    [Give an example]
 304
 305