See ChangeLog: Mon Nov 15 21:36:02 CET 1999 Werner Koch
[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 -z6 -d :pserver:anonymous@ftp.guug.de:/home/koch/cvs login
14
15 use the password "anonymous".  To check out the the complete
16 archive use:
17
18   cvs -z6 -d :pserver:anonymous@ftp.guug.de:/home/koch/cvs checkout gnupg
19
20 This service is provided to help you in hunting bugs and not to deliver
21 stable snapshots; it may happen that it even does not compile, so please
22 don't complain. CVS may put a high load on a server, so please don't poll
23 poll for new updates but wait for an announcement; to receive this you may
24 want to subscribe to:
25
26     gnupg-commit-watchers@gnupg.org
27
28 by sending a mail with subject "subscribe" to
29
30     gnupg-commit-watchers-request@gnupg.org
31
32
33 You must run scripts/autogen.sh before doing the ./configure,
34 as this creates some needed while which are not in the CVS.
35 autogen.sh should checks that you have all required tools
36 installed.
37
38
39 RSYNC access
40 ============
41 The FTP archive is also available by anonymous rsync.  A daily snapshot
42 of the CVS head revision is also available.  See rsync(1) and try
43 "rsync ftp.gnupg.org::" to see available resources.
44
45
46
47 Special Tools
48 =============
49 Documentation is based on the docbook DTD.  Actually we have only the
50 man page for now.  To build a man page you need the docbook-to-man
51 tool and all the other thinks needed for SGML processing.  Debian
52 comes with the docbook tools and you only need this docbook-to-man
53 script which is comes with gtk-doc or download it from
54 ftp.openit.de:/pub/devel/sgml.  If you don't have it everything
55 should still work fine but you will have only a dummy man page.
56
57
58 RFCs
59 ====
60
61 1423  Privacy Enhancement for Internet Electronic Mail:
62       Part III: Algorithms, Modes, and Identifiers.
63
64 1489  Registration of a Cyrillic Character Set.
65
66 1750  Randomness Recommendations for Security.
67
68 1991  PGP Message Exchange Formats.
69
70 2015  MIME Security with Pretty Good Privacy (PGP).
71
72 2144  The CAST-128 Encryption Algorithm.
73
74 2279  UTF-8, a transformation format of ISO 10646.
75
76 2440  OpenPGP.
77
78
79
80 Debug Flags
81 -----------
82 Use the option "--debug n" to output debug information. This option
83 can be used multiple times, all values are ORed; n maybe prefixed with
84 0x to use hex-values.
85
86      value  used for
87      -----  ----------------------------------------------
88       1     packet reading/writing
89       2     MPI details
90       4     ciphers and primes (may reveal sensitive data)
91       8     iobuf filter functions
92       16    iobuf stuff
93       32    memory allocation stuff
94       64    caching
95       128   show memory statistics at exit
96       256   trust verification stuff
97
98
99
100
101 Directory Layout
102 ----------------
103   ./            Readme, configure
104   ./scripts     Scripts needed by configure and others
105   ./doc         Documentation
106   ./util        General purpose utility function
107   ./mpi         Multi precision integer library
108   ./cipher      Cryptographic functions
109   ./g10         GnuPG application
110   ./tools       Some helper and demo programs
111   ./keybox      The keybox library (under construction)
112   ./gcrypt      Stuff needed to build libgcrypt (under construction)
113
114
115
116
117
118 Memory allocation
119 -----------------
120 Use only the functions:
121
122     m_alloc()
123     m_alloc_clear()
124     m_strdup()
125     m_free()
126
127 If you want to store a passphrase or some other sensitive data you may
128 want to use m_alloc_secure() instead of m_alloc(), as this puts the data
129 into a memory region which is protected from swapping (on some platforms).
130 m_free() works for both.  This functions will not return if there is not
131 enough memory available.
132
133
134
135 Logging
136 -------
137
138
139
140
141
142
143 Option parsing
144 ---------------
145 GNUPG does not use getopt or GNU getopt but functions of it's own.  See
146 util/argparse.c for details.  The advantage of these functions is that
147 it is more easy to display and maintain the help texts for the options.
148 The same option table is also used to parse resource files.
149
150
151
152 What is an IOBUF
153 ----------------
154 This is the data structure used for most I/O of gnupg.  It is similar
155 to System V Streams but much simpler.  Because OpenPGP messages are nested
156 in different ways; the use of such a system has big advantages.  Here is
157 an example, how it works:  If the parser sees a packet header with a partial
158 length, it pushes the block_filter onto the IOBUF to handle these partial
159 length packets: from now on you don't have to worry about this.  When it sees
160 a compressed packet it pushes the uncompress filter and the next read byte
161 is one which has already been uncompressed by this filter. Same goes for
162 enciphered packet, plaintext packets and so on.  The file g10/encode.c
163 might be a good staring point to see how it is used  - actually this is
164 the other way: constructing messages using pushed filters but it may be
165 easier to understand.
166
167
168 How to use the message digest functions
169 ---------------------------------------
170 cipher/md.c implements an interface to hash (message digest functions).
171
172 a) If you have a common part of data and some variable parts
173    and you need to hash of the concatenated parts, you can use this:
174         md = md_open(...)
175         md_write( md,  common_part )
176         md1 = md_copy( md )
177         md_write(md1, part1)
178         md_final(md1);
179         digest1 = md_read(md1)
180         md2 = md_copy( md )
181         md_write(md2, part2)
182         md_final(md2);
183         digest2 = md_read(md2)
184
185    An example are key signatures; the key packet is the common part
186    and the user-id packets are the variable parts.
187
188 b) If you need a running digest you should use this:
189         md = md_open(...)
190         md_write( md, part1 )
191         digest_of_part1 = md_digest( md );
192         md_write( md, part2 )
193         digest_of_part1_cat_part2 = md_digest( md );
194         ....
195
196 Both methods may be combined. [Please see the source for the real syntax]
197
198
199
200
201 How to use the cipher functions
202 -------------------------------
203 cipher/cipher.c implements the interface to symmetric encryption functions.
204 As usual you have a function to open a cipher (which returns a handle to be used
205 with all other functions), some functions to set the key and other stuff and
206 a encrypt and decrypt function which does the real work.  You probably know
207 how to work with files - so it should really be easy to work with these
208 functions.  Here is an example:
209
210     CIPHER_HANDLE hd;
211
212     hd = cipher_open( CIPHER_ALGO_TWOFISH, CIPHER_MODE_CFB, 0 );
213     if( !hd )
214         oops( use other function to check for the real error );
215     rc = cipher_setkey( hd, key256bit, 32 ) )
216     if( rc )
217         oops( weak key or something like this );
218     cipher_setiv( hd, some_IV_or_NULL_for_all_zeroes );
219     cipher_encrypt( hd, plain, cipher, size );
220     cipher_close( hd );
221
222
223
224 How to use the public key functions
225 -----------------------------------
226 cipher/pubkey.c implements the interface to asymmetric encryption and
227 signature functions. This is basically the same as with the symmetric
228 counterparts, but due to their nature it is a little bit more complicated.
229
230    [Give an example]
231
232