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