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