From 2f57035cf5fb5836c547a5ee58bfbd645eb1e349 Mon Sep 17 00:00:00 2001 From: Wojciech Rygielski Date: Thu, 6 Apr 2017 14:39:21 +0200 Subject: [PATCH] Prepare it to be used with v2 security Related issue: https://github.com/erasmus-without-paper/ewp-specs-sec-intro/issues/1 --- CHANGELOG.md | 9 +++++++++ README.md | 28 +++++++++++++++++++++++--- security-entries.xsd | 47 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 81 insertions(+), 3 deletions(-) create mode 100644 security-entries.xsd diff --git a/CHANGELOG.md b/CHANGELOG.md index 3f40de5..0ba22df 100644 --- a/CHANGELOG.md +++ b/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 ----- diff --git a/README.md b/README.md index 51cb994..cca8a47 100644 --- a/README.md +++ b/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 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 `` in your + ``. + +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 @@ -47,7 +70,7 @@ 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 diff --git a/security-entries.xsd b/security-entries.xsd new file mode 100644 index 0000000..6d2695d --- /dev/null +++ b/security-entries.xsd @@ -0,0 +1,47 @@ + + + + + + + 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/ + + + + + + + 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 + + + + + + + + + +