Added missing file
[gnupg.git] / 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