Merge pull request #16 from mbtaylor/x509-edits

Modify text concerning ivoa_x509 scheme

Author: mbtaylor

AuthVO.tex

@@ -425,41 +425,59 @@ \subsubsection{\mbox{\tt ivoa\_x509}}\label{sec:ivoa-x509}
 
 The \verb|ivoa_x509| authentication scheme indicates that the service
 will accept X.509 client certificates as authentication permits,
-and describes how to acquire such certificates.
+and optionally describes how to acquire a suitable certificate.
+
+The standard usage model for X.509 certificates is that 
+a person or organisation obtains a certificate from a
+Certification Authority (CA) once its identification has
+been verified by a Registration Authority.
+
+A client in posession of a client certificate can then use it to
+sign TLS (HTTPS) connections, and the service can examine the signature
+to authenticate the identity of the client.
+Such authentication will succeed if the service trusts the signing CA.
 
 \begin{description}
   \item[Scheme name:] \verb|ivoa_x509|
   \item[Parameters:] \mbox{}
   \begin{itemize}
-    \item \verb|access_url| (required) ---
-          indicates where to get the certificate,
+    \item \verb|access_url| (optional) ---
+          indicates where to get a suitable certificate,
           see Section~\ref{sec:access-url}
-    \item \verb|standard_id| (required) ---
+    \item \verb|standard_id| (required iff \verb|access_url| is present) ---
           indicates how to authenticate at \verb|access_url|,
           see Section~\ref{sec:standard-id}
   \end{itemize}
-  \item[Login response:] PEM-encoded X.509 certificate chain
-                         including private key
+  \item[Login response (if used):] PEM-encoded X.509 certificate chain
+                                   including private key
   \item[Scope:] Origin of challenge URL
 \end{description}
 
+The \verb|ivoa_x509| challenge exists in two forms:
+with and without the \verb|access_url|/\verb|standard_id| parameter pair.
+These optional parameters advise the client how to obtain a certificate
+for use within the domain of the challenge if it does not already have one.
 
-A client in posession of a client certificate can use it to
-sign TLS (HTTPS) connections, and the service can examine the signature
-to authenticate the identity of the client.
+For either form of the challenge,
+if the client is in possession of a certificate
+signed by a CA it expects the service to trust, it may use it to
+sign requests to protected resources within the domain of the challenge.
 
-To use this scheme, the client must present a username and password
+If the client does not hold any such certificate,
+and the \verb|access_url|/\verb|standard_id| pair is present,
+it may obtain one by presenting credentials
 to the endpoint given by the \verb|access_url| parameter,
 in the form defined by the \verb|standard_id| parameter.
 If authentication is successful, a 200 OK response must be returned
 whose body is an X.509 certificate chain including its private key,
 in PEM format.  The \header{Content-Type} header of this response
-should be ``{\tt application/x-pem-file}''. \todo{should it?}
-Current implementations support only RSA encoding.
-\todo{I copied this from a code comment but I don't know what it means}
+should be ``{\tt application/x-pem-file}''.
 If authentication fails, a 401 or 403 response should be returned.
 Once in possession of the returned certificate,
 the client can use it to sign subsequent requests to protected resources.
+Certificates obtained in this way may not be usable in all X.509 contexts
+(i.e. may not be signed by a widely trusted CA),
+but should be usable within the domain of the current challenge.
 
 Since client certificates achieve authentication by signing requests
 using public key cryptography, they cannot be stolen by third parties,
@@ -863,18 +881,18 @@ \subsection{Mandatory authentication with certificates}
 % https://ws-uv.canfar.net/youcat/capabilities,
 % whose certificate acquisition endpoint is at
 % https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/cred/generate.
-% But at time of writing it wasn't really working (no parameters in challenge)
-% and it uses optional, rather than mandatory, authentication.
+% However YouCat uses optional, rather than mandatory, authentication.
 
 Probe the VOSI-capabilities endpoint of a TAP service to check
 for authentication modality (Section~\ref{sec:modalities}):
 {\footnotesize
 \begin{verbatim}
 % curl --head https://abc.example.net/tap/capabilities
 HTTP/1.1 401 Unauthorized
+www-authenticate: Bearer
+www-authenticate: ivoa_x509
 www-authenticate: ivoa_x509 standard_id="ivo://ivoa.net/sso#BasicAA",
                   access_url="https://xyz.example.net/cert/generate"
-www-authenticate: Bearer
 \end{verbatim}
 }
 
@@ -883,10 +901,16 @@ \subsection{Mandatory authentication with certificates}
 is required to access the service.
 The \verb|Bearer| challenge (\rfc{6750}) means we can authenticate with
 a Bearer Token if we have or know how to get one, but we don't.
-We can however use the \verb|ivoa_x509| challenge
-(Section~\ref{sec:ivoa-x509});
-it has a \verb|standard_id| of \verb|BasicAA| (Section~\ref{sec:standard-id})
-so transmit user credentials using
+The unparameterised \verb|ivoa_x509| challenge means
+the client can, in principle, authenticate with a certificate
+from any valid CA and not just one issued by the endpoint in the
+parameterised challenge.  
+Without having such a certificate however we can use
+the parameterised \verb|ivoa_x509| challenge
+(Section~\ref{sec:ivoa-x509}) which advises one way to acquire
+a suitable certificate.
+It has a \verb|standard_id| of \verb|BasicAA| (Section~\ref{sec:standard-id})
+so we transmit user credentials using
 HTTP Basic Authentication to the \verb|access_url|:
 
 {\footnotesize