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
</pre>

# Introduction # {#introduction}

<i>Todo</i>

## Motivations ## {#motivations}

<i>Todo</i>

## 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>

# 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. Set |attesterVerdict| to a new [=attester verdict=] from the |attesterConnection| using the |contentBinding|. If this fails then:
            1. [=Reject=] |promise| with a <i>TODO</i> [=Exception=]
            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>