Skip to content

Commit 4d68992

Browse files
committed
doc: Describe validation of authentication
1 parent 3af5dce commit 4d68992

File tree

1 file changed

+23
-0
lines changed

1 file changed

+23
-0
lines changed

PROTOCOL.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,12 @@ Use a 32 byte long all-zeros `CHALLENGE_TOKEN`,
109109
[generate a new AUTH token](PROTOCOL.md#generate-auth-token)
110110
and use the result as the `AUTH` field of this `KNOCK` message.
111111

112+
The server must
113+
[validate the received AUTH token](PROTOCOL.md#validate-auth-token)
114+
of this `KNOCK` message before continuing in the communication flow.
115+
It is valid but not mandatory to send a `GOAWAY` message from server to client, if the validation failed.
116+
The communication must not continue beyond that, if validation failed.
117+
112118
## Message: CHALLENGE
113119

114120
The `OPERATION` field of this message shall be `CHALLENGE`.
@@ -133,6 +139,12 @@ Then
133139
[generate a new AUTH token](PROTOCOL.md#generate-auth-token)
134140
and use the result as the `AUTH` field of this `RESPONSE` message.
135141

142+
The server must
143+
[validate the received AUTH token](PROTOCOL.md#validate-auth-token)
144+
of this `RESPONSE` message before continuing in the communication flow.
145+
It is valid but not mandatory to send a `GOAWAY` message from server to client, if the validation failed.
146+
The communication must not continue beyond that, if validation failed.
147+
136148
## Message: COMEIN
137149

138150
The `COMEIN` message is not cryptographically secured.
@@ -185,3 +197,14 @@ It uses
185197
together with a
186198
[SHA3-256](https://en.wikipedia.org/wiki/SHA-3)
187199
algorithm.
200+
201+
## Validate AUTH token
202+
203+
Validation always only happens on the server side.
204+
205+
Generate the [EXPECTED_AUTH token](PROTOCOL.md#generate-auth-token) for the received message using the expected `CHALLENGE_TOKEN`.
206+
For a `KNOCK` message the expected `CHALLENGE_TOKEN` is 32 bytes of zeros.
207+
For a `RESPONSE` message the expected `CHALLENGE_TOKEN` is the `AUTH` field of the `CHALLENGE` message that the server sent to the client.
208+
209+
Compare the `EXPECTED_AUTH` token to the actual `AUTH` token of the `RESPONSE` message using a Constant Time Comparison Function.
210+
The result of the validation is Ok, if the tokens are equal.

0 commit comments

Comments
 (0)