Web-Environment-Integrity/docs/spec.bs

<pre class='metadata'>
Title: Web Environment Integrity
Shortname: web-environment-integrity
Level: 1
Status: DREAM
Editor: Ben Wiser, Google, bewise@chromium.org
Abstract: An API used to integrity check the environment a web page runs on. This check is performed
Abstract: by trusted attesters.
Markup Shorthands: markdown yes, css no
</pre>

<pre class=link-defaults>
spec:infra; type:dfn; text:user agent
spec:url; type:dfn; text:origin
</pre>

<pre class=biblio>
{
  "SHA-256": {
    "href":"https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf",
    "title":"Secure Hash Standard (SHS) (FIPS PUB 180-4)",
    "authors": ["National Institute of Standards and Technology"],
    "publisher":"NIST",
    "id":"FIPS 180-4",
    "date": "August 2015"
  }
}
</pre>

# Introduction # {#introduction}

<i>This section is non-normative.</i>

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=].

## Motivations ## {#motivations}

<i>This section is non-normative.</i>

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.

<dfn for="Web Environment Integrity">Web Environment Integrity</dfn> 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=].

## Examples ## {#examples}

<div class="example" id="client-integrity-request">
  Requesting environment integrity attestation.

  <pre class="lang-js">
    // 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 ...
  </pre>

</div>

# Key terms # {#key-terms}

The <dfn for="web environment">web environment</dfn> is defined as <i>TODO</i>

The <dfn for="content binding">content binding</dfn> is defined as <i>TODO</i>

<dfn for="entropy">Entropy</dfn> in this specification refers to Shannon entropy. This is the amount
information conveyed.

# Attesters # {#attester}

The <dfn for="relying party">relying party</dfn> is defined as any party that relies on the Web Environment Integrity API
outside of the [=user agent=].

# Infrastructure # {#infrastructure}

## Attesters ## {#infrastructure-attester}

The term <dfn for="attester">attester</dfn> 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.

### [=Attester Connection=] ### {#attester-connection}

The <dfn for="Attester Connection">attester connection</dfn> 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=].

### [=Attester Verdict=] ### {#attester-verdict}

The <dfn for="attester verdict">attester verdict</dfn> 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:

<div dfn-for="attester verdict">
* A <dfn>raw response</dfn> (a COSE [[RFC9053]] signed CBOR [[RFC8949]] stored in an {{ArrayBuffer}})

</div>

## Browser Acceptance Criteria ## {#infrastructure-browser-acceptance-criteria}

<i>Todo</i>

# Web Environment Integrity API # {#api}

## Extensions to {{Navigator}} ## {#extensions-to-navigator}

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

### {{Navigator/getEnvironmentIntegrity()}} ### {#navigator-getenvironmentintegrity}

<div algorithm="navigator-getenvironmentintegrity-alg">
    The [=user agent=] has the global |attesterConnection|, which is
    an [=Attester Connection=] with the [=attester=].

    The <dfn method for="Navigator"><code>getEnvironmentIntegrity(|contentBinding|)</code></dfn> method, when invoked, runs these steps:

    1. Let |promise| be [=a new promise=]
    1. Run the following steps [=in parallel=]:
        1. Let |hashedCB| be the digest [[SHA-256]](|contentBinding| + ";" + [=origin=])
        1. Set |attesterVerdict| to a new [=attester verdict=] from the |attesterConnection| using the |hashedCB|. If this fails then:
            1. [=Reject=] |promise| with a "{{UnknownError}}" {{DOMException}}
            1. Abort these steps
        1. Let |environmentIntegrity| be a new {{EnvironmentIntegrity}} with:
            - {{EnvironmentIntegrity/attestationToken}} set to the [=attester verdict/raw response=] in the |attesterVerdict|
        1. [=Resolve=] |promise| with |environmentIntegrity|
    1. Return |promise|
</div>

## {{EnvironmentIntegrity}} ## {#environment-integrity}

<xmp class="idl">
  [Exposed=Window]
  interface EnvironmentIntegrity {
    readonly attribute ArrayBuffer attestationToken;
    DOMString encode();
    object toJSON();
  };
</xmp>

: 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.

# Security and privacy considerations # {#security-and-privacy}

## Security considerations ## {#security}

### Secure context only ### {#security-secure-context}

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

<i>Todo</i>

## Privacy considerations ## {#privacy}

<i>Todo</i>