gpg: Remove the extra prompt for Curve25519.
[gnupg.git] / doc / HACKING
index 27faa87..2f3dd43 100644 (file)
-                         A Hacker's Guide to GNUPG
-                      ================================
-                      (Some notes on GNUPG internals.)
-
-
-
-Memory allocation
------------------
-Use only the functions:
-
-    m_alloc()
-    m_alloc_clear()
-    m_strdup()
-    m_free()
-
-If you want to store a passphrase or some other sensitive data you may
-want to use m_alloc_secure() instead of m_alloc(), as this puts the data
-into a memory region which is protected from swapping (on some platforms).
-m_free() works for both.  This functions will not return if there is not
-enough memory available.
-
-
-
-Logging
--------
+# 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.
+
+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=.
 
-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 funtions 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.
+** 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
 
-What is an iobuf
-----------------
-This is the data structure used for most I/O of gnupg. It is similiar
-to System V Streams but much simpler.  It should be replaced by a cleaner
-and faster implementation.  We are doing to much copying and the semantics
-of "filter" removing are not very clean.  EOF handling is also a problem.
+   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 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.
 
-How to use the message digest functions
----------------------------------------
-cipher/md.c implements an interface to hash (message diesgt functions).
-
-a) If you have a common part of data and some variable parts
-   and you need to hash of the concatenated parts, you can use this:
-       md = md_open(...)
-       md_write( md,  common_part )
-       md1 = md_copy( md )
-       md_write(md1, part1)
-       md_final(md1);
-       digest1 = md_read(md1)
-       md2 = md_copy( md )
-       md_write(md2, part2)
-       md_final(md2);
-       digest2 = md_read(md2)
-
-   An example are key signatures; the key packet is the common part
-   and the user-id packets are the variable parts.
-
-b) If you need a running digest you should use this:
-       md = md_open(...)
-       md_write( md, part1 )
-       digest_of_part1 = md_digest( md );
-       md_write( md, part2 )
-       digest_of_part1_cat_part2 = md_digest( md );
-       ....
-
-Both methods may be combined. [Please see the source for the real syntax]
-
-
-
-
-How to use the cipher functions
--------------------------------
+  - 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:
 
-How to use the public key functions
------------------------------------
+ - 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
+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
+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.