ACTION-114: Make proposal to amend api

Mark,

This is my suggestion as to how to amend the WebCrypto Key Discovery document to support the home automation use case; as requested in ACTION-114.

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 can be identified by their name or their id. The name can either be provisioned by the origin with the key or derived by the UA from information stored within a certificate associated with the key. The id corresponds to a unique identifier for that specific key amongst all pre-provisioned keys from the same origin.

1. Introduction

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 or ids 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.

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.

2.2 Certificate based key provisioning

Web applications may wish to use keys associated with certificates. These certificate keys may have been provisioned through means outside the scope of the WebCrypto API. This may include keys that are provisioned through platform-specific native APIs. These type of keys could be stored in secure elements such as trusted platform modules (TPMs), otherwise installed via device-specific provisioning protocols.

Such certificate keys may, for example, be used to assist in identifying a specific 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 certificate keys via a function to return either all or a subset based on either the key name or id. The discovered key can then be used 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.

Note: If a User Agents (UA) needs to generate the association between a certificate and the certificate key it does so by extracting the subject CN value and the extended key usage (id-ce 37) into the NamedKey name field and the certificate issuer CN and certificate serial number into the NamedKey id field.


7.3 CryptoKeys interface

WebIDL

[NoInterfaceObject]
interface CryptoKeys {
    Promise getKeys();
    Promise getKeyByName (DOMString name);
    Promise getKeyById (DOMString id);
};

7.3.1 Methods

getKeys

       When invoked, this method must perform the following steps:

       1. Let promise be a new Promise and resolver its associated resolver
       2. Return promise and continue executing the following steps asynchronously:
           1. Search for keys.

              If one or more keys are found
                  1. Let the result be an object of type NamedKey[] containing the keys
                  2. 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
N/A

Return type: Promise

Note: There should be no change to getKeyByName...just copied here for completeness
getKeyByName
       When invoked, this method must perform the following steps:

       1. Let promise be a new Promise and resolver its associated resolver
       2. Return promise and continue executing the following steps asynchronously:
           1. 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
                  1. Let the result be an object of type NamedKey representing the key
                  2. 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       ✘               ✘

Return type: Promise

getKeyById
       When invoked, this method must perform the following steps:

       1. Let promise be a new Promise and resolver its associated resolver
       2. Return promise and continue executing the following steps asynchronously:
           1. Search for a key matching the id specifier provided in id. A id specifier matches the id of a key if they are identical when expressed as a string of unicode characters.

              If a key is found
                  1. Let the result be an object of type NamedKey representing the key
                  2. 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
id                      DOMString       ✘               ✘

Return type: Promise



Regards,
Michael

________________________________
This message and any attachments are intended solely for the addressees and may contain confidential information. Any unauthorized use or disclosure, either whole or partial, is prohibited.
E-mails are susceptible to alteration. Our company shall not be liable for the message if altered, changed or falsified. If you are not the intended recipient of this message, please delete it and notify the sender.
Although all reasonable efforts have been made to keep this transmission free from viruses, the sender will not be liable for damages caused by a transmitted virus