Remove unused status codes
[gnupg.git] / doc / HACKING
1                       A Hacker's Guide to GNUPG
2                    ================================
3                    (Some notes on GNUPG internals.)
4
5
6 * No more ChangeLog files
7
8 Do not modify any of the ChangeLog files in GnuPG.  Starting on
9 December 1st, 2011 we put change information only in the GIT commit
10 log, and generate a top-level ChangeLog file from logs at "make dist"
11 time.  As such, there are strict requirements on the form of the
12 commit log messages.  The old ChangeLog files have all be renamed to
13 ChangeLog-2011
14
15
16 * Commit log requirements
17
18 Your commit log should always start with a one-line summary, the second
19 line should be blank, and the remaining lines are usually ChangeLog-style
20 entries for all affected files.  However, it's fine -- even recommended --
21 to write a few lines of prose describing the change, when the summary
22 and ChangeLog entries don't give enough of the big picture.  Omit the
23 leading TABs that you're used to seeing in a "real" ChangeLog file, but
24 keep the maximum line length at 72 or smaller, so that the generated
25 ChangeLog lines, each with its leading TAB, will not exceed 80 columns.
26 If you want to add text which shall not be copied to the ChangeLog,
27 separate it by a line consisting of two dashes at the begin of a line.
28
29
30 ===> What follows is probably out of date <===
31
32
33 RFCs
34 ====
35
36 1423  Privacy Enhancement for Internet Electronic Mail:
37       Part III: Algorithms, Modes, and Identifiers.
38
39 1489  Registration of a Cyrillic Character Set.
40
41 1750  Randomness Recommendations for Security.
42
43 1991  PGP Message Exchange Formats (obsolete)
44
45 2144  The CAST-128 Encryption Algorithm.
46
47 2279  UTF-8, a transformation format of ISO 10646.
48
49 2440  OpenPGP (obsolete).
50
51 3156  MIME Security with Pretty Good Privacy (PGP).
52
53 4880  Current OpenPGP specification.
54
55
56
57 Directory Layout
58 ----------------
59   ./           Readme, configure
60   ./agent      Gpg-agent and related tools
61   ./doc        Documentation
62   ./doc        Documentation
63   ./g10        Gpg program here called gpg2
64   ./jnlib      Utility functions
65   ./kbx        Keybox library
66   ./scd        Smartcard daemon
67   ./scripts    Scripts needed by configure and others
68   ./sm         Gpgsm program
69
70
71 Detailed Roadmap
72 ----------------
73 g10/gpg.c       Main module with option parsing and all the stuff you have
74                 to do on startup.  Also has the exout handler and some
75                 helper functions.
76 g10/sign.c      Create signature and optionally encrypt
77
78 g10/parse-packet.c
79 g10/build-packet.c
80 g10/free-packet.c
81                 Parsing and creating of OpenPGP message packets.
82
83 g10/getkey.c    Key selection code
84 g10/pkclist.c   Build a list of public keys
85 g10/skclist.c   Build a list of secret keys
86 g10/ringedit.c  Keyring I/O
87 g10/keydb.h
88
89 g10/keyid.c     Helper functions to get the keyid, fingerprint etc.
90
91
92 g10/trustdb.c
93 g10/trustdb.h
94 g10/tdbdump.c
95                Management of the trustdb.gpg
96
97 g10/compress.c Filter to handle compression
98 g10/filter.h   Declarations for all filter functions
99 g10/delkey.c   Delete a key
100 g10/kbnode.c   Helper for the KBNODE linked list
101 g10/main.h     Prototypes and some constants
102 g10/mainproc.c Message processing
103 g10/armor.c    Ascii armor filter
104 g10/mdfilter.c Filter to calculate hashs
105 g10/textfilter.c Filter to handle CR/LF and trailing white space
106 g10/cipher.c   En-/Decryption filter
107 g10/misc.c     Utlity functions
108 g10/options.h  Structure with all the command line options
109                and related constants
110 g10/openfile.c Create/Open Files
111 g10/tdbio.c    I/O handling for the trustdb.gpg
112 g10/tdbio.h
113 g10/hkp.h      Keyserver access
114 g10/hkp.c
115 g10/packet.h   Defintion of OpenPGP structures.
116 g10/passphrase.c  Passphrase handling code
117 g10/pubkey-enc.c
118 g10/seckey-cert.c
119 g10/seskey.c
120 g10/import.c
121 g10/export.c
122 g10/comment.c
123 g10/status.c
124 g10/status.h
125 g10/sign.c
126 g10/plaintext.c
127 g10/encr-data.c
128 g10/encode.c
129 g10/revoke.c
130 g10/keylist.c
131 g10/sig-check.c
132 g10/signal.c
133 g10/helptext.c
134 g10/verify.c
135 g10/decrypt.c
136 g10/keyedit.c
137 g10/dearmor.c
138 g10/keygen.c
139
140
141
142 Memory allocation
143 -----------------
144 Use only the functions:
145
146     xmalloc
147     xmalloc_secure
148     xtrymalloc
149     xtrymalloc_secure
150     xcalloc
151     xcalloc_secure
152     xtrycalloc
153     xtrycalloc_secure
154     xrealloc
155     xtryrealloc
156     xstrdup
157     xtrystrdup
158     xfree
159
160
161 The *secure versions allocated memory in the secure memory. That is,
162 swapping out of this memory is avoided and is gets overwritten on
163 free.  Use this for passphrases, session keys and other sensitive
164 material.  This memory set aside for secure memory is linited to a few
165 k.  In general the function don't print a memeory message and
166 terminate the process if there is not enough memory available.  The
167 "try" versions of the functions return NULL instead.
168
169
170 Logging
171 -------
172
173
174
175
176
177
178 Option parsing
179 ---------------
180 GNUPG does not use getopt or GNU getopt but functions of it's own.  See
181 util/argparse.c for details.  The advantage of these functions is that
182 it is more easy to display and maintain the help texts for the options.
183 The same option table is also used to parse resource files.
184
185
186
187 What is an IOBUF
188 ----------------
189 This is the data structure used for most I/O of gnupg.  It is similar
190 to System V Streams but much simpler.  Because OpenPGP messages are nested
191 in different ways; the use of such a system has big advantages.  Here is
192 an example, how it works:  If the parser sees a packet header with a partial
193 length, it pushes the block_filter onto the IOBUF to handle these partial
194 length packets: from now on you don't have to worry about this.  When it sees
195 a compressed packet it pushes the uncompress filter and the next read byte
196 is one which has already been uncompressed by this filter. Same goes for
197 enciphered packet, plaintext packets and so on.  The file g10/encode.c
198 might be a good staring point to see how it is used  - actually this is
199 the other way: constructing messages using pushed filters but it may be
200 easier to understand.
201
202