gpg: Reject signatures made with MD5.
[gnupg.git] / doc / HACKING
1 # HACKING                                                       -*- org -*-
2 #+TITLE: A Hacker's Guide to GnuPG
3 #+TEXT: Some notes on GnuPG internals
4 #+STARTUP: showall
5 #+OPTIONS: ^:{}
6
7 * How to contribute
8
9   The following stuff explains some basic procedures you need to
10   follow if you want to contribute code or documentation.
11
12 ** No more ChangeLog files
13
14 Do not modify any of the ChangeLog files in GnuPG.  Starting on
15 December 1st, 2011 we put change information only in the GIT commit
16 log, and generate a top-level ChangeLog file from logs at "make dist"
17 time.  As such, there are strict requirements on the form of the
18 commit log messages.  The old ChangeLog files have all be renamed to
19 ChangeLog-2011
20
21 ** Commit log requirements
22
23 Your commit log should always start with a one-line summary, the
24 second line should be blank, and the remaining lines are usually
25 ChangeLog-style entries for all affected files.  However, it's fine
26 --- even recommended --- to write a few lines of prose describing the
27 change, when the summary and ChangeLog entries don't give enough of
28 the big picture.  Omit the leading TABs that you are seeing in a
29 "real" ChangeLog file, but keep the maximum line length at 72 or
30 smaller, so that the generated ChangeLog lines, each with its leading
31 TAB, will not exceed 80 columns.  If you want to add text which shall
32 not be copied to the ChangeLog, separate it by a line consisting of
33 two dashes at the begin of a line.
34
35 Typo fixes and documentation updates don't need a ChangeLog Entry,
36 thus you would use a commit message like
37
38 #+begin_example
39 Fix type in a comment
40
41 --
42 #+end_example
43
44 The marker line here is important; without it the first line would
45 appear in the ChangeLog.
46
47 ** License policy
48
49   GnuPG is licensed under the GPLv3+ with some files under a mixed
50   LGPLv3+/GPLv2+ license.  It is thus important, that all contributed
51   code allows for an update of the license; for example we can't
52   accept code under the GPLv2(only).
53
54   GnuPG used to have a strict policy of requiring copyright
55   assignments to the FSF.  To avoid this major organizational overhead
56   and to allow inclusion of code, not copyrighted by the FSF, this
57   policy has been relaxed on 2013-03-29.  It is now also possible to
58   contribute code by asserting that the contribution is in accordance
59   to the "Libgcrypt Developer's Certificate of Origin" as found in the
60   file "DCO".  (Except for a slight wording change, this DCO is
61   identical to the one used by the Linux kernel.)
62
63   If your want to contribute code or documentation to GnuPG and you
64   didn't signed a copyright assignment with the FSF in the past, you
65   need to take these simple steps:
66
67   - Decide which mail address you want to use.  Please have your real
68     name in the address and not a pseudonym.  Anonymous contributions
69     can only be done if you find a proxy who certifies for you.
70
71   - If your employer or school might claim ownership of code written
72     by you; you need to talk to them to make sure that you have the
73     right to contribute under the DCO.
74
75   - Send an OpenPGP signed mail to the gnupg-devel@gnupg.org mailing
76     list from your mail address.  Include a copy of the DCO as found
77     in the official master branch.  Insert your name and email address
78     into the DCO in the same way you want to use it later.  Example:
79
80       Signed-off-by: Joe R. Hacker <joe@example.org>
81
82     (If you really need it, you may perform simple transformations of
83     the mail address: Replacing "@" by " at " or "." by " dot ".)
84
85   - That's it.  From now on you only need to add a "Signed-off-by:"
86     line with your name and mail address to the commit message.  It is
87     recommended to send the patches using a PGP/MIME signed mail.
88
89 ** Coding standards
90
91   Please follow the GNU coding standards.  If you are in doubt consult
92   the existing code as an example.  Do no re-indent code without a
93   need.  If you really need to do it, use a separate commit for such a
94   change.
95
96 * Debug hints
97
98   See the manual for some hints.
99
100 * Standards
101
102 ** RFCs
103
104 1423  Privacy Enhancement for Internet Electronic Mail:
105       Part III: Algorithms, Modes, and Identifiers.
106
107 1489  Registration of a Cyrillic Character Set.
108
109 1750  Randomness Recommendations for Security.
110
111 1991  PGP Message Exchange Formats (obsolete)
112
113 2144  The CAST-128 Encryption Algorithm.
114
115 2279  UTF-8, a transformation format of ISO 10646.
116
117 2440  OpenPGP (obsolete).
118
119 3156  MIME Security with Pretty Good Privacy (PGP).
120
121 4880  Current OpenPGP specification.
122
123 * Various information
124
125 ** Directory Layout
126
127   - ./        :: Readme, configure
128   - ./agent   :: Gpg-agent and related tools
129   - ./doc     :: Documentation
130   - ./g10     :: Gpg program here called gpg2
131   - ./sm      :: Gpgsm program
132   - ./jnlib   :: Not used (formerly used utility functions)
133   - ./common  :: Utility functions
134   - ./kbx     :: Keybox library
135   - ./scd     :: Smartcard daemon
136   - ./scripts :: Scripts needed by configure and others
137   - ./dirmngr :: The directory manager
138
139 ** Detailed Roadmap
140
141   This list of file is not up to date!
142
143   - g10/gpg.c :: Main module with option parsing and all the stuff you
144                  have to do on startup.  Also has the exout handler
145                  and some helper functions.
146
147   - g10/sign.c :: Create signature and optionally encrypt
148
149   - g10/parse-packet.c ::
150   - g10/build-packet.c ::
151   - g10/free-packet.c :: Parsing and creating of OpenPGP message packets.
152
153   - g10/getkey.c   :: Key selection code
154   - g10/pkclist.c  :: Build a list of public keys
155   - g10/skclist.c  :: Build a list of secret keys
156   - g10/ringedit.c :: Keyring I/O
157   - g10/keydb.h    ::
158
159   - g10/keyid.c :: Helper functions to get the keyid, fingerprint etc.
160
161
162   - g10/trustdb.c ::
163   - g10/trustdb.h ::
164   - g10/tdbdump.c :: Management of the trustdb.gpg
165   - g10/tdbio.c   ::
166   - g10/tdbio.h   :: I/O handling for the trustdb.gpg
167
168   - g10/compress.c :: Filter to handle compression
169   - g10/filter.h   :: Declarations for all filter functions
170   - g10/delkey.c   :: Delete a key
171   - g10/kbnode.c   :: Helper for the KBNODE linked list
172   - g10/main.h     :: Prototypes and some constants
173   - g10/mainproc.c :: Message processing
174   - g10/armor.c    :: Ascii armor filter
175   - g10/mdfilter.c :: Filter to calculate hashs
176   - g10/textfilter.c :: Filter to handle CR/LF and trailing white space
177   - g10/cipher.c   :: En-/Decryption filter
178   - g10/misc.c     :: Utlity functions
179   - g10/options.h  :: Structure with all the command line options
180                       and related constants
181   - g10/openfile.c :: Create/Open Files
182   - g10/hkp.h      :: Keyserver access
183   - g10/hkp.c      :: Ditto.
184   - g10/packet.h   :: Defintion of OpenPGP structures.
185   - g10/passphrase.c :: Passphrase handling code
186
187   - g10/pubkey-enc.c ::
188   - g10/seckey-cert.c ::
189   - g10/seskey.c     ::
190   - g10/import.c     ::
191   - g10/export.c     ::
192   - g10/comment.c    ::
193   - g10/status.c     ::
194   - g10/status.h     ::
195   - g10/sign.c       ::
196   - g10/plaintext.c  ::
197   - g10/encr-data.c  ::
198   - g10/encode.c     ::
199   - g10/revoke.c     ::
200   - g10/keylist.c    ::
201   - g10/sig-check.c  ::
202   - g10/signal.c     ::
203   - g10/helptext.c   ::
204   - g10/verify.c     ::
205   - g10/decrypt.c    ::
206   - g10/keyedit.c    ::
207   - g10/dearmor.c    ::
208   - g10/keygen.c     ::
209
210 ** Memory allocation
211
212 Use only the functions:
213
214  - xmalloc
215  - xmalloc_secure
216  - xtrymalloc
217  - xtrymalloc_secure
218  - xcalloc
219  - xcalloc_secure
220  - xtrycalloc
221  - xtrycalloc_secure
222  - xrealloc
223  - xtryrealloc
224  - xstrdup
225  - xtrystrdup
226  - xfree
227
228
229 The *secure versions allocated memory in the secure memory. That is,
230 swapping out of this memory is avoided and is gets overwritten on
231 free.  Use this for passphrases, session keys and other sensitive
232 material.  This memory set aside for secure memory is linited to a few
233 k.  In general the function don't print a memeory message and
234 terminate the process if there is not enough memory available.  The
235 "try" versions of the functions return NULL instead.
236
237 ** Logging
238
239  TODO
240
241 ** Option parsing
242
243 GnuPG does not use getopt or GNU getopt but functions of it's own.
244 See util/argparse.c for details.  The advantage of these functions is
245 that it is more easy to display and maintain the help texts for the
246 options.  The same option table is also used to parse resource files.
247
248 ** What is an IOBUF
249
250 This is the data structure used for most I/O of gnupg. It is similar
251 to System┬áV Streams but much simpler.  Because OpenPGP messages are
252 nested in different ways; the use of such a system has big advantages.
253 Here is an example, how it works: If the parser sees a packet header
254 with a partial length, it pushes the block_filter onto the IOBUF to
255 handle these partial length packets: from now on you don't have to
256 worry about this.  When it sees a compressed packet it pushes the
257 uncompress filter and the next read byte is one which has already been
258 uncompressed by this filter. Same goes for enciphered packet,
259 plaintext packets and so on.  The file g10/encode.c might be a good
260 staring point to see how it is used - actually this is the other way:
261 constructing messages using pushed filters but it may be easier to
262 understand.
263
264