140 lines
4.6 KiB
Plaintext
140 lines
4.6 KiB
Plaintext
<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>
|
|
|
|
|
|
# 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>
|
|
|
|
# Attesters # {#attester}
|
|
|
|
The term <dfn for="attester">attester</dfn> refers to a third party capable of returning an [=Integrity verdict=]. A <dfn for="Integrity verdict">Integrity verdict</dfn> refers
|
|
to a response that confirms if the [=attester=] trusts the [=web environment=] the [=user agent=] is
|
|
executing in.
|
|
|
|
The [=user agent=] connects to the [=attester=] through an {{AttesterConnection}}.
|
|
|
|
The [=user agent=] SHOULD use separate {{AttesterConnection}}s if the {{AttesterConnection}}
|
|
stores state in the [=Integrity verdict=] that can be used for cross site tracking.
|
|
|
|
## Token Format ## {#attester-tokens}
|
|
|
|
<i>Todo</i>
|
|
|
|
## Browser Acceptance Requirements ## {#attester-browser-requirements}
|
|
|
|
<i>Todo</i>
|
|
|
|
## {{AttesterConnection}} ## {#attester-connection}
|
|
|
|
<xmp class="idl">
|
|
[Exposed=Window]
|
|
interface AttesterConnection {
|
|
ArrayBuffer getAttestation(DOMString contentBinding);
|
|
};
|
|
</xmp>
|
|
|
|
: getAttestation
|
|
:: Returns a COSE signed CBOR object as an ArrayBuffer from the [=attester=] that contains the [=Integrity verdict=].
|
|
|
|
# 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 <dfn for="attesterConnection">attesterConnection</dfn>, which is
|
|
an {{AttesterConnection}} 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 |environmentIntegrity| be a new {{EnvironmentIntegrity}}
|
|
1. Set |environmentIntegrity|.{{EnvironmentIntegrity/attestationToken}} to [=attesterConnection=].<a method for=AttesterConnection>getAttestation(|contentBinding|)</a>. If this fails then:
|
|
1. [=Reject=] |promise| with a <i>TODO</i> [=Exception=]
|
|
1. Abort these steps
|
|
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 signed CBOR 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}
|
|
|
|
<i>Todo</i>
|
|
|
|
## Privacy considerations ## {#privacy}
|
|
|
|
<i>Todo</i>
|
|
|