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