drafts,openpgp-webkey-service: Correctly mark sentences.
authorWerner Koch <wk@gnupg.org>
Fri, 30 Sep 2016 09:36:57 +0000 (11:36 +0200)
committerWerner Koch <wk@gnupg.org>
Fri, 30 Sep 2016 09:36:57 +0000 (11:36 +0200)
misc/id/openpgp-webkey-service/draft.org

index 29b234e..e259279 100644 (file)
@@ -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@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@Example.ORG is:
@@ -163,32 +163,32 @@ For example the URI to lookup the key for Joe.Doe@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@example.org. To install the key at her provider's Web Key
+alice@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