[git] gnupg-doc - branch, master, updated. 5094fddd47141c6f52f41b23a461bba20147661b
by Werner Koch
cvs at cvs.gnupg.org
Mon May 16 21:22:32 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 5094fddd47141c6f52f41b23a461bba20147661b (commit)
via b35cc5cb1c17ca3f5220fad48e81c157d6b54a02 (commit)
from 49e14dd7905a3f331cee7ee5edc250e3db1112c3 (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 5094fddd47141c6f52f41b23a461bba20147661b
Author: Werner Koch <wk at gnupg.org>
Date: Mon May 16 21:20:51 2016 +0200
drafts: openpgp-webkey-service - Convert to org-mode
This does now use a single file and a Makefile.
diff --git a/misc/id/openpgp-webkey-service/Makefile b/misc/id/openpgp-webkey-service/Makefile
new file mode 100644
index 0000000..5e95728
--- /dev/null
+++ b/misc/id/openpgp-webkey-service/Makefile
@@ -0,0 +1,25 @@
+
+MD_EXAMPLE_FIX = '(defun org-md-example-block (example-block contents info) \
+"with fixed indentation" \
+(replace-regexp-in-string \
+"^" " " \
+(org-remove-indentation \
+ (org-export-format-code-default example-block info))))'
+
+
+draft.txt: draft.org
+ emacs --batch \
+ --eval "(require 'org)" \
+ --eval "(require 'ox-md)" \
+ --eval $(MD_EXAMPLE_FIX) \
+ --visit "draft.org" \
+ --eval "(org-md-export-to-markdown)"
+ sed <draft.md -n '/^# Abstract/q;1,$$ p' >template.xml
+ sed <draft.md -n '/^# Abstract/,/^# Middle/p' | \
+ sed '1 d;$$ d' >tmp-abstract.md
+ sed <draft.md -n '/^# Middle/,/^# Back/p' | \
+ sed '1 d;$$ d' >tmp-middle.md
+ sed <draft.md -n '/^# Back/,$$ p' | \
+ sed '1 d' >tmp-back.md
+ pandoc2rfc tmp-abstract.md tmp-middle.md tmp-back.md
+ rm template.xml tmp-abstract.md tmp-middle.md tmp-back.md
diff --git a/misc/id/openpgp-webkey-service/abstract.mkd b/misc/id/openpgp-webkey-service/abstract.mkd
deleted file mode 100644
index d8596be..0000000
--- a/misc/id/openpgp-webkey-service/abstract.mkd
+++ /dev/null
@@ -1,4 +0,0 @@
-This specification describes a service to locate OpenPGP keys by mail
-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.
diff --git a/misc/id/openpgp-webkey-service/back.mkd b/misc/id/openpgp-webkey-service/back.mkd
deleted file mode 100644
index f081a8f..0000000
--- a/misc/id/openpgp-webkey-service/back.mkd
+++ /dev/null
@@ -1,26 +0,0 @@
-# Test Vectors
-
-For help implementing this specification a non-normative example is
-given:
-
-## Sample key
-
- TODO
-
-## Software Notes
-
- GnuPG supports the key discovery described in this document since
- version 2.1.12. To use it, the new method "wkd" needs to be used
- with the --auto-key-locate option.
-
-# Changes since -00
-
- - Changed field names in the request and response format.
- - Removed useless checks.
- - Added a new policy flag.
- - Dropped the second occurrence of the domain name from the URL.
-
-## TODO
-
- - What about authenticated submission?
- - Describe how to handle a key with several User IDs.
diff --git a/misc/id/openpgp-webkey-service/draft.org b/misc/id/openpgp-webkey-service/draft.org
new file mode 100644
index 0000000..b10dedf
--- /dev/null
+++ b/misc/id/openpgp-webkey-service/draft.org
@@ -0,0 +1,446 @@
+# openpgp-webkey-service
+#+startup: showall
+#+options: toc:nil
+#+macro: RFC [](#RFC$1)
+#+macro: https_scheme ~https://~
+
+#+begin_src rfc
+<?xml version="1.0" ?>
+<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
+ <!ENTITY pandocAbstract PUBLIC '' 'tmp-abstract.xml'>
+ <!ENTITY pandocMiddle PUBLIC '' 'tmp-middle.xml'>
+ <!ENTITY pandocBack PUBLIC '' 'tmp-back.xml'>
+ <!ENTITY rfc.2119 PUBLIC '' '../common/reference.RFC.2119.xml'>
+ <!ENTITY rfc.3156 PUBLIC '' '../common/reference.RFC.3156.xml'>
+ <!ENTITY rfc.4880 PUBLIC '' '../common/reference.RFC.4880.xml'>
+ <!ENTITY rfc.5226 PUBLIC '' '../common/reference.RFC.5226.xml'>
+ <!ENTITY rfc.5785 PUBLIC '' '../common/reference.RFC.5785.xml'>
+ <!ENTITY rfc.6189 PUBLIC '' '../common/reference.RFC.6189.xml'>
+]>
+
+<rfc ipr="trust200902" category="info"
+ docName="draft-koch-openpgp-webkey-service-00">
+
+<?rfc toc="yes"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes"?>
+<?rfc subcompact="no"?>
+<?rfc compact="yes"?>
+<?rfc comments="yes"?>
+
+ <front>
+ <title>OpenPGP Web Key Service</title>
+ <author initials="W." surname="Koch"
+ fullname="Werner Koch">
+ <organization>GnuPG Project</organization>
+ <address>
+ <email>wk at gnupg.org</email>
+ <uri>https://gnupg.org</uri>
+ </address>
+ </author>
+
+ <date month="May" year="2016" />
+ <area>Security</area>
+
+ <abstract>
+ &pandocAbstract;
+ </abstract>
+ </front>
+
+ <middle>
+ &pandocMiddle;
+ </middle>
+
+ <back>
+ <references title="Normative References">
+ &rfc.2119;
+ &rfc.3156;
+ &rfc.4880;
+ &rfc.5785;
+ &rfc.6189;
+ </references>
+ &pandocBack;
+ </back>
+</rfc>
+#+end_src
+
+* 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
+method for secure communication between the key owner and the mail
+provider to publish and revoke the public key.
+
+* Middle
+
+* Introduction
+
+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
+setup such an association and to maintain it.
+
+* Notational Conventions
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+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
+difficulty of sending encrypted mails to a new communication partner is
+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
+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
+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
+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
+of a wrong key.
+
+Methods to overcome this problem are
+
+- sending an initial unencrypted message with the public key attached,
+- using the OpenPGP DANE protocol to lookup the recipients key via the
+ DNS.
+
+The first method has the obvious problems of not even trying to encrypt
+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
+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
+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.
+
+This memo specified a new method for key discovery using an encrypted
+https connection.
+
+** Key Discovery
+
+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
+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
+(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
+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
+{{{https_scheme}}} is concatenated with the mapped "domain-part", the
+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:
+
+#+BEGIN_EXAMPLE
+ https://example.org/.well-known/openpgpkey/
+ hu/iy9q119eutrkn8s1mk4r39qejnbu3n5q
+#+END_EXAMPLE
+
+(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
+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.
+
+* 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.
+
+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
+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
+ of the file is
+#+begin_example
+ https://example.org/.well-known/openpgpkey/submission-address
+#+end_example
+
+2. She sends her key using SMTP (or any other transport mechanism) to
+ the provider using the submission address and key format as specified
+ by PGP/MIME.
+
+3. The provider checks that the received key has a User ID which matches
+ 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
+ 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
+ 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.
+
+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
+ 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
+domain "example.org" is assumed, thus
+
+#+BEGIN_EXAMPLE
+ WELLKNOWN := https://example.org/.well-known/openpgpkey
+#+END_EXAMPLE
+
+The term "target key" denotes the to be published key, the term
+"submission key" the key associated with the submission-address of the
+mail provider.
+
+** The Submission Address
+
+The address of the submission file is
+
+#+BEGIN_EXAMPLE
+ WELLKNOWN/submission-address
+#+END_EXAMPLE
+
+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
+file may be
+
+#+BEGIN_EXAMPLE
+ key-submission-example.org at directory.example.org
+#+END_EXAMPLE
+
+** The Submission Mail
+
+The mail used to submit a key to the mail provider MUST comply to the
+PGP/MIME specification ({{{RFC(3156)}}}, section 7), which states that
+the Content-Type must be "application/pgp-keys", there are no required
+or optional parameters, and the body part contains the ASCII-armored
+transferable Public Key Packets as defined in {{{RFC(4880)}}}, section
+11.1.
+
+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
+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
+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
+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
+terminate a name.
+
+In a confirmation request the following names MUST be send in the
+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
+ mailbox part of the "From:" address of this
+ 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
+ encoded as required for an OpenPGP User ID.
+
+- "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
+ entirely be made up of random ASCII letters or
+ 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
+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.
+
+In other cases the confirmation request is legitimate and the MUA shall
+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
+provider is expected to cancel a pending key submission after a suitable
+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
+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
+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
+ given.
+
+- "nonce" :: The value is the value of the "nonce" parameter from the
+ confirmation request.
+
+** 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
+can be done with a file at the URL
+
+#+BEGIN_EXAMPLE
+ WELLKNOWN/policy
+#+END_EXAMPLE
+
+The file contains keywords, one per line with 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. Clients MUST use case-insensitive matching.
+
+Currently defined keywords are:
+
+- "mailbox-only" :: The mail server provider does only accept keys
+ 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
+ Key Directory Update protocol is used to update the
+ keys for the DANE service.
+
+More keywords will be defined in updates to this I-D. There is no
+registry yet 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.
+
+* Security Considerations
+
+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
+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
+web service is required for each domain name.
+
+* IANA Considerations
+
+** Well-Known URI
+
+IANA is requested to assign a well-known URI in the "Well-Known URIs"
+registry as defined by {{{RFC(5785)}}}:
+
+URI suffix: openpgpkey
+
+Change controller: IETF
+
+Specification document: This
+
+* Acknowledgments
+
+The author would like to acknowledge the help of the individuals who
+kindly voiced their opinions on the GnuPG mailing lists, in particular,
+the help of Bernhard Reiter and Guilhem Moulin.
+
+* Back
+
+* Test Vectors
+
+For help implementing this specification a non-normative example is
+given:
+
+** Sample key
+
+TODO
+
+** Software Notes
+
+GnuPG supports the key discovery described in this document since
+version 2.1.12. To use it, the new method "wkd" needs to be used with
+the =--auto-key-locate= option.
+
+* Changes since -00
+
+- Changed field names in the request and response format.
+- Removed useless checks.
+- Added a new policy flag.
+- Dropped the second occurrence of the domain name from the URL.
+
+** TODO
+
+- What about authenticated submission?
+- Describe how to handle a key with several User IDs.
diff --git a/misc/id/openpgp-webkey-service/middle.mkd b/misc/id/openpgp-webkey-service/middle.mkd
deleted file mode 100644
index 22ae453..0000000
--- a/misc/id/openpgp-webkey-service/middle.mkd
+++ /dev/null
@@ -1,345 +0,0 @@
-# Introduction
-
-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
-setup such an association and to maintain it.
-
-# Notational Conventions
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
-"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
-document are to be interpreted as described in [](#RFC2119).
-
-
-# Web Key Directory
-
-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
-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 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 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 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 of a wrong key.
-
-Methods to overcome this problem are
-
- - sending an initial unencrypted message with the public key
- attached,
- - using the OpenPGP DANE protocol to lookup the recipients key via
- the DNS.
-
-The first method has the obvious problems of not even trying to
-encrypt 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 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 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.
-
-This memo specified a new method for key discovery using an encrypted
-https connection.
-
-## Key Discovery
-
-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 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
-(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
-resulting 160 bit digest is encoded using the Z-Base-32 method as
-described in [](#RFC6189), section 5.1.6. The resulting string has a
-fixed length of 32 octets. To form the URI, the scheme "https://" is
-concatenated with the mapped "domain-part", the 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:
-
- https://example.org/.well-known/openpgpkey/
- hu/iy9q119eutrkn8s1mk4r39qejnbu3n5q
-
-(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 ([](#RFC4880)) 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.
-
-
-# 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.
-
-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
-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 of the file is
-
- https://example.org/.well-known/openpgpkey/submission-address
-
-2. She sends her key using SMTP (or any other transport mechanism) to
- the provider using the submission address and key format as
- specified by PGP/MIME.
-
-3. The provider checks that the received key has a User ID which
- matches 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 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
- 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.
-
-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 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 domain "example.org" is assumed, thus
-
- WELLKNOWN := https://example.org/.well-known/openpgpkey
-
-The term "target key" denotes the to be published key, the term
-"submission key" the key associated with the submission-address of the
-mail provider.
-
-## The Submission Address
-
-The address of the submission file is
-
- WELLKNOWN/submission-address
-
-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 file may be
-
- key-submission-example.org at directory.example.org
-
-## The Submission Mail
-
-The mail used to submit a key to the mail provider MUST comply to the
-PGP/MIME specification ([](#RFC3156), section 7), which states that the
-Content-Type must be "application/pgp-keys", there are no required or
-optional parameters, and the body part contains the ASCII-armored
-transferable Public Key Packets as defined in [](#RFC4880),
-section 11.1.
-
-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 ([](#RFC3156),
-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
-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 encryption and signing; the Combined method ([](#RFC3156),
-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
-terminate a name.
-
-In a confirmation request the following names MUST be send in the
-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 mailbox part of the "From:"
- address of this 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 encoded as required for an
- OpenPGP User ID.
-
-"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 entirely be made up
- of random ASCII letters or 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 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.
-
-In other cases the confirmation request is legitimate and the MUA
-shall 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
-provider is expected to cancel a pending key submission after a
-suitable 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 MUST be used for encryption and signing ([](#RFC3156),
-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 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 given.
-
-"nonce"
- : The value is the value of the "nonce" parameter from the
- confirmation request.
-
-
-## 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
-can be done with a file at the URL
-
- WELLKNOWN/policy
-
-The file contains keywords, one per line with 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. Clients MUST use case-insensitive matching.
-
-Currently defined keywords are:
-
-"mailbox-only"
- : The mail server provider does only accept keys 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 Key Directory Update protocol is
- used to update the keys for the DANE service.
-
-More keywords will be defined in updates to this I-D. There is no
-registry yet 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.
-
-
-# Security Considerations
-
-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 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 web service is required for each domain name.
-
-
-# IANA Considerations
-
-## Well-Known URI
-
-IANA is requested to assign a well-known URI in the "Well-Known URIs"
-registry as defined by [](#RFC5785):
-
- URI suffix: openpgpkey
-
- Change controller: IETF
-
- Specification document: This
-
-
-# Acknowledgments
-
-The author would like to acknowledge the help of the individuals who
-kindly voiced their opinions on the GnuPG mailing lists, in
-particular, the help of Bernhard Reiter and Guilhem Moulin.
diff --git a/misc/id/openpgp-webkey-service/template.xml b/misc/id/openpgp-webkey-service/template.xml
deleted file mode 100644
index 1c6d3fc..0000000
--- a/misc/id/openpgp-webkey-service/template.xml
+++ /dev/null
@@ -1,58 +0,0 @@
-<?xml version="1.0" ?>
-<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
- <!ENTITY pandocAbstract PUBLIC '' 'abstract.xml'>
- <!ENTITY pandocMiddle PUBLIC '' 'middle.xml'>
- <!ENTITY pandocBack PUBLIC '' 'back.xml'>
- <!ENTITY rfc.2119 PUBLIC '' '../common/reference.RFC.2119.xml'>
- <!ENTITY rfc.3156 PUBLIC '' '../common/reference.RFC.3156.xml'>
- <!ENTITY rfc.4880 PUBLIC '' '../common/reference.RFC.4880.xml'>
- <!ENTITY rfc.5226 PUBLIC '' '../common/reference.RFC.5226.xml'>
- <!ENTITY rfc.5785 PUBLIC '' '../common/reference.RFC.5785.xml'>
- <!ENTITY rfc.6189 PUBLIC '' '../common/reference.RFC.6189.xml'>
-]>
-
-<rfc ipr="trust200902" category="info"
- docName="draft-koch-openpgp-webkey-service-00">
-
-<?rfc toc="yes"?>
-<?rfc symrefs="yes"?>
-<?rfc sortrefs="yes"?>
-<?rfc subcompact="no"?>
-<?rfc compact="yes"?>
-<?rfc comments="yes"?>
-
-
- <front>
- <title>OpenPGP Web Key Service</title>
- <author initials="W." surname="Koch"
- fullname="Werner Koch">
- <organization>GnuPG Project</organization>
- <address>
- <email>wk at gnupg.org</email>
- <uri>https://gnupg.org</uri>
- </address>
- </author>
-
- <date month="May" year="2016" />
- <area>Security</area>
-
- <abstract>
- &pandocAbstract;
- </abstract>
- </front>
-
- <middle>
- &pandocMiddle;
- </middle>
-
- <back>
- <references title="Normative References">
- &rfc.2119;
- &rfc.3156;
- &rfc.4880;
- &rfc.5785;
- &rfc.6189;
- </references>
- &pandocBack;
- </back>
-</rfc>
commit b35cc5cb1c17ca3f5220fad48e81c157d6b54a02
Author: Werner Koch <wk at gnupg.org>
Date: Mon May 16 18:45:39 2016 +0200
drafts: openpgp-webkey-service - drop repeated domain name.
diff --git a/misc/id/openpgp-webkey-service/back.mkd b/misc/id/openpgp-webkey-service/back.mkd
index fe988e5..f081a8f 100644
--- a/misc/id/openpgp-webkey-service/back.mkd
+++ b/misc/id/openpgp-webkey-service/back.mkd
@@ -18,6 +18,7 @@ given:
- Changed field names in the request and response format.
- Removed useless checks.
- Added a new policy flag.
+ - Dropped the second occurrence of the domain name from the URL.
## TODO
diff --git a/misc/id/openpgp-webkey-service/middle.mkd b/misc/id/openpgp-webkey-service/middle.mkd
index 56aed03..22ae453 100644
--- a/misc/id/openpgp-webkey-service/middle.mkd
+++ b/misc/id/openpgp-webkey-service/middle.mkd
@@ -76,13 +76,13 @@ resulting 160 bit digest is encoded using the Z-Base-32 method as
described in [](#RFC6189), section 5.1.6. The resulting string has a
fixed length of 32 octets. To form the URI, the scheme "https://" is
concatenated with the mapped "domain-part", the fixed string
-"./well-known/openpgpkey/hu/", the "domain-part" again, and the above
-constructed 32 octet 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:
https://example.org/.well-known/openpgpkey/
- hu/example.org/iy9q119eutrkn8s1mk4r39qejnbu3n5q
+ hu/iy9q119eutrkn8s1mk4r39qejnbu3n5q
(line has been wrapped for rendering purposes)
@@ -336,3 +336,10 @@ registry as defined by [](#RFC5785):
Change controller: IETF
Specification document: This
+
+
+# Acknowledgments
+
+The author would like to acknowledge the help of the individuals who
+kindly voiced their opinions on the GnuPG mailing lists, in
+particular, the help of Bernhard Reiter and Guilhem Moulin.
-----------------------------------------------------------------------
Summary of changes:
misc/id/openpgp-webkey-service/Makefile | 25 ++
misc/id/openpgp-webkey-service/abstract.mkd | 4 -
misc/id/openpgp-webkey-service/back.mkd | 25 --
misc/id/openpgp-webkey-service/draft.org | 446 ++++++++++++++++++++++++++++
misc/id/openpgp-webkey-service/middle.mkd | 338 ---------------------
misc/id/openpgp-webkey-service/template.xml | 58 ----
6 files changed, 471 insertions(+), 425 deletions(-)
create mode 100644 misc/id/openpgp-webkey-service/Makefile
delete mode 100644 misc/id/openpgp-webkey-service/abstract.mkd
delete mode 100644 misc/id/openpgp-webkey-service/back.mkd
create mode 100644 misc/id/openpgp-webkey-service/draft.org
delete mode 100644 misc/id/openpgp-webkey-service/middle.mkd
delete mode 100644 misc/id/openpgp-webkey-service/template.xml
hooks/post-receive
--
The GnuPG website and other docs
http://git.gnupg.org
More information about the Gnupg-commits
mailing list