From 3c4231529c3ba68d8b292abb55e8e09c59527e7f Mon Sep 17 00:00:00 2001
From: Wojciech Rygielski <rygielski@mimuw.edu.pl>
Date: Tue, 8 Aug 2017 15:46:22 +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          | 13 ++++++++++---
 manifest-entry.xsd | 20 ++++++++++++++++++++
 3 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 76c2a12..b51c70b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,20 @@ This document describes all the changes made to the *Outgoing Mobilities API*
 document, starting from its first beta draft version.
 
 
+0.9.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.8.1
 -----
 
diff --git a/README.md b/README.md
index a902271..9cf2bf7 100644
--- a/README.md
+++ b/README.md
@@ -35,8 +35,15 @@ though.
 Security
 --------
 
-For all endpoints of this API, implementers MUST follow the rules described in
-[EWP Authentication and Security, Version 1][sec-v1] document.
+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.
+
+This API handles data which is considered private. Server implementers are
+allowed to forbid less-secure methods of authentication and encryption for this
+API (by dropping support for them). Currently, we leave it for the server
+implementers to decide which methods are "secure enough". These recommendations
+MAY change in the future.
 
 
 Endpoints to be implemented
@@ -75,4 +82,4 @@ Data model entities involved in the response
 [echo]: https://github.com/erasmus-without-paper/ewp-specs-api-echo
 [error-handling]: https://github.com/erasmus-without-paper/ewp-specs-architecture#error-handling
 [institutions-api]: https://github.com/erasmus-without-paper/ewp-specs-api-institutions
-[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 b4573b6..1c778d8 100644
--- a/manifest-entry.xsd
+++ b/manifest-entry.xsd
@@ -3,6 +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: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-mobilities/blob/stable-v1/manifest-entry.xsd"
@@ -15,6 +16,11 @@
         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
@@ -37,6 +43,20 @@
             <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).
+
+                                    The policies described in this element apply to all endpoints of this API (the
+                                    `*-url` elements below). Clients SHOULD consult this element before accessing
+                                    any of these endpoints (otherwise, their request might be rejected by the
+                                    server).
+                                </xs:documentation>
+                            </xs:annotation>
+                        </xs:element>
                         <xs:element name="get-url" type="ewp:HTTPS" minOccurs="1" maxOccurs="1">
                             <xs:annotation>
                                 <xs:documentation>