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