--- a/spec/index-respec.html Mon Dec 12 16:19:24 2011 +0100
+++ b/spec/index-respec.html Mon Dec 12 16:23:23 2011 +0100
@@ -350,13 +350,13 @@
These WebIDs can be used to build a Web of trust using vocabularies such as <a href="http://xmlns.com/foaf/0.1/">foaf</a> by allowing people to link together their profiles in a public or protected manner.
Such a web of trust can then be used by a <tref>Service</tref> to make authorization decisions, by allowing access to resource depending on the properties of an agent, such that the he is known by some relevant people, works at a given company, is a family member, is part of some group, ...</p>
<p>
-The WebId protocol specifies how a <tref>Service</tref> can authenticate a user after requesting his <tref>Certificate</tref> without needing to rely on this being signed by a well known Certificate Authority. This is done by dereferencing the <tref>WebID Profile</tref>, and checking if it describes the user as being in control of the the private key related to the <tref>Public Key</tref> published in the <tref>Certificate</tref> she used to authenticate.
+The WebID protocol specifies how a <tref>Service</tref> can authenticate a user after requesting his <tref>Certificate</tref> without needing to rely on this being signed by a well known Certificate Authority. This is done by dereferencing the <tref>WebID Profile</tref>, and checking if it describes the user as being in control of the the private key related to the <tref>Public Key</tref> published in the <tref>Certificate</tref> she used to authenticate.
</p>
<p>WebID authentication can also be used for automatic authentication by robots, such as web crawlers of linked data repositories, which could be agents working on behalf of users to help them in their daily tasks. The WebID protocol is not limited to authentication on the World Wide Web, but can work with any TLS based protocol.</p>
<section>
<h1>Outline</h1>
<p>This specification is divided in the following sections.</p>
-<p><a href="#introduction">This section</a> gives a high level overview of the WebId Protocol, and presents the organisation of the specification and the conventions used throughout the document.</p>
+<p><a href="#introduction">This section</a> gives a high level overview of the WebID Protocol, and presents the organisation of the specification and the conventions used throughout the document.</p>
<p><a href="#preconditions">Section 2</a> lists the preconditions that need to be in place for any authentication sequence to be successful: which include the creation of a <tref>WebID Profile</tref> and the creation of a <tref>WebID Certificate</tref></p>
<p><a href="#the-webid-protocol">Section 3</a> on the WebID Protocol describes in detail how a server can authenticate a user.</p>
</section>
@@ -373,7 +373,7 @@
<dt><tdef>Subject</tdef></dt>
<dd>The Subject is the Agent that is identified by the <tref>WebID</tref>.
When used legally it is the Subject who wishes to authenticate to a <tref>Service</tref>.
-We will name him <tref>Bob</tref> throughout the text when this helps lisibility.
+We will name him <tref>Bob</tref> throughout this document to improve readability.
The Subject is distinct from the <tref>Client</tref> which is used to connect to the <tref>Server</tref>.
</dd>
<dt><tdef>Client</tdef></dt>
@@ -381,13 +381,13 @@
</dd>
<dt><tdef>Key Chain</tdef> agent</dt>
-<dd>A Key Chain agent can return certificates to authorized <tref>Clients</tref> and can sign cryptographic tokens with the corresponding key. This protocol does not specify where that agent is: it could be that the <tref>Client</tref> contains his own Key Chain or it could be that the Key Chain is a seperate process on the Operating System.</dd>
+<dd>A Key Chain agent can return certificates to authorized <tref>Clients</tref> and can sign cryptographic tokens with the corresponding key. This protocol does not specify where that agent is: it could be that the <tref>Client</tref> contains his own Key Chain or it could be that the Key Chain is a separate process on the Operating System.</dd>
<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>
+<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>
+<dd>A Service is a an agent listening for requests at a given IP address on a given Server</dd>
<dt><tdef>TLS Service</tdef></dt>
<dd>A TLS Service is a transport level service listening on the <tref>Service</tref> port.
@@ -414,11 +414,11 @@
<dt><tdef>Guard</tdef><dt>
<dd>A guard is an agent, usually on the <tref>Server</tref> 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 <tref>WebId Verifier</tref> to complete identity checks.
+If it needs Authentication it can request it, and it can use the <tref>WebID Verifier</tref> to complete identity checks.
Finally it can grant or deny access.
</dd>
-<dt><tdef>Verification Agent</tdef> or <tdef>WebId Verifier</tdef></dt>
+<dt><tdef>Verification Agent</tdef> or <tdef>WebID Verifier</tdef></dt>
<dd>A WebID Verifier takes a <tref>WebID Certificate</tref> and verifies that the <tref>Subject</tref> of the Certificate is indeed identified by the <code>Subject Alternative Name</code> <tref>WebID</tref> published there.
This is usually done, because the <tref>TLS Service Light</tref> did not verify the SAN using a <tref>Certificate Authority</tref> signature.
But it can also be done to verify that the <tref>Certificate</tref> is still valid.
@@ -493,7 +493,7 @@
</tbody>
</table>
-<p>The ex: namespace is a URI that refers to Bob's profile, where Bob is an imaginary charcter well known in security circles.</p>
+<p>The ex: namespace is a URI that refers to Bob's profile, where Bob is an imaginary character well known in security circles.</p>
</section>
</section>
@@ -576,10 +576,10 @@
<p class="issue">Should we formally require the Issuer to be
O=FOAF+SSL, OU=The Community of Self Signers, CN=Not a Certification Authority.
This was discussed on the list as allowing servers to distinguish certificates
-that are foaf+Ssl enabled from others. Will probably need some very deep TLS
+that are foaf+SSL enabled from others. Will probably need some very deep TLS
thinking to get this right.</p>
<p class="issue">The above certificate is no longer valid, as I took an valid
-certificate and change the time and WebID. As a result the Signatiure is now
+certificate and change the time and WebID. As a result the signature is now
false. A completely valid certificate should be generated to avoid nit-pickers
picking nits.</p>
<section class='normative'>
@@ -588,7 +588,7 @@
Some keychains allow a user to create the Certificate directly with a friendly User Interface.
But using a keychain on the client still requires the public key to be published on the server as detailed in the next section.
It is possible to combine the creation of the key with its publication in one step in such a way as to allow the server to make the decision of what the WebID should be, by using the <a href="http://www.w3.org/TR/html5/the-button-element.html#the-keygen-element">HTML 5 keygen</a> element.
-This element can be placed in an html5 form, where on submitting the form, the browser asks the <tref>Key Chain</tref> to create a public and private key pair, and on receiving the public part of that keypair the Client can sends a keyrequest as part of the form to the <tref>Service</tref>. The <tref>Service</tref> can then create a <tref>WebID Certificate</tref> and return it to the <tref>Client</tref> to pass onto the <tref>KeyChain</tref>. In that way the Server is in the position to best make the decisions of what the <tref>Certificate</tref> should say and what the WebID should be without the private key ever leaving the secure <tref>Key Chain</tref>. The user experience for this Certificate creation is a one click operation.
+This element can be placed in an HTML5 form, where on submitting the form, the browser asks the <tref>Key Chain</tref> to create a public and private key pair, and on receiving the public part of that keypair the Client can sends a keyrequest as part of the form to the <tref>Service</tref>. The <tref>Service</tref> can then create a <tref>WebID Certificate</tref> and return it to the <tref>Client</tref> to pass onto the <tref>KeyChain</tref>. In that way the Server is in the position to best make the decisions of what the <tref>Certificate</tref> should say and what the WebID should be without the private key ever leaving the secure <tref>Key Chain</tref>. The user experience for this Certificate creation is a one click operation.
</section>
</section>
@@ -604,7 +604,7 @@
<p>
The protocol does not depend on any particular serialisation of the graph, provided that agents are able to parse that serialisation and obtain the graph automatically.
Technologies such as GRDDL [[!GRDDL-PRIMER]] for example permit any XML format to be transformed automatically to a graph of relations.
-Yet for reasons of interoperabity is has been decided that the document MUST be published at least in one of RDFa [XHTML-RDFA] or RDF/XML [RDF-SYNTAX-GRAMMAR].
+Yet for reasons of interoperability is has been decided that the document MUST be published at least in one of RDFa [XHTML-RDFA] or RDF/XML [RDF-SYNTAX-GRAMMAR].
HTTP Content Negotiation [SWBP-VOCAB-PUB] can be employed to aid in publication and discovery of multiple distinct serialisations of the same graph at the same URL. </p>
<p>
Irrespective of whether content negotiation can or not be employed, if an HTML representation of the WebID profile is published, it is suggested that the provider uses the HTML <code><link></code> element to allow discovery of the various alternate representations of the graph which may be available:
@@ -624,7 +624,7 @@
<section class='normative'>
<h1>Turtle</h1>
<p>A widely used format for writing RDF graphs by hand is the Turtle notation.
-It is easy to learn to use, is very handy for commmunicating over e-mail and on mailing lists, and can then be transformed into RDF/XML automatically.
+It is easy to learn to use, is very handy for communicating over e-mail and on mailing lists, and can then be transformed into RDF/XML automatically.
It is also very similar to the SPARQL query language.
</p>
<pre class="example" style="word-wrap: break-word; white-space: pre-wrap;">
@@ -648,7 +648,7 @@
<section>
<h1>RDFa HTML notation</h1>
<p>There are many ways of writing out the above graph using RDFa in
-html. Here is just one example of what a WebID profile could look like.</p>
+HTML. Here is just one example of what a WebID profile could look like.</p>
<pre class="example" style="word-wrap: break-word; white-space: pre-wrap;">
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN"
"http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">
@@ -748,8 +748,8 @@
<section class='normative'>
<h1>Disabling a WebID Certificate</h1>
<p>A <tref>WebID Certificate</tref> identifies the <tref>Subject</tref> alone and no one else, if and only if she is the only one to control the corresponding private key.
-It is very important therfore that the <tref>Subject</tref> take care of keeping the <tref>private key</tref> secure.
-This can be done by keeping it in the <tref>Key Chain</tref> of a personal machine in an account that is password protected and free of viruses, or best of all on some physical device where the private key is inacessible to be read by any software.
+It is very important therefore that the <tref>Subject</tref> take care of keeping the <tref>private key</tref> secure.
+This can be done by keeping it in the <tref>Key Chain</tref> of a personal machine in an account that is password protected and free of viruses, or best of all on some physical device where the private key is inaccessible to be read by any software.
In the second case having the device implies that the <tref>private key</tref> has not been lost or copied.
In the first case the user has to be more careful for signals of misuse.<p>
<p>In either situation if the <tref>Subject</tref> is suspicious that his private key has been taken, then he can disable future authentications for that certificate by removing the corresponding <tref>public key</tref> from his <tref>WebID Profile</tref>.
@@ -765,10 +765,10 @@
<h1>Authentication Sequence</h1>
<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.
+ <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 MUST be served over a <tref>TLS-Light Service</tref>, that will not do full <tref>CA</tref> authentication of <tref>Client</tref> <tref>Certificate</tref>s it receives.
-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.
+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>
@@ -781,11 +781,11 @@
<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 Issuer and trusted the statements it signed, then step 4 and 5 would not be needed - other than perhaps as a way to verify that the key was still valid.</li>
+<li>The <tref>TLS Agent</tref> MUST verify that the client is indeed in possession 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 Issuer and trusted the statements it signed, then step 4 and 5 would not be needed - other than perhaps as a way 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>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 <tref>Guard</tref> then MUST ask the <tref>Verification 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>
@@ -794,7 +794,7 @@
<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>
-<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>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>
@@ -841,13 +841,13 @@
<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 at the application layer with protocols such as OpenID, OAuth, BrowserID, etc... </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.
-This will break the connection at the application protocol layer, and so will lead to a very bad user experience. The server should therfore avoid doing this unless it can be confident that the client has a certificate - which it may be because the client advertised that in some other way to the server.
+This will break the connection at the application protocol layer, and so will lead to a very bad user experience. The server should therefore avoid doing this unless it can be confident that the client has a certificate - which it may be because the client advertised that in some other way to the server.
</p>
<p class="issue">Is there some normative spec about what NEED and WANT refer to?</p>
</section>
<section class='normative'>
-<h2>Verifiying the WebIDs</h2>
+<h2>Verifying the WebIDs</h2>
<p>The <tref>Verification Agent</tref> is given a list of WebIDs associated with a public key. It needs to verify that the agent identified by that WebID is indeed the agent that controls the private key of the given public key. It does this by looking up the definition of the WebID. A WebID is a URI, and it's meaning can be had by dereferencing it using the protocol indicated in its scheme. </p>
<p>If we first consider WebIDs with fragment identifiers, we can explain the logic of this as follows. As is explained in the RFC defining URIs [[!RFC3986]]
<blockquote>
@@ -861,17 +861,17 @@
If it says that the referent of the WebID is the agent that controls the private key of the given public key, then this is a definite description that can be considered to be a definition of the WebID: it gives its meaning.
</p>
<p>The trust that can be had in that statement is therefore the trust that one can have in one's having received the correct representation of the document that defined that WebID.
-An https WebID will therefore be a lot more trustworthy than an https WebID by a factor of the likelyhood of man in the middle attacks.</p>
-<p>Once that is proven then the trust one can have in the agent at the end of the TLS connection being the referent of the WebID is related to the trust one has in the cryptography, and the likelyhood that the private key could have been stolen.</p>
+An HTTPS WebID will therefore be a lot more trustworthy than an HTTPS WebID by a factor of the likelihood of man in the middle attacks.</p>
+<p>Once that is proven then the trust one can have in the agent at the end of the TLS connection being the referent of the WebID is related to the trust one has in the cryptography, and the likelihood that the private key could have been stolen.</p>
<p class="issue">Add explanation for URI with redirect.</p>
<section class='normative'>
<h2>Processing the WebID Profile</h2>
<p>The Verification Agent needs to fetch the document, if it does not have a valid one in cache. The <tref>Verification Agent</tref> MUST be able to process documents in RDF/XML [[!RDF-SYNTAX-GRAMMAR]] and RDFa in XHTML [[!XHTML-RDFA]]. The result of this processing should be a graph of RDF relations that is queryable, as explained in the next section.</p>
<p class="note">
-It is suggested that the <tref>Verification Agent</tref> should set the Accept-Header to request <code>application/rdf+xml</code> with a higher priority than <code>text/html</code> and <code>application/xhtml+xml</code>. The reason is that it is quite likely that many sites will produce non marked up html and leave the graph to the pure rdf formats.
+It is suggested that the <tref>Verification Agent</tref> should set the Accept-Header to request <code>application/rdf+xml</code> with a higher priority than <code>text/html</code> and <code>application/xhtml+xml</code>. The reason is that it is quite likely that many sites will produce non marked up HTML and leave the graph to the pure rdf formats.
</p>
-<p>If the <tref>Guard</tref> wishes to have the most up-to-date Profile document for an https URL, it can use the HTTP cache control headers to get the latest versions.</p>
+<p>If the <tref>Guard</tref> wishes to have the most up-to-date Profile document for an HTTPS URL, it can use the HTTP cache control headers to get the latest versions.</p>
</section>
<section class='normative'>
@@ -927,9 +927,9 @@
</section>
<section class="normative">
<h2>Verifying the WebID claim without SPARQL</h2>
-<p>If the triple store does dataype normalisation of all literals before loading them, then the most efficient way to execute this would be to start by searching for all triples whose subjects have relation <code>cert:modulus</code> to the literal which in our example was <code>"cb24ed..."^^xsd:hexBinary</code>. One would then iterate through all the subjects of the relations that satisfied that condition, which would most likely never number more than one, and from there filter out all those that were the object of the <code>cert:modulus</code> relation of the <tref>WebID</tref> - in the example <code>bob:me</code>. Finally one would verify that one of the keys that had satisfied those relations also had the <code>cert:exponent</code> relation to the number which in the example above is <code>"65537"^^xsd:integer</code>.
+<p>If the triple store does datatype normalisation of all literals before loading them, then the most efficient way to execute this would be to start by searching for all triples whose subjects have relation <code>cert:modulus</code> to the literal which in our example was <code>"cb24ed..."^^xsd:hexBinary</code>. One would then iterate through all the subjects of the relations that satisfied that condition, which would most likely never number more than one, and from there filter out all those that were the object of the <code>cert:modulus</code> relation of the <tref>WebID</tref> - in the example <code>bob:me</code>. Finally one would verify that one of the keys that had satisfied those relations also had the <code>cert:exponent</code> relation to the number which in the example above is <code>"65537"^^xsd:integer</code>.
</p>
-<p>For triples stores that do not normalise literals on loading a graph, the normalizatino will need to be done after the query results and before matching those with the values from the <tref>Certificate</tref>. Because one could not rely on the modulus having been normalized, one would have to start with the <tref>WebID</tref> - <code>bob:me</code> and find all it's <code>cert:key</code> relations to objects - which we know to be keys - and then iterate through each of those keys' modulus and exponent, and verify if the normalised version of the value of those relation is equal to the numbers found in the certificate. If one such key is found then the answer is <code>true</code>, otherwise the answer will be <code>false</code>.</p>
+<p>For triples stores that do not normalise literals on loading a graph, the normalization will need to be done after the query results and before matching those with the values from the <tref>Certificate</tref>. Because one could not rely on the modulus having been normalized, one would have to start with the <tref>WebID</tref> - <code>bob:me</code> and find all it's <code>cert:key</code> relations to objects - which we know to be keys - and then iterate through each of those keys' modulus and exponent, and verify if the normalised version of the value of those relation is equal to the numbers found in the certificate. If one such key is found then the answer is <code>true</code>, otherwise the answer will be <code>false</code>.</p>
</section>
</section>
<section class='normative'>
@@ -939,7 +939,7 @@
<p>Once the <tref>Guard</tref> has a WebID he can do a lookup in a database to see if the agent is allowed the required access to the given resource.
Up to this point we are not much more advanced that with a user name and password, except that the user did not have to create an account on Alice's server to identify himself and that the server has some claimed attributes to personalise the site for the requestor.
But the interesting thing about such a WebID is that because it is a global linkable URI, one can build webs of trust that can be crawled the same way the web can be crawled: by following links from one document to another.
-It is therfore possible to have very flexible access control rules where parts of the space of the user's machine is given access to friend and those friends friends (FOAF), stated by them at their domains.
+It is therefore possible to have very flexible access control rules where parts of the space of the user's machine is given access to friend and those friends friends (FOAF), stated by them at their domains.
It is even be possible to allow remote agents to define their own access control rules for parts of the machine's namespace.
There are too many possibilities to list them all here.
</p>