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 *TLS and Response
 Confidentiality* 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 encryption described
+  in this document. See [this
+  issue](https://github.com/erasmus-without-paper/ewp-specs-sec-intro/issues/1).
+
+
 1.0.0
 -----
 

README.md

@@ -21,7 +21,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. You
-MUST serve your API via HTTPS.
+MUST serve your endpoint(s) via HTTPS.
 
 
 Implementing a client
@@ -34,20 +34,43 @@ protocol.
 Security considerations
 -----------------------
 
+### When *not* to use this method
+
+In case of the server:
+
+ * If the response MAY contain private user data, and 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
+   `<response-encryption-methods>`.
+
+In case of the client:
+
+ * If the response MAY contain private user data, and you cannot be sure that
+   your root/intermediate CA certificate store has not been tampered with,
+   then you MUST NOT use this method.
+
+
 ### Main security questions
 
 The [Authentication and Security][sec-intro] document
 [requires][sec-method-rules] each response encryption method to explicitly
 answer a couple of 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 encryption?
+
+The client simply makes its request via HTTPS. It the request doesn't include
+any indication that some other server authentication method is desired, then
+the server may assume that the client uses this one.
+
 > How the client delivers his encryption key to the server?
 
 The client uses HTTPS server certificate validation to make sure that it is
 communicating with the proper party. The server receives required encryption
 keys during the TLS handshake.
 
 Note, that this only works when the clients can trust their CA certificate
-stores.
+stores. See *When not to use this method* chapter above.
 
 > How to encrypt and decrypt the response? Which parts are covered by the
 > encryption and which are not?
@@ -56,7 +79,6 @@ HTTPS does that on its own. All parts of the response are covered, including
 all headers.
 
 
-[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-resencr-tls/tree/stable-v1"
+    xmlns="https://github.com/erasmus-without-paper/ewp-specs-sec-resencr-tls/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="tls">
+        <xs:annotation>
+            <xs:documentation>
+                This element uniquely identifies the "regular TLS" method of response
+                encryption, as described here:
+
+                https://github.com/erasmus-without-paper/ewp-specs-sec-resencr-tls
+
+                It can be used in various contexts, whenever someone needs to identify this
+                particular method of response encryption. 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>