Switch to v2 security

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

CHANGELOG.md

@@ -5,6 +5,50 @@ This document describes all the changes made to the *Echo API* document,
 starting from its first released version.
 
 
+2.0.0
+-----
+
+ * This API now requires implementers to upgrade their implementations to
+   [Version 2](https://github.com/erasmus-without-paper/ewp-specs-sec-intro/tree/stable-v2)
+   of the *Authentication and Security* document.
+
+   In particular, this means that the clients MUST be aware of the fact, that
+   the server is no longer required to support methods of authentication and
+   encryption which it *was* required to support in the previous versions of
+   this API. Clients (such as the [Echo API
+   Validator](https://developers.erasmuswithoutpaper.eu/#validator)) SHOULD
+   consult the newly introduced `<http-security>` element in the server's
+   manifest entry before making their requests.
+
+ * Because we are releasing a new major release (which is no longer
+   backward-compatible with the previously released stable `1.x.x` releases),
+   XML namespaces were changed to reflect that.
+
+   In particular, API-entry namespace was changed from:
+
+   ```
+   https://github.com/erasmus-without-paper/ewp-specs-api-echo/blob/stable-v1/manifest-entry.xsd
+   ```
+
+   to:
+
+   ```
+   https://github.com/erasmus-without-paper/ewp-specs-api-echo/blob/stable-v2/manifest-entry.xsd
+   ```
+
+   And the Echo-response namespace was changed from:
+
+   ```
+   https://github.com/erasmus-without-paper/ewp-specs-api-echo/tree/stable-v1
+   ```
+
+   to:
+
+   ```
+   https://github.com/erasmus-without-paper/ewp-specs-api-echo/tree/stable-v2
+   ```
+
+
 1.1.1
 -----
 

README.md

@@ -21,25 +21,37 @@ important parts are documented in XSD files!).
 Authentication and Encryption
 -----------------------------
 
-This version (v1.x.x) of Echo API follows the rules described in [EWP
-Authentication and Security, Version 1][sec-v1] document. It requires
-implementers to support a very specific set of security solutions:
-
- * For client authentication, [TLS Client Certificate
-   Authentication][cliauth-tlscert] method MUST be used, and self-signed
-   client certificates MUST be accepted by the server.
-
- * For server authentication, [TLS Server Certificate
-   Authentication][srvauth-tlscert] method MUST be used.
-
- * Regular TLS MUST be used for both [request][reqencr-tls] and
-   [response][resencr-tls] encryption.
-
- * Other methods MAY be supported, but it is NOT REQUIRED to support them (and
-   the server doesn't declare support for them in his manifest file).
-
-Please note, that soon there will be a new (v2.x.x) version of this API, which
-will have different authentication and encryption requirements.
+This version of this API uses [standard EWP Authentication and Security,
+Version 2][sec-v2]. Server implementers choose which security methods they
+support by declaring them in their Manifest API entry.
+
+Since Echo API is implemented primarily for testing everyone's security
+framework, servers are RECOMMENDED to support *all* currently specified
+[standard authentication and encryption methods][standard-sec-methods], with
+some minor exceptions:
+
+ * It is FORBIDDEN to support [Anonymous Clients][cliauth-none] in Echo API.
+
+ * If you (the server implementer) are certain that you *won't* be supporting
+   some particular security method in *any* of your *other* APIs, then it's
+   okay to "skip" supporting this method in Echo API too. (This is especially
+   true in case of [TLS Client Certificate Authentication][cliauth-tlscert],
+   which - based on the input from EWP developers - turned out to be difficult
+   to implement in some architectures).
+
+ * When new security methods are introduced in the future, it's usually okay to
+   "lag behind" a little. That is, you usually won't be required to support
+   new security methods immediately after they are introduced. However, in
+   time, **some older security methods MAY get deprecated, or even banned** -
+   which might result in you getting cut off from the rest of the EWP Network
+   (first, you may get banned by some more restrictive partners, and later on,
+   by the Registry Service administrators). So you should keep an eye on that!
+
+It is also RECOMMENDED that you support all these security methods at a *single
+endpoint/URL* (as opposed to having separate API-entries in your manifest, per
+each possible combination of security methods). At the time we are writing
+this, all standard methods are designed in a way that enables them to be used
+interchangeably on single URL (and we hope it will stay this way).
 
 
 Request method
@@ -104,8 +116,8 @@ The format of the Echo API manifest entry is described in the
 [manifest-entry.xsd](manifest-entry.xsd) file. You will need to use a proper
 `xmlns` when you are including it in your manifest file.
 
-*Hint:* The deployment step looks exactly the same for all APIs, so in most
-cases it is not described, again and again, in all API specifications.
+Note, that this deployment step looks exactly the same for all APIs, so in most
+cases API designers skip it in their API specifications.
 
 
 [registry-spec]: https://github.com/erasmus-without-paper/ewp-specs-api-registry
@@ -125,3 +137,4 @@ cases it is not described, again and again, in all API specifications.
 [reqencr-tls]: https://github.com/erasmus-without-paper/ewp-specs-sec-reqencr-tls
 [resencr-tls]: https://github.com/erasmus-without-paper/ewp-specs-sec-resencr-tls
 [sec-v1]: https://github.com/erasmus-without-paper/ewp-specs-sec-intro/tree/stable-v1
+[sec-v2]: https://github.com/erasmus-without-paper/ewp-specs-sec-intro/tree/stable-v2

manifest-entry.xsd

@@ -3,17 +3,23 @@
     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"
+    xmlns:sec="https://github.com/erasmus-without-paper/ewp-specs-sec-intro/tree/stable-v2"
     elementFormDefault="qualified"
 
-    targetNamespace="https://github.com/erasmus-without-paper/ewp-specs-api-echo/blob/stable-v1/manifest-entry.xsd"
-    xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-echo/blob/stable-v1/manifest-entry.xsd"
+    targetNamespace="https://github.com/erasmus-without-paper/ewp-specs-api-echo/blob/stable-v2/manifest-entry.xsd"
+    xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-echo/blob/stable-v2/manifest-entry.xsd"
 >
 
     <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:import
+        schemaLocation="https://raw.githubusercontent.com/erasmus-without-paper/ewp-specs-sec-intro/stable-v2/schema.xsd"
+        namespace="https://github.com/erasmus-without-paper/ewp-specs-sec-intro/tree/stable-v2"
+    />
+
     <xs:annotation>
         <xs:documentation>
             This schema is a part of the Erasmus Without Paper project. Before you start
@@ -36,6 +42,15 @@
             <xs:complexContent>
                 <xs:extension base="ewp:ManifestApiEntryBase">
                     <xs:sequence>
+                        <xs:element name="http-security" type="sec:HttpSecurityOptions" minOccurs="0" maxOccurs="1">
+                            <xs:annotation>
+                                <xs:documentation>
+                                    Describes which security policies the server supports for this API. If not
+                                    given, then the server states that it supports the default set of security
+                                    policies (as described in the annotations in sec:HttpSecurityOptions).
+                                </xs:documentation>
+                            </xs:annotation>
+                        </xs:element>
                         <xs:element name="url" type="ewp:HTTPS" minOccurs="1" maxOccurs="1">
                             <xs:annotation>
                                 <xs:documentation>

response.xsd

@@ -4,8 +4,8 @@
     xmlns:xml="http://www.w3.org/XML/1998/namespace"
     elementFormDefault="qualified"
 
-    targetNamespace="https://github.com/erasmus-without-paper/ewp-specs-api-echo/tree/stable-v1"
-    xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-echo/tree/stable-v1"
+    targetNamespace="https://github.com/erasmus-without-paper/ewp-specs-api-echo/tree/stable-v2"
+    xmlns="https://github.com/erasmus-without-paper/ewp-specs-api-echo/tree/stable-v2"
 >
 
     <xs:annotation>