Web Cryptography Level 2

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 prefer the richer user experience provided by authenticating within the application itself.

Using the Web Cryptography API, the 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.

This exchange could be further strengthened by binding the authentication to the TLS session over which the client is authenticating, by deriving a key based on properties of the underlying transport.

If a user does 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 choice.

A web application may wish to limit the viewership of documents that contain sensitive or personal information, even when these documents have been securely received, such as over TLS.

Using the Web Cryptography API, the application could do so by encrypting the documents with a secret key, and then wrapping that key with the public keys associated with the authorized viewers. When a user agent navigates to such a web application, the application would 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.

A web application may wish to permit users to protect the confidentiality of data and documents stored with remote service providers prior to uploading.

Using the Web Cryptography API, the application may have a user select a private or secret key, optionally derive an encryption key from the selected key, encrypt the document, and then upload the encrypted data to the service provider using existing APIs.

This use case is similar to the Protected Document Exchange use case, with viewership of the document limited to the user themself.

A web application may wish to accept electronic signatures on documents, in lieu of requiring physical signatures.

Using the Web Cryptography API, the application may direct the user to select a key, which may have been pre-provisioned out-of-band, or generated specifically for the web application. Using this key, the application may perform a signing operation over some data, as proof that the user accepts the document.

A web application may wish to cache data locally, while ensuring that this data cannot be modified in an offline attack.

Using the Web Cryptography API, the application may use a public key contained within the application to verify the contents of the data cache. Previously, when data was added to the cache, it would have been signed by the server with the corresponding private key. By validating the signature when restoring data from the cache, the client ensures that the cached data has not been tampered with.

A web application may wish to employ message layer security using schemes such as off-the-record (OTR) messaging, even when these messages have been securely received, such as over TLS.

The Web Cryptography API enables OTR and similar message signing schemes, by allowing key agreement to be performed. 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.

A web application may wish to interact with the structures and message formats defined by the IETF JavaScript Object Signing and Encryption (JOSE) Working Group.

Using the Web Cryptography API, the application may read and import keys encoded in the JSON key format (JWK), validate messages that have been integrity protected using digital signatures or MACs (JWS), or decrypt messages that have been encrypted (JWE).

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

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 behaviors of individual algorithms, if implemented.

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.

This specification assumes, but does not require, that conforming user agents do not and will not be directly implementing cryptographic operations within the user agent itself. Historically, many user agents have deferred cryptographic operations, such as those used within TLS, to existing APIs that are available as part of the underlying operating system or to third-party modules that are managed independently of the user agent.

The CryptoKey object represents the bridge between the JavaScript execution environment and these underlying libraries, through the use of the internal slot named [[handle]]. The handle represents an opaque type that is implementation specific, which may not be represented within a JavaScript type, nor is it ever exposed to script authors. In this way, the CryptoKey object is the conceptual equivalent to the JavaScript executing environment as the [[handle]] is to the underlying cryptographic implementation.

These APIs are traditionally built around a notion of cryptographic providers, an abstraction for a specific implementation of a set of algorithms. The operating system or library may come with a default provider, and users are frequently allowed to add additional providers, reconfigure the set of enabled algorithms, or otherwise customize how cryptographic services are provided.

While it is assumed that most user agents will be interacting with a cryptographic provider that is implemented purely in software, it is not required by this specification. As a result, the capabilities of some implementations may be limited by the capabilities of the underlying hardware, and, depending on how the user has configured the underlying cryptographic library, this may be entirely opaque to the User Agent.

This specification does not explicitly provide any new storage mechanisms for CryptoKey objects. Instead, by defining serialization and deserialization steps for CryptoKey objects, any existing or future web storage mechanisms that support storing serializable objects can be used to store CryptoKey objects.

In practice, it is expected that most authors will make use of the Indexed Database API [INDEXEDDB], which allows associative storage of key/value pairs, where the key is some string identifier meaningful to the application, and the value is a CryptoKey object. This allows the storage and retrieval of key material, without ever exposing that key material to the application or the JavaScript environment. Additionally, this allows authors the full flexibility to store any additional metadata with the CryptoKey itself.

By not providing an explicit storage mechanism, this specification assumes that CryptoKey objects are scoped to the current execution environment and any storage mechanisms available to that environment (e.g. Indexed Database API). Application authors rely upon this for the security of their applications; two origins with the same CryptoKey object have full access to the underlying key, and as such, messages from these applications cannot be distinguished, and messages sent to these applications can be fully recovered. Implementors should ensure that no CryptoKey objects are shared between two origins unless the author has explicitly chosen to share (e.g., such as through the use of postMessage)

A number of algorithms specified within this specification perform computationally intensive work, such as the generation of significantly large prime numbers, or through repeated iterations of a particular operation. As such, hostile applications may attempt to misuse this API and attempt to cause significant amount of work to be performed by an implementation, denying access or services to other applications that are executing. Implementations should take steps to mitigate these risks, such as limiting the amount of operations an implementation performs concurrently, requiring user consent for operations that may be known to be disruptive for the executing environment, or defining device-specific limits on attributes such as key sizes or iteration counts.

This specification includes descriptions for a variety of cryptographic operations, some of which have known weaknesses when used inappropriately. Application developers must take care and review appropriate and current cryptographic literature, to understand and mitigate such issues. In general, application developers are strongly discouraged from inventing new cryptographic protocols; as with all applications, users of this specification will be best served through the use of existing protocols, of which this specification provides the necessary building blocks to implement.

In order to use the APIs defined in this specification to provide any meaningful cryptographic assurances, authors must be familiar with existing threats to web applications, as well as the underlying security model employed. Conceptually, issues such as script injection are the equivalent to remote code execution in other operating environments, and allowing hostile script to be injected may allow for the exfiltration of keys or data. Script injection may come from other applications, for which the judicious use of Content Security Policy may mitigate, or it may come from hostile network intermediaries, for which the use of Transport Layer Security may mitigate.

This specification does not define any specific mechanisms for the storage of cryptographic keys. By default, unless specific effort is taken by the author to persist keys, such as through the use of the Indexed Database API, keys created with this API will only be valid for the duration of the current page (e.g. until a navigation event). Authors that wish to use the same key across different pages or multiple browsing sessions must employ existing web storage technologies. Authors should be aware of the security assumptions of these technologies, such as the same-origin security model; that is, any application that shares the same scheme, host, and port have access to the same storage partition, even if other information, such as the path, may differ. Authors may explicitly choose to relax this security through the use of inter-origin sharing, such as postMessage.

Authors should be aware that this specification places no normative requirements on implementations as to how the underlying cryptographic key material is stored. The only requirement is that key material is not exposed to script, except through the use of the exportKey and wrapKey operations. In particular, it does not guarantee that the underlying cryptographic key material will not be persisted to disk, possibly unencrypted, nor that it will be inaccessible to users or other applications running with the same privileges as the User Agent. Any application or user that has access to the device storage may be able to recover the key material, even through scripts may be prohibited.

This specification places no normative requirements on how implementations handle key material once all references to it go away. That is, conforming user agents are not required to zeroize key material, and it may still be accessible on device storage or device memory, even after all references to the CryptoKey have gone away.

Applications may share a CryptoKey object across security boundaries, such as origins, through the use of the structured clone algorithm and APIs such as postMessage. While access to the underlying cryptographic key material may be restricted, based upon the extractable attribute, once a key is shared with a destination origin, the source origin can not later restrict or revoke access to the key. As such, authors must be careful to ensure they trust the destination origin to take the same mitigations against hostile script that the source origin employs. Further, in the event of script injection on the source origin, attackers may post the key to an origin under attacker control. Any time that the user agent visits the attacker's origin, the user agent may be directed to perform cryptographic operations using that key, such as the decryption of existing messages or the creation of new, fraudulent messages.

Authors should be aware that users may, at any time, choose to clear the storage associated with an origin, potentially destroying keys. Applications that are meant to provide long-term storage, such as on the server, should consider techniques such as key escrow to prevent such data from being inaccessible. Authors should not presume that keys will be available indefinitely.

Users of applications that employ the APIs defined in this specification should be aware that these applications will have full access to all messages exchanged, regardless of the cryptography employed. That is, for messages that are encrypted, applications that use these APIs will have full access to the decrypted message as well.