Errata for this document will be gathered from issues. Copyright © 2012-2017 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply. 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. This section describes the status of this document at the time of its publication. Other documents may supersede this document. This document is a W3C Recommendation of the Web Cryptography API specification. This document is produced by the Web Cryptography WG of the W3C. An implementation report is also available (as well as reports sent to the mailing list). This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation.
It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web. 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. This document is governed by the 1 September 2015 W3C Process Document. 10.2. Methods and Parameters10.2.1. 14.3. Methods and Parameters14.3.1. A. Mapping between JSON Web Key / JSON Web AlgorithmA.1. 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 SubtleCrypto interface, which defines a set of methods for performing common cryptographic operations. 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 and key import and export. This section is non-normative. 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.
|