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 Request
 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,12 +34,35 @@ protocol.
 Security considerations
 -----------------------
 
+### When *not* to use this method
+
+In case of the server:
+
+ * If the request 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
+   `<request-encryption-methods>`.
+
+In case of the client:
+
+ * If the request 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 request encryption method to explicitly
 answer a couple of questions:
 
+> How the client's request must look like? How can the server detect that the
+> client is using this particular method of encryption?
+
+The client simply makes its request via HTTPS. It the request doesn't include
+any other indication that the client is using some other method, then the
+server may assume it's using this one.
+
 > How the server publishes his encryption key? How the client retrieves it
 > securely?
 
@@ -48,7 +71,7 @@ communicating with the proper party. It receives all required encryption keys
 during the TLS handshake and trusts root CAs for the security of this exchange.
 
 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 request? Which parts are covered by the
 > encryption and which are not?
@@ -57,7 +80,6 @@ HTTPS does that on its own. All parts of the request are covered, including
 all headers, and the request target (URL's path).
 
 
-[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-reqencr-tls/tree/stable-v1"
+    xmlns="https://github.com/erasmus-without-paper/ewp-specs-sec-reqencr-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 request
+                encryption, as described here:
+
+                https://github.com/erasmus-without-paper/ewp-specs-sec-reqencr-tls
+
+                It can be used in various contexts, whenever someone needs to identify this
+                particular method of request 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>