2013-03-29 09:13:05 +01:00
|
|
|
|
# HACKING -*- org -*-
|
|
|
|
|
#+TITLE: A Hacker's Guide to GnuPG
|
|
|
|
|
#+TEXT: Some notes on GnuPG internals
|
|
|
|
|
#+STARTUP: showall
|
|
|
|
|
#+OPTIONS: ^:{}
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
* How to contribute
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
The following stuff explains some basic procedures you need to
|
|
|
|
|
follow if you want to contribute code or documentation.
|
|
|
|
|
|
|
|
|
|
** No more ChangeLog files
|
2011-12-01 10:51:36 +01:00
|
|
|
|
|
|
|
|
|
Do not modify any of the ChangeLog files in GnuPG. Starting on
|
|
|
|
|
December 1st, 2011 we put change information only in the GIT commit
|
|
|
|
|
log, and generate a top-level ChangeLog file from logs at "make dist"
|
|
|
|
|
time. As such, there are strict requirements on the form of the
|
|
|
|
|
commit log messages. The old ChangeLog files have all be renamed to
|
|
|
|
|
ChangeLog-2011
|
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
** Commit log requirements
|
|
|
|
|
|
|
|
|
|
Your commit log should always start with a one-line summary, the
|
|
|
|
|
second line should be blank, and the remaining lines are usually
|
|
|
|
|
ChangeLog-style entries for all affected files. However, it's fine
|
|
|
|
|
--- even recommended --- to write a few lines of prose describing the
|
|
|
|
|
change, when the summary and ChangeLog entries don't give enough of
|
|
|
|
|
the big picture. Omit the leading TABs that you are seeing in a
|
|
|
|
|
"real" ChangeLog file, but keep the maximum line length at 72 or
|
|
|
|
|
smaller, so that the generated ChangeLog lines, each with its leading
|
|
|
|
|
TAB, will not exceed 80 columns. If you want to add text which shall
|
|
|
|
|
not be copied to the ChangeLog, separate it by a line consisting of
|
|
|
|
|
two dashes at the begin of a line.
|
|
|
|
|
|
|
|
|
|
Typo fixes and documentation updates don't need a ChangeLog Entry,
|
|
|
|
|
thus you would use a commit message like
|
|
|
|
|
|
|
|
|
|
#+begin_example
|
|
|
|
|
Fix type in a comment
|
|
|
|
|
|
|
|
|
|
--
|
|
|
|
|
#+end_example
|
|
|
|
|
|
|
|
|
|
The marker line here is important; without it the first line would
|
|
|
|
|
appear in the ChangeLog.
|
|
|
|
|
|
2015-07-23 15:01:40 +02:00
|
|
|
|
If you exceptionally need to have longer lines in a commit log you may
|
|
|
|
|
do this after this scissor line:
|
|
|
|
|
#+begin_example
|
|
|
|
|
# ------------------------ >8 ------------------------
|
|
|
|
|
#+end_example
|
|
|
|
|
(hash, blank, 24 dashes, blank, scissor, blank, 24 dashes).
|
|
|
|
|
Note that such a comment will be removed if the git commit option
|
|
|
|
|
=--cleanup=scissor= is used.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
** License policy
|
|
|
|
|
|
|
|
|
|
GnuPG is licensed under the GPLv3+ with some files under a mixed
|
|
|
|
|
LGPLv3+/GPLv2+ license. It is thus important, that all contributed
|
|
|
|
|
code allows for an update of the license; for example we can't
|
|
|
|
|
accept code under the GPLv2(only).
|
|
|
|
|
|
|
|
|
|
GnuPG used to have a strict policy of requiring copyright
|
|
|
|
|
assignments to the FSF. To avoid this major organizational overhead
|
|
|
|
|
and to allow inclusion of code, not copyrighted by the FSF, this
|
|
|
|
|
policy has been relaxed on 2013-03-29. It is now also possible to
|
|
|
|
|
contribute code by asserting that the contribution is in accordance
|
|
|
|
|
to the "Libgcrypt Developer's Certificate of Origin" as found in the
|
|
|
|
|
file "DCO". (Except for a slight wording change, this DCO is
|
|
|
|
|
identical to the one used by the Linux kernel.)
|
|
|
|
|
|
|
|
|
|
If your want to contribute code or documentation to GnuPG and you
|
|
|
|
|
didn't signed a copyright assignment with the FSF in the past, you
|
|
|
|
|
need to take these simple steps:
|
|
|
|
|
|
|
|
|
|
- Decide which mail address you want to use. Please have your real
|
|
|
|
|
name in the address and not a pseudonym. Anonymous contributions
|
|
|
|
|
can only be done if you find a proxy who certifies for you.
|
2011-12-01 10:51:36 +01:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
- If your employer or school might claim ownership of code written
|
|
|
|
|
by you; you need to talk to them to make sure that you have the
|
|
|
|
|
right to contribute under the DCO.
|
2011-12-01 10:51:36 +01:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
- Send an OpenPGP signed mail to the gnupg-devel@gnupg.org mailing
|
|
|
|
|
list from your mail address. Include a copy of the DCO as found
|
|
|
|
|
in the official master branch. Insert your name and email address
|
|
|
|
|
into the DCO in the same way you want to use it later. Example:
|
2011-12-01 10:51:36 +01:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
Signed-off-by: Joe R. Hacker <joe@example.org>
|
2011-12-01 10:51:36 +01:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
(If you really need it, you may perform simple transformations of
|
|
|
|
|
the mail address: Replacing "@" by " at " or "." by " dot ".)
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
- That's it. From now on you only need to add a "Signed-off-by:"
|
|
|
|
|
line with your name and mail address to the commit message. It is
|
|
|
|
|
recommended to send the patches using a PGP/MIME signed mail.
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
** Coding standards
|
|
|
|
|
|
|
|
|
|
Please follow the GNU coding standards. If you are in doubt consult
|
|
|
|
|
the existing code as an example. Do no re-indent code without a
|
|
|
|
|
need. If you really need to do it, use a separate commit for such a
|
|
|
|
|
change.
|
|
|
|
|
|
2015-06-30 11:55:17 +02:00
|
|
|
|
** Commit log keywords
|
|
|
|
|
|
|
|
|
|
- GnuPG-bug-id :: Values are comma or space delimited bug numbers
|
|
|
|
|
from bug.gnupg.org pertaining to this commit.
|
|
|
|
|
- Debian-bug-id :: Same as above but from the Debian bug tracker.
|
|
|
|
|
- CVE-id :: CVE id number pertaining to this commit.
|
|
|
|
|
- Regression-due-to :: Commit id of the regression fixed by this commit.
|
|
|
|
|
- Fixes-commit :: Commit id this commit fixes.
|
|
|
|
|
- Reported-by :: Value is a name or mail address of a bug reporte.
|
|
|
|
|
- Suggested-by :: Value is a name or mail address of someone how
|
|
|
|
|
suggested this change.
|
|
|
|
|
- Co-authored-by :: Name or mail address of a co-author
|
|
|
|
|
- Some-comments-by :: Name or mail address of the author of
|
|
|
|
|
additional comments (commit log or code).
|
|
|
|
|
- Proofread-by :: Sometimes used by translation commits.
|
|
|
|
|
- Signed-off-by :: Name or mail address of the developer
|
|
|
|
|
|
2014-06-16 23:25:44 +02:00
|
|
|
|
* Windows
|
|
|
|
|
** How to build an installer for Windows
|
|
|
|
|
|
|
|
|
|
Your best bet is to use a decent Debian System for development.
|
|
|
|
|
You need to install a long list of tools for building. This list
|
|
|
|
|
still needs to be compiled. However, the build process will stop
|
|
|
|
|
if a tool is missing. GNU make is required (on non GNU systems
|
|
|
|
|
often installed as "gmake"). The installer requires a couple of
|
|
|
|
|
extra software to be available either as tarballs or as local git
|
|
|
|
|
repositories. In case this file here is part of a gnupg-w32-2.*.xz
|
|
|
|
|
complete tarball as distributed from the same place as a binary
|
|
|
|
|
installer, all such tarballs are already included.
|
|
|
|
|
|
|
|
|
|
Cd to the GnuPG source directory and use one of one of these
|
|
|
|
|
command:
|
|
|
|
|
|
|
|
|
|
- If sources are included (gnupg-w32-*.tar.xz)
|
|
|
|
|
|
|
|
|
|
make -f build-aux/speedo.mk WHAT=this installer
|
|
|
|
|
|
|
|
|
|
- To build from tarballs
|
|
|
|
|
|
|
|
|
|
make -f build-aux/speedo.mk WHAT=release TARBALLS=TARDIR installer
|
|
|
|
|
|
|
|
|
|
- To build from local GIT repos
|
|
|
|
|
|
|
|
|
|
make -f build-aux/speedo.mk WHAT=git TARBALLS=TARDIR installer
|
|
|
|
|
|
|
|
|
|
Note that also you need to supply tarballs with supporting
|
|
|
|
|
libraries even if you build from git. The makefile expects only
|
|
|
|
|
the core GnuPG software to be available as local GIT repositories.
|
|
|
|
|
speedo.mk has the versions of the tarballs and the branch names of
|
|
|
|
|
the git repositories. In case of problems, don't hesitate to ask
|
|
|
|
|
on the gnupg-devel mailing for help.
|
|
|
|
|
|
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
* Debug hints
|
|
|
|
|
|
|
|
|
|
See the manual for some hints.
|
|
|
|
|
|
|
|
|
|
* Standards
|
|
|
|
|
** RFCs
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
|
|
|
|
1423 Privacy Enhancement for Internet Electronic Mail:
|
|
|
|
|
Part III: Algorithms, Modes, and Identifiers.
|
|
|
|
|
|
|
|
|
|
1489 Registration of a Cyrillic Character Set.
|
|
|
|
|
|
|
|
|
|
1750 Randomness Recommendations for Security.
|
|
|
|
|
|
2011-12-20 15:55:43 +01:00
|
|
|
|
1991 PGP Message Exchange Formats (obsolete)
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
|
|
|
|
2144 The CAST-128 Encryption Algorithm.
|
|
|
|
|
|
|
|
|
|
2279 UTF-8, a transformation format of ISO 10646.
|
|
|
|
|
|
2011-12-20 15:55:43 +01:00
|
|
|
|
2440 OpenPGP (obsolete).
|
|
|
|
|
|
|
|
|
|
3156 MIME Security with Pretty Good Privacy (PGP).
|
|
|
|
|
|
|
|
|
|
4880 Current OpenPGP specification.
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
2014-06-16 23:25:44 +02:00
|
|
|
|
6337 Elliptic Curve Cryptography (ECC) in OpenPGP
|
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
* Various information
|
|
|
|
|
|
|
|
|
|
** Directory Layout
|
|
|
|
|
|
|
|
|
|
- ./ :: Readme, configure
|
|
|
|
|
- ./agent :: Gpg-agent and related tools
|
|
|
|
|
- ./doc :: Documentation
|
|
|
|
|
- ./g10 :: Gpg program here called gpg2
|
|
|
|
|
- ./sm :: Gpgsm program
|
|
|
|
|
- ./jnlib :: Not used (formerly used utility functions)
|
|
|
|
|
- ./common :: Utility functions
|
|
|
|
|
- ./kbx :: Keybox library
|
|
|
|
|
- ./scd :: Smartcard daemon
|
|
|
|
|
- ./scripts :: Scripts needed by configure and others
|
|
|
|
|
- ./dirmngr :: The directory manager
|
|
|
|
|
|
|
|
|
|
** Detailed Roadmap
|
|
|
|
|
|
2015-06-30 11:55:17 +02:00
|
|
|
|
This list of files is not up to date!
|
2013-03-29 09:13:05 +01:00
|
|
|
|
|
|
|
|
|
- g10/gpg.c :: Main module with option parsing and all the stuff you
|
2015-06-30 11:55:17 +02:00
|
|
|
|
have to do on startup. Also has the exit handler and
|
|
|
|
|
some helper functions.
|
2013-03-29 09:13:05 +01:00
|
|
|
|
|
|
|
|
|
- g10/parse-packet.c ::
|
|
|
|
|
- g10/build-packet.c ::
|
|
|
|
|
- g10/free-packet.c :: Parsing and creating of OpenPGP message packets.
|
|
|
|
|
|
|
|
|
|
- g10/getkey.c :: Key selection code
|
|
|
|
|
- g10/pkclist.c :: Build a list of public keys
|
|
|
|
|
- g10/skclist.c :: Build a list of secret keys
|
2015-06-30 11:55:17 +02:00
|
|
|
|
- g10/keyring.c :: Keyring access functions
|
2013-03-29 09:13:05 +01:00
|
|
|
|
- g10/keydb.h ::
|
|
|
|
|
|
2015-06-30 11:55:17 +02:00
|
|
|
|
- g10/keyid.c :: Helper functions to get the keyid, fingerprint etc.
|
2013-03-29 09:13:05 +01:00
|
|
|
|
|
2015-06-30 11:55:17 +02:00
|
|
|
|
- g10/trustdb.c :: Web-of-Trust computations
|
2013-03-29 09:13:05 +01:00
|
|
|
|
- g10/trustdb.h ::
|
2015-06-30 11:55:17 +02:00
|
|
|
|
- g10/tdbdump.c :: Export/import/list the trustdb.gpg
|
|
|
|
|
- g10/tdbio.c :: I/O handling for the trustdb.gpg
|
|
|
|
|
- g10/tdbio.h ::
|
2013-03-29 09:13:05 +01:00
|
|
|
|
|
|
|
|
|
- g10/compress.c :: Filter to handle compression
|
|
|
|
|
- g10/filter.h :: Declarations for all filter functions
|
|
|
|
|
- g10/delkey.c :: Delete a key
|
2015-06-30 11:55:17 +02:00
|
|
|
|
- g10/kbnode.c :: Helper for the kbnode_t linked list
|
2013-03-29 09:13:05 +01:00
|
|
|
|
- g10/main.h :: Prototypes and some constants
|
|
|
|
|
- g10/mainproc.c :: Message processing
|
|
|
|
|
- g10/armor.c :: Ascii armor filter
|
|
|
|
|
- g10/mdfilter.c :: Filter to calculate hashs
|
|
|
|
|
- g10/textfilter.c :: Filter to handle CR/LF and trailing white space
|
|
|
|
|
- g10/cipher.c :: En-/Decryption filter
|
|
|
|
|
- g10/misc.c :: Utlity functions
|
|
|
|
|
- g10/options.h :: Structure with all the command line options
|
|
|
|
|
and related constants
|
|
|
|
|
- g10/openfile.c :: Create/Open Files
|
2015-06-30 11:55:17 +02:00
|
|
|
|
- g10/keyserver.h :: Keyserver access dispatcher.
|
2013-03-29 09:13:05 +01:00
|
|
|
|
- g10/packet.h :: Defintion of OpenPGP structures.
|
|
|
|
|
- g10/passphrase.c :: Passphrase handling code
|
|
|
|
|
|
2015-06-30 11:55:17 +02:00
|
|
|
|
- g10/pubkey-enc.c :: Process a public key encoded packet.
|
|
|
|
|
- g10/seckey-cert.c :: Not anymore used
|
|
|
|
|
- g10/seskey.c :: Make sesssion keys etc.
|
|
|
|
|
- g10/import.c :: Import keys into our key storage.
|
|
|
|
|
- g10/export.c :: Export keys to the OpenPGP format.
|
|
|
|
|
- g10/sign.c :: Create signature and optionally encrypt.
|
|
|
|
|
- g10/plaintext.c :: Process plaintext packets.
|
|
|
|
|
- g10/decrypt-data.c :: Decrypt an encrypted data packet
|
|
|
|
|
- g10/encrypt.c :: Main encryption driver
|
|
|
|
|
- g10/revoke.c :: Create recovation certificates.
|
|
|
|
|
- g10/keylist.c :: Print information about OpenPGP keys
|
|
|
|
|
- g10/sig-check.c :: Check a signature
|
|
|
|
|
- g10/helptext.c :: Show online help texts
|
|
|
|
|
- g10/verify.c :: Verify signed data.
|
|
|
|
|
- g10/decrypt.c :: Decrypt and verify data.
|
|
|
|
|
- g10/keyedit.c :: Edit properties of a key.
|
|
|
|
|
- g10/dearmor.c :: Armor utility.
|
|
|
|
|
- g10/keygen.c :: Generate a key pair
|
2013-03-29 09:13:05 +01:00
|
|
|
|
|
|
|
|
|
** Memory allocation
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
|
|
|
|
Use only the functions:
|
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
- xmalloc
|
|
|
|
|
- xmalloc_secure
|
|
|
|
|
- xtrymalloc
|
|
|
|
|
- xtrymalloc_secure
|
|
|
|
|
- xcalloc
|
|
|
|
|
- xcalloc_secure
|
|
|
|
|
- xtrycalloc
|
|
|
|
|
- xtrycalloc_secure
|
|
|
|
|
- xrealloc
|
|
|
|
|
- xtryrealloc
|
|
|
|
|
- xstrdup
|
|
|
|
|
- xtrystrdup
|
|
|
|
|
- xfree
|
2006-09-13 15:57:30 +00:00
|
|
|
|
|
|
|
|
|
|
2015-06-30 11:55:17 +02:00
|
|
|
|
The *secure versions allocate memory in the secure memory. That is,
|
2006-09-13 15:57:30 +00:00
|
|
|
|
swapping out of this memory is avoided and is gets overwritten on
|
|
|
|
|
free. Use this for passphrases, session keys and other sensitive
|
|
|
|
|
material. This memory set aside for secure memory is linited to a few
|
|
|
|
|
k. In general the function don't print a memeory message and
|
|
|
|
|
terminate the process if there is not enough memory available. The
|
|
|
|
|
"try" versions of the functions return NULL instead.
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
** Logging
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
TODO
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
** Option parsing
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
GnuPG does not use getopt or GNU getopt but functions of it's own.
|
|
|
|
|
See util/argparse.c for details. The advantage of these functions is
|
|
|
|
|
that it is more easy to display and maintain the help texts for the
|
|
|
|
|
options. The same option table is also used to parse resource files.
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
** What is an IOBUF
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
2013-03-29 09:13:05 +01:00
|
|
|
|
This is the data structure used for most I/O of gnupg. It is similar
|
|
|
|
|
to System V Streams but much simpler. Because OpenPGP messages are
|
|
|
|
|
nested in different ways; the use of such a system has big advantages.
|
|
|
|
|
Here is an example, how it works: If the parser sees a packet header
|
|
|
|
|
with a partial length, it pushes the block_filter onto the IOBUF to
|
|
|
|
|
handle these partial length packets: from now on you don't have to
|
|
|
|
|
worry about this. When it sees a compressed packet it pushes the
|
|
|
|
|
uncompress filter and the next read byte is one which has already been
|
|
|
|
|
uncompressed by this filter. Same goes for enciphered packet,
|
|
|
|
|
plaintext packets and so on. The file g10/encode.c might be a good
|
2015-06-30 11:55:17 +02:00
|
|
|
|
starting point to see how it is used - actually this is the other way:
|
2013-03-29 09:13:05 +01:00
|
|
|
|
constructing messages using pushed filters but it may be easier to
|
|
|
|
|
understand.
|
2006-08-21 20:20:23 +00:00
|
|
|
|
|
|
|
|
|
|