Skip to content
This repository has been archived by the owner on Aug 1, 2023. It is now read-only.

Commit

Permalink
Add infrastructure section and clean up the attester connection
Browse files Browse the repository at this point in the history
The attester connection was currently being represented with an
IDL but other specs don't seem to do this.

Using more general language to indicate how we should retrieve the
verdict from the attester while still being clear about what we
currently expect from it.

Also cleaned up a few IDL warnings such as the user agent being
ambiguous and missing the rfc references for CBOR and COSE.
  • Loading branch information
Rupert Ben Wiser authored and RupertBenWiser committed Jun 21, 2023
1 parent 25aaa65 commit e66b7ed
Showing 1 changed file with 38 additions and 25 deletions.
63 changes: 38 additions & 25 deletions docs/spec.bs
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ 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}

Expand Down Expand Up @@ -49,36 +52,45 @@ Markup Shorthands: markdown yes, css no

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

# Attesters # {#attester}
The <dfn for="content binding">content binding</dfn> is defined as <i>TODO</i>

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.
# Infrastructure # {#infrastructure}

The [=user agent=] connects to the [=attester=] through an {{AttesterConnection}}.
## Attesters ## {#infrastructure-attester}

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.
The term <dfn for="attester">attester</dfn> refers to a third party capable of returning an
[=attester verdict=].

## Token Format ## {#attester-tokens}
[=User agents=] MUST have an [=attester connection=] to an [=attester=] in order to use Web
Environment Integrity.

<i>Todo</i>
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.

## Browser Acceptance Requirements ## {#attester-browser-requirements}
### [=Attester Connection=] ### {#attester-connection}

<i>Todo</i>
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=].

## {{AttesterConnection}} ## {#attester-connection}
The [=attester connection=] MUST use a [=content binding=] to create a new [=attester verdict=].

<xmp class="idl">
[Exposed=Window]
interface AttesterConnection {
ArrayBuffer getAttestation(DOMString contentBinding);
};
</xmp>
### [=Attester Verdict=] ### {#attester-verdict}

: getAttestation
:: Returns a COSE signed CBOR object as an ArrayBuffer from the [=attester=] that contains the [=Integrity 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}

Expand All @@ -94,17 +106,18 @@ stores state in the [=Integrity verdict=] that can be used for cross site tracki
### {{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 [=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 |environmentIntegrity| be a new {{EnvironmentIntegrity}}
1. Set |environmentIntegrity|.{{EnvironmentIntegrity/attestationToken}} to [=attesterConnection=].<a method for=AttesterConnection>getAttestation(|contentBinding|)</a>. If this fails then:
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>
Expand All @@ -121,7 +134,7 @@ stores state in the [=Integrity verdict=] that can be used for cross site tracki
</xmp>

: attestationToken
:: The attestation token is a COSE signed CBOR object as an ArrayBuffer from the attester.
:: 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()
Expand Down

0 comments on commit e66b7ed

Please sign in to comment.