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