2 #+TITLE: A Hacker's Guide to GnuPG
3 #+TEXT: Some notes on GnuPG internals
9 The following stuff explains some basic procedures you need to
10 follow if you want to contribute code or documentation.
12 ** No more ChangeLog files
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
21 ** Commit log requirements
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.
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
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
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.
61 Typo fixes and documentation updates don't need a ChangeLog entry;
62 thus you would use a commit message like
65 doc: Fix typo in a comment
70 The marker line here is important; without it the first line would
71 appear in the ChangeLog.
73 If you exceptionally need to have longer lines in a commit log you may
74 do this after this scissor line:
76 # ------------------------ >8 ------------------------
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.
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).
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.)
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:
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.
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.
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:
115 Signed-off-by: Joe R. Hacker <joe@example.org>
117 (If you really need it, you may perform simple transformations of
118 the mail address: Replacing "@" by " at " or "." by " dot ".)
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.
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
131 - Only certain C99 features may be used (see below); in general
133 - Please do not use C++ =//= style comments.
134 - Do not use comments like:
137 /* Now that we know that foo is true we can call bar. */
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
145 - Try to fit lines into 80 columns.
146 - Ignore signed/unsigned pointer mismatches
147 - No arithmetic on void pointers; cast to char* first.
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
170 - New code shall in general use xtrymalloc or xtrycalloc and check
171 for an error (use gpg_error_from_errno()).
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
177 - But 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.
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
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
195 - rc :: Used for all kind of other errors; for example system
196 calls. The value is not compatible with gpg-error.
199 *** C99 language features
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:
205 : #define foo(a,...) bar(a, __VA_ARGS__)
207 - The predefined macro =__func__=:
208 : log_debug ("%s: Problem with foo\n", __func__);
210 - Variable declaration inside a for():
211 : for (int i = 0; i < 5; ++)
214 Although we usually make use of the =u16=, =u32=, and =u64= types,
215 it is also possible to include =<stdint.h>= and use =int16_t=,
216 =int32_t=, =int64_t=, =uint16_t=, =uint32_t=, and =uint64_t=. But do
217 not use =int8_t= or =uint8_t=.
219 ** Commit log keywords
221 - GnuPG-bug-id :: Values are comma or space delimited bug numbers
222 from bug.gnupg.org pertaining to this commit.
223 - Debian-bug-id :: Same as above but from the Debian bug tracker.
224 - CVE-id :: CVE id number pertaining to this commit.
225 - Regression-due-to :: Commit id of the regression fixed by this commit.
226 - Fixes-commit :: Commit id this commit fixes.
227 - Reported-by :: Value is a name or mail address of a bug reporte.
228 - Suggested-by :: Value is a name or mail address of someone how
229 suggested this change.
230 - Co-authored-by :: Name or mail address of a co-author
231 - Some-comments-by :: Name or mail address of the author of
232 additional comments (commit log or code).
233 - Proofread-by :: Sometimes used by translation commits.
234 - Signed-off-by :: Name or mail address of the developer
237 ** How to build an installer for Windows
239 Your best bet is to use a decent Debian System for development.
240 You need to install a long list of tools for building. This list
241 still needs to be compiled. However, the build process will stop
242 if a tool is missing. GNU make is required (on non GNU systems
243 often installed as "gmake"). The installer requires a couple of
244 extra software to be available either as tarballs or as local git
245 repositories. In case this file here is part of a gnupg-w32-2.*.xz
246 complete tarball as distributed from the same place as a binary
247 installer, all such tarballs are already included.
249 Cd to the GnuPG source directory and use one of one of these
252 - If sources are included (gnupg-w32-*.tar.xz)
254 make -f build-aux/speedo.mk WHAT=this installer
256 - To build from tarballs
258 make -f build-aux/speedo.mk WHAT=release TARBALLS=TARDIR installer
260 - To build from local GIT repos
262 make -f build-aux/speedo.mk WHAT=git TARBALLS=TARDIR installer
264 Note that also you need to supply tarballs with supporting
265 libraries even if you build from git. The makefile expects only
266 the core GnuPG software to be available as local GIT repositories.
267 speedo.mk has the versions of the tarballs and the branch names of
268 the git repositories. In case of problems, don't hesitate to ask
269 on the gnupg-devel mailing for help.
273 See the manual for some hints.
278 1423 Privacy Enhancement for Internet Electronic Mail:
279 Part III: Algorithms, Modes, and Identifiers.
281 1489 Registration of a Cyrillic Character Set.
283 1750 Randomness Recommendations for Security.
285 1991 PGP Message Exchange Formats (obsolete)
287 2144 The CAST-128 Encryption Algorithm.
289 2279 UTF-8, a transformation format of ISO 10646.
291 2440 OpenPGP (obsolete).
293 3156 MIME Security with Pretty Good Privacy (PGP).
295 4880 Current OpenPGP specification.
297 6337 Elliptic Curve Cryptography (ECC) in OpenPGP
299 * Various information
303 - ./ :: Readme, configure
304 - ./agent :: Gpg-agent and related tools
305 - ./doc :: Documentation
306 - ./g10 :: Gpg program here called gpg2
307 - ./sm :: Gpgsm program
308 - ./jnlib :: Not used (formerly used utility functions)
309 - ./common :: Utility functions
310 - ./kbx :: Keybox library
311 - ./scd :: Smartcard daemon
312 - ./scripts :: Scripts needed by configure and others
313 - ./dirmngr :: The directory manager
317 This list of files is not up to date!
319 - g10/gpg.c :: Main module with option parsing and all the stuff you
320 have to do on startup. Also has the exit handler and
321 some helper functions.
323 - g10/parse-packet.c ::
324 - g10/build-packet.c ::
325 - g10/free-packet.c :: Parsing and creating of OpenPGP message packets.
327 - g10/getkey.c :: Key selection code
328 - g10/pkclist.c :: Build a list of public keys
329 - g10/skclist.c :: Build a list of secret keys
330 - g10/keyring.c :: Keyring access functions
333 - g10/keyid.c :: Helper functions to get the keyid, fingerprint etc.
335 - g10/trustdb.c :: Web-of-Trust computations
337 - g10/tdbdump.c :: Export/import/list the trustdb.gpg
338 - g10/tdbio.c :: I/O handling for the trustdb.gpg
341 - g10/compress.c :: Filter to handle compression
342 - g10/filter.h :: Declarations for all filter functions
343 - g10/delkey.c :: Delete a key
344 - g10/kbnode.c :: Helper for the kbnode_t linked list
345 - g10/main.h :: Prototypes and some constants
346 - g10/mainproc.c :: Message processing
347 - g10/armor.c :: Ascii armor filter
348 - g10/mdfilter.c :: Filter to calculate hashs
349 - g10/textfilter.c :: Filter to handle CR/LF and trailing white space
350 - g10/cipher.c :: En-/Decryption filter
351 - g10/misc.c :: Utlity functions
352 - g10/options.h :: Structure with all the command line options
353 and related constants
354 - g10/openfile.c :: Create/Open Files
355 - g10/keyserver.h :: Keyserver access dispatcher.
356 - g10/packet.h :: Definition of OpenPGP structures.
357 - g10/passphrase.c :: Passphrase handling code
359 - g10/pubkey-enc.c :: Process a public key encoded packet.
360 - g10/seckey-cert.c :: Not anymore used
361 - g10/seskey.c :: Make sesssion keys etc.
362 - g10/import.c :: Import keys into our key storage.
363 - g10/export.c :: Export keys to the OpenPGP format.
364 - g10/sign.c :: Create signature and optionally encrypt.
365 - g10/plaintext.c :: Process plaintext packets.
366 - g10/decrypt-data.c :: Decrypt an encrypted data packet
367 - g10/encrypt.c :: Main encryption driver
368 - g10/revoke.c :: Create recovation certificates.
369 - g10/keylist.c :: Print information about OpenPGP keys
370 - g10/sig-check.c :: Check a signature
371 - g10/helptext.c :: Show online help texts
372 - g10/verify.c :: Verify signed data.
373 - g10/decrypt.c :: Decrypt and verify data.
374 - g10/keyedit.c :: Edit properties of a key.
375 - g10/dearmor.c :: Armor utility.
376 - g10/keygen.c :: Generate a key pair
380 Use only the functions:
397 The *secure versions allocate memory in the secure memory. That is,
398 swapping out of this memory is avoided and is gets overwritten on
399 free. Use this for passphrases, session keys and other sensitive
400 material. This memory set aside for secure memory is linited to a few
401 k. In general the function don't print a memeory message and
402 terminate the process if there is not enough memory available. The
403 "try" versions of the functions return NULL instead.
411 GnuPG does not use getopt or GNU getopt but functions of it's own.
412 See util/argparse.c for details. The advantage of these functions is
413 that it is more easy to display and maintain the help texts for the
414 options. The same option table is also used to parse resource files.
418 This is the data structure used for most I/O of gnupg. It is similar
419 to System V Streams but much simpler. Because OpenPGP messages are
420 nested in different ways; the use of such a system has big advantages.
421 Here is an example, how it works: If the parser sees a packet header
422 with a partial length, it pushes the block_filter onto the IOBUF to
423 handle these partial length packets: from now on you don't have to
424 worry about this. When it sees a compressed packet it pushes the
425 uncompress filter and the next read byte is one which has already been
426 uncompressed by this filter. Same goes for enciphered packet,
427 plaintext packets and so on. The file g10/encode.c might be a good
428 starting point to see how it is used - actually this is the other way:
429 constructing messages using pushed filters but it may be easier to