W3C

Web Cryptography API

W3C Editor’s Draft 10 December 2012

Latest Editor’s Draft:
http://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html
Latest Published Version:
http://www.w3.org/TR/WebCryptoAPI/
Previous Version(s):
https://dvcs.w3.org/hg/webcrypto-api/raw-file/0fe9b34c13fb/spec/Overview.html
Editors:
David Dahl, Mozilla Corporation <ddahl@mozilla.com>
Ryan Sleevi, Google, Inc. <sleevi@google.com>
Participate:

Send feedback to public-webcrypto@w3.org (archives), or file a bug (see existing bugs).


Abstract

This specification describes a JavaScript API for performing basic cryptographic operations in web applications, such as hashing, signature generation and verification, and encryption and decryption. Additionally, it describes an API for applications to generate and/or manage the keying material necessary to perform these operations. Uses for this API range from user or service authentication, document or code signing, and the confidentiality and integrity of communications.

Editorial note

There are 21 further editorial notes in the document.

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 most recently formally published revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Implementors should be aware that this specification is not stable. Implementors who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation stage should join the mailing lists that follow and take part in the discussions.

The Web Cryptography Working Group invites discussion and feedback on this draft document by web developers, companies, standardization bodies or forums interested in deployment of secure services with web applications. Specifically, Web Cryptography Working Group is looking for feedback on:

This is the W3C Editor's Draft of the Web Cryptography API. Please send comments to public-webcrypto-comments@w3.org (archived). This is an unfinished work in progress.

Previous discussion of this specification has taken place on three other mailing lists: whatwg@whatwg.org (archive) , public-websecurity@w3.org (archive), and public-identity@w3.org (archive). Ongoing discussion 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 of the W3C.

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

Changes made to this document can be found in the W3C public Mercurial 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

This section is non-normative.

The Web Cryptography API defines a low-level interface to interacting with cryptographic key material that is managed or exposed by user agents. The API itself is agnostic of the underlying implementation of key storage, but provides a common set of interfaces that allow rich web applications to perform operations such as signature generation and verification, hashing and verification, encryption and decryption, without requiring access to the raw keying material.

Cryptographic transformations are exposed via the CryptoOperation interface, which defines a common set of methods and events for dealing with initialization, processing data, and completing the operation to yield the final output. In addition to operations such as signature generation and verification, hashing and verification, and encryption and decryption, the API provides interfaces for key generation, key derivation, key import and export, and key discovery.

2. Use Cases

This section is non-normative

Editorial note
ACTION-13
Add missing use cases.
ACTION-15
Insert in "right place" a description of high-level example
ACTION-27
Add additional primary use cases.

Should these use cases be migrated to the Introduction section, and include non-normative examples of how the API can be used to perform each operation?

2.1. Multi-factor Authentication

A web application may wish to extend or replace existing username/password based authentication schemes with authentication methods based on proving that the user has access to some secret keying material. Rather than using transport-layer authentication, such as TLS client certificates, the web application may wish to provide a rich user experience by providing authentication within the application itself.

Using the Web Cryptography API, such an application could locate suitable client keys, which may have been previously generated via the user agent or pre-provisioned out-of-band by the web application. It could then perform cryptographic operations such as decrypting an authentication challenge followed by signing an authentication response.

Further, the authentication data could be further enhanced by binding the authentication to the TLS session that the client is authenticating over, by deriving a key based on properties of the underlying transport.

If a user did not already have a key associated with their account, the web application could direct the user agent to either generate a new key or to re-use an existing key of the user's choosing.

2.2. Protected Document Exchange

When exchanging documents that may contain sensitive or personal information, a web application may wish to ensure that only certain users can view the documents, even after they have been securely received, such as over TLS. One way that a web application can do so is by encrypting the documents with a secret key, and then wrapping that key with the public keys associated with authorized users.

When a user agent navigates to such a web application, the application may send the encrypted form of the document. The user agent is then instructed to unwrap the encryption key, using the user's private key, and from there, decrypt and display the document.

2.3. Cloud Storage

When storing data with remote service providers, users may wish to protect the confidentiality of their documents and data prior to uploading them. The Web Cryptography API allows an application to have a user select a private or secret key, to either derive encryption keys from the selected key or to directly encrypt documents using this key, and then to upload the transformed/encrypted data to the service provider using existing APIs.

This use case is similar to the Protected Document Exchange use case because Cloud Storage can be considered as a user exchanging protected data with himself in the future.

2.4. Document Signing

A web application may wish to accept electronic signatures on documents, in lieu of requiring physical signatures. An authorized signature may use a key that was pre-provisioned out-of-band by the web application, or it may be using a key that the client generated specifically for the web application.

The web application must be able to locate any appropriate keys for signatures, then direct the user to perform a signing operation over some data, as proof that they accept the document.

2.5. Data Integrity Protection

When caching data locally, an application may wish to ensure that this data cannot be modified in an offline attack. In such a case, the server may sign the data that it intends the client to cache, with a private key held by the server. The web application that subsequently uses this cached data may contain a public key that enables it to validate that the cache contents have not been modified by anyone else.

2.6. Secure Messaging

In addition to a number of web applications already offering chat based services, the rise of WebSockets and RTCWEB allows a great degree of flexibility in inter-user-agent messaging. While TLS/DTLS may be used to protect messages to web applications, users may wish to directly secure messages using schemes such as off-the-record (OTR) messaging.

The Web Cryptography API enables OTR, by allowing key agreement to be performed so that the two parties can negotiate shared encryption keys and message authentication code (MAC) keys, to allow encryption and decryption of messages, and to prevent tampering of messages through the MACs.

2.7. Javascript Object Signing and Encryption (JOSE)

A web application wishes to make use of the structures and format of messages defined by the IETF Javascript Object Signing and Encryption (JOSE) Working Group. The web application wishes to manipulate public keys encoded in the JSON key format (JWK), messages that have been integrity protected using digital signatures or MACs (JWS), or that have been encrypted (JWE).

3. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, RECOMMENDED, MAY, OPTIONAL, in this specification are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels [RFC2119].

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 implementations. 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.

4. Scope

This section is non-normative.

4.1. Level of abstraction

The specification attempts to focus on the common functionality and features between various platform-specific or standardized cryptographic APIs, and avoid features and functionality that are specific to one or two implementations. As such this API allows key generation, management, and exchange with a level of abstraction that avoids developers needing to care about the implementation of the underlying key storage. The API is focused specifically around Key objects, as an abstraction for the underlying raw cryptographic keying material. The intent behind this is to allow an API that is generic enough to allow conforming user agents to expose keys that are stored and managed directly by the user agent, that may be stored or managed using isolated storage APIs such as per-user key stores provided by some operating systems, or within key storage devices such as secure elements, while allowing rich web applications to manipulate the keys and without requiring the web application be aware of the nature of the underlying key storage.

4.2. Cryptographic algorithms

Because the underlying cryptographic implementations will vary between conforming user agents, and may be subject to local policy, including but not limited to concerns such as government or industry regulation, security best practices, intellectual property concerns, and constrained operational environments, this specification does not dictate a mandatory set of algorithms that MUST be implemented. Instead, it defines a common set of bindings that can be used in an algorithm-independent manner, a common framework for discovering if a user agent or key handle supports the underlying algorithm, and a set of conformance requirements for the behaviours of individual algorithms, if implemented.

4.3. Operations

Although the API does not expose the notion of cryptographic providers or modules, each key is internally bound to a cryptographic provider or module, so web applications can rest assured that the right cryptographic provider or module will be used to perform cryptographic operations involving that key.

4.4. Out of scope

This API, while allowing applications to generate, retrieve, and manipulate keying material, does not specifically address the provisioning of keys in particular types of key storage, such as secure elements or smart cards. This is due to such provisioning operations often being burdened with vendor-specific details that make defining a vendor-agnostic interface an unsuitably unbounded task. Additionally, this API does not deal with or address the discovery of cryptographic modules, as such concepts are dependent upon the underlying user agent and are not concepts that are portable between common operating systems, cryptographic libraries, and implementations.

5. Security considerations

This section is non-normative.

5.1. Security considerations for implementers

User agents should take care before exposing keys that were not explicitly generated via the API in this specification or exposing keys that were generated in the context of other origins. Two applications with access to the same key handle may be able to spoof messages to each other, as both valid and hostile messages will appear to be valid for the given key. Because of this, user agents are recommended to obtain express permission from the user before re-using keys, unless there is a prearranged trust relationship.

User agents should be aware of the security considerations of each algorithm implemented and exposed to applications. For a number of algorithms, their cryptographic strength is relative to the amount of work necessary to compute the result, whether this be through the generation of significantly large prime numbers or through the repeatedly iterating through the same algorithm to reduce its susceptibility to brute force. Implementations should therefore take measures to ensure against misuse. Such measures may include requiring express user permission to compute some expensive operations, rate limiting the number of times the application may call certain APIs/algorithms, and defining implementation-specific upper limits for inputs such as key sizes or iteration counts, as appropriate for the device on which the implementation executes.

In some cases, the same underlying cryptographic key material may be re-usable for multiple algorithms. One such example is an RSA key, which may be used for both signing and encryption, or with RSA-PKCS1v1.5 and RSA-PSS. In some cases, the re-use of this key material may undermine the security properties of the key and allow applications to recover the raw material.

Editorial note
  • ISSUE-33 One proposed technical solution for user agents is to implement "key tainting", in which it records how a particular key has been used (eg: algorithms, parameters), and prevents it from being re-used in a manner that is unsafe or contrary to the security - such as preventing a PKCS1-v1.5 key from being used with RSA-PSS, or preventing an RSA-OAEP w/ MGF1-SHA1 from being used with RSA-OAEP w/ MGF1-SHA256. Questions exist about whether this should be encouraged or permitted, and the interoperability concerns it might cause.

5.2. Security considerations for developers

While this API provides important functionality for the development of secure applications, it does not try to address all of the issues that may arise from the web security model. As such, application developers must take care to ensure against common attacks such as script injection by making use of appropriate security functionality such as Content Security Policy and the use of TLS.

This API includes a variety of cryptographic operations, some of which may have known security issues when used inappropriately. Application developers should take care to review the appropriate cryptographic literature before making use of certain algorithms, and should avoid attempting to develop new cryptographic protocols whenever possible.

While the API in this specification provides a means to protect keys from future access by web applications, it makes no statements as to how the actual keying material will be stored by an implementation. As such, although a key may be inaccessible to web content, it should not be presumed that it is inaccessible to end-users. For example, a conforming user agent may choose to implement key storage by storing key material in plain text on device storage. Although the user agent prevents access to the raw keying material to web applications, any user with access to device storage may be able to recover the key.

In some situations, allowing low-level access to key handles, such as to permit the signing or encryption of arbitrary text, may allow an attacker to construct an oracle that can be used to recover key material. Application developers are thus encouraged to be careful about permitting the signing of arbitrary messages, and should consider the use of existing cryptographic messaging protocols as appropriate.

6. Privacy considerations

This section is non-normative.

Fingerprinting
Malicious applications may be able to fingerprint users or user agents by detecting or enumerating the list of algorithms that are supported. This is especially true if an implementation exposes details about users' smart cards or secure element storage, as the combination of algorithms supported by such devices may be used to fingerprint devices more accurately than just the particular user agent.
Tracking
If user agents permit keys to be re-used between origins, without performing any secondary operations such as key derivation that includes the origin, then it may be possible for two origins to collude and track a unique user by recording their ability to access a common key.
Super-cookies
With the exception of ephemeral keys, its often desirable for applications to strongly associate users with keys. These associations may be used to enhance the security of authenticating to the application, such as using a key stored in a secure element as a second factor, or may be used by users to assert some identity, such as an e-mail signing identity. As such, these keys often live longer than their counterparts such as usernames and passwords, and it may be undesirable or prohibitive for users to revoke these keys. Because of this, keys may exist longer than the lifetime of the browsing context [HTML] and beyond the lifetime of items such as cookies, thus presenting a risk that a user may be tracked even after clearing such data. This is especially true for keys that were pre-provisioned for particular origins and for which no user interaction was provided.

7. Dependencies

This specification relies on underlying specifications.

DOM

A conforming user agent MUST support at least the subset of the functionality defined in DOM4 that this specification relies upon; in particular, it MUST support EventTarget. [DOM4]

HTML

A conforming user agent MUST support at least the subset of the functionality defined in HTML that this specification relies upon; in particular, it MUST support event loops and event handler attributes. [HTML]

Web IDL

A conforming user agent MUST be a conforming implementation of the IDL fragments in this specification, as described in the Web IDL specification. [WebIDL]

Typed Arrays

A conforming user agent MUST support the Typed Arrays specification [TypedArrays].

8. Terminology

The terms and algorithms document, event handler attributes, event handler event type, origin, same origin, event loops, task, task source, URL, queue a task, fire a simple event, and structured clone, are defined by the HTML specification [HTML].

When this specification says to terminate the algorithm, the user agent must terminate the algorithm after finishing the step it is on. The algorithm referred to is the set of specification-defined processing steps, rather than the underlying cryptographic algorithm that may be in the midst of processing.

9. RandomSource interface

IDL

[NoInterfaceObject]
interface RandomSource {
  ArrayBufferView getRandomValues(ArrayBufferView array);
};
        

9.1. Description

The RandomSource interface represents an interface to a cryptographically strong pseudo-random number generator seeded with truly random values.

Implementation note: Implementations should generate cryptographically random values using well-established cryptographic pseudo-random number generators seeded with high-quality entropy, such as from an operating-system entropy source (e.g., "/dev/urandom"). This specification provides no lower-bound on the information theoretic entropy present in cryptographically random values, but implementations should make a best effort to provide as much entropy as practicable.

Implementation note: This interface defines a synchronous method for obtaining cryptographically random values. While some devices and implementations may support truly random cryptographic number generators or provide interfaces that block when there is insufficient entropy, implementations are encouraged not to use these sources when implementing getRandomValues, both for performance and to avoid depleting the system of entropy. Instead, these sources should be used to seed a cryptographic pseudo-random number generator that can then return suitable values efficiently.

9.2. Methods and Parameters

9.2.1. The getRandomValues method

The getRandomValues method generates cryptographically random values. It must act as follows:

  1. If array is not of an integer type (i.e., Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, or Uint32Array), throw a TypeMismatchError and terminate the algorithm.

  2. If the byteLength of array is greater than 65536, throw a QuotaExceededError and terminate the algorithm.

  3. Overwrite all elements of array with cryptographically random values of the appropriate type.

  4. Return array.

Do not generate keys using the getRandomValues method. Use the generateKey method instead.

Editorial note
  • The getRandomValues function has been implemented in several WebKit-based browsers, including Google Chrome and Apple Safari. If the specification of this function changes, steps will need to be taken to resolve the inconsistency - including possibly renaming the function.

10. Algorithm dictionary

The Algorithm object is a dictionary object [WebIDL] which is used to specify an algorithm and any additional parameters required to fully specify the desired operation.

IDL

// TBD: ISSUE-28
typedef (Algorithm or DOMString) AlgorithmIdentifier;

dictionary AlgorithmParameters {
};

dictionary Algorithm {
  DOMString name;
  AlgorithmParameters params;
};
        
Editorial note
  • ISSUE-28: Should algorithms permit short-names (string identifiers) as equivalent to specifying Algorithm dictionaries, or should Algorithm dictionaries be the only accepted form?

10.1. Algorithm Dictionary Members

name
The name of the registered algorithm to use.
params
The algorithm-specific parameters used to fully specify the operation to perform.

11. Key interface

The Key object represents an opaque reference to keying material that is managed by the user agent.

IDL

enum KeyType {
  "secret",
  "public",
  "private"
};

enum KeyUsage {
  "encrypt",
  "decrypt",
  "sign",
  "verify",
  "derive"
};

interface Key {
  readonly attribute KeyType type;
  readonly attribute bool extractable;
  readonly attribute Algorithm algorithm;
  readonly attribute KeyUsage[] keyUsage;
};
        

11.1. Description

This section is non-normative

This specification provides a uniform interface for many different kinds of keying material managed by the user agent. This may include keys that have been generated by the user agent, derived from other keys by the user agent, imported to the user agent through user actions or using this API, pre-provisioned within software or hardware to which the user agent has access or made available to the user agent in other ways. The term key refers broadly to any keying material including actual keys for cryptographic operations and secret values obtained within key derivation or exchange operations.

The Key object is not required to directly interface with the underlying key storage mechanism, and may instead simply be a reference for the user agent to understand how to obtain the keying material when needed, eg. via a CryptoOperation.

11.2. Key interface members

type
The type of the underlying keys. Opaque keying material, including that used for symmetric algorithms, are represented by "secret", while keys used as part of asymmetric algorithms composed of public/private keypairs will be either "public" or "private".
extractable
Whether or not the raw keying material may be exported by the application.
algorithm
The Algorithm used to generate the key.
keyUsage
An Array of KeyUsages that indicate what CryptoOperations may be used with this key.

11.3. Structured clone algorithm

When a user agent is required to obtain a structured clone of a Key object, it must run the following steps.

  1. Let input and memory be the corresponding inputs defined by the internal structured cloning algorithm, where input represents a Key object to be cloned.
  2. Let output be a newly constructed Key object.
  3. Let the following attributes of output be equal to the value obtained by invoking the internal structured clone algorithm recursively, using the corresponding attribute on input as the new "input" argument and memory as the new "memory" argument:
  4. Let output refer to the same underlying cryptographic material and cryptographic material key storage of input.

12. CryptoOperation interface

IDL

interface CryptoOperation : EventTarget {
  void process(ArrayBufferView buffer);
  void finish();
  void abort();

  readonly attribute Key? key;
  readonly attribute Algorithm algorithm;
  readonly attribute any result;

  [TreatNonCallableasNull] attribute Function? onabort;
  [TreatNonCallableAsNull] attribute Function? onerror;
  [TreatNonCallableAsNull] attribute Function? onprogress;
  [TreatNonCallableAsNull] attribute Function? oncomplete;
};
        
Editorial note

12.1. Processing Model

Every CryptoOperation object must have a list of pending data. Each item in the lists represents data that should be transformed by the cryptographic operation. The list functions as a queue that observes first-in, first-out ordering. That is, the order in which items are added shall reflect the order in which items are removed.

When a CryptoOperation is said to process data, the user agent must execute the following steps:

  1. If there are no items in the list of pending data, the algorithm is complete.

  2. If the underlying cryptographic implementation does not support multi-part cryptographic operations for the current algorithm, perform the following steps:
    1. Let bytes be an empty sequence of bytes.

    2. For each item in the list of pending data:

      1. Let item be the oldest remaining item in the list of pending data.

      2. Remove item from the list of pending data.

      3. Convert item to a sequence of byteLength bytes from the underlying ArrayBuffer, starting at the byteOffset of the ArrayBufferView, and append those bytes to bytes

    3. Perform the underlying cryptographic algorithm, using bytes as the input data.

    4. If the cryptographic operation fails, proceed to the error steps below:

      1. Update the internal state to "error".

      2. Queue a task to fire a simple event named onerror at the CryptoOperation.

      3. Terminate this algorithm.

    5. Let output be the result of the underlying cryptographic algorithm.

    Otherwise, if the underlying cryptographic implementation supports multi-part cryptographic operations for the current algorithm, perform the following algorithm:
    1. Let bytes be an empty sequence of bytes.

    2. Let item be the oldest remaining item in the list of pending data.

    3. Remove data from the list of pending data.

    4. Convert item to a sequence of byteLength bytes from the underlying ArrayBuffer, starting at the byteOffset of the ArrayBufferView, and append those bytes to bytes

    5. A conforming user agent MAY repeat the preceeding steps as many times as desired, for as long as items remain in the list of pending data, provided that the output of the underlying cryptographic algorithm is indistinguishable from when only a single item is processed at a time.

    6. Perform the underlying cryptographic algorithm, using bytes as the input data.

    7. If the cryptographic operation fails, proceed to the error steps below:

      1. Clear the list of pending data.

      2. Update the internal state to "error".

      3. Queue a task to fire a simple event named onerror at the CryptoOperation.

      4. Terminate this algorithm.

    8. Let output be the result of the underlying cryptographic algorithm.

  3. Update result with the algorithm-specific result using output.

    Editorial note

    The wording here is presently ambiguous. It is modeled after the [FILE API], which has result accumulating the output as it becomes available. However, given that support for multi-part input exists, an interface to support streaming/progressive output has also been requested. How such an interface would be implemented, if at all, remains TBD.

  4. fire a simple event named onprogress at the CryptoOperation.

  5. If the underlying cryptograophic implementation supports multi-part cryptographic operations for the current algorithm, repeat these steps for each item remaining in the list of pending data.

Editorial note
  • The above algorithm is meant to describe a possible way of supporting multi-part input (also called "streaming" input, but not to be confused with the [STREAMS API]. The downside to the above algorithm is that it does not describe a good interface for supporting algorithms that may support multiple multi-part inputs.

    An example of such an algorithm would be AES-GCM, which has two sources of input - the encrypted-and-authenticated data ("ciphertext") and the authenticated data ("additional authenticated data"). A truly multi-part implementation would allow both the plaintext/ciphertext and the authenticated data to be supplied independently, and in parts, until finish() was called.

    However, at present, several major cryptographic APIs (CDSA, CNG, PKCS#11) do not support this, and so for now, the details for handling multi-source multi-part data have been omitted.

12.2. Event Handler Attributes

The following are the event handler attributes (and their corresponding event handler event types) that user agents must support on the CryptoOperation as DOM attributes:

event handler attributes event handler event type
onabort abort
onerror error
onprogress progress
oncomplete complete

12.3. Attributes

key

On getting, the key attribute returns the Key used to initialize the CryptoOperation.

If the CryptoOperation represents a keyless-operation, such as digesting, then key MUST return null.

algorithm
On getting, the algorithm attribute returns the normalized algorithm of the algorithm used to initialize the CryptoOperation.
result
On getting, the result attribute returns the algorithm-specific result for the current CryptoOperation.
  • On getting, if an error in performing the operation has occurred, then the result attribute MUST return null.

12.4. Methods

12.4.1. process(ArrayBufferView data)

When the process(ArrayBufferView data) method is called, the user agent must run the following steps:

  1. If the internal state is in the "error" state, throw an InvalidStateError exception and abort these steps.

  2. Let data be the data to be processed.

  3. Add data to the list of pending data.

  4. If the underlying cryptographic implementation for the specified algorithm supports multi-part cryptographic operations, asynchrously process data, allowing the task that invoked this algorithm to continue.

    Editorial note

    Warning: The text here is currently ambiguous in terms of defining how the event loop processes events; in particular, it leaves under-specified how the abort() method should be handled when data is being processed.

12.4.2. The finish() method

When finish() method is called, the user agent must run the steps below.

  1. If the internal state is in the "error" state, throw an InvalidStateError exception and abort these steps.

  2. Set the internal state to "complete".

  3. If the underlying cryptographic implementation for the specified algorithm does not support multi-part cryptographic operations, asynchronously process data, allowing the task that invoked this algorithm to continue.

  4. Once all items in the list of pending data have been processed, queue a task to fire a simple event called oncomplete at the CryptoOperation.

12.4.3. The abort() method

When abort() method is called, the user agent must run the steps below.

  1. If the internal state is in the "error" state, throw an InvalidStateError exception and abort these steps.

  2. Abort processing data.

  3. If there are any tasks from the object's CryptoOperation task source in one of the task queues, then remove those tasks.
  4. Fire a simple event called onabort at the CryptoOperation.
Editorial note

The above algorithm is underspecified, both for user agents that do not implement abortable processing and because the process data algorithm does not define how to abort midstream.

13. KeyOperation interface

IDL

interface KeyOperation : EventTarget {
  readonly attribute any result;

  [TreatNonCallableAsNull] attribute Function? onerror;
  [TreatNonCallableAsNull] attribute Function? oncomplete;
};
        

14. Crypto interface

IDL

enum KeyFormat {
  // An unformatted sequence of bytes. Intended for secret keys.
  "raw",
  // The DER encoding of the PrivateKeyInfo structure from RFC 5208.
  "pkcs8",
  // The DER encoding of the SubjectPublicKeyInfo structure from RFC 5280.
  "spki",
  // The key is represented as JSON according to the JSON Web Key format.
  "jwk",
};

interface Crypto {
  CryptoOperation encrypt(AlgorithmIdentifier algorithm, Key key, optional ArrayBufferView? buffer = null);
  CryptoOperation decrypt(AlgorithmIdentifier algorithm, Key key, optional ArrayBufferView? buffer = null);
  CryptoOperation sign(AlgorithmIdentifier algorithm, Key key, optional ArrayBufferView? buffer = null);
  CryptoOperation verify(AlgorithmIdentifier algorithm, Key key, ArrayBufferView signature, optional ArrayBufferView? buffer = null);
  CryptoOperation digest(AlgorithmIdentifier algorithm, optional ArrayBufferView? buffer = null);

  // TBD: ISSUE-36
  KeyOperation generateKey(AlgorithmIdentifier algorithm,
                           bool extractable = false,
                           KeyUsage[] keyUsages = []);
  KeyOperation deriveKey(AlgorithmIdentifier algorithm,
                         Key baseKey,
                         AlgorithmIdentifier? derivedKeyType,
                         bool extractable = false,
                         KeyUsage[] keyUsages = []);
  
  // TBD: ISSUE-35
  KeyOperation importKey(KeyFormat format,
                         ArrayBufferView keyData,
                         AlgorithmIdentifier? algorithm,
                         bool extractable = false,
                         KeyUsage[] keyUsages = []);
  KeyOperation exportKey(KeyFormat format, Key key);
};

Crypto implements RandomSource;

partial interface Window {
  readonly attribute Crypto crypto;
};
        
Editorial note
  • ISSUE-35: There is an open question as to how the API should support key wrap and unwrap operations. Should they be distinct operations, independent from key import/export, or should they be part of the parameters supplied during import/export.
  • ISSUE-36: Further distinction is needed to clarify the differences between key generation and key derivation. Should they be distinguished by their inputs (Key generation takes parameters, while key derivation takes parameters + key(s)), by their outputs (Key generation generates Keys, key derivation generates opaque bytes as secret material), or is there some other construct to distinguish the two?

14.1. Methods and Parameters

14.1.1. The encrypt method

The encrypt method returns a new CryptoOperation object that will encrypt data using the specified AlgorithmIdentifier with the supplied Key. It must act as follows:

  1. Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.

  2. If normalizedAlgorithm does not describe a registered algorithm that supports the encrypt operation, throw a NotSupportedError and terminate the algorithm.

  3. Create a new CryptoOperation object S with the following characteristics:

    1. S.algorithm = normalizedAlgorithm.

    2. S.key = key.

    3. S.result = null.

  4. If buffer is specified:

    1. Queue a task to invoke the process() method on the new object, with buffer as the buffer argument.

    2. Queue a task to invoke the finish() method on the new object.

    Editorial note

    Supporting single-part operations is intended to address two use cases:

    1. Developers that "just" want to perform a simple operation. The single-method invocation best matches existing JavaScript cryptographic libraries, particularly the synchronous aspect.

    2. User agents that can optimize implementation when there is only a single operation being performed.

    Having the single-part operation return a CryptoOperation may change, as may make it easier for developers if a Promise type object (whether through TC39 or through DOM) is returned, since the only possible results are "success" and "error".

  5. Return the new object.

14.1.2. The decrypt method

The decrypt method returns a new CryptoOperation object that will decrypt data using the specified AlgorithmIdentifier with the supplied Key. It must act as follows:

  1. Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.

  2. If normalizedAlgorithm does not describe a registered algorithm that supports the decrypt operation, throw a NotSupportedError and terminate the algorithm.

  3. Create a new CryptoOperation object S with the following characteristics:

    1. S.algorithm = normalizedAlgorithm.

    2. S.key = key.

    3. S.result = null.

  4. If buffer is specified:

    1. Queue a task to invoke the process() method on the new object, with buffer as the buffer argument.

    2. Queue a task to invoke the finish() method on the new object.

    Editorial note

    Supporting single-part operations is intended to address two use cases:

    1. Developers that "just" want to perform a simple operation. The single-method invocation best matches existing JavaScript cryptographic libraries, particularly the synchronous aspect.

    2. User agents that can optimize implementation when there is only a single operation being performed.

    Having the single-part operation return a CryptoOperation may change, as may make it easier for developers if a Promise type object (whether through TC39 or through DOM) is returned, since the only possible results are "success" and "error".

  5. Return the new object.

14.1.3. The sign method

The sign method returns a new CryptoOperation object that will sign data using the specified AlgorithmIdentifier with the supplied Key. It must act as follows:

  1. Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.

  2. If normalizedAlgorithm does not describe a registered algorithm that supports the sign operation, throw a NotSupportedError and terminate the algorithm.

  3. Create a new CryptoOperation object S with the following characteristics:

    1. S.algorithm = normalizedAlgorithm.

    2. S.key = key.

    3. S.result = null.

  4. If buffer is specified:

    1. Queue a task to invoke the process() method on the new object, with buffer as the buffer argument.

    2. Queue a task to invoke the finish() method on the new object.

    Editorial note

    Supporting single-part operations is intended to address two use cases:

    1. Developers that "just" want to perform a simple operation. The single-method invocation best matches existing JavaScript cryptographic libraries, particularly the synchronous aspect.

    2. User agents that can optimize implementation when there is only a single operation being performed.

    Having the single-part operation return a CryptoOperation may change, as may make it easier for developers if a Promise type object (whether through TC39 or through DOM) is returned, since the only possible results are "success" and "error".

  5. Return the new object.

14.1.4. The verify method

The verify method returns a new CryptoOperation object that will verify data using the specified AlgorithmIdentifier with the supplied Key. It must act as follows:

  1. Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.

  2. If normalizedAlgorithm does not describe a registered algorithm that supports the verify operation, throw a NotSupportedError and terminate the algorithm.

  3. Create a new CryptoOperation object S with the following characteristics:

    1. S.algorithm = normalizedAlgorithm.

    2. S.key = key.

    3. S.result = null.

  4. If buffer is specified:

    1. Queue a task to invoke the process() method on the new object, with buffer as the buffer argument.

    2. Queue a task to invoke the finish() method on the new object.

    Editorial note

    Supporting single-part operations is intended to address two use cases:

    1. Developers that "just" want to perform a simple operation. The single-method invocation best matches existing JavaScript cryptographic libraries, particularly the synchronous aspect.

    2. User agents that can optimize implementation when there is only a single operation being performed.

    Having the single-part operation return a CryptoOperation may change, as may make it easier for developers if a Promise type object (whether through TC39 or through DOM) is returned, since the only possible results are "success" and "error".

  5. Return the new object.

14.1.5. The digest method

The digest method returns a new CryptoOperation object that will digest data using the specified AlgorithmIdentifier. It must act as follows:

  1. Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.

  2. If normalizedAlgorithm does not describe a registered algorithm that supports the digest operation, throw a NotSupportedError and terminate the algorithm.

  3. Create a new CryptoOperation object S with the following characteristics:

    1. S.algorithm = normalizedAlgorithm.

    2. S.key = null.

    3. S.result = null.

  4. If buffer is specified:

    1. Queue a task to invoke the process() method on the new object, with buffer as the buffer argument.

    2. Queue a task to invoke the finish() method on the new object.

    Editorial note

    Supporting single-part operations is intended to address two use cases:

    1. Developers that "just" want to perform a simple operation. The single-method invocation best matches existing JavaScript cryptographic libraries, particularly the synchronous aspect.

    2. User agents that can optimize implementation when there is only a single operation being performed.

    Having the single-part operation return a CryptoOperation may change, as may make it easier for developers if a Promise type object (whether through TC39 or through DOM) is returned, since the only possible results are "success" and "error".

  5. Return the new object.

14.1.6. The generateKey method

When invoked, this method MUST perform the following steps:

  1. Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.

  2. If normalizedAlgorithm does not describe a registered algorithm that supports the generate operation, throw a NotSupportedError and terminate the algorithm.

  3. Let keyOp be a newly created object implementing the KeyOperation interface.

  4. Return keyOp to the task that invoked this generateKey, while continuing the remaining steps of this algorithm.

  5. Queue up an operation to run the following steps:

    1. Invoke the algorithm-specific key generation method.

    2. If an error occured, queue a task to fire a simple event called onerror at KeyOp and terminate this algorithm.

    3. Otherwise, if the algorithm-specific key generation method completed successfully, let result be the result of that operation.

    4. Set keyOp.result = result

    5. Queue a task to fire a simple event called oncomplete at KeyOp

Editorial note
  • The handling for extractable and keyUsages are currently underspecified. The intent is that any derived secret/private keys will reflect whatever the caller specified. However, the exact wording of how to specify that remains TBD.

    Consider, for example, generation of an RSA key pair. The intent may be that the public key has the "verify" usage, and the private key has the "sign" usage, but there is no way in the API to specify that. The same concern applies for "encrypt" and "decrypt".

    An alternative would be to allow the caller to write to the attributes on individual Key objects themselves, after generation, and then have some operation to finalize the object itself, but this as well remains TBD.

14.1.7. The deriveKey method

When invoked, this method MUST perform the following steps:

  1. Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.

  2. If normalizedAlgorithm does not describe a registered algorithm that supports the derive operation, throw a NotSupportedError and terminate the algorithm.

  3. Let keyOp be a newly created object implementing the KeyOperation interface.

  4. Return keyOp to the task that invoked this generateKey, while continuing the remaining steps of this algorithm.

  5. Queue up an operation to run the following steps:

    1. If baseKey.keyUsage does not contain the "derive" KeyUsage, queue a task to fire a simple event called onerror at KeyOp and terminate this algorithm.

    2. Invoke the algorithm-specific key generation method.

    3. If an error occured, queue a task to fire a simple event called onerror at KeyOp and terminate this algorithm.

    4. Otherwise, if the algorithm-specific key derivation method completed successfully, let result be the result of that operation.

    5. Set keyOp.result = result

    6. Queue a task to fire a simple event called oncomplete at KeyOp

Editorial note
  • The handling for extractable and keyUsages are currently underspecified. The intent is that any derived secret/private keys will reflect whatever the caller specified. However, the exact wording of how to specify that remains TBD.

    Consider, for example, when derivation results in multiple key handles. The intent may be that one Key object is used for encrypting, while another is used for decrypting. However, the current way of specifying KeyUsage does not provide a means for callers to do so.

    An alternative would be to allow the caller to write to the attributes on individual Key objects themselves, after generation, and then have some operation to finalize the object itself, but this as well remains TBD.

14.1.8. The importKey method

14.1.9. The exportKey method

15. WorkerCrypto interface

IDL

interface WorkerCrypto {
};

WorkerCrypto implements RandomSource;

partial interface WorkerGlobalScope {
  readonly attribute WorkerCrypto crypto;
};
        

15.1. Description

The WorkerCrypto interface provides cryptographic functionality for background scripts, as specified by Web Workers [ Web Workers].

Editorial note

A unique interface exposing only a subset of the Crypto is provided as it has not yet been determined how Keys should be shared amongst threads, nor how user interaction should be managed for operations that may require user consent.

16. BigInteger

IDL

typedef Uint8Array BigInteger;
        

The BigInteger typedef is a Uint8Array that holds a multiple-precision unsigned integer. Each Uint8 element in the array represents a base-256 digit of the integer. The digits are in big-endian order: the first Uint8 element in the array is the most significant digit. A leading zero Uint8 element is not needed if the most significant bit of the integer is set.

17. KeyPair

IDL

interface KeyPair {
  Key publicKey;
  Key privateKey;
};
        

The KeyPair interface represents an asymmetric key pair that is comprised of both public and private keys.

18. Key Discovery

This section is non-normative.

Editorial note

The Working Group is actively discussing means of discovering Key objects that are not not directly created by the application via generateKey, or allowing web applications to dicate how and where the cryptographic keying material associated with Key objects is stored. Examples of such Key objects or interfaces that may be exposed include:

  • Named keys that have been pre-provisioned for a particular device or origin (e.g.: device specific keys).
  • Keys that are stored in secure elements (e.g.: smart cards, TPMs), particularly those that may be inserted or removed at any time.
  • Keys that are associated with X.509 certificates matching some criteria.
  • Keys derived from material associated with a particular origin (e.g.: derived from exported TLS keying material [RFC5705] or origin bound certificates [DRAFT-TLS-OBC]).

There is currently no consensus within the Web Cryptography Working Group about how and where such interfaces should be specified, nor is there consensus with regards to various proposals intended to address specific use cases.

Such features bring a variety of concerns, most notably unique concerns regarding privacy, security, and user interaction, that may be best addressed through separate specifications that expand on sources for generating or storing Key objects.

19. Algorithms

19.2. Defining an algorithm

Each algorithm that is to be exposed via the Web Cryptography API SHOULD be registered via the Web Cryptography working group, and MUST include all of the following details. Algorithms that are not registered via these means, but are exposed via this API, MUST be processed as if the sections had been defined.

19.2.1. Recognized algorithm name

Each registered algorithm MUST have a canonical name for which applications can refer to the algorithm. The canonical name MUST contain only ASCII characters and MUST NOT equal any other canonical name or algorithm alias when every character in both names are converted to lower case.

19.2.2. Supported operations

Each registered algorithm MUST define the operations that it supports.

19.2.3. Algorithm-specific parameters

Each registered algorithm MUST define the expected contents of the params member of the Algorithm object for every supported operation.

Each registered algorithm MUST define the normalization rules for the contents of the params member of the Algorithm object for every supported operation.

19.2.4. Algorithm results

Each registered algorithm MUST define the contents of the result attribute of the CryptoOperation object for every supported operation and for every state.

19.2.5. Algorithm aliases

Each registered algorithm MAY define one or more aliases that may define a fully normalized Algorithm object.

Each algorithm alias MUST follow the same naming rules as the recognized algorithm name.

Editorial note
  • ISSUE-28: Should algorithms permit short-names (string identifiers) as equivalent to specifying Algorithm dictionaries, or should Algorithm dictionaries be the only accepted form?

19.3. RSAES-PKCS1-v1_5

19.3.1. Description

The "RSAES-PKCS1-v1_5" algorithm identifier is used to perform encryption and decryption ordering to the RSAES-PKCS1-v1_5 algorithm specified in [RFC3447].

19.3.2. Registration

The recognized algorithm name for this algorithm is "RSAES-PKCS1-v1_5".

Operation Parameters Result
encrypt None ArrayBufferView?
decrypt None ArrayBufferView?
generateKey RsaKeyGenParams KeyPair?

19.3.3. RsaKeyGenParams dictionary

IDL

dictionary RsaKeyGenParams : AlgorithmParameters {
  // The length, in bits, of the RSA modulus
  unsigned long modulusLength;
  // The RSA public exponent
  BigInteger publicExponent;
};
            

19.3.4. Operations

Encrypt
When encrypting, the resultant CryptoOperation shall behave as follows:
  1. Upon invoking init:
    1. If key does not describe an RSA public key, raise an error and terminate the algorithm.
    2. Let M be an empty sequence of bytes.
  2. Upon invoking process:
    1. Let buffer be the ArrayBufferView to be processed.
    2. Convert buffer to a sequence of byteLength bytes from the underlying ArrayBuffer, starting at the byteOffset of the ArrayBufferView, and append those bytes to M.
    3. No output is returned.
  3. Upon invoking finish():
    1. Perform the RSAES-PKCS1-V1_5-ENCRYPT operation, as specified in RFC3447, Section 7.2.1, with M as the message, and with n and e obtained from the Key.
    2. If the operation resulted in an error, raise an error and terminate the algorithm.
    3. Let C be an array of bytes resulting from performing the RSAES-PKCS1-V1_5-ENCRYPT operation.
    4. Let output be an ArrayBuffer with enough bytes to hold C.length bytes, with the contents of the underlying buffer initialized to the contents of C.
Decrypt
When decrypting, the resultant CryptoOperation shall behave as follows:
  1. Upon invoking init:
    1. If key does not describe an RSA private key, raise an error and terminate the algorithm.
    2. Let C be an empty sequence of bytes.
  2. Upon invoking process:
    1. Let buffer be the ArrayBufferView to be processed.
    2. Convert buffer to a sequence of byteLength bytes from the underlying ArrayBuffer, starting at the byteOffset of the ArrayBufferView, and append those bytes to C.
    3. No output is returned.
  3. Upon invoking finish():
    1. Perform the RSAES-PKCS1-V1_5-DECRYPT operation, as specified in RFC3447, Section 7.2.2, with C as the ciphertext, and with K obtained from the Key.
    2. If the operation resulted in an error, raise an error and terminate the algorithm.
    3. Let M be an array of bytes resulting from performing the RSAES-PKCS1-V1_5-DECRYPT operation.
    4. Let output be an ArrayBuffer with enough bytes to hold M.length bytes, with the contents of the underlying buffer initialized to the contents of M.
Generate Key

19.4. RSASSA-PKCS1-v1_5

19.4.1. Description

The "RSASSA-PKCS1-v1_5" algorithm identifier is used to perform signing and verification using the RSASSA-PKCS1-v1_5 algorithm specified in [RFC3447].

19.4.2. Registration

The recognized algorithm name for this algorithm is "RSASSA-PKCS1-v1_5".

Operation Parameters Result
sign RsaSsaParams ArrayBufferView?
verify RsaSsaParams boolean?
generateKey RsaKeyGenParams KeyPair?

19.4.3. RsaSsaParams dictionary

IDL

dictionary RsaSsaParams : AlgorithmParameters {
  // The hash algorithm to use 
  AlgorithmIdentifier hash;
};
            

19.4.4. Operations

  • Sign
  • Verify
  • Generate Key

19.5. RSA-PSS

19.5.1. Description

The "RSA-PSS" algorithm identifier is used to perform signing and verification using the RSASSA-PSS algorithm specified in [RFC3447].

19.5.2. Registration

The recognized algorithm name for this algorithm is "RSA-PSS".

Operation Parameters Result
sign RsaPssParams ArrayBufferView?
verify RsaPssParams boolean?
generateKey RsaKeyGenParams KeyPair?

19.5.3. RsaPssParams dictionary

IDL

dictionary RsaPssParams : AlgorithmParameters {
  // The hash function to apply to the message
  AlgorithmIdentifier hash;
  // The mask generation function
  AlgorithmIdentifier mgf;
  // The desired length of the random salt
  unsigned long saltLength;
};
            

19.5.4. Operations

  • Sign
  • Verify
  • Generate Key

19.6. RSA-OAEP

19.6.1. Description

The "RSA-OAEP" algorithm identifier is used to perform encryption and decryption ordering to the RSAES-OAEP algorithm specified in [RFC3447].

19.6.2. Registration

The recognized algorithm name for this algorithm is "RSA-OAEP".

Operation Parameters Result
encrypt RsaOaepParams ArrayBufferView?
decrypt RsaOaepParams ArrayBufferView?
generateKey RsaKeyGenParams KeyPair?

19.6.3. RsaOaepParams dictionary

IDL

dictionary RsaOaepParams : AlgorithmParameters {
  // The hash function to apply to the message
  AlgorithmIdentifier hash;
  // The mask generation function
  AlgorithmIdentifier mgf;
  // The optional label/application data to associate with the message
  ArrayBufferView? label;
};
            

19.6.4. Operations

  • Encrypt
  • Decrypt
  • Generate Key

19.7. ECDSA

19.7.1. Description

The "ECDSA" algorithm identifier is used to perform signing and verification using the ECDSA algorithm specified in [X9.62].

19.7.2. Registration

The recognized algorithm name for this algorithm is "ECDSA".

Operation Parameters Result
sign EcdsaParams ArrayBufferView?
verify EcdsaParams boolean?
generateKey EcKeyGenParams KeyPair?

19.7.3. EcdsaParams dictionary

IDL

dictionary EcdsaParams : AlgorithmParameters {
  // The hash algorithm to use
  AlgorithmIdentifier hash;
};
            

19.7.4. EcKeyGenParams dictionary

IDL

enum NamedCurve {
  // NIST recommended curve P-256, also known as secp256r1.
  "P-256",
  // NIST recommended curve P-384, also known as secp384r1.
  "P-384",
  // NIST recommended curve P-521, also known as secp521r1.
  "P-521"
};

dictionary EcKeyGenParams : AlgorithmParameters {
  // A named curve
  NamedCurve namedCurve;
};
            

The NamedCurve enumeration type represents named elliptic curves, which are a convenient way to specify the domain parameters of well-known elliptic curves.

19.7.5. Operations

Sign
When signing, the resultant CryptoOperation shall behave as follows:
  1. Upon invoking init:
    1. If key does not describe an ECDSA private key, raise an error and terminate this algorithm.
    2. Let M be an empty sequence of bytes.
  2. Upon invoking process:
    1. Let buffer be the ArrayBufferView to be processed.
    2. Convert buffer to a sequence of byteLength bytes from the underlying ArrayBuffer, starting at the byteOffset of the ArrayBufferView, and append those bytes to M.
    3. No output is returned.
  3. Upon invoking finish():
    1. Perform the ECDSA signing process, as specified in X9.62, Section 7.3, with M as the message, with EC domain parameters and private key d obtained from the Key, and with the hash function obtained from the EcdsaParams dictionary.
    2. If the operation resulted in an error, raise an error and terminate this algorithm.
    3. Let r and s be a pair of integers resulting from performing the ECDSA signing process.
    4. Let output be an ArrayBuffer holding the concatenation of r and s, each as a ceil(ceil(log2(n))/8) byte sequence, where n (a prime number) is the order of the base point generator.
Verify
When verifying, the resultant CryptoOperation shall behave as follows:
  1. Upon invoking init:
    1. If key does not describe an ECDSA public key, raise an error and terminate this algorithm.
    2. Let M' be an empty sequence of bytes.
  2. Upon invoking process:
    1. Let buffer be the ArrayBufferView to be processed.
    2. Convert buffer to a sequence of byteLength bytes from the underlying ArrayBuffer, starting at the byteOffset of the ArrayBufferView, and append those bytes to M'.
    3. No output is returned.
  3. Upon invoking finish():
    1. Perform the ECDSA verifying process, as specified in X9.62, Section 7.4, with M' as the received message, with the EC domain parameters and public key Q obtained from the Key, and with the hash function obtained from the EcdsaParams dictionary.
    2. If the operation resulted in an error, raise an error and terminate this algorithm.
    3. Let output be a boolean that indicates whether the purported signature is valid (true) or not (false).
Generate Key

19.8. ECDH

19.8.1. Description

This describes using Elliptic Curve Diffie-Hellman (ECDH) for key generation and key agreement, as specified by X9.63.

19.8.2. Registration

The recognized algorithm name for this algorithm is "ECDH".

Operation Parameters Result
generateKey EcKeyGenParams KeyPair?
deriveKey EcdhKeyDeriveParams Key?

19.8.3. EcdhKeyDeriveParams dictionary

IDL

typedef Uint8Array ECPoint;

dictionary EcdhKeyDeriveParams : AlgorithmParameters {
  // The peer's EC public key.
  ECPoint public;
};
            

The ECPoint typedef is a Uint8Array holding an elliptic curve point. An elliptic curve point is converted to an array of Uint8 elements using the procedure specified in X9.62 Annex A.5.7.

19.8.4. Operations

  • Generate Key
  • Derive Key
  • Perform the standard ECDH primitive specified in X9.63 Section 5.4.1. The output of ECDH key agreement is the x-coordinate of the shared secret value P.

    Note: X9.63 Section 5.4.2 and NIST SP 800-56A Section 5.7.1.2 specify a modified ECDH primitive that multiplies the shared secret value by the cofactor of the curve. The cofactor of the NIST recommended curves P-256, P-384, and P-521 is 1, so the standard and modified ECDH primitives are equivalent for those curves.

19.9. AES-CTR

19.9.1. Description

19.9.2. Registration

The recognized algorithm name for this algorithm is "AES-CTR".

Operation Parameters Result
encrypt AesCtrParams ArrayBufferView?
decrypt AesCtrParams ArrayBufferView?
generateKey AesKeyGenParams Key?

19.9.3. AesCtrParams dictionary

IDL

dictionary AesCtrParams : AlgorithmParameters {
  // The initial value of the counter block. counter MUST be 16 bytes
  // (the AES block size). The counter bits are the rightmost length
  // bits of the counter block. The rest of the counter block is for
  // the nonce. The counter bits are incremented using the standard
  // incrementing function specified in NIST SP 800-38A Appendix B.1:
  // the counter bits are interpreted as a big-endian integer and
  // incremented by one.
  ArrayBuffer counter;
  // The length, in bits, of the rightmost part of the counter block
  // that is incremented.
  [EnforceRange] octet length;
};
            

19.9.4. AesKeyGenParams dictionary

IDL

dictionary AesKeyGenParams : AlgorithmParameters {
  // The length, in bits, of the key.
  [EnforceRange] unsigned short length;
};
            

19.9.5. Operations

  • Encrypt
  • Decrypt
  • Generate Key

19.10. AES-CBC

19.10.1. Description

19.10.2. Registration

The recognized algorithm name for this algorithm is "AES-CBC".

Operation Parameters Result
encrypt AesCbcParams ArrayBufferView?
decrypt AesCbcParams ArrayBufferView?
generateKey AesKeyGenParams Key?

19.10.3. AesCbcParams dictionary

IDL

dictionary AesCbcParams : AlgorithmParameters {
  // The initialization vector. MUST be 16 bytes.
  ArrayBufferView iv;
};
            

19.10.4. Operations

  • Encrypt
  • Decrypt
  • Generate Key

19.11. AES-GCM

19.11.1. Description

19.11.2. Registration

The recognized algorithm name for this algorithm is "AES-GCM".

Operation Parameters Result
encrypt AesGcmParams ArrayBufferView?
decrypt AesGcmParams ArrayBufferView?
generateKey AesKeyGenParams Key?

19.11.3. AesGcmParams dictionary

IDL

dictionary AesGcmParams : AlgorithmParameters {
  // The initialization vector to use. May be up to 2^56 bytes long.
  ArrayBufferView? iv;
  // The additional authentication data to include.
  ArrayBufferView? additionalData;
  // The desired length of the authentication tag. May be 0 - 128.
  [EnforceRange] octet? tagLength = 0;
};
            

19.11.4. Operations

  • Encrypt
  • Decrypt
  • Generate Key

19.12. HMAC

19.12.1. Description

19.12.2. Registration

The recognized algorithm name for this algorithm is "HMAC".

Operation Parameters Result
sign HmacParams ArrayBufferView?
verify HmacParams boolean?
generateKey HmacKeyGenParams Key?

19.12.3. HmacParams dictionary

IDL

dictionary HmacParams : AlgorithmParameters {
  // The inner hash function to use.
  AlgorithmIdentifier hash;
};
            

19.12.4. Operations

  • Sign
  • Verify
  • Generate Key

19.13. Diffie-Hellman

19.13.1. Description

This describes using Diffie-Hellman for key generation and key agreement, as specified by PKCS #3.

19.13.2. Registration

The recognized algorithm name for this algorithm is "DH".

Operation Parameters Result
generateKey DhKeyGenParams KeyPair?
deriveKey DhKeyDeriveParams Key?

19.13.3. DhKeyGenParams dictionary

IDL

dictionary DhKeyGenParams : AlgorithmParameters {
  // The prime p.
  BigInteger prime;
  // The base g.
  BigInteger generator;
};
            

19.13.4. DhKeyDeriveParams dictionary

IDL

dictionary DhKeyDeriveParams : AlgorithmParameters {
  // The peer's public value.
  BigInteger public;
};
            

19.13.5. Operations

  • Generate Key
  • Derive Key

19.14. SHA

19.14.1. Description

This describes the SHA-1 and SHA-2 families, as specified by [FIPS 180-4].

19.14.2. Registration

The following algorithms are added as recognized algorithm names:

"SHA-1"
The SHA-1 algorithm as specified in Section 6.1
"SHA-224"
The SHA-224 algorithm as specified in Section 6.3
"SHA-256"
The SHA-256 algorithm as specified in Section 6.2
"SHA-384"
The SHA-384 algorithm as specified in Section 6.5
"SHA-512"
The SHA-512 algorithm as specified in Section 6.4
Operation Parameters Result
digest None ArrayBufferView?

19.14.3. Operations

  • Digest

19.15. Concat KDF

19.15.1. Description

The "CONCAT" algorithm identifier is used to perform key derivation using the key derivation algorithm defined in Section 5.8.1 of NIST SP 800-56A [SP800-56A].

19.15.2. Registration

The recognized algorithm name for this algorithm is "CONCAT".

Operation Parameters Result
deriveKey ConcatParams Key?

19.15.3. ConcatParams dictionary

IDL

dictionary ConcatParams : AlgorithmParameters {
  // The digest method to use to derive the keying material.
  AlgorithmIdentifier hash;

  // A bit string corresponding to the AlgorithmId field of the OtherInfo parameter.
  // The AlgorithmId indicates how the derived keying material will be parsed and for which
  // algorithm(s) the derived secret keying material will be used.
  ArrayBufferView algorithmId;

  // A bit string that corresponds to the PartyUInfo field of the OtherInfo parameter.
  ArrayBufferView partyUInfo;
  // A bit string that corresponds to the PartyVInfo field of the OtherInfo parameter.
  ArrayBufferView partyVInfo;
  // An optional bit string that corresponds to the SuppPubInfo field of the OtherInfo parameter.
  ArrayBufferView? publicInfo;
  // An optional bit string that corresponds to the SuppPrivInfo field of the OtherInfo parameter.
  ArrayBufferView? privateInfo;
};
            

19.15.4. Operations

  • Derive Key

19.16. PBKDF2

19.16.1. Description

19.16.2. Registration

The recognized algorithm name for this algorithm is "PBKDF2".

Operation Parameters Result
deriveKey Pbkdf2Params Key?

19.16.3. Pbkdf2Params dictionary

IDL

dictionary Pbkdf2Params : AlgorithmParameters {
  ArrayBufferView salt;
  [Clamp] unsigned long iterations;
  AlgorithmIdentifier prf;
  ArrayBufferView? password;
};
            
Editorial note

In the above snippet, password is an optional field. The intent is that conforming user agents MAY support applications that wish to use PBKDF2 by providing password entry via an un-spoofable (by the web application) UI.

19.16.4. Operations

  • Derive Key

20. Algorithm normalizing rules

The AlgorithmIdentifier typedef permits algorithms to be specified as either a dictionary or a DOMString. In order to ensure consistency, conforming user agents must normalize all AlgorithmIdentifier inputs into a single, canonical form. When normalization is indicated, it must act as follows:

  1. Let O be the AlgorithmIdentifier to be normalized.
  2. If O is a DOMString, then:
    1. If O contains any non-ASCII characters, throw a SyntaxError and return from this algorithm.
    2. Convert every character in O to lower case.
    3. If O contains a recognized algorithm alias then let O be re-initialized to the aliased dictionary and this algorithm restarted.
    4. Otherwise, throw an InvalidAlgorithmError exception and return from this algorithm.
  3. Let name be the name member of the Algorithm dictionary.
  4. If name contains any non-ASCII characters, throw a SyntaxError and return from this algorithm.
  5. Convert every character in name to lower case.
  6. If name does not contain a recognized algorithm name, throw an InvalidAlgorithmError exception and return from this algorithm.
  7. Let params be the params member of the Algorithm dictionary.
  8. Process params according to the algorithm-defined algorithm parameter normalizing rules.
  9. If an exception was raised during parameter processing, propagate the exception.
  10. Return an Algorithm object, with its name set to name and its params set to params.

21. JavaScript Example Code

21.1. Generate a signing key pair, sign some data

ECMAScript

// Algorithm Object
var algorithmKeyGen = {
  name: "RSASSA-PKCS1-v1_5",
  // RsaKeyGenParams
  params: {
    modulusLength: 2048,
    publicExponent: new Uint8Array([0x01, 0x00, 0x01]),  // Equivalent to 65537
  }
};

var algorithmSign = {
  name: "RSASSA-PKCS1-v1_5",
  // RsaSsaParams
  params: {
    hash: {
      name: "SHA-256",
    }
  }
};

var keyGen = window.crypto.generateKey(algorithmKeyGen,
                                       false, // extractable
                                       ["sign"]);

keyGen.oncomplete = function(event) {
  // Because we are not supplying data to .sign(), a multi-part
  // CryptoOperation will be returned, which requires us to call .process()
  // and .finish().
  var signer = window.crypt.sign(algorithmSign, event.target.result.privateKey);
  signer.oncomplete = function(event) {
    console.log("The signature is: " + event.target.result);
  }
  signer.onerror = function(event) {
    console.error("Unable to sign");
  }

  var dataPart1 = convertPlainTextToArrayBufferView("hello,");
  var dataPart2 = convertPlainTextToArrayBufferView(" world!");
  // TODO: create example utility function that converts text -> ArrayBufferView

  signer.process(dataPart1);
  signer.process(dataPart2);
  signer.finish();
};

keyGen.onerror = function(event) {
  console.error("Unable to generate a key.");
};
        

21.2. Symmetric Encryption

ECMAScript

var clearDataArrayBufferView = convertPlainTextToArrayBufferView("Plain Text Data");
// TODO: create example utility function that converts text -> ArrayBufferView

var aesAlgorithmKeyGen = {
  name: "AES-CBC",
  // AesKeyGenParams
  params: {
    length: 128
  }
};

var aesAlgorithmEncrypt = {
  name: "AES-CBC",
  // AesCbcParams
  params: {
    iv: window.crypto.getRandomValues(new Uint8Array(16))
  }
};

// Create a keygenerator to produce a one-time-use AES key to encrypt some data
var cryptoKeyGen = window.crypto.generateKey(aesAlgorithmKeyGen,
                                             false, // extractable
                                             ["encrypt"]);

cryptoKeyGen.oncomplete = function(event) {
  // A new, random AES key has been generated.
  var aesKey = event.target.result;

  // Unlike the signing example, which showed multi-part encryption, here we
  // will perform the entire AES operation in a single call.
  var aesOp = window.crypto.encrypt(aesAlgorithmEncrypt, aesKey, clearDataArrayBufferView);
  aesOp.oncomplete = function(event) {
    // The clearData has been encrypted.
    var ciphertext = event.target.result; // ArrayBufferView
  };
  aesOp.onerror = function(event) {
    console.error("Unable to AES encrypt.");
  };
};
        

22. Acknowledgements

The editors would like to thank Adam Barth, Ali Asad, Arun Ranganathan, Brian Smith, Brian Warner, Channy Yun, Kai Engert, Mark Watson, Vijay Bharadwaj, Virginie Galindo, and Wan-Teh Chang for their technical feedback and assistance.

Thanks to the W3C Web Cryptography WG, and to participants on the public-webcrypto@w3.org mailing list.

The W3C would like to thank the Northrop Grumman Cybersecurity Research Consortium for supporting W3C/MIT.

The getRandomValues method in the Crypto interface was originally proposed by Adam Barth to the WHATWG.

23. References

23.1. Normative References

RFC2119
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF.
WebIDL Specification
WebIDL (work in progress), C. McCormack.
DOM4
DOM4 (work in progress), A. Gregor, A. van Kesteren, Ms2ger. W3C.
HTML
HTML5: A vocabulary and associated APIs for HTML and XHTML (work in progress), I. Hickson. W3C.
Typed Arrays
Typed Arrays (work in progress), V. Vukicevic, K. Russell. Khronos Group.
RFC3447
Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1, J. Jonsson, B. Kaliski. IETF.
RFC5208
Public-Key Cryptography Standards (PKCS) #8: Private-Key Information Syntax Specification Version 1.2, B. Kaliski. IETF.
RFC5280
Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, D. Cooper, S. Santesson, S. Farrell, S. Boeyen, R. Housley, W. Polk. IETF.
PKCS3
PKCS #3: Diffie-Hellman Key-Agreement Standard, RSA Laboratories.
X9.62
ANS X9.62–2005: Public Key Cryptography for the Financial Services Industry, The Elliptic Curve Digital Signature Algorithm (ECDSA), ANSI.
X9.63
ANS X9.63–2001: Public Key Cryptography for the Financial Services Industry, Key Agreement and Key Transport Using Elliptic Curve Cryptography, ANSI.
ECMAScript
ECMAScript 5th Edition, A. Wirfs-Brock, P. Lakshman et al.
FIPS 180-4
FIPS PUB 180-4: Secure Hash Standard, NIST.

23.2. Informative References

draft-balfanz-tls-obc-01
TLS Origin-Bound Certificates, D. Balfanz, D. Smetters, M. Upadhyay, A. Barth. IETF.
RFC 5705
Keying Material Exporters for Transport Layer Security (TLS), E. Rescorla. IETF.
PKCS11
PKCS #11: Cryptographic Token Interface Standard, RSA Laboratories.
CryptoAPI
Cryptography Reference, Microsoft Corporation.
CNG
Cryptography API: Next Generation, Microsoft Corporation.
CDSA
Common Security: CDSA and CSSM, Version 2 (with corrigenda), the Open Group.
NIST SP 800-56A
NIST SP 800-56A: Recommendation for Pair-Wise Key Establishment Schemes Using Discrete Logarithm Cryptography (Revised), March 2007, NIST.