Updates to WebFinger wiki (issue184066)

[jpa...@google.com]

Review of Joe's suggested Wiki updates; LGTM.

http://codereview.appspot.com/184066/diff/1/2
File Requirements.wiki (right):

http://codereview.appspot.com/184066/diff/1/2#newcode5
Requirements.wiki:5: follow requirements, which will give some insight
typo: following

http://codereview.appspot.com/184066/diff/1/2#newcode11
Requirements.wiki:11: able to use WebFinger. That implies that is must
typo: it? (implies that at most a user must be able to create a
directory and place a file in it to be served?)

http://codereview.appspot.com/184066/diff/1/2#newcode14
Requirements.wiki:14: is required, picking a technology that allows
packaging
A bit unclear -- perhaps "needed in some situations"?

http://codereview.appspot.com/184066/diff/1/2#newcode24
Requirements.wiki:24: defacement attack could lead users to enter their
typo: attack,

http://codereview.appspot.com/184066

[joe.gr...@gmail.com]

Reviewers: jpanzer, jcgregorio,

Message:
Brad gave me commit access, so I've committed it with all
of these changes.

Please review this at http://codereview.appspot.com/184066

Affected files:
A Requirements.wiki
M WebFingerProtocol.wiki

Index: Requirements.wiki
===================================================================
--- Requirements.wiki (revision 0)
+++ Requirements.wiki (revision 0)
@@ -0,0 +1,35 @@
+#summary Requirements for WebFinger
+
+The WebFinger protocol allows looking up meta-data about
+a resource. The final protocol has been guided by the
+follow requirements, which will give some insight
+into the design decisions made during development.
+
+
+== Ease of Install ==
+A user with a standard web hosting provider must be
+able to use WebFinger. That implies that is must
+be just one or two files that get placed in a directory.
+Since optional signing of the WebFinger files
+is required, picking a technology that allows packaging
+of signatures and data files together is important,
+and thus the choice of XML as a format for XRD, and the
+use of XML Signatures.
+
+== Security ==
+There must be an ability to sign XRD files. Some
+of the resources pointed to via an XRD file, such
+as the users OpenID provider, are sensitive and
+if corrupted via a Man-in-the-middle attack, or a
+defacement attack could lead users to enter their
+usernames and passwords into an untrusted site.
+While SSL could solve this problem, it doesn't do
+so without conflicting with the 'Ease of Install'
+requirement. While signing XRD files for
+servers and checking signatures for clients is optional
+in the base specifications, there may be follow-on
+specifications, or profiles of XRD that require
+signatures.
+
+
+
Index: WebFingerProtocol.wiki
===================================================================
--- WebFingerProtocol.wiki (revision 16)
+++ WebFingerProtocol.wiki (working copy)
@@ -10,6 +10,8 @@
The goal of the protocol is to get an [XrdFiles XRD] XML file describing
how to find a user's public metadata from that user's
email address or email address like identifier. The following describes
the steps in the Webfinger protocol specifically,
and ignores the options in the underlying protocols that don't apply
(mostly the Link: header).
+The [Requirements] page gives some background on the requirements that
went into
+the design of the WebFinger protocol.

==Normalize and parse the email address==

@@ -19,8 +21,8 @@
==Get the domain's host-meta XRD file==

First, you need to get the host's host-meta XRD file. In this case,
example.com's. This is available at
-https://example.com/.well-known/host-meta. If there's no response to an
SSL connection there,
-try http://example.com/.well-known/host-meta. Follow 3xx redirects;
remember if anything _wasn't_ retrieved via SSL
+`https://example.com/.well-known/host-meta`. If there's no response to an
SSL connection there,
+try `http://example.com/.well-known/host-meta`. Follow 3xx redirects;
remember if anything _wasn't_ retrieved via SSL
connections with valid certificates.

Note that this needs to be done only the first time for each host-meta,
after that you can cache the results using standard