From da1d3e07f9daf0c768b838e0228ce9fba153f210 Mon Sep 17 00:00:00 2001
From: setrofim <setrofim@gmail.com>
Date: Wed, 27 Sep 2023 15:19:10 +0100
Subject: [PATCH] api/challenge-response: document nonce size limits

Document limitations for the nonce and nonceSize parameters
for /newSession requests.

Signed-off-by: setrofim <setrofim@gmail.com>
---
 api/challenge-response/README.md               | 4 ++++
 api/challenge-response/challenge-response.yaml | 5 +++--
 api/challenge-response/schemas/components.yaml | 3 ++-
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/api/challenge-response/README.md b/api/challenge-response/README.md
index 16c9d12..b001daa 100644
--- a/api/challenge-response/README.md
+++ b/api/challenge-response/README.md
@@ -66,6 +66,10 @@ session expiry has elapsed.
   }
 ```
 
+`nonceSize` must be between `8` and `64`. Analogously, `nonce` must be between
+8 and 64 bytes when decoded (which means the specified base64 string must be no
+longer than 88 bytes).
+
 ### Asynchronous verification
 
 * Submit evidence for this session:
diff --git a/api/challenge-response/challenge-response.yaml b/api/challenge-response/challenge-response.yaml
index 1c0ab5f..0a6a7f1 100644
--- a/api/challenge-response/challenge-response.yaml
+++ b/api/challenge-response/challenge-response.yaml
@@ -22,7 +22,7 @@ paths:
         - name: nonceSize
           in: query
           description: >
-            number of bytes of the returned nonce
+            number of bytes of the returned nonce. Must be between 8 and 64.
           required: false
           schema:
             type: integer
@@ -30,7 +30,8 @@ paths:
           in: query
           description: >
             the API server should not generate a nonce for this session and
-            use instead the one supplied by the client
+            use instead the one supplied by the client. The supplied value must
+            decode to a byte sequence between 8 and 64 bytes long.
           required: false
           schema:
             type: string
diff --git a/api/challenge-response/schemas/components.yaml b/api/challenge-response/schemas/components.yaml
index a53cdc2..70db188 100644
--- a/api/challenge-response/schemas/components.yaml
+++ b/api/challenge-response/schemas/components.yaml
@@ -10,7 +10,8 @@ components:
           type: string
           format: byte
           description:
-            base64 encoded 32, 48, or 64 bytes random value
+            base64 encoded random value. Must be between 8 and 64 bytes long in
+            its raw form (the base64 encoding must be no longer than 88 bytes).
           example: MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI=
         expiry:
           type: string