[git] gnupg-doc - branch, master, updated. 83cb8037c27558e8de8bc62876a713562f491aed
by Werner Koch
cvs at cvs.gnupg.org
Fri Sep 30 16:31:51 CEST 2016
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "The GnuPG website and other docs".
The branch, master has been updated
via 83cb8037c27558e8de8bc62876a713562f491aed (commit)
via 8b45e3c75e9577167ace97e5c5572f3e79c3f6d3 (commit)
from 5eb502a5405d48057fdbebf683cf3c0c21540d25 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 83cb8037c27558e8de8bc62876a713562f491aed
Author: Werner Koch <wk at gnupg.org>
Date: Fri Sep 30 16:28:55 2016 +0200
faq: Update HACKING.
diff --git a/web/faq/HACKING.org b/web/faq/HACKING.org
index fb71a91..5aec848 100644
--- a/web/faq/HACKING.org
+++ b/web/faq/HACKING.org
@@ -39,25 +39,31 @@ 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
+ - build :: Changes to the build system
- ccid :: The CCID driver in scdaemon
+ - common :: Code in common
- dirmngr :: The dirmngr component
- - w32 :: Windows related code
+ - 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
- - build :: Changes to the build system
+ - scd :: The scdaemon component
- speedo :: Speedo build system specific changes
- - doc :: Documentation 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
-Fix typo in a comment
+doc: Fix typo in a comment
--
#+end_example
@@ -74,7 +80,6 @@ do this after this scissor line:
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
@@ -127,30 +132,70 @@ Note that such a comment will be removed if the git commit option
- 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
- =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.
+ =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_errno()).
- 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.
+ - 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
+*** 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:
@@ -307,7 +352,7 @@ Note that such a comment will be removed if the git commit option
and related constants
- g10/openfile.c :: Create/Open Files
- g10/keyserver.h :: Keyserver access dispatcher.
- - g10/packet.h :: Defintion of OpenPGP structures.
+ - g10/packet.h :: Definition of OpenPGP structures.
- g10/passphrase.c :: Passphrase handling code
- g10/pubkey-enc.c :: Process a public key encoded packet.
commit 8b45e3c75e9577167ace97e5c5572f3e79c3f6d3
Author: Werner Koch <wk at gnupg.org>
Date: Fri Sep 30 11:36:57 2016 +0200
drafts,openpgp-webkey-service: Correctly mark sentences.
diff --git a/misc/id/openpgp-webkey-service/draft.org b/misc/id/openpgp-webkey-service/draft.org
index 29b234e..e259279 100644
--- a/misc/id/openpgp-webkey-service/draft.org
+++ b/misc/id/openpgp-webkey-service/draft.org
@@ -67,7 +67,7 @@
* Abstract
This specification describes a service to locate OpenPGP keys by mail
-address using a Web service and the HTTPS protocol. It also provides a
+address using a Web service and the HTTPS protocol. It also provides a
method for secure communication between the key owner and the mail
provider to publish and revoke the public key.
@@ -77,7 +77,7 @@ provider to publish and revoke the public key.
This memo describes a method to associate OpenPGP keys with a mail
address and how to look them up using a web service with a well-known
-URI. In addition a mail based protocol is given to allow a client to
+URI. In addition a mail based protocol is given to allow a client to
setup such an association and to maintain it.
* Notational Conventions
@@ -89,17 +89,17 @@ document are to be interpreted as described in {{{RFC(2119)}}}.
* Web Key Directory
-A major use case for OpenPGP is the encryption of mail. A common
+A major use case for OpenPGP is the encryption of mail. A common
difficulty of sending encrypted mails to a new communication partner is
-to find the appropriate public key of the recipient. Unless an
+to find the appropriate public key of the recipient. Unless an
off-channel key exchange has been done, there are no easy ways to
-discover the required key. The common practice is to search the network
+discover the required key. The common practice is to search the network
of public key servers for a key matching the recipient's mail address.
This practise bears the problem that the keyservers are not able to give
a positive confirmation that a key actually belongs to the mail
-addresses given in the key. Further, there are often several keys
+addresses given in the key. Further, there are often several keys
matching a mail address and thus one needs to pick a key on good luck.
-This is clearly not a secure way to setup an end-to-end encryption. Even
+This is clearly not a secure way to setup an end-to-end encryption. Even
if the need for a trusted key for an initial mail message is
relinquished, a non-authenticated key may be a wrong one and the actual
recipient would receive a mail which she can't decrypt, due to the use
@@ -116,11 +116,11 @@ the initial mail, an extra mail round-trip, and problems with unattended
key discovery.
The latter method works fine but requires that mail providers need to
-set up a separate DNS resolver to provide the key. The administration of
-a DNS zone is often not in the hands of small mail installations. Thus
+set up a separate DNS resolver to provide the key. The administration of
+a DNS zone is often not in the hands of small mail installations. Thus
an update of the DNS resource records needs to be delegated to the ISP
-running the DNS service. Further, DNS lookups are not encrypted and
-missing all confidentially. Even if the participating MUAs are using
+running the DNS service. Further, DNS lookups are not encrypted and
+missing all confidentially. Even if the participating MUAs are using
STARTTLS to encrypt the mail exchange, a DNS lookup for the key
unnecessarily identifies the local-part of the recipients mail address
to any passive eavesdroppers.
@@ -132,25 +132,25 @@ https connection.
Although URIs are able to encode all kind of characters, straightforward
implementations of a key directory may want to store the "local-part" of
-a mail address directly in the file system. This forbids the use of
-certain characters in the "local-part". To allow for such an
+a mail address directly in the file system. This forbids the use of
+certain characters in the "local-part". To allow for such an
implementation method the URI uses an encoded form of the "local-part"
which can be directly mapped to a file name.
OpenPGP defines its User IDs, and thus the mail address, as UTF-8
-strings. To help with the common pattern of using capitalized names
+strings. To help with the common pattern of using capitalized names
(e.g. "Joe.Doe at example.org") for mail addresses, and under the premise
that almost all MTAs treat the "local-part" case-insensitive and that
the "domain-part" is required to be compared case-insensitive anyway,
all upper-case ASCII characters in a User ID are mapped to lowercase.
Non-ASCII characters are not changed.
-The so mapped "local-part" is hashed using the SHA-1 algorithm. The
+The so mapped "local-part" is hashed using the SHA-1 algorithm. The
resulting 160 bit digest is encoded using the Z-Base-32 method as
-described in {{{RFC(6189)}}}, section 5.1.6. The resulting string has a
-fixed length of 32 octets. To form the URI, the scheme
+described in {{{RFC(6189)}}}, section 5.1.6. The resulting string has a
+fixed length of 32 octets. To form the URI, the scheme
{{{https_scheme}}} is concatenated with the mapped "domain-part", the
-fixed string ~./well-known/openpgpkey/hu/~, and the above constructed
+fixed string ~/.well-known/openpgpkey/hu/~, and the above constructed
32 octet string.
For example the URI to lookup the key for Joe.Doe at Example.ORG is:
@@ -163,32 +163,32 @@ For example the URI to lookup the key for Joe.Doe at Example.ORG is:
(line has been wrapped for rendering purposes)
The HTTP GET method MUST return the binary representation of the OpenPGP
-key for the given mail address. The key needs to carry a User ID packet
-({{{RFC(4880)}}}) with that mail address. Note that the key may be
+key for the given mail address. The key needs to carry a User ID packet
+({{{RFC(4880)}}}) with that mail address. Note that the key may be
revoked or expired - it is up to the client to handle such conditions.
The server MUST also accept a HEAD method so that a client may only
check for the existence of a key.
-The server SHOULD return "application/octet-string" as the content-type
-for the data but clients MAY also accept any other appropriate
-content-type. The server MUST NOT return an ASCII armored version of the
-key.
+The server SHOULD return "application/octet-string" as the
+content-type for the data but clients SHOULD also accept any other
+content-type. The server MUST NOT return an ASCII armored version of
+the key.
* Web Key Directory Update Protocol
To put keys into the key directory a protocol to automate the task is
-desirable. The protocol defined here is entirely based on mail and the
-assumption that a mail provider can securely deliver mail to the INBOX
-of a user (e.g. an IMAP folder). Note that the same protocol may also be
-used for submitting keys for use with OpenPGP DANE.
+desirable. The protocol defined here is entirely based on mail and
+the assumption that a mail provider can securely deliver mail to the
+INBOX of a user (e.g. an IMAP folder). Note that the same protocol
+may also be used for submitting keys for use with OpenPGP DANE.
We assume that the user already created a key for her mail account
-alice at example.org. To install the key at her provider's Web Key
+alice at example.org. To install the key at her provider's Web Key
Directory, she performs the following steps:
1. She retrieves a file which contains one line with the mail address
- used to submit the key to the mail provider. See below for the syntax
- of that file. For a mail address at the domain "example.org" the URI
+ used to submit the key to the mail provider. See below for the syntax
+ of that file. For a mail address at the domain "example.org" the URI
of the file is
#+begin_example
https://example.org/.well-known/openpgpkey/submission-address
@@ -202,30 +202,30 @@ Directory, she performs the following steps:
an account name of the provider.
4. The provider sends an encrypted message containing a nonce and the
- fingerprint of the key to the mail account of the user. Note that a
+ fingerprint of the key to the mail account of the user. Note that a
similar scheme is used by the well known caff(1) tool to help with
key signing parties.
5. A legitimate user will be able to decrypt the message because she
- created the key and is in charge of the private key. This step
+ created the key and is in charge of the private key. This step
verifies that the submitted key has actually been created by the
owner of the account.
-6. The user sends the decrypted nonce back to the submission address as
- a confirmation that the private key is owned by her and that the
- provider may now publish the key. Also technically not required, it
- is suggested that the mail to the provider is encrypted. The public
- key for this is retrieved using the key lookup protocol described
- above.
+6. The user sends the decrypted nonce back to the submission address
+ as a confirmation that the private key is owned by her and that the
+ provider may now publish the key. Although technically not
+ required, it is suggested that the mail to the provider is
+ encrypted. The public key for this is retrieved using the key
+ lookup protocol described above.
7. The provider receives the nonce, matches it with its database of
- pending confirmations and then publishes the key. Finally the
- provider sends a mail back to the user to notify her of the the
+ pending confirmations and then publishes the key. Finally the
+ provider sends a mail back to the user to notify her of the
publication of her key.
The message data structures used for the above protocol are specified in
-detail below. In the following sections the string "WELLKNOWN" denotes
-the first part of an URI specific for a domain. In the examples the
+detail below. In the following sections the string "WELLKNOWN" denotes
+the first part of an URI specific for a domain. In the examples the
domain "example.org" is assumed, thus
#+BEGIN_EXAMPLE
@@ -246,7 +246,7 @@ The address of the submission file is
The file consists of exactly one line, terminated by a LF, or the
sequence of CR and LF, with the full mail address to be used for
-submission of a key to the mail provider. For example the content of the
+submission of a key to the mail provider. For example the content of the
file may be
#+BEGIN_EXAMPLE
@@ -265,25 +265,25 @@ transferable Public Key Packets as defined in {{{RFC(4880)}}}, section
If the mail provider has published an encryption key for the
submission-address in the Web Key Directory, the key to be published
MUST be submitted using a PGP/MIME encrypted message ({{{RFC(3156)}}},
-section 4). The message MUST NOT be signed (because the authenticity of
-the signing key has not yet been confirmed). After decryption of the
+section 4). The message MUST NOT be signed (because the authenticity of
+the signing key has not yet been confirmed). After decryption of the
message at the mail provider a single "application/pgp-keys" part, as
specified above, is expected.
** The Confirmation Request
The mail provider sends a confirmation mail in response to a received
-key publication request. The message SHOULD be sent from the
+key publication request. The message SHOULD be sent from the
submission-address of the mail provider to the mail address extracted
-from the target key. The message needs to be encrypted to the target key
-and MAY be signed by the submission key. PGP/MIME MUST be used for
+from the target key. The message needs to be encrypted to the target key
+and MAY be signed by the submission key. PGP/MIME MUST be used for
encryption and signing; the Combined method ({{{RFC(3156)}}}, section
6.2) MUST be used if the message is to be signed.
The Content-type used for the plaintext part MUST be
-"application/vnd.gnupg.wkd". The body consists of name-value pairs with
-one name-value pair per LF or CR+LF terminated line. Empty lines are
-allowed and will be ignored by the receiver. A colon is used to
+"application/vnd.gnupg.wkd". The body consists of name-value pairs with
+one name-value pair per LF or CR+LF terminated line. Empty lines are
+allowed and will be ignored by the receiver. A colon is used to
terminate a name.
In a confirmation request the following names MUST be send in the
@@ -292,30 +292,30 @@ specified order:
- "type" :: The value must be "confirmation-request".
- "sender" :: This is the mailbox the user is expected to sent the
- confirmation response to. The value must match the
+ confirmation response to. The value must match the
mailbox part of the "From:" address of this
- request. Exactly one address MUST be given.
+ request. Exactly one address MUST be given.
- "address" :: The value is the addr-spec part of the target key's
- mail address. The value SHOULD match the addr-spec part
- of the recipient's address. The value MUST be UTF-8
+ mail address. The value SHOULD match the addr-spec part
+ of the recipient's address. The value MUST be UTF-8
encoded as required for an OpenPGP User ID.
-- "fingerprint" :: The value is the fingerprint of the target key. The
+- "fingerprint" :: The value is the fingerprint of the target key. The
fingerprint is given in uppercase hex encoding
without any interleaving spaces.
- "nonce" :: The value is a string with a minimum length of 16 octets
- and a maximum length of 64 octets. The string must
+ and a maximum length of 64 octets. The string must
entirely be made up of random ASCII letters or
- digits. This nonce will be sent back to the mail provider
+ digits. This nonce will be sent back to the mail provider
as proof that the recipient is the legitimate owner of
the target-key.
The receiver of the message decrypts the message, checks that the
"fingerprint" matches the target key, checks that the "address" matches
a User ID of the target key, and checks the other constrains of the
-request format. If any constraint is not asserted, or the fingerprint or
+request format. If any constraint is not asserted, or the fingerprint or
User ID do not match the target key, or there is no pending publication
requests (i.e. a mail recently sent o the submission address), the user
MAY be notified about this fake confirmation attempt.
@@ -326,27 +326,27 @@ silently send a response as described in the next section.
** The Confirmation Response
A response to a confirmation request MUST only be send in the positive
-case; there is no negative confirmation response. A mail service
+case; there is no negative confirmation response. A mail service
provider is expected to cancel a pending key submission after a suitable
-time without a confirmation. The mail service provider SHOULD NOT retry
+time without a confirmation. The mail service provider SHOULD NOT retry
the sending of a confirmation request after the first request has been
send successfully.
The user MUST send the confirmation response from her target mail
-address to the "from" address of the confirmation request. The message
-MUST be signed and SHOULD be encrypted. The PGP/MIME Combined format
+address to the "from" address of the confirmation request. The message
+MUST be signed and SHOULD be encrypted. The PGP/MIME Combined format
MUST be used for encryption and signing ({{{RFC(3156)}}}, section 6.2).
The encryption key can be taken from the Web Key Directory.
The Content-type used for the plaintext message MUST also be
-"application/vnd.gnupg.wkd". The format is the same as described above
-for the Confirmation Request. The body must contain three name-value
+"application/vnd.gnupg.wkd". The format is the same as described above
+for the Confirmation Request. The body must contain three name-value
pairs in this order:
- "type" :: The value must be "confirmation-response".
- "sender" :: The value must match the mailbox part of the "From:"
- address of this response. Exactly one address MUST be
+ address of this response. Exactly one address MUST be
given.
- "nonce" :: The value is the value of the "nonce" parameter from the
@@ -355,7 +355,7 @@ pairs in this order:
** Policy Flags
For key generation and submission it is sometimes useful to tell the
-client about certain properties of the mail provider in advance. This
+client about certain properties of the mail provider in advance. This
can be done with a file at the URL
#+BEGIN_EXAMPLE
@@ -363,11 +363,11 @@ can be done with a file at the URL
#+END_EXAMPLE
The file contains keywords and optioanlly values, one per line with
-each line terminated by a LF or the sequence of CR and LF. Empty lines
+each line terminated by a LF or the sequence of CR and LF. Empty lines
and lines starting with a '#' character are considered comment
-lines. A keyword is made up of lowercase letters, digits, hyphens, or
-dots. An underscore is allowed as a name space delimiters; see
-below. The first character must be a letter. Keywords which are
+lines. A keyword is made up of lowercase letters, digits, hyphens, or
+dots. An underscore is allowed as a name space delimiters; see
+below. The first character must be a letter. Keywords which are
defined to require a value are directly followed by a colon and then
after optional white space the value. Clients MUST use
case-insensitive matching for the keyword.
@@ -375,12 +375,12 @@ case-insensitive matching for the keyword.
Currently defined keywords are:
- "mailbox-only" :: The mail server provider does only accept keys
- with only a mailbox in the User ID. In particular
+ with only a mailbox in the User ID. In particular
User IDs with a real name in addition to the
mailbox will be rejected as invalid.
- "dane-only" :: The mail server provider does not run a Web Key
- Directory but only an OpenPGP DANE service. The Web
+ Directory but only an OpenPGP DANE service. The Web
Key Directory Update protocol is used to update the
keys for the DANE service.
@@ -390,7 +390,7 @@ Currently defined keywords are:
any confirmation request.
-More keywords will be defined in updates to this I-D. There is no
+More keywords will be defined in updates to this I-D. There is no
registry except for this document. For experimental use of new
features or for provider specific settings, keywords MUST be prefixed
with a domain name and an underscore.
@@ -399,11 +399,11 @@ with a domain name and an underscore.
The use of SHA-1 for the mapping of the "local-part" to a fixed string
is not a security feature but merely used to map the local-part to a
-fixed-sized string made from a well defined set of characters. It is not
+fixed-sized string made from a well defined set of characters. It is not
intended to conceal information about a mail address.
The domain name part of the mail address is not part of the hash to
-avoid problems with internationalized domain names. Instead a separate
+avoid problems with internationalized domain names. Instead a separate
web service is required for each domain name.
* IANA Considerations
-----------------------------------------------------------------------
Summary of changes:
misc/id/openpgp-webkey-service/draft.org | 154 +++++++++++++++----------------
web/faq/HACKING.org | 85 +++++++++++++----
2 files changed, 142 insertions(+), 97 deletions(-)
hooks/post-receive
--
The GnuPG website and other docs
http://git.gnupg.org
More information about the Gnupg-commits
mailing list