Integrate feedback from review

Author: mrts

README.md

@@ -219,7 +219,7 @@ The authentication steps are as follows:
 1. **User enters the authentication PIN and gives consent**.
 1. **Web eID application exchanges APDUs with the eID card to get the authentication certificate**. The Web eID application uses the PC/SC API to send APDU commands to the smart card to select the authentication certificate file and read its content. In case of a tier 2 card, it uses the PKCS#11 API instead to get the certificate.
 1. **eID card responds with the authentication certificate**. The smart card responds with APDU responses containing the certificate bytes.
-1. **Web eID application creates the authentication token and creates the authentication value to be signed**. The Web eID application creates the authentication token according to the [specification below](#web-eid-authentication-token-specification), and embeds the user certificate in the token. The application calculates the value to be signed using the origin and challenge nonce received from the browser extension with the formula `hash(origin)+hash(challenge)` and then hashes it. The hash algorithm used depends on the capabilities of the card, see details below.
+1. **Web eID application creates the authentication token and creates the authentication value to be signed**. The Web eID application creates the authentication token according to the [specification below](#web-eid-authentication-token-specification), and embeds the user certificate in the token. The application calculates the value to be signed using the origin and challenge nonce received from the browser extension with the formula `hash(origin)+hash(challenge nonce)` and then hashes it. The hash algorithm used depends on the capabilities of the card, see details below.
 1. **Web eID application exchanges APDUs with the eID card to sign the authentication value**. The Web eID application sends APDU commands to the smart card to select the authentication security environment, verify the PIN and to sign the hash of the authentication value.
 1. **eID card responds with the authentication value signature**. The smart card encrypts the authentication value with the authentication private key on the card to create the signature, and responds with APDU responses containing the signature.
 1. **Web eID application returns the authentication token through the browser extension to the JavaScript application**. The Web eID application embeds the signature into the authentication token and returns it to the browser extension. The Web eID browser extension returns the token to the JavaScript application in the asynchronous response to the `webeid.authenticate()` call.
@@ -235,7 +235,7 @@ The authentication steps are as follows:
      1. The server application
          1. validates the OCSP response,
          1. looks up the challenge nonce from its local store using an identifier specific to the browser session and validates that the challenge nonce hasn't expired by comparing current time with the nonce issuing time from the store,
-         1. validates that the token signature was created using the provided user certificate by reconstructing the signed data `hash(origin)+hash(challenge)` and using the public key from the certificate to verify the signature in the `signature` field,
+         1. validates that the token signature was created using the key that corresponds to the provided user certificate by reconstructing the signed data `hash(origin)+hash(challenge nonce)` and using the public key from the certificate to verify the signature in the `signature` field,
          1. if the signature verification succeeds, then the origin and challenge nonce have been implicitly and correctly verified without the need to implement any additional security checks,
          1. validates the subject of the authentication certificate.
      1. If validation succeeds, the user is authenticated. The server application responds accordingly, for example by setting the HTTP session cookie in the response. The server application retrieves user details from the subject field of the authentication certificate.
@@ -248,7 +248,7 @@ Web eID authentication token validation libraries that implement the validation
 
 ##### Authentication and WebAuthn
 
-As mentioned above, the Web eID authentication subsystem is similar in principle, purpose and most of the steps to the WebAuthn specification. Like in WebAuthn, a server-generated challenge is encrypted with authentication private key, authentication takes place in the JavaScript application and browser extension layer using `fetch()` calls for communicating with the server and origin validation is an integral part of the security model.
+As mentioned above, the Web eID authentication subsystem is similar in principle, purpose and most of the steps to the WebAuthn specification. Like in WebAuthn, a server-generated challenge is signed with the authentication private key, authentication takes place in the JavaScript application and browser extension layer using `fetch()` calls for communicating with the server and origin validation is an integral part of the security model.
 
 However, WebAuthn has a different design with separate loosely coupled authenticator components that work on a different level of abstraction, and Web eID authentication token format is different, see the section [_Web eID authentication token specification_](#web-eid-authentication-token-specification) below for more details.
 
@@ -262,7 +262,7 @@ The server application can retrieve user details from the authentication certifi
 
 Use of Token Binding protects the authentication flow from man-in-the-middle and token export and replay attacks. With token binding, man-in-the-middle attacks cannot forward requests or replay credentials because they cannot prove they have the key bound to the token, as the key is securely stored in the user's device.
 
-A TSL terminating reverse proxy may be in use in front of the server application. There is a draft proposal [*HTTPS Token Binding with TLS Terminating Reverse Proxies*](https://tools.ietf.org/html/draft-ietf-tokbind-ttrp-07) to support forwarding token binding information through the proxy to the backend server, which facilitates the reverse proxy and backend server functioning together as though they are a single logical server side deployment of Token Binding.
+A TLS terminating reverse proxy may be in use in front of the server application. There is a draft proposal [*HTTPS Token Binding with TLS Terminating Reverse Proxies*](https://tools.ietf.org/html/draft-ietf-tokbind-ttrp-07) to support forwarding token binding information through the proxy to the backend server, which facilitates the reverse proxy and backend server functioning together as though they are a single logical server side deployment of Token Binding.
 
 However, Token Binding is not supported by mainstream browsers and proxy usage may still be problematic: the server application can see if token binding is missing but it is not obvious if that is malicious or a proxy has stripped off the token binding.
 

docs/web-eid-auth-token-v2-format-spec.md

@@ -7,7 +7,7 @@ date: <<DATE>>
 
 # Introduction
 
-As of September 2021, the Estonian Information System Authority is preparing to introduce Web eID -- a new architecture solution for web authentication and signing[^webeid]. In this new architecture, a user of the Estonian ID card is authenticated to a website on the application level by signing the website’s challenge with the help of the Web eID browser extension.
+As of September 2021, the Estonian Information System Authority is preparing to introduce Web eID -- a new architecture solution for web authentication and signing[^webeid]. In this new architecture, a user of the Estonian ID card is authenticated to a website on the application level by signing the website’s challenge nonce with the help of the Web eID browser extension.
 
 In version 1, Web eID was using the OpenID X509 ID Token format[^openidx5idtoken] in authentication tokens. However, the OpenID X509 ID Token format had weaknesses that make it possible to use it incorrectly.
 
@@ -59,11 +59,11 @@ The header part contains a JSON structure that contains the `alg` field which id
 
 ## Weaknesses of the OpenID X509 ID Token format
 
-The only values that have to be included under the user’s signature to achieve the security properties of the protocol are the website’s challenge (the `nonce` field above) and the website’s origin (the `aud` field above). The inclusion of the fields `exp`, `iat`, `iss` and `sub` under the signature serve no practical purpose. On the contrary, the presence of these fields in the authentication token introduces a risk of vulnerabilities in case the authentication implementation of a website decides to rely on any of them for making security critical decisions. A correct implementation should ignore these fields and verify the freshness of the authentication token using a locally-stored trusted timestamp that indicates the time when the challenge was issued.
+The only values that have to be included under the user’s signature to achieve the security properties of the protocol are the website’s challenge nonce (the `nonce` field above) and the website’s origin (the `aud` field above). The inclusion of the fields `exp`, `iat`, `iss` and `sub` under the signature serve no practical purpose. On the contrary, the presence of these fields in the authentication token introduces a risk of vulnerabilities in case the authentication implementation of a website decides to rely on any of them for making security critical decisions. A correct implementation should ignore these fields and verify the freshness of the authentication token using a locally-stored trusted timestamp that indicates the time when the challenge nonce was issued.
 
 While the fields `nonce` and `aud` must be included under the signature, including them in the authentication token introduces a risk of man-in-the-middle relay impersonation attacks, as a faulty implementation can verify the signature without ensuring that the fields included under the signature correspond to the trusted values stored locally by the website.
 
-Furthermore, the inclusion of the `nonce` field in the authentication token introduces a risk of forged login attacks, as a faulty implementation may use the nonce value from the received authentication token to lookup the corresponding data in its local storage, without verifying that the authentication token is received from the same browser to which the corresponding challenge was issued. Such a flaw would enable a cross-site request forgery attack where an attacker can forge a request to force a victim’s browser to log into a vulnerable website using the attacker’s credential (authentication token).
+Furthermore, the inclusion of the `nonce` field in the authentication token introduces a risk of forged login attacks, as a faulty implementation may use the nonce value from the received authentication token to lookup the corresponding data in its local storage, without verifying that the authentication token is received from the same browser to which the corresponding challenge nonce was issued. Such a flaw would enable a cross-site request forgery attack where an attacker can forge a request to force a victim’s browser to log into a vulnerable website using the attacker’s credential (authentication token).
 
 Even though the Web eID project provides ready-made libraries for validating the authentication token securely, it is possible that not every developer implementing the solution is able to use them. In this case it is also possible that they will not closely examine the documentation and will not be able to precisely follow the instructions to ignore certain fields in the token. Therefore, it is desirable to design a security protocol in a manner that makes implementation mistakes less likely to occur.
 
@@ -96,7 +96,7 @@ The Web eID authentication token is a JSON data structure that looks like the fo
 
 It contains the following fields:
 
-- `unverifiedCertificate`: the base64-encoded DER-encoded authentication certificate of the eID user; the public key contained in this certificate should be used to verify the signature; the certificate cannot be trusted as it is received from client side and the client can submit a malicious certificate; to establish trust, it must be verified that the certificate is signed by a trusted certificate authority,
+- `unverifiedCertificate`: the base64-encoded DER-encoded authentication certificate of the eID user. The public key contained in this certificate should be used to verify the signature. The certificate cannot be trusted as it is received from client side and the client can submit a malicious certificate. To establish trust, it must be verified that the certificate is signed by a trusted certificate authority.
 
 - `algorithm`: the signature algorithm used to produce the signature; the allowed values are the algorithms specified in JWA RFC[^jwa] sections 3.3, 3.4 and 3.5:
 
@@ -106,15 +106,15 @@ It contains the following fields:
       "RS256", "RS384", "RS512"  // RSASSA-PKCS1-v1_5
     ```
 
-- `signature`: the base64-encoded signature of the token (see the description below),
+- `signature`: the base64-encoded signature of the token (see the description below).
 
-- `format`: the type identifier and version of the token format separated by a colon character '`:`', `web-eid:1.0` as of now; the version number consists of the major and minor number separated by a dot, major version changes are incompatible with previous versions, minor version changes are backwards-compatible within the given major version,
+- `format`: the type identifier and version of the token format separated by a colon character '`:`', `web-eid:1.0` as of now. The version number consists of the major and minor number separated by a dot, major version changes are incompatible with previous versions, minor version changes are backwards-compatible within the given major version.
 
-- `appVersion`: the URL identifying the name and version of the application that issued the token; informative purpose, can be used to identify the affected application in case of faulty tokens.
+- `appVersion`: the URL identifying the name and version of the application that issued the token. Informative purpose, can be used to identify the affected application in case of faulty tokens.
 
-The value that is signed by the user’s authentication private key and included in the `signature` field is `hash(origin)+hash(challenge)`. The hash function is used before concatenation to ensure field separation as the hash of a value is guaranteed to have a fixed length. Otherwise the origin `example.com` with challenge `.eu1234` and another origin `example.com.eu` with challenge `1234` would result in the same value after concatenation. The hash function `hash` is the same hash function that is used in the signature algorithm, for example SHA256 in case of RS256.
+The value that is signed by the user’s authentication private key and included in the `signature` field is `hash(origin)+hash(challenge nonce)`. The hash function is used before concatenation to ensure field separation as the hash of a value is guaranteed to have a fixed length. Otherwise the origin `example.com` with challenge nonce `.eu1234` and another origin `example.com.eu` with challenge nonce `1234` would result in the same value after concatenation. The hash function `hash` is the same hash function that is used in the signature algorithm, for example SHA256 in case of RS256.
 
-To verify the signature, the website has to reconstruct the signed data. Since the challenge value and the origin field are not included in the token in the proposed solution, the website is forced to reconstruct the signed data using the origin and challenge values from its trusted local storage. This provides an important security advantage as it is guaranteed that if the signature verification succeeds, then the origin and challenge have been implicitly and correctly verified without the need to implement any additional security checks. Furthermore, it also guarantees that the authentication proof was received from the same browser to which the corresponding challenge was issued, as the website is forced to lookup the challenge and, possibly, the origin, in case it can vary, from its local storage using an identifier specific to the browser session.
+To verify the signature, the website has to reconstruct the signed data. Since the challenge nonce value and the origin field are not included in the token in the proposed solution, the website is forced to reconstruct the signed data using the origin and challenge nonce values from its trusted local storage. This provides an important security advantage as it is guaranteed that if the signature verification succeeds, then the origin and challenge nonce have been implicitly and correctly verified without the need to implement any additional security checks. Furthermore, it also guarantees that the authentication proof was received from the same browser to which the corresponding challenge nonce was issued, as the website is forced to lookup the challenge nonce and, possibly, the origin, in case it can vary, from its local storage using an identifier specific to the browser session.
 
 [^foolproof]: So simple, plain, or reliable as to leave no opportunity for error, misuse, or failure.
 [^jwa]: <https://www.ietf.org/rfc/rfc7518.html>