doc: Two typo fixes.
[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 If you exceptionally need to have longer lines in a commit log you may
48 do this after this scissor line:
49 #+begin_example
50 # ------------------------ >8 ------------------------
51 #+end_example
52 (hash, blank, 24 dashes, blank, scissor, blank, 24 dashes).
53 Note that such a comment will be removed if the git commit option
54 =--cleanup=scissor= is used.
55
56
57
58 ** License policy
59
60   GnuPG is licensed under the GPLv3+ with some files under a mixed
61   LGPLv3+/GPLv2+ license.  It is thus important, that all contributed
62   code allows for an update of the license; for example we can't
63   accept code under the GPLv2(only).
64
65   GnuPG used to have a strict policy of requiring copyright
66   assignments to the FSF.  To avoid this major organizational overhead
67   and to allow inclusion of code, not copyrighted by the FSF, this
68   policy has been relaxed on 2013-03-29.  It is now also possible to
69   contribute code by asserting that the contribution is in accordance
70   to the "Libgcrypt Developer's Certificate of Origin" as found in the
71   file "DCO".  (Except for a slight wording change, this DCO is
72   identical to the one used by the Linux kernel.)
73
74   If you want to contribute code or documentation to GnuPG and you
75   didn't sign a copyright assignment with the FSF in the past, you
76   need to take these simple steps:
77
78   - Decide which mail address you want to use.  Please have your real
79     name in the address and not a pseudonym.  Anonymous contributions
80     can only be done if you find a proxy who certifies for you.
81
82   - If your employer or school might claim ownership of code written
83     by you; you need to talk to them to make sure that you have the
84     right to contribute under the DCO.
85
86   - Send an OpenPGP signed mail to the gnupg-devel@gnupg.org mailing
87     list from your mail address.  Include a copy of the DCO as found
88     in the official master branch.  Insert your name and email address
89     into the DCO in the same way you want to use it later.  Example:
90
91       Signed-off-by: Joe R. Hacker <joe@example.org>
92
93     (If you really need it, you may perform simple transformations of
94     the mail address: Replacing "@" by " at " or "." by " dot ".)
95
96   - That's it.  From now on you only need to add a "Signed-off-by:"
97     line with your name and mail address to the commit message.  It is
98     recommended to send the patches using a PGP/MIME signed mail.
99
100 ** Coding standards
101
102   Please follow the GNU coding standards.  If you are in doubt consult
103   the existing code as an example.  Do no re-indent code without a
104   need.  If you really need to do it, use a separate commit for such a
105   change.
106
107 ** Commit log keywords
108
109   - GnuPG-bug-id :: Values are comma or space delimited bug numbers
110                     from bug.gnupg.org pertaining to this commit.
111   - Debian-bug-id :: Same as above but from the Debian bug tracker.
112   - CVE-id :: CVE id number pertaining to this commit.
113   - Regression-due-to :: Commit id of the regression fixed by this commit.
114   - Fixes-commit :: Commit id this commit fixes.
115   - Reported-by :: Value is a name or mail address of a bug reporte.
116   - Suggested-by :: Value is a name or mail address of someone how
117                     suggested this change.
118   - Co-authored-by :: Name or mail address of a co-author
119   - Some-comments-by :: Name or mail address of the author of
120                         additional comments (commit log or code).
121   - Proofread-by :: Sometimes used by translation commits.
122   - Signed-off-by :: Name or mail address of the developer
123
124 * Windows
125 ** How to build an installer for Windows
126
127    Your best bet is to use a decent Debian System for development.
128    You need to install a long list of tools for building.  This list
129    still needs to be compiled.  However, the build process will stop
130    if a tool is missing.  GNU make is required (on non GNU systems
131    often installed as "gmake").  The installer requires a couple of
132    extra software to be available either as tarballs or as local git
133    repositories.  In case this file here is part of a gnupg-w32-2.*.xz
134    complete tarball as distributed from the same place as a binary
135    installer, all such tarballs are already included.
136
137    Cd to the GnuPG source directory and use one of one of these
138    command:
139
140    - If sources are included (gnupg-w32-*.tar.xz)
141
142      make -f build-aux/speedo.mk WHAT=this installer
143
144    - To build from tarballs
145
146      make -f build-aux/speedo.mk WHAT=release TARBALLS=TARDIR installer
147
148    - To build from local GIT repos
149
150      make -f build-aux/speedo.mk WHAT=git TARBALLS=TARDIR installer
151
152    Note that also you need to supply tarballs with supporting
153    libraries even if you build from git.  The makefile expects only
154    the core GnuPG software to be available as local GIT repositories.
155    speedo.mk has the versions of the tarballs and the branch names of
156    the git repositories.  In case of problems, don't hesitate to ask
157    on the gnupg-devel mailing for help.
158
159
160 * Debug hints
161
162   See the manual for some hints.
163
164 * Standards
165 ** RFCs
166
167 1423  Privacy Enhancement for Internet Electronic Mail:
168       Part III: Algorithms, Modes, and Identifiers.
169
170 1489  Registration of a Cyrillic Character Set.
171
172 1750  Randomness Recommendations for Security.
173
174 1991  PGP Message Exchange Formats (obsolete)
175
176 2144  The CAST-128 Encryption Algorithm.
177
178 2279  UTF-8, a transformation format of ISO 10646.
179
180 2440  OpenPGP (obsolete).
181
182 3156  MIME Security with Pretty Good Privacy (PGP).
183
184 4880  Current OpenPGP specification.
185
186 6337  Elliptic Curve Cryptography (ECC) in OpenPGP
187
188 * Various information
189
190 ** Directory Layout
191
192   - ./        :: Readme, configure
193   - ./agent   :: Gpg-agent and related tools
194   - ./doc     :: Documentation
195   - ./g10     :: Gpg program here called gpg2
196   - ./sm      :: Gpgsm program
197   - ./jnlib   :: Not used (formerly used utility functions)
198   - ./common  :: Utility functions
199   - ./kbx     :: Keybox library
200   - ./scd     :: Smartcard daemon
201   - ./scripts :: Scripts needed by configure and others
202   - ./dirmngr :: The directory manager
203
204 ** Detailed Roadmap
205
206   This list of files is not up to date!
207
208   - g10/gpg.c :: Main module with option parsing and all the stuff you
209                  have to do on startup.  Also has the exit handler and
210                  some helper functions.
211
212   - g10/parse-packet.c ::
213   - g10/build-packet.c ::
214   - g10/free-packet.c :: Parsing and creating of OpenPGP message packets.
215
216   - g10/getkey.c   :: Key selection code
217   - g10/pkclist.c  :: Build a list of public keys
218   - g10/skclist.c  :: Build a list of secret keys
219   - g10/keyring.c  :: Keyring access functions
220   - g10/keydb.h    ::
221
222   - g10/keyid.c   :: Helper functions to get the keyid, fingerprint etc.
223
224   - g10/trustdb.c :: Web-of-Trust computations
225   - g10/trustdb.h ::
226   - g10/tdbdump.c :: Export/import/list the trustdb.gpg
227   - g10/tdbio.c   :: I/O handling for the trustdb.gpg
228   - g10/tdbio.h   ::
229
230   - g10/compress.c :: Filter to handle compression
231   - g10/filter.h   :: Declarations for all filter functions
232   - g10/delkey.c   :: Delete a key
233   - g10/kbnode.c   :: Helper for the kbnode_t linked list
234   - g10/main.h     :: Prototypes and some constants
235   - g10/mainproc.c :: Message processing
236   - g10/armor.c    :: Ascii armor filter
237   - g10/mdfilter.c :: Filter to calculate hashs
238   - g10/textfilter.c :: Filter to handle CR/LF and trailing white space
239   - g10/cipher.c   :: En-/Decryption filter
240   - g10/misc.c     :: Utlity functions
241   - g10/options.h  :: Structure with all the command line options
242                       and related constants
243   - g10/openfile.c :: Create/Open Files
244   - g10/keyserver.h :: Keyserver access dispatcher.
245   - g10/packet.h   :: Defintion of OpenPGP structures.
246   - g10/passphrase.c :: Passphrase handling code
247
248   - g10/pubkey-enc.c :: Process a public key encoded packet.
249   - g10/seckey-cert.c :: Not anymore used
250   - g10/seskey.c     :: Make sesssion keys etc.
251   - g10/import.c     :: Import keys into our key storage.
252   - g10/export.c     :: Export keys to the OpenPGP format.
253   - g10/sign.c       :: Create signature and optionally encrypt.
254   - g10/plaintext.c  :: Process plaintext packets.
255   - g10/decrypt-data.c :: Decrypt an encrypted data packet
256   - g10/encrypt.c    :: Main encryption driver
257   - g10/revoke.c     :: Create recovation certificates.
258   - g10/keylist.c    :: Print information about OpenPGP keys
259   - g10/sig-check.c  :: Check a signature
260   - g10/helptext.c   :: Show online help texts
261   - g10/verify.c     :: Verify signed data.
262   - g10/decrypt.c    :: Decrypt and verify data.
263   - g10/keyedit.c    :: Edit properties of a key.
264   - g10/dearmor.c    :: Armor utility.
265   - g10/keygen.c     :: Generate a key pair
266
267 ** Memory allocation
268
269 Use only the functions:
270
271  - xmalloc
272  - xmalloc_secure
273  - xtrymalloc
274  - xtrymalloc_secure
275  - xcalloc
276  - xcalloc_secure
277  - xtrycalloc
278  - xtrycalloc_secure
279  - xrealloc
280  - xtryrealloc
281  - xstrdup
282  - xtrystrdup
283  - xfree
284
285
286 The *secure versions allocate memory in the secure memory.  That is,
287 swapping out of this memory is avoided and is gets overwritten on
288 free.  Use this for passphrases, session keys and other sensitive
289 material.  This memory set aside for secure memory is linited to a few
290 k.  In general the function don't print a memeory message and
291 terminate the process if there is not enough memory available.  The
292 "try" versions of the functions return NULL instead.
293
294 ** Logging
295
296  TODO
297
298 ** Option parsing
299
300 GnuPG does not use getopt or GNU getopt but functions of it's own.
301 See util/argparse.c for details.  The advantage of these functions is
302 that it is more easy to display and maintain the help texts for the
303 options.  The same option table is also used to parse resource files.
304
305 ** What is an IOBUF
306
307 This is the data structure used for most I/O of gnupg. It is similar
308 to System┬áV Streams but much simpler.  Because OpenPGP messages are
309 nested in different ways; the use of such a system has big advantages.
310 Here is an example, how it works: If the parser sees a packet header
311 with a partial length, it pushes the block_filter onto the IOBUF to
312 handle these partial length packets: from now on you don't have to
313 worry about this.  When it sees a compressed packet it pushes the
314 uncompress filter and the next read byte is one which has already been
315 uncompressed by this filter. Same goes for enciphered packet,
316 plaintext packets and so on.  The file g10/encode.c might be a good
317 starting point to see how it is used - actually this is the other way:
318 constructing messages using pushed filters but it may be easier to
319 understand.
320
321