Prepare it to be used with v2 security

Related issue:
erasmus-without-paper/ewp-specs-sec-intro#1

CHANGELOG.md

@@ -5,6 +5,15 @@ This document describes all the changes made to the *Authenticating Servers
 with TLS Certificate* document, starting from its first released version.
 
 
+1.1.0
+-----
+
+* Added the `security-entries.xsd` file. It contains the definition of an XML
+  element which can be used to reference the method of authentication described
+  in this document. See [this
+  issue](https://github.com/erasmus-without-paper/ewp-specs-sec-intro/issues/1).
+
+
 1.0.0
 -----
 

README.md

@@ -22,7 +22,7 @@ Implementing a server
 You MUST acquire a CA-signed certificate for your domain(s), and install it on
 your servers. These are just the "regular" domain-validated certificates.
 
-Note, that your APIs can be spread across multiple domains. The number of
+Note, that your endpoints can be spread across multiple domains. The number of
 domains used to implement EWP does not matter, but all of them need to be
 protected by proper certificates issued for these domains.
 
@@ -42,27 +42,57 @@ all the standard methods of validation.
 Security considerations
 -----------------------
 
+### When *not* to use this method
+
+In case of the server:
+
+ * If you **don't trust your own internal network** (the one between your
+   actual server and your TLS terminator), then you MUST NOT include `<tls/>`
+   in your `<server-auth-methods>`. (An attacker might send a spoofed response
+   from your internal network.)
+
+ * Remember, that the client may *choose* which of the supported server
+   authentication methods it applies. For example, if you support both
+   `<tlscert/>` and `<httpsig/>`, then the client MAY validate your server with
+   `<tlscert/>` and **ignore** your HTTP Signature.
+
+In case of the client:
+
+ * If you cannot be sure that your root/intermediate CA certificate store has
+   not been tampered with, then you MUST NOT use this method. (You might be
+   connecting with the attacker's machine in this case.)
+
+
 ### Main security questions
 
 The [Authentication and Security][sec-intro] document
 [recommends][sec-method-rules] that each server authentication method
 specification explicitly answers the following questions:
 
+> How the client's request must look like? How can the server know, that the
+> client *wants the server* to use this particular method of authentication?
+
+The client simply makes the request over HTTPS protocol. If there are no other
+indications that the client wants the server to use any other server
+authentication method, then the server may assume that the clients uses this
+one.
+
 > How can the client verify the server's identity?
 
 The client uses regular HTTPS server certificate validation to make sure that
 it is communicating with the proper domain and URL.
 
 This only works if the client configures his TLS properly (in particular, when
-his certificate storage is safe).
+his certificate storage is safe). See also the *When not to use this method*
+chapter above.
 
 > How can the client verify that the response has not been tampered with? Can
 > it also verify that it was indeed generated for this particular request?
 
 TLS prevents communication to be tampered with during the transport. The client
 also **trusts** that the internal network of the server is safe - it trusts
 that the server implementers wouldn't allow this method of authentication if it
-*wasn't* safe.
+*wasn't* safe. See the previous section - *When not to use this method*.
 
 > Does it provide non-repudiation? Can a client provide a solid proof later
 > on, that the server sent a particular response (in response to a particular
@@ -72,7 +102,6 @@ No. In theory, recording entire TLS session can provide this proof, but this is
 hard to achieve. TLS has not been designed for non-repudiation.
 
 
-[discovery-api]: https://github.com/erasmus-without-paper/ewp-specs-api-discovery
 [develhub]: http://developers.erasmuswithoutpaper.eu/
 [statuses]: https://github.com/erasmus-without-paper/ewp-specs-management/blob/stable-v1/README.md#statuses
 [sec-intro]: https://github.com/erasmus-without-paper/ewp-specs-sec-intro

security-entries.xsd

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema
+    xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    xmlns:xml="http://www.w3.org/XML/1998/namespace"
+    xmlns:ewp="https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/common-types.xsd"
+    elementFormDefault="qualified"
+
+    targetNamespace="https://github.com/erasmus-without-paper/ewp-specs-sec-srvauth-tlscert/tree/stable-v1"
+    xmlns="https://github.com/erasmus-without-paper/ewp-specs-sec-srvauth-tlscert/tree/stable-v1"
+>
+    <xs:import
+        schemaLocation="https://raw.githubusercontent.com/erasmus-without-paper/ewp-specs-architecture/stable-v1/common-types.xsd"
+        namespace="https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/common-types.xsd"
+    />
+
+    <xs:annotation>
+        <xs:documentation>
+            This schema is a part of the Erasmus Without Paper project. Before you start
+            using it, make sure you have read the general rules described here:
+
+            http://developers.erasmuswithoutpaper.eu/
+        </xs:documentation>
+    </xs:annotation>
+
+    <xs:element name="tlscert">
+        <xs:annotation>
+            <xs:documentation>
+                This element uniquely identifies the TLS Server Certificate Authentication
+                method, as described here:
+
+                https://github.com/erasmus-without-paper/ewp-specs-sec-srvauth-tlscert
+
+                It can be used in various contexts, whenever someone needs to identify this
+                particular method of *server authentication*. In particular, it is often seen
+                together with `HttpSecurityOptions` data type described here:
+
+                https://github.com/erasmus-without-paper/ewp-specs-sec-intro/blob/stable-v2/schema.md
+            </xs:documentation>
+        </xs:annotation>
+        <xs:complexType>
+            <xs:sequence>
+                <!-- Empty. -->
+            </xs:sequence>
+        </xs:complexType>
+    </xs:element>
+
+</xs:schema>