Copyright © 2013 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification describes a JavaScript API for discovering named, origin-specific pre-provisioned cryptographic keys for use with the Web Cryptography API. Pre-provisioned keys are keys which have been made available to the UA by means other than the generation, derivation, imporation functions of the Web Cryptography API. Origin-specific keys are keys that are available only to a specified origin. Named keys are identified by a name assumed to be known to the origin in question and provisioned with the key itself.
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 latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is the First Public Working Draft of the WebCrypto Key Discovery recommendation. It defines an API that provides access to named origin-specific pre-provisioned keys. Such keys were previously accessible through the KeyStorage API of the main WebCrypto API, which provided for both key storage and key discovery. The KeyStorage API has been removed in favour of using existing web storage mechanisms for key storage and this specification for named origin-specific pre-provisioned key discovery. The privacy issues associated with such keys require special attention and the privacy related material in this document has not yet received thorough review by the community. It is an open issue in the Web Cryptography Working Group whether the scope of this document may be expanded to discovery of other kinds of key.
This document was published by the Web Cryptography WG as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webcrypto@w3.org (subscribe, archives). All feedback is welcome.
Publication as a Working 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.
This section is non-normative.
The Web Cryptography API [WEBCRYPTO] describes a JavaScript API for performing basic cryptographic
operations in web applications. Cryptographic keys in are represented in this API using
Key objects. The API provides methods to generate, derive or import cryptographic
keying material, so creating Key objects.
This document concerns the discovery of cryptographic keys which are made available to the UA by other means. Specifically, this document provides an API for the discovery of cryptographic keys which have been pre-provisioned into a UA or device for use by a specific origin. Such keys are identified by names which are assumed to be known to the origin in question and thus they are referred to as named origin-specific pre-provisioned keys.
This enables web applications to establish secure proof that the UA has access to a particular pre-provisioned key. Depending on the nature of the key and its associated storage - for example within a Hardware Security Module or available only within a Trusted Execution Environment - further properties of the device on which the UA is running may be inferred.
The use of pre-provisioned keys requires the informed consent of the user, because such keys may be used for tracking and may reveal information about the users device. The privacy implications of origin-specific pre-provisioned keys are discussed further in Security and Privacy Considerations.
Web applications may wish to use keys that have been provisioned through means outside the scope of the WebCrypto API. This may include keys that are provisioned through platform-specific native APIs, stored in secure elements such as trusted platform modules (TPMs), individually bound to devices at time of manufacturing or otherwise installed via device-specific provisioning protocols.
Such keys may, for example, be used to assist in identifying a device to a specific web service. User agents may choose to expose such keys to web applications after implementing appropriate security and privacy mitigations, including gaining user consent.
In this scenario, a web application discovers a pre-provisioned key based on its name 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 device and customizing its responses based on that.
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 key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
The following conformance classes are defined by this specification:
A user agent is considered to be a conforming user agent if it satisfies all of the must-, required- and shall-level criteria in this specification that apply to implementation. This specification uses both the terms "conforming user agent" and "user agent" to refer to this product class.
User agents may implement algorithms in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained from the specification's algorithms.
User agents that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL] as this specification uses that specification and terminology.
This section is non-normative.
The considerations in the Scope section of [WEBCRYPTO] apply to this specification as well. In particular, although this specification directly addresses the discovery of named origin-specific pre-provisioned keys, it does not address the processes used to provision those keys or the type and properties of the hardware or software components in which they are stored.
This section is non-normative.
The Privacy considerations of [WEBCRYPTO] apply to this specification.
This section is non-normative.
A third-party host (or any object capable of getting content distributed to multiple sites) could use a named origin-specific pre-provisioned key to track a user across multiple sessions, building a profile of the user's activities. In conjunction with a site that is aware of the user's real identity (for example an e-commerce site that requires authenticated credentials), this could allow oppressive groups to target individuals with greater accuracy than in a world with purely anonymous Web usage.
There are a number of techniques that can be used to mitigate this risk of tracking without user consent:
User agents should require the user to explicitly authorize access to named origin-specific pre-provisioned keys before a site can use the keys.
User agents should enable users to revoke this authorization either temporarily or permanently.
User agents may restrict access to named origin-specific pre-provisioned keys to scripts originating at the domain of the top-level document of the browsing context, for instance returning empty key search results for pages from other domains running in iframes.
User agents should present the named origin-specific pre-provisioned keys feature to the user in a way that associates it strongly with HTTP session cookies. [COOKIES]
This might encourage users to view such keys with healthy suspicion.
User agents may record the origins of sites that contained content from third-party origins that used pre-provisioned keys.
If this information is then used to present a view of pre-provisioned keys to the user, it would allow the user to make informed decisions about authorizing sites to make use of keys. Combined with a blacklist ("delete this key" or "prevent this domain from ever accessing this key again"), the user can restrict the use of pre-provisioned keys to sites that he trusts.
User agents may allow users to share their pre-provisioned key domain blacklists.
This would allow communities to act together to protect their privacy.
While these suggestions prevent trivial use of this feature for user tracking, they do not block it altogether. Where a browser supports a mode of operation intended to preserve user anonymity, access to pre-provisioned keys should be disabled in this mode. Even so, within a single domain, a site can continue to track the user during a session, and can then pass all this information to the third party along with any identifying information (names, credit card numbers, addresses) obtained by the site. If a third party cooperates with multiple sites to obtain such information, a profile can still be created.
However, user tracking is to some extent possible even with no cooperation from the user agent whatsoever, for instance by using session identifiers in URLs, a technique already commonly used for innocuous purposes but easily repurposed for user tracking (even retroactively). This information can then be shared with other sites, using visitors' IP addresses and other user-specific data (e.g. user-agent headers and configuration settings) to combine separate sessions into coherent user profiles.
User agents should treat pre-provisioned keys and material generated using such keys as potentially sensitive; it is quite possible for the user privacy to be compromised by the release of this information.
To this end, user agents should ensure that when deleting data, it is promptly deleted from the underlying storage.
This specification relies on several other underlying specifications.
Window,
Function,
origin, same origin, structured clone,
structured clone algorithm, task, task source,
queue a task
and fire a simple event are defined by the HTML 5
specification [HTML5].
A conforming user agent must support the Web Cryptography API [WEBCRYPTO].
The terms Key and KeyOperation are defined in [WEBCRYPTO].
WorkerGlobalScope is defined by
the WebWorkers specification [WEBWORKERS].This section is non-normative.
This specification defines a new cryptokeys attribute on the Window and WorkerGlobalScope objects. This attribute is an object supporting a method, getkeysByName which may be used to get an array of all keys matching a DOMString name specifier. Keys are returned as NamedKey objects which are subclasses of the Key class.
interface NamedKey : Key {
readonly attribute DOMString name;
readonly attribute DOMString? id;
};id of type DOMString, readonly, nullableA global identifier associated with the key.
Origin-specific pre-provisioned keys are frequently provisioned with associated identifiers. Where an identifier exists that uniquely identifies the key amongst all keys pre-provisoned with the same origin and name and if this identifier can be canonically expressed as a sequence of no more than 256 bytes, then this identifier should be exposed, base64 encoded, as the id. If no identifier matching these conditions exists, id must be null.
The inclusion and definition of this identifier is the subject of ISSUE-25.
name of type DOMString, readonlyA local identifier for the key.
When a user agent is required to obtain a structured clone of a NamedKey object, it must run the following steps.
NamedKey object to be cloned.NamedKey object, where the structured clone algorithm is followed for the base Key object.nameidThe name and id attributes of a NamedKey object shall not change. The underlying cryptographic key shall not change, except that it may be removed altogether. In this case any attempt to use the NamedKey object shall return an error.
[NoInterfaceObject]
interface CryptoKeys {
KeyOperation getKeysByName (DOMString name);
};getKeysByNameWhen invoked, this method must perform the following steps:
KeyOperation interfacename. A name specifier matches the name of a key if they are identical when expressed as a string of unicode characters.
result attribute of KeyOp be an object of type NamedKey[] containing the keysonsuccessat KeyOponerror at KeyOpA name specifier matches the name of a key if they are identical when expressed as a string of unicode characters. If no matching keys are found, and empty array is returned.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| name | DOMString | ✘ | ✘ |
KeyOperationpartial interface Window {
readonly attribute CryptoKeys cryptokeys;
};cryptokeys of type CryptoKeys, readonlypartial interface WorkerGlobalScope {
readonly attribute CryptoKeys cryptokeys;
};cryptokeys of type CryptoKeys, readonly