From 07227279c44e3af0939f90025a0d22b782d0f185 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Fri, 29 Mar 2013 09:13:05 +0100 Subject: [PATCH] copyright assignments are not anymore required. --- AUTHORS | 18 ++- doc/HACKING | 352 ++++++++++++++++++++++++++++-------------------- doc/Makefile.am | 2 +- doc/TRANSLATE | 5 +- 4 files changed, 223 insertions(+), 154 deletions(-) diff --git a/AUTHORS b/AUTHORS index cfcf98450..374111be2 100644 --- a/AUTHORS +++ b/AUTHORS @@ -6,8 +6,8 @@ Security related bug reports: License: GPLv3+ -Authors -======= +Authors with a FSF copyright assignment +======================================= Ales Nyakhaychyk Translations [be] @@ -131,11 +131,19 @@ Yutaka Niibe Assigns Past and Future Changes (scd/) +Authors with a DCO +================== + +Werner Koch +2013-03-29:87620ahchj.fsf@vigenere.g10code.de: + + Other authors ============= -The need for copyright disclaimers for translations has been waived in -December 2012. +The need for copyright assignments to the FSF has been waived on +2013-03-29; the need for copyright disclaimers for translations +already in December 2012. The files common/libestream.[ch] are maintained as a separate project by g10 Code GmbH. These files, as used here, are considered part of @@ -181,7 +189,7 @@ name gpg2keys_*. Copyright 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, - 2012 Free Software Foundation, Inc. + 2012, 2013 Free Software Foundation, Inc. This file is free software; as a special exception the author gives unlimited permission to copy and/or distribute it, with or without diff --git a/doc/HACKING b/doc/HACKING index 0ef5b891d..8116c3f3a 100644 --- a/doc/HACKING +++ b/doc/HACKING @@ -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,26 +18,88 @@ 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 -* 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. -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. -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 -===> What follows is probably out of date <=== +-- +#+end_example +The marker line here is important; without it the first line would +appear in the ChangeLog. -RFCs -==== +** 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 + + (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. @@ -52,110 +120,110 @@ RFCs 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. -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 + - 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 -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/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 :: -g10/parse-packet.c -g10/build-packet.c -g10/free-packet.c - Parsing and creating of OpenPGP message packets. +** Memory allocation -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 ------------------ Use only the functions: - xmalloc - xmalloc_secure - xtrymalloc - xtrymalloc_secure - xcalloc - xcalloc_secure - xtrycalloc - xtrycalloc_secure - xrealloc - xtryrealloc - xstrdup - xtrystrdup - xfree + - 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, @@ -166,37 +234,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 -------- - - - - - - -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. + 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. diff --git a/doc/Makefile.am b/doc/Makefile.am index 9a46a0751..17d5997fd 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -43,7 +43,7 @@ info_TEXINFOS = gnupg.texi dist_pkgdata_DATA = qualified.txt com-certs.pem $(helpfiles) -nobase_dist_doc_DATA = FAQ DETAILS HACKING TRANSLATE OpenPGP KEYSERVER \ +nobase_dist_doc_DATA = FAQ DETAILS HACKING DCO TRANSLATE OpenPGP KEYSERVER \ $(examples) #dist_html_DATA = diff --git a/doc/TRANSLATE b/doc/TRANSLATE index 8dfc18348..38a6fd9b3 100644 --- a/doc/TRANSLATE +++ b/doc/TRANSLATE @@ -57,6 +57,5 @@ also strongly advise to get subscribed to i18n@gnupg.org and request assistance if it is not clear on how to translate certain strings. A wrongly translated string may lead to a security problem. -A copyright disclaimer to the FSF is required by all translators. - - +A copyright disclaimer to the FSF is not anymore required since +December 2012.