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