gpg: Remove the extra prompt for Curve25519.
[gnupg.git] / doc / HACKING
index d6cb8ab..2f3dd43 100644 (file)
@@ -1,9 +1,15 @@
-                     A Hacker's Guide to GNUPG
-                  ================================
-                  (Some notes on GNUPG internals.)
+# HACKING                                                       -*- org -*-
+#+TITLE: A Hacker's Guide to GnuPG
+#+TEXT: Some notes on GnuPG internals
+#+STARTUP: showall
+#+OPTIONS: ^:{}
 
+* How to contribute
 
-* No more ChangeLog files
+  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
@@ -12,25 +18,215 @@ 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're used to 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.
-
-
-
-===> What follows is probably out of date <===
-
-
-RFCs
-====
+** 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.
+
+The one-line summary usually starts with a keyword to identify the
+mainly affected subsystem.  If more than one keyword is required the
+are delimited by a comma (e.g. =scd,w32:=). Commonly found keywords
+are
+
+ - agent   :: The gpg-agent component
+ - ssh     :: The ssh-agent part of the agent
+ - common  :: Code in common
+ - iobuf   :: The IOBUF system in common
+ - gpg     :: The gpg or gpgv components
+ - gpgsm   :: The gpgsm component
+ - scd     :: The scdaemon component
+ - ccid    :: The CCID driver in scdaemon
+ - dirmngr :: The dirmngr component
+ - w32     :: Windows related code
+ - po      :: Translations
+ - build   :: Changes to the build system
+ - speedo  :: Speedo build system specific changes
+ - doc     :: Documentation changes
+
+Typo fixes and documentation updates don't need a ChangeLog entry;
+thus you would use a commit message like
+
+#+begin_example
+Fix typo in a comment
+
+--
+#+end_example
+
+The marker line here is important; without it the first line would
+appear in the ChangeLog.
+
+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.
+
+
+** 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 you want to contribute code or documentation to GnuPG and you
+  didn't sign 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.
+
+  - Only certain C99 features may be used (see below); in general
+    stick to C90.
+  - Please do not use C++ =//= style comments.
+  - Try to fit lines into 80 columns.
+  - Ignore signed/unsigned pointer mismatches
+  - No arithmetic on void pointers; cast to char* first.
+  - We use our own printf style functions like =es_printf=, and
+    =es_asprintf= which implement most C99 features with the exception
+    of =wchar_t= (which should anyway not be used).  Please always use
+    them and do not resort to those provided by libc.  The rationale
+    for using them is that we know that the format specifiers work on
+    all platforms and that we do not need to chase platform dependent
+    bugs.
+  - It is common to have a label named "leave" for a function's
+    cleanup and return code.  This helps with freeing memory and is a
+    convenient location to set a breakpoint for debugging.
+  - Always use xfree() instead of free().  If it is not easy to see
+    that the freed variable is not anymore used, explicitly set the
+    variable to NULL.
+  - Init function local variables only if needed so that the compiler
+    can do a better job in detecting uninitialized variables which may
+    indicate a problem with the code.
+  - Never init static or file local variables to 0 to make sure they
+    end up in BSS.
+  - Use --enable-maintainer-mode with configure.
+
+*** C99 language features
+
+  In GnuPG 2.x, but *not in 1.4* and not in most libraries, a limited
+  set of C99 features may be used:
+
+  - Variadic macros:
+    : #define foo(a,...)  bar(a, __VA_ARGS__)
+
+  - The predefined macro =__func__=:
+    : log_debug ("%s: Problem with foo\n", __func__);
+
+  - Variable declaration inside a for():
+    : for (int i = 0; i < 5; ++)
+    :   bar (i);
+
+  Although we usually make use of the =u16=, =u32=, and =u64= types,
+  it is also possible to include =<stdint.h>= and use =int16_t=,
+  =int32_t=, =int64_t=, =uint16_t=, =uint32_t=, and =uint64_t=.  But do
+  not use =int8_t= or =uint8_t=.
+
+** 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
+
+* 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.
@@ -39,123 +235,119 @@ RFCs
 
 1750  Randomness Recommendations for Security.
 
-1991  PGP Message Exchange Formats.
-
-2015  MIME Security with Pretty Good Privacy (PGP).
+1991  PGP Message Exchange Formats (obsolete)
 
 2144  The CAST-128 Encryption Algorithm.
 
 2279  UTF-8, a transformation format of ISO 10646.
 
-2440  OpenPGP.
-
-
-
-Directory Layout
-----------------
-  ./          Readme, configure
-  ./agent      Gpg-agent and related tools
-  ./doc        Documentation
-  ./doc        Documentation
-  ./g10        Gpg program here called gpg2
-  ./jnlib      Utility functions
-  ./kbx        Keybox library
-  ./scd        Smartcard daemon
-  ./scripts    Scripts needed by configure and others
-  ./sm         Gpgsm program
-
-
-Detailed Roadmap
-----------------
-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/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/tdbio.c    I/O handling for the trustdb.gpg
-g10/tdbio.h
-g10/hkp.h      Keyserver access
-g10/hkp.c
-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
------------------
+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 files 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 exit handler and
+                 some helper functions.
+
+  - 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/keyring.c  :: Keyring access functions
+  - g10/keydb.h    ::
+
+  - g10/keyid.c          :: Helper functions to get the keyid, fingerprint etc.
+
+  - g10/trustdb.c :: Web-of-Trust computations
+  - g10/trustdb.h ::
+  - g10/tdbdump.c :: Export/import/list the trustdb.gpg
+  - g10/tdbio.c   :: I/O handling for the trustdb.gpg
+  - g10/tdbio.h   ::
+
+  - 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_t 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/keyserver.h :: Keyserver access dispatcher.
+  - g10/packet.h   :: Defintion of OpenPGP structures.
+  - g10/passphrase.c :: Passphrase handling code
+
+  - 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
+
+** 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,
- xmalloc
- xmalloc_secure
- xtrymalloc
- xtrymalloc_secure
- xcalloc
- xcalloc_secure
- xtrycalloc
- xtrycalloc_secure
- xrealloc
- xtryrealloc
- xstrdup
- xtrystrdup
- xfree
+
+
+The *secure versions allocate 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
@@ -163,37 +355,31 @@ 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
 
-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.
+** 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
 
-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.
+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
+starting 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.