From b7ff5ffcdbb52a83241633036107f273788e5839 Mon Sep 17 00:00:00 2001
From: Joachim Bauch <bauch@struktur.de>
Date: Thu, 12 May 2022 17:13:23 +0200
Subject: [PATCH] Document hello version 2.0 authentication.

---
 docs/standalone-signaling-api-v1.md | 88 ++++++++++++++++++++++++++---
 1 file changed, 79 insertions(+), 9 deletions(-)

diff --git a/docs/standalone-signaling-api-v1.md b/docs/standalone-signaling-api-v1.md
index ed548006..ca412113 100644
--- a/docs/standalone-signaling-api-v1.md
+++ b/docs/standalone-signaling-api-v1.md
@@ -140,7 +140,7 @@ Message format (Client -> Server):
       "id": "unique-request-id",
       "type": "hello",
       "hello": {
-        "version": "the-protocol-version-must-be-1.0",
+        "version": "the-protocol-version",
         "auth": {
           "url": "the-url-to-the-auth-backend",
           "params": {
@@ -159,7 +159,7 @@ Message format (Server -> Client):
         "sessionid": "the-unique-session-id",
         "resumeid": "the-unique-resume-id",
         "userid": "the-user-id-for-known-users",
-        "version": "the-protocol-version-must-be-1.0",
+        "version": "the-protocol-version",
         "server": {
           "features": ["optional", "list, "of", "feature", "ids"],
           ...additional information about the server...
@@ -172,12 +172,82 @@ future version. Clients should use the data from the
 [`welcome` message](#welcome-message) instead.
 
 
+### Protocol version "1.0"
+
+For protocol version `1.0` in the `hello` request, the `params` from the `auth`
+field are sent to the Nextcloud backend for [validation](#backend-validation).
+
+
+### Protocol version "2.0"
+
+For protocol version `2.0` in the `hello` request, the `params` from the `auth`
+field must contain a `token` entry containing a [JWT](https://jwt.io/).
+
+The JWT must contain the following fields:
+- `iss`: URL of the Nextcloud server that issued the token.
+- `iat`: Timestamp when the token has been issued.
+- `exp`: Timestamp of the token expiration.
+- `sub`: User Id (if known).
+- `userdata`: Optional JSON containing more user data.
+
+It must be signed with an RSA, ECDSA or Ed25519 key.
+
+Example token:
+```
+eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJodHRwczovL25leHRjbG91ZC1tYXN0ZXIubG9jYWwvIiwiaWF0IjoxNjU0ODQyMDgwLCJleHAiOjE2NTQ4NDIzODAsInN1YiI6ImFkbWluIiwidXNlcmRhdGEiOnsiZGlzcGxheW5hbWUiOiJBZG1pbmlzdHJhdG9yIn19.5rV0jh89_0fG2L-BUPtciu1q49PoYkLboj33EOdD0qQeYcvE7_di2r5WXM1WmKUCOGeX3hzn6qldDMrJBNuxvQ
+```
+
+Example public key:
+```
+-----BEGIN PUBLIC KEY-----
+MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEIoCsNSCXyxK25zvSKRio0uiBzwub
+ONq3tiGTPZo3p2Ogn6wAhhsuSxbFuUQDWMX7Tsu9fDzVdwpRHPT4y3V9cA==
+-----END PUBLIC KEY-----
+```
+
+Example payload:
+```
+{
+  "iss": "https://nextcloud-master.local/",
+  "iat": 1654842080,
+  "exp": 1654842380,
+  "sub": "admin",
+  "userdata": {
+    "displayname": "Administrator"
+  }
+}
+```
+
+The public key is retrieved from the capabilities of the Nextcloud instance
+in `config` key `hello-v2-token-key` inside `signaling`.
+
+```
+        "spreed": {
+          "features": [
+            "audio",
+            "video",
+            "chat-v2",
+            "conversation-v4",
+            ...
+          ],
+          "config": {
+            …
+            "signaling": {
+              "hello-v2-token-key": "-----BEGIN RSA PUBLIC KEY----- ..."
+            }
+          }
+        },
+```
+
+
 ### Backend validation
 
-The server validates the connection request against the passed auth backend
-(needs to make sure the passed url / hostname is in a whitelist). It performs
-a POST request and passes the provided `params` as JSON payload in the body
-of the request.
+For `hello` protocol version `1.0`, the server validates the connection request
+against the passed auth backend (needs to make sure the passed url / hostname
+is in a whitelist).
+
+It performs a POST request and passes the provided `params` as JSON payload in
+the body of the request.
 
 Message format (Server -> Auth backend):
 
@@ -236,7 +306,7 @@ Message format (Client -> Server):
       "id": "unique-request-id",
       "type": "hello",
       "hello": {
-        "version": "the-protocol-version-must-be-1.0",
+        "version": "the-protocol-version",
         "auth": {
           "type": "the-client-type",
           ...other attributes depending on the client type...
@@ -294,7 +364,7 @@ Message format (Client -> Server):
       "id": "unique-request-id",
       "type": "hello",
       "hello": {
-        "version": "the-protocol-version-must-be-1.0",
+        "version": "the-protocol-version",
         "resumeid": "the-resume-id-from-the-original-hello-response"
       }
     }
@@ -306,7 +376,7 @@ Message format (Server -> Client):
       "type": "hello",
       "hello": {
         "sessionid": "the-unique-session-id",
-        "version": "the-protocol-version-must-be-1.0"
+        "version": "the-protocol-version"
       }
     }