├── .gitignore ├── README.md ├── diagrams ├── Man-in-the-middle-attack-broken.png ├── Man-in-the-middle-attack-fixed.png ├── Open-eID-web-authentication-components.png ├── Open-eID-web-signing-components.png ├── Web eID Component Model.eap ├── Web-eID-Component-Model.png ├── Web-eID-Safari-Extension-Component-Model.png ├── Web-eID-authentication-communication-diagram.png ├── Web-eID-full-overview.png ├── Web-eID-internals.png ├── Web-eID-signing-communication-diagram.png └── diagrams.net │ ├── Man-in-the-middle attack - broken.html │ ├── Man-in-the-middle attack - fixed with origin.html │ ├── Web eID authentication communication diagram.html │ ├── Web eID internal design.html │ └── Web eID signing communication diagram.html └── docs ├── .nojekyll ├── build.sh ├── index.html ├── web-eid-auth-token-v2-format-spec.md └── web-eid-auth-token-v2-format-spec.pdf /.gitignore: -------------------------------------------------------------------------------- 1 | *.ldb 2 | *.swp 3 | Thumbs.db* 4 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Web eID: electronic identity cards on the Web 2 | 3 | ## Table of Contents 4 | 5 | * [Introduction](#introduction) 6 | * [Use cases](#use-cases) 7 | * [Authentication](#authentication) 8 | * [Signing documents](#signing-documents) 9 | * [Web eID project websites](#web-eid-project-websites) 10 | * [Requirements notation and conventions](#requirements-notation-and-conventions) 11 | * [Glossary](#glossary) 12 | * [Design choices](#design-choices) 13 | * [Overview of the current Open eID implementation](#overview-of-the-current-open-eid-implementation) 14 | * [Problems of the current implementation](#problems-of-the-current-implementation) 15 | * [Principles of the new technical design](#principles-of-the-new-technical-design) 16 | * [Requirements for the new solution](#requirements-for-the-new-solution) 17 | * [Support for other security tokens besides smart cards](#support-for-other-security-tokens-besides-smart-cards) 18 | * [New solution architecture](#new-solution-architecture) 19 | * [Technical overview of authentication and digital signing](#technical-overview-of-authentication-and-digital-signing) 20 | * [Authentication](#authentication-1) 21 | * [Authentication and WebAuthn](#authentication-and-webauthn) 22 | * [Authenticated identity](#authenticated-identity) 23 | * [Authentication and TLS Token Binding](#authentication-and-tls-token-binding) 24 | * [Protection against man\-in\-the\-middle attacks during authentication with origin validation](#protection-against-man-in-the-middle-attacks-during-authentication-with-origin-validation) 25 | * [Digital signing](#digital-signing) 26 | * [The full overview](#the-full-overview) 27 | * [Security analysis](#security-analysis) 28 | * [JavaScript library](#javascript-library) 29 | * [Web eID authentication token specification](#web-eid-authentication-token-specification) 30 | * [Token format](#token-format) 31 | * [Requesting a Web eID authentication token](#requesting-a-web-eid-authentication-token) 32 | * [Browser extensions](#browser-extensions) 33 | * [Chrome, Edge and Firefox](#chrome-edge-and-firefox) 34 | * [Safari](#safari) 35 | * [Internet Explorer](#internet-explorer) 36 | * [Native application](#native-application) 37 | * [Native application messaging API](#native-application-messaging-api) 38 | * [General](#general) 39 | * [PKI operations](#pki-operations) 40 | * [libpcsc\-cpp: PC/SC library](#libpcsc-cpp-pcsc-library) 41 | * [libelectronic\-id: eID token library](#libelectronic-id-eid-token-library) 42 | * [Web eID authentication token validation libraries](#web-eid-authentication-token-validation-libraries) 43 | * [Implementation guide and example applications](#implementation-guide-and-example-applications) 44 | * [References](#references) 45 | 46 | ## Introduction 47 | 48 | The **Web eID** project enables usage of European Union electronic identity (eID) smart cards for secure authentication and digital signing of documents on the web using public-key cryptography. 49 | 50 | The project builds on the success of the [Estonian ID card](https://e-estonia.com/solutions/e-identity/) (EstEID) and the [Open Electronic Identity](https://github.com/open-eid) (Open eID) project that has been in operation since 2002. Most of Estonia's 1.3 million citizens have an ID card which provides digital access to all of Estonia’s secure e-services, releasing them from tedious red tape and making daily tasks faster and more comfortable while banking, signing documents, doing business or obtaining a digital medical prescription online. However, the Open eID implementation is facing certain technical challenges on the web browser platform due to its technical design that the Web eID project aims to overcome. 51 | 52 | The Web eID solution consists of a JavaScript library, browser extension and a native application that together coordinate communication between the browser, website and the smart card to perform cryptographic operations. 53 | 54 | The solution is cross-platform and works in all modern browsers in Windows, macOS and Linux. 55 | 56 | This document defines the functionality and technical design of the Web eID solution. 57 | 58 | ### Use cases 59 | 60 | The solution supports two main use cases – authentication and digital signing of documents. 61 | 62 | #### Authentication 63 | 64 | The user opens a website that requires authentication with an eID card, connects a card reader, inserts his/her smart card to the card reader and initiates signing in. The application asks the user for permission to send authentication certificate to the website and prompts to enter his/her authentication PIN. The user enters the authentication PIN and confirms. The website verifies the authentication data, notifies the user of successful login and displays the signed-in page. 65 | 66 | #### Signing documents 67 | 68 | The user opens a website that supports digital signing of documents, connects a card reader, inserts his/her smart card to the card reader and initiates digital signing. The application asks the user for permission to send digital signature certificate to the website and prompts to enter his/her digital signature PIN. The user enters the digital signature PIN and confirms. The website verifies the signature data, notifies the user of successful signing and displays the signed document. 69 | 70 | ### Web eID project websites 71 | 72 | The Web eID project website and authentication and digital signing test web application is available at https://web-eid.eu/. Links to Git repositories with the implementation of the Web eID components are available from the Web eID GitHub organization page https://github.com/web-eid and referenced below under corresponding components' sections. 73 | 74 | ### Requirements notation and conventions 75 | 76 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.txt). 77 | 78 | ### Glossary 79 | 80 | The following terms and abbreviations are used in this document: 81 | 82 | - **APDU**, *application protocol data unit*, the communication unit between a smart card reader and a smart card 83 | - **challenge nonce** (or challenge, or nonce), a cryptographic nonce, a large random number that can be used only once, with at least 256 bits of entropy 84 | - **CNG**, *Cryptography API: Next Generation*, the pluggable Windows Cryptography API introduced in Windows Vista 85 | - **CSRF**, *Cross-site request forgery*, a type of malicious exploit of a website where unauthorized commands are submitted from a user that the web application trusts 86 | - **CTK**, *CryptoTokenKit*, a framework for accessing security tokens and the cryptographic assets they store in macOS 87 | - **eID**, *electronic identification*, a digital solution for proof of identity of citizens or organizations 88 | - **OCSP**, *Online Certificate Status Protocol*, an internet protocol for obtaining the revocation status of a X.509 digital certificate 89 | - **OpenID Connect**, a simple identity layer on top of the OAuth 2.0 protocol 90 | - **origin**, the website origin, the URL serving the web application 91 | - **PC/SC**, *Personal Computer/Smart Card*, a specification for smart card integration into computing environments 92 | - **PKCS#11**, one of the *Public-Key Cryptography Standards*, defines a platform-independent API to cryptographic tokens, such as hardware security modules and smart cards 93 | - **TLS**, *Transport Layer Security*, a cryptographic protocol for secure Internet communication 94 | - **TLS CCA**, *TLS Client Certificate Authentication*, a TLS protocol variant where the client (browser) uses a certificate to authenticate itself during the TLS handshake 95 | - **TLS Token Binding**, a set of draft IETF RFC proposals for a TLS extension that aims to increase TLS security by using cryptographic certificates on both ends of the TLS connection 96 | - **TokenD**, a software module for bridging a cryptographic device (like a smart card) and the CryptoTokenKit (CTK) framework in macOS 97 | - **WebAuthn**, *Web Authentication*, an API enabling the creation and use of public key-based credentials by web applications, for the purpose of strongly authenticating users 98 | - **WebExtensions**, a new cross-browser system for developing browser extensions 99 | 100 | ## Design choices 101 | 102 | ### Overview of the current Open eID implementation 103 | 104 | The current Open eID implementation for using eID smart cards on the web is deeply integrated with the operating system cryptographic APIs and native browser APIs. It provides a driver for the Cryptography API: Next Generation (CNG) in Windows, CTK/TokenD plug-in in macOS and PKCS#11 driver in Linux for cryptographic operations with EstEID cards. Firefox uses PKCS#11 on all platforms. Authentication is implemented in the browser TLS session establishment layer with browser and operating system native components, using [TLS Client Certificate Authentication (CCA)](https://en.wikipedia.org/wiki/Transport_Layer_Security#Client-authenticated_TLS_handshake). 105 | 106 | The following diagrams provide an overview of Open eID web components. 107 | 108 | ![Open eID authentication components](diagrams/Open-eID-web-authentication-components.png) 109 | Figure 1: Open eID authentication components 110 | 111 | ![Open eID digital signing components](diagrams/Open-eID-web-signing-components.png) 112 | Figure 2: Open eID digital signing components 113 | 114 | The benefit of the deep integration is support for a wide range of use cases outside the web browser, e.g. secure login to the operating system with eID cards. However, there are significant downsides for the web browser platform due to that. 115 | 116 | ### Problems of the current implementation 117 | 118 | Due to the complexity of the solution, there have been numerous browser and operating system API stability issues throughout the years where users either cannot use their eID card with the web browser or have to restart the browser or the operating system to restore function. 119 | 120 | Here is the listing of the most prominent problems of the current implementation: 121 | 122 | - Dependence on complex, changing operating system and browser APIs creates fragility and high maintenance cost when the APIs change. 123 | - Different browsers use different cryptographic APIs in different operating systems (CNG, CTK/TokenD, PKCS#11). 124 | - Authentication and signing use different mechanisms that creates additional fragility – authentication may work but signing not, which is especially confusing and frustrating for users. 125 | - No authentication PIN prompts after first authentication until browser restart. Not asking for PIN is possible as the authentication security environment remains active on the eID smart card after first use. Without this authentication in TLS session establishment layer using TLS CCA would be infeasible as one would need to re-type the PIN for every browser request (including for media) – but not asking for authentication PIN creates security and usability problems. 126 | - Due to the previous issue, need to restart the browser after logout from sites with high security requirements. As the authentication security environment remains active on the card, logout in the browser has no effect (it is possible to login again without a PIN prompt). 127 | - Certificates are cached during login. When several people use the computer with their personal eID cards, their certificates [are cached](https://www.id.ee/en/article/removal-of-old-or-expired-certificates/) and later presented in the certificate selection dialog even if the card is not present. This is confusing and tedious for users as they either have to find their certificate from the list each time or manually remove unused certificates. 128 | - Inconsistent visuals. As web browsers use different cryptographic APIs, the eID middleware user interface visuals differ in web browsers. The visuals may also differ in the same browser during authentication and signing. 129 | 130 | ### Principles of the new technical design 131 | 132 | The new technical design aims to overcome the problems listed above. 133 | 134 | The principles of the new design are: 135 | 136 | - Focus on web use cases and the web browser platform. 137 | - Decoupling from the browser internals. Use [WebExtensions](https://wiki.mozilla.org/WebExtensions), a new cross-browser system for developing browser extensions, both for authentication and signing. 138 | - Decoupling from the operating system internals. Use the PC/SC API to communicate with eID cards directly. PC/SC API is user space, lower-level than the operating system cryptographic APIs, stable and cross-platform. Fall back to PKCS#11 only in case the specification of the PC/SC APDU protocol is not available for the given eID card. 139 | - Implement authentication according to the principles of the [Web Authentication API](https://www.w3.org/TR/webauthn/). Don't implement authentication in the browser TLS session establishment layer using TLS CCA. Special TLS CCA configuration is no longer required in the web servers which simplifies using eID cards in cloud services and clustered systems. 140 | - Require HTTPS and reject requests from non-secure contexts. 141 | - No need to restart the browser after logout as the PIN is prompted during each authentication. 142 | - Use the same mechanism for authentication and signing. 143 | - Use the same, consistent visuals for authentication and signing across browsers and operating systems. 144 | - Support most common European eID smart cards. 145 | 146 | The following diagram provides an overview of the Web eID solution components (in orange). The Safari Web Extension component model differs slightly, though not in principle, see the corresponding diagram in section *[Safari](#safari)* below. 147 | 148 | ![Web eID components](diagrams/Web-eID-Component-Model.png) 149 | Figure 3: Web eID components 150 | 151 | ## Requirements for the new solution 152 | 153 | Besides the principles listed above, the new solution satisfies the following requirements: 154 | 155 | 1. Support authentication and digital signing with Estonian, Latvian, Finnish (tier 1) and Croatian, Lithuanian (tier 2) eID smart cards in phase 1 and other EU eID cards in next phases. 156 | 1. Support recent versions of common operating systems, Windows, macOS, Linux, and evergreen browsers Chrome, Edge, Firefox, and Safari. 157 | 1. Support easy installation and immediate launch through the browser without requiring restart of the operating system and, if possible, browser after installation. Note that the Web eID native application needs to be installed separately from the browser extension. 158 | 1. For tier 1 supported eID cards, does not require any other third party software besides the operating system standard PC/SC stack and standard card reader driver. Tier 2 cards require the availability of a third-party PKCS#11 module and installation of the corresponding eID middleware. 159 | 1. Resilient, responsive, non-blocking, message driven internal design that supports unexpected events like card or reader removal or insertion during all operations. 160 | 1. Does not interfere with other eID software components in the browser or operating system. 161 | 1. Authentication success implies signing success unless the signing PIN is blocked. 162 | 163 | ### Support for other security tokens besides smart cards 164 | 165 | The solution is designed to be extensible so that it can support other security tokens that support public-key encryption besides smart cards, for example Yubikey. Thus in the following, the term "smart card" or "eID card" also refers to other security tokens that support public-key encryption. 166 | 167 | ## New solution architecture 168 | 169 | The following diagram provides an overview of the internal design of the new solution: 170 | 171 | ![Web eID internal design](diagrams/Web-eID-internals.png) 172 | Figure 4: Web eID internal design 173 | 174 | - JavaScript library `web-eid.js` is a thin wrapper on top of the messaging interface provided by the Web eID native application via the Web eID browser extension. 175 | - The Web eID browser extension is either a [WebExtensions](https://wiki.mozilla.org/WebExtensions) extension in browsers that support it (Chrome, Edge and Firefox) or a [Web Extension](https://developer.apple.com/documentation/safariservices/safari_web_extensions) in Safari for macOS. The Safari extension architecture is slightly different. See section *[Safari](#safari)* below for details. 176 | - The browser extension communicates with the Web eID native application installed on the host using native messaging. 177 | - The native application is built with Qt and consists of the application, controller and UI modules and uses the `libpcsc-cpp` and `libelectronic-id` libraries. 178 | - The controller module is a Qt library responsible for coordinating interaction between other components and the browser extension. Controller is event-based. Card event monitoring and communication with the eID card runs in separate threads from the main application thread. The controller module contains thread management classes and command handlers that perform PKI operations like signing and retrieving the certificate. 179 | - The UI module contains cross-platform Qt dialogs that the application uses to communicate with the user. 180 | - `libpcsc-cpp` is a pure C++ library for accessing smart cards using the PC/SC API. 181 | - `libelectronic-id` is a pure C++ library for performing cryptographic operations with eID smart cards that encapsulates the cards' APDU commands and manages communication with the smart card by using `libpcsc-cpp` services. It also supports using the PKCS#11 API in case the APDU commands are not available. 182 | - Electronic ID cards are divided into two tiers: 183 | - for tier 1 cards, the specification of the PC/SC APDU protocol is available and the PC/SC API is used to communicate with the cards directly; 184 | - for tier 2 cards, the specification of the PC/SC APDU protocol is *not* available and the PKCS#11 API is used to communicate with the card instead, which requires the availability of a third-party PKCS#11 module. 185 | 186 | ### Technical overview of authentication and digital signing 187 | 188 | The authentication and digital signing processes share a common scheme – the Web eID application signs a server-sent datagram with the private key on the smart card and sends the certificate and signature cryptogram back to the server. Server verifies if the certificate is valid and verifies the signature with the public key from the certificate. 189 | 190 | In the following sections, _JavaScript application_ is the website's client-side front end application in the browser that uses the `web-eid.js` library APIs to perform authentication and signing. 191 | 192 | _Server application_ is the website's server-side back end application. 193 | 194 | #### Authentication 195 | 196 | Authentication uses digital signing and is based on the same principles as TLS Client Certificate Authentication (CCA) and Web Authentication (WebAuthn): 197 | 198 | - server and client share a cryptographic nonce, a large random number that can be used only once, 199 | - client signs the nonce with the user's private authentication key and sends the signature together with the user's authentication certificate to the server, 200 | - server verifies the signature and certificate sent by the client to authenticate the user. 201 | 202 | Web eID authentication uses the same mechanism, but it is implemented in the application layer, not in the transport layer like TLS CCA. 203 | 204 | Authentication uses the authentication key and certificate of the eID smart cards, as most cards have separate keys for authentication and digital signing. 205 | 206 | Server retrieves user details from the subject field of the authentication certificate. 207 | 208 | ![Web eID authentication diagram](diagrams/Web-eID-authentication-communication-diagram.png) 209 | Figure 5: Web eID authentication diagram 210 | 211 | The authentication steps are as follows: 212 | 213 | 1. User initiates signing in. 214 | 1. **JavaScript application sends the initial authentication request to the server application**. JavaScript application sends the initial authentication challenge nonce request to the server application using `fetch()`. 215 | 1. **Server application responds with the challenge nonce**. The server application generates a cryptographic challenge nonce, a large random number that can be used only once, stores it in the nonce store along with the issuing time, base64-encodes it and returns it as the response. The challenge nonce must contain at least 256 bits of entropy. The browser extension and native application reject challenge nonces shorter than 44 bytes (length of base64-encoded 256 bits). 216 | 1. **JavaScript application initiates Web eID authentication**. The JavaScript application retrieves the challenge nonce from the response and calls the `web-eid.js` JavaScript library function `webeid.authenticate()`, passing the challenge nonce as parameter. `web-eid.js` sends the authentication initiation message along with the challenge nonce to the browser extension. 217 | The Web eID browser extension receives the message from `web-eid.js`, launches the Web eID native application and passes the challenge and document origin `location.origin` as arguments to the `authenticate` command. 218 | 1. **Web eID application asks consent and PIN from the user**. The Web eID application displays a dialog to the user with an input field for entering the authentication PIN and a message requesting consent to allow sending user's name and personal identification code to the server. User consent is required as the authentication certificate contains personal data. 219 | 1. **User enters the authentication PIN and gives consent**. 220 | 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. 221 | 1. **eID card responds with the authentication certificate**. The smart card responds with APDU responses containing the certificate bytes. 222 | 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. 223 | 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. 224 | 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. 225 | 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. 226 | 1. **JavaScript application sends the authentication token to the server application**. The JavaScript application posts the authentication token to the server application with a `fetch()` call. 227 | 1. **Server application validates the user certificate from the authentication token**. The server application extracts the user certificate from the authentication token and performs the following validation steps: 228 | 1. validates that the current time falls within the authentication certificate's validity period, 229 | 1. validates that the purpose of the authentication certificate's key usage is client authentication, 230 | 1. validates that the authentication certificate does not contain any disallowed policies, 231 | 1. validates that the authentication certificate is signed by a trusted certificate authority. 232 | 1. **Server application sends the authentication certificate revocation status request to the OCSP responder**. Server verifies the revocation status of the certificate embedded inside the authentication token with the [Online Certificate Status Protocol](https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol). 233 | 1. **OCSP responder responds that the certificate status is good**. 234 | 1. **Server application validates the authentication token signature and responds that the user is authenticated**. 235 | 1. The server application 236 | 1. validates the OCSP response, 237 | 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, 238 | 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, 239 | 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, 240 | 1. validates the subject of the authentication certificate. 241 | 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. 242 | 243 | The validation algorithm implementation needs to use a secure store for storing issued challenge nonces and their issuing time at server side. It must be guaranteed that the authentication token is received from the same browser to which the corresponding challenge nonce was issued, thus using a session-backed challenge nonce store is the most natural choice. During validation, the nonce received from the user will be looked up from the nonce store to assure it was previously issued by the server application. The nonce must be removed from the store during lookup to assure that it can be used only once to protect against replay attacks. The issuing time from the store must be used to validate that the challenge nonce hasn't expired. The recommended challenge nonce lifetime is 5 minutes. 244 | 245 | In addition, CSRF attacks must be mitigated with a standard CSRF protection mechanism when posting data to the server application. 246 | 247 | Web eID authentication token validation libraries that implement the validation algorithm are available for different programming languages, see section *[Authentication token validation libraries](#authentication-token-validation-libraries)* below. 248 | 249 | ##### Authentication and WebAuthn 250 | 251 | 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. 252 | 253 | 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. 254 | 255 | ##### Authenticated identity 256 | 257 | The server application can retrieve user details from the authentication certificate to access secure authenticated identity of an individual. The authenticity of the identity information is guaranteed via the state issued digital identity card and official public eID infrastructure. 258 | 259 | ##### Authentication and TLS Token Binding 260 | 261 | [Token Binding](https://en.wikipedia.org/wiki/Token_Binding) is a set of draft IETF RFC proposals for a TLS extension that aims to increase TLS security by using cryptographic certificates on both ends of the TLS connection. Bound tokens are established by the browser that generates a private-public key pair per target server, providing the public key to the server, and thereafter proving possession of the corresponding private key on every TLS connection to the server. 262 | 263 | 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. 264 | 265 | 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. 266 | 267 | 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. 268 | 269 | Thus, Token Binding support is not planned until it becomes more widely supported by browsers and proxy servers. 270 | 271 | ##### Protection against man-in-the-middle attacks during authentication with origin validation 272 | 273 | The security properties of the Web eID authentication subsystem are provided by ensuring that all authentication tokens are scoped to a particular origin, and cannot be replayed against a different origin, by incorporating the origin under the signature that is included in the token. Specifically, the full document origin [`location.origin`](https://developer.mozilla.org/en-US/docs/Web/API/Location) of the requester is included in the data that is signed. Since this is an integral part of the security model, the Web eID extension and native application only allow HTTPS origins. 274 | 275 | All Web eID application dialogs display the website origin so that the user can verify it before giving consent. 276 | 277 | Origin validation protects the authentication flow from man-in-the-middle and authentication token export and replay attacks. With origin validation, man-in-the-middle attacks cannot forward requests or replay the authentication token because they cannot forge the origin in the HTTPS context. To perform a man-in-the-middle attack, the attacker must use [DNS spoofing](https://en.wikipedia.org/wiki/DNS_spoofing) so that the origin host name is resolved to the attacker's server IP address and have a TLS certificate for the origin trusted by the user's browser installed in the server. The draft [Certificate Transparancy](https://en.wikipedia.org/wiki/Certificate_Transparency) standard may eventually eliminate misuse of TLS certificates by providing an open framework for monitoring and auditing TLS certificates in real time. 278 | 279 | ![Man-in-the-middle attack, broken](diagrams/Man-in-the-middle-attack-broken.png) 280 | ![Man-in-the-middle attack, fixed](diagrams/Man-in-the-middle-attack-fixed.png) 281 | Figure 6: Man-in-the-middle attack and mitigation with origin validation 282 | 283 | Figure 6.1 demonstrates how an attacker who deceives the user to visit a deceptive website that impersonates a legitimate website can gain unauthorized access to the legitimate website with user credentials by intercepting the authentication data, in case only the challenge nonce is signed over without including the origin. Figure 6.2 demonstrates how including origin under the signature helps to mitigate this attack. 284 | 285 | #### Digital signing 286 | 287 | The digital signature of a document is created by encrypting the document hash using the signing key on the eID smart card. The signature is usually embedded into a signature container. 288 | 289 | The Web eID digital signing subsystem and API is more similar to the existing Open eID design than the authentication subsystem, but it uses PC/SC for tier 1 eID cards. 290 | 291 | ![Web eID digital signing diagram](diagrams/Web-eID-signing-communication-diagram.png) 292 | Figure 7: Web eID digital signing diagram 293 | 294 | The digital signing steps are as follows: 295 | 296 | 1. User initiates digital signing of a document. 297 | 1. **JavaScript application calls `webeid.getSigningCertificate()`**. The JavaScript application calls the `web-eid.js` API method `getSigningCertificate()`. The Web eID browser extension internally launches the Web eID native application and sends it the `get-signing-certificate` command. 298 | 1. **Web eID application asks consent from the user**. The Web eID application displays a dialog to the user with a message requesting consent to allow sending user's name and personal identification code to the server. User consent is required as the signing certificate contains personal data. 299 | 1. **User gives consent**. 300 | 1. **Web eID application exchanges APDUs with the eID card to get the signing certificate**. The Web eID application uses the PC/SC API to send APDU commands to the eID card to select the signing certificate file and read its content. 301 | 1. **eID card responds with the signing certificate**. The smart card responds with APDU responses containing the certificate bytes. 302 | 1. **Web eID application returns the signing certificate and supported signature algorithms to the JavaScript application**. The Web eID application returns the signing certificate and the signature algorithms that the eID card supports to the Web eID browser extension. The extension returns them to the JavaScript application. 303 | 1. **JavaScript application sends the signing request to the server application with the signing certificate**. The JavaScript application sends the signing request to the server application with a `fetch()` call, passing the certificate and supported signature algorithms as arguments. 304 | 1. **Server application creates the digital signature container of the document and calculates the hash to be signed**. Server application creates the digital signature container compliant to ETSI TS 102 918 standard [Associated Signature Containers (ASiC)](http://www.etsi.org/deliver/etsi_ts/102900_102999/102918/01.03.01_60/ts_102918v010301p.pdf), possibly using the [DigiDoc4j](http://open-eid.github.io/digidoc4j/) library, adds the document as data file to the container and calculates the hash to be signed using a hash algorithm supported by the card. 305 | 1. **Server application returns the hash to be signed and the preferred hash function name to the JavaScript application**. 306 | 1. **JavaScript application calls `webeid.sign(certificate, hash, hashFunctionName)`**. The JavaScript application calls the `web-eid.js` API method `sign(certificate, hash, hashFunctionName)`, passing the signing certificate, the hash to be signed and hash function name received from the server as arguments. The Web eID JavaScript extension internally sends the `sign` command to the Web eID native application, forwarding the signing certificate, the hash and hash function name as arguments. 307 | 1. **Web eID application asks the user to input the signing PIN**. The Web eID application displays a dialog to the user with an input field for entering the signing PIN. 308 | 1. **User enters the signing PIN**. 309 | 1. **Web eID application exchanges APDUs with the eID card to sign the hash**. The Web eID application sends APDU commands to the smart card to select the signing security environment, verify the PIN and to sign the hash. 310 | 1. **eID card responds with the signature**. The eID card encrypts the hash with the signing private key on the card to create the signature, and responds with APDU responses containing the signature. 311 | 1. **Web eID application returns the signature and signature algorithm to the JavaScript application**. The Web eID application returns the signature and the signature algorithms that was used during signing to the Web eID browser extension. The extension returns them to the JavaScript application. 312 | 1. **JavaScript application sends the signature and signature algorithm to the server application**. The JavaScript application posts the signature and signature algorithm to the server application with a `fetch()` call. 313 | 1. **Server application adds the signature to the digital signature container and validates it**. 314 | 1. **Server application sends the signing certificate revocation status request to the OCSP service**. 315 | 1. **OCSP service responds that certificate status is good**. 316 | 1. **Server application responds that signing is successful**. 317 | 318 | ### The full overview 319 | 320 | The following diagram provides an overview of Web eID and related third party components across the server and user computer. 321 | 322 | ![Full overview of Web eID and related components](diagrams/Web-eID-full-overview.png) 323 | 324 | Figure 8: Full overview of Web eID and related components 325 | 326 | ### Security analysis 327 | 328 | Security analysis of the solution is available in the document ["Analysis of planned architectural changes in Open-eID"](https://web-eid.github.io/web-eid-cybernetica-analysis/webextensions-main.pdf). 329 | 330 | ### JavaScript library 331 | 332 | The `web-eid.js` JavaScript library is a thin wrapper on top of the messaging interface provided by the Web eID browser extension which in turn communicates with the Web eID application. 333 | 334 | It gives access to the Web eID solution features by providing an asynchronous, [`Promise`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise)-based interface and listening to incoming messages and turning them into resolved `Promises`. 335 | 336 | Design principles: 337 | 338 | - All calls are asynchronous in nature and return a `Promise`. 339 | - While asynchronous, the API is still sequential – only one call can be serviced by a smart card reader at a time. If a call can not be serviced because another call is underway, the promise shall be rejected. 340 | - The `code` property of a rejected promise (an [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)) contains a symbolic error code that can be handled in calling code. 341 | 342 | The full specification of the `web-eid.js` JavaScript library API and its source code is available in the `web-eid.js` [GitHub repository](https://github.com/web-eid/web-eid.js). 343 | 344 | ### Web eID authentication token specification 345 | 346 | Since there does not exist a standardized format of an authentication proof that fulfills the needs of the Web eID authentication protocol, we use a special purpose format for the Web eID authentication token. We intentionally avoid using the JWT format, but still use its proven basic building blocks: the JSON format and base64-encoding. 347 | 348 | The OpenID Connect ID Token JWT format was initially considered, but it was found that any similarities of the Web eID authentication token to the JWT format are actually undesirable, as they would imply that the claims presented in the Web eID authentication token can be trusted and processed, while actually they cannot be trusted as the token is created in the user's untrusted environment. The solutions are fundamentally different – the purpose of OpenID Connect (and JWT in general) is to exchange identity claims that are signed by a trusted party (usually an authentication server), while the purpose of the Web eID authentication token is to prove that the user is able to create signatures with the private key that corresponds to the presented certificate. 349 | 350 | The in-depth rationale of the Web eID authentication token format design is available in a separate [specification document](https://web-eid.github.io/web-eid-system-architecture-doc/web-eid-auth-token-v2-format-spec.pdf). 351 | 352 | #### Token format 353 | 354 | The Web eID authentication token is a JSON data structure that looks like the following example: 355 | 356 | ```json 357 | { 358 | "unverifiedCertificate": "MIIFozCCA4ugAwIBAgIQHFpdK-zCQsFW4...", 359 | "algorithm": "RS256", 360 | "signature": "HBjNXIaUskXbfhzYQHvwjKDUWfNu4yxXZha...", 361 | "format": "web-eid:1.0", 362 | "appVersion": "https://web-eid.eu/web-eid-app/releases/v2.0.0" 363 | } 364 | ``` 365 | 366 | It contains the following fields: 367 | 368 | - `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. 369 | 370 | - `algorithm`: the signature algorithm used to produce the signature. The allowed values are the algorithms specified in [JWA RFC](https://www.ietf.org/rfc/rfc7518.html) sections 3.3, 3.4 and 3.5: 371 | 372 | ``` 373 | "ES256", "ES384", "ES512", // ECDSA 374 | "PS256", "PS384", "PS512", // RSASSA-PSS 375 | "RS256", "RS384", "RS512" // RSASSA-PKCS1-v1_5 376 | ``` 377 | 378 | The algorithm field value depends on the capabilities of the eID card. 379 | 380 | - `signature`: the base64-encoded signature of the token (see the signature description below). 381 | 382 | - `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. 383 | 384 | - `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. 385 | 386 | 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. 387 | 388 | The `origin` value that is signed over must contain the URL of the website origin, i.e. the URL serving the web application. `origin` URL must be in the form of ` "://" [ ":" ]` as defined in [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Location/origin), where `scheme` must be `https`. Note that the `origin` URL must not end with a slash `/`. 389 | 390 | #### Requesting a Web eID authentication token 391 | 392 | The Web eID authentication token is returned from the following `web-eid.js` JavaScript API call: 393 | 394 | ```js 395 | const authToken = await webeid.authenticate('NONCEVALUE'); 396 | ``` 397 | 398 | * The challenge nonce must be generated by the back end application and must contain at least 256 bits of entropy. 399 | * The consuming back end application must assure that the authentication token is received from the same browser to which the corresponding challenge nonce was issued. 400 | * The browser extension and native application reject challenge nonces shorter than 44 bytes (length of base64-encoded 256 bits of entropy). 401 | * The browser extension rejects origins that are not secure. 402 | * The session and expiry management used for the nonce in the consuming backend application must conform to the recommendations of the [OWASP Session Management Cheat Sheet](https://www.owasp.org/index.php/Session_Management_Cheat_Sheet). 403 | 404 | The full specification of the `web-eid.js` JavaScript library API and its source code is available in the `web-eid.js` [GitHub repository](https://github.com/web-eid/web-eid.js). 405 | 406 | ### Browser extensions 407 | 408 | #### Chrome, Edge and Firefox 409 | 410 | The Web eID extension for Chrome, Edge and Firefox is built using the [WebExtensions API](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions), a cross-browser system for developing extensions. It is created using web technologies – HTML, CSS, and JavaScript and can take advantage of the same web APIs as JavaScript on a web page, but extensions also have access to their own set of JavaScript APIs. 411 | 412 | The goal of the WebExtensions standard is to make browser extension code much more interoperable across browsers by specifying common extension interfaces and well-defined browser behavior. This will allow extension authors to greatly reduce or eliminate the rework necessary to create extensions that target different browsers. 413 | 414 | The extension communicates with the Web eID native application using [Native messaging](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging). Native messaging enables an extension to exchange messages with a native application installed on the user's computer to enable the extension to access resources that are not accessible through WebExtension APIs, like the PC/SC subsystem in case of Web eID. Messages are exchanged with the native application via standard input-output streams. 415 | 416 | The native application is not installed or managed by the browser, it is installed using the underlying operating system's installation facilities. 417 | 418 | More information about the Web eID browser extension and its source code is available in the extension [GitHub repository](https://github.com/web-eid/web-eid-webextension). 419 | 420 | #### Safari 421 | 422 | The Web eID extension for Safari for macOS is built as a [Safari Web Extension](https://developer.apple.com/documentation/safariservices/safari_web_extensions). 423 | 424 | Safari Web Extensions are similar to WebExtensions extensions that communicate with a native application, except that the native application is bundled with the extension. The extension can use a combination of JavaScript, CSS, and native code written in Objective-C or Swift. As extensions are built on the standard macOS app model, they are bundled inside an app and distributed through the App Store. 425 | 426 | The injected script, the Safari Web Extension and the extension's native app live in different sandboxed environments, each with specific limits on what it can access. Like with WebExtensions, communication between the injected script and the web extension happens with message passing. The two runtime environments share a common format for message passing, and each provides an interface for sending and receiving messages. 427 | 428 | However, Apple does not provide a dedicated two-way communication channel between the extension and the extension's native app. Therefore a combination of [`NSNotificationCenter`](https://developer.apple.com/documentation/foundation/NSNotificationCenter) and [`NSUserDefaults`](https://developer.apple.com/documentation/foundation/nsuserdefaults) is used for sending and receiving messages between the extension and the extension's native app. 429 | 430 | The source code of the Safari extension is available in the [`mac` subdirectory of the `web-eid-app` GitHub repository](https://github.com/web-eid/web-eid-app/tree/main/src/mac). 431 | 432 | Besides the JavaScript-based extension, there is the additional app extension's native component in `safari-extension.mm` that coordinates launching the app and exchanging messages with it. 433 | 434 | The extension's native app in `main.mm` is a thin adapter layer on top of the Qt-based Web eID native app libraries and calls the Web eID app API functions directly from Objective-C code. It also manages message exchange with the app extension. 435 | 436 | The following diagram provides an overview of the Web eID general and Safari extension-specific components (in orange). 437 | 438 | ![Web eID Safari extension components](diagrams/Web-eID-Safari-Extension-Component-Model.png) 439 | 440 | Figure 9: Web eID general and Safari extension-specific components 441 | 442 | #### Internet Explorer 443 | 444 | As Microsoft has [announced](https://blogs.windows.com/windowsexperience/2021/05/19/the-future-of-internet-explorer-on-windows-10-is-in-microsoft-edge/) that the Internet Explorer 11 desktop application will be retired on June 15, 2022, there is no support for Internet Explorer in Web eID. 445 | 446 | ### Native application 447 | 448 | The Web eID native application is built with the [Qt](https://www.qt.io/) framework. It consists of 449 | 450 | - the Qt application bootstrapping code that starts the Qt event loop, 451 | - a controller component that is responsible for creating other component objects and coordinating communication between them and the user, 452 | - command handlers that implement the actual PKI operations (authenticate, get signing certificate, sign) using the `libelectronic-id` library, 453 | - thread management code, including the card reader and smart card event monitoring thread, 454 | - a dynamic user interface dialog built with Qt Widgets. 455 | 456 | The controller has an event-driven internal design that supports unexpected events like card or reader removal or insertion during all operations. Communication with the smart card and card monitoring run in separate threads to assure responsive, non-blocking operations. 457 | 458 | The lifetime of the native application is managed by the Web eID browser extension, for example when Native messaging is used, then the application is launched when the extension calls `runtime.connectNative()`, and stopped with the `Port.disconnect()` call or when the `Port` object is garbage collected (e.g. during page reload). 459 | 460 | The native application is not installed or managed by the browser, it is installed using the underlying operating system's installation facilities. 461 | 462 | More information about the Web eID native application, its source code and the full specification of the messaging API is available in the `web-eid-app` [GitHub repository](https://github.com/web-eid/web-eid-app). 463 | 464 | #### Native application messaging API 465 | 466 | Messaging API describes the application level messaging protocol between the Web eID browser extension and the native application. 467 | 468 | ##### General 469 | 470 | - Messaging API works in request-response pairs over `stdin`/`stdout` when using WebExtension Native messaging. Safari extension invokes the Web eID app API functions directly. 471 | - Each request must send a single JSON object, the command, one of `"authenticate"`, `"get-signing-certificate"` or `"sign"`, and its arguments. 472 | - For security reasons, authentication certificate can only be accessed through the `"authenticate"` command and there is no support for signing of raw hash values with the authentication key. 473 | - All commands require the mandatory `origin` field in arguments. 474 | - All commands support an optional `lang` field in arguments that, if provided, must contain a two-letter ISO 639-1 language code. If translations exist for the given language, then the user interface will be displayed in this language. 475 | - The response is a single JSON object. 476 | - Presence of the `error` field in a response indicates error. Additional information about the error is in the `code` and `message` fields of the error JSON object. 477 | - When starting, the application sends an initial `version` message to `stdout` and starts listening for a command from `stdin`. 478 | - When the command has been completed successfully or an error occurs and the response has been sent to `stdout`, the native application exits. 479 | - All binary fields are base64-encoded. 480 | - Incorrect requests are rejected with an error. 481 | - Messages must not exceed 8 KiB (8192 bytes). 482 | 483 | ##### PKI operations 484 | 485 | Messaging API supports the following PKI operations. The mandatory `origin` field and optional `lang` field have been omitted from arguments for brevity. 486 | 487 | - Authenticate: 488 | - request: `{"command": "authenticate", "arguments": {"challengeNonce": "base64"}}` 489 | - response (Web eID authentication token): `{"unverifiedCertificate": "base64", "algorithm": "string", "signature": "base64", "format": "string", "appVersion": "URL"}`. 490 | 491 | - Get signing certificate: 492 | - request: `{"command": "get-signing-certificate", "arguments": {}}` 493 | - response: `{"certificate": "base64", "supportedSignatureAlgorithms" : [{"cryptoAlgorithm": "string", "hashFunction": "string", "paddingScheme": "string"}]}`. 494 | 495 | - Sign: 496 | - request: `{"command": "sign", "arguments": {"certificate": "base64", "hash": "base64", "hashFunction": "string"}}` 497 | - response: `{"signature": "base64", "signatureAlgorithm": {"cryptoAlgorithm": "string", "hashFunction": "string", "paddingScheme": "string"}}`. 498 | 499 | 500 | ### libpcsc-cpp: PC/SC library 501 | 502 | `libpcsc-cpp` is a C++ library for communicating with smart cards using the PC/SC API. 503 | 504 | Microsoft implemented PC/SC in Microsoft Windows 2000/XP and free implementation of PC/SC, PC/SC Lite, is available for Linux and other Unixes; a forked version comes bundled with macOS. The PC/SC API interface has been stable for more than twenty years and is the foundation of all the higher-level operating system smart card cryptographic APIs that Open eID currently uses. 505 | 506 | More information about `libpcsc-cpp` and its source code is available in the `libpcsc-cpp` [GitHub repository](https://github.com/web-eid/libpcsc-cpp). 507 | 508 | ### libelectronic-id: eID token library 509 | 510 | `libelectronic-id` is a C++ library for performing cryptographic operations with eID smart cards that encapsulates the APDU command protocol of tier 1 cards and manages communication with the smart card by using `libpcsc-cpp` services. It also supports using the PKCS#11 API with tier 2 cards for which the APDU command protocol is not available. 511 | 512 | The APDU commands for each eID card are embedded inside the library. Therefore, to support a new eID card, implementers need access to the APDU protocol of the card. As tier 1 cards do not rely on external frameworks like PKCS#11, support for new cards can be added immediately without waiting for external release cycles. 513 | 514 | More information about `libelectronic-id` and its source code is available in the `libelectronic-id` [GitHub repository](https://github.com/web-eid/libelectronic-id). 515 | 516 | ### Web eID authentication token validation libraries 517 | 518 | The Web eID project provides official reference implementations of the Web eID authentication token validation algorithm for Java and .NET. The reference implementations also include secure challenge nonce generation as required by the Web eID authentication protocol. The reference implementations are distributed as libraries to make them easy to integrate into applications that intend to use Web eID authentication. 519 | 520 | Java applications can use the `web-eid-authtoken-validation-java` library. The full specification of the library API and its source code is available in the `web-eid-authtoken-validation-java` [GitHub repository](https://github.com/web-eid/web-eid-authtoken-validation-java). 521 | 522 | .NET applications can use the `web-eid-authtoken-validation-dotnet` library. The full specification of the library API and its source code is available in the `web-eid-authtoken-validation-dotnet` [GitHub repository](https://github.com/web-eid/web-eid-authtoken-validation-dotnet). 523 | 524 | A C++ implementation of the Web eID authentication token validation algorithm is planned with [SWIG](http://www.swig.org/) bindings for Go, Node.js, PHP, Python and Ruby. 525 | 526 | ### Implementation guide and example applications 527 | 528 | To implement authentication and digital signing with Web eID in a Java or .NET web application, 529 | 530 | - in the front end of the web application, use the *web-eid.js* JavaScript library according to the instructions [here](https://github.com/web-eid/web-eid.js#quickstart), 531 | - in the back end of a Java web application, 532 | - for authentication, use the *web-eid-authtoken-validation-java* Java library according to instructions [here](https://github.com/web-eid/web-eid-authtoken-validation-java#quickstart), 533 | - for digital signing, use the *digidoc4j* Java library according to instructions [here](https://github.com/open-eid/digidoc4j/wiki/Examples-of-using-it), 534 | - in the back end of a .NET web application, 535 | - for authentication, use the *web-eid-authtoken-validation-dotnet* .NET library according to instructions [here](https://github.com/web-eid/web-eid-authtoken-validation-dotnet#quickstart), 536 | - for digital signing, use the C# bindings of the `libdigidocpp` library according to instructions [here](https://github.com/web-eid/web-eid-asp-dotnet-example/wiki/How-to-implement-digital-signing-in-a-.NET-web-application-back-end). 537 | 538 | The full source code and overview of an example Spring Boot web application that uses Web eID for authentication and digital signing is available [here](https://github.com/web-eid/web-eid-spring-boot-example). The .NET/C# version of the same example is available [here](https://github.com/web-eid/web-eid-asp-dotnet-example). 539 | 540 | ## References 541 | 542 | 1. ["Estonian ID card (EstEID)"](https://e-estonia.com/solutions/e-identity/), *E-Estonia* 543 | 1. ["Open Electronic Identity (Open eID)"](https://github.com/open-eid), *Open eID GitHub project* 544 | 1. The Web eID project GitHub organization page, https://github.com/web-eid 545 | 1. The Web eID project website and authentication and digital signing test web application, https://web-eid.eu/ 546 | 1. ["Key words for use in RFCs to Indicate Requirement Levels (RFC 2119)"](https://www.rfc-editor.org/rfc/rfc2119.txt), *IETF RFC document* 547 | 1. ["Client-authenticated TLS handshake"](https://en.wikipedia.org/wiki/Transport_Layer_Security#Client-authenticated_TLS_handshake), *Wikipedia*, provides overview of TLS Client Certificate Authentication (CCA) 548 | 1. ["Mobile-ID"](https://e-estonia.com/solutions/e-identity/mobile-id/), *E-estonia* 549 | 1. ["Smart-ID"](https://e-estonia.com/solutions/e-identity/smart-id), *E-estonia* 550 | 1. ["WebExtensions"](https://wiki.mozilla.org/WebExtensions), *MozillaWiki* 551 | 1. ["Safari Web Extensions"](https://developer.apple.com/documentation/safariservices/safari_web_extensions), *Apple Devloper Documentation* 552 | 1. ["Native Messaging"](https://developer.chrome.com/extensions/nativeMessaging#native-messaging-host-protocol), *Google Chrome browser extension developer guide* 553 | 1. ["Web Authentication (WebAuthn)"](https://www.w3.org/TR/webauthn-2/), *W3C Recommendation* 554 | 1. ["Online Certificate Status Protocol (OCSP)"](https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol), *Wikipedia* 555 | 1. ["HTTPS Token Binding with TLS Terminating Reverse Proxies"](https://tools.ietf.org/html/draft-ietf-tokbind-ttrp-07), *IETF draft proposal* 556 | 1. ["Associated Signature Containers (ASiC)"](http://www.etsi.org/deliver/etsi_ts/102900_102999/102918/01.03.01_60/ts_102918v010301p.pdf), *ETSI TS 102 918 standard* 557 | 1. ["DigiDoc4j"](http://open-eid.github.io/digidoc4j/), *DigiDoc4j project documentation* 558 | 1. ["Analysis of planned architectural changes in Open-eID"](https://web-eid.github.io/web-eid-cybernetica-analysis/webextensions-main.pdf), *Estonian Information System Authority and Cybernetica AS* 559 | 1. ["OWASP Session Management Cheat Sheet"](https://www.owasp.org/index.php/Session_Management_Cheat_Sheet) 560 | 1. ["The future of Internet Explorer on Windows 10 is in Microsoft Edge"](https://blogs.windows.com/windowsexperience/2021/05/19/the-future-of-internet-explorer-on-windows-10-is-in-microsoft-edge/), *Windows Experience Blog* 561 | 562 | -------------------------------------------------------------------------------- /diagrams/Man-in-the-middle-attack-broken.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/diagrams/Man-in-the-middle-attack-broken.png -------------------------------------------------------------------------------- /diagrams/Man-in-the-middle-attack-fixed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/diagrams/Man-in-the-middle-attack-fixed.png -------------------------------------------------------------------------------- /diagrams/Open-eID-web-authentication-components.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/diagrams/Open-eID-web-authentication-components.png -------------------------------------------------------------------------------- /diagrams/Open-eID-web-signing-components.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/diagrams/Open-eID-web-signing-components.png -------------------------------------------------------------------------------- /diagrams/Web eID Component Model.eap: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/diagrams/Web eID Component Model.eap -------------------------------------------------------------------------------- /diagrams/Web-eID-Component-Model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/diagrams/Web-eID-Component-Model.png -------------------------------------------------------------------------------- /diagrams/Web-eID-Safari-Extension-Component-Model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/diagrams/Web-eID-Safari-Extension-Component-Model.png -------------------------------------------------------------------------------- /diagrams/Web-eID-authentication-communication-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/diagrams/Web-eID-authentication-communication-diagram.png -------------------------------------------------------------------------------- /diagrams/Web-eID-full-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/diagrams/Web-eID-full-overview.png -------------------------------------------------------------------------------- /diagrams/Web-eID-internals.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/diagrams/Web-eID-internals.png -------------------------------------------------------------------------------- /diagrams/Web-eID-signing-communication-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/diagrams/Web-eID-signing-communication-diagram.png -------------------------------------------------------------------------------- /diagrams/diagrams.net/Man-in-the-middle attack - broken.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | diagrams.net 5 | 6 | 7 | 8 | 9 |
10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /diagrams/diagrams.net/Man-in-the-middle attack - fixed with origin.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | diagrams.net 5 | 6 | 7 | 8 | 9 |
10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /diagrams/diagrams.net/Web eID authentication communication diagram.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | diagrams.net 5 | 6 | 7 | 8 | 9 |
10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /diagrams/diagrams.net/Web eID internal design.html: -------------------------------------------------------------------------------- 1 | 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 -------------------------------------------------------------------------------- /diagrams/diagrams.net/Web eID signing communication diagram.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Draw.io Diagram 5 | 6 | 7 | 8 | 9 |
10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /docs/.nojekyll: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/docs/.nojekyll -------------------------------------------------------------------------------- /docs/build.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | set -eu 4 | 5 | DATE_STR=$(LANG='en_US' date '+%B %e, %Y') 6 | 7 | sed -i "s/<>/${DATE_STR}/" *.md 8 | 9 | for f in *.md 10 | do 11 | pandoc $f -s -o "${1}/${f/%.md/.pdf}" --number-sections 12 | done 13 | -------------------------------------------------------------------------------- /docs/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 |

PDF of "Web eID authentication token format specification"

4 | 5 | 6 | -------------------------------------------------------------------------------- /docs/web-eid-auth-token-v2-format-spec.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Web eID authentication token format specification 3 | author: 4 | - Mart Sõmermaa, Estonian Information System Authority 5 | date: <> 6 | --- 7 | 8 | # Introduction 9 | 10 | 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. 11 | 12 | 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. 13 | 14 | In this paper, we provide an overview of the weaknesses, and the specification of the new Web eID authentication token format used in Web eID version 2 that mitigates the weaknesses. 15 | 16 | The paper is based on Arnis Paršovs paper _On the format of the authentication proof used by RIA’s Web eID solution_[^parsovs]. 17 | 18 | [^webeid]: 19 | [^openidx5idtoken]: 20 | [^parsovs]: 21 | 22 | 23 | # The Web eID authentication token format 24 | 25 | The authentication token format used in Web eID version 1 is based on the OpenID Connect ID Token[^openidconnectidtoken] specification. All fields required in the OpenID Connect specification are present, including `iat`, `exp`, `iss` and `sub` that are ignored by the Web eID authentication protocol. 26 | 27 | \newpage 28 | 29 | **Example token**: 30 | 31 | `Header:` 32 | 33 | ```json 34 | { 35 | "typ": "JWT", 36 | "alg": "RS256", 37 | "x5c": ["MIIFozCCA4ugAwIBAgIQHFpdK-zCQsFW4..."] 38 | } 39 | ``` 40 | 41 | `Payload:` 42 | 43 | ```json 44 | { 45 | "aud": ["https://ria.ee"], 46 | "exp": "1479621923", 47 | "iat": "1479621900", 48 | "iss": "web-eid app v1.0.0", 49 | "sub": "John Doe", 50 | "nonce": "NONCEVALUE" 51 | } 52 | ``` 53 | 54 | `Signature:` ... 55 | 56 | The header part contains a JSON structure that contains the `alg` field which identifies the cryptographic algorithm used to create the signature and the `x5c` field which contains the user’s authentication certificate. The payload part contains a JSON structure depicted above and is signed together with the header using the user’s authentication key. The signature part carries the value of the user’s signature. 57 | 58 | [^openidconnectidtoken]: 59 | 60 | ## Weaknesses of the OpenID X509 ID Token format 61 | 62 | 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. 63 | 64 | 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. 65 | 66 | 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). 67 | 68 | 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. 69 | 70 | ## Reasoning behind the OpenID X509 ID Token format 71 | 72 | As mentioned above, the redundant fields `exp`, `iat`, `iss` and `sub` have been included in the JWT authentication token to support compatibility with the OpenID Connect ID Token specification. The security analysis of the Web eID solution further adds that the use of the OpenID Connect format offers a cheaper migration path, as the format is already known for e-service developers[^webeidanalysis]. 73 | 74 | We note that this reasoning is flawed because it is not possible to achieve compatibility and integration between two conceptually different solutions just by making the data exchange format used by the solutions look the same. The purpose of OpenID Connect (and JWT in general) is to exchange identity claims that are signed by a trusted party (usually an authentication server), while the purpose of the Web eID authentication token is to prove that the user is able to create signatures with the private key that 75 | corresponds to the presented certificate. 76 | 77 | We argue that any similarities of the Web eID authentication token to the JWT format are actually undesirable, as they would imply that the claims presented in the Web eID authentication token can be trusted and processed, while actually they must be ignored. For the same reason the use of the current format of the authentication token cannot provide a cheaper migration path, because the same codebase or workflow that is applied to any other JWT must not be applied to the Web eID authentication token, to not introduce security vulnerabilities or other unintended behavior. 78 | 79 | [^webeidanalysis]: , section 3.1. 80 | 81 | ## Proposed new format for the Web eID authentication token 82 | 83 | Since to our knowledge there does not exist a standardized format for an authentication proof that implements nothing less and nothing more than is necessary for the Web eID authentication protocol, we propose to use a simple and foolproof[^foolproof] special purpose format for the Web eID authentication token. The new format is used in Web eID version 2. We intentionally avoid using the JWT format, but still use its proven basic building blocks: the JSON format and base64-encoding. 84 | 85 | The Web eID authentication token is a JSON data structure that looks like the following example: 86 | 87 | ```json 88 | { 89 | "unverifiedCertificate": "MIIFozCCA4ugAwIBAgIQHFpdK-zCQsFW4...", 90 | "algorithm": "RS256", 91 | "signature": "HBjNXIaUskXbfhzYQHvwjKDUWfNu4yxXZha...", 92 | "format": "web-eid:1.0", 93 | "appVersion": "https://web-eid.eu/web-eid-app/releases/v2.0.0" 94 | } 95 | ``` 96 | 97 | It contains the following fields: 98 | 99 | - `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, 100 | 101 | - `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: 102 | 103 | ``` 104 | "ES256", "ES384", "ES512", // ECDSA 105 | "PS256", "PS384", "PS512", // RSASSA-PSS 106 | "RS256", "RS384", "RS512" // RSASSA-PKCS1-v1_5 107 | ``` 108 | 109 | - `signature`: the base64-encoded signature of the token (see the description below), 110 | 111 | - `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, 112 | 113 | - `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. 114 | 115 | 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. 116 | 117 | 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. 118 | 119 | [^foolproof]: So simple, plain, or reliable as to leave no opportunity for error, misuse, or failure. 120 | [^jwa]: 121 | -------------------------------------------------------------------------------- /docs/web-eid-auth-token-v2-format-spec.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/web-eid/web-eid-system-architecture-doc/86b51cf7d14d3fc5c7b31d58c86d025e9118099a/docs/web-eid-auth-token-v2-format-spec.pdf --------------------------------------------------------------------------------