Web Cryptography API Use Cases

W3C Editor’s Draft 22 October 2012

Latest Editor’s Draft:
Latest Published Version:
Previous Version(s):
Arun Ranganathan, Mozilla Corporation <arun@mozilla.com>


This document collates the target use cases for the Web Cryptography API. These use cases, described as scenarios, represent the set of expected functionality that may be achieved by the Web Cryptography API . A set of "secondary" functionality may also be documented here as scenarios.

Editorial note

This is revision $Id: OverviewUseCases.html,v 1.4 2012-11-19 05:50:44 arangana Exp $.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is the 22 October 2012 Editor’s Draft of the Web Cryptography API Use Cases specification. Please send comments about this document to public-webcrypto@w3.org (archived).

Ongoing discussion of this document will be on the public-webcrypto@w3.org mailing list.

This section describes the status of this document at the time of its publication. Other documents may supersede this document, since it is only an editor's draft. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is produced by the Web Cryptography WG in the W3C Interaction Domain.

Web content and browser developers are encouraged to review this draft. Please send comments to public-webcrypto@w3.org, the W3C's public email list for issues related to Web APIs. Archives of the list are available.

This document is produced by the Web Cryptography Working Group, within the W3C Interaction Domain. Changes made to this document can be found in the W3C public CVS server.

Publication as an Editor’s Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

The Web Cryptography API describes a JavaScript API for basic cryptographic operations, including: hashing, signature generation and verification, encryption and decryption. Additionally, it describes an API for applications to generate and/or manage the keying material necessary to perform these operations. This document presents use cases in the form of scenarios, with each scenario describing a potential web application using the API.

2. Requirements

This section presents required features of the Web Cryptography API; in many cases, the Web Cryptography API encompasses more than one algorithm and more than one mechanism to accomplish each of these features. The section presents code names for each of the features.

3. Use Case Scenarios

This section collates use case scenarios based on the requirements.

3.1. Banking Transactions

Park Jae-sang opens up a bank account with Gangnam Bank (GB), and wishes to log-in and engage in online transactions, including account balance checking, online payments (with some automated scheduled payments), and account transfers between domestic and investment accounts. The first time Park logs in to the GB website with a temporary verification code sent to his cell phone, the bank asks him to ascertain if the browser he is using is not at a kiosk; moreover, he is asked if it is a web browser and machine configuration he will use often.

He confirms that it is. The GB web site then asks him to generate a public key/private key pair, along with a digital certificate. Park consents, and the web page creates the key pair, storing his private key in the browser's designated key store, along with a one-time key escrow by the bank. [DERIVE | KEYEX-DH].

Subsequent access to the GB website is triggered via presentation of the key that Park generated when he first accessed the website [KEYCALL | DECRYPT-PKI | ??SIGN]. His browser presents this key every time he accesses the website and enters his password, which effectively binds his username and password to the generated private key and certificate. Additionally, Park can digitally sign online checks, authorize payments, and sign tax forms that he submits to the bank site using this generated key [SIGN]. Park can also perform the following tasks:

  1. Park can receive documents from GB that only he can read. These include his private bank statements and tax documents. [DECRYPT-PKI | DECRYPT]

  2. Park can submit documents to GB that only GB can read, with the assurance that these have come from Park. Such documents include confidential financial information. [ENCRYPT-PKI]

3.2. Dr. What: Video Service

Virginie connects to her favorite video service to watch an episode of a show she is interested in using her entertainment device, which connects to the biggest screen in her living room. The video service collects a monthly subscription fee and allows the watching of five streaming movies a month at that fee, and streams high definition content over an Internet connection. Virginie does the following:

  1. She sets her device up to interact with the service. Her device runs a user agent that meets the conformance criteria for the Web Cryptography API specification. During the set up process, the entertainment device generates the keys it will use and exchanges them safely with the video service [DERIVE | DERIVE-PKI | KEYEX-DH].

  2. Subsequent access to the video service from her device is seamless, and it identifies her as Virginie, loading her preferences and her watch queue. [KEYCALL | DECRYPT-PKI | ??SIGN]. She can access the service and browse videos to watch.

  3. She selects her favorite show -- Dr. What -- and picks an episode that she has not yet seen. The service then determines that she is authorized to watch that video, and streams that video. [???]

  4. Virginie rates the video so that the service understands her preferences. Along with personalized data about Virginie, the device sends usage statistics and metrics back to the service [MAC | ENCRYPT-SYM | ENCRYPT-PKI].

3.3. Code Sanctity and Bandwidth Saver

A major social networking site wishes to optimize website performance by storing JavaScript and other resources in local storage, preventing a needless server roundrip. The social network site wishes to verify that these resources have not been tampered with; the service uses localStorage and IndexedDB to store assets for their web pages, notably JavaScript. Their threat model is such that the social networking site implicitly trusts the HTTP connection (which uses TLS), the browser, and the HTTP cache, but cannot vouch for localStorage or IndexedDB. Let us take the case of a couple who have gone from being "In a Relationship" to "It's Complicated." John Doe uses the social networking site often, while Jane Doe, a JavaScript programmer, packs her bags to move out of the apartment.


This illustrates a worst case scenario, in which localStorage is compromised by a malicious user. Normally, the social networking site deploys code of the sort below, which John Doe's browser runs everytime he logs into the social networking site.


      function init() {
      var src = window.localStorage.getItem('src');
      // up until now env is safe
      if (src) {
        // now whatever code was in src will be executed
      } else {
        // fetch the code using xhr, populate localStorage
        // with it. Execute it.

But at some point in time, a malicious user -- Jane Doe -- with access to the JavaScript console of John Doe's browser does something of the sort:

      window.localStorage.setItem('src', evil_code);
      // evil_code sends photos to Jane Doe's personal server.

John Doe's use of the social network is thus compromised by Jane Doe's script injection, since the next time he logs in, and init() is called, evil_code is run, which may upload his private photos to Jane Doe's server. To mitigate against situations like this, the social networking site might do something like this:


      // Synchronously retrieve an MD5 hash of the pristine version of the code
      // This is retrieved from the server
        var src_hash = getHashFromServer();
        function init()
          var src = window.localStorage.getItem('src');

          // validateSrc is an utility function that wraps the Crypto API

          validateSrc(src, src_hash, success, failFetch);

          function success(){eval(src)};
          function failFetch(){//Fetch the code using XHR, and populate localStorage with it};



In this case, getHashFromServer() is guaranteed to be untampered with, since it connects to the server or the HTTP cache, which are above suspicion.


3.4. Mitch Turns 21: Encrypted Communications

Mark wishes to post pictures of Mitch's 21st birthday party to a social network that allows confidential and encrypted communication between members, but wishes to ensure that these pictures are safe from prying eyes -- more importantly, he wants them to be indecipherable digital data for everyone except Mitch. Mark can do the following:

  1. He can encrypt the photos with a key he generates for the occasion. [DERIVE | ENCRYPT]

  2. He can communicate with others on the network about the key and share the encrypted photos. [KEYEX | ENCRYPT-PKI]

  3. He can receive confidential communication from Mitch about the pictures via encrypted messages that are virtually impossible to read by any other entity than Mark. [VERIFY | DECRYPT-PKI]

3.5. Off The Record Real Time Messaging

David and Nadim wish to have an "Off The Record" chat in real time, completely between them, and in text, including the ability to share digital data such as photographs. They log on to a chat server that serves up web content, and connect to each other's machines directly. The server merely serves up the chat client necessary, and does not log their conversation (and in fact cannot). David and Nadim need to:

  • Be assured that they are who they claim they are. [DECRYPT | DECRYPT-PKI | ENCRYPT | ENCRYPT-PKI]

  • Be assured that during a conversation, messages sent back and forth are unmodified. [RANDOM | ENCRYPT | DECRYPT]

  • Be assured that after the conversation, the contents of the conversation cannot be determined. [???]

3.6. Documents In the Cloud

Vijay wishes to confidentially store certain documents, including photos, music, pages from the novel he is working on, and notes about his employer using a web service that he pays a monthly subscription to for such confidential storage. He can drag and drop content from his laptop onto a web page of the service, and it automatically stores it in an encrypted manner. Vijay can do the following:

  1. Log on to the service using his credentials; after the service determines that Vijay is using his primary browser, which he will use to access the service subsequently, it generates encryption keys. [DERIVE | DERIVE-PKI]

  2. Drag over content from his underlying file system that he wishes to store. [ENCRYPT-PKI]

  3. Store that content on the server, with the assurance that it is stored there in a way that is virtually undecipherable to third-parties, including employees of the service in question.

  4. Later, Vijay can retrieve the content, and save it back to his local file system. [DECRYPT-PKI]