Abstract
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, importation 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.
Status of This Document
This section describes the status of this document at the time of its publication. Other
documents may supersede this document. A list of current W3C publications and the latest revision
of this technical report can be found in the W3C technical reports
index at http://www.w3.org/TR/.
This document 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 comments are 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.
2. Use cases
2.1 Out of band key provisioning
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.
6. Dependencies
This specification relies on several other underlying specifications.
- HTML5
- The terms and algorithms
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].
- Web Cryptography API
A conforming user agent MUST support the Web Cryptography API [WEBCRYPTO].
The terms Key and KeyOperation are defined in [WEBCRYPTO].
- WebIDL
- Many of the interface definitions and all of the IDL in this spec depends on [WEBIDL].
- WebWorkers
- The term
WorkerGlobalScope is defined by
the WebWorkers specification [WEBWORKERS].
7. API definition
7.2 NamedKey interface
interface NamedKey : Key {
readonly attribute DOMString name;
readonly attribute DOMString? id;
};7.2.1 Attributes
id of type DOMString, readonly , nullable-
A 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.
Note
The inclusion and definition of this identifier is the subject of ISSUE-25.
name of type DOMString, readonly A local identifier for the key.
7.2.2 Structured clone algorithm
When a user agent is required to obtain a structured clone of a NamedKey object, it must run the following steps.
- Let input and memory be the corresponding inputs defined by the internal structured clone algorithm, where input is a
NamedKey object to be cloned.
- Let output be a newly constructed
NamedKey object, where the structured clone algorithm is followed for the base Key object.
- Let the following attributes of output be equal to the value obtained by invoking the internal structured clone algorithm recursively, using the corresponding attribute on input as the new "input" argument and memory as the new "memory" argument:
7.2.3 Immutability of NamedKey objects
The 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.
7.3 CryptoKeys interface
[NoInterfaceObject]
interface CryptoKeys {
Promise getKeyByName (DOMString name);
};7.3.1 Methods
getKeyByName-
When invoked, this method must perform the following steps:
- Let promise be a new
Promise and resolver its associated resolver
- Return promise and continue executing the following steps asynchronously:
- Search for a key matching the name specifier provided in
name. A name specifier matches the name of a key if they are identical when expressed as a string of unicode characters.
- If a key is found
-
- Let the result be an object of type
NamedKey representing the key
- Execute resolver's
resolve(value) algorithm with result as the value argument
- Otherwise
- Execute resolver's
resolve(value) algorithm with null as the value argument
| Parameter | Type | Nullable | Optional | Description |
|---|
| name | DOMString | ✘ | ✘ | |
7.4 Extension of Window interface
partial interface Window {
readonly attribute CryptoKeys cryptokeys;
};7.4.1 Attributes
cryptokeys of type CryptoKeys, readonly - The object that exposes the key discovery methods
7.5 Extension of WorkerGlobalScope interface
partial interface WorkerGlobalScope {
readonly attribute CryptoKeys cryptokeys;
};7.5.1 Attributes
cryptokeys of type CryptoKeys, readonly - The object that exposes the key discovery methods