From d275a98cfd9d4735e4e84b5a4de7ae25fe332425 Mon Sep 17 00:00:00 2001 From: Rupert Ben Wiser Date: Tue, 9 May 2023 12:51:41 +0000 Subject: [PATCH] Add empty spec bikeshed Adding this so that we can begin to iterate on this spec with the web community as more design decisions are agreed upon. --- docs/spec/index.bs | 71 ++ docs/spec/index.html | 2266 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 2337 insertions(+) create mode 100644 docs/spec/index.bs create mode 100644 docs/spec/index.html diff --git a/docs/spec/index.bs b/docs/spec/index.bs new file mode 100644 index 0000000000..ebf3798a2d --- /dev/null +++ b/docs/spec/index.bs @@ -0,0 +1,71 @@ +
+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
+
+ + +# Introduction # {#introduction} + +Todo + +## Motivations ## {#motivations} + +Todo + +## Examples ## {#examples} + +
+ Requesting environment integrity attestation. + + 
+    // 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 ...
+
+ +
+ +# Web Environment Integrity API # {#api} + +Todo + +# Attesters # {#attester} + +## Token Format ## {#attester-tokens} + +Todo + +## Browser Acceptance Requirements ## {#attester-browser-requirements} + +Todo + +# Security and privacy considerations # {#security-and-privacy} + +## Security considerations ## {#security} + +Todo + +## Privacy considerations ## {#privacy} + +Todo + diff --git a/docs/spec/index.html b/docs/spec/index.html new file mode 100644 index 0000000000..8fedddbe3e --- /dev/null +++ b/docs/spec/index.html @@ -0,0 +1,2266 @@ + + + + Web Environment Integrity + + + + + + + + + + + + + +
+

+

Web Environment Integrity

+

A Collection of Interesting Ideas,

+
+
+
Issue Tracking: +
GitHub +
Editor: +
(Google) +
+
+
+

CC0 To the extent possible under law, the editors have waived all copyright +and related or neighboring rights to this work. +In addition, as of 9 May 2023, +the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, +which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0. +Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.

+
+
+
+

Abstract

+

An API used to integrity check the environment a web page runs on. This check is performed + +by trusted attesters.

+
+
+ +
+

1. Introduction

+

Todo

+

1.1. Motivations

+

Todo

+

1.2. Examples

+
+ Requesting environment integrity attestation. +
// 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 ...
+
+
+

2. Web Environment Integrity API

+

Todo

+

3. Attesters

+

3.1. Token Format

+

Todo

+

3.2. Browser Acceptance Requirements

+

Todo

+

4. Security and privacy considerations

+

4.1. Security considerations

+

Todo

+

4.2. Privacy considerations

+

Todo

+
+
+

Conformance

+

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. + The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” + in the normative parts of this document + are to be interpreted as described in RFC 2119. + However, for readability, + these words do not appear in all uppercase letters in this specification.

+

All of the text of this specification is normative + except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

+

Examples in this specification are introduced with the words “for example” + or are set apart from the normative text with class="example", like this:

+
This is an example of an informative example.
+

Informative notes begin with the word “Note” + and are set apart from the normative text with class="note", like this:

+

Note, this is an informative note.

+
+ +

References

+

Normative References

+
+
[RFC2119] +
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119 +
\ No newline at end of file