See ChangeLog: Tue Mar 2 10:38:42 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@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 RFCs
37 ====
38
39 1423  Privacy Enhancement for Internet Electronic Mail:
40       Part III: Algorithms, Modes, and Identifiers.
41
42 1489  Registration of a Cyrillic Character Set.
43
44 1750  Randomness Recommendations for Security.
45
46 1991  PGP Message Exchange Formats.
47
48 2015  MIME Security with Pretty Good Privacy (PGP).
49
50 2144  The CAST-128 Encryption Algorithm.
51
52 2279  UTF-8, a transformation format of ISO 10646.
53
54 2440  OpenPGP.
55
56
57
58 Debug Flags
59 -----------
60 Use the option "--debug n" to output debug information. This option
61 can be used multiple times, all values are ORed; n maybe prefixed with
62 0x to use hex-values.
63
64      value  used for
65      -----  ----------------------------------------------
66       1     packet reading/writing
67       2     MPI details
68       4     ciphers and primes (may reveal sensitive data)
69       8     iobuf filter functions
70       16    iobuf stuff
71       32    memory allocation stuff
72       64    caching
73       128   show memory statistics at exit
74       256   trust verification stuff
75
76
77
78
79 Directory Layout
80 ----------------
81   ./            Readme, configure
82   ./scripts     Scripts needed by configure and others
83   ./doc         Documentation
84   ./util        General purpose utility function
85   ./mpi         Multi precision integer library
86   ./cipher      Cryptographic functions
87   ./g10         GnuPG application
88   ./tools       Some helper and demo programs
89   ./keybox      The keybox library
90   ./gcrypt      Stuff needed to build libgcrypt
91
92
93
94
95
96 Memory allocation
97 -----------------
98 Use only the functions:
99
100     m_alloc()
101     m_alloc_clear()
102     m_strdup()
103     m_free()
104
105 If you want to store a passphrase or some other sensitive data you may
106 want to use m_alloc_secure() instead of m_alloc(), as this puts the data
107 into a memory region which is protected from swapping (on some platforms).
108 m_free() works for both.  This functions will not return if there is not
109 enough memory available.
110
111
112
113 Logging
114 -------
115
116
117
118
119
120
121 Option parsing
122 ---------------
123 GNUPG does not use getopt or GNU getopt but functions of it's own.  See
124 util/argparse.c for details.  The advantage of these functions is that
125 it is more easy to display and maintain the help texts for the options.
126 The same option table is also used to parse resource files.
127
128
129
130 What is an iobuf
131 ----------------
132 This is the data structure used for most I/O of gnupg.  It is similar
133 to System V Streams but much simpler.  It should be replaced by a cleaner
134 and faster implementation.  We are doing to much copying and the semantics
135 of "filter" removing are not very clean.  EOF handling is also a problem.
136
137
138
139 How to use the message digest functions
140 ---------------------------------------
141 cipher/md.c implements an interface to hash (message digest functions).
142
143 a) If you have a common part of data and some variable parts
144    and you need to hash of the concatenated parts, you can use this:
145         md = md_open(...)
146         md_write( md,  common_part )
147         md1 = md_copy( md )
148         md_write(md1, part1)
149         md_final(md1);
150         digest1 = md_read(md1)
151         md2 = md_copy( md )
152         md_write(md2, part2)
153         md_final(md2);
154         digest2 = md_read(md2)
155
156    An example are key signatures; the key packet is the common part
157    and the user-id packets are the variable parts.
158
159 b) If you need a running digest you should use this:
160         md = md_open(...)
161         md_write( md, part1 )
162         digest_of_part1 = md_digest( md );
163         md_write( md, part2 )
164         digest_of_part1_cat_part2 = md_digest( md );
165         ....
166
167 Both methods may be combined. [Please see the source for the real syntax]
168
169
170
171
172 How to use the cipher functions
173 -------------------------------
174
175
176
177
178 How to use the public key functions
179 -----------------------------------
180
181