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