fijimunkii / security-key

iOS SEP U2F

iOS Security Key

This app provides a iOS Safari extension, which implements the FIDO U2F protocol. The cryptographic keys used for authentication are generated and stored on the Secure Enclave Processor (SEP), requiring user interaction for signing operations.

Setup

After installing the app, you'll need to enable the extension

Open Safari

Click the "share" button

Scroll to the right and click the "more" button

Ensure "Security Key" is enabled

Protocol and implementaion details

FIDO U2F

FIDO U2F is a cryptographic protocol for second factor authentication. In addition to registering a username and password with a website, you also register a "security key". This key may be a hardware device like a USB dongle, or a software application on your device. When authenticating with the website, you provide your username and password, and are then prompted to interact with your security key. At this point the key strongly authenticates you by digitally signing a challenge from the website. The signature is sent to the website, which can verify its authenticity and finish authenticating your session.

Your web browser needs to facilitate the communication between the website you are authenticating with and your security key. Currently, only the Chrome and Opera browsers implement this protocol — FIDO U2F. This application adds an extension to the Safari browser on your iOS device, implementing FIDO U2F.

Secure Enclave Processor (SEP)

A desirable characteristic of security keys is that they securely store the keys used for creating digital signatures. For example, USB security keys generate a new set of keys for each website you want to authenticate with. These keys are stored on the USB device and are impossible to extract. Even if malware is installed on your computer, your USB key can never be cloned. USB keys also require interaction, such as pressing a physical button, before they will use their stored keys for creating a signature. This provides a strong assurance for websites that it is actually you who is authenticating.

Modern iOS devices have a special chip called the Secure Enclave Processor (SEP). This chip is responsible for cryptographic operations, such as generating keys and signing and encrypting messages. The SEP allows apps to generate sets of keys, such as those stored on USB security keys, specifying that they may never be exported. Additionally, the app may specify that in order for these keys to be used for signing, the user must biometrically verify her presence using Touch ID.

iOS Action Extension limitations

The iOS platform allows developers to create "Action Extensions", which are available to users while browsing the web. These extensions can include JavaScript, which runs in a separate sandbox from the website's JavaScript. This separation means that extensions cannot directly define JavaScript API's, like the U2F API¹ — window.u2f.

An added difficulty is that communications between the native and JavaScript components of the extension are limited. When the user invokes the extension, a JavaScript files is loaded. This file defines run and finalize functions. The run function is called and given a callback which allows the JavaScript to send data to the native side of the extension. When the native side is done, it calls the finalize function, passing any necessary data back to the JavaScript. This restrictive model of communication means that only one chance is given to pass information in either direction.

To facilitate the U2F protocol, this extension needs to allow the website to communicate with the extension. Of the available options, the best approach was to achieve this communication via DOM events. The website must include a JavaScript polyfill that defines the window.u2f API and sends registration and signing requests to the extension.

¹ The extension could inject a <script> tag, allowing it to run JavaScript outside of its sandbox, but this pattern is frustrating to web developers and interferes with security features like Content Security Policy.

window.u2f polyfill

The polyfill can be found here