This document describes the architecture of WebSign, Cyph’s proprietary “secure web application” technology. WebSign was originally presented during our talks at Black Hat 2016 and DEF CON 24 (deck, video), and is now protected by US Patent 9,906,369.

Overview

A core technique involved is what we refer to as “HPKP Suicide”, an abuse¹ of a web security standard called HTTP Public Key Pinning that essentially lets us “trick” the browser into behaving as though a server is persistently offline after its first interaction with that server.

General summary of HPKP Suicide’s steps (and the talk goes into more detail if needed):

1. Server generates TLS key pair and stores it on a volatile RAM filesystem (e.g. tmpfs).
2. Server requests a new TLS certificate for that key pair from a certificate authority or requests to rekey its existing certificate.
3. After obtaining the new cert, server updates its web server configuration to include an HPKP header with a hash matching the new public key.
4. Server starts serving with the new config/cert/key.
5. Server waits for as small an interval as possible before proceeding to the next step. (e.g. Let’s Encrypt’s rate limit makes an 8.4-hour interval possible, and DigiCert is allowing us a 12-hour interval.)
6. Server destroys its current TLS key pair (making it practically unrecoverable due to it having been stored only in RAM during its lifetime).
7. Server goes back to step #1.

After each iteration of these steps, any HPKP-supporting browsers that had hit the server at any point during the interval from step #5 will now treat the server as though it’s literally offline (AJAX requests will fail, attempts to navigate to the server’s hostname will bump into an unskippable error page, etc.) — which the server will have no power to undo without access to the private key it deleted in step #6. In other words, we’ve now (approximately) achieved the needed TOFU property.

With this, we can now pin whatever logic we’d like using a web standard that facilitates offline web applications (often used for games that don’t depend on access to a backend API 100% of the time): AppCache (and/or its successor, ServiceWorker). Because the server is pseudo-offline, the browser will always fall back to the logic contained within the AppCache cache rather than pull untrusted code from the server.

In the case of WebSign, we take advantage of this to pin our code signing framework within the browser. Here’s a high-level overview of how these pieces all fit together:

Code Signing

Specific mechanics of our code signing implementation are as follows.

Package generation/signing components:

• Build environment (machine where code is compiled and deployments are initiated).
• Air Gapped Signing Environment (air gapped microcontroller, on which SPHINCS and RSA release signing keys were generated and continue to be stored — functionally similar to an HSM):
  
  

Package generation/signing steps:

1. Build environment swaps out all subresource references in application’s index.html with markup similar to SRI (for a WebSign-specific implementation of the same concept).
   1. Differences between WebSign-SRI and the SRI standard:
      1. Rather than just JS and CSS, WebSign-SRI supports any arbitrary subresource; for this to work, non-JS/CSS subresources referenced anywhere throughout the code (e.g. images) are first converted into text files containing base64 data URIs.
      2. In the event that a subresource fails to validate during the initial package load, rather than just silently discarding that subresource, WebSign-SRI will abort loading the package entirely.
      3. Rather than being restricted to newer versions of Chrome and Firefox, WebSign-SRI works in any browser that isn’t ancient (although more recent browser versions with native SHA-512 support get a small performance boost).
2. Build environment is connected to signing environment via temporary unidirectional fiber network.
3. Build environment sends index.html to signing environment — along with some metadata, e.g. an expiration date and the allowed hostname for running the package (which would be cyph.app in the case of Cyph’s production deployment).
4. After manual review in a terminal pager and explicit confirmation, signing environment signs the package.
5. Unidirectional network direction is physically reversed (cables swapped).
6. Signing environment sends signed package back to build environment.
7. Fiber network is disconnected.
8. Build environment publishes signed package at api.cyph.com/package/cyph.app and publishes all subresources to InterPlanetary File System (IPFS).

WebSign client logic:

1. Downloads and validates the WebSign bootstrap itself against a hash whitelist from the signed package metadata. This is meant to provide a form of TOFU even in browsers where HPKP is unavailable, albeit much more fragile and subject to things like cache eviction attacks, but also has the side effect of protecting users during the initial download from naive tampering by things like malware and harmful TLS-intercepting antivirus software. Failures abort the package load process and display:
   
   
   
   1. With this degraded level of TOFU, rather than outright blocking a tampered version of the WebSign bootstrap from ever hitting the browser, we instead are able to warn the user when a tampered bootstrap has been downloaded and queued for execution the next time they navigate to the page.
2. Downloads the package and validates its signature against the public keys.
3. If the package fails to validate — and an older still-valid version of the package isn’t cached locally — the process will be aborted and a message will be displayed indicating that the application failed to load.
4. Executes HTML from package, with subresources being processed by WebSign-SRI and downloaded from IPFS as needed. In native app contexts, a local IPFS node is used; in web contexts, a remote IPFS gateway is chosen as a fallback based on the user’s geography.
   

Usability Considerations

While this all works very well for Cyph given that Cyph was from the start architected and developed against WebSign with its usage being a hard requirement, there are a number of considerations and caveats to keep in mind when evaluating WebSign for use in any other (particularly non-greenfield) software:

• Single-page applications only.
• The URL fragment must be used for routing views (e.g. app.com/#foo/bar). However, this requirement can be skipped when restricting support to browsers with ServiceWorker capability.
• WebSigned applications that use Content Security Policy (which any WebSigned application should do) must do so through the “CSP Meta-Hardening” technique demoed in our BH/DC talk.
• Broadly speaking, all subresources should be self-contained within a WebSigned project, not fetched from remote origins like CDNs (otherwise WebSign adds no value). This includes ensuring that any third-party libraries used don’t have hard dependencies on remote subresources, and finding alternatives to those libraries when they do.
• Due to various traces necessarily left in the client (pinned keys, AppCache, etc.), WebSign isn’t appropriate for applications with threat models geared toward a strong guarantee of deniability of use (e.g. SecureDrop understandably treats this with a higher priority than data confidentiality).