api/challenge-response: document nonce size limits

Document limitations for the nonce and nonceSize parameters for /newSession requests. Signed-off-by: setrofim <[email protected]>
veraison · Sep 28, 2023 · da1d3e0 · da1d3e0
1 parent 2b22692
commit da1d3e0
Show file tree

Hide file tree

Showing 3 changed files with 9 additions and 3 deletions.
diff --git 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
@@ -22,15 +22,16 @@ 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
         - name: nonce
           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
@@ -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