Hardware Based Secure Services features

Status of This Document

This specification was published by the Hardware Based Secure Services. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

Working copy

Table of Contents

• 1. Introduction
• 2. Problem Statement
• 3. Use cases
• 4. Secure transaction and secure credential storage APIs
• 5. Implementation requirements
• 6. TODO
• 7. Dependencies
• A. References

1. Introduction

The open web platform runs on diverse devices such as tablets, PCs, smart phones, and cars' systems. Driven by an expectation from users and service providers, a majority of those devices are embedding some technology allowing to offer some secure services. One can think about secure chips such as embedded secure element, TPM, UICC, or proximity smart card, using BLE or NFC communication means. Another technology getting traction is the Trusted Execution environment. Both types of technology are offering some advantages in terms of secure execution and storage. Secure elements and TEEs can offer some services, known as Secure Services, to improve the integrity and confidentiality of data transactions.

This document is proposing some use cases where the web apps could benefit from secure services. In addition, in order to demonstrate the feasibility of such secure services, the Hardware Based Secure Services Community Group has identified two services, for which technical rationale and API will be detailed. In addition some protoypes, testing the reliablility of the architecture, will be developed. The elected secure services are (1) secure transaction confirmation and (2) secure credential storage.

1.1 Terminology

• Secure Service: any web site that manages sensitive operations and would benefit from/depend upon the use of an hardware based security solution to give the security proof of the user confirmation integrity and non repudiation
• Relying party: the Web application providing the Secure Service and requesting the hardware access
• Issuing authority: the issuing authority is in charge of issuing an associated key/identity pair to a known identity and to maintain its lifecycle. The end-user identification is out-of-scope of this document but is clearly mandatory to associate a key to a genuine identity. As an example, in the well known in X509 certificates scheme, the issuing authority is the certificate authority
• Origin: with reference to the Same Origin Policy, in this document an origin refers to an HTTP URL with scheme, host, port without path
• User Agent (UA): a user agent is software (a software agent) that is acting on behalf of a user (from Wikipedia)
• User Verification Method: This is the way that the Hardware Secure Device ensures that only a natural and genuine person with possession and knowledge is able to access the keys stored in the Secure Element. For example, this method could be knowledge of a PIN code or biometric verification
• Identity: to be verified by the issuing authority, the identity is cryptographically linked to the key demonstrating who has confirmed a transaction or signed a document
• Key: asymmetric cryptographic public/private key pair, sometimes linked to an identity
• Hardware Secure Device: addition of the Secure Credential Storage and the Trusted User Interface with a trusted path between them
• Secure Element: A secure element is a tamper proof device, providing a secure storage and execution environment for sensitive data and processing. It offers both physical and logical protection against attacks, ensuring integrity and confidentiality of its content.
• Trusted User Interface: User interface component outside the direct browser scope providing an additional level of trust in regards to the transaction confirmation message presented to the end-user to acquire its acknowledgment. It covers both the display of the information and the input of the user verification method.

2. Problem Statement

At this time Secure Element are not yet usable by web applications. For years, various form factors have been usable thanks to many native API and technologies (PKCS#11, Microsoft API like CSP / Minidriver, Java applet ...). Use cases are valid for native applications but browsers have not been working on integrating those technologies. The need to use secure services in all types of application (native, web app, hybrid) is becoming important, especially on the mobile devices. This document aims to define the next generation Javascript API for two specific requirements for hardware based key management and usage: Secure transaction confirmation and Secure credential storage. These two requirements have been identified by the Hardware Based Secure Services Community Group as being as key to enable a strong security and identity ecosystem.

The management of keys is associated with the problem of key usage. On the open web platform, the security principle that prevails everywhere is the Same Origin Policy. This strict policy may have some limitation in some specific cases, where several parties are involved in the delivery of a secure service.

Same Origin Policy: one main matter of interest of the hardware-based secure services community group members is how to protect key usage considering the special use case where the credentials are used outside their issuing origin. For example: Suppose that a domain foo.com issues a key. Because the key is not accessible by Javascript API from another domain, we have to design a secure system where the domain bar.com is allowed to use this key.

There is a need for multiple domain key usage, but that this work will be treated later or when the CG will be a WG.

In this document, we assume that:

• pre-existing keys and X509 certificates are under the full control of the end-user
• any API issued key MUST only be managed and used by its own origin

Position to FIDO and WebAuth standards: this document is focusing on providing web developers means to issue and use identity keys (whether they are X509 certificates or any other cryptographic model with underlying asymmetric cryptography). FIDO standards is related to device authentication: in the FIDO vision, it is up to the relying party to manage the link between the credential and the identity.

Position to WebCryptoAPI standards: this report includes to WebCryptoAPI so that web developers can rely upon the same API but with a different initialization (like Java Cryptographic Engine with hardware provider).

The user verification method is out of scope of this specification. But it should be clear whether a key is protected by:

• the terminal without any user interaction (passive)
• the user presence confirmation (presence)
• the underlying OS user verification method like an handle to the registered fingerprint template (os)
• a specific and private key bound with user verification method like a specific PIN or a specific fingerprint/iris template (active)

The Relying Party should take care that:

• with the passive option, there won't be any effective user confirmation - it's only about device authentication
• with the presence option there is no assurance that the right user is really behind the user-agent
• with the os option, there is options provided by the OS manufacturer to manage real world use cases - i.e. sensor not capturing the fingerprint switching to the PIN code

Only the active option will guarantee that the user with the right knowledge or biometric characteristic is behind the user-agent.

3. Use cases

Hardware based services are already used in a number of domains which are particularly vulnerable to security attacks. Those domains cover financial and telecommunication industry, government and corporate services. Hardware based technology is used in those domains in specific cases such as managing authentication of the user or of the device, capturing user consent, document signature... The following use cases describe different areas in which hardware based technology is being used today. One should read those use cases as attractive for web application scenario.

3.1 National electronic identity for accessing public services.

As of 2016, a large number of European countries have already deployed electronic identity systems and offer their citizens access to government services such as paying tax or managing pensions. Examples of countries and associated systems are:

• Estonia: eEstonia
• Belgium: eID with eService ecosystem
• Sweden: Tax Agency card and Telia eID
• Norway: ID-porten

All the deployed solutions are relying on middleware deployment on citizen devices.

Whatever the service accessed, the citizen will be expected to own a hardware token that will carry their electronic identity. This identity (most of the time a certificate for a key pair) will be used to authenticate the user and sign some transaction he or she will be performing on the government portal. The native environment of the citizen device, or of the public service office, is able to access to the hardware token, thanks to a transport layer (USB, ISO 7816 / 14443, Bluetooth Low Energy ...).

3.2 Financial transaction signature, with user consent

The remote access to financial account, together with the electronic fund transfer are now part of citizen habits in developed countries. Most of the banks do offer in their account package this remote management service. In some conditions, usually defined by the bank, some extra security is requested to the consumer to finalize transactions. This extra security aims at improving the usual login/password security barrier. Depending on the use case, it could be either a one time password sent by SMS, or a user operation to confirm his or her presence, or a digital signature of the transaction itself. That last step requires the user to use some credentials, distributed by the bank, usually stored in a secure container, such as a hardware based token (USB token or proximity token). The data signed by the user generally includes the amount and destination of the transaction, plus additional information as desired by the bank.

3.2.1 French ecosystem

In France, a list of trusted issuing certificate authorities is maintained by the Finance Ministry. The face-to-face verification of individual identity acting on behalf of a company is managed by the certificate authorities, as is the delivery of smartcards or USB tokens. This ecosystem is also used by the French corporate banks to manage many regulatory related tasks and also to enforce strong authentication but also digital signature, for example to confirm the file containing the widthdrawal of the salary for a company. Issuing authentication credential is not acceptable according to the existing risks they are facing in terms cyber attacks: combined social engineering, phishing, stolen Transaction Account Number for multiple attack vectors: 3DSecure online payment confirmation, withdrawal... Banks are looking to cover the transaction risk by using the right credentials for the risk, with the strongest level of authentication being used for the highest risk scenarios. Without the capability to rely upon Secure Elements in the browser, banks currently face a major issue in being able to replace the existing identity scheme delegation which provides a strong authentication and signature credential.

3.3 The expectation from secure services

Whatever is the envisaged use case, signing a tax payment, confirming a transaction payment, validating the signature of a document, the service needs to rely on a genuine signature and user control. Each service provider needs to have a certain flexibility in designing its security model. Nevertheless, there are some minimum common basic functions that one can find in most of the security operations. The Hardware Based secure Services Community Group identified two technical features that are used on a regular basis : the secure transaction confirmation, and the secure credential storage. It is expected that those secure services, when being implemented natively in user agents, will offer a certain level of resistance and a certain level of trustworthiness. In the following section, those features will be detailed in the form of APIs and their security merits.

4. Secure transaction and secure credential storage APIs

This section contains the API descriptions and the different rationale for the architecture and design choices. It covers both functionalities related to the storage and usage of credentials in a hardware based token, and the secure transaction confirmation. Those functions rely on the presence of a credential, referred to here as a key.

The life cycle of this key is usual : creation, usage and deletion. In the framework of this short life community group, we will take the following assumptions on the key lifecycle :

• the key has already been generated
• the service using the key is an authorized service - in the framework of the SOP, it is the same service that created the key. The Community Group is in parallel also working on the definition of a mechanism to allow an entity to use some keys generated by another entity, but this requires the definition of a new type of data, associated with a specific key, and this is for future deliverable. Note : all use cases are envisaged with a pre-existing key set.

4.1 Secure transaction interface

NOTE: This subpart of the API is relying upon pre-existing keys.

4.1.1 Secure transaction API

					
[NoInterfaceObject]
enum UVMMode { "passive", "presence", 
"os", "active" };

[Exposed=(Window,Worker)]
interface Crypto {
...
  readonly attribute HWCrypto hwCrypto;
...
};

[Exposed=(Window)]
interface HWCrypto {
	Promise<any> confirm(DOMString origin, 
			DOMString NRMessage, 
			UVMMode mode, 
			ArrayBuffer[] issuingAuthorities);
	Promise<any> deviceAuthentication(DOMString origin, 
			BufferSource challenge, 
			ArrayBuffer[] issuingAuthorities);
	Promise<any> sign(DOMString origin, 
			DOMString NRMessage, 
			BufferSource data, 
			UVMMode mode, 
			ArrayBuffer[] issuingAuthorities);
}
					
				

4.1.2 Secure transaction API details

The secure transaction confirmation aims to give the assurance to a remote entity that a transaction is confirmed by the user. Its value relies in the fact that the requested confirmation was sent to the user, was displayed to the user with no alteration and that the user confirmed exactly what was displayed. This is the 'What You See Is What You Confirm' principle.

• Transaction confirmation: This operation is defined to request from the browser and underlying security capabilities to ensure that the transaction context, also called non-repudiation message, has been presented to the end-user and provide non-repudiation
• Device authentication: This operation should be used when the relying party is trying to use a hardware key to authenticate the device without any user consent
• Digital signature: This operation is defined to allow binary data signature.

4.1.3 Data types

UVMMode

The type of user verification method mode prior to the key usage for the corresponding method. The recognized user verification modes values are "passive", "presence", "active" and "os". "passive" means that the no user interaction has been done, "presence" means that someone confirms the operation on the device, "active" means that the user has been actively authenticated and "os" means that the confirmation relies upon the OS either through PIN, fingerprint or any other end-user verification methods. The user experience of verification (including recovery procedures) is the same as provided natively by the OS itself, which may carry its own strength or weakness.

4.1.4 Methods and parameters

4.1.4.1 The confirm method

The confirm method returns a new Promise object that will display the origin and the NRMessage, sign the hash of the NRMessage using the a key issued by one of the issuingAuthorities and by verifying the user according to the UVMMode. It must act as follows:

1. Let mode be the mode parameter passed to the confirm method.

2. Let issuingAuthorities, origin and NRMessage be the result of cloning the data of the issuingAuthorities, origin and NRMessage parameters passed to the confirm method respectively.

3. If an error occurred, return a Promise rejected with the corresponding invalid parameter(s).

4. Let promise be a new Promise.

5. Return promise and asynchronously perform the remaining steps.

6. If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.

7. The trusted UI should request the selection of a key by the user. The list proposed by the browser should rely upon those available in the various secure elements or requests the user to add the secure element (connected or contactless) and update the list correspondingly. The list should be filtered according to the issuingAuthorities: this parameter should include the array of the public keys of the issuing authorities. If this values is empty, no filtering should be applied. This step can be bypassed if the user has registered a prefered key for this origin, but then the key should be presented with the NRMessage. In this case, the browser should ensure that the prefered key is still acceptable in regards to the current operation issuingAuthorities parameter. At this step, if the user cancels the operation or if no key match the requirements, then let throw a AbortError.

8. Let present to the end-user the origin and the non repudiation message (NRMessage) and the user interface to either confirm the presence or authenticate according to the UVMMode. At this step, if the user cancels the operation or if the user verification method fails too many times, then let throw a AbortError.

9. Let signature-nrmessage be the result of performing the signature operation with the hash of the NRMessage.

10. Resolve promise with signature-nrmessage and, if applicable, key the public part of key used to sign.

4.1.4.2 The deviceAuthentication method

The deviceAuthentication method returns a new Promise object that will sign the hash of the challenge using a key issued by one of the issuingAuthorities. It must act as follows:

1. Let issuingAuthorities and origin of the issuingAuthorities and origin parameters passed to the deviceAuthentication method respectively.

2. If an error occurred, return a Promise rejected with the corresponding invalid parameter(s).

3. Let promise be a new Promise.

4. Return promise and asynchronously perform the remaining steps.

5. If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.

6. Let signature be the result of performing the signature operation with the hash of the challenge. The signature should be performed with the first key that is issued by one of the issuingAuthorities. The requesting SP has to ensure that the corresponding key will not require a user verification method otherwise it will throw a AbortError.

7. Resolve promise with signature and, if applicable, key the public part of key used to sign.

4.1.4.3 The sign method

The sign method returns a new Promise object that will display the origin and the NRMessage, sign the hash of the NRMessage and the hash of the data using the a key issued by one of the issuingAuthorities and by verifying the user according to the UVMMode. It must act as follows:

1. Let mode be the mode parameter passed to the sign method.

2. Let issuingAuthorities, origin, data and NRMessage be the result of cloning the data of the issuingAuthorities, origin, data and NRMessage parameters passed to the sign method respectively.

3. If an error occurred, return a Promise rejected with the corresponding invalid parameter(s).

4. Let promise be a new Promise.

5. Return promise and asynchronously perform the remaining steps.

6. If the following steps or referenced procedures say to throw an error, reject promise with the returned error and then terminate the algorithm.

7. The trusted UI should request the selection of a key by the user. The list proposed by the browser should rely upon those available in the various secure elements or requests the user to add the secure element (connected or contactless) and update the list correspondingly. The list should be filtered according to the issuingAuthorities: this parameter should include the array of the public keys of the issuing authorities. If this values is empty, no filtering should be applied. This step can be bypassed if the user has registered a prefered key for this origin, but then the key should be presented with the NRMessage. In this case, the browser should ensure that the prefered key is still acceptable in regards to the current operation issuingAuthorities parameter. At this step, if the user cancels the operation or if no key match the requirements, then let throw a AbortError.

8. Let present to the end-user the origin and the NRMessage and the user interface to either confirm the presence or authenticate according to the UVMMode. At this step, if the user cancels the operation or if the user verification method fails too many times, then let throw a AbortError.

9. Let signature-nrmessage be the result of performing the signature operation with the hash of the NRMessage and signature-data be the result of performing the signature operation with the hash of the data.

10. Resolve promise with signature-nrmessage and, if applicable keythe public part of key used to sign.

4.1.5 Exceptions

The methods of the HWCrypto interface return errors by rejecting the returned promise with a predefined exception defined in ECMAScript [ECMA-262] or DOMException. The following predefined exceptions are used: TypeError. The following DOMException types from [DOM4] are used:

When this specification says to throw an error, the user agent must throw an error as described in [WebIDL]. When this occurs in a sub-algorithm, this results in termination of execution of the sub-algorithm and all ancestor algorithms until one is reached that explicitly describes procedures for catching exceptions.

4.1.6 Security considerations

This 4.1 section covers the various usages of keys. The use cases (transaction confirmation, signature, device authentication) are not highly sensitive in terms of transaction confidentiality, which means that standard SOP rules are considered sufficient without any need for end-to-end encryption (i.e. from SP to the Hardware Secure Device).
To avoid context swapping, it is mandatory that the non-repudiation message contains specific data for the requested transaction with the requesting party, the purpose of the transaction and the date of the operation.

Assumption: for many different reasons, complex data are not the right format to get the end-user consent and confirm her/his acknowledgment:

• Liability: The major reasons is that this type of API is targeting valuable transactions with liability. And for most regulations, liability relies upon the end-user capability to understand the message and confirm it. So only the simplest format should be considered: no color, no emphasis, no image.
• Technical: structured documents (XHTML, XML, RDF, PDF ...) cannot be presented in trusted UI
• Accessibility: no image should be used

So it should be:

• text only
• not too short: it should give enough context information to protect against social engineering and replay attacks
• not too long: it should be displayable on almost every end-user terminal and read by the end-user
• scoped: it should target a particular operation (type, amount, beneficiary ...) at a particular time
• localized (UTF-8)

What it should not be:

• full list of terms and conditions - but it can be the operation to confirm that the end-user agree with a particular version of the terms and conditions
• a generic operation request because it would not be scoped (i.e: "Do you confirm this signature operation ?" or "Do you want to confirm the authentication ?")

NOTE: a particular attention should be paid to UTF-8 characters support with the wide variety of similar characters. Therefore, both the context and the data should be signed at the same time with the same key. It is then up to the relying party to ensure that the data associated with the context are both signed and they match the initial request The user has accepted the context (and liability may rely only on that context in regards to this cryptographic operation) The data signature (i.e. PDF signature) is then a way to embed into the data the user consent.

It could occur that the binary data are altered before signature by a malware or javascript or any software attacking the user agent. in such scenario, the altered binary data would be successfully signed on the user agent side. It is up to the relying party to check that the binary data and the context received are signed with the same key. In addition, the relying party, as part of its security policy, will be able to reject any attempt to submit binary signed data if they are not provided with a valid signed context.

Within this signature operation, the mode for the user verification method MUST NOT be neither "passive" nor "presence".

4.2 Secure Credential Storage

This subpart describes a JavaScript API for discovering named, origin-specific pre-provisioned cryptographic keys stored into hardware secure device to be used 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, importing and unwrapping 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.

4.2.1 Secure Credential Storage API

This API relies on the existing WebCrypto API and provide some additionnal features to support key naming, as proposed in WebCrypto Key Discovery note, but also defines the notion of HardwareSecureDevice which represents any form of hardware cryptographic device acting as cryptographic provider, in a similar way of what JAVA defines with its framework Java Cryptography Architecture (JCA), to bring new capabilities to the SubtleCrypto interface and in particular the persistent and secure storage of keys.

4.2.1.1 Window interface

Window interface is enhanced to expose hardware secure device management service.

					
[NoInterfaceObject]
interface GlobalHardwareSecureDeviceManager {
  readonly  attribute  HardwareSecureDeviceManager  hsdm;
};

Window implements GlobalHardwareSecureDeviceManager;
WorkerGlobalScope implements GlobalHardwareSecureDeviceManager;
					
				

4.2.1.2 HardwareSecureDeviceManager interface

The HardwareSecureDeviceManager interface provides access to hardware secure devices and is the source of events notifying their presences. The notion of presence is important because a hardware secure device may not always be fixed in the same hardware environment as the user agent (e.g. an embedded secure element or a TEE); some hardware secure devices may be shared with several user agents (e.g. smart cards or NFC cards).

					
[Exposed=(Window,Worker)]
interface HardwareSecureDeviceManager : EventTarget {
    readonly  attribute  HardwareSecureDevice[]  hardwaresecuredevices;
              attribute  EventHandler?           onHardwareSecureDevicePresent;
              attribute  EventHandler?           onHardwareSecureDeviceRemoval;
};
					
				

The attribute hardwaresecuredevices represents the list of hardware secure devices present and acccessible by UA at the time the attribute is accessed. UA is in charge to add or remove element in that array depending of the evolution of the environment in term of presence and absence of hardware secure device. User MAY define two event listeners (onHardwareSecureDevicePresent and onHardwareSecureDeviceRemoval) which will be called by UA to notify the user of the ongoing changes of the environment in term of presence or absence of hardware secure device.

4.2.1.3 HardwareSecureDevice interface

The HardwareSecureDevice interface extends the SubtleCrypto interface providing a different implementation of one or more SubtleCrypto methods in order to let the hardware device handle the cryptographic operation internaly instead of the UA in software. It can be viewed as a cryptographic provider bringing cryptographic capabilities of a hardware device to the WebCrypto API in a transparent manner. UA MAY defines other classes extending the HardwareSecureDevice one representing different types of hardware secure device with specific implementation. One implementation COULD be using PKCS#11 as transport layer to communicate with a compatible hardware secure devices

					
[Exposed=(Window,Worker)]
interface HardwareSecureDevice : SubtleCrypto {
	readonly  attribute  DOMString     name;
	readonly  attribute  boolean       ispresent;
};
					
				

The attribute name is used to identify in a human readable way the hardware secure device. It will typically be used by the browser when requesting permission to the user to access a given hardware secure device. The attribute ispresent is used by UA to indicate if the given hardware secure device is currently accessible. This attribute will typically be checked by UA before trying to perform any cryptographic operation on the hardware secure device.

4.2.1.4 CryptoKey interface

The CryptoKey interface as defined in the WebCrypto Key Discovery note requires some modification in order to support hardware secure device. The CryptoKey interface and in particular the method getKeyByName is improved to add an optional parameter of hardwaresecuredevice type. If this parameter is provided, the look up for a key with the given name MUST occur only in the targeted hardware secure device. Prior to that, UA MUST validate the presence of the targeted hardware secure device first and then UA MUST call the same method than the callee one but on the provided hardware secure device object. The remaining executive flow remains unchanged as defined in WebCrypto API. In case of absence UA MUST throw an exception by using the reject promise. If the optional parameter is not provided, the search MUST occur only in software wherever the keys are usually stored by UA.

					
[NoInterfaceObject]
interface CryptoKeys {
    Promise getKeyByName (DOMString name, 
                          optional HardwareSecureDevice hsd);
};
					
				

4.2.1.5 SubtleCrypto interface

The SubtleCrypto interface as defined in the WebCrypto API requires some modification in order to support hardware secure device. All the methods of the SubtleCrypto interface are improved to add an optional parameter of hardwaresecuredevice type. If this parameter is provided, the cryptographic operation MUST occur in the targeted hardware secure device. Prior to that, UA MUST validate the presence of the targeted hardware secure device first and and then UA MUST call the same method than the callee one but on the provided hardware secure device object. The remaining executive flow remains unchanged as defined in WebCrypto API. In case of absence UA MUST throw an exception by using the reject promise. If the optional parameter is not provided, the cryptographic operation MUST occur only in software with the default UA implementation.

					
[Exposed=(Window,Worker)]
interface SubtleCrypto {
				   
  Promise encrypt(AlgorithmIdentifier algorithm,
                       CryptoKey key,
                       BufferSource data
                       optional HardwareSecureDevice hsd);

  Promise decrypt(AlgorithmIdentifier algorithm,
                       CryptoKey key,
                       BufferSource data
                       optional HardwareSecureDevice hsd);
					   
  Promise sign(AlgorithmIdentifier algorithm,
                    CryptoKey key,
                    BufferSource data
                    optional HardwareSecureDevice hsd);
					   
  Promise verify(AlgorithmIdentifier algorithm,
                      CryptoKey key,
                      BufferSource signature,
                      BufferSource data
                      optional HardwareSecureDevice hsd);
					  
  Promise digest(AlgorithmIdentifier algorithm,
                      BufferSource data
                      optional HardwareSecureDevice hsd);

  Promise generateKey(AlgorithmIdentifier algorithm,
                          boolean extractable,
                          sequence keyUsages
                          optional HardwareSecureDevice hsd);
						  
  Promise deriveKey(AlgorithmIdentifier algorithm,
                         CryptoKey baseKey,
                         AlgorithmIdentifier derivedKeyType,
                         boolean extractable,
                         sequence keyUsages
                         optional HardwareSecureDevice hsd);
						 
  Promise deriveBits(AlgorithmIdentifier algorithm,
                          CryptoKey baseKey,
                          unsigned long length
                          optional HardwareSecureDevice hsd);
  
  Promise importKey(KeyFormat format,
                         (BufferSource or JsonWebKey) keyData,
                         AlgorithmIdentifier algorithm,
                         boolean extractable,
                         sequence keyUsages
                         optional HardwareSecureDevice hsd);
						 
  Promise exportKey(KeyFormat format, 
                         CryptoKey key
                         optional HardwareSecureDevice hsd);

  Promise wrapKey(KeyFormat format,
                       CryptoKey key,
                       CryptoKey wrappingKey,
                       AlgorithmIdentifier wrapAlgorithm
                       optional HardwareSecureDevice hsd);

  Promise unwrapKey(KeyFormat format,
                         BufferSource wrappedKey,
                         CryptoKey unwrappingKey,
                         AlgorithmIdentifier unwrapAlgorithm,
                         AlgorithmIdentifier unwrappedKeyAlgorithm,
                         boolean extractable,
                         sequence keyUsages
                         optional HardwareSecureDevice hsd);
};
					
				

4.2.2 Permission

UA MUST not start to exchange with an Hardware Secure Device without the express permission of the user. UA MUST acquire permission through a user interface, unless they have prearranged trust relationships with users. The user interface MUST include the host component of the document's URI and a reminder of the Hardware Secure Device name targetted. Those permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond the time when the browsing context is navigated to another URL) must be revocable and UA MUST respect revoked permissions.

Some Hardware Secure Device MAY require to be unlocked, using a secure mechanism, before being accessed. In that case, UA MUST provide a way to unlock through a user interface with input capability (text value, fingerprint...). The user interface MUST include the host component of the document's URI and a reminder of the Hardware Secure Device name targeted. The data used to unlock the Hardware Secure Device MUST be transmitted in a secure way and UA MUST NOT store those data.

5. Implementation requirements

These requirements are provided to split the responsibilities of each vendor / software providers for the different implementation environments

5.1 Attestations

Both the Secure Element and the TrustedUI should be securely identified by attestation. These attestations should be implemented as exposed in the the FIDO 2.0 Attestations.

5.2 PC-like environments

It is typically the environment where secure elements - either smartcards with readers or usb tokens - are used with middleware through PKCS#11 or Microsoft Minidriver. In this architecture, the trusted UI is:

• Either the middleware when the signature is requested through PKCS#11 library
• Or the Microsoft Windows operating system which manage the secure element user interface for CSP/CNG API

In this implementation, it means that the origin of the request and the non repudiation message should be displayed by the middleware or the Windows OS in a trusted way.

To limit the capability of a website to request the usage of the cryptographic API, browser implementers SHOULD support a mechanism of white / black lists of authorized domains (like camera access), so that an end-user could reject any request from an unknown origin.

NOTE: transaction confirmation could be supported by providing the merge of the origin and the non repudiation message as the data to sign for existing API. It MUST be displayed to the end-user with the user verification method input. But signature operation will require a interface definition new method for both PKCS#11 and CSP/CNG

5.3 Mobile environments

In mobile environments, Secure Elements are either:

• device binded like embedded Secure Element
• roaming like SIM or external NFC/BLE factors

But there is no capability to add middleware. It is up the OS manufacturer to provide support for the Secure Elements and provide an API for third party applications including browsers.

5.3.1 Generic mobile environments

In this situation, the trusted user interface should be part of the Operating System, interacting with the Secure Element

5.3.2 Mobile environments with Trusted Execution Environment

In this situation, the browser is a trusted app and the trusted UI is relying upon the existing TEE functions (See [GP_TEE])

5.4 About implementations considerations

Implementation into a mobile phone will require:

• browser modifications to interact with TEE
• a trusted application interacting with the Secure Element

6. TODO

The following topics need to be managed later:

• Attestation retrieval by the issuing authority to evaluate the environment (TrustedUI & SE)
• Post issuance of the key: a specific operation should be added to the Secure Credential Storage API for two reasons: filtering the certified public keys to match the one accepted by the service provider and adding the certified public key during transaction confirmation, device authentication or signature
• Need to confirm is this API being operated only in the context of Priviledged Context or not

A. References

A.1 Normative references

DOM4

W3C DOM4, A. van Kesteren, A. Gregor, Ms2ger, Alex Russell, Robin Berjon. W3C.

Editorial note

A reference will be added to ECMAScript 6 once "Promises" are stable.

ECMA262

ECMAScript 5th Edition, A. Wirfs-Brock, P. Lakshman et al.

WebCryptoAPI

W3C WebCryptoAPI, Ryan Sleevi, Mark Watson. W3C.

WebCrypto Key Discovery

W3C WebCrypto Key Discovery Note, Mark Watson. W3C.

A.2 Informative references

CryptoAPI

Cryptography Reference, Microsoft Corporation.

OpenTEE

OpenTEE project.

PKCS#11

PKCS #11: CRYPTOGRAPHIC TOKEN INTERFACE STANDARD, RSA Laboratories/EMC.

PC/SC

PCSC, standard for integrating smart cards and smart card readers, PC/SC Workgroup.

Replacement for <keygen>

Keygen and Client Certificates, W3C TAG.

Trusted Execution Environment

Trusted Execution Environment, Global Platform.

FIDO 2.0 Attestations

FIDO 2.0: Key Attestation Format, W3C WebAuth.

JCA Reference Guide

Java Cryptography Architecture (JCA) Reference Guide, Oracle.