Update for SPAKE2

index.bs

@@ -649,26 +649,24 @@ that may lead to authentication failures.
 Authentication with SPAKE2 {#authentication-with-spake2}
 --------------------------
 
-Issue(235): Update SPAKE2 section according to current IETF draft
-
 Issue(242): [Meta] Track CFRG PAKE competition outcome
 
 For all messages and objects defined in this section, see Appendix A for
 the full CDDL definitions.
 
 The default authentication method is
-\[SPAKE2](https://tools.ietf.org/html/draft-irtf-cfrg-spake2-08) with
+\[SPAKE2](https://tools.ietf.org/html/draft-irtf-cfrg-spake2-26) with
 the following cipher suite:
 
-1. Elliptic curve is [Curve25519](https://tools.ietf.org/html/rfc7748#page-4).
-2. Hash function is \[SHA-512](https://tools.ietf.org/html/rfc6234).
+1. Elliptic curve is \[edwards25519](https://tools.ietf.org/html/rfc7748#page-4).
+2. Hash function is \[SHA-256](https://tools.ietf.org/html/rfc6234).
 3. Key derivation function is \[HKDF](https://tools.ietf.org/html/rfc5869).
 4. Message authentication code is \[HMAC](https://tools.ietf.org/html/rfc2104).
-5. Password hash function is SHA-512.
+5. Password hash function is \[SHA-512](https://tools.ietf.org/html/rfc6234).
 
-Open Screen Protocol does not use a memory-hard hash function to hash PSKs
-with SPAKE2 and uses SHA-512 instead as the PSK is one-time use and
-is not stored in any form.
+Open Screen Protocol does not use a memory-hard hash function to hash PSKs with
+SPAKE2 and uses SHA-512 instead, as the PSK is one-time use and is not stored in
+any form.
 
 SPAKE2 provides explicit mutual authentication.
 
@@ -679,42 +677,48 @@ phone, a keyboard or a TV remote control.
 Issue(210): [Security] Describe encoding/decoding of PSK into numeric and QR codes.
 
 SPAKE2 is not symmetric and has two roles, Alice (A) and Bob (B).
-The client acts as Alice, the server acts as Bob.
-
-<!-- TODO: What do "client" and "server" mean here? -->
 
-The messages used in this authentication method are: [=auth-spake2-need-psk=],
-[=auth-spake2-handshake=], [=auth-spake2-confirmation=] and [=auth-status=].
-SPAKE2 describes in detail how [=auth-spake2-handshake=] and
-[=auth-spake2-confirmation=] are computed.
+The messages used in this authentication method are: [=auth-spake2-handshake=],
+[=auth-spake2-confirmation=] and [=auth-status=].  \[SPAKE2] describes in detail
+how [=auth-spake2-handshake=] and [=auth-spake2-confirmation=] are computed.
 
 The values `A` and `B` used in SPAKE2 are the [=agent fingerprints=] of the
-client and server, respectively. `K` is the PSK presented to the user.  `S` and
-`T` from SPAKE2 are put into the `random` field of [=auth-spake2-handshake=].
-`F` from SPAKE2 is put into the `transcript-mac` field of
-[=auth-spake2-confirmation=].
-
-If the PSK presenter wants to authenticate, the PSK presenter starts the
-authentication process by presenting the PSK to the user and sending a
-[=auth-spake2-handshake=] message. When the PSK consumer receives the
-[=auth-spake2-handshake=] message, the PSK consumer prompts the user for the PSK input
-if it has not done so yet.
+client and server, respectively. `pw` is the PSK presented to the user. 
 
-If the PSK consumer wants to authenticate, the PSK consumer sends a
-[=auth-spake2-need-psk=] message to the PSK presenter to start the authentication
-process and prompts the user to input the PSK. If the PSK presenter receives a
-[=auth-spake2-need-psk=] message after starting authentication from their side, the
-PSK presenter ignores the [=auth-spake2-need-psk=] message.
+The PSK presenter or the PSK consumer may initiate authentication (assuming the
+role of Alice in SPAKE2).
 
-After the user inputs the PSK into the PSK consumer, the PSK consumer computes
-and sends a [=auth-spake2-handshake=].
-
-When either agent both knows the PSK and has received a [=auth-spake2-handshake=]
-message, the agent computes and sends a [=auth-spake2-confirmation=] message.
-
-When either agent has received both [=auth-spake2-handshake=] and
-[=auth-spake2-confirmation=] messages, the agent validates the confirmation message
-and sends the [=auth-status=] authenticated message.
+If the PSK presenter wants to initiate authentication, it starts the
+authentication process by presenting the PSK to the user and sending a
+[=auth-spake2-handshake=] message.  The `public-value` field of the
+[=auth-spake2-handshake=] message must be set to the value of `pA` from SPAKE2
+and the `psk-status` field must be set to `psk-shown`.
+
+When the PSK consumer receives the [=auth-spake2-handshake=] message, the PSK
+consumer prompts the user for the PSK input if it has not done so yet.  Once it
+receives the PSK, it sends an [=auth-spake2-handshake=] message with the
+`public-value` field set to the value of `pB` from SPAKE2 and the `psk-status`
+field set to `psk-input`.
+
+If the PSK consumer wants to initiate authentication, the PSK consumer sends a
+[=auth-spake2-handshake=] message to the PSK presenter with the `psk-status`
+field set to `psk-needs-presentation` and the `public-value` field set to
+`pA`. The PSK presenter, on receiving this message, creates a PSK and presents
+it to the the user.  Once that is done, it sends an [=auth-spake2-handshake=]
+message to the PSK consumer with `psk-status` set to `psk-input` and the
+`public-value` field set to `pB`.
+
+Once an agent knows both `pA` and `pB` from [=auth-spake2-handshake=] messages,
+it computes and sends a [=auth-spake2-confirmation=] with the `transcript-mac`
+field set to `cA` (for Alice) or `cB` (for Bob) to the other agent.
+
+Once an agent receives an [=auth-spake2-confirmation=] message, it validates
+that message using the procedure in \[SPAKE2] and send an [=auth-status=]
+authenticated message to the other agent.  Any value of `result` other than
+`authenticated` means that authentication failed.
+
+Note that this message is merely informative as each agent independently
+computes the outcome of SPAKE2 through key confirmation verification.
 
 Presentation Protocol {#presentation-protocol}
 =====================

messages_appendix.cddl

@@ -75,23 +75,24 @@ auth-initiation-token = (
   ? 0 : text ; token
 )
 
-; type key 1002
-auth-spake2-need-psk = {
-  auth-initiation-token
-}
+auth-spake2-psk-status = &(
+ psk-needs-presentation: 0
+ psk-shown: 1
+ psk-input: 2
+)
 
-; type key 1003
+; type key 1002
 auth-spake2-handshake = {
-  auth-initation-token
-  1 : bytes .size 32 ; random
+  0: auth-spake2-psk-status ; psk-status
+  1: bytes ; public-value
 }
 
-; type key 1004
+; type key 1003
 auth-spake2-confirmation = {
-  1 : bytes .size 32 ; transcript-mac
+  1 : bytes .size 64 ; transcript-mac
 }
 
-; type key 1005
+; type key 1004
 auth-status = {
   1 : auth-status-result ; result
 }