See ChangeLog ;-). Key validation should now be faster
[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 anouncement; 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 Memory allocation
59 -----------------
60 Use only the functions:
61
62     m_alloc()
63     m_alloc_clear()
64     m_strdup()
65     m_free()
66
67 If you want to store a passphrase or some other sensitive data you may
68 want to use m_alloc_secure() instead of m_alloc(), as this puts the data
69 into a memory region which is protected from swapping (on some platforms).
70 m_free() works for both.  This functions will not return if there is not
71 enough memory available.
72
73
74
75 Logging
76 -------
77
78
79
80
81
82
83 Option parsing
84 ---------------
85 GNUPG does not use getopt or GNU getopt but functions of it's own.  See
86 util/argparse.c for details.  The advantage of these funtions is that
87 it is more easy to display and maintain the help texts for the options.
88 The same option table is also used to parse resource files.
89
90
91
92 What is an iobuf
93 ----------------
94 This is the data structure used for most I/O of gnupg.  It is similiar
95 to System V Streams but much simpler.  It should be replaced by a cleaner
96 and faster implementation.  We are doing to much copying and the semantics
97 of "filter" removing are not very clean.  EOF handling is also a problem.
98
99
100
101 How to use the message digest functions
102 ---------------------------------------
103 cipher/md.c implements an interface to hash (message diesgt functions).
104
105 a) If you have a common part of data and some variable parts
106    and you need to hash of the concatenated parts, you can use this:
107         md = md_open(...)
108         md_write( md,  common_part )
109         md1 = md_copy( md )
110         md_write(md1, part1)
111         md_final(md1);
112         digest1 = md_read(md1)
113         md2 = md_copy( md )
114         md_write(md2, part2)
115         md_final(md2);
116         digest2 = md_read(md2)
117
118    An example are key signatures; the key packet is the common part
119    and the user-id packets are the variable parts.
120
121 b) If you need a running digest you should use this:
122         md = md_open(...)
123         md_write( md, part1 )
124         digest_of_part1 = md_digest( md );
125         md_write( md, part2 )
126         digest_of_part1_cat_part2 = md_digest( md );
127         ....
128
129 Both methods may be combined. [Please see the source for the real syntax]
130
131
132
133
134 How to use the cipher functions
135 -------------------------------
136
137
138
139
140 How to use the public key functions
141 -----------------------------------
142
143