--- a/spec/img/WebIdGraph.graffle Fri Nov 18 20:05:15 2011 +0100
+++ b/spec/img/WebIdGraph.graffle Sun Nov 20 22:09:01 2011 +0100
@@ -7,7 +7,7 @@
<key>ApplicationVersion</key>
<array>
<string>com.omnigroup.OmniGrafflePro</string>
- <string>138.30.0.155892</string>
+ <string>138.33.0.157554</string>
</array>
<key>AutoAdjust</key>
<true/>
@@ -46,7 +46,7 @@
<key>DisplayScale</key>
<string>1.000 cm = 1.000 cm</string>
<key>GraphDocumentVersion</key>
- <integer>6</integer>
+ <integer>8</integer>
<key>GraphicsList</key>
<array>
<dict>
@@ -236,7 +236,7 @@
</dict>
<dict>
<key>Bounds</key>
- <string>{{81.919296, 530.02002}, {49.999599, 18}}</string>
+ <string>{{81.919296, 530.02002}, {49.999588, 18}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>ID</key>
@@ -262,7 +262,7 @@
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
-\f0\fs24 \cf0 cert:int}</string>
+\f0\fs24 \cf0 xsd:int}</string>
</dict>
</dict>
<dict>
@@ -983,7 +983,7 @@
</dict>
<dict>
<key>Bounds</key>
- <string>{{16.9592, 231}, {178.041, 18}}</string>
+ <string>{{16.959198, 231}, {194.89795, 18}}</string>
<key>Class</key>
<string>ShapedGraphic</string>
<key>ID</key>
@@ -1016,7 +1016,7 @@
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc
-\f0\b\fs24 \cf0 http://joe.example/profile#me}</string>
+\f0\b\fs24 \cf0 http://bob.example/profile#me}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
@@ -1210,7 +1210,7 @@
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720
-\f0\fs24 \cf0 http://joe.example/profile}</string>
+\f0\fs24 \cf0 http://bob.example/profile}</string>
<key>VerticalPad</key>
<integer>0</integer>
</dict>
@@ -1265,7 +1265,7 @@
<key>MasterSheets</key>
<array/>
<key>ModificationDate</key>
- <string>2011-10-17 16:42:43 +0000</string>
+ <string>2011-11-20 16:55:19 +0000</string>
<key>Modifier</key>
<string>Henry Story</string>
<key>NotesVisible</key>
@@ -1293,11 +1293,6 @@
<string>float</string>
<string>18</string>
</array>
- <key>NSPaperName</key>
- <array>
- <string>string</string>
- <string>A4</string>
- </array>
<key>NSPaperSize</key>
<array>
<string>coded</string>
--- a/spec/index-respec.html Fri Nov 18 20:05:15 2011 +0100
+++ b/spec/index-respec.html Sun Nov 20 22:09:01 2011 +0100
@@ -411,49 +411,55 @@
<section>
<h1>Terminology</h1>
-
<dl>
+<dt><tdef>Alice</tdef></dt>
+<dd>Alice is an agent who owns a Server which runs a Service which Bob wishes to Access</dd>
-<dt><tdef>Verification Agent</tdef></dt>
-<dd>Performs authentication on provided WebID credentials and determines if
-an <tref>Identification Agent</tref> can have access to a particular
-resource. A <tref>Verification Agent</tref> is typically a Web server, but
-may also be a peer on a peer-to-peer network.</dd>
+<dt><tdef>Bob</tdef></dt>
+<dd>Bob is any agent who uses a Client to connect to Alice's Service, and who controls the private key the client uses to access the resource</dd>
-<dt><tdef>Identification Agent</tdef></dt>
-<dd>Provides identification credentials to a <tref>Verification Agent</tref>.
-The <tref>Identification Agent</tref> is typically also a User Agent.</dd>
+<dt><tdef>Client</tdef></dt>
+<dd>The Client initiates a request to a Service listening on a specific port using a given protocol on a given Server.</dd>
-<dt><tdef>Identification Certificate</tdef></dt>
+<dt><tdef>Server</tdef></dt>
+<dd>A Server is a machine contactable at a domain name or ip address that hosts a number of globally accessible Services.</dd>
+
+<dt><tdef>Service</tdef></dt>
+<dd>A Service is a an agent listening for requests at a given ip address on a given Server</dd>
+
+<dt><tdef>Guard</tdef><dt>
+<dd>A guard is an agent that can look at a request from the <tref>Client</tref> and decide if it needs Authentication by looking at the Access control Rules. If it needs Authentication it can request it, and it can use the <tdef>WebId Verifier</tdef> to complete identity checks. Finally it can grant or deny access.</dd>
+
+<dt><tdef>Verification Agent</tdef> or <tdef>WebId Verifier</tdef></dt>
+<dd>Performs authentication on provided WebID credentials, ie it verifies that the WebID is indeed identified by a given public key.</dd>
+
+<dt><tdef>WebID Certificate</tdef></dt>
<dd>An X.509 [[!X509V3]] Certificate that MUST contain a
<code>Subject Alternative Name</code> extension with at least one URI entry
-identifying the <tref>Identification Agent</tref>. This URI SHOULD be
+identifying the <tref>Client</tref>. This URI MUST be
dereference-able and result in a document containing RDF data.
For example, a certificate identifying the WebID URI
-<code>http://example.org/webid#public</code> would contain the following:
+<code>http://example.org/bob#me</code> would contain the following:
<pre>
X509v3 extensions:
...
X509v3 Subject Alternative Name:
- URI:http://example.org/webid#public
+ URI:http://example.org/bob#me
</pre>
-<p class="issue">TODO: cover the case where there are more than one URI entry</p>
</dd>
-<dt><tdef>WebID URI</tdef></dt>
-<dd>A URI specified via the <code>Subject Alternative Name</code> extension
-of the <tref>Identification Certificate</tref> that identifies an
-<tref>Identification Agent</tref>.</dd>
+<dt><tdef>WebID</tdef></dt>
+<dd>A URI that refers to an Agent - Person, Robot, Group or other thing that can have Intentions. The WebID should be a URI which when dereferenced returns a representation whose description uniquely identifies the Agent as the controller of a public key. In our example the WebID refers to Bob. A WebID is usually a URL with a #tag, as the meaning of such a URL is defined in the document.</dd>
+</dd>
<dt><tdef>public key</tdef></dt>
-<dd>A widely distributed cryptographic key that can be used to verify
-digital signatures and encrypt data between a sender and a receiver. A public
-key is always included in an <tref>Identification Certificate</tref>.</dd>
+<dd>A cryptographic key that can be published and can be used to verify the possession of a private key. A public
+key is always included in a <tref>WebID Certificate</tref>.</dd>
<dt><tdef>WebID Profile</tdef></dt>
<dd>
-A structured document that contains identification credentials for the
-<tref>Identification Agent</tref> expressed using the Resource Description
+A structured document containing credentials for
+<tref>Bob</tref> expressed using the Resource Description
Framework [[RDF-CONCEPTS]]. Either the XHTML+RDFa 1.1 [[!XHTML-RDFA]]
serialization format or the RDF/XML [[!RDF-SYNTAX-GRAMMAR]] serialization
format MUST be supported by the mechanism, e.g. a Web Service, providing the
@@ -478,8 +484,8 @@
<code>Subject Alternative Name</code> URI entry. This URI must be one that
dereferences to a document the user controls so that he can publish the
public key of the <tref>Identification Certificate</tref> at this URI.</p>
-<p>For example, if a user Joe controls <code>http://joe.example/profile</code>,
-then his WebID can be <code>http://joe.example/profile#me</code></p>
+<p>For example, if a user Joe controls <code>http://bob.example/profile</code>,
+then his WebID can be <code>http://bob.example/profile#me</code></p>
<p class="issue">explain why the WebID URI is different from the URI of the
WebID profile document.</p>
@@ -498,7 +504,7 @@
Validity
Not Before: Jun 8 14:16:14 2010 GMT
Not After : Jun 8 16:16:14 2010 GMT
- <span style="color: red">Subject:</span> O=FOAF+SSL, OU=The Community Of Self Signers/UID=https://example.org/profile#me, CN=Joe (Personal)
+ <span style="color: red">Subject:</span> O=FOAF+SSL, OU=The Community Of Self Signers, UID=https://example.org/profile#me, CN=Joe (Personal)
Subject Public Key Info:
<span style="color: red"> Public Key Algorithm:</span> rsaEncryption
<span style="color: red">Public-Key:</span> (2048 bit)
@@ -526,13 +532,13 @@
X509v3 Basic Constraints: critical
CA:FALSE
X509v3 Key Usage: critical
- Digital Signature, Non Repudiation, Key Encipherment, Key Agreement, Certificate Sign
+ Digital Signature, Non Repudiation, Key Encipherment, Key Agreement
Netscape Cert Type:
SSL Client, S/MIME
X509v3 Subject Key Identifier:
08:8E:A5:5B:AE:5D:C3:8B:00:B7:30:62:65:2A:5A:F5:D2:E9:00:FA
<span style="color: red">X509v3 Subject Alternative Name:</span> critical
- <span style="color: red">URI:</span>https://joe.example/profile#me
+ <span style="color: red">URI:</span>https://bob.example/profile#me
Signature Algorithm: sha1WithRSAEncryption
cf:8c:f8:7b:b2:af:63:f0:0e:dc:64:22:e5:8a:ba:03:1e:f1:
ee:6f:2c:f5:f5:10:ad:4c:54:fc:49:2b:e1:0d:cd:be:3d:7c:
@@ -569,14 +575,9 @@
<img alt="Web ID graph" src="img/WebIdGraph.jpg"/>
<p>The document can publish many more relations than are of interest to the
WebID protocol, as shown in the above graph by the grayed out relations.</p>
-<p>The encoding of this graph is immaterial to the protocol, so long as a well
-known mapping to the format of the representation to such a graph can be found.
-Below we discuss the most well known formats, and a method for dealing with new
-unknown formats as they come along.</p>
-<p>The WebID provider must publish the graph of relations in one of the well
-known formats, though he may publish it in a number of formats to increase the
-usability of his site using content negotiations.</p>
-<p class="issue">Add content negotiation pointers</p>
+<p>The encoding of this graph is theortically immaterial to the protocol, so long as a well
+known mapping from the format of the representation to such a graph can be found automatically.
+In order to improve interoperability at this time it is suggested that WebID provider publish the graph of relations at least in one of RDFa [[!XHTML-RDFA]] or RDF/XML [[!RDF-SYNTAX-GRAMMAR]], though he may publish it in a number of formats to increase the usability of his site to different agents using content negotiations [[!SWBP-VOCAB-PUB]].</p>
<p>It is particularly useful to have one of the representations be in HTML or
XHTML even if it is not marked up in RDFa as this allows people using a
web browser to understand what the information at that URI represents.</p>
@@ -588,7 +589,7 @@
@prefix cert: <http://www.w3.org/ns/auth/cert#> .
@prefix rsa: <http://www.w3.org/ns/auth/rsa#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
- @prefix : <https://joe.example/profile#> .
+ @prefix : <https://bob.example/profile#> .
:me a foaf:Person;
foaf:name "Joe";
@@ -704,7 +705,7 @@
xmlns:rsa="http://www.w3.org/ns/auth/rsa#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
xmlns:foaf="http://xmlns.com/foaf/0.1/">
- <foaf:Person rdf:about="https://joe.example/profile#me">
+ <foaf:Person rdf:about="https://bob.example/profile#me">
<foaf:name>Joe</foaf:name>
<cert:key>
<rsa:RSAPublicKey>
@@ -751,84 +752,35 @@
<section class='normative'>
<h1>Authentication Sequence</h1>
-<img src="img/WebIDSequence-friendly.jpg">
-<p>The following steps are executed by <tref>Verification Agent</tref>s and
-<tref>Identification Agent</tref>s to determine the global identity of the
-requesting agent. Once this is known, the identity can be used to determine
-if access should be granted to the requested resource.
+<p>In order to give the full context of a <tref>Client</tref> interaction with a <tref>Server</tref> we will illustrate the protocol with the following sequence diagram. <tref>Bob</tref> initiates a connection to <tref>Alice</tref>'s server via a TLS enabled protocol such as https in order to access a Protected Resource or a Protected Service. The Protected Resource may be a document served over https, but it could also be a SOAP service, or some other resource. This resource is protected by a Guard, which uses a <tref>WebID Verifier</tref> to verify the non Certified WebIds found in the certificate. Once the verification succeeds the Guard checks to see if the Agent identified by the <tref>WebID</tref> is allowed access to the resource, by using trusted information from the Web and access control rules.
</p>
+<img width="90%" src="img/WebIDSequence-friendly.jpg">
+<p>The steps in detail are as follows:</p>
<ol>
-<li>The <tref>Identification Agent</tref> (Bob's Browser) requests an action (GET, PUT, POST, DELETE, ... ) on a resource managed by the <tref>Verification Agent</tref> (Alice's Web Server) using HTTP over a TLS connection [[!HTTP-TLS]] . </li>
-
-<li>The <tref>Verification Agent</tref> decides if it needs to authenticate the user, by potentially taking into consideration the Method of the request, the resource and the capabilities of the browser as well as acces control permissions for that resource. Some servers may require all requests to be identified, others may only require some resources to be accessed by identified agents. If the server requires the <tref>Identification Agent</tref> to be identified, then it can ask for the agent's cleint certificate using the null DN [to be discussed: do we have a DN for WebID enabled TLS ] in a TLS client-certificate Request message. </li>
-</li>
-
-<li>The Client can select a certificate and send it to the server as specified in the TLS spec [exact location]</li>
-
-<li>The <tref>Verification Agent</tref> MUST extract the <tref>public key</tref>
-and all the URI entries contained in the <code>Subject Alternative Name</code>
-extension of the <tref>Identification Certificate</tref>.
-An <tref>Identification Certificate</tref> MAY contain multiple URI entries
-which are considered claimed <tref>WebID URI</tref>s.</li>
-
-<li>The <tref>Verification Agent</tref> MUST attempt to verify the
-<tref>public key</tref> information associated with at least one of the claimed
-<tref>WebID URI</tref>s. The <tref>Verification Agent</tref> MAY attempt to
-verify more than one claimed <tref>WebID URI</tref>.
-This verification process SHOULD occur either by dereferencing the
-<tref>WebID URI</tref> and
-extracting RDF data from the resulting document, or by utilizing a cached
-version of the RDF data contained in the document or other data source that is
-up-to-date and trusted by the <tref>Verification Agent</tref>. The processing
-and extraction mechanism is further detailed in the sections titled
-<a href="#processing-the-webid-profile">Processing the WebID Profile</a> and
-<a href="#extracting-webid-URI-details">Extracting WebID URI Details</a>.
+<li><tref>Bob</tref>'s <tref>Client</tref> MUST open a TLS [[!RFC5246]] connection with the server which authenticates itself using well known TLS mechanisms. This MAY be done as the first part of an HTTPS connection [[!HTTP-TLS]]. Once the TLS session is established, which means that the <tref>Server</tref> was authenticated by the client, then it is possible for the application layer protocol to get started. </li>
+<li>If the protocol is HTTP then the client can request an HTTP GET, PUT, POST or DELETE action on a resource for example. The <tref>Guard</tref> can then intercept that request and by checking some access control rules determine if the client needs authentication. We will consider the case here where the client does need to be authenticated.</li>
+<li>The Guard MUST requests the client to authenticate itself using public key cryptography by signing a token with its private key and have the Client send its Certificate. This has been carefully defined in the TLS protocol and can be summarised by the following steps:
+<ol>
+<li>The guard requests of the TLS agent that it make a Certificate Request to the client. The TLS layer does this. Because the WebID protocol does not rely on Certificate Authorities to verify the contents of the <tref>Certificate</tref>, the TLS Agent can ask for any Certificate from the Client. More details in <a href="requesting-the-client-certificate">Requesting the Client Certificate</a></li>
+<li>The Client asks Bob to choose a certificate if the choice has not been automated. We will assume that Bob does choose a <tref>WebID Certificate</tref> and sends it to the client.</li>
+<li>The <tref>TLS Agent</tref> MUST verify that the client is indeed in posession of the private key. What is important here is that the TLS Agent need not know the Issuer of the Certificate, or need not have any trust relation with the Issuer. Indeed if the TLS Layer could verify the signature of the Isser and trusted the statements it signed, then step 4 and 5 would not be needed - other than perhaps as a double check to verify that the key was still valid.</li>
+<li>The <tref>WebID Certificate</tref> is then passed on to the <tref>Guard</tref> with the proviso that the WebIDs still needs to be verified.</li>
+</ol>
</li>
-
-<li>If the <tref>public key</tref> in the
-<tref>Identification Certificate</tref> is found in the list of
-<tref>public key</tref>s associated with the claimed <tref>WebID URI</tref>, the
-<tref>Verification Agent</tref> MUST assume that the client intends to use
-this <tref>public key</tref> to verify their ownership of the
-<tref>WebID URI</tref>.
-On the other hand, if no matching <tref>public key</tref> is found in the list
-of <tref>public key</tref>s associated with the claimed <tref>WebID URI</tref>,
-the <tref>Verification Agent</tref> MUST attempt to verify another claimed
-<tref>WebID URI</tref>. The authentication MUST fail if no matching
-<tref>public key</tref> is found among all the claimed
-<tref>WebID URI</tref>s.</li>
-
-<li>The <tref>Verification Agent</tref> verifies that the
-<tref>Identification Agent</tref> owns the private key corresponding to the
-public key sent in the <tref>Identification Certificate</tref>.
-This SHOULD be fulfilled by performing TLS mutual-authentication
-between the <tref>Verification Agent</tref> and the
-<tref>Identification Agent</tref>.
-If the <tref>Verification Agent</tref> does not have access to the TLS layer,
-a digital signature challenge MUST be provided by the
-<tref>Verification Agent</tref>. These processes are detailed in the sections
-titled <a href="#authorization">Authorization</a> and
-<a href="#secure-communication">Secure Communication</a>.</li>
-
-<li>If the <tref>public key</tref> in the
-<tref>Identification Certificate</tref> matches one in the set given by the
-profile document graph given above then the <tref>Verification Agent</tref>
-knows that the <tref>Identification Agent</tref> is indeed identified by the
-<tref>WebID URI</tref>. The verification is done by querying the
-Personal Profile graph as specified in
-<a href="#extracting-webid-uri-details">querying the RDF graph</a>.</li>
+<li>The <tref>Guard</tref> then MUST ask the <tref>Verfication Agent</tref> to verify that the WebIDs do identify the agent who knows the given public key.</li>
+<li>The WebID is verified by looking up the definition of the URL at its canonical location. This can be done by dereferencing it. The <tref>Verification Agent</tref> MUST extract the <tref>public key</tref> and all the URI entries contained in the <code>Subject Alternative Name</code> extension of the <tref>WebID Certificate</tref>. A <tref>WebID Certificate</tref> MAY contain multiple URI entries
+which are considered claimed <tref>WebID</tref>s at this point, since they have not been verified. The <tref>Verification Agent</tref> may verify as many or as few WebIDs it has time for. It may do it in parallel and asynchronously. However that is done, a claimed WebIDs can only be considered verified if the following steps have been accomplished successfully:</li>
+<ol>
+<li>If the <tref>WebID Verifier</tref> does not have an up to date version of the WebID profile in the cache, then it MUST dereference the WebID using the canonical method for dereferencing a URL of that scheme. For an https://... WebID this would be done using the [[!HTTP-TLS]] protocol. </li>
+<li>The returned representation is then transformed into an RDF graph as specified in <a href="#processing-the-webid-profile">Processing the WebID Profile</a> </li>
+<li>That graph is then queried as explained in <a href="#querying-the-graph">Querying the Graph</a>. If the query succeeds, then that WebID is verified.
+</li>
</ol>
-
-<p>
-The <tref>Identification Agent</tref> MAY re-establish a different identity at
-any time by executing all of the steps in the Authentication Sequence again.
-Additional algorithms, detailed in the next section, MAY be performed to
-determine if the <tref>Verification Agent</tref> can access a particular
-resource after the last step of the Authentication Sequence has been
-completed.
-</p>
-
+<li>With the set of verified WebIds the Guard can then check its access control rules using information from the web and other information available to it, to verify if the referent of the WebID is indeed allowed access to the protected resource. The exact nature of those Access Control Rules is left for another specification. Suffice it to say that it can be something as simple as a lookup in a table.</li>
+<li>If access is granted, then the guard can pass on the request to the protected resource, which can then interact unimpeded with the client.</li>
+</ol>
+<ol>
</section>
<section class='normative'>
@@ -840,18 +792,30 @@
<section class='normative'>
<h2>Initiating a TLS Connection</h2>
-<p class="issue">This section will detail how the TLS connection process is
-started and used by WebID to create a secure channel between the
-Identification Agent and the Verification Agent.</p>
+<p>Standard SSLv3 and TLSv1 and upwards can be used to establish the connection between
+the Client and the TLS Agent listening on the Service's port.</p>
</section>
<section class='normative'>
-<h2>Exchanging the Identification Certificate</h2>
+<h2>Connecting at the Application Layer</h2>
-<p class="issue">This section will detail how the certificate is selected and
-sent to the Verification Agent.</p>
+<p>Once the TLS connection has started the application layer protocol can get going. It is always possible during communication at the application layer for communication parameters to be set at the TLS layer, such as requesting a client certificate as described in the following section. This permits some very flexible authentiation interaction, as the Guard can find out exactly what the abilities of the client are in order to work out what type of TLS client authentication it can ask for.</p>
+<p>If the protocol permits it, the Client can let the Application layer, and especially the <tref>Guard</tref> know that the client can authenticate with a WebID Certificate, and even if it wishes to do so. This may be useful both to allow the Server to know that it can request the client certificate, and also in order to allow Robots that may find it a lot more convenient to be authenticated automatically.
+</p>
</section>
+
+<section class='normative'>
+<h2>Requesting the Client Certificate</h2>
+
+<p>TLS allows the server to request a Certificate from the Client using the <code>CertificateRequest</code> message [section 7.4.4] of TLS v1.1 [[RFC5246]]. Since WebID TLS authentication does not rely on CA's signing the certificate to verify the WebID Claims made therein, the Server does not need to restrict the certificate it receives by the CA's they were signed by. It can therefore leave the <code>certificate_authorities</code> field blank in the request. Most programming languages permit this option to be set. </p>
+</section>
+<p class="note">From our experience leaving the certificate_authorities field empty leads to the correct behavior on all browsers and all TLS versions.</p>
+<p>If the Client does not send a certificate, because either it does not have one or it does not wish to send one, other authentication procedures can be pursued from OpenID, OAuth, BrowserID, etc... as these occur at the Application Layer, which has not yet been accessed.</p>
+<p>As far as possible it is important for the server to request the client certificate in <code>WANT</code> mode, not in <code>NEED</code> mode. If the request is made in <code>NEED</code> mode then connections will be broken off if the client does not send a certificate. Unless the server can be confident that the client has a certificate - which it may be because it advertised that in some other way to the server - then it should try to avoid making the request in <code>NEED</code> mode. In most browsers this leads to a very bad user experience. Luckily only few browsers require <code>Need</code> mode for the client to send a certificate.
+</p>
+<p class="issue">Is there some normative spec about what NEED and WANT refer to?</p>
+
<section class='normative'>
<h2>Processing the WebID Profile</h2>