gnupg/doc/HACKING

# 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.

* 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.

* 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.