mirror of git://git.gnupg.org/gnupg.git
302 lines
10 KiB
Org Mode
302 lines
10 KiB
Org Mode
# HACKING -*- org -*-
|
||
#+TITLE: A Hacker's Guide to GnuPG
|
||
#+TEXT: Some notes on GnuPG internals
|
||
#+STARTUP: showall
|
||
#+OPTIONS: ^:{}
|
||
|
||
* How to contribute
|
||
|
||
The following stuff explains some basic procedures you need to
|
||
follow if you want to contribute code or documentation.
|
||
|
||
** No more ChangeLog files
|
||
|
||
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
|
||
|
||
** 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.
|
||
|
||
** 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.
|
||
|
||
- 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.
|
||
|
||
- 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:
|
||
|
||
Signed-off-by: Joe R. Hacker <joe@example.org>
|
||
|
||
(If you really need it, you may perform simple transformations of
|
||
the mail address: Replacing "@" by " at " or "." by " dot ".)
|
||
|
||
- 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.
|
||
|
||
** 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.
|
||
|
||
* 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.
|
||
|
||
|
||
* Debug hints
|
||
|
||
See the manual for some hints.
|
||
|
||
* Standards
|
||
** RFCs
|
||
|
||
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.
|
||
|
||
1991 PGP Message Exchange Formats (obsolete)
|
||
|
||
2144 The CAST-128 Encryption Algorithm.
|
||
|
||
2279 UTF-8, a transformation format of ISO 10646.
|
||
|
||
2440 OpenPGP (obsolete).
|
||
|
||
3156 MIME Security with Pretty Good Privacy (PGP).
|
||
|
||
4880 Current OpenPGP specification.
|
||
|
||
6337 Elliptic Curve Cryptography (ECC) in OpenPGP
|
||
|
||
* 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
|
||
|
||
This list of file is not up to date!
|
||
|
||
- g10/gpg.c :: Main module with option parsing and all the stuff you
|
||
have to do on startup. Also has the exout handler
|
||
and some helper functions.
|
||
|
||
- g10/sign.c :: Create signature and optionally encrypt
|
||
|
||
- 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
|
||
- g10/ringedit.c :: Keyring I/O
|
||
- g10/keydb.h ::
|
||
|
||
- g10/keyid.c :: Helper functions to get the keyid, fingerprint etc.
|
||
|
||
|
||
- g10/trustdb.c ::
|
||
- g10/trustdb.h ::
|
||
- g10/tdbdump.c :: Management of the trustdb.gpg
|
||
- g10/tdbio.c ::
|
||
- g10/tdbio.h :: I/O handling for the trustdb.gpg
|
||
|
||
- g10/compress.c :: Filter to handle compression
|
||
- g10/filter.h :: Declarations for all filter functions
|
||
- g10/delkey.c :: Delete a key
|
||
- g10/kbnode.c :: Helper for the KBNODE linked list
|
||
- 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
|
||
- g10/hkp.h :: Keyserver access
|
||
- g10/hkp.c :: Ditto.
|
||
- g10/packet.h :: Defintion of OpenPGP structures.
|
||
- g10/passphrase.c :: Passphrase handling code
|
||
|
||
- g10/pubkey-enc.c ::
|
||
- g10/seckey-cert.c ::
|
||
- g10/seskey.c ::
|
||
- g10/import.c ::
|
||
- g10/export.c ::
|
||
- g10/comment.c ::
|
||
- g10/status.c ::
|
||
- g10/status.h ::
|
||
- g10/sign.c ::
|
||
- g10/plaintext.c ::
|
||
- g10/encr-data.c ::
|
||
- g10/encode.c ::
|
||
- g10/revoke.c ::
|
||
- g10/keylist.c ::
|
||
- g10/sig-check.c ::
|
||
- g10/signal.c ::
|
||
- g10/helptext.c ::
|
||
- g10/verify.c ::
|
||
- g10/decrypt.c ::
|
||
- g10/keyedit.c ::
|
||
- g10/dearmor.c ::
|
||
- g10/keygen.c ::
|
||
|
||
** Memory allocation
|
||
|
||
Use only the functions:
|
||
|
||
- xmalloc
|
||
- xmalloc_secure
|
||
- xtrymalloc
|
||
- xtrymalloc_secure
|
||
- xcalloc
|
||
- xcalloc_secure
|
||
- xtrycalloc
|
||
- xtrycalloc_secure
|
||
- xrealloc
|
||
- xtryrealloc
|
||
- xstrdup
|
||
- xtrystrdup
|
||
- xfree
|
||
|
||
|
||
The *secure versions allocated memory in the secure memory. That is,
|
||
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.
|
||
|
||
** Logging
|
||
|
||
TODO
|
||
|
||
** Option parsing
|
||
|
||
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.
|
||
|
||
** What is an IOBUF
|
||
|
||
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
|
||
staring point to see how it is used - actually this is the other way:
|
||
constructing messages using pushed filters but it may be easier to
|
||
understand.
|
||
|
||
|