Web Cryptography API

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

2.8. Out-of-Band Key Provisioning

Web applications may wish to use keys that have been provisioned through means outside the scope of this API. This may include keys that are provisioned through platform-specific native APIs, stored in secure elements such as smart cards or trusted platform modules (TPMs), or individually bound to devices at time of manufacturing. Such keys may, for example, be used to assist in identifying a client to a specific web service. User agents may choose to expose such keys to web applications after implementing appropriate security and privacy mitigations, such as gaining user consent or other out-of-band authorization.

In this scenario, a web application discovers a pre-provisioned key based on its attributes and uses it to perform authorized cryptographic operations as part of a protocol with a server. The server may utilize knowledge obtained out-of-band regarding the key's provisioning to make access control and policy decisions, such as inferring the identity of the user and/or device and customizing its responses based on that.

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 is specific to one or two implementations. As such this API allows key generation, management, exchange and discovery with a level of abstraction that avoids developers 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 the API in this specification provides a means for applications to request that keying material be kept private from a web application, this should not be misinterpreted as providing secure key storage. The only guarantee is that the application should not be able to extract the raw key material directly, not that the key is protected from users with access to the device. For example, a conforming user agent may choose to store the key material unencrypted in plain text on device storage, which would permit any user with access to the device access to the key. Alternatively, applications that have been granted access to the key may be able to use certain algorithms and messages to act as an oracle, recovering key material through a combination of messages. Thus, because the security of the key cannot be guaranteed by this API, application developers are encouraged to provide a means for users to revoke keys or to address key compromise.

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, 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. 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?

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

10. Key interface

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

IDL



// TBD: ISSUE-17
interface KeyAttributes {
  getter DOMString getAttribute(DOMString name);
  setter creator void setAttribute(DOMString name, DOMString value);
  deleter void removeAttribute(DOMString name);
};


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

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

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

  // TBD: ISSUE-16
  readonly attribute Date? startDate;
  readonly attribute Date? endDate;

  // TBD: ISSUE-17
  // TBD: ISSUE-25
  attribute KeyAttributes extra;
};

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

10.2. Key interface members

id

For all Keys visible within a given origin, each Key shall have a unique, opaque identifier assigned that may be used to uniquely identify that Key within the set of keys.

Within the same origin, if two Keys are created from the same underlying keying material, they MUST share the same id.

Within multiple origins, if two Keys are created from the same underlying keying material, they SHOULD be assigned distinct key identifiers.

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.

temporary

Whether or not the keying material persists beyond the lifetime of the current top-level browsing context.

algorithm

The Algorithm used to generate the key.

keyUsage

An Array of KeyUsages that indicate what CryptoOperations may be used with this key.

startDate

The effective start date for the validity of the key. This is not enforced by the Web Cryptography API, and is provided for informative purposes only. May be null, indicating that the start date is unknown or undefined.

Editorial note

ISSUE-16 TBD: The semantics of key expiration.

endDate

The effective end date for the validity of the key. This is not enforced by the Web Cryptography API, and is provided for informative purposes only. May be null, indicating that the end date is unknown or undefined.

Editorial note

ISSUE-16 TBD: The semantics of key expiration.

extra

Application-defined attributes that are associated with a key.

Editorial note

ISSUE-17 TBD: Whether or not key-specific storage is exposed to the application or if it is left up to Web Storage or IndexedDB.

ISSUE-25 TBD: Whether pre-provisioned keys should support some well-known attribute that defines a pre-provisioned ID, or whether such definitions are application-specific and not part of the spec.

11. CryptoOperation interface

IDL


interface CryptoOperation : EventTarget {
  void init();
  void processData(ArrayBufferView buffer);
  void complete();
  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? oninit;
  [TreatNonCallableAsNull] attribute Function? onprogress;
  [TreatNonCallableAsNull] attribute Function? oncomplete;
};

Editorial note

ISSUE-22: Should CryptoOperations be clonable? If so, under what states?
ISSUE-23: Should CryptoOperations be transferable?

11.1. CryptoOperation states

The CryptoOperation can be in any one of five states. This state is tracked internal to the CryptoOperation and may be used to determine what methods may be called.

"empty": The CryptoOperation has been constructed, and init() has not yet been called. This is the default state of a newly constructed CryptoOperation object, until init() is called.
"initializing": The CryptoOperation is in the midst of performing necessary initialization steps as the result of init() being called. The CryptoOperation is not yet ready to accept data supplied via processData().
"processing": The CryptoOperation has completed initialization and is ready to process data. More data to be processed may be supplied via processData(), or the operation may be concluded by calling complete().
"completing": The CryptoOperation is in the midst of performing the necessary finishing steps to compute the final result, as a result of calling the complete() method. No further data may be provided via the processData() method.
"complete": The CryptoOperation has finished processing data, OR an error occurred during initialization, OR an error occurred during processing, OR the operation was aborted using abort(). The CryptoOperation is no longer able to be used to process data.

11.2. The CryptoOperation Task Source

The CryptoOperation interface enables asynchronous cryptographic processing by firing events. Unless stated otherwise, the task source that is used in this specification is the CryptoOperation. This task source is used for events that are asynchronously fired, and for event tasks that are queued for firing.

11.3. 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
oninit	init
onprogress	progress
oncomplete	complete

11.4. 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 the internal state of the CryptoOperation is the "empty" state, then the result attribute MUST return null.
On getting, if an error in performing the operation has occurred, then the result attribute MUST return null.

11.5. Methods and Parameters

11.5.1. The `init` method

When init method is called, the user agent must run the steps below.

If the internal state is not in the "empty" state, throw an InvalidStateError exception [DOM4] and terminate the algorithm.
Set the internal state to "initializing".
Return from the init() method, but continue processing the steps in this algorithm.
If an error occurs during initialization, set the internal state to complete and set result to null. Proceed to the error steps below.
1. Fire an event called error.
2. Terminate this algorithm.
When the CryptoOperation is fully initialized, set the state to processing.
Fire an event called init.
Terminate this algorithm.

11.5.2. The `processData(ArrayBufferView buffer)` method

When processData(ArrayBufferView buffer) method is called, the user agent must run the steps below.

If the internal state is not in the "processing" state, throw an InvalidStateError exception [DOM4] and terminate the algorithm.
Return from the processData() method, but continue processing the steps in this algorithm.
If an error occurs during processing, set the internal state to complete and set result to null. Proceed to the error steps below.
1. Fire an event called error.
2. Terminate this algorithm.
Perform the algorithm-specific processing.
If processing resulted in output, perform the following steps.
1. Queue a task to update result with the output
2. Fire an event called progress.
Terminate this algorithm.

11.5.3. The `complete()` method

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

If the internal state is not in the "processing" state, throw an InvalidStateError exception [DOM4] and terminate the algorithm.
Set the internal state to completing.
Return from the complete() method, but continue processing the steps in this algorithm.
If an error occurs during processing, set the internal state to complete and set result to null. Proceed to the error steps below.
1. Fire an event called error.
2. Terminate this algorithm.
Perform the algorithm-specific processing.
Let output be the result of the algorithm-specific processing.
Queue a task to update result with the output
Fire an event called progress.
Set the internal state to complete.
Fire an event called complete.
Terminate this algorithm.

11.5.4. The `abort()` method

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

If the internal state is either "empty" or "complete", set result to null and terminate this overall set of steps without doing anything else.
If the internal state is "initializing", then perform the following steps:
1. Set the internal state to "complete".
2. Set result to null.
3. Terminate the algorithm for the init() method.
If the internal state is "processing", then perform the following steps:
1. Set the internal state to "complete".
2. Set result to null.
3. Terminate the algorithm for the processData() method.
If the internal state is "completing", then perform the following steps:
1. Set the internal state to "complete".
2. Set result to null.
3. Terminate the algorithm for the complete() method.
If there are any tasks from the object's CryptoOperation task source in one of the task queues, then remove those tasks.
Fire an event called abort.

12. KeyOperation interface

IDL


interface KeyOperation : EventTarget {
  readonly attribute any result;

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

13. KeyGenerator interface

IDL


interface KeyGenerator : KeyOperation {
  void generate();
};

14. KeyDeriver interface

IDL


interface KeyDeriver : KeyOperation {
  void derive();
};

15. KeyImporter interface

IDL


enum KeyFormat {
  // An unformatted sequence of bytes. Intended for secret keys.
  "raw",
  // The BER encoding of the RSAPublicKey structure from RFC 3447.
  // Only usable with RSA keys.
  "pkcs1-public",
  // The BER encoding of the RSAPrivateKey structure from RFC 3447.
  // Only usable with RSA keys.
  "pkcs1-private",
  // The BER encoding of the PrivateKeyInfo structure from RFC 5208.
  "pkcs8",
  // The key is represented as JSON according to the JSON Web Key format.
  "jwk",
};

interface KeyImporter : KeyOperation {
  void import();
  
  readonly attribute KeyFormat format;
};

16. KeyExporter interface

IDL


interface KeyExporter : KeyOperation {
  void export();

  readonly attribute KeyFormat format;
};

17. KeyStorage interface

IDL


interface KeyStorage {
  readonly attribute unsigned long length;

  getter Key getKey(unsigned long index);
  deleter void removeKey(unsigned long index);

  getter Key getKeyById(DOMString keyId);
  deleter void removeKeyById(DOMString keyId);
  void clear();
};

Each KeyStorage object provides access to a collection of Key objects that have been previously been authorized for an origin.

Each KeyStorage object is associated with a list of Keys when it is created, as defined in the section on the keys attribute.

An object storage implementing KeyStorage supports indexed properties with indices in the range 0 ≤ index < storage.length

Such objects also support a named property for every name that, if passed to getKeyById, would return a non-null value.

The length attribute must return the number of keys present in the KeyStorage.

The supported property names on a KeyStorage object are the values of the id attribute of all Key objects within storage.

The getKeyById(keyId) method must first check to see if there exists within the list a Key object whose id attribute is equal to keyId. If no such Key exists within the list, then this method must return null.

Editorial note

ISSUE-31: KeyStorage is currently a synchronous API, but, depending on implementation, may need to access storage such as disk or secure element.
ISSUE-31: KeyStorage does not provide a way to discover keys based on particular attributes, either intrinsic attributes or custom, user-defined attributes.

18. Crypto interface

IDL


// TBD: ISSUE-37
interface Crypto {
  CryptoOperation createEncrypter(AlgorithmIdentifier algorithm, Key key);
  CryptoOperation createDecrypter(AlgorithmIdentifier algorithm, Key key);
  CryptoOperation createSigner(AlgorithmIdentifier algorithm, Key key);
  CryptoOperation createVerifier(AlgorithmIdentifier algorithm, Key key, ArrayBufferView signature);
  CryptoOperation createDigester(AlgorithmIdentifier algorithm);

  // TBD: ISSUE-36
  KeyGenerator createKeyGenerator(AlgorithmIdentifier algorithm,
                           bool temporary = true,
                           bool extractable = false,
                           KeyUsage[] keyUsages = []);
  KeyDeriver createKeyDeriver(AlgorithmIdentifier algorithm,
                         Key baseKey,
                         AlgorithmIdentifier? derivedKeyType,
                         bool temporary = true,
                         bool extractable = false,
                         KeyUsage[] keyUsages = []);
  
  // TBD: ISSUE-35
  KeyImporter createKeyImporter(KeyFormat format,
                         ArrayBufferView key,
                         AlgorithmIdentifier? algorithm,
                         bool temporary = true,
                         bool extractable = false,
                         KeyUsage[] keyUsages = []);
  KeyExporter createKeyExporter(KeyFormat format, Key key);
  readonly attribute KeyStorage keys;

  ArrayBufferView getRandomValues(ArrayBufferView array);
};

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.
ISSUE-26: When generating, importing, or deriving a key, should it be possible to specify multiple origins that the key is automatically authorized for, beyond the current origin executing the script?
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?
ISSUE-37: Consider alternative method naming schemes, to reduce the use of "create" as a prefix and "er" as a suffix, including the possible use of distinct objects with defined Constructors.

18.1. Methods and Parameters

18.1.1. The createEncrypter method

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

Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.
If normalizedAlgorithm does not describe a registered algorithm that supports the encrypt operation, throw a NotSupportedError and terminate the algorithm.
Return a new CryptoOperation object S with the following characteristics:
1. S.algorithm = normalizedAlgorithm.
2. S.key = key.
3. S.result = null.

18.1.2. The createDecrypter method

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

Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.
If normalizedAlgorithm does not describe a registered algorithm that supports the decrypt operation, throw a NotSupportedError and terminate the algorithm.
Return a new CryptoOperation object S with the following characteristics:
1. S.algorithm = normalizedAlgorithm.
2. S.key = key.
3. S.result = null.

18.1.3. The createSigner method

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

Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.
If normalizedAlgorithm does not describe a registered algorithm that supports the sign operation, throw a NotSupportedError and terminate the algorithm.
Return a new CryptoOperation object S with the following characteristics:
1. S.algorithm = normalizedAlgorithm.
2. S.key = key.
3. S.result = null.

18.1.4. The createVerifier method

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

Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.
If normalizedAlgorithm does not describe a registered algorithm that supports the verify operation, throw a NotSupportedError and terminate the algorithm.
Return a new CryptoOperation object S with the following characteristics:
1. S.algorithm = normalizedAlgorithm.
2. S.key = key.
3. S.result = null.

18.1.5. The createDigester method

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

Let normalizedAlgorithm be the result of processing algorithm according to the algorithm normalizing rules.
If normalizedAlgorithm does not describe a registered algorithm that supports the digest operation, throw a NotSupportedError and terminate the algorithm.
Return a new CryptoOperation object S with the following characteristics:
1. S.algorithm = normalizedAlgorithm.
2. S.key = null.
3. S.result = null.

18.1.6. The createKeyGenerator method

Editorial note

ISSUE-26: Should callers be allowed to specify a list of origins to authorized the key to be shared with?
ISSUE-16: Should callers be able to specify key lifetime?

18.1.7. The createKeyDeriver method

18.1.8. The createKeyImporter method

18.1.9. The createKeyExporter method

18.1.10. The keys attribute

The keys attribute provides access to the key storage of a particular origin. Keys that have been generated by, imported into, or have otherwise had access granted, such as through out-of-band pre-provisioning, will be available through this method.

Editorial note

The availability of Key objects via this attribute does not necessarily mean that the underlying keying material is available to be used. For example, if a user agent were to generate keying material on removable storage, it may register that there exists an authorized Key, but attempting to use it with any CryptoOperation or KeyOperation may cause an error to be raised once it was discovered that the underlying key was not available.

It is expected that the user agent will not need to attempt to obtain the underlying keying material when returning a Key. Instead, the underlying keying material is obtained when instantiating a CryptoOperation that makes use of the key.

18.1.11. The getRandomValues method

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

If array is not of an integer type (i.e., Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, or Uint32Array), throw a TypeMismatchError and terminate the algorithm.
If the byteLength of array is greater than 65536, throw a QuotaExceededError and terminate the algorithm.
Overwrite all elements of array with cryptographically random values of the appropriate type.
Return array.

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

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

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

21. NamedCurve

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"
};

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

22. ECPoint

IDL


typedef Uint8Array ECPoint;

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.

23. Algorithms

23.1. Recommended algorithms

This section is non-normative

As the API is meant to be extensible in order to keep up with future developments within cryptography and to provide flexibility, there are no strictly required algorithms. Thus users of this API should check to see what algorithms are currently recommended and supported by implementations.

However, in order to promote interoperability for developers, there are a number of recommended algorithms. The recommended algorithms are:

HMAC using SHA-256
RSASSA-PKCS1-v1_5 using SHA-256
ECDSA using P-256 curve and SHA-256
AES-CBC

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

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

23.2.2. Supported operations

Each registered algorithm MUST define the operations that it supports.

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

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

23.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?

23.3. RSAES-PKCS1-v1_5

23.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].

23.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?

23.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;
};

23.3.4. Operations

Encrypt

When encrypting, the resultant CryptoOperation shall behave as follows:

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.
Upon invoking processData:
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.
Upon invoking complete:
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:

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.
Upon invoking processData:
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.
Upon invoking complete:
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

When generating a key pair, the resultant KeyGenerator shall behave as follows:

23.4. RSASSA-PKCS1-v1_5

23.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].

23.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?

23.4.3. RsaSsaParams dictionary

IDL


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

23.4.4. Operations

Sign
Verify
Generate Key

23.5. RSA-PSS

23.5.1. Description

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

23.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?

23.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;
};

23.5.4. Operations

Sign
Verify
Generate Key

23.6. RSA-OAEP

23.6.1. Description

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

23.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?

23.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;
};

23.6.4. Operations

Encrypt
Decrypt
Generate Key

23.7. ECDSA

23.7.1. Description

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

23.7.2. Registration

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

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

23.7.3. EcdsaParams dictionary

IDL


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

23.7.4. EcKeyGenParams dictionary

IDL


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

23.7.5. Operations

Sign

When signing, the resultant CryptoOperation shall behave as follows:

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.
Upon invoking processData:
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.
Upon invoking complete:
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:

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.
Upon invoking processData:
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.
Upon invoking complete:
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

When generating a key pair, the resultant KeyGenerator shall behave as follows:

23.8. ECDH

23.8.1. Description

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

23.8.2. Registration

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

Operation	Parameters	Result
generateKey	EcKeyGenParams	KeyPair?
deriveKey	EcdhKeyDeriveParams	Key?

23.8.3. EcdhKeyDeriveParams dictionary

IDL


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

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

23.9. AES-CTR

23.9.1. Description

23.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?

23.9.3. AesCtrParams dictionary

IDL


dictionary AesCtrParams : AlgorithmParameters {
  // The initial value of the counter. counter MUST be 16 bytes.
  ArrayBuffer counter;
  // The length, in bits, of the counter
  [EnforceRange] octet length;
};

Editorial note

ISSUE-27: Should the caller be able to specify where the block-counter bits appear? Some protocols use the least significant bits, others use the most significant bits.

23.9.4. AesKeyGenParams dictionary

IDL


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

23.9.5. Operations

Encrypt
Decrypt
Generate Key

23.10. AES-CBC

23.10.1. Description

23.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?

23.10.3. AesCbcParams dictionary

IDL


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

23.10.4. Operations

Encrypt
Decrypt
Generate Key

23.11. AES-GCM

23.11.1. Description

23.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?

23.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;
};

23.11.4. Operations

Encrypt
Decrypt
Generate Key

23.12. HMAC

23.12.1. Description

23.12.2. Registration

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

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

23.12.3. HmacParams dictionary

IDL


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

23.12.4. Operations

Sign
Verify
Generate Key

23.13. Diffie-Hellman

23.13.1. Description

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

23.13.2. Registration

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

Operation	Parameters	Result
generateKey	DhKeyGenParams	KeyPair?
deriveKey	DhKeyDeriveParams	Key?

23.13.3. DhKeyGenParams dictionary

IDL


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

23.13.4. DhKeyDeriveParams dictionary

IDL


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

23.13.5. Operations

Generate Key
Derive Key

23.14. SHA

23.14.1. Description

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

23.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?

23.14.3. Operations

Digest

23.15. PBKDF2

23.15.1. Description

23.15.2. Registration

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

Operation	Parameters	Result
deriveKey	Pbkdf2Params	Key?

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

23.15.4. Operations

Derive Key

24. 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:

Let O be the AlgorithmIdentifier to be normalized.
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.
Let name be the name member of the Algorithm dictionary.
If name contains any non-ASCII characters, throw a SyntaxError and return from this algorithm.
Convert every character in name to lower case.
If name does not contain a recognized algorithm name, throw an InvalidAlgorithmError exception and return from this algorithm.
Let params be the params member of the Algorithm dictionary.
Process params according to the algorithm-defined algorithm parameter normalizing rules.
If an exception was raised during parameter processing, propagate the exception.
Return an Algorithm object, with its name set to name and its params set to params.

25. JavaScript Example Code

25.1. Generate a signing key pair, sign some data

ECMAScript


var publicExponent = new Uint8Array([0x01, 0x00, 0x01]); 

// Algorithm Object
var algorithmKeyGen = {
  name: "RSASSA-PKCS1-v1_5",
  // RsaKeyGenParams
  params: {
    modulusLength: 2048,
    publicExponent: publicExponent
  }
};

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

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

keyGen.oncomplete = function onKeyGenComplete(event)
{
  // The keyGen operation is complete
  console.log("Public Key ID: " + event.target.result.publicKey.id);

  // create a "signer" CryptoOperation object
  var signer = window.crypto.createSigner(algorithmSign, event.target.result.privateKey.id);
  signer.oncomplete = function signer_oncomplete(event)
  {
    console.log("The signer CryptoOperation is finished, the signature is: " +
                event.target.result);
  };
  signer.onerror = function signer_onerror(event)
  {
    console.log("The signer CryptoOperation failed");
  };

  signer.oninit = function signer_oninit(event)
  {
    signer.processData(myData);
  };

  signer.onprogress = function signer_onprogress(event)
  {
    signer.complete();
  };

  // Sign some data:
  signer.init();
};

keyGen.onerror = function onKeyGenError(event)
{
  console.error("KeyGen failed");
};

// Generate the keypair, the key object is available inside the oncomplete handler
keyGen.generate();

25.2. Key Storage

ECMAScript


var encryptionKey = window.keys.getKeyById("78966b83-b003-46ac-8122-3771e9d7f78");

// This key is no longer needed, I should remove it:
window.keys.removeKeyById(encryptionKey.id);

var otherEncryptionKey = window.keys.getKeyById("5edbeebe-bbbf-4d60-9846-8bbdb81e3215");

25.3. 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 myIV = new Uint8Array(16);

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

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

cryptoKeyGen.oncomplete = function ckg_onComplete(event)
{

  // Optionally get the keyId and key via the id:
  // var aesKeyId = event.target.result.id;
  // var aesKey = window.crypto.keys.getKeyByKeyId(aesKeyId);


  var aesKey = event.target.result;

  var aesSymmetricCryptoOp = window.crypto.createEncrypter(aesAlgorithmEncrypt, aesKey);
  aesSymmetricCryptoOp.oncomplete = function aes_oncomplete(event)
  {
    // the clearData array has been encrypted
    var resultCipherDataArrayBufferView = event.target.result; // ArrayBufferView
  };

  aesSymmetricCryptoOp.oninit = function aes_oninit(event)
  {
    aesSymmetricCryptoOp.processData(clearDataArrayBufferView);
  };

  aesSymmetricCryptoOp.onprogress = function aes_onprogress(event)
  {
    aesSymmetricCryptoOp.complete();
  };

  aesSymmetricCryptoOp.onerror = function aes_onerror(event)
  {
    console.error("AES encryption failed");
  };

  aesSymmetricCryptoOp.init();
};

cryptoKeyGen.generate();

26. 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 getRandomValues method in the Crypto interface was originally proposed by Adam Barth to the WHATWG.

27. References

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

27.2. Informative References

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.

Web Cryptography API

W3C Working Draft 13 September 2012

Abstract

Status of this Document

Table of Contents

1. Introduction

2. Use Cases

2.1. Multi-factor Authentication

2.2. Protected Document Exchange

2.3. Cloud Storage

2.4. Document Signing

2.5. Data Integrity Protection

2.6. Secure Messaging

2.7. Javascript Object Signing and Encryption (JOSE)

2.8. Out-of-Band Key Provisioning

3. Conformance

4. Scope

4.1. Level of abstraction

4.2. Cryptographic algorithms

4.3. Operations

4.4. Out of scope

5. Security considerations

5.1. Security considerations for implementers

5.2. Security considerations for developers

6. Privacy considerations

7. Dependencies

8. Terminology

9. Algorithm dictionary

9.1. Algorithm Dictionary Members

10. Key interface

10.1. Description

10.2. Key interface members

11. CryptoOperation interface

11.1. CryptoOperation states

11.2. The CryptoOperation Task Source

11.3. Event Handler Attributes

11.4. Attributes

11.5. Methods and Parameters

11.5.1. The init method

11.5.2. The processData(ArrayBufferView buffer) method

11.5.3. The complete() method

11.5.4. The abort() method

12. KeyOperation interface

13. KeyGenerator interface

14. KeyDeriver interface

15. KeyImporter interface

16. KeyExporter interface

17. KeyStorage interface

18. Crypto interface

18.1. Methods and Parameters

18.1.1. The createEncrypter method

18.1.2. The createDecrypter method

18.1.3. The createSigner method

18.1.4. The createVerifier method

18.1.5. The createDigester method

18.1.6. The createKeyGenerator method

18.1.7. The createKeyDeriver method

18.1.8. The createKeyImporter method

18.1.9. The createKeyExporter method

18.1.10. The keys attribute

18.1.11. The getRandomValues method

19. BigInteger

20. KeyPair

21. NamedCurve

22. ECPoint

23. Algorithms

23.1. Recommended algorithms

23.2. Defining an algorithm

23.2.1. Recognized algorithm name

23.2.2. Supported operations

23.2.3. Algorithm-specific parameters

23.2.4. Algorithm results

23.2.5. Algorithm aliases

23.3. RSAES-PKCS1-v1_5

23.3.1. Description

23.3.2. Registration

23.3.3. RsaKeyGenParams dictionary

23.3.4. Operations

23.4. RSASSA-PKCS1-v1_5

23.4.1. Description

11.5.1. The `init` method

11.5.2. The `processData(ArrayBufferView buffer)` method

11.5.3. The `complete()` method

11.5.4. The `abort()` method