A Hacker's Guide to GNUPG
A Hacker's Guide to GNUPG
A Hacker's Guide to GNUPG
You also want an ePaper? Increase the reach of your titles
YUMPU automatically turns print PDFs into web optimized ePapers that Google loves.
A Hacker’s <strong>Guide</strong> <strong>to</strong> <strong>GNUPG</strong><br />
================================<br />
(Some notes on <strong>GNUPG</strong> internals.)<br />
===> Under construction
1423 Privacy Enhancement for Internet Electronic Mail:<br />
Part III: Algorithms, Modes, and Identifiers.<br />
1489 Registration of a Cyrillic Character Set.<br />
1750 Randomness Recommendations for Security.<br />
1991 PGP Message Exchange Formats.<br />
2015 MIME Security with Pretty Good Privacy (PGP).<br />
2144 The CAST-128 Encryption Algorithm.<br />
2279 UTF-8, a transformation format of ISO 10646.<br />
2440 OpenPGP.<br />
Debug Flags<br />
-----------<br />
Use the option "--debug n" <strong>to</strong> output debug information. This option<br />
can be used multiple times, all values are ORed; n maybe prefixed with<br />
0x <strong>to</strong> use hex-values.<br />
value used for<br />
----- ----------------------------------------------<br />
1 packet reading/writing<br />
2 MPI details<br />
4 ciphers and primes (may reveal sensitive data)<br />
8 iobuf filter functions<br />
16 iobuf stuff<br />
32 memory allocation stuff<br />
64 caching<br />
128 show memory statistics at exit<br />
256 trust verification stuff<br />
Direc<strong>to</strong>ry Layout<br />
----------------<br />
./ Readme, configure<br />
./scripts Scripts needed by configure and others<br />
./doc Documentation<br />
./util General purpose utility function<br />
./mpi Multi precision integer library<br />
./cipher Cryp<strong>to</strong>graphic functions<br />
./g10 GnuPG application<br />
./<strong>to</strong>ols Some helper and demo programs<br />
./keybox The keybox library (under construction)<br />
./gcrypt Stuff needed <strong>to</strong> build libgcrypt (under construction)<br />
Detailed Roadmap<br />
---------------g10/g10.c<br />
Main module with option parsing and all the stuff you have<br />
<strong>to</strong> do on startup. Also has the exout handler and some<br />
helper functions.
g10/sign.c Create signature and optionally encrypt<br />
g10/parse-packet.c<br />
g10/build-packet.c<br />
g10/free-packet.c<br />
Parsing and creating of OpenPGP message packets.<br />
g10/getkey.c Key selection code<br />
g10/pkclist.c Build a list of public keys<br />
g10/skclist.c Build a list of secret keys<br />
g10/ringedit.c Keyring I/O<br />
g10/keydb.h<br />
g10/keyid.c Helper functions <strong>to</strong> get the keyid, fingerprint etc.<br />
g10/trustdb.c<br />
g10/trustdb.h<br />
g10/tdbdump.c<br />
Management of the trustdb.gpg<br />
g10/compress.c Filter <strong>to</strong> handle compression<br />
g10/filter.h Declarations for all filter functions<br />
g10/delkey.c Delete a key<br />
g10/kbnode.c Helper for the KBNODE linked list<br />
g10/main.h Pro<strong>to</strong>types and some constants<br />
g10/mainproc.c Message processing<br />
g10/armor.c Ascii armor filter<br />
g10/mdfilter.c Filter <strong>to</strong> calculate hashs<br />
g10/textfilter.c Filter <strong>to</strong> handle CR/LF and trailing white space<br />
g10/cipher.c En-/Decryption filter<br />
g10/misc.c Utlity functions<br />
g10/options.h Structure with all the command line options<br />
and related constants<br />
g10/openfile.c Create/Open Files<br />
g10/tdbio.c I/O handling for the trustdb.gpg<br />
g10/tdbio.h<br />
g10/hkp.h Keyserver access<br />
g10/hkp.c<br />
g10/packet.h Defintion of OpenPGP structures.<br />
g10/passphrase.c Passphrase handling code<br />
g10/pubkey-enc.c<br />
g10/seckey-cert.c<br />
g10/seskey.c<br />
g10/import.c<br />
g10/export.c<br />
g10/comment.c<br />
g10/status.c<br />
g10/status.h<br />
g10/sign.c<br />
g10/plaintext.c<br />
g10/encr-data.c<br />
g10/encode.c<br />
g10/revoke.c<br />
g10/keylist.c<br />
g10/sig-check.c<br />
g10/signal.c<br />
g10/helptext.c<br />
g10/verify.c<br />
g10/decrypt.c
g10/keyedit.c<br />
g10/dearmor.c<br />
g10/keygen.c<br />
Memory allocation<br />
-----------------<br />
Use only the functions:<br />
m_alloc()<br />
m_alloc_clear()<br />
m_strdup()<br />
m_free()<br />
If you want <strong>to</strong> s<strong>to</strong>re a passphrase or some other sensitive data you may<br />
want <strong>to</strong> use m_alloc_secure() instead of m_alloc(), as this puts the data<br />
in<strong>to</strong> a memory region which is protected from swapping (on some platforms).<br />
m_free() works for both. This functions will not return if there is not<br />
enough memory available.<br />
Logging<br />
-------<br />
Option parsing<br />
---------------<br />
<strong>GNUPG</strong> does not use ge<strong>to</strong>pt or GNU ge<strong>to</strong>pt but functions of it’s own. See<br />
util/argparse.c for details. The advantage of these functions is that<br />
it is more easy <strong>to</strong> display and maintain the help texts for the options.<br />
The same option table is also used <strong>to</strong> parse resource files.<br />
What is an IOBUF<br />
----------------<br />
This is the data structure used for most I/O of gnupg. It is similar<br />
<strong>to</strong> System V Streams but much simpler. Because OpenPGP messages are nested<br />
in different ways; the use of such a system has big advantages. Here is<br />
an example, how it works: If the parser sees a packet header with a partial<br />
length, it pushes the block_filter on<strong>to</strong> the IOBUF <strong>to</strong> handle these partial<br />
length packets: from now on you don’t have <strong>to</strong> worry about this. When it sees<br />
a compressed packet it pushes the uncompress filter and the next read byte<br />
is one which has already been uncompressed by this filter. Same goes for<br />
enciphered packet, plaintext packets and so on. The file g10/encode.c<br />
might be a good staring point <strong>to</strong> see how it is used - actually this is<br />
the other way: constructing messages using pushed filters but it may be<br />
easier <strong>to</strong> understand.<br />
How <strong>to</strong> use the message digest functions<br />
--------------------------------------cipher/md.c<br />
implements an interface <strong>to</strong> hash (message digest functions).
a) If you have a common part of data and some variable parts<br />
and you need <strong>to</strong> hash of the concatenated parts, you can use this:<br />
md = md_open(...)<br />
md_write( md, common_part )<br />
md1 = md_copy( md )<br />
md_write(md1, part1)<br />
md_final(md1);<br />
digest1 = md_read(md1)<br />
md2 = md_copy( md )<br />
md_write(md2, part2)<br />
md_final(md2);<br />
digest2 = md_read(md2)<br />
An example are key signatures; the key packet is the common part<br />
and the user-id packets are the variable parts.<br />
b) If you need a running digest you should use this:<br />
md = md_open(...)<br />
md_write( md, part1 )<br />
digest_of_part1 = md_digest( md );<br />
md_write( md, part2 )<br />
digest_of_part1_cat_part2 = md_digest( md );<br />
....<br />
Both methods may be combined. [Please see the source for the real syntax]<br />
How <strong>to</strong> use the cipher functions<br />
------------------------------cipher/cipher.c<br />
implements the interface <strong>to</strong> symmetric encryption functions.<br />
As usual you have a function <strong>to</strong> open a cipher (which returns a handle <strong>to</strong> be used<br />
with all other functions), some functions <strong>to</strong> set the key and other stuff and<br />
a encrypt and decrypt function which does the real work. You probably know<br />
how <strong>to</strong> work with files - so it should really be easy <strong>to</strong> work with these<br />
functions. Here is an example:<br />
CIPHER_HANDLE hd;<br />
hd = cipher_open( CIPHER_ALGO_TWOFISH, CIPHER_MODE_CFB, 0 );<br />
if( !hd )<br />
oops( use other function <strong>to</strong> check for the real error );<br />
rc = cipher_setkey( hd, key256bit, 32 ) )<br />
if( rc )<br />
oops( weak key or something like this );<br />
cipher_setiv( hd, some_IV_or_NULL_for_all_zeroes );<br />
cipher_encrypt( hd, plain, cipher, size );<br />
cipher_close( hd );<br />
How <strong>to</strong> use the public key functions<br />
----------------------------------cipher/pubkey.c<br />
implements the interface <strong>to</strong> asymmetric encryption and<br />
signature functions. This is basically the same as with the symmetric<br />
counterparts, but due <strong>to</strong> their nature it is a little bit more complicated.<br />
[Give an example]
This is a demo version of txt2pdf v.10.1<br />
Developed by SANFACE Software http://www.sanface.com/<br />
Available at http://www.sanface.com/txt2pdf.html