From ffea58d1ed03388dd712806dd525e9b0fdc86109 Mon Sep 17 00:00:00 2001
From: Wojciech Rygielski <rygielski@mimuw.edu.pl>
Date: Tue, 8 Aug 2017 10:06:44 +0200
Subject: [PATCH] Switch to v2 security

Related issue:
https://github.com/erasmus-without-paper/ewp-specs-sec-intro/issues/1
---
 CHANGELOG.md       | 14 ++++++++++++++
 README.md          | 12 ++++++++++--
 manifest-entry.xsd | 18 +++++++++++++++---
 3 files changed, 39 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f2341fc..ec5e984 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,20 @@ This document describes all the changes made to the *Courses API* document,
 starting from its first beta draft version.
 
 
+0.7.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 SHOULD consult the newly introduced `<http-security>`
+   element in the server's manifest entry before making their requests.
+
+
 0.6.1
 -----
 
diff --git a/README.md b/README.md
index c417959..5aeadcd 100644
--- a/README.md
+++ b/README.md
@@ -176,7 +176,15 @@ Security
 --------
 
 This version of this API uses [standard EWP Authentication and Security,
-Version 1][sec-v1].
+Version 2][sec-v2]. Server implementers choose which security methods they
+support by declaring them in their manifest's API-entry.
+
+This API provides data which is also usually accessible to the anonymous public
+by other channels. It is RECOMMENDED for server implementers to not be overly
+strict on security methods they require (i.e. it is RECOMMENDED to *not*
+require extra layers of encryption in requests and responses - TLS seems more
+than enough). Server implementers MAY also consider allowing this API to be
+accessed by anonymous clients.
 
 
 Handling of invalid parameters
@@ -226,4 +234,4 @@ Data model entities involved in the response
 [replication-api]: https://github.com/erasmus-without-paper/ewp-specs-api-course-replication
 [emrex]: http://emrex.eu/
 [ids-intro]: https://github.com/erasmus-without-paper/ewp-specs-architecture#ids
-[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
diff --git a/manifest-entry.xsd b/manifest-entry.xsd
index 5d30da6..ee52878 100644
--- a/manifest-entry.xsd
+++ b/manifest-entry.xsd
@@ -3,7 +3,7 @@
     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:resp="https://github.com/erasmus-without-paper/ewp-specs-api-courses/tree/stable-v1"
+    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-courses/blob/stable-v1/manifest-entry.xsd"
@@ -17,8 +17,8 @@
     />
 
     <xs:import
-        schemaLocation="https://raw.githubusercontent.com/erasmus-without-paper/ewp-specs-api-courses/master/response.xsd"
-        namespace="https://github.com/erasmus-without-paper/ewp-specs-api-courses/tree/stable-v1"
+        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>
@@ -43,6 +43,18 @@
             <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).
+
+                                    Clients SHOULD consult this element before accessing the endpoint given in the
+                                    `url` element (otherwise, their request might be rejected by the server).
+                                </xs:documentation>
+                            </xs:annotation>
+                        </xs:element>
                         <xs:element name="url" type="ewp:HTTPS" minOccurs="1" maxOccurs="1">
                             <xs:annotation>
                                 <xs:documentation>