Web Environment Integrity

A Collection of Interesting Ideas,

Issue Tracking:
GitHub
Editor:
(Google)

CC0 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 17 July 2023, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.

Abstract

An API used to integrity check the environment a web page runs on. This check is performed by trusted attesters.

1. Introduction

This section is non-normative.

The Web Environment Integrity API allows user agents to request attester verdicts from an attester that can be used to verify the integrity of the web environment. These verdicts are piped to a relying party where they are validated for authenticity.

Web Environment Integrity is best suited for detecting deceptive web environments.

1.1. Motivations

This section is non-normative.

Users often depend on websites being able to establish the trustworthiness of the web environment. When users are playing online games for instance, they are trusting that other users are not cheating. Or when they are browsing social media websites, they are trusting that other users are not faking engagement to make posts popular.

Websites currently need to establish this trust relationship without any support from user agents. This can result in websites collecting signals that can be used to fingerprint users.

Web Environment Integrity is being proposed as a privacy preserving API to provide low entropy trust signals for the web environment. This API relies on user agents having access to an attester.

1.2. Examples

Requesting environment integrity attestation. 
// getEnvironmentIntegrity expects a "content binding" of the request you are
// about to make. The content binding protects against this information being
// used for a different request.
// The contentBinding will be concatenated with top-level domain name and hashed
// before it is sent to the attester.

const contentBinding = "/someRequestPath?requestID=xxxx" +
    "Any other data needed for a request-specific contentBinding...";

const attestation = await navigator.getEnvironmentIntegrity(contentBinding);

console.log(attestation.encode());
"base-64 encoding of the attestation payload and signature approx 500 bytes; see below for details"

// More on attestation validation below
const response = await fetch(`/someRequest?requestID=xxxx&attested=${attestation.encode()}`);
// Do something with this ...

2. Key terms

The web environment is defined as TODO

The content binding is defined as TODO

Entropy in this specification refers to Shannon entropy. This is the amount information conveyed.

3. Attesters

The relying party is defined as any party that relies on the Web Environment Integrity API outside of the user agent.

4. Infrastructure

4.1. Attesters

The term attester refers to a third party capable of returning an attester verdict.

User agents MUST have an attester connection to an attester in order to use Web Environment Integrity.

The user agent SHOULD use separate attester connections if the attester connection stores state in the attester verdict that can be used for cross site tracking.

4.1.1. Attester Connection

The attester connection is an abstract concept representing the channel through which the user agent can communicate to an attester. The user agent uses the attester connection to request new attester verdicts.

The attester connection MUST use a content binding to create a new attester verdict.

4.1.2. Attester Verdict

The attester verdict is an abstract concept that refers to the response from attester. It reports how much an attester trusts the web environment the user agent is executing in.

The attester verdict consists of:

4.2. Browser Acceptance Criteria

Todo

5. Web Environment Integrity API

5.1. Extensions to Navigator

[Exposed=Window]
partial interface Navigator {
  [SecureContext] Promise<EnvironmentIntegrity> getEnvironmentIntegrity(DOMString contentBinding);
};
The user agent has the global attesterConnection, which is an Attester Connection with the attester.

The getEnvironmentIntegrity(contentBinding) method, when invoked, runs these steps:

  1. Let promise be a new promise

  2. Run the following steps in parallel:

    1. Let hashedCB be the digest [SHA-256](contentBinding + ";" + origin)

    2. Set attesterVerdict to a new attester verdict from the attesterConnection using the hashedCB. If this fails then:

      1. Reject promise with a "UnknownError" DOMException

      2. Abort these steps

    3. Let environmentIntegrity be a new EnvironmentIntegrity with:

    4. Resolve promise with environmentIntegrity

  3. Return promise

5.2. EnvironmentIntegrity

[Exposed=Window]
interface EnvironmentIntegrity {
  readonly attribute ArrayBuffer attestationToken;
  DOMString encode();
  object toJSON();
};
attestationToken

The attestation token is a COSE [RFC9053] signed CBOR [RFC8949] object as an ArrayBuffer from the attester.

encode()

The encode method will return a Base64 string representation of the attestation token.

toJSON()

The toJSON method returns a human readable JSON representation of the attestation token. It will first decode the CBOR object. Useful for local debugging.

6. Security and privacy considerations

6.1. Security considerations

6.1.1. Secure context only

Web environment integrity MUST only be enabled in a secure context. This is to ensure that the website is not spoofed.

Todo

6.2. Privacy considerations

Todo

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Informative References

[RFC8949]
C. Bormann; P. Hoffman. Concise Binary Object Representation (CBOR). December 2020. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8949
[RFC9053]
J. Schaad. CBOR Object Signing and Encryption (COSE): Initial Algorithms. August 2022. Informational. URL: https://www.rfc-editor.org/rfc/rfc9053
[SHA-256]
National Institute of Standards and Technology. Secure Hash Standard (SHS) (FIPS PUB 180-4). August 2015. URL: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf

IDL Index

[Exposed=Window]
partial interface Navigator {
  [SecureContext] Promise<EnvironmentIntegrity> getEnvironmentIntegrity(DOMString contentBinding);
};

[Exposed=Window]
interface EnvironmentIntegrity {
  readonly attribute ArrayBuffer attestationToken;
  DOMString encode();
  object toJSON();
};