summaryrefslogtreecommitdiffstats
path: root/doc/HACKING
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/HACKING433
1 files changed, 433 insertions, 0 deletions
diff --git a/doc/HACKING b/doc/HACKING
new file mode 100644
index 0000000..bd16856
--- /dev/null
+++ b/doc/HACKING
@@ -0,0 +1,433 @@
+# 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
+ - build :: Changes to the build system
+ - ccid :: The CCID driver in scdaemon
+ - common :: Code in common
+ - dirmngr :: The dirmngr component
+ - doc :: Documentation changes
+ - gpg :: The gpg or gpgv components
+ - sm :: The gpgsm component (also "gpgsm")
+ - gpgscm :: The regression test driver
+ - indent :: Indentation and similar changes
+ - iobuf :: The IOBUF system in common
+ - po :: Translations
+ - scd :: The scdaemon component
+ - speedo :: Speedo build system specific changes
+ - ssh :: The ssh-agent part of the agent
+ - tests :: The regressions tests
+ - tools :: Other code in tools
+ - w32 :: Windows related code
+ - wks :: The web key service tools
+ - yat2m :: The yat2m tool.
+
+Typo fixes and documentation updates don't need a ChangeLog entry;
+thus you would use a commit message like
+
+#+begin_example
+doc: 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.
+ - Do not use comments like:
+#+begin_src
+ if (foo)
+ /* Now that we know that foo is true we can call bar. */
+ bar ();
+#+end_src
+ instead write the comment on the if line or before it. You may
+ also use a block and put the comment inside.
+ - Please use asterisks on the left of longer comments. This makes
+ it easier to read without syntax highlighting, on printouts, and
+ for blind people.
+ - Try to fit lines into 80 columns.
+ - Ignore signed/unsigned pointer mismatches
+ - No arithmetic on void pointers; cast to char* first.
+ - Do not use
+#+begin_src
+ if ( 42 == foo )
+#+end_src
+ this is harder to read and modern compilers are pretty good in
+ detecing accidential assignments. It is also suggested not to
+ compare to 0 or NULL but to test the value direct or with a '!';
+ this makes it easier to see that a boolean test is done.
+ - We use our own printf style functions like =es_printf=, and
+ =gpgrt_asprintf= (or the =es_asprintf= macro) which implement most
+ C99 features with the exception of =wchar_t= (which should anyway
+ not be used). Please use them always 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. Note also that in
+ gnupg asprintf is a macro already evaluating to gpgrt_asprintf.
+ - 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.
+ - New code shall in general use xtrymalloc or xtrycalloc and check
+ for an error (use gpg_error_from_syserror()).
+ - 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.
+ - Put extra parenthesis around terms with binary operators to make
+ it clear that the binary operator was indeed intended.
+ - Use --enable-maintainer-mode with configure so that all suitable
+ warnings are enabled.
+
+** Variable names
+
+ Follow the GNU standards. Here are some conventions you may want to
+ stick to (do not rename existing "wrong" uses without a goog
+ reason).
+
+ - err :: This conveys an error code of type =gpg_error_t= which is
+ compatible to an =int=. To compare such a variable to a
+ GPG_ERR_ constant, it is necessary to map the value like
+ this: =gpg_err_code(err)=.
+ - ec :: This is used for a gpg-error code which has no source part
+ (=gpg_err_code_t=) and will eventually be used as input to
+ =gpg_err_make=.
+ - rc :: Used for all kind of other errors; for example system
+ calls. The value is not compatible with gpg-error.
+
+
+*** 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.
+ - Updates-commit :: Commit id this commit updates.
+ - 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.
+
+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.
+
+ - 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 :: Utility 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 :: Definition 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 session 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 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.
+
+