WebCrypto High-level API

This specification describes a JavaScript API for public key generation, encryption, decryption, digital signature generation and verification, and hashing.

Use cases

Security of data at rest

An E-commerce website needs to store credit card numbers and related customer information to facilitate 1-step ordering. The site can either store this data on its own servers, making it a rich target for criminals. Another option is protecting this data with the "seal" method and decrypting later with "open" during a transaction. The server stores the the key ID and uses it when appropriate. A credit card transaction is processed easily, the server does not store the credentials and the data is more safely stored in the browser's LocalStorage without the KeyID, without which, an attacker cannot access the 'sealed' data.

Web-based messaging

A web-messaging company would like to provide a private messaging feature. Users can create keypairs and share them via a link, out of band or via a text message. (The user experience of the site equates each public key with an "addressbook entry", without which, no communication can take place.) After a message is composed, it is encrypted and signed, then sent to the server for delivery. No plaintext is passed to the server or retained on the client.

The following conformance classes are defined by this specification:

conforming user agent

A user agent is considered to be a conforming user agent if it satisfies all of the MUST-, REQUIRED- and SHALL-level criteria in this specification that apply to implementation. This specification uses both the terms "conforming user agent" and "user agent" to refer to this product class.

User agents MAY implement algorithms in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained from the specification's algorithms.

User agents that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]] as this specification uses that specification and terminology.

Dependencies

This specification relies on several other underlying specifications.

HTML5: The terms and algorithms Window, Function, origin, same origin, structured clone, structured clone algorithm, task, task source, queue a task and fire a simple event are defined by the HTML 5 specification [[!HTML5]].
WebIDL: Many of the interface definitions and all of the IDL in this spec depends on [[!WEBIDL]].
WebWorkers: The term WorkerGlobalScope is defined by the WebWorkers specification [[!WEBWORKERS]].

API definition

Overview

This specification defines a new highlevel attribute on the Window.crypto and WorkerGlobalScope objects.

Extension of Crypto interface

readonly attribute Highlevel highlevel: The object that exposes the high-level API

Highlevel interface

CreateKeyPairSuccess event handler: Upon creation of a key pair this handler is executed. The argument, publicKey, provides the public key data. The key pair data is a JSON Web Key (JWK)

CreateKeyPairError event handler: During key pair generation a platform error will fire this event handler, if defined.

EncryptSuccess event handler: Upon successful encryptAndSign operation, this event handler is executed. An argument, cipherText, is provided (a JSON Web Encryption (JWE) DOMString) and the Key ID of the current user's key pair.

EncryptError event handler: During a public key encryption operation an error will trigger this event handler.

DecryptSuccess event handler: Upon a successful public key decryption operation, this event handler is executed with a plainText argument.

DecryptError event handler: During a public key decrypt operation an error will trigger this event handler.

SealSuccess event handler: Each time seal is called a symmetric key is generated and ued to encrypt the plaintext. Upon successful seal operation, this event handler is executed producing the id that corresponds to the underlying symmetric key generated for this operation.

SealError event handler: During a seal operation an error will trigger this event handler.

OpenSuccess event handler: Upon successful open operation, this event handler is executed providing the plaintext result.

OpenError event handler: During an open operation an error will trigger this event handler.

void createKeyPair (optional in DOMString joseAlg): Generate a keypair
[TreatNonCallableAsNull] attribute CreateKeypairSuccess onCreateKeypairSuccess: onCreateKeypair event handler
[TreatNonCallableAsNull] attribute CreateKeypairError onCreateKeypairError: onCreateKeypair event handler
void encryptAndSign (in DOMString plainText, in DOMString recipientJWK, in DOMString jwkID): Perform encryption, signing the encrypted data
[TreatNonCallableAsNull] attribute EncryptSuccess onEncryptSuccess: onEncryptComplete event handler
[TreatNonCallableAsNull] attribute EncryptError onEncryptError: onEncryptError event handler
void verifyAndDecrypt (in DOMString receivedJWE, in DOMString senderJWK, in DOMString recipientJWKID): Verify signature and decryption method
[TreatNonCallableAsNull] attribute DecryptSuccess onDecryptSuccess: onDecryptComplete event handler
[TreatNonCallableAsNull] attribute DecryptError onDecryptError: onDecryptError event handler
void seal (in DOMString plainText): Symmetric encryption of a string (a key is generated on each use)
[TreatNonCallableAsNull] attribute SealSuccess onSealSuccess: onSealSuccess event handler, ciphertext and keyID are passed to this function
[TreatNonCallableAsNull] attribute SealError onSealError: onSealError event handler
void open (in DOMString keyID, in DOMString cipherText): Symmetric decryption of a string
[TreatNonCallableAsNull] attribute OpenSuccess onOpenSuccess: onOpenComplete event handler
[TreatNonCallableAsNull] attribute OpenError onOpenError: onOpenError event handler

Extension of WorkerGlobalScope interface

readonly attribute Highlevel highlevel: The object that exposes the high-level API

Examples

Keypair generation

var cryptoAPI = new window.crypto.highlevel();

function onCreateKeypairSuccess(aKeypair)
{
  localStorage.setItem(aKeypair.id, aKeypair.publicKey);
}

cryptoAPI.onCreateKeypair = onCreateKeypair;

function onCreateKeypairError(aError)
{
  console.log(aError);
}

cryptoAPI.createKeypair();

Public Key Encryption

var cryptoAPI = new window.crypto.highlevel();

var plainText = "The rain in Spain falls mainly on the plain.";

function onEncryptSuccess(aJWE, aPublicKey) {
  // send cipher data to the server for storage, etc...
}

cryptoAPI.onEncryptSuccess = onEncryptSuccess;

function onEncryptError(aError) {
  console.log(aError);
}

cryptoAPI.onEncryptError = onEncryptError;

cryptoAPI.encryptAndSign(plainText, recipientJSONWebKey, myKeyID);

Public Key Decryption

var cryptoAPI = new window.crypto.highlevel();

function onDecryptSuccess(aPlainText) {
  // read and save plain text
}

function onDecryptError(aError) {
  console.log(aError);
}

cryptoAPI.onDecryptError = onDecryptError;

cryptoAPI.onDecryptSuccess = onDecryptSuccess;

// verfiy and decrypt - if verification or decryption fails, onDecryptError is fired
cryptoAPI.verifyAndDecrypt(receivedJSONWebEncryption, senderJSONWebKey, myKeyID);

Symmetric Encryption

var cryptoAPI = new window.crypto.highlevel();

function onSealComplete(aCipherText, aKeyID) {
  // cipher text and the key ID are provided to this event handler
}

function onSealError(aError) {
  console.log(aError);
}
cryptoAPI.onSealError = onSealError;

cryptoAPI.onSealComplete = onSealComplete;

cryptoAPI.seal("s3kr3t m355ag3");

Symmetric Decryption

var cryptoAPI = new window.crypto.highlevel();

function onOpenSuccess(aPlainText) {
  savePlainTextToLocalStorageOrWhatever(aPlainText);
}

function onOpenError(aError) {
  console.log(aError);
}

cryptoAPI.onOpenError = onOpenError;

cryptoAPI.onOpenSuccess = onOpenSuccess;

cryptoAPI.open(cipherString, keyID);

Introduction