Binary file spec/img/WebIDSequence-friendly.graffle has changed

Binary file spec/img/WebIDSequence-friendly.jpg has changed

--- a/spec/index-respec.html	Wed Nov 30 10:37:25 2011 +0100
+++ b/spec/index-respec.html	Wed Nov 30 14:49:30 2011 +0100
@@ -354,10 +354,8 @@
 <h1>Motivation</h1>
 
 <p>
-It is a fundamental design criteria of the Web to enable individuals and
-organizations to control how they interact with the rest of society. This
-includes how one expresses their identity, public information and personal
-details to social networks, Web sites and services.
+It is a fundamental to the architecture of the Web that anyone - be they an individual and organisation, be  able to participate in publishing resources and enableing services available to all.
+ This includes how one expresses their identity, public information and personal details to social networks, Web sites and services.
 </p>
 
 <p>
@@ -411,14 +409,18 @@
 <dd>Alice is an agent who owns a Server which runs a Service which Bob wishes to Access</dd>
 
 <dt><tdef>Bob</tdef></dt>
-<dd>Bob is an agent who uses a <tref>Client</tref> to connect to <tref>Alice</tref>'s Service, and who controls the private key the client uses to access the resource.</dd>
-
+<dd>Bob is an agent who uses a <tref>Client</tref> to connect to <tref>Alice</tref>'s Service, and who is responsible for the private key the <tref>Client</tref> uses to authenticate to <tref>Service</tref>s.
+If he notices the private key was compromised he needs to take action to disable the public key.
+</dd>
 <dt><tdef>Subject</tdef></dt>
-<dd>The Subject is the Agent that is identified by the <tref>WebID</tref>. When used correctly it is the Subject who wishes to authenticate to a <tref>Service</tref>.
-When speaking of a particular agent, and in order to improve lisibility in this spec, we will name him <tref>Bob</tref>. The Subject is distinct from the <tref>Client</tref> which is used to connect to the <tref>Server</tref>.</dd>
-
+<dd>The Subject is the Agent that is identified by the <tref>WebID</tref>.
+When used correctly it is the Subject who wishes to authenticate to a <tref>Service</tref>.
+When speaking of a particular agent, and in order to improve lisibility in this spec, we will name him <tref>Bob</tref>.
+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>
-<dd>The Client initiates a request to a Service listening on a specific port using a given protocol on a given Server.</dd>
+<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>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>
@@ -426,6 +428,29 @@
 <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>TLS Service</tdef></dt>
+<dd>A TLS Service is a transport level service listening on the <tref>Service</tref> port. 
+It secures the transport layer before passing messages to the Application layer <tref>Service</tref> itself.
+The TLS protocol [[!RFC5246]] is applied to incoming connections: it identifies the server to the client, securing the channel and is able to request authentication credentials from the <tref>Client</tref> if needed. 
+Server Credentials and Client credentials traditionally take the form of X509 Certificates containing a public key. 
+The TLS protocol enables the TLS Service to verify that the <tref>Client</tref> controls the private key of the <tref>Public Key</tref> published in the certificate.
+Trust decisions on other attributes of the <tref>Subject</tref> published in the Certificate - such as his name - are traditionally based on the trust in the Agent that signed the Certificate - known as a <tref>Certificate Authority</tref>.
+</dd>
+<dt><tdef>Certificate</tdef><dt>
+<dd>A Certificate is a document that affirms statements about a <tref>Subject</tref> such as its <tref>public key</tref> and its name, and that is signed by a <tref>Certificate Authority</tref> using the private key that corresponds to the public key published in its certificate. The Certificate Authority's own Certificate is self signed. Certificates used by TLS are traditionally X509 [[!X509V3]] Certificates. </dd>
+<dt><tdef>Certificate Authority</tdef> (<tdef>CA</tdef>)</dt>
+<dd>
+A Certificate Authority is a Subject that signs <tref>Certificates</tref>. 
+It is an Authority for what is written in the Certificate for any Agent that trusts it to be truthful in what it signs.
+Such agents use the knowledge of the CA's public key to verify the statements made by that CA in any of the Certificates it signed.
+<tref>Service</tref>s usually identify themselves with Certificates signed by well known and widely deployed CAs available in all agents. 
+</dd>
+<dt><tdef>TLS-Light Service</tdef></dt>
+<dd>A TLS-Light Service is a standard TLS Service, except that it does not do CA Based Client Certificate Authentication.
+If on requesting a Certificate from a Client it receives one, it simply verifies that the <tref>Client</tref> knows the private key of the public key published in the Certificate it received.
+Verification of attributes in the certificate is left to other services such as the <tref>WebID Verifier</tref>.
+</dd>
+
 <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. 
@@ -433,10 +458,13 @@
 </dd>
 
 <dt><tdef>Verification Agent</tdef> or <tdef>WebId Verifier</tdef></dt>
-<dd>Performs authentication on provided WebID credentials.</dd>
+<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.
+</dd>
 
 <dt><tdef>WebID Certificate</tdef></dt>
-<dd>An X.509 [[!X509V3]] Certificate that will identify an Agent using a WebID.
+<dd>An X.509 [[!X509V3]] <tref>Certificate</tref> that will identify an Agent using a <tref>WebID</tref>.
 The Certificate need not be signed by a well known Certificate Authority.
 Indeed it can be signed by the server which hosts the certificate, or it can even be self signed. 
 The Certificate MUST contain a <code>Subject Alternative Name</code> extension with at least one URI entry identifying the <tref>Subject</tref>. 
@@ -752,7 +780,12 @@
 <section class='normative'>
 <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. 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>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 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.
+ 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">
@@ -762,7 +795,7 @@
 <li>Once the Transport Layer Security [TLS] has been set up, the application protocol exchange can start. If the protocol is HTTP then the client can request an HTTP GET, PUT, POST, DELETE, ... action on a resource as detailed by [[!HTTP11]]. 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 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>WebID Certificate</tref> is then passed on to the <tref>Guard</tref> with the proviso that the WebIDs still needs to be verified.</li>