Merge pull request #126 from webscreens/mutual-auth

Add challenge/response mechanism for authentication

index.bs

@@ -376,7 +376,100 @@ request they are associated with.
 Authentication {#authentication}
 ================================
 
-Issue(102): Incorporate material from the \[J-PAKE](j-pake.md) document.
+In order for one agent (the challenger) to authenticate another (the responder),
+the challenger may send an authentication-request message and expect an
+authentication-response message to be sent back from the responder.  To
+mutually authenticate, this mechanism is used twice, once by each side acting as
+the challenger.  This mechanism assumes the agents share a low-entropy secret,
+such as a number or a short password that could be entered by a user on a
+keyboard or TV remote control.
+
+For all messages and objects defined in this section, see Appendix A for the full
+CDDL definitions.
+
+The challenger sends an authentication-request message with the following values:
+
+-   mechanism: The authentication mechanism being used.  This standard only
+    defines the mechanism hkdf-of-scrypt-of-psk but this field gives a place for
+    other mechanisms to be specified.
+
+-   salt: 32 random bytes.  This salt is used in HKDF, so see
+    https://tools.ietf.org/html/rfc5869#section-3.1 for more details on how this
+    value should be generated.
+
+-   cost: log base 2 of the cost parameter (N) for scrypt defined in [RFC
+    7914 section 2](https://tools.ietf.org/html/rfc7914#section-2).  It must be
+    greater than or equal to 14 (to avoid being too weak) and less than or equal
+    to 128 (the limit defined by scrypt).  A value of 15 is recommended (an
+    scrypt N of 2^15 or 32768).
+
+The responder replies with an authentication-response message with the following values:
+
+-   result:  If the responder was able to calculate proof of possession of the
+    shared secret, and if it failed, why it failed.
+
+-   proof: The result of running the authentication mechanism.  The steps for
+    hkdf-of-scrypt-of-psk are described below.
+
+The challenger verifies the proof and sends the responder an
+authentication-result message with the following values:
+
+-   result:  If the challenger was able to authenticate the responder or not,
+    and if not, why not.
+
+The challenger must limit the time the responder has to send a response to 60
+seconds (to avoid the possibility of brute-force attacks.)
+
+
+For hkdf-of-scrypt-of-psk, the proof is calculated using the following steps:
+
+1. Let secret be the pre-shared secret.
+
+2. Let N be 2 to the power of of the cost from the authentication-request
+   message.
+
+3. Let r be 8.
+
+4. Let p be 1.
+
+5. Let keyLength be 32.
+
+6. Let scryptResult be the result of running
+   [scrypt](https://tools.ietf.org/html/rfc7914) on secret with cost parameter N,
+   block size r, parallelization parameter p, and derived key length of
+   keyLength.
+
+7. Let hashFunction be sha-256.
+
+8. Let salt be the salt from the authentication-request message.
+
+9. Let info be a CBOR-serialized certificate-fingerprint-pair object (CDDL
+   defined in Appendix A) with the following values:
+
+-   challenger-fingerprint: The result of running sha-256 on the
+    Distinguished Encoding Rules (DER) form (see
+    https://tools.ietf.org/html/rfc8122#section-5) of the certificate used by
+    the challenger in the QUIC crypto handshake during connection establishment.
+
+-   responder-fingerprint: The result of running sha-256 on the
+    Distinguished Encoding Rules (DER) form (see
+    https://tools.ietf.org/html/rfc8122#section-5) of the certificate used by
+    the responder in the QUIC crypto handshake during connection establishment.
+
+9. Let proof be the result of running
+   [HKDF](https://tools.ietf.org/html/rfc5869) on scryptResult with 
+   both the extract and expand steps, hash function hashFunction,
+   application-specific info, and output key length keyLength.
+
+To verify that the responder's proof is correct, the challenger makes the same
+calculation of the proof and compares the result. If the results are the same,
+the challenger considers the responder authenticated, and considers it
+unauthenticated otherwise.  
+
+Note: the values of 32 above (for salt length, keyLength) are based on the
+output size of sha-256.  If a different hash mechanism is used in the future,
+these values should be updated as well.
+
 
 Control Protocols {#control-protocols}
 ============================
@@ -510,7 +603,7 @@ message which contains the following values:
 
 -   presentation-id: The ID of the presentation to connect to.
 
-- url: The URL of the presentation to connect to.
+-   url: The URL of the presentation to connect to. 
 
 
 The receiver should, upon receipt of a
@@ -705,6 +798,53 @@ response = (
 
 request-id = uint
 
+; type key 1001 
+authentication-request = {
+  request
+  1: authentication-mechanism ; mechanism
+  2: bytes ; salt
+  3: uint ; cost
+}
+
+; type key 1002 
+authentication-response = {
+  response
+  1: authentication-response-result ; result
+  2: bytes ; proof
+}
+
+certificate-fingerprint-pair = [
+  challenger-fingerprint: bytes
+  responder-fingerprint: bytes
+]
+
+; type key 1003
+authentication-result = {
+  1: authentication-result-result ; result
+}
+
+
+authentication-mechanism = &(
+  hkdf-of-scrypt-of-psk: 1
+)
+
+authentication-response-result = &(
+  ok: 0
+  unknown-error: 1
+  mechanism-unknown: 2
+  salt-too-small: 3
+  cost-too-low: 4
+  cost-too-high: 5
+  secret-unknown: 6
+  calculation-took-too-long: 7
+)
+
+authentication-result-result = &(
+  authenticated: 0
+  unknown-error: 1
+  proof-invalid: 2
+)
+
 ; type key 14
 presentation-url-availability-request = {
   request