security-and-privacy/gnupg
security-and-privacy/gnupg
1
0
Fork 0
mirror of git://git.gnupg.org/gnupg.git synced 2024-12-22 10:19:57 +01:00
Code Activity

copyright assignments are not anymore required.

Browse Source
This commit is contained in:
Werner Koch 2013-03-29 09:13:05 +01:00
parent 64b1a2cf6f
commit 07227279c4
4 changed files with 223 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
AUTHORS
View File

@ -6,8 +6,8 @@ Security related bug reports: <security@gnupg.org>
License: GPLv3+
Authors
=======
Authors with a FSF copyright assignment
=======================================
Ales Nyakhaychyk <nyakhaychyk@i1fn.linux.by> Translations [be]
@ -131,11 +131,19 @@ Yutaka Niibe Assigns Past and Future Changes
(scd/)
Authors with a DCO
==================
Werner Koch <wk@gnupg.org>
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

352
doc/HACKING
View 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,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 <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.
@ -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.

2
doc/Makefile.am
View File

@ -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 =

5
doc/TRANSLATE
View File

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