*** empty log message ***
[gnupg.git] / doc / HACKING
1                           A Hacker's Guide to GNUPG
2                        ================================
3                        (Some notes on GNUPG internals.)
4
5
6
7 Memory allocation
8 -----------------
9 Use only the functions:
10
11     m_alloc()
12     m_alloc_clear()
13     m_strdup()
14     m_free()
15
16 If you want to store a passphrase or some other sensitive data you may
17 want to use m_alloc_secure() instead of m_alloc(), as this puts the data
18 into a memory region which is protected from swapping (on some platforms).
19 m_free() works for both.  This functions will not return if there is not
20 enough memory available.
21
22
23
24 Logging
25 -------
26
27
28
29
30
31
32 Option parsing
33 ---------------
34 GNUPG does not use getopt or GNU getopt but functions of it's own.  See
35 util/argparse.c for details.  The advantage of these funtions is that
36 it is more easy to display and maintain the help texts for the options.
37 The same option table is also used to parse resource files.
38
39
40
41 What is an iobuf
42 ----------------
43 This is the data structure used for most I/O of gnupg.  It is similiar
44 to System V Streams but much simpler.  It should be replaced by a cleaner
45 and faster implementation.  We are doing to much copying and the semantics
46 of "filter" removing are not very clean.  EOF handling is also a problem.
47
48
49
50 How to use the message digest functions
51 ---------------------------------------
52 cipher/md.c implements an interface to hash (message diesgt functions).
53
54 a) If you have a common part of data and some variable parts
55    and you need to hash of the concatenated parts, you can use this:
56         md = md_open(...)
57         md_write( md,  common_part )
58         md1 = md_copy( md )
59         md_write(md1, part1)
60         md_final(md1);
61         digest1 = md_read(md1)
62         md2 = md_copy( md )
63         md_write(md2, part2)
64         md_final(md2);
65         digest2 = md_read(md2)
66
67    An example are key signatures; the key packet is the common part
68    and the user-id packets are the variable parts.
69
70 b) If you need a running digest you should use this:
71         md = md_open(...)
72         md_write( md, part1 )
73         digest_of_part1 = md_digest( md );
74         md_write( md, part2 )
75         digest_of_part1_cat_part2 = md_digest( md );
76         ....
77
78 Both methods may be combined. [Please see the source for the real syntax]
79
80
81
82
83 How to use the cipher functions
84 -------------------------------
85
86
87
88
89 How to use the public key functions
90 -----------------------------------
91
92