inhji
/
Web-Environment-Integrity
1
0
Fork 0
Code Issues 69 Pull Requests 11 Packages Projects Releases Wiki Activity

Update alternative spec to be considered working draft 

Making it clear from the top level README.md that this represents
the current working prototype for Chromium in particular.

The goal is to help make it clear that we've thought about the details
of how this could work to any community group that we
present this to for adoption.

Also updated a few minor points in the process.
This commit is contained in:
Rupert Ben Wiser 2023-06-16 09:30:43 +00:00 committed by Ben Wiser
parent f0628638e4
commit 5d400f8d1e
5 changed files with 1178 additions and 3272 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
README.md Normal file
View File

@ -0,0 +1,12 @@
# Web Environment Integrity API
This repository details the proposal to add a new API for determining the integrity
of web environments:
```js
const attestation = await navigator.getEnvironmentIntegrity("...");
```
The [explainer](./explainer.md) goes gives a high level overview of the proposal.
The [spec](./docs/spec) currently describes how this is being prototyped in Chromium.

137
docs/alternatives/navigator_extension_alternative.bs
View File

@ -1,137 +0,0 @@
<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 an 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">
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">
interface EnvironmentIntegrity {
readonly attribute ArrayBuffer attestationToken;
DOMString encode();
[Default] 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 JSON representation of the attestation token. Useful for local debugging.
# Security and privacy considerations # {#security-and-privacy}
## Security considerations ## {#security}
<i>Todo</i>
## Privacy considerations ## {#privacy}
<i>Todo</i>

2945
docs/alternatives/navigator_extension_alternative.html
View File

File diff suppressed because it is too large Load Diff

70
docs/spec/index.bs
View File

@ -45,12 +45,21 @@ Markup Shorthands: markdown yes, css no
</div>
# Web Environment Integrity API # {#api}
# Key terms # {#key-terms}
<i>Todo</i>
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>
@ -59,6 +68,63 @@ Markup Shorthands: markdown yes, css no
<i>Todo</i>
## {{AttesterConnection}} ## {#attester-connection}
<xmp class="idl">
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">
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}

1286
docs/spec/index.html
View File

File diff suppressed because it is too large Load Diff